@usegraft/sdk-astro 0.1.1 → 1.0.0-beta.0

package/README.md

@@ -0,0 +1,93 @@
+# @usegraft/sdk-astro
+
+> Astro adapter: typed content reads and endpoint mounts over the same handlers every other surface serves.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+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";
+
+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 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/mcp.ts
+import { createGraftMcpHandler } from "@usegraft/mcp";
+import { graftRoute } from "@usegraft/sdk-astro";
+
+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
+
+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/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,20 @@
 {
   "name": "@usegraft/sdk-astro",
-  "version": "0.1.1",
+  "version": "1.0.0-beta.0",
+  "description": "Astro adapter: typed content reads and endpoint mounts over Graft's stateless handlers.",
+  "keywords": [
+    "agent",
+    "ai",
+    "astro",
+    "cms",
+    "content",
+    "graft",
+    "headless-cms",
+    "mcp",
+    "ssr",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,10 +38,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@usegraft/sdk-core": "0.1.1"
+    "@usegraft/db": "1.0.0-beta.0",
+    "@usegraft/sdk-core": "1.0.0-beta.0"
   },
   "devDependencies": {
-    "@usegraft/core": "0.1.1"
+    "@usegraft/core": "1.0.0-beta.0"
   },
   "engines": {
     "node": ">=22.16"
@@ -36,7 +51,6 @@
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests",
-    "lint": "oxlint ."
+    "test": "vitest run --passWithNoTests"
   }
 }