@synap-core/sdk 0.2.0 → 1.1.0

package/README.md

@@ -1,173 +1,99 @@
-# @synap/sdk
+# @synap-core/sdk
 
-High-level SDK for Synap - Event-sourced personal data platform
+Type-safe tRPC client for [Synap](https://synap.live) data pods. Connect any JavaScript/TypeScript app to your personal data pod with full autocomplete on all 47+ routers.
 
-## Installation
+## Install
 
 ```bash
-pnpm add @synap/sdk
+npm install @synap-core/sdk
+# or
+pnpm add @synap-core/sdk
 ```
 
-## Quick Start
+## Quick start
 
 ```typescript
-import { SynapSDK } from '@synap/sdk';
+import { createSynapClient } from "@synap-core/sdk";
 
-// Initialize SDK
-const synap = new SynapSDK({
-  url: 'https://api.synap.app',
-  apiKey: 'your-api-key'
+const synap = createSynapClient({
+  podUrl: "https://your-pod.synap.live", // your data pod URL
+  apiKey: "sk_live_...", // from Workspace → Settings → API Keys
+  workspaceId: "ws_...", // your workspace ID
 });
 
-// Create entity (event-sourced)
-const { entityId } = await synap.entities.create({
-  type: 'task',
-  title: 'Call Marie tomorrow',
-  metadata: {
-    dueDate: '2024-12-20',
-    priority: 'high'
-  }
-});
-
-// Create relationship (event-sourced)
-await synap.relations.create(entityId, personId, 'assigned_to');
+// Fully typed — autocomplete works on all procedures
+const entities = await synap.entities.list.query({ limit: 20 });
+const workspace = await synap.workspaces.get.query();
 
-// Query data (direct reads)
-const tasks = await synap.entities.list({ type: 'task' });
-const history = await synap.events.getHistory(entityId);
+// Create an entity
+await synap.entities.create.mutate({
+  profileSlug: "note",
+  title: "My first note",
+  properties: { content: "Hello from the SDK!" },
+});
 ```
 
-## Architecture
-
-### Event Sourcing
-
-All **mutations** go through event sourcing:
-- `entities.create/update/delete` → `events.log` → Inngest worker → Database
-- `relations.create/delete` → `events.log` → Inngest worker → Database
-
-All **queries** are direct database reads:
-- `entities.get/list/search` → Direct query
-- `relations.get/getRelated` → Direct query
-- `events.getHistory` → Direct query
-
-### Benefits
-
-- **Audit trail**: Every change logged as immutable event
-- **Time travel**: Replay events to see past states
-- **Reliability**: Workers handle async processing with retries
-- **Real-time**: Events trigger webhooks and SSE broadcasts
+## Authentication
 
-## API Reference
-
-### Entities API
+**API key (server-side / external apps)**
 
 ```typescript
-// Create
-const { entityId } = await synap.entities.create({
-  type: 'note',
-  title: 'Meeting Notes',
-  content: '# Discussion points...'
-});
-
-// Update
-await synap.entities.update(entityId, {
-  title: 'Updated Title'
-});
-
-// Delete (soft delete)
-await synap.entities.delete(entityId);
-
-// Get
-const entity = await synap.entities.get(entityId);
-
-// List
-const notes = await synap.entities.list({
-  type: 'note',
-  limit: 20
-});
-
-// Search
-const results = await synap.entities.search({
-  query: 'project planning',
-  types: ['note', 'task']
+const synap = createSynapClient({
+  podUrl: "https://your-pod.synap.live",
+  apiKey: "sk_live_...", // Bearer token — generate in workspace settings
+  workspaceId: "ws_...",
 });
 ```
 
-### Relations API
+**Session cookie (browser — after Kratos login)**
 
 ```typescript
-// Create relationship
-await synap.relations.create(
-  sourceEntityId,
-  targetEntityId,
-  'assigned_to'
-);
-
-// Get relations
-const relations = await synap.relations.get(entityId, {
-  type: 'assigned_to',
-  direction: 'both' // 'source' | 'target' | 'both'
+const synap = createSynapClient({
+  podUrl: "https://your-pod.synap.live",
+  workspaceId: "ws_...",
+  // omit apiKey — credentials: "include" is set automatically
 });
+```
 
-// Get related entities
-const people = await synap.relations.getRelated(taskId, {
-  type: 'assigned_to',
-  direction: 'source'
-});
+## Type helpers
 
-// Get statistics
-const stats = await synap.relations.getStats(entityId);
-// Returns: { total, outgoing, incoming, byType }
+```typescript
+import type { RouterInputs, RouterOutputs } from "@synap-core/sdk";
 
-// Delete relationship
-await synap.relations.delete(relationId);
+type EntityListInput = RouterInputs["entities"]["list"];
+type EntityListOutput = RouterOutputs["entities"]["list"];
 ```
 
-### Events API
+## Public doors (no credentials): `@synap-core/sdk/public`
+
+A tiny, dependency-free fetch client for the pod's credentialless public doors
+(published shares, guest forms). It never sends credentials (`credentials: 'omit'`,
+no Authorization/Cookie) and works from any origin, so it is safe in a public site.
 
 ```typescript
-// Get entity history
-const history = await synap.events.getHistory(entityId, {
-  eventTypes: ['entities.create.validated'],
-  limit: 100
-});
+import { createPublicClient } from "@synap-core/sdk/public";
 
-// Get user timeline
-const timeline = await synap.events.getTimeline({
-  limit: 50
-});
+const pub = createPublicClient({ podUrl: "https://your-pod.synap.live" });
 
-// Replay events to rebuild state
-const state = await synap.events.replay(entityId);
+const share = await pub.readShare(token); // { ok: true, data } | { ok: false, error }
+const form = await pub.getForm(formToken); // fields, honeypotField, ticket, captcha
+const sent = await pub.submitForm(formToken, {
+  fields: { email: "a@b.co" },
+  ticket: form.ok ? form.data.ticket : undefined,
+  captchaToken, // when form.data.captcha.required
+});
 ```
 
-## Entity Types
+Errors are typed: `not_found` (the uniform 404: unknown, revoked and expired are
+indistinguishable), `rate_limited`, `network`, `server`. A submit always answers
+`{ ok: true, received: true }` on the pod's constant 202; the pod silently drops
+too-fast, honeypot, captcha-failed and over-cap submissions, so wait out the form's
+minimum time before submitting. Pass `fetch` to inject your own.
 
-```typescript
-type EntityType = 
-  | 'task'
-  | 'note'
-  | 'person'
-  | 'event'
-  | 'file';
-```
+## React
 
-## Relation Types
-
-```typescript
-type RelationType =
-  | 'assigned_to'    // Task → Person
-  | 'mentions'       // Note → Entity
-  | 'links_to'       // Note → Note
-  | 'parent_of'      // Project → Task
-  | 'relates_to'     // Generic
-  | 'tagged_with'    // Entity → Tag
-  | 'created_by'     // Entity → Person
-  | 'attended_by'    // Event → Person
-  | 'depends_on'     // Task → Task
-  | 'blocks';        // Task → Task
-```
+For React apps use [`@synap-core/react`](https://www.npmjs.com/package/@synap-core/react) which wraps this SDK with TanStack Query hooks.
 
-## License
+## API reference
 
-AGPL-3.0
+Full procedure reference: [docs.synap.live/reference/api-reference](https://docs.synap.live/reference/api-reference)

package/dist/index.cjs

@@ -0,0 +1,115 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSynapClient: () => createSynapClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_client = require("@trpc/client");
+var import_superjson = __toESM(require("superjson"), 1);
+function createSynapClient(options) {
+  const { podUrl, apiKey, workspaceId, extraHeaders, onAuthError } = options;
+  const url = `${podUrl.replace(/\/$/, "")}/trpc`;
+  const baseFetch = (input, init) => fetch(input, { ...init, credentials: "include" });
+  const wrappedFetch = onAuthError ? async (input, init) => {
+    const response = await baseFetch(input, init);
+    if (response.ok) return response;
+    const cloned = response.clone();
+    let body = "";
+    try {
+      body = await cloned.text();
+    } catch {
+      body = "";
+    }
+    let isTrpcFormat = false;
+    try {
+      isTrpcFormat = Array.isArray(JSON.parse(body));
+    } catch {
+      isTrpcFormat = false;
+    }
+    if (isTrpcFormat) return response;
+    const parsedMessage = (() => {
+      try {
+        const parsed = JSON.parse(body);
+        return parsed.error ?? parsed.message ?? null;
+      } catch {
+        return null;
+      }
+    })();
+    const message = response.status === 401 ? "Session expired. Please sign in again." : `Request failed (${response.status}).`;
+    if (response.status === 401) {
+      onAuthError({ status: 401, message });
+    }
+    const trpcError = [
+      {
+        error: {
+          message,
+          code: response.status === 401 ? -32001 : -32e3,
+          data: {
+            code: response.status === 401 ? "UNAUTHORIZED" : "INTERNAL_SERVER_ERROR",
+            httpStatus: response.status,
+            // Server-supplied detail — untrusted; consumers must escape it
+            // before rendering (never inject as HTML).
+            detail: parsedMessage ?? void 0
+          }
+        }
+      }
+    ];
+    return new Response(JSON.stringify(trpcError), {
+      status: response.status,
+      headers: { "content-type": "application/json" }
+    });
+  } : baseFetch;
+  return (0, import_client.createTRPCClient)({
+    links: [
+      (0, import_client.httpBatchLink)({
+        url,
+        transformer: import_superjson.default,
+        fetch: wrappedFetch,
+        headers: () => ({
+          // Session token mode (Kratos, preferred for non-browser clients)
+          ...options.sessionToken ? { "x-session-token": options.sessionToken } : {},
+          // API key mode (Bearer, for legacy SDK usage)
+          ...apiKey && !options.sessionToken ? { Authorization: `Bearer ${apiKey}` } : {},
+          ...workspaceId ? { "x-workspace-id": workspaceId } : {},
+          ...extraHeaders
+        })
+      })
+    ]
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSynapClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts"],"sourcesContent":["export { createSynapClient } from \"./client\";\nexport type { SynapClient, SynapClientOptions, AppRouter } from \"./client\";\n","/**\n * @synap-core/sdk — Type-safe tRPC client for Synap data pods.\n *\n * Usage:\n * ```typescript\n * import { createSynapClient } from \"@synap-core/sdk\";\n *\n * const synap = createSynapClient({\n *   podUrl: \"https://pod.example.com\",\n *   apiKey: \"sk_live_...\",\n *   workspaceId: \"ws_...\",\n * });\n *\n * // Fully typed — autocomplete works on all 47+ routers\n * const entities = await synap.entities.list.query({ limit: 20 });\n * const workspace = await synap.workspaces.get.query();\n * ```\n */\n\nimport {\n  createTRPCClient,\n  httpBatchLink,\n  type CreateTRPCClient,\n} from \"@trpc/client\";\nimport superjson from \"superjson\";\nimport type { AppRouter } from \"@synap-core/api-types\";\n\nexport interface SynapClientOptions {\n  /**\n   * Base URL of the data pod (no trailing slash, no `/trpc` suffix).\n   * @example \"https://pod.example.com\"\n   */\n  podUrl: string;\n\n  /**\n   * Ory Kratos session token (for example, from the Pod's\n   * `/api/federation/exchange` endpoint).\n   * Sent as `X-Session-Token` header — preferred for non-browser clients\n   * like extensions, CLI tools, and mobile apps.\n   * @example \"oathkeeper_token_...\"\n   */\n  sessionToken?: string;\n\n  /**\n   * API key for authentication (Bearer token).\n   * Generate one in your workspace developer settings.\n   * If omitted, the client falls back to cookie-based Kratos session auth.\n   * @example \"sk_live_abc123...\"\n   */\n  apiKey?: string;\n\n  /**\n   * Workspace ID to scope all requests to.\n   * Pass empty string for procedures that don't require workspace context\n   * (e.g. workspaces.list, which is protectedProcedure only).\n   * @example \"ws_01jk...\"\n   */\n  workspaceId: string;\n\n  /**\n   * Additional headers to include in every request.\n   */\n  extraHeaders?: Record<string, string>;\n\n  /**\n   * Called when the pod returns a `401 Unauthorized` (expired/invalid session\n   * or API key). The app should sign out and re-authenticate (re-handshake).\n   *\n   * The pod's auth middleware can reply with a plain-JSON body\n   * (`{\"error\":\"Invalid session\"}`) that is NOT in tRPC batch format and would\n   * otherwise crash the superjson transformer; when an `onAuthError` handler is\n   * provided the client rewrites such responses into a well-formed tRPC error so\n   * the query rejects gracefully instead of throwing a parse error.\n   */\n  onAuthError?: (error: { status: number; message: string }) => void;\n}\n\n/**\n * Creates a fully-typed tRPC client connected to a Synap data pod.\n *\n * All 47+ tRPC routers are available with full TypeScript autocomplete\n * and compile-time safety. Auth is handled via Bearer token + workspace header.\n */\nexport function createSynapClient(\n  options: SynapClientOptions,\n): CreateTRPCClient<AppRouter> {\n  const { podUrl, apiKey, workspaceId, extraHeaders, onAuthError } = options;\n\n  const url = `${podUrl.replace(/\\/$/, \"\")}/trpc`;\n\n  // Base fetch: always include credentials so session cookies are sent in\n  // cookie-auth mode. When apiKey is present, the Bearer token takes precedence\n  // on the pod.\n  const baseFetch: typeof fetch = (input, init) =>\n    fetch(input, { ...init, credentials: \"include\" });\n\n  // When an onAuthError handler is provided, wrap fetch to catch 401 (and other\n  // non-tRPC error) responses. The pod's auth middleware replies with a plain\n  // JSON body that is not a tRPC batch array; left untouched it crashes the\n  // superjson transformer. We notify the handler and rewrite the body into a\n  // valid tRPC error envelope so the query rejects cleanly.\n  const wrappedFetch: typeof fetch = onAuthError\n    ? async (input, init) => {\n        const response = await baseFetch(input, init);\n        if (response.ok) return response;\n\n        const cloned = response.clone();\n        let body = \"\";\n        try {\n          body = await cloned.text();\n        } catch {\n          body = \"\";\n        }\n\n        let isTrpcFormat = false;\n        try {\n          isTrpcFormat = Array.isArray(JSON.parse(body));\n        } catch {\n          isTrpcFormat = false;\n        }\n        if (isTrpcFormat) return response;\n\n        const parsedMessage = (() => {\n          try {\n            const parsed = JSON.parse(body) as {\n              error?: string;\n              message?: string;\n            };\n            return parsed.error ?? parsed.message ?? null;\n          } catch {\n            return null;\n          }\n        })();\n        // Never forward a server-controlled string as user-facing copy — map by\n        // status. The raw server detail is preserved (untrusted) on `data.detail`.\n        const message =\n          response.status === 401\n            ? \"Session expired. Please sign in again.\"\n            : `Request failed (${response.status}).`;\n\n        if (response.status === 401) {\n          onAuthError({ status: 401, message });\n        }\n\n        const trpcError = [\n          {\n            error: {\n              message,\n              code: response.status === 401 ? -32001 : -32000,\n              data: {\n                code:\n                  response.status === 401\n                    ? \"UNAUTHORIZED\"\n                    : \"INTERNAL_SERVER_ERROR\",\n                httpStatus: response.status,\n                // Server-supplied detail — untrusted; consumers must escape it\n                // before rendering (never inject as HTML).\n                detail: parsedMessage ?? undefined,\n              },\n\n            },\n          },\n        ];\n        return new Response(JSON.stringify(trpcError), {\n          status: response.status,\n          headers: { \"content-type\": \"application/json\" },\n        });\n      }\n    : baseFetch;\n\n  return createTRPCClient<AppRouter>({\n    links: [\n      httpBatchLink({\n        url,\n        transformer: superjson,\n        fetch: wrappedFetch,\n        headers: () => ({\n          // Session token mode (Kratos, preferred for non-browser clients)\n          ...(options.sessionToken ? { \"x-session-token\": options.sessionToken } : {}),\n          // API key mode (Bearer, for legacy SDK usage)\n          ...(apiKey && !options.sessionToken ? { Authorization: `Bearer ${apiKey}` } : {}),\n          ...(workspaceId ? { \"x-workspace-id\": workspaceId } : {}),\n          ...extraHeaders,\n        }),\n      }),\n    ],\n  });\n}\n\nexport type SynapClient = ReturnType<typeof createSynapClient>;\n\n// Re-export type helpers so consumers don't need @trpc/server\nexport type { AppRouter };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,oBAIO;AACP,uBAAsB;AA2Df,SAAS,kBACd,SAC6B;AAC7B,QAAM,EAAE,QAAQ,QAAQ,aAAa,cAAc,YAAY,IAAI;AAEnE,QAAM,MAAM,GAAG,OAAO,QAAQ,OAAO,EAAE,CAAC;AAKxC,QAAM,YAA0B,CAAC,OAAO,SACtC,MAAM,OAAO,EAAE,GAAG,MAAM,aAAa,UAAU,CAAC;AAOlD,QAAM,eAA6B,cAC/B,OAAO,OAAO,SAAS;AACrB,UAAM,WAAW,MAAM,UAAU,OAAO,IAAI;AAC5C,QAAI,SAAS,GAAI,QAAO;AAExB,UAAM,SAAS,SAAS,MAAM;AAC9B,QAAI,OAAO;AACX,QAAI;AACF,aAAO,MAAM,OAAO,KAAK;AAAA,IAC3B,QAAQ;AACN,aAAO;AAAA,IACT;AAEA,QAAI,eAAe;AACnB,QAAI;AACF,qBAAe,MAAM,QAAQ,KAAK,MAAM,IAAI,CAAC;AAAA,IAC/C,QAAQ;AACN,qBAAe;AAAA,IACjB;AACA,QAAI,aAAc,QAAO;AAEzB,UAAM,iBAAiB,MAAM;AAC3B,UAAI;AACF,cAAM,SAAS,KAAK,MAAM,IAAI;AAI9B,eAAO,OAAO,SAAS,OAAO,WAAW;AAAA,MAC3C,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF,GAAG;AAGH,UAAM,UACJ,SAAS,WAAW,MAChB,2CACA,mBAAmB,SAAS,MAAM;AAExC,QAAI,SAAS,WAAW,KAAK;AAC3B,kBAAY,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAAA,IACtC;AAEA,UAAM,YAAY;AAAA,MAChB;AAAA,QACE,OAAO;AAAA,UACL;AAAA,UACA,MAAM,SAAS,WAAW,MAAM,SAAS;AAAA,UACzC,MAAM;AAAA,YACJ,MACE,SAAS,WAAW,MAChB,iBACA;AAAA,YACN,YAAY,SAAS;AAAA;AAAA;AAAA,YAGrB,QAAQ,iBAAiB;AAAA,UAC3B;AAAA,QAEF;AAAA,MACF;AAAA,IACF;AACA,WAAO,IAAI,SAAS,KAAK,UAAU,SAAS,GAAG;AAAA,MAC7C,QAAQ,SAAS;AAAA,MACjB,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAChD,CAAC;AAAA,EACH,IACA;AAEJ,aAAO,gCAA4B;AAAA,IACjC,OAAO;AAAA,UACL,6BAAc;AAAA,QACZ;AAAA,QACA,aAAa,iBAAAA;AAAA,QACb,OAAO;AAAA,QACP,SAAS,OAAO;AAAA;AAAA,UAEd,GAAI,QAAQ,eAAe,EAAE,mBAAmB,QAAQ,aAAa,IAAI,CAAC;AAAA;AAAA,UAE1E,GAAI,UAAU,CAAC,QAAQ,eAAe,EAAE,eAAe,UAAU,MAAM,GAAG,IAAI,CAAC;AAAA,UAC/E,GAAI,cAAc,EAAE,kBAAkB,YAAY,IAAI,CAAC;AAAA,UACvD,GAAG;AAAA,QACL;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACH;","names":["superjson"]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { CreateTRPCClient } from '@trpc/client';
+import { AppRouter } from '@synap-core/api-types';
+export { AppRouter } from '@synap-core/api-types';
+
+/**
+ * @synap-core/sdk — Type-safe tRPC client for Synap data pods.
+ *
+ * Usage:
+ * ```typescript
+ * import { createSynapClient } from "@synap-core/sdk";
+ *
+ * const synap = createSynapClient({
+ *   podUrl: "https://pod.example.com",
+ *   apiKey: "sk_live_...",
+ *   workspaceId: "ws_...",
+ * });
+ *
+ * // Fully typed — autocomplete works on all 47+ routers
+ * const entities = await synap.entities.list.query({ limit: 20 });
+ * const workspace = await synap.workspaces.get.query();
+ * ```
+ */
+
+interface SynapClientOptions {
+    /**
+     * Base URL of the data pod (no trailing slash, no `/trpc` suffix).
+     * @example "https://pod.example.com"
+     */
+    podUrl: string;
+    /**
+     * Ory Kratos session token (for example, from the Pod's
+     * `/api/federation/exchange` endpoint).
+     * Sent as `X-Session-Token` header — preferred for non-browser clients
+     * like extensions, CLI tools, and mobile apps.
+     * @example "oathkeeper_token_..."
+     */
+    sessionToken?: string;
+    /**
+     * API key for authentication (Bearer token).
+     * Generate one in your workspace developer settings.
+     * If omitted, the client falls back to cookie-based Kratos session auth.
+     * @example "sk_live_abc123..."
+     */
+    apiKey?: string;
+    /**
+     * Workspace ID to scope all requests to.
+     * Pass empty string for procedures that don't require workspace context
+     * (e.g. workspaces.list, which is protectedProcedure only).
+     * @example "ws_01jk..."
+     */
+    workspaceId: string;
+    /**
+     * Additional headers to include in every request.
+     */
+    extraHeaders?: Record<string, string>;
+    /**
+     * Called when the pod returns a `401 Unauthorized` (expired/invalid session
+     * or API key). The app should sign out and re-authenticate (re-handshake).
+     *
+     * The pod's auth middleware can reply with a plain-JSON body
+     * (`{"error":"Invalid session"}`) that is NOT in tRPC batch format and would
+     * otherwise crash the superjson transformer; when an `onAuthError` handler is
+     * provided the client rewrites such responses into a well-formed tRPC error so
+     * the query rejects gracefully instead of throwing a parse error.
+     */
+    onAuthError?: (error: {
+        status: number;
+        message: string;
+    }) => void;
+}
+/**
+ * Creates a fully-typed tRPC client connected to a Synap data pod.
+ *
+ * All 47+ tRPC routers are available with full TypeScript autocomplete
+ * and compile-time safety. Auth is handled via Bearer token + workspace header.
+ */
+declare function createSynapClient(options: SynapClientOptions): CreateTRPCClient<AppRouter>;
+type SynapClient = ReturnType<typeof createSynapClient>;
+
+export { type SynapClient, type SynapClientOptions, createSynapClient };

package/dist/index.d.ts

@@ -1,55 +1,80 @@
+import { CreateTRPCClient } from '@trpc/client';
+import { AppRouter } from '@synap-core/api-types';
+export { AppRouter } from '@synap-core/api-types';
+
 /**
- * @synap/sdk - High-Level SDK for Synap
+ * @synap-core/sdk — Type-safe tRPC client for Synap data pods.
  *
- * Event-sourced personal data platform SDK with type-safe APIs.
- *
- * @example
+ * Usage:
  * ```typescript
- * import { SynapSDK } from '@synap/sdk';
- *
- * const synap = new SynapSDK({
- *   url: 'https://api.synap.app',
- *   apiKey: 'your-api-key',
- *   realtime: {
- *     userId: 'user-123',
- *     userName: 'Alice',
- *   },
- * });
+ * import { createSynapClient } from "@synap-core/sdk";
  *
- * // Create entity (event-sourced)
- * const task = await synap.entities.create({
- *   type: 'task',
- *   title: 'Call Marie',
- *   metadata: { dueDate: '2024-12-20', priority: 'high' }
+ * const synap = createSynapClient({
+ *   podUrl: "https://pod.example.com",
+ *   apiKey: "sk_live_...",
+ *   workspaceId: "ws_...",
  * });
  *
- * // Create workspace
- * const workspace = await synap.workspaces.create({ name: 'Team' });
- *
- * // Create whiteboard
- * const board = await synap.views.create({
- *   type: 'whiteboard',
- *   name: 'Brainstorm',
- *   workspaceId: workspace.id,
- * });
- *
- * // Real-time collaboration
- * synap.realtime?.connectPresence(board.id);
- * const ydoc = synap.realtime?.connectYjs(board.id);
+ * // Fully typed — autocomplete works on all 47+ routers
+ * const entities = await synap.entities.list.query({ limit: 20 });
+ * const workspace = await synap.workspaces.get.query();
  * ```
  */
-export { SynapSDK, type SynapSDKConfig } from './client.js';
-export { EntitiesAPI } from './resources/entities.js';
-export { RelationsAPI } from './resources/relations.js';
-export { EventsAPI } from './resources/events.js';
-export { WorkspacesAPI } from './resources/workspaces.js';
-export { ViewsAPI } from './resources/views.js';
-export { PreferencesAPI } from './resources/preferences.js';
-export type { EntityType, EntityMetadata, Entity, NewEntity, UpdateEntity, } from '@synap-core/types/entities';
-export type { Workspace, WorkspaceMember, CreateWorkspaceInput, UpdateWorkspaceInput, } from '@synap-core/types/workspaces';
-export type { View, CreateViewInput, UpdateViewInput, } from '@synap-core/types/views';
-export type { UserPreferences, UpdatePreferencesInput, } from '@synap-core/types/preferences';
-export type { UserPresence, YDoc, } from '@synap-core/types/realtime';
-export type { Relation, RelationType, } from './types/relations.js';
-export type { Event, EventFilter, } from './types/events.js';
-//# sourceMappingURL=index.d.ts.map
+
+interface SynapClientOptions {
+    /**
+     * Base URL of the data pod (no trailing slash, no `/trpc` suffix).
+     * @example "https://pod.example.com"
+     */
+    podUrl: string;
+    /**
+     * Ory Kratos session token (for example, from the Pod's
+     * `/api/federation/exchange` endpoint).
+     * Sent as `X-Session-Token` header — preferred for non-browser clients
+     * like extensions, CLI tools, and mobile apps.
+     * @example "oathkeeper_token_..."
+     */
+    sessionToken?: string;
+    /**
+     * API key for authentication (Bearer token).
+     * Generate one in your workspace developer settings.
+     * If omitted, the client falls back to cookie-based Kratos session auth.
+     * @example "sk_live_abc123..."
+     */
+    apiKey?: string;
+    /**
+     * Workspace ID to scope all requests to.
+     * Pass empty string for procedures that don't require workspace context
+     * (e.g. workspaces.list, which is protectedProcedure only).
+     * @example "ws_01jk..."
+     */
+    workspaceId: string;
+    /**
+     * Additional headers to include in every request.
+     */
+    extraHeaders?: Record<string, string>;
+    /**
+     * Called when the pod returns a `401 Unauthorized` (expired/invalid session
+     * or API key). The app should sign out and re-authenticate (re-handshake).
+     *
+     * The pod's auth middleware can reply with a plain-JSON body
+     * (`{"error":"Invalid session"}`) that is NOT in tRPC batch format and would
+     * otherwise crash the superjson transformer; when an `onAuthError` handler is
+     * provided the client rewrites such responses into a well-formed tRPC error so
+     * the query rejects gracefully instead of throwing a parse error.
+     */
+    onAuthError?: (error: {
+        status: number;
+        message: string;
+    }) => void;
+}
+/**
+ * Creates a fully-typed tRPC client connected to a Synap data pod.
+ *
+ * All 47+ tRPC routers are available with full TypeScript autocomplete
+ * and compile-time safety. Auth is handled via Bearer token + workspace header.
+ */
+declare function createSynapClient(options: SynapClientOptions): CreateTRPCClient<AppRouter>;
+type SynapClient = ReturnType<typeof createSynapClient>;
+
+export { type SynapClient, type SynapClientOptions, createSynapClient };