@usegraft/sdk-react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @usegraft/sdk-react
+
+> The browser client: typed content reads and hooks over Graft's read-only content API.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+Every other Graft SDK reads on a server. This one reads in the browser, for the places a loader cannot help: a search box, a client-side editor preview, a widget on a page the server rendered an hour ago.
+
+## Install
+
+```bash
+npm i @usegraft/sdk-react
+```
+
+`react` is a peer dependency, 18 or 19.
+
+## Types do not cross the wire
+
+Your app imports its own `collections` from `graft.config.ts` at compile time, exactly as a server adapter does. The endpoint supplies data at runtime. Nothing is generated, nothing is fetched to be typed, and `getContent("docs", slug)` returns the document type your schema declares.
+
+```ts
+// src/graft.ts
+import { createGraft, createGraftHooks } from "@usegraft/sdk-react";
+import { collections } from "../graft.config";
+
+export const graft = createGraft({
+  endpoint: "https://cms.example.com/api/content/v1",
+  collections,
+});
+
+export const { GraftProvider, useGraft, useContent, useContentList, useContentSearch } =
+  createGraftHooks(graft);
+```
+
+The hooks come out of a factory rather than being importable directly, and that is what keeps the reads typed. A hook reading an untyped context could only promise `Document<AnyCollection>` — `data.title` would be `unknown` and a misspelled collection name would be a runtime surprise instead of a compile error. Binding the factory to your collections once buys typed reads everywhere.
+
+## Serve the endpoint
+
+`endpoint` points at a mount of Graft's read-only content API — what `graft serve` exposes at `/api/content/v1`, or your own mount of `createContentApiHandler` from [`@usegraft/content-api`](https://www.npmjs.com/package/@usegraft/content-api). It answers document reads and search, nothing else: no functions, no writes, no schema.
+
+An endpoint is pinned to one branch on the server side, which is why there is no `branch` option to pass with `endpoint`. Point at the preview deployment's endpoint to read a preview branch.
+
+## Read
+
+```tsx
+import { useContent, useContentSearch } from "../graft";
+
+function Doc({ slug }: { slug: string }) {
+  const { data, error, loading } = useContent("docs", slug);
+
+  if (loading) return <Spinner />;
+  if (error) return <Problem error={error} />;
+  if (!data) return <NotFound />;
+  return <article>{data.data.title}</article>;
+}
+```
+
+Each hook reports `{ data, error, loading, refresh }`. `data` answers the current arguments or it is `undefined`: changing the slug clears it rather than showing the previous document while the next one loads.
+
+`useContentList(collection, options?)` and `useContentSearch(collection, query, options?)` are the same shape over `listContent` and `searchContent`.
+
+## What this is not
+
+It is not a cache. There is no deduplication, no retry, no background refresh, no stale-while-revalidate — a read starts when its arguments change and reports one answer. Your app almost certainly has TanStack Query or SWR already, both of which do that properly, and `graft.getContent` is a plain async function that composes with either:
+
+```ts
+useQuery({
+  queryKey: ["docs", slug],
+  queryFn: () => graft.getContent("docs", slug),
+});
+```
+
+Shipping a worse copy of a query client inside an SDK is the wrong trade, so the hooks stay a binding and the caching stays yours.
+
+It is also not a server renderer. `useEffect` does not run during server rendering, so on the server these hooks report their loading state and nothing else. Content that has to be in the HTML belongs in a loader or a server adapter: [`@usegraft/sdk-next`](https://www.npmjs.com/package/@usegraft/sdk-next), [`sdk-astro`](https://www.npmjs.com/package/@usegraft/sdk-astro), [`sdk-sveltekit`](https://www.npmjs.com/package/@usegraft/sdk-sveltekit), [`sdk-react-router`](https://www.npmjs.com/package/@usegraft/sdk-react-router), [`sdk-tanstack-start`](https://www.npmjs.com/package/@usegraft/sdk-tanstack-start).
+
+## Point a subtree somewhere else
+
+`GraftProvider` is optional — the hooks fall back to the handle the factory was built with. Mount one to override it for a subtree: a preview branch's endpoint, or a fake in tests.
+
+```tsx
+<GraftProvider graft={previewGraft}>
+  <Preview />
+</GraftProvider>
+```
+
+## Without hooks
+
+`createGraft` is useful on its own. It returns `getContent` / `listContent` / `searchContent` and the underlying `client`, all typed the same way, for event handlers, a query client, or anywhere React is not involved.
+
+## Bring your own transport
+
+Pass `index` instead of `endpoint` to read through any `ContentIndexReader` — a configured `createContentApiReader`, a service-worker-backed reader, or a fake in a test.
+
+```ts
+import { createContentApiReader } from "@usegraft/sdk-react";
+
+export const graft = createGraft({
+  index: createContentApiReader({ endpoint, headers: { Authorization: `Bearer ${token}` } }),
+  collections,
+});
+```
+
+There is no `db` option, and no `graftRoute`. A database handle in a browser bundle is a database URL in a browser bundle, and mounting a request handler is a server's job.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/sdk-react/CHANGELOG.md)

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { AnyCollection, ReadOptions, Document, ListOptions, SearchOptions, SearchHit, GraftClient, ClientOptions } from '@usegraft/sdk-core';
+export { AnyCollection, ChangeSet, ClientOptions, Document, GraftClient, ListOptions, ReadOptions, SearchHit, SearchOptions, TAG_NAMESPACE, collectionTag, createClient, documentTag, tagsFor, tagsForChanges, toDocument } from '@usegraft/sdk-core';
+import { ReactNode, ReactElement } from 'react';
+export { ContentApiReaderOptions, createContentApiReader } from '@usegraft/content-api';
+
+interface GraftOptions<TCollections extends Record<string, AnyCollection>> extends Omit<ClientOptions<TCollections>, "db"> {
+    /** Content API base URL, e.g. `https://cms.example.com/api/content/v1`. */
+    endpoint?: string | URL;
+    /** Static headers sent with every read, such as `Authorization`. */
+    headers?: Record<string, string>;
+    /** Fetch implementation, for tests, instrumentation, or a non-browser runtime. */
+    fetch?: typeof globalThis.fetch;
+}
+interface Graft<TCollections extends Record<string, AnyCollection>> {
+    /** Typed getDocument. */
+    getContent<K extends keyof TCollections & string>(collection: K, slug: string, options?: ReadOptions): Promise<Document<TCollections[K]> | null>;
+    /** Typed listDocuments. */
+    listContent<K extends keyof TCollections & string>(collection: K, options?: ListOptions): Promise<Document<TCollections[K]>[]>;
+    /** Typed searchDocuments (full-text, best-ranked first). */
+    searchContent<K extends keyof TCollections & string>(collection: K, query: string, options?: SearchOptions): Promise<SearchHit<TCollections[K]>[]>;
+    /** The underlying sdk-core client, for anything the helpers don't cover. */
+    client: GraftClient<TCollections>;
+}
+/**
+ * Build the read handle. Give it your `collections` and the endpoint your
+ * content API is mounted at; reads are typed from the schema, not from the
+ * response.
+ */
+declare function createGraft<TCollections extends Record<string, AnyCollection>>(options: GraftOptions<TCollections>): Graft<TCollections>;
+
+/**
+ * React ergonomics over the read handle: a provider and three hooks that run
+ * the async reads and report their state.
+ *
+ * Deliberately not a cache. Every re-read starts from nothing and reports
+ * exactly one answer for the current arguments, because an SDK that invented
+ * its own stale-while-revalidate would be a worse copy of the query client the
+ * app already has. Wrap `graft.getContent` in TanStack Query or SWR when you
+ * want caching, retries, deduplication or background refresh — the handle is a
+ * plain async function and composes with either of them.
+ *
+ * Browser-side. `useEffect` does not run during server rendering, so on the
+ * server these hooks render their loading state and nothing else. Data that
+ * has to be in the HTML belongs in a loader or a server adapter
+ * (@usegraft/sdk-react-router, @usegraft/sdk-tanstack-start, and the rest).
+ *
+ * The hooks come out of a factory rather than being importable directly. That
+ * is what keeps the no-codegen contract: a hook reading an untyped context
+ * could only return `Document<AnyCollection>`, so `data.title` would be
+ * `unknown` and an unknown collection name would be a runtime surprise instead
+ * of a compile error. Binding the factory to your `collections` once is what
+ * buys typed reads everywhere the hooks are used.
+ */
+
+/** What a hook reports about the read it is running. */
+interface AsyncState<TData> {
+    /** The answer for the current arguments, or undefined until one arrives. */
+    data: TData | undefined;
+    /** Why the read failed, usually a GraftError. */
+    error: Error | undefined;
+    /** True while a read is in flight, the first one included. */
+    loading: boolean;
+    /** Run the read again. */
+    refresh: () => void;
+}
+interface GraftHooks<TCollections extends Record<string, AnyCollection>> {
+    /**
+     * Supplies the handle the hooks read. Optional — they fall back to the one
+     * the factory was built with. Use it to point a subtree somewhere else: a
+     * preview branch's endpoint, or a fake in tests.
+     */
+    GraftProvider: (props: {
+        graft: Graft<TCollections>;
+        children: ReactNode;
+    }) => ReactElement;
+    /** The handle in scope, for reads the hooks don't cover. */
+    useGraft: () => Graft<TCollections>;
+    /** One document, or null when the collection has no such slug. */
+    useContent: <K extends keyof TCollections & string>(collection: K, slug: string, options?: ReadOptions) => AsyncState<Document<TCollections[K]> | null>;
+    /** A collection, in index order. */
+    useContentList: <K extends keyof TCollections & string>(collection: K, options?: ListOptions) => AsyncState<Document<TCollections[K]>[]>;
+    /** Full-text search within one collection, best-ranked first. */
+    useContentSearch: <K extends keyof TCollections & string>(collection: K, query: string, options?: SearchOptions) => AsyncState<SearchHit<TCollections[K]>[]>;
+}
+/**
+ * Bind the provider and hooks to one handle, and to the collections that
+ * handle was built with.
+ *
+ * ```ts
+ * // src/graft.ts
+ * import { createGraft, createGraftHooks } from "@usegraft/sdk-react";
+ * import { collections } from "../graft.config";
+ *
+ * export const graft = createGraft({ endpoint: "/api/content/v1", collections });
+ * export const { GraftProvider, useContent, useContentList, useContentSearch } =
+ *   createGraftHooks(graft);
+ * ```
+ */
+declare function createGraftHooks<TCollections extends Record<string, AnyCollection>>(graft: Graft<TCollections>): GraftHooks<TCollections>;
+
+export { type AsyncState, type Graft, type GraftHooks, type GraftOptions, createGraft, createGraftHooks };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/graft.ts
+import { createContentApiReader } from "@usegraft/content-api";
+import { GraftError } from "@usegraft/contracts";
+import {
+  createClient
+} from "@usegraft/sdk-core";
+function readerFor(options) {
+  if (options.endpoint === void 0) {
+    if (options.index === void 0) {
+      throw new GraftError({
+        code: "CONFIG_INVALID",
+        message: "createGraft needs somewhere to read from: pass `endpoint` or `index`.",
+        fix: "Pass `endpoint` (the content API a `graft serve` mounts, e.g. https://cms.example.com/api/content/v1) or `index` (your own ContentIndexReader). There is no `db` option in the browser."
+      });
+    }
+    return options.index;
+  }
+  if (options.branch !== void 0) {
+    throw new GraftError({
+      code: "CONFIG_INVALID",
+      message: "`branch` cannot be combined with `endpoint`.",
+      fix: "Each content API endpoint serves exactly one branch, fixed by the server. Point `endpoint` at the branch's own deployment instead of asking for one here.",
+      details: { branch: options.branch, endpoint: options.endpoint.toString() }
+    });
+  }
+  return createContentApiReader({
+    endpoint: options.endpoint,
+    headers: options.headers,
+    fetch: options.fetch
+  });
+}
+function createGraft(options) {
+  const client = createClient({
+    index: readerFor(options),
+    collections: options.collections,
+    branch: options.branch
+  });
+  return {
+    client,
+    getContent: (collection, slug, opts) => client.getDocument(collection, slug, opts),
+    listContent: (collection, opts) => client.listDocuments(collection, opts),
+    searchContent: (collection, query, opts) => client.searchDocuments(collection, query, opts)
+  };
+}
+
+// src/hooks.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var PENDING = { data: void 0, error: void 0, loading: true };
+function asError(cause) {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+function useRead(read) {
+  const [attempt, setAttempt] = useState(0);
+  const [state, setState] = useState(PENDING);
+  useEffect(() => {
+    let live = true;
+    setState(PENDING);
+    read().then(
+      (data) => {
+        if (live) setState({ data, error: void 0, loading: false });
+      },
+      (cause) => {
+        if (live) setState({ data: void 0, error: asError(cause), loading: false });
+      }
+    );
+    return () => {
+      live = false;
+    };
+  }, [read, attempt]);
+  const refresh = useCallback(() => setAttempt((previous) => previous + 1), []);
+  return { ...state, refresh };
+}
+function createGraftHooks(graft) {
+  const GraftContext = createContext(graft);
+  function GraftProvider({
+    graft: value,
+    children
+  }) {
+    return /* @__PURE__ */ jsx(GraftContext.Provider, { value, children });
+  }
+  const useGraft = () => useContext(GraftContext);
+  return {
+    GraftProvider,
+    useGraft,
+    useContent(collection, slug, options) {
+      const handle = useGraft();
+      const branch = options?.branch;
+      const read = useCallback(
+        () => handle.getContent(collection, slug, { branch }),
+        [handle, collection, slug, branch]
+      );
+      return useRead(read);
+    },
+    useContentList(collection, options) {
+      const handle = useGraft();
+      const branch = options?.branch;
+      const limit = options?.limit;
+      const offset = options?.offset;
+      const read = useCallback(
+        () => handle.listContent(collection, { branch, limit, offset }),
+        [handle, collection, branch, limit, offset]
+      );
+      return useRead(read);
+    },
+    useContentSearch(collection, query, options) {
+      const handle = useGraft();
+      const branch = options?.branch;
+      const limit = options?.limit;
+      const read = useCallback(
+        () => handle.searchContent(collection, query, { branch, limit }),
+        [handle, collection, query, branch, limit]
+      );
+      return useRead(read);
+    }
+  };
+}
+
+// src/index.ts
+import {
+  createClient as createClient2,
+  toDocument,
+  collectionTag,
+  documentTag,
+  tagsFor,
+  tagsForChanges,
+  TAG_NAMESPACE
+} from "@usegraft/sdk-core";
+import { createContentApiReader as createContentApiReader2 } from "@usegraft/content-api";
+export {
+  TAG_NAMESPACE,
+  collectionTag,
+  createClient2 as createClient,
+  createContentApiReader2 as createContentApiReader,
+  createGraft,
+  createGraftHooks,
+  documentTag,
+  tagsFor,
+  tagsForChanges,
+  toDocument
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@usegraft/sdk-react",
+  "version": "0.2.0",
+  "description": "React browser client: typed content reads and hooks over Graft's read-only content API.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "content-api",
+    "graft",
+    "headless-cms",
+    "hooks",
+    "react",
+    "spa",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/sdk-react"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@usegraft/content-api": "0.2.0",
+    "@usegraft/contracts": "0.2.0",
+    "@usegraft/sdk-core": "0.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@usegraft/core": "0.2.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react --external react/jsx-runtime",
+    "dev": "tsup src/index.ts --format esm --watch --external react --external react/jsx-runtime",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}