@storystick/client 0.0.0-stage → 0.2.0-rc.0

package/dist/resolve-route.js

@@ -0,0 +1,145 @@
+/**
+ * `resolveStorystickPage` — core URL → document resolver (ADR-094 §1).
+ *
+ * Takes a configured client and a pathname (and optional storytype filter),
+ * dispatches a SINGLE call to the backend `queries:getRouteByPathname`
+ * cross-storytype endpoint (Lane A0), and returns a discriminated
+ * {@link ResolvedRoute}.
+ *
+ * Single-call semantics: the backend resolves cross-storytype via the
+ * `by_projectId_resolvedPathname` index (ADR-086 URL-uniqueness invariant);
+ * no SDK-side fan-out across storytypes. 1 indexed call per invocation,
+ * regardless of how many storytypes the project declares.
+ *
+ * Production vs preview parity is JWT-driven — the configured client's
+ * `requestContext.previewToken` (when set) routes the underlying transport
+ * to the preview JWT; otherwise the API-key mint cache supplies the
+ * production JWT (audit P1-1).
+ */
+import { attachDocumentLocaleRouting, publicHrefForLocale, resolveLocalePathname } from './locale-routing.js';
+import { getInternalClientRuntime } from './query-client.js';
+import { normalizePathname } from './normalize-pathname.js';
+import { attachPublicRouteIdentity } from './public-delivery.js';
+import { hasUsablePreviewToken, withPreviewVariantArgs } from './preview-scope.js';
+import { attachPreviewFrameDependencies, previewAssetDependenciesFromValue, } from './preview-frame-dependencies.js';
+import { createPreviewProvenanceReadCacheKey, runPreviewProvenanceReadLifecycle, } from './preview-read-lifecycle.js';
+/**
+ * Resolve a developer-supplied pathname to a `ResolvedRoute` discriminated
+ * union. Throws on infrastructure failures (auth, network, gateway 5xx) —
+ * the return shape only models *resolution outcomes*, never failures
+ * (per ADR-094 §1 error strategy).
+ */
+export async function resolveStorystickPage(client, input) {
+    // ADR-094 §1 storyTypes semantics — empty array is rejected as
+    // INVALID_ARGS. The almost-always-a-bug case (developer forgot to
+    // populate the list) gets a clear error rather than silently
+    // returning notFound.
+    if (input.storyTypes !== undefined && input.storyTypes.length === 0) {
+        throw new Error('StorystickError: resolveStorystickPage was called with `storyTypes: []` ' +
+            '(empty array). Empty storyTypes is rejected as INVALID_ARGS — pass a non-empty array ' +
+            'to filter to specific types, or omit the argument entirely to resolve any URL-routable storytype. ' +
+            'See ADR-094 §1 storyTypes semantics.');
+    }
+    const canonical = normalizePathname(input.pathname);
+    const runtime = getInternalClientRuntime(client);
+    // Dispatch a single cross-storytype call via the configured client's
+    // transport. We don't go through a generated story query because this helper
+    // isn't bound to a single storytype — the backend resolves any URL-routable
+    // type that matches the canonical pathname (ADR-094 §1.bis).
+    const args = { pathname: canonical, ...(input.locale ? { locale: input.locale } : {}) };
+    if (input.storyTypes && input.storyTypes.length > 0) {
+        args.storyTypes = [...input.storyTypes];
+    }
+    return runPreviewProvenanceReadLifecycle(runtime.requestContext, {
+        kind: 'resolved-route',
+        cacheKey: createPreviewProvenanceReadCacheKey('resolved-route', {
+            pathname: canonical,
+            locale: input.locale,
+            publicOrigins: runtime.localeRouting?.publicOrigins,
+            storyTypes: input.storyTypes ? [...input.storyTypes].sort() : undefined,
+        }),
+        executeRaw: async () => {
+            const response = await runtime.transport.request({
+                udfPath: 'queries:getRouteByPathname',
+                args: withPreviewVariantArgs('queries:getRouteByPathname', args, runtime.requestContext),
+                options: undefined,
+                requestContext: runtime.requestContext,
+                signal: undefined,
+            });
+            const data = response.data;
+            if (!data)
+                return { type: 'notFound' };
+            if ('notFound' in data) {
+                return {
+                    type: 'notFound',
+                    ...(data.localeContext ? { localeContext: siteLocaleContext(data.localeContext, runtime.localeRouting?.publicOrigins) } : {}),
+                };
+            }
+            if ('redirectTo' in data) {
+                let redirectTo = data.redirectTo;
+                if (runtime.localeRouting?.publicOrigins && redirectTo.startsWith('/') && !redirectTo.startsWith('//')) {
+                    const resolved = resolveLocalePathname(redirectTo, runtime.localeRouting);
+                    if (!resolved.ok)
+                        throw new TypeError('Invalid published redirect locale.');
+                    const suffix = redirectTo.match(/[?#].*$/)?.[0] ?? '';
+                    redirectTo = publicHrefForLocale(resolved.pathname, resolved.locale, runtime.localeRouting) + suffix;
+                }
+                return {
+                    type: 'redirect',
+                    redirectTo,
+                    permanent: data.permanent === true,
+                };
+            }
+            if (hasUsablePreviewToken(runtime.requestContext)) {
+                attachPreviewFrameDependencies(data.document, [
+                    ...routeDependencies({
+                        pathname: canonical,
+                        storyTypes: input.storyTypes,
+                        document: data.document,
+                        storyType: data.storyType,
+                    }),
+                    ...previewAssetDependenciesFromValue(data.document),
+                ]);
+            }
+            const localeContext = siteLocaleContext(data.localeContext, runtime.localeRouting?.publicOrigins);
+            attachDocumentLocaleRouting(data.document, localeContext);
+            if (!hasUsablePreviewToken(runtime.requestContext))
+                attachPublicRouteIdentity(data.document, response.publicReadIdentity);
+            return {
+                type: 'document',
+                document: data.document,
+                storyType: data.storyType,
+                canonicalPathname: data.localeContext.pathname,
+                publicPathname: localeContext.publicPathname,
+                localeContext,
+                primaryLocale: data.primaryLocale,
+                alternates: data.alternates,
+                seo: data.seo ?? { indexable: true },
+            };
+        },
+    });
+}
+function routeDependencies(input) {
+    return [
+        {
+            kind: 'route-lookup',
+            pathname: input.pathname,
+            ...(input.storyTypes && input.storyTypes.length > 0
+                ? { storyTypes: [...input.storyTypes].sort() }
+                : {}),
+        },
+        {
+            kind: 'document',
+            documentId: input.document.documentId,
+            storyType: input.storyType,
+            reason: 'route-document',
+        },
+    ];
+}
+function siteLocaleContext(context, publicOrigins) {
+    return {
+        ...context,
+        ...(publicOrigins ? { publicOrigins } : {}),
+        ...(publicOrigins?.[context.locale] ? { publicPathname: '/' + context.pathname.replace(/^\/+/, '') } : {}),
+    };
+}

package/dist/resolve.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Project shortId resolution
+ *
+ * Resolves a project shortId (8-char Crockford, e.g. `a3k9m2x7`) to its
+ * infrastructure config (endpoint, metadata, plan, features) via the
+ * Storystick gateway API.
+ *
+ * Post ADR-063 (Wave 2): the public project identifier is the shortId.
+ * The same identifier appears in URLs (`/p/<label>-<shortId>`), SDK
+ * config (`STORYSTICK_PROJECT_ID=<shortId>`), API key prefixes, logs,
+ * and support lookups. Previous slug-based config has been removed.
+ *
+ * Post multi-tenant refactor (ADR-058): the gateway returns `endpoint`
+ * (the Storystick gateway URL — same for all tenants) + tenant-scoped
+ * metadata. Tenant isolation is carried by a JWT claim that the gateway
+ * mints from the caller's API key server-side — the SDK does not need
+ * to know the internal Convex id.
+ *
+ * Used by:
+ * - generated clients that need endpoint discovery
+ * - @storystick/next server helpers (server-side, cached in memory)
+ */
+export interface ProjectConfig {
+    /** Storystick gateway endpoint.
+     *  Same URL for every project on this Storystick deployment. */
+    readonly endpoint: string;
+    /** Public project identifier — the 8-char Crockford shortId that
+     *  appears in URLs, SDK env config, API key prefixes, logs. */
+    readonly projectId: string;
+    readonly name: string;
+    readonly plan: string;
+    readonly features: Readonly<Record<string, boolean>>;
+}
+/**
+ * Resolve a project shortId to its config.
+ *
+ * Client-side: caches in sessionStorage (survives page navigations).
+ * Server-side: caches in module-level Map (expires after five minutes).
+ *
+ *   const config = await resolveProject('a3k9m2x7')
+ *   // → { endpoint: 'https://...', projectId: 'a3k9m2x7', plan: 'free', ... }
+ */
+export declare function resolveProject(projectId: string, gatewayUrl?: string): Promise<ProjectConfig>;

package/dist/resolve.js

@@ -0,0 +1,160 @@
+import { STORYSTICK_GATEWAY_ORIGIN } from '@storystick/types/public-endpoints';
+// ─────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────
+const DEFAULT_GATEWAY_URL = STORYSTICK_GATEWAY_ORIGIN;
+const PROJECT_CACHE_PREFIX = 'storystick:project:v1:';
+const PROJECT_CACHE_TTL_MS = 5 * 60 * 1000;
+// Module-level cache for server-side (bounded and refreshed after five minutes)
+const PROJECT_CACHE_MAX_ENTRIES = 128;
+const _cache = new Map();
+const inFlight = new Map();
+// ─────────────────────────────────────────────
+// Resolution
+// ─────────────────────────────────────────────
+/**
+ * Resolve a project shortId to its config.
+ *
+ * Client-side: caches in sessionStorage (survives page navigations).
+ * Server-side: caches in module-level Map (expires after five minutes).
+ *
+ *   const config = await resolveProject('a3k9m2x7')
+ *   // → { endpoint: 'https://...', projectId: 'a3k9m2x7', plan: 'free', ... }
+ */
+export async function resolveProject(projectId, gatewayUrl) {
+    const gateway = gatewayUrl ?? DEFAULT_GATEWAY_URL;
+    // ADR-131 C9 codex R3 P2 fix : the cache key must include the gateway
+    // URL so that a self-host customer passing a non-default `gatewayUrl`
+    // does not get the default-gateway-resolved config back from the cache.
+    // The same shortId resolved through different gateways yields different
+    // endpoint/plan/features rows.
+    const cacheKey = `${projectId}::${gateway}`;
+    const cached = getFromCache(cacheKey, projectId);
+    if (cached)
+        return cached;
+    const pending = inFlight.get(cacheKey);
+    if (pending)
+        return pending;
+    const request = fetchProject(projectId, gateway, cacheKey);
+    // Bound bookkeeping even when a discovery endpoint is unavailable.
+    if (inFlight.size < PROJECT_CACHE_MAX_ENTRIES)
+        inFlight.set(cacheKey, request);
+    try {
+        return await request;
+    }
+    finally {
+        if (inFlight.get(cacheKey) === request)
+            inFlight.delete(cacheKey);
+    }
+}
+async function fetchProject(projectId, gateway, cacheKey) {
+    const url = `${gateway}/api/projects/${encodeURIComponent(projectId)}/config`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        if (response.status === 404) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(body.message ??
+                `StorystickError: Project "${projectId}" not found.\n` +
+                    `Check your STORYSTICK_PROJECT_ID environment variable.\n`);
+        }
+        if (response.status === 503) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(body.message ??
+                `StorystickError: Project "${projectId}" has no backend provisioned.\n`);
+        }
+        throw new Error(`StorystickError: Failed to resolve project "${projectId}" (HTTP ${response.status})`);
+    }
+    // Gateway returns { endpoint, projectId: <convex _id>, name, shortId,
+    // urlLabel, plan, features }. Post-Wave-2 the SDK treats the shortId
+    // as the public projectId; the Convex `_id` stays hidden inside the
+    // gateway (used only for JWT minting + internal FK integrity).
+    const raw = await response.json();
+    if (!isRecord(raw))
+        throw new Error('StorystickError: Invalid project discovery response.');
+    const config = {
+        endpoint: raw.endpoint,
+        projectId: raw.shortId,
+        name: raw.name,
+        plan: raw.plan,
+        features: raw.features,
+    };
+    if (!isProjectConfig(config, projectId)) {
+        throw new Error('StorystickError: Invalid project discovery response.');
+    }
+    Object.freeze(config.features);
+    Object.freeze(config);
+    // Store in cache (keyed by projectId + gateway URL — see cacheKey above)
+    setInCache(cacheKey, config);
+    return config;
+}
+// ─────────────────────────────────────────────
+// Caching
+// ─────────────────────────────────────────────
+function getFromCache(cacheKey, projectId) {
+    // Server-side: module-level Map
+    if (typeof window === 'undefined') {
+        const entry = _cache.get(cacheKey);
+        if (!entry)
+            return null;
+        const age = Date.now() - entry.timestamp;
+        if (age < 0 || age >= PROJECT_CACHE_TTL_MS) {
+            _cache.delete(cacheKey);
+            return null;
+        }
+        // Least recently used entries are evicted first.
+        _cache.delete(cacheKey);
+        _cache.set(cacheKey, entry);
+        return entry.config;
+    }
+    // Client-side: sessionStorage
+    try {
+        const raw = sessionStorage.getItem(`${PROJECT_CACHE_PREFIX}${cacheKey}`);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            return null;
+        const { config, timestamp } = parsed;
+        if (typeof timestamp !== 'number' ||
+            !Number.isFinite(timestamp) ||
+            timestamp > Date.now() ||
+            Date.now() - timestamp >= PROJECT_CACHE_TTL_MS ||
+            !isProjectConfig(config, projectId))
+            return null;
+        Object.freeze(config.features);
+        return Object.freeze(config);
+    }
+    catch {
+        return null;
+    }
+}
+function setInCache(cacheKey, config) {
+    // Server-side
+    if (typeof window === 'undefined') {
+        _cache.delete(cacheKey);
+        _cache.set(cacheKey, { config, timestamp: Date.now() });
+        while (_cache.size > PROJECT_CACHE_MAX_ENTRIES)
+            _cache.delete(_cache.keys().next().value);
+        return;
+    }
+    // Client-side
+    try {
+        sessionStorage.setItem(`${PROJECT_CACHE_PREFIX}${cacheKey}`, JSON.stringify({ config, timestamp: Date.now() }));
+    }
+    catch {
+        // sessionStorage might be unavailable (private browsing, etc.)
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isProjectConfig(value, projectId) {
+    if (!isRecord(value) || !isRecord(value.features))
+        return false;
+    return typeof value.endpoint === 'string' &&
+        value.endpoint.length > 0 &&
+        value.projectId === projectId &&
+        typeof value.name === 'string' &&
+        typeof value.plan === 'string' &&
+        Object.values(value.features).every((feature) => typeof feature === 'boolean');
+}

package/dist/schemas.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Schema delivery — ADR-131 Amendment 002.
+ *
+ * Standalone wrapper around the existing `/api/q/schemas/current` HTTP
+ * route (`apps/studio/convex/gateway_queries.ts::schemasCurrent`). Auth
+ * comes from `client.requestContext.previewToken` in preview mode (the
+ * iframe runtime path) ; production callers use the same configured
+ * client and inherit the API-key mint chain.
+ *
+ * NOT exposed as `client.schemas.current()`. The client factory's Proxy
+ * treats unknown string keys as story types (see `index.ts:198`) ;
+ * adding `schemas` as a first-class namespace would require modifying
+ * the surface/type/metadata assembly. The standalone-function pattern
+ * sidesteps that and matches the existing convention for non-storytype
+ * SDK calls.
+ */
+import type { Client } from './query-client.js';
+import type { RequestOptions } from './types.js';
+import { STORY_SCHEMA_FORMAT_VERSION } from '@storystick/types';
+import { StorystickError } from './errors.js';
+export declare const SCHEMA_FORMAT_UNSUPPORTED_CODE: "storystick/SCHEMA_FORMAT_UNSUPPORTED";
+export interface SchemaFormatUnsupportedPayload {
+    expectedFormatVersion: typeof STORY_SCHEMA_FORMAT_VERSION;
+    receivedFormatVersion: number | null;
+}
+export declare function isSchemaFormatUnsupportedError(error: unknown): error is StorystickError & {
+    readonly code: typeof SCHEMA_FORMAT_UNSUPPORTED_CODE;
+    readonly payload: SchemaFormatUnsupportedPayload;
+};
+/**
+ * Shape returned by `GET /api/q/schemas/current`. For an installed
+ * generation this is its row in the `schemas` Convex table. A verified,
+ * not-yet-installed B Preview uses the same envelope with `pushedAt: 0`.
+ *
+ * The route returns the full row — the iframe schema-store keeps it
+ * verbatim to preserve fidelity for future tooling ; downstream consumers
+ * (resolver §D6.1, render-for-correlation) extract the fields they need.
+ *
+ * `null` when no schema has been pushed yet for the tenant.
+ *
+ * Additional Convex metadata (`_id`, `_creationTime`) may be present on
+ * the row at runtime ; the interface omits them for clarity. Callers
+ * that need them can read via `(row as { _id?: string })._id`.
+ */
+export interface RawSchemaRow {
+    projectId: string;
+    formatVersion: typeof STORY_SCHEMA_FORMAT_VERSION;
+    version: string;
+    stories: unknown;
+    storyCount: number;
+    zoneMappings?: unknown;
+    fieldBindings?: unknown;
+    diagnostics?: unknown;
+    pushedAt: number;
+}
+/**
+ * Fetch the schema paired to this client's signed build. Multi-tenant
+ * scoping is enforced by `gatewayTenantQuery`; the JWT's `projectId` is
+ * the structural cross-tenant boundary.
+ *
+ * Returns `null` if no schema has been pushed for the tenant.
+ *
+ * Wire path (ADR-131 Amendment 002 §3.1) :
+ *   client.transport.request({ udfPath: 'queries:schemas.current', ... })
+ *     → endpointForUdf('queries:schemas.current')
+ *     → GET /api/q/schemas/current
+ *     → authAndLimit (preview JWT OR API-key mint)
+ *     → gateway_queries::schemasCurrent
+ *     → signed generation resolution → exact schema row (or prepared target)
+ */
+export declare function fetchCurrentSchema(client: Client, options?: RequestOptions): Promise<RawSchemaRow | null>;

package/dist/schemas.js

@@ -0,0 +1,75 @@
+/**
+ * Schema delivery — ADR-131 Amendment 002.
+ *
+ * Standalone wrapper around the existing `/api/q/schemas/current` HTTP
+ * route (`apps/studio/convex/gateway_queries.ts::schemasCurrent`). Auth
+ * comes from `client.requestContext.previewToken` in preview mode (the
+ * iframe runtime path) ; production callers use the same configured
+ * client and inherit the API-key mint chain.
+ *
+ * NOT exposed as `client.schemas.current()`. The client factory's Proxy
+ * treats unknown string keys as story types (see `index.ts:198`) ;
+ * adding `schemas` as a first-class namespace would require modifying
+ * the surface/type/metadata assembly. The standalone-function pattern
+ * sidesteps that and matches the existing convention for non-storytype
+ * SDK calls.
+ */
+import { STORY_SCHEMA_FORMAT_VERSION } from '@storystick/types';
+import { StorystickError } from './errors.js';
+import { getInternalClientRuntime } from './query-client.js';
+export const SCHEMA_FORMAT_UNSUPPORTED_CODE = 'storystick/SCHEMA_FORMAT_UNSUPPORTED';
+export function isSchemaFormatUnsupportedError(error) {
+    return error instanceof StorystickError &&
+        error.code === SCHEMA_FORMAT_UNSUPPORTED_CODE;
+}
+/**
+ * Fetch the schema paired to this client's signed build. Multi-tenant
+ * scoping is enforced by `gatewayTenantQuery`; the JWT's `projectId` is
+ * the structural cross-tenant boundary.
+ *
+ * Returns `null` if no schema has been pushed for the tenant.
+ *
+ * Wire path (ADR-131 Amendment 002 §3.1) :
+ *   client.transport.request({ udfPath: 'queries:schemas.current', ... })
+ *     → endpointForUdf('queries:schemas.current')
+ *     → GET /api/q/schemas/current
+ *     → authAndLimit (preview JWT OR API-key mint)
+ *     → gateway_queries::schemasCurrent
+ *     → signed generation resolution → exact schema row (or prepared target)
+ */
+export async function fetchCurrentSchema(client, options) {
+    const runtime = getInternalClientRuntime(client);
+    const response = await runtime.transport.request({
+        udfPath: 'queries:schemas.current',
+        args: {},
+        options,
+        requestContext: runtime.requestContext,
+    });
+    if (response.data === null)
+        return null;
+    if (!response.data ||
+        typeof response.data !== 'object' ||
+        Array.isArray(response.data) ||
+        response.data.formatVersion !==
+            STORY_SCHEMA_FORMAT_VERSION) {
+        const received = response.data !== null &&
+            typeof response.data === 'object' &&
+            !Array.isArray(response.data) &&
+            typeof response.data.formatVersion ===
+                'number'
+            ? response.data.formatVersion
+            : null;
+        throw new StorystickError(`Unsupported Storystick schema format; expected V${STORY_SCHEMA_FORMAT_VERSION}, ` +
+            `received ${received === null ? 'a payload without formatVersion' : `V${received}`}.`, {
+            code: SCHEMA_FORMAT_UNSUPPORTED_CODE,
+            category: 'validation',
+            recoverable: true,
+            retryable: false,
+            payload: {
+                expectedFormatVersion: STORY_SCHEMA_FORMAT_VERSION,
+                receivedFormatVersion: received,
+            },
+        });
+    }
+    return response.data;
+}

package/dist/seo.d.ts

@@ -0,0 +1,52 @@
+import type { ResolvedRoute } from './index.js';
+import { type PublicLocaleOrigins } from './locale-routing.js';
+type ClientResolvedDocumentRoute = Extract<ResolvedRoute, {
+    type: 'document';
+}>;
+export interface ResolvedDocumentRoute {
+    readonly localeContext: ClientResolvedDocumentRoute['localeContext'];
+    readonly publicPathname: ClientResolvedDocumentRoute['publicPathname'];
+    readonly alternates: ClientResolvedDocumentRoute['alternates'];
+    readonly primaryLocale: ClientResolvedDocumentRoute['primaryLocale'];
+    readonly seo: ClientResolvedDocumentRoute['seo'];
+}
+export interface StorystickAlternatesOptions {
+    readonly siteUrl: string | URL;
+    readonly publicOrigins?: PublicLocaleOrigins;
+}
+export interface StorystickPublishedLocaleRoute {
+    readonly documentId: string;
+    readonly storyType: string;
+    readonly locale: string;
+    readonly pathname: string;
+    readonly publicPathname: string;
+    readonly defaultLocale?: string;
+    readonly primaryLocale?: string;
+    readonly seo: ClientResolvedDocumentRoute['seo'];
+}
+export interface StorystickSitemapOptions {
+    readonly locale?: string;
+    readonly siteUrl: string | URL;
+    readonly publicOrigins?: PublicLocaleOrigins;
+}
+export interface StorystickAlternates {
+    canonical?: string;
+    languages?: Record<string, string>;
+}
+export interface StorystickSitemapEntry {
+    url: string;
+    alternates?: {
+        languages: Record<string, string>;
+    };
+}
+export declare const STORYSTICK_SITEMAP_MAX_URLS = 50000;
+/**
+ * Convert a publication-backed route map to canonical and language URLs. Missing
+ * translations are absent by construction. The publication SEO posture is
+ * frozen at publish time so metadata and sitemap share one decision.
+ */
+export declare function storystickAlternates(route: ResolvedDocumentRoute, options: StorystickAlternatesOptions): StorystickAlternates | undefined;
+/** Pure mapping used by `ss.sitemap` and pinned independently in unit tests. */
+export declare function buildStorystickSitemap(routes: readonly StorystickPublishedLocaleRoute[], options: StorystickSitemapOptions): StorystickSitemapEntry[];
+export declare function buildStorystickSitemapShards(routes: readonly StorystickPublishedLocaleRoute[], options: StorystickSitemapOptions, shardSize?: number): StorystickSitemapEntry[][];
+export {};

package/dist/seo.js

@@ -0,0 +1,93 @@
+import { publicHrefForPublication, publishedLocaleHrefs, publicHrefForLocale, normalizePublicLocaleOrigins } from './locale-routing.js';
+export const STORYSTICK_SITEMAP_MAX_URLS = 50_000;
+function absoluteUrl(siteUrl, pathname) {
+    const base = new URL(siteUrl);
+    if (/^https?:\/\//.test(pathname))
+        return new URL(pathname).toString();
+    const normalizedPathname = pathname.startsWith('/') ? pathname : `/${pathname}`;
+    return new URL(normalizedPathname, base).toString();
+}
+/**
+ * Convert a publication-backed route map to canonical and language URLs. Missing
+ * translations are absent by construction. The publication SEO posture is
+ * frozen at publish time so metadata and sitemap share one decision.
+ */
+export function storystickAlternates(route, options) {
+    const settings = { ...route.localeContext, ...(options.publicOrigins ? { publicOrigins: normalizePublicLocaleOrigins(options.publicOrigins) } : {}) };
+    const currentUrl = () => absoluteUrl(options.siteUrl, publicHrefForLocale(route.localeContext.pathname, route.localeContext.locale, settings));
+    if (!route.seo.indexable) {
+        return {
+            canonical: route.seo.canonicalUrl ??
+                currentUrl(),
+        };
+    }
+    if (route.seo.canonicalUrl !== undefined) {
+        return { canonical: route.seo.canonicalUrl };
+    }
+    const publishedLanguages = Object.entries(publishedLocaleHrefs(route.alternates, settings));
+    if (publishedLanguages.length === 0)
+        return undefined;
+    const languages = Object.fromEntries(publishedLanguages.map(([locale, pathname]) => [
+        locale,
+        absoluteUrl(options.siteUrl, pathname),
+    ]));
+    const available = new Set(publishedLanguages.map(([locale]) => locale));
+    const xDefaultLocale = available.has(route.localeContext.defaultLocale)
+        ? route.localeContext.defaultLocale
+        : available.has(route.primaryLocale)
+            ? route.primaryLocale
+            : route.localeContext.locale;
+    const xDefaultPathname = languages[xDefaultLocale];
+    if (xDefaultPathname) {
+        languages['x-default'] = absoluteUrl(options.siteUrl, xDefaultPathname);
+    }
+    const canonicalPathname = languages[route.localeContext.locale];
+    return {
+        ...(canonicalPathname
+            ? { canonical: absoluteUrl(options.siteUrl, canonicalPathname) }
+            : {}),
+        languages,
+    };
+}
+/** Pure mapping used by `ss.sitemap` and pinned independently in unit tests. */
+export function buildStorystickSitemap(routes, options) {
+    const origins = options.publicOrigins ? normalizePublicLocaleOrigins(options.publicOrigins) : undefined;
+    const urlFor = (route) => absoluteUrl(options.siteUrl, publicHrefForPublication(route, origins));
+    const localRoutes = routes.filter((route) => route.seo.indexable && route.seo.canonicalUrl === undefined);
+    const byDocument = new Map();
+    for (const route of localRoutes) {
+        const cluster = byDocument.get(route.documentId) ?? [];
+        cluster.push(route);
+        byDocument.set(route.documentId, cluster);
+    }
+    return localRoutes.filter(route => !options.locale || route.locale === options.locale).map((route) => {
+        const cluster = byDocument.get(route.documentId) ?? [route];
+        if (cluster.length < 2) {
+            return { url: urlFor(route) };
+        }
+        const languages = Object.fromEntries(cluster.map((alternate) => [
+            alternate.locale,
+            urlFor(alternate),
+        ]));
+        const locales = new Set(cluster.map((alternate) => alternate.locale));
+        const defaultLocale = cluster.find((alternate) => alternate.defaultLocale !== undefined &&
+            locales.has(alternate.defaultLocale))?.defaultLocale;
+        const primaryLocale = cluster.find((alternate) => alternate.primaryLocale !== undefined &&
+            locales.has(alternate.primaryLocale))?.primaryLocale;
+        const xDefaultLocale = defaultLocale ?? primaryLocale ?? cluster[0].locale;
+        languages['x-default'] = languages[xDefaultLocale];
+        return {
+            url: urlFor(route),
+            alternates: { languages },
+        };
+    });
+}
+export function buildStorystickSitemapShards(routes, options, shardSize = STORYSTICK_SITEMAP_MAX_URLS) {
+    if (!Number.isSafeInteger(shardSize) || shardSize < 1) {
+        throw new RangeError('sitemap shardSize must be a positive integer');
+    }
+    const sitemap = buildStorystickSitemap(routes, options);
+    if (sitemap.length === 0)
+        return [[]];
+    return Array.from({ length: Math.ceil(sitemap.length / shardSize) }, (_, index) => sitemap.slice(index * shardSize, (index + 1) * shardSize));
+}

package/dist/signed-webhook.d.ts

@@ -0,0 +1,13 @@
+/** Shared HTTP boundary for framework delivery adapters. No cache or queue policy. */
+export declare function signWebhookBody(body: string, secret: string): Promise<string>;
+export declare function readSignedWebhook(request: Request, options: {
+    secret: string;
+    signatureHeader?: string;
+}): Promise<{
+    ok: true;
+    payload: unknown;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+}>;