@archastro/sdk

TypeScript SDK for the ArchAstro Platform API.

Documentation

API reference documentation is published at archastro.github.io/archastro-js.

Use this site in two layers:

• Start with the guides when you are wiring the SDK into an app, worker, or internal tool.
• Use the API reference when you know the resource or method you need.

Install

npm install @archastro/sdk

Choose An Auth Mode

Most app integrations use a publishable API key plus a user access token:

import { PlatformClient } from "@archastro/sdk";

const client = PlatformClient.withToken(
  process.env.ARCHASTRO_API_KEY ?? "",
  process.env.ARCHASTRO_ACCESS_TOKEN ?? "",
);

Server-side org bots and workers can also use an app-scoped user token directly:

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
});

Set baseUrl only for local development or staging:

import { PlatformClient } from "@archastro/sdk";

const client = PlatformClient.withToken(
  process.env.ARCHASTRO_API_KEY ?? "",
  process.env.ARCHASTRO_ACCESS_TOKEN ?? "",
  process.env.ARCHASTRO_PLATFORM_BASE_URL,
);

Quickstart

const me = await client.users.me();
const teams = await client.teams.list();

console.log(me.id, me.email, teams);

React Native / Expo

Native mobile works out of the box — no Node ws / events polyfills. Use PlatformClient.forApp so session storage, passwordless OTP, and auto-refresh stay behind one client (not a parallel session helper):

import { PlatformClient, ApiChatChannel, type SessionStorage } from "@archastro/sdk";

const client = PlatformClient.forApp({
  publishableKey: process.env.EXPO_PUBLIC_PUBLISHABLE_KEY!,
  baseUrl: process.env.EXPO_PUBLIC_API_BASE_URL!,
  storage, // your SessionStorage (SecureStore / AsyncStorage)
});

await client.restore();
// client.passwordless… → client.signIn(tokens, user)
await client.agents.list();
const socket = client.createSocket();

See React Native guide.

Integration Guides

• Authentication: choose the right token strategy for browser sessions, server-side app integrations, and org workers.
• React Native / Expo: session storage, passwordless auth, and chat channels without Node polyfills.
• Integration scenarios: read the current user, list teams, and create an agent with snippets that were smoke-tested against the local platform dev harness.
• Custom-object collaboration: team-owned objects, same-origin cookie authentication, realtime snapshots, reconnect recovery, presence, and React cleanup.

Common Resource Pattern

Resources hang directly off PlatformClient and under client.v1:

await client.agents.list();
await client.agents.create({
  name: "Support triage",
  identity: "You triage support requests and keep replies concise.",
});

The generated API surface includes typed REST resources, auth helpers, and channel clients. The lower-level Phoenix Channel client is documented in src/phx_channel/README.md.