@synap-core/react 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,157 @@
1
+ # @synap-core/react
2
+
3
+ React hooks and provider for [Synap](https://synap.live) data pods. Built on TanStack Query + tRPC for real-time, type-safe data fetching.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @synap-core/react
9
+ # or
10
+ pnpm add @synap-core/react
11
+ ```
12
+
13
+ ## Quick start
14
+
15
+ **1. Wrap your app**
16
+
17
+ ```tsx
18
+ import { SynapProvider } from "@synap-core/react";
19
+
20
+ export default function App() {
21
+ return (
22
+ <SynapProvider
23
+ podUrl="https://your-pod.synap.live"
24
+ apiKey="sk_live_..." // from Workspace → Settings → API Keys
25
+ workspaceId="ws_..."
26
+ >
27
+ <YourApp />
28
+ </SynapProvider>
29
+ );
30
+ }
31
+ ```
32
+
33
+ **2. Use hooks anywhere inside**
34
+
35
+ ```tsx
36
+ import { useSynap } from "@synap-core/react";
37
+
38
+ function EntityList() {
39
+ const { data, isLoading } = useSynap().entities.list.useQuery({ limit: 20 });
40
+
41
+ if (isLoading) return <p>Loading...</p>;
42
+
43
+ return (
44
+ <ul>
45
+ {data?.items.map((entity) => (
46
+ <li key={entity.id}>{entity.title}</li>
47
+ ))}
48
+ </ul>
49
+ );
50
+ }
51
+
52
+ function CreateNote() {
53
+ const create = useSynap().entities.create.useMutation();
54
+
55
+ return (
56
+ <button
57
+ onClick={() =>
58
+ create.mutate({
59
+ profileSlug: "note",
60
+ title: "New note",
61
+ properties: { content: "Hello!" },
62
+ })
63
+ }
64
+ >
65
+ Create note
66
+ </button>
67
+ );
68
+ }
69
+ ```
70
+
71
+ ## API
72
+
73
+ ### `<SynapProvider>`
74
+
75
+ | Prop | Type | Required | Description |
76
+ | -------------- | ------------------------ | -------- | ---------------------------------------- |
77
+ | `podUrl` | `string` | ✓ | Data pod base URL (no trailing slash) |
78
+ | `workspaceId` | `string` | ✓ | Workspace ID |
79
+ | `apiKey` | `string` | — | Bearer token. Omit for cookie-based auth |
80
+ | `extraHeaders` | `Record<string, string>` | — | Extra request headers |
81
+ | `queryClient` | `QueryClient` | — | Reuse an existing TanStack Query client |
82
+
83
+ ### `useSynap()`
84
+
85
+ Returns the full tRPC hook tree. Every procedure is available:
86
+
87
+ ```typescript
88
+ // Queries
89
+ useSynap().entities.list.useQuery(input);
90
+ useSynap().workspaces.get.useQuery();
91
+ useSynap().channels.list.useQuery({ workspaceId });
92
+
93
+ // Mutations
94
+ useSynap().entities.create.useMutation();
95
+ useSynap().entities.update.useMutation();
96
+ useSynap().chat.sendMessage.useMutation();
97
+ ```
98
+
99
+ ### `useSynapContext()`
100
+
101
+ Access the current pod URL and workspace ID inside a provider:
102
+
103
+ ```typescript
104
+ const { podUrl, workspaceId } = useSynapContext();
105
+ ```
106
+
107
+ ### Ergonomic data hooks
108
+
109
+ Thin, fully-typed wrappers over the most common reads — no need to remember
110
+ procedure paths. They are plain TanStack-Query hooks (accept `enabled`,
111
+ `staleTime`, etc. as a second argument):
112
+
113
+ ```tsx
114
+ import { useEntity, useEntities, useLinks, useView } from "@synap-core/react";
115
+
116
+ function Profile({ id }: { id: string }) {
117
+ const { data: entity } = useEntity(id); // entities.get
118
+ const { data: links } = useLinks(id); // relations.get (both directions)
119
+ return <h1>{entity?.entity?.title}</h1>;
120
+ }
121
+
122
+ function People() {
123
+ const { data } = useEntities("person", { limit: 50 }); // entities.list
124
+ return <ul>{data?.items.map((e) => <li key={e.id}>{e.title}</li>)}</ul>;
125
+ }
126
+
127
+ function MyView({ viewId }: { viewId: string }) {
128
+ const { data: view } = useView(viewId); // views.get
129
+ return <pre>{JSON.stringify(view, null, 2)}</pre>;
130
+ }
131
+ ```
132
+
133
+ | Hook | Procedure | Notes |
134
+ | ----------------------------- | --------------- | --------------------------------------- |
135
+ | `useEntity(id, opts?)` | `entities.get` | `opts.includeProfile?: boolean` |
136
+ | `useEntities(slug?, opts?)` | `entities.list` | `opts: { workspaceId?, projectId?, limit? }` |
137
+ | `useLinks(entityId, opts?)` | `relations.get` | `opts.direction?: "source" \| "target" \| "both"` (default `both`) |
138
+ | `useView(viewId, opts?)` | `views.get` | — |
139
+
140
+ For anything else, drop down to `useSynap()` (the full tRPC tree).
141
+
142
+ ## Type helpers
143
+
144
+ ```typescript
145
+ import type { RouterInputs, RouterOutputs } from "@synap-core/react";
146
+
147
+ type CreateEntityInput = RouterInputs["entities"]["create"];
148
+ type EntityListOutput = RouterOutputs["entities"]["list"];
149
+ ```
150
+
151
+ ## Vanilla JS
152
+
153
+ For non-React apps use [`@synap-core/sdk`](https://www.npmjs.com/package/@synap-core/sdk) directly.
154
+
155
+ ## API reference
156
+
157
+ Full procedure reference: [docs.synap.live/reference/api-reference](https://docs.synap.live/reference/api-reference)
package/dist/index.cjs ADDED
@@ -0,0 +1,116 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/index.ts
21
+ var index_exports = {};
22
+ __export(index_exports, {
23
+ SynapProvider: () => SynapProvider,
24
+ useEntities: () => useEntities,
25
+ useEntity: () => useEntity,
26
+ useLinks: () => useLinks,
27
+ useSynap: () => trpc,
28
+ useSynapContext: () => useSynapContext,
29
+ useView: () => useView
30
+ });
31
+ module.exports = __toCommonJS(index_exports);
32
+
33
+ // src/SynapProvider.tsx
34
+ var import_react = require("react");
35
+ var import_react_query2 = require("@tanstack/react-query");
36
+ var import_sdk = require("@synap-core/sdk");
37
+
38
+ // src/trpc.ts
39
+ var import_react_query = require("@trpc/react-query");
40
+ var trpc = (0, import_react_query.createTRPCReact)();
41
+
42
+ // src/SynapProvider.tsx
43
+ var import_jsx_runtime = require("react/jsx-runtime");
44
+ var SynapContext = (0, import_react.createContext)(null);
45
+ function useSynapContext() {
46
+ const ctx = (0, import_react.useContext)(SynapContext);
47
+ if (!ctx)
48
+ throw new Error("useSynapContext must be called inside <SynapProvider>");
49
+ return ctx;
50
+ }
51
+ function SynapProvider({
52
+ children,
53
+ queryClient: externalQueryClient,
54
+ ...clientOptions
55
+ }) {
56
+ const { podUrl, sessionToken, apiKey, workspaceId } = clientOptions;
57
+ const [queryClient] = (0, import_react.useState)(
58
+ () => externalQueryClient ?? new import_react_query2.QueryClient({
59
+ defaultOptions: {
60
+ queries: { staleTime: 3e4, retry: 1 }
61
+ }
62
+ })
63
+ );
64
+ const trpcClient = (0, import_react.useMemo)(
65
+ () => (0, import_sdk.createSynapClient)(clientOptions),
66
+ [podUrl, sessionToken, apiKey, workspaceId]
67
+ );
68
+ const ctx = (0, import_react.useMemo)(() => ({ podUrl, workspaceId }), [podUrl, workspaceId]);
69
+ return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SynapContext.Provider, { value: ctx, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(trpc.Provider, { client: trpcClient, queryClient, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_query2.QueryClientProvider, { client: queryClient, children }) }) });
70
+ }
71
+
72
+ // src/hooks.ts
73
+ function useEntity(id, opts = {}) {
74
+ const { includeProfile, ...queryOptions } = opts;
75
+ const input = { id, includeProfile };
76
+ return trpc.entities.get.useQuery(input, {
77
+ enabled: !!id,
78
+ ...queryOptions
79
+ });
80
+ }
81
+ function useEntities(profileSlug, opts = {}) {
82
+ const { workspaceId, projectId, limit, ...queryOptions } = opts;
83
+ const input = {
84
+ profileSlug,
85
+ workspaceId,
86
+ projectId,
87
+ limit
88
+ };
89
+ return trpc.entities.list.useQuery(input, queryOptions);
90
+ }
91
+ function useLinks(entityId, opts = {}) {
92
+ const { direction = "both", ...queryOptions } = opts;
93
+ const input = { entityId, direction };
94
+ return trpc.relations.get.useQuery(input, {
95
+ enabled: !!entityId,
96
+ ...queryOptions
97
+ });
98
+ }
99
+ function useView(viewId, opts = {}) {
100
+ const input = { id: viewId };
101
+ return trpc.views.get.useQuery(input, {
102
+ enabled: !!viewId,
103
+ ...opts
104
+ });
105
+ }
106
+ // Annotate the CommonJS export names for ESM import in node:
107
+ 0 && (module.exports = {
108
+ SynapProvider,
109
+ useEntities,
110
+ useEntity,
111
+ useLinks,
112
+ useSynap,
113
+ useSynapContext,
114
+ useView
115
+ });
116
+ //# sourceMappingURL=index.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.ts","../src/SynapProvider.tsx","../src/trpc.ts","../src/hooks.ts"],"sourcesContent":["/**\n * @synap-core/react — React hooks and provider for Synap data pods.\n *\n * Quick start:\n * ```tsx\n * import { SynapProvider, useSynap } from \"@synap-core/react\";\n *\n * // 1. Wrap your app\n * <SynapProvider podUrl=\"...\" apiKey=\"...\" workspaceId=\"...\">\n * <App />\n * </SynapProvider>\n *\n * // 2. Use hooks anywhere inside\n * function MyComponent() {\n * const { entities } = useSynap();\n * const { data } = entities.list.useQuery({ limit: 20 });\n * }\n * ```\n */\n\nexport { SynapProvider, useSynapContext } from \"./SynapProvider\";\nexport type { SynapProviderProps } from \"./SynapProvider\";\n\n// Expose the raw tRPC hooks for advanced use (useSynap().entities.list.useQuery etc.)\nexport { trpc as useSynap } from \"./trpc\";\n\n// Thin ergonomic data hooks over the SDK + TanStack Query.\nexport {\n useEntity,\n useEntities,\n useLinks,\n useView,\n} from \"./hooks\";\nexport type {\n UseEntityData,\n UseEntitiesData,\n UseLinksData,\n UseViewData,\n} from \"./hooks\";\n\n// Re-export type helpers\nexport type { AppRouter } from \"@synap-core/api-types\";\nexport type { RouterInputs, RouterOutputs } from \"./types\";\n","/**\n * SynapProvider — wraps your React app with tRPC + TanStack Query\n * configured for a Synap data pod.\n *\n * Usage:\n * ```tsx\n * import { SynapProvider } from \"@synap-core/react\";\n *\n * function App() {\n * return (\n * <SynapProvider\n * podUrl=\"https://pod.example.com\"\n * apiKey=\"sk_live_...\"\n * workspaceId=\"ws_...\"\n * >\n * <YourApp />\n * </SynapProvider>\n * );\n * }\n * ```\n */\n\nimport React, { useState, createContext, useContext, useMemo } from \"react\";\nimport { QueryClient, QueryClientProvider } from \"@tanstack/react-query\";\nimport { createSynapClient, type SynapClientOptions } from \"@synap-core/sdk\";\nimport { trpc } from \"./trpc\";\n\nexport interface SynapProviderProps extends SynapClientOptions {\n children: React.ReactNode;\n /**\n * Provide your own QueryClient to share it with an existing TanStack Query setup.\n */\n queryClient?: QueryClient;\n}\n\nconst SynapContext = createContext<{\n podUrl: string;\n workspaceId: string;\n} | null>(null);\n\n/**\n * Returns the current pod context. Must be called inside <SynapProvider>.\n */\nexport function useSynapContext() {\n const ctx = useContext(SynapContext);\n if (!ctx)\n throw new Error(\"useSynapContext must be called inside <SynapProvider>\");\n return ctx;\n}\n\nexport function SynapProvider({\n children,\n queryClient: externalQueryClient,\n ...clientOptions\n}: SynapProviderProps) {\n const { podUrl, sessionToken, apiKey, workspaceId } = clientOptions;\n\n const [queryClient] = useState(\n () =>\n externalQueryClient ??\n new QueryClient({\n defaultOptions: {\n queries: { staleTime: 30_000, retry: 1 },\n },\n })\n );\n\n // Delegate to the SDK so every option (sessionToken, onAuthError,\n // extraHeaders) is honoured — the provider owns no transport of its own.\n // Deps are deliberately the credential fields, not `clientOptions` itself:\n // that object is rebuilt on every render, so depending on it would recreate\n // the client (and drop all in-flight query state) on every render.\n const trpcClient = useMemo(\n () => createSynapClient(clientOptions),\n [podUrl, sessionToken, apiKey, workspaceId]\n );\n\n const ctx = useMemo(() => ({ podUrl, workspaceId }), [podUrl, workspaceId]);\n\n return (\n <SynapContext.Provider value={ctx}>\n <trpc.Provider client={trpcClient} queryClient={queryClient}>\n <QueryClientProvider client={queryClient}>\n {children}\n </QueryClientProvider>\n </trpc.Provider>\n </SynapContext.Provider>\n );\n}\n","import { createTRPCReact, type CreateTRPCReact } from \"@trpc/react-query\";\nimport type { AppRouter } from \"@synap-core/api-types\";\n\n/**\n * tRPC React hooks — use via `useSynap()` from the provider context.\n * Exported for advanced use cases (e.g. calling `trpc.useUtils()`).\n */\nexport const trpc: CreateTRPCReact<AppRouter, unknown> =\n createTRPCReact<AppRouter>();\n","/**\n * Thin, self-contained data hooks over the published Synap SDK + TanStack Query.\n *\n * These wrap the `trpc` react-query client (the same instance exposed as\n * `useSynap`) — they do NOT import the monorepo `@synap-core/hooks` (which\n * couples Zustand stores, Yjs, notifications and is unpublishable). Each hook is\n * a thin pass-through to a single tRPC procedure so an external React app gets\n * ergonomic entity/relation/view access with zero hand-written query code.\n *\n * Procedure paths and input shapes mirror the canonical pod router:\n * - entities.get { id, includeProfile? }\n * - entities.list { profileSlug?, workspaceId?, projectId?, limit? }\n * - relations.get { entityId, direction? }\n * - views.get { id }\n *\n * Each hook's `opts` is the *exact* TanStack-Query options type of its\n * underlying procedure (derived via `Parameters<...useQuery>[1]`), so passthrough\n * options like `enabled` / `staleTime` keep full type-safety against that\n * procedure's data + error shapes.\n */\n\nimport { trpc } from \"./trpc\";\nimport type { RouterInputs, RouterOutputs } from \"./types\";\n\n/** The TanStack-Query options accepted by a given `useQuery` procedure. */\ntype QueryOptionsOf<P extends { useQuery: (...args: never[]) => unknown }> =\n NonNullable<Parameters<P[\"useQuery\"]>[1]>;\n\n/** The result type returned by a given `useQuery` procedure. */\ntype QueryResultOf<P extends { useQuery: (...args: never[]) => unknown }> =\n ReturnType<P[\"useQuery\"]>;\n\n/** The `useMutation` options accepted by a given mutation procedure. */\ntype MutationOptionsOf<\n P extends { useMutation: (...args: never[]) => unknown },\n> = NonNullable<Parameters<P[\"useMutation\"]>[0]>;\n\n/** The result type returned by a given `useMutation` procedure. */\ntype MutationResultOf<\n P extends { useMutation: (...args: never[]) => unknown },\n> = ReturnType<P[\"useMutation\"]>;\n\n/**\n * Fetch a single entity by id.\n *\n * @param id - Entity id.\n * @param opts - `{ includeProfile?, ...tanstackQueryOptions }`.\n */\nexport function useEntity(\n id: string,\n opts: { includeProfile?: boolean } & QueryOptionsOf<\n typeof trpc.entities.get\n > = {},\n): QueryResultOf<typeof trpc.entities.get> {\n const { includeProfile, ...queryOptions } = opts;\n const input: RouterInputs[\"entities\"][\"get\"] = { id, includeProfile };\n return trpc.entities.get.useQuery(input, {\n enabled: !!id,\n ...queryOptions,\n });\n}\n\n/**\n * List entities, optionally filtered by profile / workspace / project.\n *\n * @param profileSlug - Restrict to a single profile (e.g. \"person\", \"note\"). Omit for all.\n * @param opts - `{ workspaceId?, projectId?, limit?, ...tanstackQueryOptions }`.\n */\nexport function useEntities(\n profileSlug?: string,\n opts: {\n workspaceId?: string;\n projectId?: string;\n limit?: number;\n } & QueryOptionsOf<typeof trpc.entities.list> = {},\n): QueryResultOf<typeof trpc.entities.list> {\n const { workspaceId, projectId, limit, ...queryOptions } = opts;\n const input: RouterInputs[\"entities\"][\"list\"] = {\n profileSlug,\n workspaceId,\n projectId,\n limit,\n };\n return trpc.entities.list.useQuery(input, queryOptions);\n}\n\n/**\n * Fetch the relations/graph edges for an entity (both directions by default).\n *\n * @param entityId - The entity whose links to fetch.\n * @param opts - `{ direction?, ...tanstackQueryOptions }`.\n */\nexport function useLinks(\n entityId: string,\n opts: {\n direction?: RouterInputs[\"relations\"][\"get\"][\"direction\"];\n } & QueryOptionsOf<typeof trpc.relations.get> = {},\n): QueryResultOf<typeof trpc.relations.get> {\n const { direction = \"both\", ...queryOptions } = opts;\n const input: RouterInputs[\"relations\"][\"get\"] = { entityId, direction };\n return trpc.relations.get.useQuery(input, {\n enabled: !!entityId,\n ...queryOptions,\n });\n}\n\n/**\n * Fetch a view definition (config + query) by id.\n *\n * @param viewId - The view id.\n * @param opts - Passthrough TanStack Query options.\n */\nexport function useView(\n viewId: string,\n opts: QueryOptionsOf<typeof trpc.views.get> = {},\n): QueryResultOf<typeof trpc.views.get> {\n const input: RouterInputs[\"views\"][\"get\"] = { id: viewId };\n return trpc.views.get.useQuery(input, {\n enabled: !!viewId,\n ...opts,\n });\n}\n\n// NOTE: useTemplateCatalog / useInstallTemplate were removed — they referenced\n// tRPC procedures (workspaces.listInstallableTemplates / installFromCatalog) that\n// no longer exist in @synap-core/api-types, so they broke the dts build and could\n// never work. Re-add them here only once those procedures are back in api-types.\n\n/** Output type helpers for consumers that want to type derived state. */\nexport type UseEntityData = RouterOutputs[\"entities\"][\"get\"];\nexport type UseEntitiesData = RouterOutputs[\"entities\"][\"list\"];\nexport type UseLinksData = RouterOutputs[\"relations\"][\"get\"];\nexport type UseViewData = RouterOutputs[\"views\"][\"get\"];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsBA,mBAAoE;AACpE,IAAAA,sBAAiD;AACjD,iBAA2D;;;ACxB3D,yBAAsD;AAO/C,IAAM,WACX,oCAA2B;;;AD0ErB;AA/CR,IAAM,mBAAe,4BAGX,IAAI;AAKP,SAAS,kBAAkB;AAChC,QAAM,UAAM,yBAAW,YAAY;AACnC,MAAI,CAAC;AACH,UAAM,IAAI,MAAM,uDAAuD;AACzE,SAAO;AACT;AAEO,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA,aAAa;AAAA,EACb,GAAG;AACL,GAAuB;AACrB,QAAM,EAAE,QAAQ,cAAc,QAAQ,YAAY,IAAI;AAEtD,QAAM,CAAC,WAAW,QAAI;AAAA,IACpB,MACE,uBACA,IAAI,gCAAY;AAAA,MACd,gBAAgB;AAAA,QACd,SAAS,EAAE,WAAW,KAAQ,OAAO,EAAE;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACL;AAOA,QAAM,iBAAa;AAAA,IACjB,UAAM,8BAAkB,aAAa;AAAA,IACrC,CAAC,QAAQ,cAAc,QAAQ,WAAW;AAAA,EAC5C;AAEA,QAAM,UAAM,sBAAQ,OAAO,EAAE,QAAQ,YAAY,IAAI,CAAC,QAAQ,WAAW,CAAC;AAE1E,SACE,4CAAC,aAAa,UAAb,EAAsB,OAAO,KAC5B,sDAAC,KAAK,UAAL,EAAc,QAAQ,YAAY,aACjC,sDAAC,2CAAoB,QAAQ,aAC1B,UACH,GACF,GACF;AAEJ;;;AExCO,SAAS,UACd,IACA,OAEI,CAAC,GACoC;AACzC,QAAM,EAAE,gBAAgB,GAAG,aAAa,IAAI;AAC5C,QAAM,QAAyC,EAAE,IAAI,eAAe;AACpE,SAAO,KAAK,SAAS,IAAI,SAAS,OAAO;AAAA,IACvC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;AAQO,SAAS,YACd,aACA,OAIgD,CAAC,GACP;AAC1C,QAAM,EAAE,aAAa,WAAW,OAAO,GAAG,aAAa,IAAI;AAC3D,QAAM,QAA0C;AAAA,IAC9C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACA,SAAO,KAAK,SAAS,KAAK,SAAS,OAAO,YAAY;AACxD;AAQO,SAAS,SACd,UACA,OAEgD,CAAC,GACP;AAC1C,QAAM,EAAE,YAAY,QAAQ,GAAG,aAAa,IAAI;AAChD,QAAM,QAA0C,EAAE,UAAU,UAAU;AACtE,SAAO,KAAK,UAAU,IAAI,SAAS,OAAO;AAAA,IACxC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;AAQO,SAAS,QACd,QACA,OAA8C,CAAC,GACT;AACtC,QAAM,QAAsC,EAAE,IAAI,OAAO;AACzD,SAAO,KAAK,MAAM,IAAI,SAAS,OAAO;AAAA,IACpC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;","names":["import_react_query"]}
@@ -0,0 +1,122 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import React from 'react';
3
+ import { QueryClient } from '@tanstack/react-query';
4
+ import { SynapClientOptions } from '@synap-core/sdk';
5
+ import { CreateTRPCReact } from '@trpc/react-query';
6
+ import { AppRouter } from '@synap-core/api-types';
7
+ export { AppRouter } from '@synap-core/api-types';
8
+ import { inferRouterInputs, inferRouterOutputs } from '@trpc/server';
9
+
10
+ interface SynapProviderProps extends SynapClientOptions {
11
+ children: React.ReactNode;
12
+ /**
13
+ * Provide your own QueryClient to share it with an existing TanStack Query setup.
14
+ */
15
+ queryClient?: QueryClient;
16
+ }
17
+ /**
18
+ * Returns the current pod context. Must be called inside <SynapProvider>.
19
+ */
20
+ declare function useSynapContext(): {
21
+ podUrl: string;
22
+ workspaceId: string;
23
+ };
24
+ declare function SynapProvider({ children, queryClient: externalQueryClient, ...clientOptions }: SynapProviderProps): react_jsx_runtime.JSX.Element;
25
+
26
+ /**
27
+ * tRPC React hooks — use via `useSynap()` from the provider context.
28
+ * Exported for advanced use cases (e.g. calling `trpc.useUtils()`).
29
+ */
30
+ declare const trpc: CreateTRPCReact<AppRouter, unknown>;
31
+
32
+ /**
33
+ * Infer input types from any tRPC procedure.
34
+ *
35
+ * @example
36
+ * ```typescript
37
+ * type CreateEntityInput = RouterInputs["entities"]["create"];
38
+ * ```
39
+ */
40
+ type RouterInputs = inferRouterInputs<AppRouter>;
41
+ /**
42
+ * Infer output types from any tRPC procedure.
43
+ *
44
+ * @example
45
+ * ```typescript
46
+ * type Entity = RouterOutputs["entities"]["list"]["entities"][0];
47
+ * ```
48
+ */
49
+ type RouterOutputs = inferRouterOutputs<AppRouter>;
50
+
51
+ /**
52
+ * Thin, self-contained data hooks over the published Synap SDK + TanStack Query.
53
+ *
54
+ * These wrap the `trpc` react-query client (the same instance exposed as
55
+ * `useSynap`) — they do NOT import the monorepo `@synap-core/hooks` (which
56
+ * couples Zustand stores, Yjs, notifications and is unpublishable). Each hook is
57
+ * a thin pass-through to a single tRPC procedure so an external React app gets
58
+ * ergonomic entity/relation/view access with zero hand-written query code.
59
+ *
60
+ * Procedure paths and input shapes mirror the canonical pod router:
61
+ * - entities.get { id, includeProfile? }
62
+ * - entities.list { profileSlug?, workspaceId?, projectId?, limit? }
63
+ * - relations.get { entityId, direction? }
64
+ * - views.get { id }
65
+ *
66
+ * Each hook's `opts` is the *exact* TanStack-Query options type of its
67
+ * underlying procedure (derived via `Parameters<...useQuery>[1]`), so passthrough
68
+ * options like `enabled` / `staleTime` keep full type-safety against that
69
+ * procedure's data + error shapes.
70
+ */
71
+
72
+ /** The TanStack-Query options accepted by a given `useQuery` procedure. */
73
+ type QueryOptionsOf<P extends {
74
+ useQuery: (...args: never[]) => unknown;
75
+ }> = NonNullable<Parameters<P["useQuery"]>[1]>;
76
+ /** The result type returned by a given `useQuery` procedure. */
77
+ type QueryResultOf<P extends {
78
+ useQuery: (...args: never[]) => unknown;
79
+ }> = ReturnType<P["useQuery"]>;
80
+ /**
81
+ * Fetch a single entity by id.
82
+ *
83
+ * @param id - Entity id.
84
+ * @param opts - `{ includeProfile?, ...tanstackQueryOptions }`.
85
+ */
86
+ declare function useEntity(id: string, opts?: {
87
+ includeProfile?: boolean;
88
+ } & QueryOptionsOf<typeof trpc.entities.get>): QueryResultOf<typeof trpc.entities.get>;
89
+ /**
90
+ * List entities, optionally filtered by profile / workspace / project.
91
+ *
92
+ * @param profileSlug - Restrict to a single profile (e.g. "person", "note"). Omit for all.
93
+ * @param opts - `{ workspaceId?, projectId?, limit?, ...tanstackQueryOptions }`.
94
+ */
95
+ declare function useEntities(profileSlug?: string, opts?: {
96
+ workspaceId?: string;
97
+ projectId?: string;
98
+ limit?: number;
99
+ } & QueryOptionsOf<typeof trpc.entities.list>): QueryResultOf<typeof trpc.entities.list>;
100
+ /**
101
+ * Fetch the relations/graph edges for an entity (both directions by default).
102
+ *
103
+ * @param entityId - The entity whose links to fetch.
104
+ * @param opts - `{ direction?, ...tanstackQueryOptions }`.
105
+ */
106
+ declare function useLinks(entityId: string, opts?: {
107
+ direction?: RouterInputs["relations"]["get"]["direction"];
108
+ } & QueryOptionsOf<typeof trpc.relations.get>): QueryResultOf<typeof trpc.relations.get>;
109
+ /**
110
+ * Fetch a view definition (config + query) by id.
111
+ *
112
+ * @param viewId - The view id.
113
+ * @param opts - Passthrough TanStack Query options.
114
+ */
115
+ declare function useView(viewId: string, opts?: QueryOptionsOf<typeof trpc.views.get>): QueryResultOf<typeof trpc.views.get>;
116
+ /** Output type helpers for consumers that want to type derived state. */
117
+ type UseEntityData = RouterOutputs["entities"]["get"];
118
+ type UseEntitiesData = RouterOutputs["entities"]["list"];
119
+ type UseLinksData = RouterOutputs["relations"]["get"];
120
+ type UseViewData = RouterOutputs["views"]["get"];
121
+
122
+ export { type RouterInputs, type RouterOutputs, SynapProvider, type SynapProviderProps, type UseEntitiesData, type UseEntityData, type UseLinksData, type UseViewData, useEntities, useEntity, useLinks, trpc as useSynap, useSynapContext, useView };
@@ -0,0 +1,122 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import React from 'react';
3
+ import { QueryClient } from '@tanstack/react-query';
4
+ import { SynapClientOptions } from '@synap-core/sdk';
5
+ import { CreateTRPCReact } from '@trpc/react-query';
6
+ import { AppRouter } from '@synap-core/api-types';
7
+ export { AppRouter } from '@synap-core/api-types';
8
+ import { inferRouterInputs, inferRouterOutputs } from '@trpc/server';
9
+
10
+ interface SynapProviderProps extends SynapClientOptions {
11
+ children: React.ReactNode;
12
+ /**
13
+ * Provide your own QueryClient to share it with an existing TanStack Query setup.
14
+ */
15
+ queryClient?: QueryClient;
16
+ }
17
+ /**
18
+ * Returns the current pod context. Must be called inside <SynapProvider>.
19
+ */
20
+ declare function useSynapContext(): {
21
+ podUrl: string;
22
+ workspaceId: string;
23
+ };
24
+ declare function SynapProvider({ children, queryClient: externalQueryClient, ...clientOptions }: SynapProviderProps): react_jsx_runtime.JSX.Element;
25
+
26
+ /**
27
+ * tRPC React hooks — use via `useSynap()` from the provider context.
28
+ * Exported for advanced use cases (e.g. calling `trpc.useUtils()`).
29
+ */
30
+ declare const trpc: CreateTRPCReact<AppRouter, unknown>;
31
+
32
+ /**
33
+ * Infer input types from any tRPC procedure.
34
+ *
35
+ * @example
36
+ * ```typescript
37
+ * type CreateEntityInput = RouterInputs["entities"]["create"];
38
+ * ```
39
+ */
40
+ type RouterInputs = inferRouterInputs<AppRouter>;
41
+ /**
42
+ * Infer output types from any tRPC procedure.
43
+ *
44
+ * @example
45
+ * ```typescript
46
+ * type Entity = RouterOutputs["entities"]["list"]["entities"][0];
47
+ * ```
48
+ */
49
+ type RouterOutputs = inferRouterOutputs<AppRouter>;
50
+
51
+ /**
52
+ * Thin, self-contained data hooks over the published Synap SDK + TanStack Query.
53
+ *
54
+ * These wrap the `trpc` react-query client (the same instance exposed as
55
+ * `useSynap`) — they do NOT import the monorepo `@synap-core/hooks` (which
56
+ * couples Zustand stores, Yjs, notifications and is unpublishable). Each hook is
57
+ * a thin pass-through to a single tRPC procedure so an external React app gets
58
+ * ergonomic entity/relation/view access with zero hand-written query code.
59
+ *
60
+ * Procedure paths and input shapes mirror the canonical pod router:
61
+ * - entities.get { id, includeProfile? }
62
+ * - entities.list { profileSlug?, workspaceId?, projectId?, limit? }
63
+ * - relations.get { entityId, direction? }
64
+ * - views.get { id }
65
+ *
66
+ * Each hook's `opts` is the *exact* TanStack-Query options type of its
67
+ * underlying procedure (derived via `Parameters<...useQuery>[1]`), so passthrough
68
+ * options like `enabled` / `staleTime` keep full type-safety against that
69
+ * procedure's data + error shapes.
70
+ */
71
+
72
+ /** The TanStack-Query options accepted by a given `useQuery` procedure. */
73
+ type QueryOptionsOf<P extends {
74
+ useQuery: (...args: never[]) => unknown;
75
+ }> = NonNullable<Parameters<P["useQuery"]>[1]>;
76
+ /** The result type returned by a given `useQuery` procedure. */
77
+ type QueryResultOf<P extends {
78
+ useQuery: (...args: never[]) => unknown;
79
+ }> = ReturnType<P["useQuery"]>;
80
+ /**
81
+ * Fetch a single entity by id.
82
+ *
83
+ * @param id - Entity id.
84
+ * @param opts - `{ includeProfile?, ...tanstackQueryOptions }`.
85
+ */
86
+ declare function useEntity(id: string, opts?: {
87
+ includeProfile?: boolean;
88
+ } & QueryOptionsOf<typeof trpc.entities.get>): QueryResultOf<typeof trpc.entities.get>;
89
+ /**
90
+ * List entities, optionally filtered by profile / workspace / project.
91
+ *
92
+ * @param profileSlug - Restrict to a single profile (e.g. "person", "note"). Omit for all.
93
+ * @param opts - `{ workspaceId?, projectId?, limit?, ...tanstackQueryOptions }`.
94
+ */
95
+ declare function useEntities(profileSlug?: string, opts?: {
96
+ workspaceId?: string;
97
+ projectId?: string;
98
+ limit?: number;
99
+ } & QueryOptionsOf<typeof trpc.entities.list>): QueryResultOf<typeof trpc.entities.list>;
100
+ /**
101
+ * Fetch the relations/graph edges for an entity (both directions by default).
102
+ *
103
+ * @param entityId - The entity whose links to fetch.
104
+ * @param opts - `{ direction?, ...tanstackQueryOptions }`.
105
+ */
106
+ declare function useLinks(entityId: string, opts?: {
107
+ direction?: RouterInputs["relations"]["get"]["direction"];
108
+ } & QueryOptionsOf<typeof trpc.relations.get>): QueryResultOf<typeof trpc.relations.get>;
109
+ /**
110
+ * Fetch a view definition (config + query) by id.
111
+ *
112
+ * @param viewId - The view id.
113
+ * @param opts - Passthrough TanStack Query options.
114
+ */
115
+ declare function useView(viewId: string, opts?: QueryOptionsOf<typeof trpc.views.get>): QueryResultOf<typeof trpc.views.get>;
116
+ /** Output type helpers for consumers that want to type derived state. */
117
+ type UseEntityData = RouterOutputs["entities"]["get"];
118
+ type UseEntitiesData = RouterOutputs["entities"]["list"];
119
+ type UseLinksData = RouterOutputs["relations"]["get"];
120
+ type UseViewData = RouterOutputs["views"]["get"];
121
+
122
+ export { type RouterInputs, type RouterOutputs, SynapProvider, type SynapProviderProps, type UseEntitiesData, type UseEntityData, type UseLinksData, type UseViewData, useEntities, useEntity, useLinks, trpc as useSynap, useSynapContext, useView };
package/dist/index.js ADDED
@@ -0,0 +1,83 @@
1
+ // src/SynapProvider.tsx
2
+ import { useState, createContext, useContext, useMemo } from "react";
3
+ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
4
+ import { createSynapClient } from "@synap-core/sdk";
5
+
6
+ // src/trpc.ts
7
+ import { createTRPCReact } from "@trpc/react-query";
8
+ var trpc = createTRPCReact();
9
+
10
+ // src/SynapProvider.tsx
11
+ import { jsx } from "react/jsx-runtime";
12
+ var SynapContext = createContext(null);
13
+ function useSynapContext() {
14
+ const ctx = useContext(SynapContext);
15
+ if (!ctx)
16
+ throw new Error("useSynapContext must be called inside <SynapProvider>");
17
+ return ctx;
18
+ }
19
+ function SynapProvider({
20
+ children,
21
+ queryClient: externalQueryClient,
22
+ ...clientOptions
23
+ }) {
24
+ const { podUrl, sessionToken, apiKey, workspaceId } = clientOptions;
25
+ const [queryClient] = useState(
26
+ () => externalQueryClient ?? new QueryClient({
27
+ defaultOptions: {
28
+ queries: { staleTime: 3e4, retry: 1 }
29
+ }
30
+ })
31
+ );
32
+ const trpcClient = useMemo(
33
+ () => createSynapClient(clientOptions),
34
+ [podUrl, sessionToken, apiKey, workspaceId]
35
+ );
36
+ const ctx = useMemo(() => ({ podUrl, workspaceId }), [podUrl, workspaceId]);
37
+ return /* @__PURE__ */ jsx(SynapContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(trpc.Provider, { client: trpcClient, queryClient, children: /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children }) }) });
38
+ }
39
+
40
+ // src/hooks.ts
41
+ function useEntity(id, opts = {}) {
42
+ const { includeProfile, ...queryOptions } = opts;
43
+ const input = { id, includeProfile };
44
+ return trpc.entities.get.useQuery(input, {
45
+ enabled: !!id,
46
+ ...queryOptions
47
+ });
48
+ }
49
+ function useEntities(profileSlug, opts = {}) {
50
+ const { workspaceId, projectId, limit, ...queryOptions } = opts;
51
+ const input = {
52
+ profileSlug,
53
+ workspaceId,
54
+ projectId,
55
+ limit
56
+ };
57
+ return trpc.entities.list.useQuery(input, queryOptions);
58
+ }
59
+ function useLinks(entityId, opts = {}) {
60
+ const { direction = "both", ...queryOptions } = opts;
61
+ const input = { entityId, direction };
62
+ return trpc.relations.get.useQuery(input, {
63
+ enabled: !!entityId,
64
+ ...queryOptions
65
+ });
66
+ }
67
+ function useView(viewId, opts = {}) {
68
+ const input = { id: viewId };
69
+ return trpc.views.get.useQuery(input, {
70
+ enabled: !!viewId,
71
+ ...opts
72
+ });
73
+ }
74
+ export {
75
+ SynapProvider,
76
+ useEntities,
77
+ useEntity,
78
+ useLinks,
79
+ trpc as useSynap,
80
+ useSynapContext,
81
+ useView
82
+ };
83
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/SynapProvider.tsx","../src/trpc.ts","../src/hooks.ts"],"sourcesContent":["/**\n * SynapProvider — wraps your React app with tRPC + TanStack Query\n * configured for a Synap data pod.\n *\n * Usage:\n * ```tsx\n * import { SynapProvider } from \"@synap-core/react\";\n *\n * function App() {\n * return (\n * <SynapProvider\n * podUrl=\"https://pod.example.com\"\n * apiKey=\"sk_live_...\"\n * workspaceId=\"ws_...\"\n * >\n * <YourApp />\n * </SynapProvider>\n * );\n * }\n * ```\n */\n\nimport React, { useState, createContext, useContext, useMemo } from \"react\";\nimport { QueryClient, QueryClientProvider } from \"@tanstack/react-query\";\nimport { createSynapClient, type SynapClientOptions } from \"@synap-core/sdk\";\nimport { trpc } from \"./trpc\";\n\nexport interface SynapProviderProps extends SynapClientOptions {\n children: React.ReactNode;\n /**\n * Provide your own QueryClient to share it with an existing TanStack Query setup.\n */\n queryClient?: QueryClient;\n}\n\nconst SynapContext = createContext<{\n podUrl: string;\n workspaceId: string;\n} | null>(null);\n\n/**\n * Returns the current pod context. Must be called inside <SynapProvider>.\n */\nexport function useSynapContext() {\n const ctx = useContext(SynapContext);\n if (!ctx)\n throw new Error(\"useSynapContext must be called inside <SynapProvider>\");\n return ctx;\n}\n\nexport function SynapProvider({\n children,\n queryClient: externalQueryClient,\n ...clientOptions\n}: SynapProviderProps) {\n const { podUrl, sessionToken, apiKey, workspaceId } = clientOptions;\n\n const [queryClient] = useState(\n () =>\n externalQueryClient ??\n new QueryClient({\n defaultOptions: {\n queries: { staleTime: 30_000, retry: 1 },\n },\n })\n );\n\n // Delegate to the SDK so every option (sessionToken, onAuthError,\n // extraHeaders) is honoured — the provider owns no transport of its own.\n // Deps are deliberately the credential fields, not `clientOptions` itself:\n // that object is rebuilt on every render, so depending on it would recreate\n // the client (and drop all in-flight query state) on every render.\n const trpcClient = useMemo(\n () => createSynapClient(clientOptions),\n [podUrl, sessionToken, apiKey, workspaceId]\n );\n\n const ctx = useMemo(() => ({ podUrl, workspaceId }), [podUrl, workspaceId]);\n\n return (\n <SynapContext.Provider value={ctx}>\n <trpc.Provider client={trpcClient} queryClient={queryClient}>\n <QueryClientProvider client={queryClient}>\n {children}\n </QueryClientProvider>\n </trpc.Provider>\n </SynapContext.Provider>\n );\n}\n","import { createTRPCReact, type CreateTRPCReact } from \"@trpc/react-query\";\nimport type { AppRouter } from \"@synap-core/api-types\";\n\n/**\n * tRPC React hooks — use via `useSynap()` from the provider context.\n * Exported for advanced use cases (e.g. calling `trpc.useUtils()`).\n */\nexport const trpc: CreateTRPCReact<AppRouter, unknown> =\n createTRPCReact<AppRouter>();\n","/**\n * Thin, self-contained data hooks over the published Synap SDK + TanStack Query.\n *\n * These wrap the `trpc` react-query client (the same instance exposed as\n * `useSynap`) — they do NOT import the monorepo `@synap-core/hooks` (which\n * couples Zustand stores, Yjs, notifications and is unpublishable). Each hook is\n * a thin pass-through to a single tRPC procedure so an external React app gets\n * ergonomic entity/relation/view access with zero hand-written query code.\n *\n * Procedure paths and input shapes mirror the canonical pod router:\n * - entities.get { id, includeProfile? }\n * - entities.list { profileSlug?, workspaceId?, projectId?, limit? }\n * - relations.get { entityId, direction? }\n * - views.get { id }\n *\n * Each hook's `opts` is the *exact* TanStack-Query options type of its\n * underlying procedure (derived via `Parameters<...useQuery>[1]`), so passthrough\n * options like `enabled` / `staleTime` keep full type-safety against that\n * procedure's data + error shapes.\n */\n\nimport { trpc } from \"./trpc\";\nimport type { RouterInputs, RouterOutputs } from \"./types\";\n\n/** The TanStack-Query options accepted by a given `useQuery` procedure. */\ntype QueryOptionsOf<P extends { useQuery: (...args: never[]) => unknown }> =\n NonNullable<Parameters<P[\"useQuery\"]>[1]>;\n\n/** The result type returned by a given `useQuery` procedure. */\ntype QueryResultOf<P extends { useQuery: (...args: never[]) => unknown }> =\n ReturnType<P[\"useQuery\"]>;\n\n/** The `useMutation` options accepted by a given mutation procedure. */\ntype MutationOptionsOf<\n P extends { useMutation: (...args: never[]) => unknown },\n> = NonNullable<Parameters<P[\"useMutation\"]>[0]>;\n\n/** The result type returned by a given `useMutation` procedure. */\ntype MutationResultOf<\n P extends { useMutation: (...args: never[]) => unknown },\n> = ReturnType<P[\"useMutation\"]>;\n\n/**\n * Fetch a single entity by id.\n *\n * @param id - Entity id.\n * @param opts - `{ includeProfile?, ...tanstackQueryOptions }`.\n */\nexport function useEntity(\n id: string,\n opts: { includeProfile?: boolean } & QueryOptionsOf<\n typeof trpc.entities.get\n > = {},\n): QueryResultOf<typeof trpc.entities.get> {\n const { includeProfile, ...queryOptions } = opts;\n const input: RouterInputs[\"entities\"][\"get\"] = { id, includeProfile };\n return trpc.entities.get.useQuery(input, {\n enabled: !!id,\n ...queryOptions,\n });\n}\n\n/**\n * List entities, optionally filtered by profile / workspace / project.\n *\n * @param profileSlug - Restrict to a single profile (e.g. \"person\", \"note\"). Omit for all.\n * @param opts - `{ workspaceId?, projectId?, limit?, ...tanstackQueryOptions }`.\n */\nexport function useEntities(\n profileSlug?: string,\n opts: {\n workspaceId?: string;\n projectId?: string;\n limit?: number;\n } & QueryOptionsOf<typeof trpc.entities.list> = {},\n): QueryResultOf<typeof trpc.entities.list> {\n const { workspaceId, projectId, limit, ...queryOptions } = opts;\n const input: RouterInputs[\"entities\"][\"list\"] = {\n profileSlug,\n workspaceId,\n projectId,\n limit,\n };\n return trpc.entities.list.useQuery(input, queryOptions);\n}\n\n/**\n * Fetch the relations/graph edges for an entity (both directions by default).\n *\n * @param entityId - The entity whose links to fetch.\n * @param opts - `{ direction?, ...tanstackQueryOptions }`.\n */\nexport function useLinks(\n entityId: string,\n opts: {\n direction?: RouterInputs[\"relations\"][\"get\"][\"direction\"];\n } & QueryOptionsOf<typeof trpc.relations.get> = {},\n): QueryResultOf<typeof trpc.relations.get> {\n const { direction = \"both\", ...queryOptions } = opts;\n const input: RouterInputs[\"relations\"][\"get\"] = { entityId, direction };\n return trpc.relations.get.useQuery(input, {\n enabled: !!entityId,\n ...queryOptions,\n });\n}\n\n/**\n * Fetch a view definition (config + query) by id.\n *\n * @param viewId - The view id.\n * @param opts - Passthrough TanStack Query options.\n */\nexport function useView(\n viewId: string,\n opts: QueryOptionsOf<typeof trpc.views.get> = {},\n): QueryResultOf<typeof trpc.views.get> {\n const input: RouterInputs[\"views\"][\"get\"] = { id: viewId };\n return trpc.views.get.useQuery(input, {\n enabled: !!viewId,\n ...opts,\n });\n}\n\n// NOTE: useTemplateCatalog / useInstallTemplate were removed — they referenced\n// tRPC procedures (workspaces.listInstallableTemplates / installFromCatalog) that\n// no longer exist in @synap-core/api-types, so they broke the dts build and could\n// never work. Re-add them here only once those procedures are back in api-types.\n\n/** Output type helpers for consumers that want to type derived state. */\nexport type UseEntityData = RouterOutputs[\"entities\"][\"get\"];\nexport type UseEntitiesData = RouterOutputs[\"entities\"][\"list\"];\nexport type UseLinksData = RouterOutputs[\"relations\"][\"get\"];\nexport type UseViewData = RouterOutputs[\"views\"][\"get\"];\n"],"mappings":";AAsBA,SAAgB,UAAU,eAAe,YAAY,eAAe;AACpE,SAAS,aAAa,2BAA2B;AACjD,SAAS,yBAAkD;;;ACxB3D,SAAS,uBAA6C;AAO/C,IAAM,OACX,gBAA2B;;;AD0ErB;AA/CR,IAAM,eAAe,cAGX,IAAI;AAKP,SAAS,kBAAkB;AAChC,QAAM,MAAM,WAAW,YAAY;AACnC,MAAI,CAAC;AACH,UAAM,IAAI,MAAM,uDAAuD;AACzE,SAAO;AACT;AAEO,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA,aAAa;AAAA,EACb,GAAG;AACL,GAAuB;AACrB,QAAM,EAAE,QAAQ,cAAc,QAAQ,YAAY,IAAI;AAEtD,QAAM,CAAC,WAAW,IAAI;AAAA,IACpB,MACE,uBACA,IAAI,YAAY;AAAA,MACd,gBAAgB;AAAA,QACd,SAAS,EAAE,WAAW,KAAQ,OAAO,EAAE;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACL;AAOA,QAAM,aAAa;AAAA,IACjB,MAAM,kBAAkB,aAAa;AAAA,IACrC,CAAC,QAAQ,cAAc,QAAQ,WAAW;AAAA,EAC5C;AAEA,QAAM,MAAM,QAAQ,OAAO,EAAE,QAAQ,YAAY,IAAI,CAAC,QAAQ,WAAW,CAAC;AAE1E,SACE,oBAAC,aAAa,UAAb,EAAsB,OAAO,KAC5B,8BAAC,KAAK,UAAL,EAAc,QAAQ,YAAY,aACjC,8BAAC,uBAAoB,QAAQ,aAC1B,UACH,GACF,GACF;AAEJ;;;AExCO,SAAS,UACd,IACA,OAEI,CAAC,GACoC;AACzC,QAAM,EAAE,gBAAgB,GAAG,aAAa,IAAI;AAC5C,QAAM,QAAyC,EAAE,IAAI,eAAe;AACpE,SAAO,KAAK,SAAS,IAAI,SAAS,OAAO;AAAA,IACvC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;AAQO,SAAS,YACd,aACA,OAIgD,CAAC,GACP;AAC1C,QAAM,EAAE,aAAa,WAAW,OAAO,GAAG,aAAa,IAAI;AAC3D,QAAM,QAA0C;AAAA,IAC9C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACA,SAAO,KAAK,SAAS,KAAK,SAAS,OAAO,YAAY;AACxD;AAQO,SAAS,SACd,UACA,OAEgD,CAAC,GACP;AAC1C,QAAM,EAAE,YAAY,QAAQ,GAAG,aAAa,IAAI;AAChD,QAAM,QAA0C,EAAE,UAAU,UAAU;AACtE,SAAO,KAAK,UAAU,IAAI,SAAS,OAAO;AAAA,IACxC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;AAQO,SAAS,QACd,QACA,OAA8C,CAAC,GACT;AACtC,QAAM,QAAsC,EAAE,IAAI,OAAO;AACzD,SAAO,KAAK,MAAM,IAAI,SAAS,OAAO;AAAA,IACpC,SAAS,CAAC,CAAC;AAAA,IACX,GAAG;AAAA,EACL,CAAC;AACH;","names":[]}
package/package.json ADDED
@@ -0,0 +1,57 @@
1
+ {
2
+ "name": "@synap-core/react",
3
+ "version": "1.0.0",
4
+ "description": "React hooks and provider for Synap data pods",
5
+ "type": "module",
6
+ "main": "./dist/index.cjs",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js",
13
+ "require": "./dist/index.cjs"
14
+ }
15
+ },
16
+ "files": [
17
+ "dist",
18
+ "src"
19
+ ],
20
+ "keywords": [
21
+ "synap",
22
+ "react",
23
+ "trpc",
24
+ "data-pod",
25
+ "hooks"
26
+ ],
27
+ "dependencies": {
28
+ "@synap-core/api-types": "^1.23.3",
29
+ "@tanstack/react-query": "^5.62.10",
30
+ "@trpc/client": "^11.10.0",
31
+ "@trpc/react-query": "^11.10.0",
32
+ "@trpc/server": "^11.10.0",
33
+ "superjson": "^2.2.6",
34
+ "@synap-core/sdk": "1.0.0"
35
+ },
36
+ "peerDependencies": {
37
+ "react": "^18.0.0 || ^19.0.0"
38
+ },
39
+ "devDependencies": {
40
+ "@types/react": "^19.0.0",
41
+ "tsup": "^8.3.5",
42
+ "typescript": "^5.7.3"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
46
+ },
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "https://github.com/synap/synap-app.git",
50
+ "directory": "packages/react"
51
+ },
52
+ "license": "MIT",
53
+ "scripts": {
54
+ "build": "tsup",
55
+ "typecheck": "tsc --noEmit"
56
+ }
57
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * SynapProvider — wraps your React app with tRPC + TanStack Query
3
+ * configured for a Synap data pod.
4
+ *
5
+ * Usage:
6
+ * ```tsx
7
+ * import { SynapProvider } from "@synap-core/react";
8
+ *
9
+ * function App() {
10
+ * return (
11
+ * <SynapProvider
12
+ * podUrl="https://pod.example.com"
13
+ * apiKey="sk_live_..."
14
+ * workspaceId="ws_..."
15
+ * >
16
+ * <YourApp />
17
+ * </SynapProvider>
18
+ * );
19
+ * }
20
+ * ```
21
+ */
22
+
23
+ import React, { useState, createContext, useContext, useMemo } from "react";
24
+ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
25
+ import { createSynapClient, type SynapClientOptions } from "@synap-core/sdk";
26
+ import { trpc } from "./trpc";
27
+
28
+ export interface SynapProviderProps extends SynapClientOptions {
29
+ children: React.ReactNode;
30
+ /**
31
+ * Provide your own QueryClient to share it with an existing TanStack Query setup.
32
+ */
33
+ queryClient?: QueryClient;
34
+ }
35
+
36
+ const SynapContext = createContext<{
37
+ podUrl: string;
38
+ workspaceId: string;
39
+ } | null>(null);
40
+
41
+ /**
42
+ * Returns the current pod context. Must be called inside <SynapProvider>.
43
+ */
44
+ export function useSynapContext() {
45
+ const ctx = useContext(SynapContext);
46
+ if (!ctx)
47
+ throw new Error("useSynapContext must be called inside <SynapProvider>");
48
+ return ctx;
49
+ }
50
+
51
+ export function SynapProvider({
52
+ children,
53
+ queryClient: externalQueryClient,
54
+ ...clientOptions
55
+ }: SynapProviderProps) {
56
+ const { podUrl, sessionToken, apiKey, workspaceId } = clientOptions;
57
+
58
+ const [queryClient] = useState(
59
+ () =>
60
+ externalQueryClient ??
61
+ new QueryClient({
62
+ defaultOptions: {
63
+ queries: { staleTime: 30_000, retry: 1 },
64
+ },
65
+ })
66
+ );
67
+
68
+ // Delegate to the SDK so every option (sessionToken, onAuthError,
69
+ // extraHeaders) is honoured — the provider owns no transport of its own.
70
+ // Deps are deliberately the credential fields, not `clientOptions` itself:
71
+ // that object is rebuilt on every render, so depending on it would recreate
72
+ // the client (and drop all in-flight query state) on every render.
73
+ const trpcClient = useMemo(
74
+ () => createSynapClient(clientOptions),
75
+ [podUrl, sessionToken, apiKey, workspaceId]
76
+ );
77
+
78
+ const ctx = useMemo(() => ({ podUrl, workspaceId }), [podUrl, workspaceId]);
79
+
80
+ return (
81
+ <SynapContext.Provider value={ctx}>
82
+ <trpc.Provider client={trpcClient} queryClient={queryClient}>
83
+ <QueryClientProvider client={queryClient}>
84
+ {children}
85
+ </QueryClientProvider>
86
+ </trpc.Provider>
87
+ </SynapContext.Provider>
88
+ );
89
+ }
package/src/hooks.ts ADDED
@@ -0,0 +1,133 @@
1
+ /**
2
+ * Thin, self-contained data hooks over the published Synap SDK + TanStack Query.
3
+ *
4
+ * These wrap the `trpc` react-query client (the same instance exposed as
5
+ * `useSynap`) — they do NOT import the monorepo `@synap-core/hooks` (which
6
+ * couples Zustand stores, Yjs, notifications and is unpublishable). Each hook is
7
+ * a thin pass-through to a single tRPC procedure so an external React app gets
8
+ * ergonomic entity/relation/view access with zero hand-written query code.
9
+ *
10
+ * Procedure paths and input shapes mirror the canonical pod router:
11
+ * - entities.get { id, includeProfile? }
12
+ * - entities.list { profileSlug?, workspaceId?, projectId?, limit? }
13
+ * - relations.get { entityId, direction? }
14
+ * - views.get { id }
15
+ *
16
+ * Each hook's `opts` is the *exact* TanStack-Query options type of its
17
+ * underlying procedure (derived via `Parameters<...useQuery>[1]`), so passthrough
18
+ * options like `enabled` / `staleTime` keep full type-safety against that
19
+ * procedure's data + error shapes.
20
+ */
21
+
22
+ import { trpc } from "./trpc";
23
+ import type { RouterInputs, RouterOutputs } from "./types";
24
+
25
+ /** The TanStack-Query options accepted by a given `useQuery` procedure. */
26
+ type QueryOptionsOf<P extends { useQuery: (...args: never[]) => unknown }> =
27
+ NonNullable<Parameters<P["useQuery"]>[1]>;
28
+
29
+ /** The result type returned by a given `useQuery` procedure. */
30
+ type QueryResultOf<P extends { useQuery: (...args: never[]) => unknown }> =
31
+ ReturnType<P["useQuery"]>;
32
+
33
+ /** The `useMutation` options accepted by a given mutation procedure. */
34
+ type MutationOptionsOf<
35
+ P extends { useMutation: (...args: never[]) => unknown },
36
+ > = NonNullable<Parameters<P["useMutation"]>[0]>;
37
+
38
+ /** The result type returned by a given `useMutation` procedure. */
39
+ type MutationResultOf<
40
+ P extends { useMutation: (...args: never[]) => unknown },
41
+ > = ReturnType<P["useMutation"]>;
42
+
43
+ /**
44
+ * Fetch a single entity by id.
45
+ *
46
+ * @param id - Entity id.
47
+ * @param opts - `{ includeProfile?, ...tanstackQueryOptions }`.
48
+ */
49
+ export function useEntity(
50
+ id: string,
51
+ opts: { includeProfile?: boolean } & QueryOptionsOf<
52
+ typeof trpc.entities.get
53
+ > = {},
54
+ ): QueryResultOf<typeof trpc.entities.get> {
55
+ const { includeProfile, ...queryOptions } = opts;
56
+ const input: RouterInputs["entities"]["get"] = { id, includeProfile };
57
+ return trpc.entities.get.useQuery(input, {
58
+ enabled: !!id,
59
+ ...queryOptions,
60
+ });
61
+ }
62
+
63
+ /**
64
+ * List entities, optionally filtered by profile / workspace / project.
65
+ *
66
+ * @param profileSlug - Restrict to a single profile (e.g. "person", "note"). Omit for all.
67
+ * @param opts - `{ workspaceId?, projectId?, limit?, ...tanstackQueryOptions }`.
68
+ */
69
+ export function useEntities(
70
+ profileSlug?: string,
71
+ opts: {
72
+ workspaceId?: string;
73
+ projectId?: string;
74
+ limit?: number;
75
+ } & QueryOptionsOf<typeof trpc.entities.list> = {},
76
+ ): QueryResultOf<typeof trpc.entities.list> {
77
+ const { workspaceId, projectId, limit, ...queryOptions } = opts;
78
+ const input: RouterInputs["entities"]["list"] = {
79
+ profileSlug,
80
+ workspaceId,
81
+ projectId,
82
+ limit,
83
+ };
84
+ return trpc.entities.list.useQuery(input, queryOptions);
85
+ }
86
+
87
+ /**
88
+ * Fetch the relations/graph edges for an entity (both directions by default).
89
+ *
90
+ * @param entityId - The entity whose links to fetch.
91
+ * @param opts - `{ direction?, ...tanstackQueryOptions }`.
92
+ */
93
+ export function useLinks(
94
+ entityId: string,
95
+ opts: {
96
+ direction?: RouterInputs["relations"]["get"]["direction"];
97
+ } & QueryOptionsOf<typeof trpc.relations.get> = {},
98
+ ): QueryResultOf<typeof trpc.relations.get> {
99
+ const { direction = "both", ...queryOptions } = opts;
100
+ const input: RouterInputs["relations"]["get"] = { entityId, direction };
101
+ return trpc.relations.get.useQuery(input, {
102
+ enabled: !!entityId,
103
+ ...queryOptions,
104
+ });
105
+ }
106
+
107
+ /**
108
+ * Fetch a view definition (config + query) by id.
109
+ *
110
+ * @param viewId - The view id.
111
+ * @param opts - Passthrough TanStack Query options.
112
+ */
113
+ export function useView(
114
+ viewId: string,
115
+ opts: QueryOptionsOf<typeof trpc.views.get> = {},
116
+ ): QueryResultOf<typeof trpc.views.get> {
117
+ const input: RouterInputs["views"]["get"] = { id: viewId };
118
+ return trpc.views.get.useQuery(input, {
119
+ enabled: !!viewId,
120
+ ...opts,
121
+ });
122
+ }
123
+
124
+ // NOTE: useTemplateCatalog / useInstallTemplate were removed — they referenced
125
+ // tRPC procedures (workspaces.listInstallableTemplates / installFromCatalog) that
126
+ // no longer exist in @synap-core/api-types, so they broke the dts build and could
127
+ // never work. Re-add them here only once those procedures are back in api-types.
128
+
129
+ /** Output type helpers for consumers that want to type derived state. */
130
+ export type UseEntityData = RouterOutputs["entities"]["get"];
131
+ export type UseEntitiesData = RouterOutputs["entities"]["list"];
132
+ export type UseLinksData = RouterOutputs["relations"]["get"];
133
+ export type UseViewData = RouterOutputs["views"]["get"];
package/src/index.ts ADDED
@@ -0,0 +1,43 @@
1
+ /**
2
+ * @synap-core/react — React hooks and provider for Synap data pods.
3
+ *
4
+ * Quick start:
5
+ * ```tsx
6
+ * import { SynapProvider, useSynap } from "@synap-core/react";
7
+ *
8
+ * // 1. Wrap your app
9
+ * <SynapProvider podUrl="..." apiKey="..." workspaceId="...">
10
+ * <App />
11
+ * </SynapProvider>
12
+ *
13
+ * // 2. Use hooks anywhere inside
14
+ * function MyComponent() {
15
+ * const { entities } = useSynap();
16
+ * const { data } = entities.list.useQuery({ limit: 20 });
17
+ * }
18
+ * ```
19
+ */
20
+
21
+ export { SynapProvider, useSynapContext } from "./SynapProvider";
22
+ export type { SynapProviderProps } from "./SynapProvider";
23
+
24
+ // Expose the raw tRPC hooks for advanced use (useSynap().entities.list.useQuery etc.)
25
+ export { trpc as useSynap } from "./trpc";
26
+
27
+ // Thin ergonomic data hooks over the SDK + TanStack Query.
28
+ export {
29
+ useEntity,
30
+ useEntities,
31
+ useLinks,
32
+ useView,
33
+ } from "./hooks";
34
+ export type {
35
+ UseEntityData,
36
+ UseEntitiesData,
37
+ UseLinksData,
38
+ UseViewData,
39
+ } from "./hooks";
40
+
41
+ // Re-export type helpers
42
+ export type { AppRouter } from "@synap-core/api-types";
43
+ export type { RouterInputs, RouterOutputs } from "./types";
package/src/trpc.ts ADDED
@@ -0,0 +1,9 @@
1
+ import { createTRPCReact, type CreateTRPCReact } from "@trpc/react-query";
2
+ import type { AppRouter } from "@synap-core/api-types";
3
+
4
+ /**
5
+ * tRPC React hooks — use via `useSynap()` from the provider context.
6
+ * Exported for advanced use cases (e.g. calling `trpc.useUtils()`).
7
+ */
8
+ export const trpc: CreateTRPCReact<AppRouter, unknown> =
9
+ createTRPCReact<AppRouter>();
package/src/types.ts ADDED
@@ -0,0 +1,22 @@
1
+ import type { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
2
+ import type { AppRouter } from "@synap-core/api-types";
3
+
4
+ /**
5
+ * Infer input types from any tRPC procedure.
6
+ *
7
+ * @example
8
+ * ```typescript
9
+ * type CreateEntityInput = RouterInputs["entities"]["create"];
10
+ * ```
11
+ */
12
+ export type RouterInputs = inferRouterInputs<AppRouter>;
13
+
14
+ /**
15
+ * Infer output types from any tRPC procedure.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * type Entity = RouterOutputs["entities"]["list"]["entities"][0];
20
+ * ```
21
+ */
22
+ export type RouterOutputs = inferRouterOutputs<AppRouter>;