@synap-core/sdk 0.2.0 → 1.1.0

package/dist/index.js

@@ -1,48 +1,81 @@
-/**
- * @synap/sdk - High-Level SDK for Synap
- *
- * Event-sourced personal data platform SDK with type-safe APIs.
- *
- * @example
- * ```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',
- *   },
- * });
- *
- * // Create entity (event-sourced)
- * const task = await synap.entities.create({
- *   type: 'task',
- *   title: 'Call Marie',
- *   metadata: { dueDate: '2024-12-20', priority: 'high' }
- * });
- *
- * // 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);
- * ```
- */
-export { SynapSDK } 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';
+// src/client.ts
+import {
+  createTRPCClient,
+  httpBatchLink
+} from "@trpc/client";
+import superjson from "superjson";
+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 createTRPCClient({
+    links: [
+      httpBatchLink({
+        url,
+        transformer: superjson,
+        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
+        })
+      })
+    ]
+  });
+}
+export {
+  createSynapClient
+};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,QAAQ,EAAuB,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["/**\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":";AAmBA;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AACP,OAAO,eAAe;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,SAAO,iBAA4B;AAAA,IACjC,OAAO;AAAA,MACL,cAAc;AAAA,QACZ;AAAA,QACA,aAAa;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":[]}

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@synap-core/sdk",
-  "version": "0.2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "High-level SDK for Synap - Event-sourced personal data platform",
+  "version": "1.1.0",
+  "description": "Type-safe tRPC client SDK for Synap data pods",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -14,39 +11,53 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./public": {
+      "types": "./dist/public.d.ts",
+      "import": "./dist/public.js",
+      "require": "./dist/public.cjs"
     }
   },
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
   "keywords": [
     "synap",
     "sdk",
-    "event-sourcing",
-    "personal-data",
-    "knowledge-graph"
+    "trpc",
+    "data-pod"
   ],
-  "author": "Synap Team",
-  "license": "AGPL-3.0",
   "dependencies": {
-    "@synap-core/client": "^0.1.0",
-    "@synap-core/types": "^0.1.0"
+    "@synap-core/api-types": "^1.25.7",
+    "@trpc/client": "^11.10.0",
+    "superjson": "^2.2.6"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
-    "typescript": "^5.3.3"
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "peerDependencies": {
+    "@trpc/server": "^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@trpc/server": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/synap-core/synap-backend",
+    "url": "https://github.com/synap/synap-app.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/synap-core/synap-backend#readme",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "license": "MIT"
+}

package/src/client.ts

@@ -0,0 +1,193 @@
+/**
+ * @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();
+ * ```
+ */
+
+import {
+  createTRPCClient,
+  httpBatchLink,
+  type CreateTRPCClient,
+} from "@trpc/client";
+import superjson from "superjson";
+import type { AppRouter } from "@synap-core/api-types";
+
+export 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.
+ */
+export function createSynapClient(
+  options: SynapClientOptions,
+): CreateTRPCClient<AppRouter> {
+  const { podUrl, apiKey, workspaceId, extraHeaders, onAuthError } = options;
+
+  const url = `${podUrl.replace(/\/$/, "")}/trpc`;
+
+  // Base fetch: always include credentials so session cookies are sent in
+  // cookie-auth mode. When apiKey is present, the Bearer token takes precedence
+  // on the pod.
+  const baseFetch: typeof fetch = (input, init) =>
+    fetch(input, { ...init, credentials: "include" });
+
+  // When an onAuthError handler is provided, wrap fetch to catch 401 (and other
+  // non-tRPC error) responses. The pod's auth middleware replies with a plain
+  // JSON body that is not a tRPC batch array; left untouched it crashes the
+  // superjson transformer. We notify the handler and rewrite the body into a
+  // valid tRPC error envelope so the query rejects cleanly.
+  const wrappedFetch: typeof fetch = 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) as {
+              error?: string;
+              message?: string;
+            };
+            return parsed.error ?? parsed.message ?? null;
+          } catch {
+            return null;
+          }
+        })();
+        // Never forward a server-controlled string as user-facing copy — map by
+        // status. The raw server detail is preserved (untrusted) on `data.detail`.
+        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 : -32000,
+              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 ?? undefined,
+              },
+
+            },
+          },
+        ];
+        return new Response(JSON.stringify(trpcError), {
+          status: response.status,
+          headers: { "content-type": "application/json" },
+        });
+      }
+    : baseFetch;
+
+  return createTRPCClient<AppRouter>({
+    links: [
+      httpBatchLink({
+        url,
+        transformer: superjson,
+        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,
+        }),
+      }),
+    ],
+  });
+}
+
+export type SynapClient = ReturnType<typeof createSynapClient>;
+
+// Re-export type helpers so consumers don't need @trpc/server
+export type { AppRouter };

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createSynapClient } from "./client";
+export type { SynapClient, SynapClientOptions, AppRouter } from "./client";