@usegraft/content-api 0.0.0-canary-20260901211203

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,66 @@
+# @usegraft/content-api
+
+> A versioned, read-only HTTP transport for Graft's authored content index.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i @usegraft/content-api
+```
+
+## Serve authored content
+
+`graft serve` mounts this handler at `/api/content/v1`. You can also mount it in any runtime that accepts Web `Request` and `Response` objects.
+
+```ts
+import { createContentApiHandler } from "@usegraft/content-api";
+import { createDb, createDbIndexReader } from "@usegraft/db";
+import { collections } from "./graft.config";
+
+const database = createDb(process.env.DATABASE_URL!);
+
+export const GET = createContentApiHandler({
+  collections: Object.keys(collections),
+  branch: "main",
+  index: createDbIndexReader(database.db),
+});
+```
+
+The handler serves:
+
+- `GET /api/content/v1/documents?collection=pages`
+- `GET /api/content/v1/documents?collection=pages&slug=home`
+- `GET /api/content/v1/search?collection=pages&query=pricing`
+
+An endpoint represents one branch. It does not accept a branch query parameter, so a caller cannot switch a production endpoint to preview content.
+
+The handler does not authenticate callers. Put a proxy or check Authorization before invoking it if the index is not public. The handler does not close its reader or database. The application that created those handles owns their lifecycle.
+
+## Use the existing typed SDK
+
+The remote reader implements `ContentIndexReader`, so the framework-agnostic client and framework adapters need no HTTP-specific API.
+
+```ts
+import { createContentApiReader } from "@usegraft/content-api";
+import { createClient } from "@usegraft/sdk-core";
+import { collections } from "./graft.config";
+
+const graft = createClient({
+  index: createContentApiReader({
+    endpoint: "https://cms.example.com/api/content/v1",
+    headers: { authorization: `Bearer ${process.env.GRAFT_CONTENT_TOKEN}` },
+  }),
+  collections,
+});
+
+const page = await graft.getDocument("pages", "home");
+const hits = await graft.searchDocuments("pages", "pricing");
+```
+
+Pass `fetch` to `createContentApiReader` when the runtime needs a custom implementation. `headers` are static and sent on every request, which suits an auth token or proxy header.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft)

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { ContentIndexReader } from '@usegraft/contracts';
+
+type ContentApiHandler = (request: Request) => Promise<Response>;
+interface ContentApiRateLimit {
+    /** Requests allowed per identity per window. */
+    limit: number;
+    /** Window length in seconds. Also the `Retry-After` value on a refusal. */
+    windowSeconds: number;
+}
+interface ContentApiHandlerOptions {
+    /** Collection names this endpoint may expose. */
+    collections: readonly string[];
+    /** The one branch represented by this endpoint. Callers cannot override it. */
+    branch: string;
+    /** Reader owned by the caller. The handler never closes it. */
+    index: ContentIndexReader;
+    /**
+     * Per-identity backstop. Omitted means unlimited, which is the right default
+     * for a handler mounted behind something that already has a limiter — but a
+     * mount facing the open internet wants one, because these routes run database
+     * listings and full-text searches for callers this handler never
+     * authenticates.
+     */
+    rateLimit?: ContentApiRateLimit;
+    /**
+     * How many proxies in front of this handler are ours. Forwarded to
+     * `rateIdentity`; zero (the default) means `x-forwarded-for` is never read
+     * and every unidentified caller shares one bucket.
+     */
+    trustedProxyHops?: number;
+    /**
+     * Origins allowed to read responses from a browser.
+     *
+     * Omitted means no CORS headers at all, which is same-origin only — the
+     * correct default, because publishing an endpoint to other origins is a
+     * decision for whoever deploys it and not one a library should make on their
+     * behalf. `@usegraft/sdk-react` needs this set whenever the app and the
+     * content API are on different origins, which is the ordinary case.
+     *
+     * An explicit list is echoed back per request (with `Vary: Origin`, so a
+     * cache cannot serve one origin's response to another). `"*"` allows any
+     * origin and is reasonable for content that is public anyway — which this
+     * handler's content is, since it authenticates nobody.
+     */
+    allowedOrigins?: readonly string[] | "*";
+}
+interface ContentApiReaderOptions {
+    /**
+     * API base URL: absolute (https://cms.example.com/api/content/v1), or a
+     * same-origin path (/api/content/v1) when running in a browser, where it
+     * resolves against the page origin.
+     */
+    endpoint: string | URL;
+    /** Fetch implementation for non-browser runtimes, tests, or instrumentation. */
+    fetch?: typeof globalThis.fetch;
+    /** Static headers sent with every request, such as Authorization. */
+    headers?: Record<string, string>;
+}
+declare function createContentApiHandler(options: ContentApiHandlerOptions): ContentApiHandler;
+/** Create a ContentIndexReader that reads a remote /api/content/v1 endpoint. */
+declare function createContentApiReader(options: ContentApiReaderOptions): ContentIndexReader;
+
+export { type ContentApiHandlerOptions, type ContentApiRateLimit, type ContentApiReaderOptions, createContentApiHandler, createContentApiReader };

package/dist/index.js

@@ -0,0 +1,459 @@
+// src/index.ts
+import {
+  ErrorCodes,
+  GraftError,
+  rateIdentity
+} from "@usegraft/contracts";
+var CONTENT_API_BASE = "/api/content/v1";
+var MAX_QUERY_LIMIT = 500;
+var JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isErrorCode(value) {
+  return typeof value === "string" && Object.hasOwn(ErrorCodes, value);
+}
+function parseGraftError(value) {
+  if (!isRecord(value) || !isErrorCode(value.error) || typeof value.message !== "string") {
+    return void 0;
+  }
+  if (value.fix !== void 0 && typeof value.fix !== "string") return void 0;
+  if (value.details !== void 0 && !isRecord(value.details)) return void 0;
+  const json2 = {
+    error: value.error,
+    message: value.message
+  };
+  if (typeof value.fix === "string") json2.fix = value.fix;
+  if (isRecord(value.details)) json2.details = value.details;
+  return new GraftError({
+    code: json2.error,
+    message: json2.message,
+    fix: json2.fix,
+    details: json2.details
+  });
+}
+function protocolError(message, details) {
+  return new GraftError({
+    code: "FUNCTION_EXECUTION_FAILED",
+    message,
+    fix: "Check that endpoint points to a compatible /api/content/v1 server and that no proxy is replacing its JSON response.",
+    details
+  });
+}
+function stringField(value, field, location) {
+  const raw = value[field];
+  if (typeof raw !== "string") {
+    throw protocolError(`Content API returned a malformed row at ${location}.`, {
+      location,
+      field
+    });
+  }
+  return raw;
+}
+function parseWireRow(value, location) {
+  if (!isRecord(value)) {
+    throw protocolError(`Content API returned a malformed row at ${location}.`, { location });
+  }
+  const data = value.data;
+  if (!isRecord(data)) {
+    throw protocolError(`Content API returned a malformed row at ${location}.`, {
+      location,
+      field: "data"
+    });
+  }
+  if (typeof value.deleted !== "boolean") {
+    throw protocolError(`Content API returned a malformed row at ${location}.`, {
+      location,
+      field: "deleted"
+    });
+  }
+  const search = value.search;
+  if (search !== null && typeof search !== "string") {
+    throw protocolError(`Content API returned a malformed row at ${location}.`, {
+      location,
+      field: "search"
+    });
+  }
+  const updatedAtRaw = stringField(value, "updatedAt", location);
+  const updatedAt = new Date(updatedAtRaw);
+  if (Number.isNaN(updatedAt.getTime())) {
+    throw protocolError(`Content API returned an invalid updatedAt at ${location}.`, {
+      location,
+      updatedAt: updatedAtRaw
+    });
+  }
+  return {
+    branchId: stringField(value, "branchId", location),
+    collection: stringField(value, "collection", location),
+    slug: stringField(value, "slug", location),
+    data,
+    body: stringField(value, "body", location),
+    contentHash: stringField(value, "contentHash", location),
+    sourcePath: stringField(value, "sourcePath", location),
+    deleted: value.deleted,
+    updatedAt,
+    search
+  };
+}
+function parseRowsPayload(value) {
+  if (!isRecord(value) || !Array.isArray(value.rows)) {
+    throw protocolError('Content API documents response must be an object with a "rows" array.');
+  }
+  return value.rows.map((row, index) => parseWireRow(row, `rows[${index}]`));
+}
+function parseHitsPayload(value) {
+  if (!isRecord(value) || !Array.isArray(value.hits)) {
+    throw protocolError('Content API search response must be an object with a "hits" array.');
+  }
+  return value.hits.map((value2, index) => {
+    const location = `hits[${index}]`;
+    if (!isRecord(value2) || typeof value2.rank !== "number" || !Number.isFinite(value2.rank) || typeof value2.snippet !== "string") {
+      throw protocolError(`Content API returned a malformed search hit at ${location}.`, {
+        location
+      });
+    }
+    return {
+      row: parseWireRow(value2.row, `${location}.row`),
+      rank: value2.rank,
+      snippet: value2.snippet
+    };
+  });
+}
+function toWireRow(row) {
+  return {
+    branchId: row.branchId,
+    collection: row.collection,
+    slug: row.slug,
+    data: row.data,
+    body: row.body,
+    contentHash: row.contentHash,
+    sourcePath: row.sourcePath,
+    deleted: row.deleted,
+    updatedAt: row.updatedAt.toISOString(),
+    search: row.search
+  };
+}
+function json(value, status = 200, extra) {
+  const headers = new Headers();
+  if (extra) {
+    for (const [name, headerValue] of Object.entries(extra)) {
+      headers.set(name, headerValue);
+    }
+  }
+  headers.set("content-type", JSON_CONTENT_TYPE);
+  return new Response(JSON.stringify(value), { status, headers });
+}
+function responseHeadersFor(error) {
+  if (error.code === "METHOD_NOT_ALLOWED") return { allow: "GET" };
+  if (error.code === "RATE_LIMITED") {
+    const retryAfter = error.details?.retryAfter;
+    if (typeof retryAfter === "number") return { "retry-after": String(retryAfter) };
+  }
+  return void 0;
+}
+function statusFor(error) {
+  switch (error.code) {
+    case "COLLECTION_NOT_FOUND":
+    case "ROUTE_NOT_FOUND":
+      return 404;
+    case "METHOD_NOT_ALLOWED":
+      return 405;
+    case "INPUT_VALIDATION_FAILED":
+      return 400;
+    case "RATE_LIMITED":
+      return 429;
+    default:
+      return 500;
+  }
+}
+function inputError(message, fix, details) {
+  return new GraftError({ code: "INPUT_VALIDATION_FAILED", message, fix, details });
+}
+function parseLimit(url) {
+  const raw = url.searchParams.get("limit");
+  if (raw === null) return void 0;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw inputError(
+      `"${raw}" is not a valid limit.`,
+      `Pass limit as a positive integer. Values above ${MAX_QUERY_LIMIT} are capped at ${MAX_QUERY_LIMIT}.`,
+      { limit: raw }
+    );
+  }
+  return Math.min(value, MAX_QUERY_LIMIT);
+}
+function parseOffset(url) {
+  const raw = url.searchParams.get("offset");
+  if (raw === null) return void 0;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw inputError(`"${raw}" is not a valid offset.`, "Pass offset as a non-negative integer.", {
+      offset: raw
+    });
+  }
+  return value;
+}
+function requiredParam(url, name) {
+  const value = url.searchParams.get(name)?.trim() ?? "";
+  if (value === "") {
+    throw inputError(
+      `${name} query param is required.`,
+      `GET ${CONTENT_API_BASE}/${name === "query" ? "search" : "documents"}?collection=<name>${name === "query" ? "&query=<text>" : ""}`,
+      { parameter: name }
+    );
+  }
+  return value;
+}
+function assertNoBranchOverride(url) {
+  if (url.searchParams.has("branch")) {
+    throw inputError(
+      "The content API does not accept a branch query param.",
+      "Use the endpoint mounted for the branch you need. Each endpoint represents exactly one branch.",
+      { branch: url.searchParams.get("branch") }
+    );
+  }
+}
+function createRateLimiter(limit, windowSeconds) {
+  const windowMs = windowSeconds * 1e3;
+  const buckets = /* @__PURE__ */ new Map();
+  const SWEEP_THRESHOLD = 4096;
+  return (identity, now) => {
+    if (buckets.size >= SWEEP_THRESHOLD) {
+      for (const [key, bucket2] of buckets) {
+        if (bucket2.resetAt <= now) buckets.delete(key);
+      }
+    }
+    const bucket = buckets.get(identity);
+    if (bucket === void 0 || bucket.resetAt <= now) {
+      buckets.set(identity, { count: 1, resetAt: now + windowMs });
+      return void 0;
+    }
+    bucket.count += 1;
+    if (bucket.count <= limit) return void 0;
+    return Math.max(1, Math.ceil((bucket.resetAt - now) / 1e3));
+  };
+}
+function corsHeaders(request, allowed) {
+  if (allowed === void 0) return void 0;
+  const origin = request.headers.get("origin");
+  if (origin === null) return void 0;
+  if (allowed === "*") {
+    return { "access-control-allow-origin": "*" };
+  }
+  if (!allowed.includes(origin)) return void 0;
+  return { "access-control-allow-origin": origin, vary: "Origin" };
+}
+function createContentApiHandler(options) {
+  const collections = new Set(options.collections);
+  const consume = options.rateLimit === void 0 ? void 0 : createRateLimiter(options.rateLimit.limit, options.rateLimit.windowSeconds);
+  const trustedProxyHops = options.trustedProxyHops ?? 0;
+  return async (request) => {
+    const url = new URL(request.url);
+    const cors = corsHeaders(request, options.allowedOrigins);
+    if (request.method === "OPTIONS" && cors !== void 0) {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          ...cors,
+          "access-control-allow-methods": "GET, OPTIONS",
+          "access-control-allow-headers": request.headers.get("access-control-request-headers") ?? "authorization,content-type",
+          "access-control-max-age": "86400"
+        }
+      });
+    }
+    try {
+      const route = url.pathname === `${CONTENT_API_BASE}/documents` ? "documents" : url.pathname === `${CONTENT_API_BASE}/search` ? "search" : void 0;
+      if (route === void 0) {
+        throw new GraftError({
+          code: "ROUTE_NOT_FOUND",
+          message: `Nothing is mounted at ${url.pathname}.`,
+          fix: `Use GET ${CONTENT_API_BASE}/documents or GET ${CONTENT_API_BASE}/search.`,
+          details: { pathname: url.pathname }
+        });
+      }
+      if (request.method !== "GET") {
+        throw new GraftError({
+          code: "METHOD_NOT_ALLOWED",
+          message: `Content API reads use GET, not ${request.method}.`,
+          fix: `Send a GET request to ${url.pathname}.`,
+          details: { method: request.method }
+        });
+      }
+      if (consume !== void 0 && options.rateLimit !== void 0) {
+        const retryAfter = consume(rateIdentity(request, trustedProxyHops), Date.now());
+        if (retryAfter !== void 0) {
+          throw new GraftError({
+            code: "RATE_LIMITED",
+            message: `This content endpoint allows ${options.rateLimit.limit} requests per ${options.rateLimit.windowSeconds}s per caller.`,
+            fix: `Wait ${retryAfter}s \u2014 the Retry-After header says how long \u2014 then retry. Cache reads at your CDN if you need a higher sustained rate.`,
+            details: {
+              limit: options.rateLimit.limit,
+              windowSeconds: options.rateLimit.windowSeconds,
+              retryAfter
+            }
+          });
+        }
+      }
+      assertNoBranchOverride(url);
+      const collection = requiredParam(url, "collection");
+      if (!collections.has(collection)) {
+        throw new GraftError({
+          code: "COLLECTION_NOT_FOUND",
+          message: `Collection "${collection}" is not registered on this content endpoint.`,
+          fix: `Use one of the registered collections: ${[...collections].join(", ") || "(none)"}.`,
+          details: { collection, registered: [...collections] }
+        });
+      }
+      const limit = parseLimit(url);
+      if (route === "documents") {
+        const slugRaw = url.searchParams.get("slug");
+        const slug = slugRaw === null ? void 0 : slugRaw.trim();
+        if (slug === "") {
+          throw inputError(
+            "slug cannot be empty when provided.",
+            "Omit slug to list the collection, or pass a non-empty document slug.",
+            { slug: slugRaw }
+          );
+        }
+        const rows = await options.index.readContent({
+          collection,
+          slug,
+          limit,
+          offset: parseOffset(url),
+          branch: options.branch
+        });
+        return json({ rows: rows.map(toWireRow) }, 200, cors);
+      }
+      const query = requiredParam(url, "query");
+      const hits = await options.index.searchContent({
+        collections: [collection],
+        query,
+        limit,
+        branch: options.branch
+      });
+      return json(
+        {
+          hits: hits.map(
+            ({ row, rank, snippet }) => ({
+              row: toWireRow(row),
+              rank,
+              snippet
+            })
+          )
+        },
+        200,
+        cors
+      );
+    } catch (error) {
+      const graftError = error instanceof GraftError ? error : protocolError(
+        `Content API failed to read its index: ${error instanceof Error ? error.message : String(error)}`
+      );
+      const extra = { ...responseHeadersFor(graftError), ...cors };
+      return json(
+        graftError.toJSON(),
+        statusFor(graftError),
+        Object.keys(extra).length > 0 ? extra : void 0
+      );
+    }
+  };
+}
+function normalizeEndpoint(endpoint) {
+  const url = endpoint instanceof URL ? new URL(endpoint) : resolveEndpointUrl(endpoint);
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+function resolveEndpointUrl(endpoint) {
+  const base = globalThis.location?.href;
+  try {
+    return base === void 0 ? new URL(endpoint) : new URL(endpoint, base);
+  } catch {
+    throw new GraftError({
+      code: "CONFIG_INVALID",
+      message: `\`endpoint\` is not a valid URL: ${endpoint}`,
+      fix: base === void 0 ? "Outside a browser there is no page origin to resolve a relative path against. Pass an absolute endpoint, e.g. https://cms.example.com/api/content/v1." : "Pass an absolute endpoint (https://cms.example.com/api/content/v1) or a same-origin path (/api/content/v1).",
+      details: { endpoint, base }
+    });
+  }
+}
+function createContentApiReader(options) {
+  const endpoint = normalizeEndpoint(options.endpoint);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const headers = new Headers();
+  if (options.headers) {
+    for (const [name, headerValue] of Object.entries(options.headers)) {
+      headers.set(name, headerValue);
+    }
+  }
+  if (!headers.has("accept")) headers.set("accept", "application/json");
+  const getJson = async (route, params) => {
+    const url = new URL(endpoint);
+    url.pathname = `${endpoint.pathname}/${route}`;
+    url.search = params.toString();
+    let response;
+    try {
+      response = await fetchImpl(url, { method: "GET", headers });
+    } catch (error) {
+      throw protocolError(
+        `Content API request to ${url.toString()} failed: ${error instanceof Error ? error.message : String(error)}`,
+        { endpoint: url.toString() }
+      );
+    }
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      throw protocolError(`Content API returned non-JSON HTTP ${response.status}.`, {
+        endpoint: url.toString(),
+        status: response.status
+      });
+    }
+    if (!response.ok) {
+      const remoteError = parseGraftError(payload);
+      if (remoteError) throw remoteError;
+      throw protocolError(`Content API returned HTTP ${response.status} without a GraftError.`, {
+        endpoint: url.toString(),
+        status: response.status
+      });
+    }
+    if (!isRecord(payload)) {
+      throw protocolError("Content API returned JSON that was not an object.", {
+        endpoint: url.toString()
+      });
+    }
+    return payload;
+  };
+  return {
+    async readContent(options2) {
+      const params = new URLSearchParams({ collection: options2.collection });
+      if (options2.slug !== void 0) params.set("slug", options2.slug);
+      if (options2.limit !== void 0) params.set("limit", String(options2.limit));
+      if (options2.offset !== void 0) params.set("offset", String(options2.offset));
+      return parseRowsPayload(await getJson("documents", params));
+    },
+    async searchContent(options2) {
+      if (options2.collections?.length !== 1) {
+        throw new GraftError({
+          code: "INPUT_VALIDATION_FAILED",
+          message: "The content API reader needs exactly one collection for search.",
+          fix: "Pass collections: [name]. Graft SDK searchDocuments already does this.",
+          details: { collections: options2.collections }
+        });
+      }
+      const params = new URLSearchParams({
+        collection: options2.collections[0],
+        query: options2.query
+      });
+      if (options2.limit !== void 0) params.set("limit", String(options2.limit));
+      return parseHitsPayload(await getJson("search", params));
+    },
+    // The reader owns no server or database handle.
+    async close() {
+    }
+  };
+}
+export {
+  createContentApiHandler,
+  createContentApiReader
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@usegraft/content-api",
+  "version": "0.0.0-canary-20260901211203",
+  "description": "A versioned read-only HTTP transport for Graft's authored content index.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "content-api",
+    "graft",
+    "headless-cms",
+    "http",
+    "sdk",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/content-api"
+  },
+  "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/contracts": "0.0.0-canary-20260901211203"
+  },
+  "devDependencies": {
+    "@usegraft/db": "0.0.0-canary-20260901211203"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}