@usegraft/content-api 0.2.0 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-import { ContentIndexReader } from '@usegraft/db';
+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[];
@@ -8,18 +14,50 @@ interface ContentApiHandlerOptions {
     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 {
-    /** Full API base URL, for example https://cms.example.com/api/content/v1. */
+    /**
+     * 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>;
 }
-/** Create the read-only Web-standard handler mounted at /api/content/v1. */
 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 ContentApiReaderOptions, createContentApiHandler, createContentApiReader };
+export { type ContentApiHandlerOptions, type ContentApiRateLimit, type ContentApiReaderOptions, createContentApiHandler, createContentApiReader };

package/dist/index.js

@@ -1,5 +1,9 @@
 // src/index.ts
-import { ErrorCodes, GraftError } from "@usegraft/contracts";
+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";
@@ -139,6 +143,14 @@ function json(value, status = 200, extra) {
   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":
@@ -148,6 +160,8 @@ function statusFor(error) {
       return 405;
     case "INPUT_VALIDATION_FAILED":
       return 400;
+    case "RATE_LIMITED":
+      return 429;
     default:
       return 500;
   }
@@ -199,10 +213,54 @@ function assertNoBranchOverride(url) {
     );
   }
 }
+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) {
@@ -221,6 +279,21 @@ function createContentApiHandler(options) {
           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)) {
@@ -249,7 +322,7 @@ function createContentApiHandler(options) {
           offset: parseOffset(url),
           branch: options.branch
         });
-        return json({ rows: rows.map(toWireRow) });
+        return json({ rows: rows.map(toWireRow) }, 200, cors);
       }
       const query = requiredParam(url, "query");
       const hits = await options.index.searchContent({
@@ -258,31 +331,52 @@ function createContentApiHandler(options) {
         limit,
         branch: options.branch
       });
-      return json({
-        hits: hits.map(
-          ({ row, rank, snippet }) => ({
-            row: toWireRow(row),
-            rank,
-            snippet
-          })
-        )
-      });
+      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 = graftError.code === "METHOD_NOT_ALLOWED" ? { allow: "GET" } : void 0;
-      return json(graftError.toJSON(), statusFor(graftError), extra);
+      const extra = { ...responseHeadersFor(graftError), ...cors };
+      return json(
+        graftError.toJSON(),
+        statusFor(graftError),
+        Object.keys(extra).length > 0 ? extra : void 0
+      );
     }
   };
 }
 function normalizeEndpoint(endpoint) {
-  const url = new URL(endpoint.toString());
+  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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usegraft/content-api",
-  "version": "0.2.0",
+  "version": "1.0.0-beta.1",
   "description": "A versioned read-only HTTP transport for Graft's authored content index.",
   "keywords": [
     "agent",
@@ -37,8 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@usegraft/contracts": "0.2.0",
-    "@usegraft/db": "0.2.0"
+    "@usegraft/contracts": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@usegraft/db": "1.0.0-beta.1"
   },
   "engines": {
     "node": ">=22.16"