@speakspec/astro 0.0.1 → 0.0.3

package/README.md

@@ -56,6 +56,34 @@ export const POST = aidpWebhookRoute()
 > (treats it as private). Use `api/aidp/...` (no leading underscore).
 > The path you register with the SpeakSpec dashboard must match.
 
+## Content inline vs directory (v0.4+)
+
+AIDP v0.4 introduces per-type content strategy. The entity owner can decide, per content type, whether content appears:
+
+- **Inline** (`inline`, default): full content envelopes appear inside `/.well-known/aidp.json`'s `content` array
+- **Directory** (`directory`): the type is omitted from `aidp.json.content`; AI agents fetch `/.well-known/aidp/content/directory.json` for the index, and `/.well-known/aidp/content/{id}.json` for individual envelopes
+
+The `content_index` field in `aidp.json` declares which types are inlined vs indexed:
+
+```json
+{
+  "content_index": {
+    "url": "https://example.com/.well-known/aidp/content/directory.json",
+    "types_inlined": ["faq", "service"],
+    "types_indexed": ["article", "event"],
+    "total_by_type": { "article": 1240, "event": 387, "faq": 18, "service": 6 },
+    "pinned_count": 3,
+    "updated_at": "2026-05-12T10:00:00Z"
+  }
+}
+```
+
+The SDK proxies the upstream response transparently—no client code change is needed when an entity owner switches strategy. AI consumers should check `content_index.types_indexed` and pull `directory.json` when needed.
+
+### Pinned content
+
+Any content can be marked `pinned: true`. Pinned content always appears in `aidp.json.content` regardless of the type's strategy, sorted first.
+
 ## Wire the bot-detection middleware
 
 ```ts

package/dist/runtime/server/utils/cache.d.ts

@@ -26,10 +26,22 @@ export interface CacheStorage {
 export declare function invalidateEntityCache(storage: CacheStorage, slug: string): Promise<void>;
 export declare function invalidateContentCache(storage: CacheStorage, slug: string, contentId: string): Promise<void>;
 /**
- * Build a JSON Response with cache headers, short-circuiting to 304
- * when the inbound `If-None-Match` matches the response ETag (per
- * AIDP §8.7 + RFC 7232 §2.3.2 weak comparison via `etagMatches`).
+ * Build a JSON Response with cache headers per AIDP §8.3 + §11.6,
+ * short-circuiting to 304 when the inbound `If-None-Match` matches the
+ * response ETag (per AIDP §8.7 + RFC 7232 §2.3.2 weak comparison via
+ * `etagMatches`).
  *
- * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1.
+ * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1, and
+ * we keep CORS on them so browser-side agents can revalidate cross-origin.
  */
 export declare function respondWithCache<T>(etag: string, payload: T, cacheControl: string, inboundIfNoneMatch: string | undefined | null): Response;
+/**
+ * Project `directives.access_control` to an AIPREF-compatible
+ * `Content-Usage` header value per AIDP §11.6.
+ *
+ * Returns null when the payload is not an AIDP envelope (e.g. the
+ * directory listing has no `directives` field) or when `access_control`
+ * has no actionable flags — callers MUST NOT emit the header in that
+ * case rather than emitting an empty value.
+ */
+export declare function buildContentUsage(payload: unknown): string | null;

package/dist/runtime/server/utils/cache.js

@@ -55,26 +55,60 @@ export async function invalidateContentCache(storage, slug, contentId) {
     }
 }
 /**
- * Build a JSON Response with cache headers, short-circuiting to 304
- * when the inbound `If-None-Match` matches the response ETag (per
- * AIDP §8.7 + RFC 7232 §2.3.2 weak comparison via `etagMatches`).
+ * Build a JSON Response with cache headers per AIDP §8.3 + §11.6,
+ * short-circuiting to 304 when the inbound `If-None-Match` matches the
+ * response ETag (per AIDP §8.7 + RFC 7232 §2.3.2 weak comparison via
+ * `etagMatches`).
  *
- * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1.
+ * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1, and
+ * we keep CORS on them so browser-side agents can revalidate cross-origin.
  */
 export function respondWithCache(etag, payload, cacheControl, inboundIfNoneMatch) {
     const headers = {
         'cache-control': cacheControl,
+        'access-control-allow-origin': '*',
     };
     if (etag)
         headers.etag = etag;
     if (etagMatches(inboundIfNoneMatch, etag)) {
         return new Response(null, { status: 304, headers });
     }
+    const usage = buildContentUsage(payload);
+    if (usage)
+        headers['content-usage'] = usage;
     return new Response(JSON.stringify(payload), {
         status: 200,
         headers: {
             ...headers,
-            'content-type': 'application/json; charset=utf-8',
+            'content-type': 'application/aidp+json',
         },
     });
 }
+/**
+ * Project `directives.access_control` to an AIPREF-compatible
+ * `Content-Usage` header value per AIDP §11.6.
+ *
+ * Returns null when the payload is not an AIDP envelope (e.g. the
+ * directory listing has no `directives` field) or when `access_control`
+ * has no actionable flags — callers MUST NOT emit the header in that
+ * case rather than emitting an empty value.
+ */
+export function buildContentUsage(payload) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const directives = payload.directives;
+    if (!directives || typeof directives !== 'object')
+        return null;
+    const ac = directives.access_control;
+    if (!ac || typeof ac !== 'object')
+        return null;
+    const flags = ac;
+    const parts = [];
+    if (flags.allow_training === true)
+        parts.push('allow=FoundationModelProduction');
+    else if (flags.allow_training === false)
+        parts.push('disallow=FoundationModelProduction');
+    if (flags.allow_derivative === true)
+        parts.push('allow=Search');
+    return parts.length > 0 ? parts.join(', ') : null;
+}

package/dist/runtime/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION: "0.0.1";
+export declare const SDK_VERSION: "0.0.3";
 export declare const SDK_USER_AGENT: string;

package/dist/runtime/version.js

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.0.1";
+export const SDK_VERSION = "0.0.3";
 export const SDK_USER_AGENT = `@speakspec/astro/${SDK_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speakspec/astro",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "AIDP 0.3 publishing channel for Astro 5 — exposes /.well-known/aidp.json and friends, fetches signed content + pointer payloads from SpeakSpec, receives §8.10 cache-invalidation webhooks.",
   "repository": {
     "type": "git",