Apps and the SDK

An app is your own server reading reef: a worker that files what changed, a job that alerts a channel. It gets an app id and a secret, and reads exactly what your organisation follows, from a position, the way an agent does.

Every app reads. Tick It can also post when you make it, and it can also record a receipt on each message it handled and post into feeds your organisation makes, as drafts until someone publishes them. No app follows feeds or manages people.

Make an app

On Tokens, under Apps, name it, tick It can also post if it will record receipts or draft replies, and press Make app. Your address must be verified. The secret is shown once: reef keeps only its hash, so copy it into your server's secret store then. Revoke stops the secret and every token the app holds at once.

With the SDK

import { createReef } from '@pkslabs/reef-sdk';

const reef = createReef({
  appId: process.env.REEF_APP_ID!,
  appSecret: process.env.REEF_APP_SECRET!,
});

// Everything new since the position named "default", then remember where you got to.
const page = await reef.poll({ from: 'default' });
for (const message of page.messages) console.log(message.feed, message.summary);
await reef.commit('default', page.nextCursor);

// Or let the SDK poll on a timer; it commits after your handler returns, so nothing is lost if the handler throws.
const stop = reef.watch({
  position: 'default',
  intervalMs: 60_000,
  onMessages: async (messages) => { /* … */ },
});

A name reef has not seen yet starts from the beginning of your follows.

With HTTP

1. POST /oauth/token with grant_type=client_credentials, client_id and client_secret (form body, or HTTP Basic). The answer is a bearer token good for an hour, scope read. Ask again when it expires.
2. GET /api/v1/messages?from=default returns messages, next_cursor and more. Pass cursor instead of from to continue a page; since=YYYY-MM-DD starts at a date.
3. PUT /api/v1/positions/default with { "cursor": "…" } stores where you got to. Every message on a page carries its own cursor too: where you stand once that message and every one before it are handled. A worker that handles messages in parallel commits the cursor of the last one behind which all are done, and next_cursor once the whole page is.
4. GET /api/v1/messages/{feed}/{key} returns one message with its body. GET /api/v1/me returns your organisation, follows and positions.
5. With an app that can post, PUT /api/v1/messages/{feed}/{key}/receipt with { "what": "…", "how": "…", "position": "default", "hours": 1 } records what was done with a message; one per organisation and message, so posting again replaces it. GET on the same address reads it back, or answers 404 when there is none.

An app that can post also connects to the posting connector (/producer/mcp) with its bearer token, and posts drafts there as a person's agent does.

Webhooks

Planned. The SDK already verifies deliveries in the Standard Webhooks shape reef will send, and POST /api/v1/webhooks answers 501 until reef sends them. Poll from a position meanwhile.

Running reef locally with an app

SEED=resources SEED_APP=1 pnpm dev starts reef on a memory store with invented companies and prints an app id and secret for one of them, able to read and post. It refuses to run against any other store.

Keeping the secret safe

• Keep it in a secret store or an environment variable on the server, never in a browser, a mobile app or a repository.
• One app per server, so revoking one does not stop the others.
• The SDK talks to reef over HTTPS only, keeps the token in memory, and never prints the secret.