@archastro/sdk 0.5.3 → 0.7.0

package/docs/authentication.md

@@ -0,0 +1,91 @@
+---
+title: Authentication
+group: Guides
+---
+
+# Authentication
+
+`@archastro/sdk` supports four auth shapes. Pick the one that matches who the
+process is acting as.
+
+## Mobile / SPA durable app session
+
+Use this for React Native or browser apps that sign users in (passwordless OTP
+or other flows) and need access tokens to auto-refresh across restarts.
+
+```ts
+import { PlatformClient, type SessionStorage } from "@archastro/sdk";
+
+const client = PlatformClient.forApp({
+  publishableKey: process.env.ARCHASTRO_PUBLISHABLE_KEY ?? "",
+  baseUrl: process.env.ARCHASTRO_PLATFORM_BASE_URL, // optional
+  storage, // your SecureStore / AsyncStorage adapter
+});
+
+await client.restore();
+// login → client.passwordless… → client.signIn(tokens, user)
+const me = await client.users.me();
+```
+
+On 401 the client exchanges the refresh token via `POST /api/v1/auth/refresh`,
+updates storage, and retries. See [React Native](./react-native.md).
+
+## Static user access token
+
+Use this when a user has already signed in elsewhere and your code only has a
+publishable API key plus a short-lived access token (no durable refresh).
+
+```ts
+import { PlatformClient } from "@archastro/sdk";
+
+const client = PlatformClient.withToken(
+  process.env.ARCHASTRO_API_KEY ?? "",
+  process.env.ARCHASTRO_ACCESS_TOKEN ?? "",
+);
+
+const me = await client.users.me();
+console.log(me.id, me.email);
+```
+
+## Org bot or worker
+
+Use this when a backend process should act as an org-owned system user. The
+token should be an app-scoped user token created for that bot or worker.
+
+```ts
+import { PlatformClient } from "@archastro/sdk";
+
+const client = new PlatformClient({
+  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
+});
+
+const me = await client.users.me();
+console.log(me.id);
+```
+
+## Email/password (scripts)
+
+```ts
+const client = await PlatformClient.withCredentials(
+  publishableKey,
+  email,
+  password,
+  baseUrl,
+);
+```
+
+Wires in-memory refresh only — tokens are not persisted. Prefer `forApp` for
+long-lived clients.
+
+## Local or staging targets
+
+The SDK defaults to `https://platform.archastro.ai`. Override `baseUrl` only
+when targeting local development, staging, or another non-production gateway.
+
+```ts
+const client = PlatformClient.forApp({
+  publishableKey: process.env.ARCHASTRO_PUBLISHABLE_KEY ?? "",
+  baseUrl: process.env.ARCHASTRO_PLATFORM_BASE_URL,
+  storage,
+});
+```

package/docs/react-native.md

