@planningcenter/api-client

@planningcenter/api-client

A Planning Center API client that will make you smile

Setup

Install the package:
yarn add @planningcenter/api-client

transformResponse

transformResponse takes an JSON API spec-adhering response and returns a lovely, transformed object or collection.

For example:

transformResponse({
  "data": {
    "type": "Person",
    "id": "123",
    "attributes": {
      "first_name": "Marvin",
      "last_name": "Gaye"
    },
    "relationships": {
      "top_song": {
        "data": {
          "type": "Song",
          "id": "456"
        }
      },
      "instruments": {
        "data": [{
          "type": "Instrument",
          "id": "789"
        }]
      }
    },
    "links": { ... }
  },
  "included": [
    {
      "type": "Instrument",
      "id": "789",
      "attributes": {
        "name": "Piano"
      }
    }
  ],
  "meta": {
    "parent": {
      "id": "1",
      "type": "Organization"
    }
  }
})

Will return a transformed object:

{
  data: {
    // string IDs are parsed into integers
    id: 123,
    type: "Person",

    // all keys are camel-cased
    firstName: "Marvin",
    lastName: "Gaye",

    // belongs to relationships are given a singular foreign key property
    topSongId: 456,
    topSongType: "Song",

    // relationships not also `included` are given a property with a null value
    topSong: null,

    // has many relationships are given a plural foreign key property
    instrumentIds: [789],

    // included records are gathered via relationships & placed in a collection:
    instruments: [
      { id: 789, type: "Instrument", name: "Piano" },
    ],

    links: {}
  },
  // response meta is available in case you need it
  meta: { parent: { id: "1", type: "Organization" } }
}

---

transformRequestData

transformRequestData takes an object with request parameters and transforms to a more api friendly format.

For example:

transformRequestData({
  fields: { Song: ["title", "arrangements"], Arrangement: ["name"] },
  include: "arrangements",
  where: { title: "I Like Bugs" },
})

Will return a transformed object:

{
  "fields[Song]": "title,arrangements",
  "fields[Arrangement]": "name",
  include: "arrangements",
  per_page: 100,
  "where[title]": "I Like Bugs",
}

---

Client Request Methods

Request methods are exposed on instances of Client.

import { Client } from "@planningcenter/api-client"

// You may choose to instantiate clients as needed, or export a singleton for use across multiple call-sites
const client = new Client({ app: "services", version: "2018-11-01" })

GET

Note:

• fields are required
• non-standard meta attributes are discarded when walking pagination with walk: true

client.get({
  url: '/plans',
  data: {
    where: { title: 'Plan Title' },
    include: ['series'],
    order: 'created_at',
    fields: { Plan: 'dates,series,title', Series: 'title,artwork_for_dashboard' },
  }
})

POST

Fields are recommended, it will warn in dev if you do not pass them

client.post({
  url: '/series',
  data: {
    fields: { Series: 'title,artwork_for_dashboard' },
    data: {
      type: 'Series',
      attributes: { name: 'New Series Name' },
      relationships: {
        plan: {
          data: { type: 'Plan', id }
        }
      }
    }
  }
})

PATCH

Fields are recommended, it will warn in dev if you do not pass them

client.patch({
  url: `/series/${seriesId}`,
  data: {
    fields: { Series: 'title,artwork_for_dashboard' },
    data: { type: 'Series', attributes: { name: 'New Series Name' }
  }
})

DELETE

same as what you would expect

client.delete({ url: `/series/${seriesId}` })

---

contributions are welcome, please read the contribution guidelines before submiting any pull requests

---

Write something nice in my guest book:

---

Have a good day!