@speakspec/astro 0.0.1

package/dist/runtime/server/utils/impression-queue.js

@@ -0,0 +1,145 @@
+// Buffered queue for AI-crawler impressions observed by the SDK
+// middleware. Flushes to the SpeakSpec server's
+// POST {endpoint}/api/v1/impressions endpoint in batches.
+//
+// Design contract:
+//   - Fire-and-forget: enqueue() returns immediately, flush runs async
+//   - Bounded memory: maxQueueBytes hard cap (drops oldest on overrun)
+//   - Backoff on failure: N consecutive flush errors → pause 5 min
+//   - Fallback on permanent failure: emit each impression to stdout so
+//     the customer's log pipeline still sees it
+//
+// The queue is module-scoped — one instance per host process. In
+// serverless deployments with cold starts, items in flight may be
+// lost (acceptable per fire-and-forget design).
+import { Buffer } from 'node:buffer';
+import { SDK_USER_AGENT } from '../../version';
+const DEFAULT_CONFIG = {
+    batchSize: 50,
+    flushIntervalMs: 60_000,
+    maxQueueBytes: 2 * 1024 * 1024,
+    onError: 'fallback-stdout',
+};
+const BACKOFF_THRESHOLD = 5;
+const BACKOFF_DURATION_MS = 5 * 60_000;
+let state = newState();
+let activeConfig = null;
+function newState() {
+    return { items: [], bytes: 0, consecutiveFailures: 0, backoffUntil: 0, flushTimer: null };
+}
+export function configureQueue(cfg) {
+    activeConfig = { ...DEFAULT_CONFIG, ...cfg };
+}
+export function resetQueue() {
+    if (state.flushTimer)
+        clearTimeout(state.flushTimer);
+    state = newState();
+    activeConfig = null;
+}
+export function enqueueImpression(impression) {
+    if (!activeConfig) {
+        fallbackLog(impression, 'fallback-stdout', console.log);
+        return;
+    }
+    const cfg = activeConfig;
+    const size = approximateSize(impression);
+    while (state.bytes + size > cfg.maxQueueBytes && state.items.length > 0) {
+        const dropped = state.items.shift();
+        state.bytes -= approximateSize(dropped);
+        fallbackLog(dropped, cfg.onError, cfg.logger ?? console.log);
+    }
+    state.items.push(impression);
+    state.bytes += size;
+    if (state.items.length >= cfg.batchSize) {
+        void flushQueue();
+        return;
+    }
+    scheduleFlush(cfg);
+}
+function scheduleFlush(cfg) {
+    if (state.flushTimer)
+        return;
+    state.flushTimer = setTimeout(() => {
+        state.flushTimer = null;
+        void flushQueue();
+    }, cfg.flushIntervalMs);
+    if (typeof state.flushTimer === 'object' && state.flushTimer && typeof state.flushTimer.unref === 'function') {
+        state.flushTimer.unref();
+    }
+}
+export async function flushQueue() {
+    if (!activeConfig || state.items.length === 0)
+        return;
+    if (state.flushTimer) {
+        clearTimeout(state.flushTimer);
+        state.flushTimer = null;
+    }
+    const cfg = activeConfig;
+    if (Date.now() < state.backoffUntil) {
+        drainTo(cfg, cfg.onError);
+        return;
+    }
+    const batch = state.items;
+    state.items = [];
+    state.bytes = 0;
+    const payload = {
+        impressions: batch.map(i => ({
+            user_agent: i.user_agent,
+            path: i.path,
+            content_id: i.content_id,
+            client_ip: i.client_ip,
+        })),
+    };
+    try {
+        const fetcher = cfg.fetcher ?? fetch;
+        const url = `${stripTrailingSlash(cfg.endpoint)}/api/v1/impressions`;
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), 5000);
+        const res = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'accept': 'application/json',
+                'user-agent': SDK_USER_AGENT,
+                'x-api-key': cfg.apiKey,
+            },
+            body: JSON.stringify(payload),
+            signal: ctrl.signal,
+        });
+        clearTimeout(timeout);
+        if (!res.ok) {
+            throw new Error(`POST impressions → ${res.status} ${res.statusText}`);
+        }
+        state.consecutiveFailures = 0;
+    }
+    catch {
+        state.consecutiveFailures += 1;
+        if (state.consecutiveFailures >= BACKOFF_THRESHOLD) {
+            state.backoffUntil = Date.now() + BACKOFF_DURATION_MS;
+        }
+        for (const item of batch) {
+            fallbackLog(item, cfg.onError, cfg.logger ?? console.log);
+        }
+    }
+}
+function drainTo(cfg, mode) {
+    const items = state.items;
+    state.items = [];
+    state.bytes = 0;
+    for (const i of items)
+        fallbackLog(i, mode, cfg.logger ?? console.log);
+}
+function fallbackLog(impression, mode, logger) {
+    if (mode === 'silent')
+        return;
+    logger(JSON.stringify(impression));
+}
+function approximateSize(record) {
+    return Buffer.byteLength(JSON.stringify(record), 'utf8');
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+export function _peekQueue() {
+    return { count: state.items.length, bytes: state.bytes, consecutiveFailures: state.consecutiveFailures, backoffUntil: state.backoffUntil };
+}

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

@@ -0,0 +1,14 @@
+export declare class QueryError extends Error {
+    statusCode: number;
+    statusMessage: string;
+    constructor(statusCode: number, statusMessage: string);
+}
+/**
+ * Parse an optional positive-integer query value (>= 1). Returns
+ * undefined when the input is unset; throws QueryError(400) for
+ * arrays, non-integers, zero, or negative numbers.
+ *
+ * `page=0` is rejected (the server normalises it but a fast-fail at
+ * the SDK layer surfaces the customer's mistake immediately).
+ */
+export declare function parsePositiveInt(value: unknown, name: string): number | undefined;

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

@@ -0,0 +1,33 @@
+// Pure helpers for parsing inbound query-string params on the AIDP
+// route handlers. Framework-agnostic — throws QueryError that route
+// factories convert into a Response.
+export class QueryError extends Error {
+    statusCode;
+    statusMessage;
+    constructor(statusCode, statusMessage) {
+        super(statusMessage);
+        this.name = 'QueryError';
+        this.statusCode = statusCode;
+        this.statusMessage = statusMessage;
+    }
+}
+/**
+ * Parse an optional positive-integer query value (>= 1). Returns
+ * undefined when the input is unset; throws QueryError(400) for
+ * arrays, non-integers, zero, or negative numbers.
+ *
+ * `page=0` is rejected (the server normalises it but a fast-fail at
+ * the SDK layer surfaces the customer's mistake immediately).
+ */
+export function parsePositiveInt(value, name) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (Array.isArray(value)) {
+        throw new QueryError(400, `${name} must be a single value`);
+    }
+    const n = Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new QueryError(400, `${name} must be a positive integer (>= 1)`);
+    }
+    return n;
+}

