@usegraft/contracts 0.2.0 → 1.0.0-beta.1

package/README.md

@@ -33,4 +33,4 @@ throw new GraftError({
 
 ---
 
-MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/feat/core/packages/contracts/CHANGELOG.md)
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/contracts/CHANGELOG.md)

package/dist/index.d.ts

@@ -292,4 +292,103 @@ type RegistryItemDescriptor = z.infer<typeof RegistryItemDescriptor>;
  */
 declare const STATIC_INDEX_DEFAULT_PATH = ".graft/index.db";
 
-export { CollectionDescriptor, ContentAuthority, EditorComponentList, EditorComponentSpec, type ErrorCode, ErrorCodes, FieldDescriptor, FunctionDescriptor, GraftError, type GraftErrorJSON, type GraftErrorOptions, RegistryFileDescriptor, RegistryFileRole, RegistryItemDescriptor, RegistryItemType, STATIC_INDEX_DEFAULT_PATH, SchemaDescription };
+/**
+ * Record the socket address a request came from. Called by an adapter that owns
+ * the connection — never from anything that merely receives a Request.
+ */
+declare function setRequestPeer(request: Request, address: string): void;
+/** The recorded peer address, or undefined when no adapter registered one. */
+declare function getRequestPeer(request: Request): string | undefined;
+/**
+ * The rate-limit identity for a caller with no verified actor.
+ *
+ * Lives here rather than beside one handler because more than one surface
+ * needs it — `createFunctionsHandler` for anonymous function calls, and
+ * `createContentApiHandler` for a read endpoint that never authenticates at
+ * all — and the rule it encodes is the kind that must not be reimplemented
+ * twice. `.greptile/rules.md` names it as a security invariant precisely
+ * because the obvious reading of `x-forwarded-for` is the wrong one.
+ *
+ * Never reads the header unless the deployment declares how many proxies it
+ * controls, and then counts from the RIGHT: entries are appended, so the
+ * rightmost were added by infrastructure closest to us. A client can prepend
+ * anything it likes and never reach that far.
+ */
+declare function rateIdentity(request: Request, trustedProxyHops: number): string;
+
+/**
+ * The content-index read contract.
+ *
+ * These types used to live in `@usegraft/db`, which made them unreachable
+ * without depending on the Postgres package — and `ContentRow` in particular
+ * was `typeof contentIndex.$inferSelect`, derived from a Drizzle table. So the
+ * shape every reader returns was defined by one implementation's storage
+ * schema, and any consumer that merely wanted to *describe* a row (the HTTP
+ * transport, the browser client) had to install a database driver to say so.
+ *
+ * They live here because this is the layer every package already shares.
+ * `@usegraft/db` now proves its table still matches this contract rather than
+ * defining it, which is the direction the dependency should have run in from
+ * the start: the seam owns the shape, the implementation conforms to it.
+ */
+/** One row of the authored-content index. */
+interface ContentRow {
+    branchId: string;
+    collection: string;
+    slug: string;
+    /** Validated frontmatter. */
+    data: Record<string, unknown>;
+    /** Authored MDX source, byte-for-byte as written. */
+    body: string;
+    contentHash: string;
+    sourcePath: string;
+    /** Soft-delete marker. Readers exclude these. */
+    deleted: boolean;
+    updatedAt: Date;
+    /** The FTS vector, when the implementation has one. */
+    search: string | null;
+}
+interface ReaderReadOptions {
+    collection: string;
+    /** When set, read a single document; otherwise the whole collection. */
+    slug?: string;
+    limit?: number;
+    offset?: number;
+    /** Branch to read; defaults to "main". Static readers serve their compiled branch regardless. */
+    branch?: string;
+}
+interface ReaderSearchOptions {
+    /** Websearch-syntax query: words, "quoted phrases", `or`, -exclusions. */
+    query: string;
+    /** Restrict to these collections; defaults to all. */
+    collections?: string[];
+    /** Max hits, best-ranked first. Defaults to 20. */
+    limit?: number;
+    branch?: string;
+}
+interface ContentSearchHit {
+    row: ContentRow;
+    /** Relevance rank: slug beats frontmatter beats body prose. */
+    rank: number;
+    /** Body fragment(s) with matches wrapped in `<b>…</b>`. */
+    snippet: string;
+}
+/**
+ * The seam between "who serves content reads" and "where the index lives".
+ * Implemented by the Postgres reader, the compiled SQLite artifact, and the
+ * HTTP reader in `@usegraft/content-api`.
+ */
+interface ContentIndexReader {
+    readContent(options: ReaderReadOptions): Promise<ContentRow[]>;
+    searchContent(options: ReaderSearchOptions): Promise<ContentSearchHit[]>;
+    close(): Promise<void>;
+}
+/** What one compile changed, by slug. */
+interface ChangeSet {
+    added: string[];
+    changed: string[];
+    removed: string[];
+    unchanged: number;
+}
+
+export { type ChangeSet, CollectionDescriptor, ContentAuthority, type ContentIndexReader, type ContentRow, type ContentSearchHit, EditorComponentList, EditorComponentSpec, type ErrorCode, ErrorCodes, FieldDescriptor, FunctionDescriptor, GraftError, type GraftErrorJSON, type GraftErrorOptions, type ReaderReadOptions, type ReaderSearchOptions, RegistryFileDescriptor, RegistryFileRole, RegistryItemDescriptor, RegistryItemType, STATIC_INDEX_DEFAULT_PATH, SchemaDescription, getRequestPeer, rateIdentity, setRequestPeer };

package/dist/index.js

@@ -176,6 +176,26 @@ var RegistryItemDescriptor = z.object({
 
 // src/paths.ts
 var STATIC_INDEX_DEFAULT_PATH = ".graft/index.db";
+
+// src/peer.ts
+var peers = /* @__PURE__ */ new WeakMap();
+function setRequestPeer(request, address) {
+  peers.set(request, address);
+}
+function getRequestPeer(request) {
+  return peers.get(request);
+}
+function rateIdentity(request, trustedProxyHops) {
+  if (trustedProxyHops > 0) {
+    const forwarded = request.headers.get("x-forwarded-for");
+    if (forwarded) {
+      const hops = forwarded.split(",").map((entry) => entry.trim()).filter(Boolean);
+      const trusted = hops[hops.length - trustedProxyHops];
+      if (trusted) return trusted;
+    }
+  }
+  return getRequestPeer(request) ?? "unknown";
+}
 export {
   CollectionDescriptor,
   ContentAuthority,
@@ -190,5 +210,8 @@ export {
   RegistryItemDescriptor,
   RegistryItemType,
   STATIC_INDEX_DEFAULT_PATH,
-  SchemaDescription
+  SchemaDescription,
+  getRequestPeer,
+  rateIdentity,
+  setRequestPeer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usegraft/contracts",
-  "version": "0.2.0",
+  "version": "1.0.0-beta.1",
   "description": "Shared error codes and introspection schemas: the vocabulary every Graft package speaks.",
   "keywords": [
     "agent",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.1.0"
+    "zod": "^4.5.4"
   },
   "engines": {
     "node": ">=22.16"