@planningcenter/url

A dumb url origin generator in JS.

Builds environment-considered url origins in JS-land, for Planning Center apps and APIs.

pcoUrl Examples

``js
// window.location.origin === "https://people.planningcenteronline.com"
import { pcoUrl } from "@planningcenter/url"

pcoUrl("services")
// => "https://services.planningcenteronline.com"

pcoUrl("api", { env: "development" });
// => "http://api.pco.test"

pcoUrl("accounts", { env: "staging" });
// => "https://accounts-staging.planningcenteronline.com"

pcoUrl("api", { env: "development" });
// => "http://api.pco.test"

pcoUrl("people", { env: "staging" });
// => "https://accounts.planningcenteronline.com"
`

pcoApiUrl Examples

`js
// window.location.origin === "https://people.planningcenteronline.com"
import { pcoApiUrl } from "@planningcenter/url"

pcoApiUrl("services")
// => "https://people.planningcenteronline.com/~api/services/v2"

pcoApiUrl("services", { env: "staging" })
// => "https://people-staging.planningcenteronline.com/~api/services/v2"

pcoApiUrl("services", { squiggly: false })
// => "https://api.planningcenteronline.com/services/v2"

pcoApiUrl("services", { squiggly: false, env: "staging" })
// => "https://api-staging.planningcenteronline.com/services/v2"
`

In Planning Center Apps

Generally, the environment can be inferred from within Planning Center apps:

`js
// window.location.origin === "https://people.planningcenteronline.com"

pcoUrl("api") // https://api.planningcenteronline.com
pcoApiUrl("services") // https://people.planningcenteronline.com/~api/services/v2
`

However, most Planning Center apps also expose the Rails env as the JS global railsEnv. Use it like so:

`js
pcoUrl("api", { env: railsEnv })
pcoApiUrl("services", { env: railsEnv })
`

Fetching example

`js
fetch(${pcoApiUrl("people")}/me, {
credentials: "include"
})
.then(res => res.json())
.then(json => json.data)
.then(({ id, attributes }) =>
this.setState({
currentUser: {
id,
...attributes
}
})
)
.catch(err => console.log(err));
`

Installation

Script tag on Rails

`html



`

Webpacker on Rails

`bash
yarn add @planningcenter/url
`

`js
import { pcoUrl, pcoApiUrl } from "@planningcenter/url";

pcoUrl("people"); // https://people.planningcenteronline.com
pcoApiUrl("people"); // https://{app}.planningcenteronline.com/~api/people/v2
`

inferEnv

The inferEnv pcoUrl and pcoApiUrl use is exported, should you need it.

Building and Testing Locally

You can use Devbox to test this project locally:

`sh
devbox run setup # installs JavaScript dependencies
devbox run build # builds the dist folder
devbox run test # runs the jest tests
`

Legacy

In @planningcenter/url versions <= 2.7.2, the default export was a function that took the env as an argument and returned a curried function for generating urls. That's still available, but its use is discouraged.

$3

`js
import planningcenterurl from "@planningcenter/url";

planningcenterurl("development")("api");
// => "http://api.pco.test"

planningcenterurl("staging")("people");
// => "https://accounts.planningcenteronline.com"

planningcenterurl("production")("accounts");
// => "https://people-staging.planningcenteronline.com"
`

Arguments are curried. You can make a generic env-considered function.

`js
const envURL = planningcenterurl(window.railsEnv);

envURL("api");
``