SDK

@peretyn/sdk is the TypeScript client for the Peretyn runtime. It needs Node.js 24 or later.

npm install @peretyn/sdk

Write a schemaCopy Anchor Link

Every example in the SDK guides uses this schema. A document has owners, editors and viewers. Owners and editors can edit it, and all three can view it:

import { any, defineSchema, type } from '@peretyn/sdk';

export const schema = defineSchema({
  user: type(),
  document: type({
    relations: { owner: ['user'], editor: ['user'], viewer: ['user'] },
    permissions: {
      can_edit: any('owner', 'editor'),
      can_view: any('owner', 'editor', 'viewer'),
    },
  }),
});

Create a clientCopy Anchor Link

Pass your schema's type to peretyn and give it the API key of an environment. With the schema type, the compiler rejects any type or relation name that the schema doesn't declare.

import { peretyn } from '@peretyn/sdk';
import type { schema } from './schema';

const authz = peretyn<typeof schema>({
  token: process.env.PERETYN_TOKEN!,
  baseUrl: process.env.PERETYN_RUNTIME_URL,
  timeoutMs: 2000,
});

const { environment } = await authz.me();

console.log(environment);

me returns the scope of the API key: its environment, its project and the store that holds its tuples. The script prints development.

The API key selects the environment, so you never pass a project or environment id.

OptionsCopy Anchor Link

peretyn throws when baseUrl is not a valid URL.

withToken returns a client with the same options and a different API key. Use it when one process serves more than one environment.

Timeouts and retriesCopy Anchor Link

timeoutMs is the budget for a whole call, across every attempt and the time it takes to read the response. A check costs the runtime tens of microseconds, so most of the budget goes to the network. Raise it for lookupResources over large result sets.

The SDK retries network errors, 429 and every 5xx except 504, as long as the budget lasts. It retries a write only when the write is idempotent. See Idempotent writes.

Next stepsCopy Anchor Link