package/dist/runtime/version.d.ts

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

package/dist/runtime/version.js

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@speakspec/astro",
+  "version": "0.0.1",
+  "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",
+    "url": "git+https://github.com/speakspec/astro.git"
+  },
+  "homepage": "https://docs.speakspec.com/developer/sdk-astro",
+  "bugs": {
+    "url": "https://github.com/speakspec/astro/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./components/AidpLinks.astro": "./src/components/AidpLinks.astro",
+    "./components/AidpContent.astro": "./src/components/AidpContent.astro"
+  },
+  "files": [
+    "dist",
+    "src/components"
+  ],
+  "dependencies": {
+    "ofetch": "^1.4.1"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "astro": "^5.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^17.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "generate:version": "node scripts/generate-version.mjs",
+    "build": "pnpm generate:version && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "test": "pnpm generate:version && vitest run --passWithNoTests",
+    "test:types": "pnpm generate:version && tsc --noEmit"
+  }
+}

package/src/components/AidpContent.astro

@@ -0,0 +1,23 @@
+---
+import { readConfig } from '../runtime/config'
+import { registerContent } from '../runtime/server/utils/content-registry'
+
+interface Props {
+  contentId: string
+  /** Path the AI crawler will hit. Required so the middleware can
+   *  enrich subsequent impressions with content_id. */
+  pathname: string
+}
+
+const { contentId, pathname } = Astro.props
+const config = readConfig()
+const stripTrailingSlash = (s: string) => (s.endsWith('/') ? s.slice(0, -1) : s)
+const href = config.siteOrigin && contentId
+  ? `${stripTrailingSlash(config.siteOrigin)}/.well-known/aidp/content/${encodeURIComponent(contentId)}.json`
+  : null
+
+if (pathname && contentId) {
+  registerContent(pathname, contentId)
+}
+---
+{href && <link rel="aidp-content" href={href} />}

package/src/components/AidpLinks.astro

@@ -0,0 +1,10 @@
+---
+import { readConfig } from '../runtime/config'
+
+const config = readConfig()
+const stripTrailingSlash = (s: string) => (s.endsWith('/') ? s.slice(0, -1) : s)
+const entityHref = config.siteOrigin ? `${stripTrailingSlash(config.siteOrigin)}/.well-known/aidp.json` : null
+const keysHref = config.endpoint ? `${stripTrailingSlash(config.endpoint)}/.well-known/aidp-keys` : null
+---
+{entityHref && <link rel="aidp" href={entityHref} />}
+{keysHref && <link rel="aidp-keys" href={keysHref} />}