@@ -0,0 +1,118 @@
+---
+title: React Native
+group: Guides
+---
+
+# React Native / Expo
+
+`@archastro/sdk` works in React Native and Expo without Node polyfills
+(`events`, `ws`, etc.). The package ships a Metro-resolved native entry and a
+`.native` WebSocket factory that uses the global `WebSocket` only.
+
+## Install
+
+```sh
+npm install @archastro/sdk
+```
+
+`zod` is a normal dependency and is resolved by Metro from the package. The
+optional `ws` package is **Node-only** and is not required in RN (Metro loads
+`phx_channel/websocket.native.js` instead).
+
+## One client: `PlatformClient.forApp`
+
+Provide durable storage (Expo SecureStore or AsyncStorage) and a publishable
+key. Session lifecycle, passwordless OTP, auto-refresh, and REST all live on
+the same `PlatformClient` instance:
+
+```ts
+import {
+  PlatformClient,
+  ApiChatChannel,
+  type SessionStorage,
+  type AppSession,
+} from "@archastro/sdk";
+import * as SecureStore from "expo-secure-store";
+
+// Only SessionStorage is a public type you implement — OTP, refresh, and
+// sockets are methods on the client returned by forApp.
+const storage: SessionStorage = {
+  async load() {
+    const raw = await SecureStore.getItemAsync("archastro_session");
+    return raw ? (JSON.parse(raw) as AppSession) : null;
+  },
+  async save(session) {
+    await SecureStore.setItemAsync("archastro_session", JSON.stringify(session));
+  },
+  async clear() {
+    await SecureStore.deleteItemAsync("archastro_session");
+  },
+};
+
+const client = PlatformClient.forApp({
+  baseUrl: process.env.EXPO_PUBLIC_API_BASE_URL!,
+  publishableKey: process.env.EXPO_PUBLIC_PUBLISHABLE_KEY!,
+  storage,
+});
+
+await client.restore();
+
+// Passwordless OTP (behind the client — not a free-standing auth class)
+await client.passwordless.register({
+  email: "you@company.com",
+  full_name: "You",
+  alias: "you",
+});
+// or requestLoginCode on existing accounts
+
+const { tokens, user } = await client.passwordless.verifyCode({
+  email: "you@company.com",
+  code: "123456",
+});
+await client.signIn(tokens, user as AppSession["user"]);
+
+// Typed REST — 401 auto-refreshes using the stored refresh token
+const me = await client.users.me();
+const agents = await client.agents.list();
+```
+
+## Realtime chat
+
+```ts
+const socket = client.createSocket(); // uses current access token + publishable key
+await socket.connect();
+
+const channel = await ApiChatChannel.joinUserThread(socket, threadId, {
+  limit: 50,
+});
+await channel.apiChatPostMessage({ content: "Hello" });
+```
+
+## What the SDK needs from RN
+
+| Need | Source |
+|---|---|
+| HTTP | global `fetch` |
+| WebSocket | global `WebSocket` |
+| Token persistence | your `SessionStorage` |
+| API base URL | e.g. `http://localhost:4005` (sim) or production |
+| Publishable key | `x-archastro-api-key` header |
+
+## Local monorepo (file: link)
+
+When developing against a local `archastro-js` checkout:
+
+```json
+"@archastro/sdk": "file:../../../archastro-js/packages/sdk"
+```
+
+Point Metro `watchFolders` at the SDK package and rebuild after SDK changes:
+
+```sh
+cd packages/sdk && npm run build
+```
+
+## iOS simulator localhost
+
+The iOS simulator can reach the host via `http://localhost:PORT`. Physical
+devices need your machine LAN IP instead.

package/docs/scenarios.md

@@ -0,0 +1,57 @@
+---
+title: Integration Scenarios
+group: Guides
+---
+
+# Integration Scenarios
+
+These examples show the SDK shape for common integrations. They were smoke-tested
+against the local platform dev harness with org-user tokens.
+
+## Read The Current User
+
+Use `users.me()` to validate that a token is usable and to discover the current
+actor.
+
+```ts
+import { PlatformClient } from "@archastro/sdk";
+
+const client = PlatformClient.withToken(
+  process.env.ARCHASTRO_API_KEY ?? "",
+  process.env.ARCHASTRO_ACCESS_TOKEN ?? "",
+);
+
+const me = await client.users.me();
+console.log(me.id, me.email);
+```
+
+## List Teams
+
+Use resource collections directly from the client. List responses are typed and
+follow the API response shape for that resource.
+
+```ts
+const teams = await client.teams.list();
+console.log(teams);
+```
+
+## Create An Agent
+
+Use `agents.create()` to provision an agent owned by the current user, org, or
+team context. Store the returned `id` if you need to fetch or update it later.
+
+```ts
+const agent = await client.agents.create({
+  name: "Support triage",
+  identity: "You triage support requests and keep replies concise.",
+});
+
+console.log(agent.id, agent.name);
+```
+
+For cleanup in tests and scripts:
+
+```ts
+await client.agents.delete(agent.id);
+```
+

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@archastro/sdk",
-  "version": "0.5.3",
-  "description": "TypeScript SDK for the ArchAstro Platform API",
+  "version": "0.7.0",
+  "description": "TypeScript SDK for the ArchAstro Platform API (Node, browser, React Native)",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "react-native": "dist/index.native.js",
+  "browser": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "tsc",
@@ -24,16 +27,35 @@
     "directory": "packages/sdk"
   },
   "dependencies": {
-    "ws": "^8.17.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@archastro/channel-harness": "^0.1.0",
+    "@archastro/channel-harness": "^0.4.0",
     "@stoplight/prism-cli": "^5.14.2",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
     "typedoc": "^0.28.19",
     "typescript": "^5.4.0",
-    "vitest": "^4.1.3"
+    "vitest": "^4.1.3",
+    "ws": "^8.17.0"
+  },
+  "keywords": [
+    "archastro",
+    "sdk",
+    "react-native",
+    "expo",
+    "phoenix",
+    "typescript"
+  ],
+  "optionalDependencies": {
+    "ws": "^8.17.0"
+  },
+  "peerDependencies": {
+    "ws": "^8.17.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
   }
 }