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

package/dist/preview-read-observation.js

@@ -0,0 +1,81 @@
+/**
+ * Preview read metadata is server-render bookkeeping, not customer data.
+ *
+ * Keep it out-of-band so documents can cross a React Server Component
+ * boundary without exposing symbol-keyed properties. Next.js rejects objects
+ * carrying symbols even when those properties are non-enumerable.
+ */
+const observationByObject = new WeakMap();
+export function attachPreviewReadObservation(root, observation) {
+    const seen = new WeakSet();
+    const visit = (value) => {
+        if (!isObject(value) || seen.has(value))
+            return;
+        seen.add(value);
+        observationByObject.set(value, observation);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    visit(root);
+    return root;
+}
+export function getPreviewReadObservation(value) {
+    if (!isObject(value))
+        return null;
+    const candidate = observationByObject.get(value);
+    if (!isObject(candidate))
+        return null;
+    if (!Array.isArray(candidate.documentIds))
+        return null;
+    if (!Array.isArray(candidate.storyTypes))
+        return null;
+    if (typeof candidate.codeVersion !== 'string')
+        return null;
+    if (typeof candidate.observationId !== 'string')
+        return null;
+    if (typeof candidate.renderWatermark !== 'number' ||
+        !Number.isFinite(candidate.renderWatermark))
+        return null;
+    return candidate;
+}
+export function collectPreviewReadObservations(...roots) {
+    const observations = new Map();
+    const seen = new WeakSet();
+    const visit = (value) => {
+        if (!isObject(value) || seen.has(value))
+            return;
+        seen.add(value);
+        const observation = getPreviewReadObservation(value);
+        if (observation) {
+            observations.set(`${observation.codeVersion}\u0000${observation.observationId}\u0000${observation.renderWatermark}\u0000${observation.receiptId ?? ''}`, observation);
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    for (const root of roots)
+        visit(root);
+    return [...observations.values()];
+}
+export function conservativePreviewRenderWatermark(observations) {
+    let watermark;
+    for (const observation of observations) {
+        const next = observation.renderWatermark;
+        if (!Number.isFinite(next))
+            continue;
+        watermark = watermark === undefined ? next : Math.min(watermark, next);
+    }
+    return watermark;
+}
+function isObject(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}

package/dist/preview-scope.d.ts

@@ -0,0 +1,3 @@
+import type { RequestContext } from './types.js';
+export declare function hasUsablePreviewToken(context: RequestContext | undefined): boolean;
+export declare function withPreviewVariantArgs(udfPath: string, args: Record<string, unknown>, context: RequestContext | undefined): Record<string, unknown>;

package/dist/preview-scope.js

@@ -0,0 +1,22 @@
+export function hasUsablePreviewToken(context) {
+    const token = context?.previewToken;
+    return typeof token === 'string' && token.length > 0;
+}
+const VARIANT_AWARE_CONTROL_UDFS = new Set([
+    'queries:getRouteByPathname',
+]);
+export function withPreviewVariantArgs(udfPath, args, context) {
+    if (!VARIANT_AWARE_CONTROL_UDFS.has(udfPath) || !hasUsablePreviewToken(context)) {
+        return args;
+    }
+    const variantId = nonEmpty(context?.variantId);
+    const releaseId = nonEmpty(context?.releaseId);
+    return {
+        ...args,
+        ...(args.variantId === undefined && variantId ? { variantId } : {}),
+        ...(args.releaseId === undefined && releaseId ? { releaseId } : {}),
+    };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/preview-target.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `resolvePreviewTarget` — derive the URL the Studio preview iframe
+ * should open for the document being edited (ADR-095, extended by ADR-099).
+ *
+ * Pure function, JSON-serializable output, no IO. Imports only from
+ * `@storystick/client` and standard libraries so the parallel ADR-094
+ * absorption (file move into `packages/client/src/preview-target.ts`,
+ * Stage 2) is mechanical: file moves, Studio updates one import path.
+ *
+ * Resolution order:
+ *
+ *   1. `document === null` (loading) → fallback-root '/'.
+ *      The bridge's `enabled` gate (ADR-095 §4.1) means this fallback
+ *      target is never actually consumed by the iframe in production.
+ *   2. `document.isRoutable === false` → no-route. This authoritative
+ *      schema signal blocks every stored or live pathname. `undefined`
+ *      preserves the legacy path-driven behavior for pre-098 documents.
+ *   3. `liveResolvedPathname` is a string → 'self' with that pathname.
+ *      Wins over the stored value so unsaved keystrokes in the pathname
+ *      widget reflect in the iframe before autosave commits. The empty
+ *      string `''` is a valid live value (the homepage canonical shape,
+ *      ADR-056), distinct from `undefined` (no live value). Per ADR-099
+ *      D1 step 2, this case takes Tier 1 even when the doc is routable
+ *      so the homepage shape never regresses to the draft URL.
+ *   4. `document.resolvedPathname` is a string → 'self' with that pathname.
+ *   5. `document.isRoutable === true` → 'draft' with `pathname: '/'`
+ *      (ADR-099 D1 Tier 2, Cas A — schema declares pathname, value not
+ *      yet set). The customer's layout dispatches to the draft via
+ *      `resolvePreviewDraft()` from `@storystick/next/server`. The
+ *      `previewHomePath` knob (per-project Tier 2 destination) is
+ *      deferred to a follow-up — see ADR-099 §7.
+ *   6. Else → no-route (doc has no pathname field — Cas B). The Studio
+ *      may still present it through an explicit host context, but an unrelated
+ *      previous iframe is never a preview target and the dispatcher must not
+ *      invent a navigation to `/`.
+ *
+ * Two canonical forms cross at this seam:
+ *
+ *   | Layer                                  | Homepage | Nested        |
+ *   | -------------------------------------- | -------- | ------------- |
+ *   | Storage / SDK / `resolvedPathname` col | `""`     | `"blog/post"` |
+ *   | Browser / iframe / navigate envelope   | `"/"`    | `"/blog/post"`|
+ *
+ * `pathnameToHref` (in `@storystick/client`, paired with `normalizePathname`)
+ * is the single conversion seam.
+ */
+import type { QueryResult } from './types.js';
+export type PreviewTarget = {
+    reason: 'self';
+    pathname: string;
+} | {
+    reason: 'fallback-root';
+    pathname: string;
+} | {
+    reason: 'no-route';
+    pathname: string;
+} | {
+    reason: 'draft';
+    pathname: string;
+    draftDocumentId: string;
+};
+/**
+ * Resolve which URL the Studio preview iframe should open.
+ *
+ * @param document Document being edited, or `null` while the loading
+ *   query has not yet returned. Reads `resolvedPathname` and `isRoutable`
+ *   (formalized on `QueryResult` per ADR-094 / ADR-099). Studio's
+ *   `DocumentData` is structurally compatible.
+ * @param liveResolvedPathname In-flight canonical pathname from the
+ *   editor's reactive `resolvePathname` query. Wins over the stored
+ *   value when present.
+ */
+export declare function resolvePreviewTarget(document: QueryResult | null, liveResolvedPathname: string | undefined): PreviewTarget;

package/dist/preview-target.js

@@ -0,0 +1,86 @@
+/**
+ * `resolvePreviewTarget` — derive the URL the Studio preview iframe
+ * should open for the document being edited (ADR-095, extended by ADR-099).
+ *
+ * Pure function, JSON-serializable output, no IO. Imports only from
+ * `@storystick/client` and standard libraries so the parallel ADR-094
+ * absorption (file move into `packages/client/src/preview-target.ts`,
+ * Stage 2) is mechanical: file moves, Studio updates one import path.
+ *
+ * Resolution order:
+ *
+ *   1. `document === null` (loading) → fallback-root '/'.
+ *      The bridge's `enabled` gate (ADR-095 §4.1) means this fallback
+ *      target is never actually consumed by the iframe in production.
+ *   2. `document.isRoutable === false` → no-route. This authoritative
+ *      schema signal blocks every stored or live pathname. `undefined`
+ *      preserves the legacy path-driven behavior for pre-098 documents.
+ *   3. `liveResolvedPathname` is a string → 'self' with that pathname.
+ *      Wins over the stored value so unsaved keystrokes in the pathname
+ *      widget reflect in the iframe before autosave commits. The empty
+ *      string `''` is a valid live value (the homepage canonical shape,
+ *      ADR-056), distinct from `undefined` (no live value). Per ADR-099
+ *      D1 step 2, this case takes Tier 1 even when the doc is routable
+ *      so the homepage shape never regresses to the draft URL.
+ *   4. `document.resolvedPathname` is a string → 'self' with that pathname.
+ *   5. `document.isRoutable === true` → 'draft' with `pathname: '/'`
+ *      (ADR-099 D1 Tier 2, Cas A — schema declares pathname, value not
+ *      yet set). The customer's layout dispatches to the draft via
+ *      `resolvePreviewDraft()` from `@storystick/next/server`. The
+ *      `previewHomePath` knob (per-project Tier 2 destination) is
+ *      deferred to a follow-up — see ADR-099 §7.
+ *   6. Else → no-route (doc has no pathname field — Cas B). The Studio
+ *      may still present it through an explicit host context, but an unrelated
+ *      previous iframe is never a preview target and the dispatcher must not
+ *      invent a navigation to `/`.
+ *
+ * Two canonical forms cross at this seam:
+ *
+ *   | Layer                                  | Homepage | Nested        |
+ *   | -------------------------------------- | -------- | ------------- |
+ *   | Storage / SDK / `resolvedPathname` col | `""`     | `"blog/post"` |
+ *   | Browser / iframe / navigate envelope   | `"/"`    | `"/blog/post"`|
+ *
+ * `pathnameToHref` (in `@storystick/client`, paired with `normalizePathname`)
+ * is the single conversion seam.
+ */
+import { pathnameToHref } from './normalize-pathname.js';
+// Reserved for palier 2+ — commented out today; activating a variant
+// grows the union additively without breaking call sites that switch
+// on `reason` exhaustively (TS will flag missing cases):
+//
+// | { reason: 'host-page';  pathname: string; hostDocumentId: string }
+// | { reason: 'redirect';   pathname: string; originalPathname: string }
+const FALLBACK_ROOT = { reason: 'fallback-root', pathname: '/' };
+const NO_ROUTE = { reason: 'no-route', pathname: '/' };
+/**
+ * Resolve which URL the Studio preview iframe should open.
+ *
+ * @param document Document being edited, or `null` while the loading
+ *   query has not yet returned. Reads `resolvedPathname` and `isRoutable`
+ *   (formalized on `QueryResult` per ADR-094 / ADR-099). Studio's
+ *   `DocumentData` is structurally compatible.
+ * @param liveResolvedPathname In-flight canonical pathname from the
+ *   editor's reactive `resolvePathname` query. Wins over the stored
+ *   value when present.
+ */
+export function resolvePreviewTarget(document, liveResolvedPathname) {
+    if (document === null)
+        return FALLBACK_ROOT;
+    if (document.isRoutable === false)
+        return NO_ROUTE;
+    if (typeof liveResolvedPathname === 'string') {
+        return { reason: 'self', pathname: pathnameToHref(liveResolvedPathname) };
+    }
+    if (typeof document.resolvedPathname === 'string') {
+        return { reason: 'self', pathname: pathnameToHref(document.resolvedPathname) };
+    }
+    if (document.isRoutable === true) {
+        return {
+            reason: 'draft',
+            pathname: '/',
+            draftDocumentId: document.documentId,
+        };
+    }
+    return NO_ROUTE;
+}

package/dist/project-locales.d.ts

@@ -0,0 +1,4 @@
+import type { Transport, RequestContext } from './types.js';
+import { type LocaleRoutingSettings } from './locale-routing.js';
+/** Resolve locale settings under the same admitted generation as content. */
+export declare function fetchProjectLocaleSettings(transport: Pick<Transport, 'request'>, requestContext?: RequestContext): Promise<LocaleRoutingSettings>;

package/dist/project-locales.js

@@ -0,0 +1,12 @@
+import { readDocumentLocaleRouting } from './locale-routing.js';
+/** Resolve locale settings under the same admitted generation as content. */
+export async function fetchProjectLocaleSettings(transport, requestContext) {
+    const response = await transport.request({ udfPath: 'locales:get', args: {}, requestContext });
+    const data = response.data;
+    if (!data || typeof data !== 'object' || typeof data.synthetic !== 'boolean')
+        throw new TypeError('Storystick: malformed project locale settings.');
+    const settings = readDocumentLocaleRouting({ ...data, locale: data.defaultLocale });
+    if (!settings)
+        throw new TypeError('Storystick: invalid project locale routing.');
+    return settings;
+}

package/dist/public-delivery.d.ts

@@ -0,0 +1,36 @@
+import { type PublicSiteManifestV1, type PublicReadIdentityV1, type PublicRenderReceiptV1 } from '@storystick/types/public-delivery';
+import type { QueryMeta } from '@storystick/types/query-contract';
+/** Only SDK-owned hydration may transfer an observation to its prepared value. */
+export declare function carryPublicReadIdentity(from: object, to: object): void;
+/** Internal transport observation for the route's SQL-rendered document. */
+export declare function attachPublicRouteIdentity<T extends object>(document: T, identity?: PublicReadIdentityV1): T;
+/** SDK-owned response observation, never reconstructed by a live readback. */
+export declare function attachPublicReadIdentity<T extends object & {
+    meta: QueryMeta;
+    exactness: string;
+}>(result: T, identity?: PublicReadIdentityV1): T;
+/** Pass every CMS query result that actually contributed to this rendered page.
+ * Missing or cloned observations fail closed; no DOM traversal is involved. */
+export declare function createPublicRenderReceipt(input: {
+    projectId: string;
+    buildId: string;
+    deploymentId?: string;
+    pathname: string;
+    requestToken?: string;
+    results: readonly object[];
+}): PublicRenderReceiptV1;
+/** Safe text for an explicit application/json script owned by the renderer. */
+export declare function serializePublicRenderReceipt(receipt: PublicRenderReceiptV1): string;
+/** Call in the same render/build as the route inventory and sitemap. The inputs
+ * are the actual SDK results used for that inventory, including an empty list. */
+export declare function createPublicSiteManifest(input: {
+    projectId: string;
+    buildId: string;
+    deploymentId: string;
+    routes: {
+        pathname: string;
+        indexable: boolean;
+    }[];
+    sitemapPath: string;
+    results: readonly object[];
+}): PublicSiteManifestV1;

package/dist/public-delivery.js

@@ -0,0 +1,55 @@
+import { isPublicRenderReceipt, isPublicSiteManifest, PUBLIC_SITE_MANIFEST_PATH } from '@storystick/types/public-delivery';
+const publicReads = new WeakMap();
+/** Only SDK-owned hydration may transfer an observation to its prepared value. */
+export function carryPublicReadIdentity(from, to) {
+    const identity = publicReads.get(from);
+    if (identity)
+        publicReads.set(to, identity);
+}
+/** Internal transport observation for the route's SQL-rendered document. */
+export function attachPublicRouteIdentity(document, identity) {
+    if (identity)
+        publicReads.set(document, structuredClone(identity));
+    return document;
+}
+/** SDK-owned response observation, never reconstructed by a live readback. */
+export function attachPublicReadIdentity(result, identity) {
+    if (!identity)
+        return result;
+    if (result.exactness !== 'exact' || result.meta.scope.kind !== 'activePublication' ||
+        result.meta.projectionHash !== identity.projection.projectionHash || result.meta.lensHash !== identity.projection.lensHash ||
+        result.meta.consistency.projectedThroughSeq !== identity.projection.projectedThroughSeq)
+        throw new TypeError('Public result and read identity disagree.');
+    publicReads.set(result, structuredClone(identity));
+    return result;
+}
+/** Pass every CMS query result that actually contributed to this rendered page.
+ * Missing or cloned observations fail closed; no DOM traversal is involved. */
+export function createPublicRenderReceipt(input) {
+    const reads = input.results.map(result => {
+        const identity = publicReads.get(result);
+        if (!identity)
+            throw new TypeError('A rendered query has no authoritative public read identity. Configure an application build and public delivery.');
+        return structuredClone(identity);
+    });
+    const receipt = { version: 1, projectId: input.projectId, buildId: input.buildId,
+        deploymentId: input.deploymentId ?? null, pathname: input.pathname, reads, ...(input.requestToken ? { requestToken: input.requestToken } : {}) };
+    if (!isPublicRenderReceipt(receipt))
+        throw new TypeError('Invalid public render receipt.');
+    return receipt;
+}
+/** Safe text for an explicit application/json script owned by the renderer. */
+export function serializePublicRenderReceipt(receipt) {
+    if (!isPublicRenderReceipt(receipt))
+        throw new TypeError('Invalid public render receipt.');
+    return JSON.stringify(receipt).replace(/[<>&\u2028\u2029]/g, value => `\\u${value.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/** Call in the same render/build as the route inventory and sitemap. The inputs
+ * are the actual SDK results used for that inventory, including an empty list. */
+export function createPublicSiteManifest(input) {
+    const manifest = { version: 1, routes: [...input.routes].sort((a, b) => a.pathname.localeCompare(b.pathname)), sitemapPath: input.sitemapPath,
+        receipt: createPublicRenderReceipt({ ...input, pathname: PUBLIC_SITE_MANIFEST_PATH }) };
+    if (!isPublicSiteManifest(manifest))
+        throw new TypeError('Invalid public site manifest.');
+    return manifest;
+}

package/dist/published-routes.d.ts

@@ -0,0 +1,3 @@
+import { type Client } from './query-client.js';
+import type { StorystickPublishedLocaleRoute } from './seo.js';
+export declare function publishedLocaleRoutes(client: Client, storyTypes: readonly string[]): Promise<StorystickPublishedLocaleRoute[]>;

package/dist/published-routes.js

@@ -0,0 +1,100 @@
+import { StorystickError } from './errors.js';
+import { getInternalClientRuntime } from './query-client.js';
+import { LOCALE_ROUTE_COLLISION } from '@storystick/types/errors/codes/locale-lifecycle';
+import { samePublicReadIdentity } from '@storystick/types/public-delivery';
+import { attachPublicRouteIdentity } from './public-delivery.js';
+export async function publishedLocaleRoutes(client, storyTypes) {
+    if (storyTypes.length === 0)
+        return [];
+    const runtime = getInternalClientRuntime(client);
+    const routes = [];
+    const seenCursors = new Set();
+    let cursor = null;
+    let identity;
+    let witnessed;
+    for (let page = 0; page < 10_000; page += 1) {
+        const response = await runtime.transport.request({
+            udfPath: 'queries:listPublishedLocaleRoutes',
+            args: { storyTypes: [...storyTypes], cursor, numItems: 500 },
+            options: undefined,
+            requestContext: runtime.requestContext,
+        });
+        if (witnessed !== undefined && (witnessed !== Boolean(response.publicReadIdentity) ||
+            (identity && response.publicReadIdentity && !samePublicReadIdentity(identity, response.publicReadIdentity))))
+            throw new StorystickError('The public route inventory changed during pagination.', {
+                code: 'storystick/QUERY_GENERATION_CHANGED', category: 'system', retryable: true,
+            });
+        witnessed = Boolean(response.publicReadIdentity);
+        identity = response.publicReadIdentity;
+        const result = response.data;
+        routes.push(...result.page.map((route) => ({
+            ...route,
+            seo: route.seo ?? { indexable: true },
+        })));
+        if (result.isDone)
+            break;
+        const nextCursor = result.continueCursor;
+        if (!nextCursor || seenCursors.has(nextCursor)) {
+            throw new StorystickError('Published locale route pagination returned a missing or repeated cursor.', {
+                code: 'storystick/QUERY_CURSOR_INVALID',
+                category: 'system',
+                retryable: false,
+            });
+        }
+        seenCursors.add(nextCursor);
+        cursor = nextCursor;
+        if (page === 9_999) {
+            throw new StorystickError('Published locale route pagination exceeded the safety bound.', {
+                code: 'storystick/QUERY_PROTOCOL',
+                category: 'system',
+                retryable: false,
+            });
+        }
+    }
+    // Keep the whole owning route, not just its id — the collision report has
+    // to name the locale each side published under, which is the only way a
+    // customer can tell which of the two publications to rename.
+    const owners = new Map();
+    for (const route of routes) {
+        const owner = owners.get(route.publicPathname);
+        if (owner && owner.documentId !== route.documentId) {
+            // Typed, not a message-only error: `site.params` and `site.sitemap`
+            // are the only guard on the locale-prefixed public URL namespace, and
+            // customer build fallbacks re-throw on `error.code`. A plain `Error`
+            // silently degrades a real collision to zero static params and an
+            // empty sitemap.
+            throw new StorystickError(`LOCALE_ROUTE_COLLISION — "${route.publicPathname}" is published by both ` +
+                `"${owner.documentId}" (locale "${owner.locale}") and ` +
+                `"${route.documentId}" (locale "${route.locale}"). ` +
+                'Two documents cannot own the same public URL. Rename one of the two ' +
+                'publications, or unpublish it, then rebuild.', {
+                code: LOCALE_ROUTE_COLLISION.code,
+                category: LOCALE_ROUTE_COLLISION.category,
+                recoverable: LOCALE_ROUTE_COLLISION.recoverable,
+                retryable: LOCALE_ROUTE_COLLISION.retryable,
+                // The catalogue payload for this code was minted for the backend's
+                // locale-PREFIX collisions, where `conflictingLocale` is the enabled
+                // locale code a pathname's first segment shadows. This call site has
+                // no such value — it holds two documents that resolved to the same
+                // public URL — so `conflictingLocale` is omitted rather than filled
+                // with something that means a different thing, and the second party
+                // is reported under explicit `conflictingDocument*` keys. Extending
+                // the base payload follows `releases.ts` (`releaseId`) and
+                // `locales.ts` (`collisions`, `truncated`).
+                payload: {
+                    documentId: route.documentId,
+                    locale: route.locale,
+                    pathname: route.pathname,
+                    publicPathname: route.publicPathname,
+                    storyType: route.storyType,
+                    conflictingDocumentId: owner.documentId,
+                    conflictingDocumentLocale: owner.locale,
+                    conflictingPathname: owner.pathname,
+                    conflictingStoryType: owner.storyType,
+                },
+            });
+        }
+        owners.set(route.publicPathname, route);
+    }
+    return attachPublicRouteIdentity([...owners.values()], identity);
+}