@speakspec/astro 0.0.1

package/dist/runtime/server/utils/bot-detect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Crawler "source" buckets. Logged alongside the matched label so
+ * observability dashboards can filter by trust provider without
+ * maintaining a separate mapping table.
+ */
+export type CrawlerSource = 'openai' | 'anthropic' | 'perplexity' | 'google' | 'commoncrawl' | 'bytedance' | 'cohere' | 'diffbot' | 'apple' | 'meta';
+export interface CrawlerMatch {
+    /** Lowercased label identifying the matched crawler. */
+    label: string;
+    /** Trust provider / vendor bucket — useful for log-side aggregation. */
+    source: CrawlerSource;
+}
+/**
+ * Returns the matched crawler label when `ua` looks like a known AI
+ * bot, or `null` otherwise. Empty / undefined input always returns
+ * null (we don't classify unknown UAs).
+ */
+export declare function detectAICrawler(ua: string | null | undefined): CrawlerMatch | null;
+/** Returns true when `ua` matches any known AI crawler pattern. */
+export declare function isAICrawler(ua: string | null | undefined): boolean;
+/**
+ * Returns true when `path` matches any of the `excludePaths` prefixes.
+ * Comparison is exact-prefix; trailing slashes on the configured
+ * prefix are tolerated.
+ */
+export declare function isExcludedPath(path: string, excludePaths?: string[]): boolean;

package/dist/runtime/server/utils/bot-detect.js

