@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

// 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

// 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:

// 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:

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

Fetching example

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

<script src="https://unpkg.com/@planningcenter/url"></script>

<script>
  const { pcoUrl, pcoApiUrl } = PLANNINGCENTER.url

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

Webpacker on Rails

yarn add @planningcenter/url

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:

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.

Examples

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.

const envURL = planningcenterurl(window.railsEnv);

envURL("api");