@pinecards/client v0.1.0

Pine's client library provides an easy way to interact with the Pine API in a type-safe manner. For a complete overview of the documentation, please visit docs.pinecards.app instead.

Installation

To get started, you'll first need to install the library in your project with your preferred package manager:

npm install @pinecards/client

You can then import the PineClient class and construct it with your authorization token:

import { PineClient } from "@pinecards/client";

const client = new PineClient({ accessToken: "YOUR_TOKEN" });

The PineClient uses tRPC under the hood to make network requests. As a result, this requires explicitly denoting whether a certain operation is a query or a mutation.

client.cards.list.query({ limit: 100 });

The list and read operations are always queries, while the create, update, and delete operations are always mutations. Following these conventions allows the client to be used with other React libraries that interface with tRPC.

Queries

"Read" queries are the simplest operations as they only require a valid idas part of their where argument:

const deck = await client.decks.read.query({ where: { id: "..." } });
const card = await client.cards.read.query({ where: { id: "..." } });

"List" queries rely on cursor-based pagination and can thus optionally take a limit (min 1, max 100) and a cursor argument:

const response = await client.decks.list.query({ where: { limit: 100 } });

if (response.cursor) {
  const { results } = await client.decks.list.query({
    where: { cursor: response.cursor }
  });
}

Mutations

"Create" mutations take data inputs that depend on the model that is being operated on:

• Decks require a title argument that accepts an input array that conforms to Pine's inline text editor.
• Cards require a title and body argument that conforms to Pine's block text editor.
• Associations (comments etc..) require a body argument that conforms to Pine's block text editor, and a where argument for specifying the parent model that the association should be added to.

// create a deck with bolded inline text
const deck = await client.decks.create.mutate({
  data: {
    title: [
      {
        type: "text",
        text: { text: "Example text" },
        marks: [{ type: "bold" }]
      }
    ]
  }
});

// create a card with block elements that have inline text
const card = await client.cards.create.mutate({
  data: {
    title: [
      {
        type: "heading",
        heading: { color: "gray" },
        content: [{ type: "text", text: { text: "Question" } }]
      }
    ],
    body: [
      {
        type: "paragraph",
        paragraph: { color: "gray" },
        content: [{ type: "text", text: { text: "Answer" } }]
      }
    ]
  }
});

// create an association with a paragraph that indents another paragraph
const association = await client.cards.associations.create.mutate({
  where: { parent: { id: card.id } },
  data: {
    body: [
      {
        type: "paragraph",
        paragraph: { color: "gray" },
        children: [{ type: "paragraph", paragraph: { color: "gray" } }]
      }
    ]
  }
});

Pine's editor adopts a hierarchical schema (similar to Notion!), where the structure of the data maps very neatly to what gets rendered on the screen.

"Update" mutations are similar, except they require a where argument and optional data:

// update the target deck
const deck = await client.decks.update.mutate({
  where: { id: "..." },
  data: {}
});

// update the target card
const card = await client.cards.update.mutate({
  where: { id: "..." },
  data: {}
});

// update the target association
const association = await client.cards.associations.update.mutate({
  where: { id: "...", parent: { id: "..." } },
  data: {}
});

"Delete" mutations only require a where argument:

await client.decks.delete.mutate({
  where: { id: "..." }
});

await client.cards.delete.mutate({
  where: { id: "..." }
});

await client.cards.associations.delete.mutate({
  where: { id: "...", parent: { id: "..." } }
});

Preferences

The Preferences API allows you to query a user's configured preferences. This will return an object/dictionary data structure with the appropriate field type matching the corresponding value type:

Preferences that haven't been assigned a value will return a null value.

You can retrieve the value of a configured number field as follows:

const preferences: Record<string, any> = await client.preferences.read.query();
const value: number | null = preferences["COPY_ID_FROM_UI"];