@usegraft/sdk-astro 0.2.0 → 1.0.0-beta.1

package/README.md

@@ -12,33 +12,82 @@ npm i @usegraft/sdk-astro
 
 ## Read content
 
+Build the handle once in a server-only module, then import it from frontmatter, endpoints, and middleware. Never from a client island: it holds a database handle.
+
 ```ts
+// src/lib/graft.ts
+import { createDb } from "@usegraft/db";
 import { createGraft } from "@usegraft/sdk-astro";
-import { collections } from "../graft.config";
+import { collections } from "../../graft.config";
 
-const graft = createGraft({ db, collections });
-const page = await graft.getContent("pages", Astro.params.slug);
+export const graft = createGraft({ db: createDb(process.env.DATABASE_URL!).db, collections });
+```
+
+```astro
+---
+// src/pages/[slug].astro
+import { graft } from "../lib/graft";
+
+const page = await graft.getContent("pages", Astro.params.slug!);
+---
+```
+
+Return types come from your `defineCollection` schemas, so a renamed field is a build error rather than a runtime `undefined`.
+
+There is no request-level memo here, because `React.cache` has no Astro equivalent. Reads go straight to the index, which is the right default: prerendered pages read at build time, and an SSR page makes a handful of reads.
+
+## Read with no database
+
+Pass `index` instead of `db` and the same surface reads the SQLite artifact `graft compile` writes.
+
+```ts
+import { openStaticIndex } from "@usegraft/db";
+
+export const graft = createGraft({
+  index: await openStaticIndex(".graft/index.db"),
+  collections,
+});
 ```
 
 ## Mount the runtime
 
-`graftRoute` binds Graft's stateless handlers to an Astro endpoint, so typed functions and MCP are served from your own app rather than a separate process.
+`graftRoute` binds a Graft handler to an Astro endpoint, so typed functions and MCP are served from your own app rather than a separate process. It takes the handler, not a config object: Astro hands over an `APIContext`, and the handlers want its `request`.
+
+```ts
+// src/pages/api/fn/[name].ts
+import { createFunctionsHandler } from "@usegraft/core";
+import { graftRoute } from "@usegraft/sdk-astro";
+
+const handler = createFunctionsHandler({ db, collections, functions });
+
+export const POST = graftRoute(handler);
+export const GET = graftRoute(handler); // 405s with Allow and a fix
+```
 
 ```ts
-// src/pages/api/[...graft].ts
+// src/pages/api/mcp.ts
+import { createGraftMcpHandler } from "@usegraft/mcp";
 import { graftRoute } from "@usegraft/sdk-astro";
 
-export const ALL = graftRoute({ db, collections, functions });
+export const POST = graftRoute(createGraftMcpHandler({ db, collections, functions, actor }));
 ```
 
+The parameter is typed structurally as `{ request: Request }`, so this package needs no `astro` dependency and every `APIContext` satisfies it.
+
 ## MDX
 
 Bodies come back as authored source. Render them with Astro's own MDX pipeline rather than a runtime evaluator, which is why this package ships no `MdxBody` equivalent.
 
 ## Cache invalidation
 
-The [`@usegraft/sdk-core`](https://www.npmjs.com/package/@usegraft/sdk-core) tag contract maps onto CDN surrogate keys.
+Astro has no tag-based data cache, so the [`@usegraft/sdk-core`](https://www.npmjs.com/package/@usegraft/sdk-core) tag contract maps onto HTTP. Stamp `tagsFor(...)` into a CDN surrogate-key header on SSR responses, and purge `tagsForChanges(branch, changeSet)` from your compile webhook.
+
+```astro
+---
+Astro.response.headers.set("Cache-Tag", tagsFor(branch, "pages", slug).join(","));
+---
+```
 
 ---
 
-MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/feat/core/packages/sdk-astro/CHANGELOG.md)
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/sdk-astro/CHANGELOG.md)

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { DbClientOptions } from '@usegraft/sdk-core/db';
 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';
 
@@ -29,7 +30,15 @@ interface Graft<TCollections extends Record<string, AnyCollection>> {
     /** The underlying sdk-core client, for anything the helpers don't cover. */
     client: GraftClient<TCollections>;
 }
-declare function createGraft<TCollections extends Record<string, AnyCollection>>(options: ClientOptions<TCollections>): Graft<TCollections>;
+/**
+ * Either an index this adapter reads through, or a Postgres handle it builds
+ * the reader for. Two shapes rather than one optional field so that neither can
+ * be omitted: `createClient` no longer accepts `db`, because taking it there
+ * meant every consumer of `@usegraft/sdk-core` — the browser client included —
+ * carried a Postgres driver in its dependency graph.
+ */
+type GraftOptions<TCollections extends Record<string, AnyCollection>> = ClientOptions<TCollections> | DbClientOptions<TCollections>;
+declare function createGraft<TCollections extends Record<string, AnyCollection>>(options: GraftOptions<TCollections>): Graft<TCollections>;
 
 /**
  * Mounting the Graft runtime in Astro — endpoints are already Web-standard,
@@ -58,4 +67,4 @@ declare function graftRoute(handler: FetchHandler): (context: {
     request: Request;
 }) => Promise<Response>;
 
-export { type FetchHandler, type Graft, createGraft, graftRoute };
+export { type FetchHandler, type Graft, type GraftOptions, createGraft, graftRoute };

package/dist/index.js

@@ -1,9 +1,10 @@
 // src/graft.ts
+import { createDbClient } from "@usegraft/sdk-core/db";
 import {
   createClient
 } from "@usegraft/sdk-core";
 function createGraft(options) {
-  const client = createClient(options);
+  const client = "db" in options ? createDbClient(options) : createClient(options);
   return {
     client,
     getContent: (collection, slug, opts) => client.getDocument(collection, slug, opts),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usegraft/sdk-astro",
-  "version": "0.2.0",
+  "version": "1.0.0-beta.1",
   "description": "Astro adapter: typed content reads and endpoint mounts over Graft's stateless handlers.",
   "keywords": [
     "agent",
@@ -38,10 +38,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@usegraft/sdk-core": "0.2.0"
+    "@usegraft/db": "1.0.0-beta.1",
+    "@usegraft/sdk-core": "1.0.0-beta.1"
   },
   "devDependencies": {
-    "@usegraft/core": "0.2.0"
+    "@usegraft/core": "1.0.0-beta.1"
   },
   "engines": {
     "node": ">=22.16"