@@ -0,0 +1,75 @@
+// Pure helper: classify a User-Agent string as an AI crawler when it
+// matches one of the known patterns. Used by the opt-in middleware
+// at `src/runtime/server/middleware/ai-bot-detect.ts` to surface
+// structured impressions for AI traffic.
+//
+// Patterns ordered most-specific-first to keep the match label
+// useful: e.g. `GPTBot/1.0` returns `gptbot`, not the generic
+// `chatgpt-user`. Patterns are matched case-insensitively.
+//
+// Sources for the canonical UA strings:
+//   - OpenAI:    https://platform.openai.com/docs/bots
+//   - Anthropic: https://docs.anthropic.com/en/docs/about-claude/claude-bot
+//   - Google AI: https://developers.google.com/search/docs/crawling-indexing/google-extended
+//   - Perplexity: https://docs.perplexity.ai/guides/bots
+//   - Common Crawl + Bytedance / Cohere / Diffbot: industry references
+const PATTERNS = [
+    // OpenAI
+    { label: 'gptbot', source: 'openai', regex: /\bGPTBot\b/i },
+    { label: 'chatgpt-user', source: 'openai', regex: /\bChatGPT-User\b/i },
+    { label: 'oai-searchbot', source: 'openai', regex: /\bOAI-SearchBot\b/i },
+    // Anthropic
+    { label: 'claudebot', source: 'anthropic', regex: /\bClaudeBot\b/i },
+    { label: 'claude-web', source: 'anthropic', regex: /\bClaude-Web\b/i },
+    { label: 'anthropic-ai', source: 'anthropic', regex: /\bAnthropic-AI\b/i },
+    // Perplexity
+    { label: 'perplexitybot', source: 'perplexity', regex: /\bPerplexityBot\b/i },
+    // Google AI
+    { label: 'google-extended', source: 'google', regex: /\bGoogle-Extended\b/i },
+    // Common Crawl (training data)
+    { label: 'ccbot', source: 'commoncrawl', regex: /\bCCBot\b/i },
+    // ByteDance
+    { label: 'bytespider', source: 'bytedance', regex: /\bBytespider\b/i },
+    // Cohere
+    { label: 'cohere-ai', source: 'cohere', regex: /\bcohere-ai\b/i },
+    // Diffbot (used by some LLM data pipelines)
+    { label: 'diffbot', source: 'diffbot', regex: /\bDiffbot\b/i },
+    // Apple
+    { label: 'applebot-extended', source: 'apple', regex: /\bApplebot-Extended\b/i },
+    // Meta
+    { label: 'meta-externalagent', source: 'meta', regex: /\bmeta-externalagent\b/i },
+];
+/**
+ * Returns the matched crawler label when `ua` looks like a known AI
+ * bot, or `null` otherwise. Empty / undefined input always returns
+ * null (we don't classify unknown UAs).
+ */
+export function detectAICrawler(ua) {
+    if (!ua)
+        return null;
+    for (const { label, source, regex } of PATTERNS) {
+        if (regex.test(ua)) {
+            return { label, source };
+        }
+    }
+    return null;
+}
+/** Returns true when `ua` matches any known AI crawler pattern. */
+export function isAICrawler(ua) {
+    return detectAICrawler(ua) !== null;
+}
+/**
+ * Returns true when `path` matches any of the `excludePaths` prefixes.
+ * Comparison is exact-prefix; trailing slashes on the configured
+ * prefix are tolerated.
+ */
+export function isExcludedPath(path, excludePaths = []) {
+    for (const raw of excludePaths) {
+        if (!raw)
+            continue;
+        const prefix = raw.endsWith('/') ? raw : raw + '/';
+        if (path === raw || path.startsWith(prefix))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,35 @@
+export interface CachedBundle<T = unknown> {
+    payload: T;
+    etag: string;
+    expiresAt: number;
+}
+export declare const DEFAULT_CACHE_TTL_MS: number;
+export declare function cacheKey(scope: string, id: string): string;
+export declare function isFresh<T>(bundle: CachedBundle<T> | null): boolean;
+/**
+ * RFC 7232 §2.3.2 weak comparison. Strips any `W/` prefix on either
+ * side before comparing the opaque value. Wildcard `*` is NOT
+ * supported (treated as literal); AIDP agents send specific tags.
+ */
+export declare function etagMatches(inbound: string | undefined | null, current: string | undefined | null): boolean;
+/**
+ * True when `err` looks like a fetch failure with a 4xx status.
+ * Used by route handlers to distinguish operator-action errors
+ * (bad apiKey, removed entity) from transient outages — the former
+ * surface as 502 with detail; the latter serve stale.
+ */
+export declare function isUpstream4xx(err: unknown): boolean;
+export interface CacheStorage {
+    removeItem: (key: string) => Promise<unknown>;
+    getKeys: (base: string) => Promise<string[]>;
+}
+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`).
+ *
+ * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1.
+ */
+export declare function respondWithCache<T>(etag: string, payload: T, cacheControl: string, inboundIfNoneMatch: string | undefined | null): Response;

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

@@ -0,0 +1,80 @@
+// Pure cache helpers for the AIDP SDK's framework-agnostic route
+// handlers (used by both `@speakspec/next` and `@speakspec/astro`).
+//
+// Storage IO is pluggable — these hosts don't expose a built-in
+// storage primitive like Nitro's `useStorage`, so this module stays
+// framework-free and accepts any object satisfying the `CacheStorage`
+// interface. Default implementations (in-memory map, fs-backed, Redis)
+// are exposed from `./cache-store`.
+export const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+export function cacheKey(scope, id) {
+    return `${scope}:${id}`;
+}
+export function isFresh(bundle) {
+    return !!bundle && bundle.expiresAt > Date.now();
+}
+/**
+ * RFC 7232 §2.3.2 weak comparison. Strips any `W/` prefix on either
+ * side before comparing the opaque value. Wildcard `*` is NOT
+ * supported (treated as literal); AIDP agents send specific tags.
+ */
+export function etagMatches(inbound, current) {
+    if (!inbound || !current)
+        return false;
+    const norm = (e) => (e.startsWith('W/') ? e.slice(2) : e).trim();
+    return norm(inbound) === norm(current);
+}
+/**
+ * True when `err` looks like a fetch failure with a 4xx status.
+ * Used by route handlers to distinguish operator-action errors
+ * (bad apiKey, removed entity) from transient outages — the former
+ * surface as 502 with detail; the latter serve stale.
+ */
+export function isUpstream4xx(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const status = err.response?.status
+        ?? err.statusCode;
+    return typeof status === 'number' && status >= 400 && status < 500;
+}
+export async function invalidateEntityCache(storage, slug) {
+    await storage.removeItem(cacheKey('entity', slug));
+    for (const prefix of [cacheKey('content', `${slug}:`), cacheKey('directory', `${slug}:`)]) {
+        const keys = await storage.getKeys(prefix);
+        for (const key of keys) {
+            await storage.removeItem(key);
+        }
+    }
+}
+export async function invalidateContentCache(storage, slug, contentId) {
+    await storage.removeItem(cacheKey('content', `${slug}:${contentId}`));
+    const dirPrefix = cacheKey('directory', `${slug}:`);
+    const keys = await storage.getKeys(dirPrefix);
+    for (const key of keys) {
+        await storage.removeItem(key);
+    }
+}
+/**
+ * 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`).
+ *
+ * 304 responses still carry ETag + Cache-Control per RFC 7232 §4.1.
+ */
+export function respondWithCache(etag, payload, cacheControl, inboundIfNoneMatch) {
+    const headers = {
+        'cache-control': cacheControl,
+    };
+    if (etag)
+        headers.etag = etag;
+    if (etagMatches(inboundIfNoneMatch, etag)) {
+        return new Response(null, { status: 304, headers });
+    }
+    return new Response(JSON.stringify(payload), {
+        status: 200,
+        headers: {
+            ...headers,
+            'content-type': 'application/json; charset=utf-8',
+        },
+    });
+}

package/dist/runtime/server/utils/content-registry.d.ts

@@ -0,0 +1,3 @@
+export declare function registerContent(path: string, contentId: string): void;
+export declare function lookupContentId(path: string): string | undefined;
+export declare function clearContentRegistry(): void;

package/dist/runtime/server/utils/content-registry.js

@@ -0,0 +1,24 @@
+// In-memory map: path → content_id, populated by the SDK's content
+// helper on SSR-render and read by the bot-detect middleware on
+// subsequent crawler requests so impressions can be enriched with
+// content_id.
+//
+// First-request limitation: the middleware fires BEFORE the page
+// renders, so the very first hit on a path has no registered
+// content_id. AI agents typically revisit; later hits get enriched.
+//
+// Module-scoped Map persists for the lifetime of the host process.
+// In serverless cold-start scenarios the registry resets — acceptable
+// for the analytics signal.
+const pathToContentId = new Map();
+export function registerContent(path, contentId) {
+    if (!path || !contentId)
+        return;
+    pathToContentId.set(path, contentId);
+}
+export function lookupContentId(path) {
+    return pathToContentId.get(path);
+}
+export function clearContentRegistry() {
+    pathToContentId.clear();
+}

package/dist/runtime/server/utils/fetch-content.d.ts

@@ -0,0 +1,14 @@
+export interface FetchContentOptions {
+    endpoint: string;
+    entityId: string;
+    contentId: string;
+    apiKey?: string;
+    ifNoneMatch?: string;
+    timeoutMs?: number;
+}
+export interface FetchContentResult {
+    payload: Record<string, unknown> | null;
+    etag: string;
+    notModified: boolean;
+}
+export declare function fetchContentEnvelope(opts: FetchContentOptions): Promise<FetchContentResult>;

package/dist/runtime/server/utils/fetch-content.js

@@ -0,0 +1,53 @@
+// Fetches a signed Content envelope (§8.7) from SpeakSpec for a single
+// (entity, content) pair. The envelope already contains the directive
+// overlay, body, media, links, and (when an active signing key exists
+// upstream) a _proof. The SDK serves the result at
+// /.well-known/aidp/content/{id}.json on the customer's own domain.
+//
+// SpeakSpec's public per-content envelope route is:
+//   GET {endpoint}/public/entity/{entityId}/content/{contentId}/publish.json
+//
+// Authentication is OPTIONAL — the upstream endpoint accepts requests
+// without an API key, but we attach Authorization when configured so
+// usage shows up under the customer's account in SpeakSpec analytics.
+import { ofetch, FetchError } from 'ofetch';
+import { SDK_USER_AGENT } from '../../version';
+export async function fetchContentEnvelope(opts) {
+    const url = `${stripTrailingSlash(opts.endpoint)}/public/entity/${encodeURIComponent(opts.entityId)}/content/${encodeURIComponent(opts.contentId)}/publish.json`;
+    const headers = {
+        'User-Agent': SDK_USER_AGENT,
+        'Accept': 'application/json',
+    };
+    if (opts.apiKey) {
+        headers.Authorization = `Bearer ${opts.apiKey}`;
+    }
+    if (opts.ifNoneMatch) {
+        headers['If-None-Match'] = opts.ifNoneMatch;
+    }
+    try {
+        const response = await ofetch.raw(url, {
+            method: 'GET',
+            headers,
+            retry: 0,
+            timeout: opts.timeoutMs ?? 5000,
+        });
+        return {
+            payload: response._data ?? null,
+            etag: response.headers.get('etag') ?? '',
+            notModified: false,
+        };
+    }
+    catch (err) {
+        if (err instanceof FetchError && err.response?.status === 304) {
+            return {
+                payload: null,
+                etag: err.response.headers.get('etag') ?? opts.ifNoneMatch ?? '',
+                notModified: true,
+            };
+        }
+        throw err;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}

package/dist/runtime/server/utils/fetch-directive.d.ts

@@ -0,0 +1,21 @@
+export interface FetchOptions {
+    endpoint: string;
+    entityId: string;
+    apiKey?: string;
+    /** Existing ETag, sent as If-None-Match for conditional fetch. */
+    ifNoneMatch?: string;
+    /** SSR-time fetch budget. Defaults to 5s — long enough to absorb
+     * typical TLS/DNS latency, short enough that a slow upstream cannot
+     * block downstream rendering past one normal request budget.
+     */
+    timeoutMs?: number;
+}
+export interface FetchResult {
+    /** Parsed AIDP entity directive payload, OR null on 304. */
+    payload: Record<string, unknown> | null;
+    /** Server-issued ETag for next round-trip; empty string if missing. */
+    etag: string;
+    /** True when the upstream returned 304 — caller keeps cached payload. */
+    notModified: boolean;
+}
+export declare function fetchEntityDirective(opts: FetchOptions): Promise<FetchResult>;

package/dist/runtime/server/utils/fetch-directive.js

@@ -0,0 +1,52 @@
+// Fetches the customer's entity directive from SpeakSpec. The SDK
+// serves the result at /.well-known/aidp.json on the customer's own
+// domain (per AIDP 0.3 §8.5). All fetches are SSR-time only — never
+// build-time baked, so directive changes propagate within one cache
+// TTL plus eventual webhook invalidation (Step 3.1.5).
+//
+// SpeakSpec's public entity-directive route is:
+//   GET {endpoint}/public/entity/{entityId}
+// Authentication is OPTIONAL (the route is publicly readable); we
+// pass an Authorization header anyway so usage shows up under the
+// customer's API key in SpeakSpec analytics.
+import { ofetch, FetchError } from 'ofetch';
+import { SDK_USER_AGENT } from '../../version';
+export async function fetchEntityDirective(opts) {
+    const url = `${stripTrailingSlash(opts.endpoint)}/public/entity/${encodeURIComponent(opts.entityId)}`;
+    const headers = {
+        'User-Agent': SDK_USER_AGENT,
+        'Accept': 'application/json',
+    };
+    if (opts.apiKey) {
+        headers.Authorization = `Bearer ${opts.apiKey}`;
+    }
+    if (opts.ifNoneMatch) {
+        headers['If-None-Match'] = opts.ifNoneMatch;
+    }
+    try {
+        const response = await ofetch.raw(url, {
+            method: 'GET',
+            headers,
+            retry: 0,
+            timeout: opts.timeoutMs ?? 5000,
+        });
+        return {
+            payload: response._data ?? null,
+            etag: response.headers.get('etag') ?? '',
+            notModified: false,
+        };
+    }
+    catch (err) {
+        if (err instanceof FetchError && err.response?.status === 304) {
+            return {
+                payload: null,
+                etag: err.response.headers.get('etag') ?? opts.ifNoneMatch ?? '',
+                notModified: true,
+            };
+        }
+        throw err;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}

package/dist/runtime/server/utils/fetch-directory.d.ts

@@ -0,0 +1,21 @@
+export interface FetchDirectoryOptions {
+    endpoint: string;
+    entityId: string;
+    apiKey?: string;
+    page?: number;
+    pageSize?: number;
+    contentType?: string;
+    /** §8.8 optional filter: BCP 47 language tag. */
+    language?: string;
+    /** §8.8 optional filter: RFC 3339 timestamp; only items updated
+     *  strictly after this point are returned. */
+    updatedSince?: string;
+    ifNoneMatch?: string;
+    timeoutMs?: number;
+}
+export interface FetchDirectoryResult {
+    payload: Record<string, unknown> | null;
+    etag: string;
+    notModified: boolean;
+}
+export declare function fetchContentDirectory(opts: FetchDirectoryOptions): Promise<FetchDirectoryResult>;

package/dist/runtime/server/utils/fetch-directory.js

@@ -0,0 +1,59 @@
+// Fetches the paginated content directory (§8.8) from SpeakSpec.
+// SDK serves the result at /.well-known/aidp/content/ on the
+// customer's own domain. The directory itself is not signed (per the
+// proposal, security boundary is per-content envelopes); this fetcher
+// is a thin proxy with the same User-Agent / auth / 304 handling as
+// the entity-directive and content-envelope fetchers.
+import { ofetch, FetchError } from 'ofetch';
+import { SDK_USER_AGENT } from '../../version';
+export async function fetchContentDirectory(opts) {
+    const base = `${stripTrailingSlash(opts.endpoint)}/public/entity/${encodeURIComponent(opts.entityId)}/content/directory.json`;
+    const params = new URLSearchParams();
+    if (typeof opts.page === 'number')
+        params.set('page', String(opts.page));
+    if (typeof opts.pageSize === 'number')
+        params.set('page_size', String(opts.pageSize));
+    if (opts.contentType)
+        params.set('type', opts.contentType);
+    if (opts.language)
+        params.set('language', opts.language);
+    if (opts.updatedSince)
+        params.set('updated_since', opts.updatedSince);
+    const url = params.size > 0 ? `${base}?${params.toString()}` : base;
+    const headers = {
+        'User-Agent': SDK_USER_AGENT,
+        'Accept': 'application/json',
+    };
+    if (opts.apiKey) {
+        headers.Authorization = `Bearer ${opts.apiKey}`;
+    }
+    if (opts.ifNoneMatch) {
+        headers['If-None-Match'] = opts.ifNoneMatch;
+    }
+    try {
+        const response = await ofetch.raw(url, {
+            method: 'GET',
+            headers,
+            retry: 0,
+            timeout: opts.timeoutMs ?? 5000,
+        });
+        return {
+            payload: response._data ?? null,
+            etag: response.headers.get('etag') ?? '',
+            notModified: false,
+        };
+    }
+    catch (err) {
+        if (err instanceof FetchError && err.response?.status === 304) {
+            return {
+                payload: null,
+                etag: err.response.headers.get('etag') ?? opts.ifNoneMatch ?? '',
+                notModified: true,
+            };
+        }
+        throw err;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}

package/dist/runtime/server/utils/hmac-verify.d.ts

@@ -0,0 +1,37 @@
+export interface VerifyOptions {
+    /** Pre-shared secret from `runtimeConfig.speakspec.webhookSecret`. */
+    secret: string;
+    /** `X-AIDP-Timestamp` header value (RFC 3339). */
+    timestamp: string;
+    /** Raw request body bytes (UTF-8 string). */
+    body: string;
+    /** `X-AIDP-Signature` header value (`hmac-sha256={hex}`). */
+    signature: string;
+}
+/**
+ * Returns the canonical signature string for (secret, timestamp, body).
+ * Used by `verifyHmacSignature` and exposed for tests / golden fixtures.
+ */
+export declare function computeSignature(secret: string, timestamp: string, body: string): string;
+/**
+ * Constant-time signature comparison. Returns false on any mismatch,
+ * empty secret, or unequal length.
+ */
+export declare function verifyHmacSignature(opts: VerifyOptions): boolean;
+/**
+ * Returns true when `timestamp` parses as ISO 8601 and falls within
+ * `windowMs` of the current wall clock. Default window 5 minutes
+ * matches the spec recommendation; SDK consumers can tighten it via
+ * the optional argument if their delivery latency is consistently
+ * sub-minute.
+ */
+export declare function isTimestampFresh(timestamp: string, windowMs?: number): boolean;
+/**
+ * Strip the `urn:aidp:entity:` URN prefix to recover the bare slug.
+ * If the input doesn't match the URN form, returns it unchanged. The
+ * result is validated against the canonical slug rule and rejected
+ * with a descriptive error when malformed — that way a future server
+ * change to a different URN scheme (e.g. `urn:speakspec:entity:foo`)
+ * fails loudly here instead of writing junk into the cache namespace.
+ */
+export declare function urnToSlug(entityId: string): string;

package/dist/runtime/server/utils/hmac-verify.js

@@ -0,0 +1,63 @@
+// HMAC verification for AIDP §8.10 cache-invalidation webhooks.
+//
+// Spec mandates HMAC-SHA256 over `${X-AIDP-Timestamp}\n${raw body}`,
+// presented as the header `X-AIDP-Signature: hmac-sha256={hex}`. We
+// recompute the signature against the SDK's configured webhookSecret
+// and compare in constant time. Timestamp is also bounded to ±5 min
+// (default) so a captured webhook cannot be replayed days later.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const SIGNATURE_PREFIX = 'hmac-sha256=';
+/**
+ * Returns the canonical signature string for (secret, timestamp, body).
+ * Used by `verifyHmacSignature` and exposed for tests / golden fixtures.
+ */
+export function computeSignature(secret, timestamp, body) {
+    const mac = createHmac('sha256', secret);
+    mac.update(timestamp + '\n' + body);
+    return SIGNATURE_PREFIX + mac.digest('hex');
+}
+/**
+ * Constant-time signature comparison. Returns false on any mismatch,
+ * empty secret, or unequal length.
+ */
+export function verifyHmacSignature(opts) {
+    if (!opts.secret || !opts.signature)
+        return false;
+    const expected = computeSignature(opts.secret, opts.timestamp, opts.body);
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(opts.signature, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * Returns true when `timestamp` parses as ISO 8601 and falls within
+ * `windowMs` of the current wall clock. Default window 5 minutes
+ * matches the spec recommendation; SDK consumers can tighten it via
+ * the optional argument if their delivery latency is consistently
+ * sub-minute.
+ */
+export function isTimestampFresh(timestamp, windowMs = 5 * 60 * 1000) {
+    const ts = Date.parse(timestamp);
+    if (Number.isNaN(ts))
+        return false;
+    return Math.abs(Date.now() - ts) <= windowMs;
+}
+// Slug rule mirrors aidp-server's slug_validator.go: lowercase
+// alphanumerics and hyphens, no leading or trailing hyphen.
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Strip the `urn:aidp:entity:` URN prefix to recover the bare slug.
+ * If the input doesn't match the URN form, returns it unchanged. The
+ * result is validated against the canonical slug rule and rejected
+ * with a descriptive error when malformed — that way a future server
+ * change to a different URN scheme (e.g. `urn:speakspec:entity:foo`)
+ * fails loudly here instead of writing junk into the cache namespace.
+ */
+export function urnToSlug(entityId) {
+    const slug = entityId.replace(/^urn:aidp:entity:/, '');
+    if (!SLUG_RE.test(slug)) {
+        throw new Error(`urnToSlug: "${entityId}" did not produce a valid AIDP slug (got "${slug}")`);
+    }
+    return slug;
+}

package/dist/runtime/server/utils/impression-queue.d.ts

@@ -0,0 +1,33 @@
+export interface ImpressionRecord {
+    msg: string;
+    crawler: string;
+    crawler_source: string;
+    path: string;
+    user_agent: string;
+    ts: string;
+    entity_id?: string;
+    content_id?: string;
+    client_ip?: string;
+}
+export interface QueueConfig {
+    endpoint: string;
+    apiKey: string;
+    batchSize: number;
+    flushIntervalMs: number;
+    maxQueueBytes: number;
+    onError: 'fallback-stdout' | 'silent';
+    /** Override for tests; default uses global fetch. */
+    fetcher?: typeof fetch;
+    /** Override for tests; default uses console.log. */
+    logger?: (line: string) => void;
+}
+export declare function configureQueue(cfg: QueueConfig): void;
+export declare function resetQueue(): void;
+export declare function enqueueImpression(impression: ImpressionRecord): void;
+export declare function flushQueue(): Promise<void>;
+export declare function _peekQueue(): {
+    count: number;
+    bytes: number;
+    consecutiveFailures: number;
+    backoffUntil: number;
+};