Client Library

Process workspace data by using Pine's API client.

This library is only intended for use on the frontend. Use the @pinecards/server library to communicate with Pine on the backend.

Pine's client library provides an easy way to interact with the Pine API from within a frontend extension.

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

npm install @pinecards/client

The PineSDKClient uses IPC messages under the hood to securely communicate with Pine. To create the connection, it's thus necessary to call connectSDKClient as soon as possible in the global scope of your application:

import { connectSDKClient } from "@pinecards/client";
 
const client = connectSDKClient({ debug: false }) 

The cards, decks, and fields namespaces follow a similar signature to server library, while namespaces like routes , storage, and context are available exclusively through the client library.

Cards

The cards namespace provides methods for interacting with card data.

Data can be queried using read and list, as expanded on in queries.

const card = await client.cards.read({ where: { id: "..." } });
const { data: cards } = await client.cards.list({ where: { limit: 100 } });

Data can be mutated using create, update, and delete, as expanded on in mutations.

const createdCard = await client.cards.create({
  data: { title: [], body: [] },
});

const updatedCard = await client.cards.update({
  where: { id: "..." },
  data: { title: [], body: [] },
});

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

Data can be subscribed to by using the on handler:

await client.cards.on("cardsChange", event => {
  const cards = event.data;
});

These methods will throw an error if you do not have the required card permissions.

The cards namespace also supports the following sub-namespaces:

• associations: create, update, and delete card associations (comments, etc...).

• connections: create, update, and delete card connections (links, backlinks, etc...).

• embeddings: read and list local AI card embeddings.

Decks

The decks namespace provides methods for interacting with deck data.

Data can be queried using read and list, as expanded on in queries.

const deck = await client.decks.read({ where: { id: "..." } });
const { data: decks } = await client.decks.list({ where: { limit: 100 } });

Data can be mutated using create, update, and delete, as expanded on in mutations.

const createdDeck = await client.decks.create({
  data: { title: [], description: [] },
});

const updatedDeck = await client.decks.update({
  where: { id: "..." },
  data: { title: [], description: [] },
});

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

Data can be subscribed to by using the on handler:

await client.decks.on("decksChange", event => {
  const decks = event.data;
});

These methods will throw an error if you do not have the required deck permissions.

The decks namespace also supports the following sub-namespaces:

• associations: create, update, and delete deck associations (comments, etc...).

• connections: create, update, and delete deck connections (links, backlinks, etc...).

• embeddings: read and list local AI deck embeddings.

Fields

The fields namespace provides methods for interacting with a workspace's configured preferences. This will return an object/dictionary data structure with the appropriate field type matching the corresponding value type:

Field type	Value type
text	string
number	number
switch	boolean
date	string

Fields 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 fields = await client.fields.list({ where: {} });
const value = fields.data.find(field => field.id === "ID_FROM_UI")

Routes

The routes namespace allows you to listen to route changes, as well as navigate users to specific routes.

// push to a route
await client.routes.push({
  path: "/dates/:dateId",
  params: { dateId: new Date().toISOString() },
});

// replace existing route
await client.routes.replace({
  path: "/dates/:dateId",
  params: { dateId: new Date().toISOString() },
});

// fetch current route
const route = await client.routes.get();

// listen to route changes
await client.routes.on("routeChange", (event) => {
  switch (event.data.path) {
    case "/dates/:dateId":
      // do something
      break;
  }
});

Storage

The storage namespace provides methods for storing data in IndexedDB.

The data that is stored in IndexedDB is not encrypted. It's thus not recommended that any sensitive data be stored here. Instead, it should be used to persist in the application state between sessions or store other forms of non-sensitive data.

As mentioned in size limits, Pine also limits the size of input parameters and overall storage requests to 256KB.

To minimize security risks, both the key and value arguments must be strings. It's recommended to serialize your inputs to strings (e.g. using JSON.stringify()) if you wish to store more complex objects:

// set the following key-value pair in storage
await client.storage.set({
  key: "key",
  value: JSON.stringify({ foo: "bar" }),
});

// retrieve the value associated with the key from storage
const result = await client.storage.get({ key: "key" });
if (result) JSON.parse(result);

// remove the key from storage
await client.storage.remove({ key: "key" });

// clear the storage completely
await client.storage.clear();

Context

The context namespace provides utilities for accessing information such as theme data or manipulating the optional badge that appears next to the integration icon in the sidebar.

const theme = await client.context.getTheme();

await client.context.on("themeChange", (event) => {
  const theme = event.data;
});

await client.context.setBadge({ count: 5 });