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

package/dist/query-client.js

@@ -0,0 +1,306 @@
+import { STORYSTICK_GATEWAY_ORIGIN } from '@storystick/types/public-endpoints';
+import { isExactPublicQueryResultV2 } from '@storystick/types/delivery-contract';
+import { attachPublicReadIdentity } from './public-delivery.js';
+import { createHttpTransportV2, assertResponseProject, assertProjectMatch, } from './transport.js';
+import { createUnselectedQuery, } from './query-builder.js';
+import { attachPreviewFrameDependencies, previewAssetDependenciesFromValue, } from './preview-frame-dependencies.js';
+import { createPreviewProvenanceReadCacheKey, runPreviewProvenanceReadLifecycle, } from './preview-read-lifecycle.js';
+import { StorystickError } from './errors.js';
+import { attachDocumentLocaleRouting, normalizePublicLocaleOrigins } from './locale-routing.js';
+import { attachPreviewQueryReceipt } from './preview-query-receipt.js';
+const CLIENT_RUNTIMES = new WeakMap();
+const AUTHORITY_SCHEMA_CLIENTS = new WeakMap();
+export function getInternalClientRuntime(client) {
+    const runtime = CLIENT_RUNTIMES.get(client);
+    if (!runtime)
+        throw new TypeError('storystick/QUERY_INVALID: Expected a Client instance.');
+    return runtime;
+}
+/** Compare private Preview authority in memory without returning or serializing it. */
+export function clientMatchesPreviewAuthority(authority, expected) {
+    const runtime = CLIENT_RUNTIMES.get(authority);
+    const context = runtime?.requestContext;
+    return authority.projectId === expected.projectId &&
+        context?.previewSessionId === expected.previewSessionId &&
+        context?.previewObservationId === expected.previewObservationId &&
+        context.previewToken === expected.previewToken &&
+        (context.previewReadContext?.contextId ?? null) === (expected.readContext?.contextId ?? null) &&
+        (context.previewReadContext?.revision ?? null) === (expected.readContext?.revision ?? null) &&
+        (context.variantId ?? null) === expected.variantId &&
+        (context.releaseId ?? null) === expected.releaseId;
+}
+/**
+ * Internal adapter primitive: keep a trusted client's transport authority and
+ * request scope while replacing only its generated schema surface.
+ */
+export function bindClientSchemaToAuthority(authority, schema) {
+    let schemas = AUTHORITY_SCHEMA_CLIENTS.get(authority);
+    if (!schemas) {
+        schemas = new WeakMap();
+        AUTHORITY_SCHEMA_CLIENTS.set(authority, schemas);
+    }
+    const existing = schemas.get(schema);
+    if (existing)
+        return existing;
+    const runtime = getInternalClientRuntime(authority);
+    const options = normalizeClientOptions({
+        schema,
+        projectId: authority.projectId,
+        publishableKey: 'internal-authority-binding',
+        requestContext: runtime.requestContext,
+        defaults: runtime.defaults,
+        localeRouting: runtime.localeRouting,
+    });
+    const bound = createClientWithTransport(options, runtime.transport);
+    schemas.set(schema, bound);
+    return bound;
+}
+const DEFAULT_GATEWAY_URL = STORYSTICK_GATEWAY_ORIGIN;
+export function createClient(options) {
+    // An untyped caller cannot opt into internal Preview authority through this entry.
+    return createInternalClient({ ...options, requestContext: undefined });
+}
+export function createInternalClient(options) {
+    const normalized = normalizeClientOptions(options);
+    const sourceTransport = normalized.transport ?? createHttpTransportV2({
+        projectId: normalized.projectId,
+        endpoint: normalized.endpoint ?? DEFAULT_GATEWAY_URL,
+        deliveryEndpoint: normalized.deliveryEndpoint,
+        apiKey: normalized.apiKey ?? normalized.publishableKey,
+        applicationBuildId: normalized.applicationBuildId,
+    });
+    return createClientWithTransport(normalized, sourceTransport);
+}
+function normalizeClientOptions(options) {
+    validateSchema(options.schema);
+    if (options.localeRouting?.publicOrigins) {
+        for (const locale of options.localeRouting.locales) {
+            if (locale.enabled && !options.localeRouting.publicOrigins[locale.code]) {
+                throw new TypeError(`Missing public origin for enabled locale ${locale.code}.`);
+            }
+        }
+        options = { ...options, localeRouting: { ...options.localeRouting,
+                publicOrigins: normalizePublicLocaleOrigins(options.localeRouting.publicOrigins),
+            } };
+    }
+    if (!options.projectId.trim())
+        throw new TypeError('storystick/QUERY_INVALID: projectId is required.');
+    return options;
+}
+/** Schema rebinding reuses authority; only the outer factory selects HTTP. */
+function createClientWithTransport(options, sourceTransport) {
+    const transport = {
+        async request(input) {
+            assertProjectMatch(input.expectedProjectId ?? options.projectId, options.projectId);
+            const response = await sourceTransport.request({ ...input, expectedProjectId: options.projectId });
+            assertResponseProject(response, options.projectId);
+            return response;
+        },
+    };
+    const contextEpoch = contextEpochFor(options);
+    const client = {
+        schema: options.schema,
+        ...(options.defaults?.locale ? { defaultLocale: options.defaults.locale } : {}),
+        projectId: options.projectId,
+        query(storyType) {
+            if (!Object.prototype.hasOwnProperty.call(options.schema.stories, storyType)) {
+                throw new TypeError(`storystick/QUERY_INVALID: Unknown document story ${JSON.stringify(storyType)}.`);
+            }
+            return createUnselectedQuery(executionHost, storyType);
+        },
+    };
+    const executionHost = {
+        client,
+        schema: client.schema,
+        defaultLocale: client.defaultLocale,
+        async executeCompiled(compiled, canonical, executeOptions) {
+            const requestOptions = mergeQueryExecuteOptions(options.defaults, executeOptions);
+            const kind = compiled.cardinality === 'one'
+                ? 'query-single'
+                : 'query-many';
+            return runPreviewProvenanceReadLifecycle(options.requestContext, {
+                kind,
+                cacheKey: createPreviewProvenanceReadCacheKey(kind, {
+                    projectId: options.projectId,
+                    endpoint: options.endpoint ?? DEFAULT_GATEWAY_URL,
+                    authority: previewReadCacheAuthority(options.requestContext),
+                    query: canonical,
+                    options: requestOptions,
+                    localeRouting: options.localeRouting,
+                }),
+                signal: executeOptions?.signal,
+                executeRaw: async () => {
+                    let response;
+                    try {
+                        response = await transport.request({
+                            udfPath: 'queries:queryV2',
+                            args: { requestVersion: 2, query: compiled },
+                            options: requestOptions,
+                            requestContext: options.requestContext,
+                            signal: executeOptions?.signal,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof StorystickError)
+                            throw error;
+                        if (executeOptions?.signal?.aborted || (error instanceof DOMException && error.name === 'AbortError')) {
+                            throw new StorystickError('The query was aborted.', {
+                                code: 'storystick/QUERY_ABORTED', category: 'cancel', retryable: false,
+                            });
+                        }
+                        if (error instanceof SyntaxError) {
+                            throw new StorystickError('The Query V2 gateway returned malformed JSON.', {
+                                code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false,
+                            });
+                        }
+                        throw new StorystickError('The Query V2 gateway is unreachable.', {
+                            code: 'storystick/QUERY_NETWORK', category: 'system', retryable: true,
+                        });
+                    }
+                    assertAuthoritativeExecutionIdentity({
+                        compiled,
+                        requestContext: options.requestContext,
+                        response,
+                    });
+                    if (!isExactPublicQueryResultV2(response.data, compiled.cardinality)) {
+                        throw new StorystickError('The Query V2 gateway returned an invalid response.', {
+                            code: 'storystick/PROTOCOL_ERROR', category: 'system', retryable: false,
+                        });
+                    }
+                    const result = response.data;
+                    if (!options.requestContext?.previewToken)
+                        attachPublicReadIdentity(result, response.publicReadIdentity);
+                    if (options.localeRouting)
+                        attachDocumentLocaleRouting(result, options.localeRouting);
+                    if (options.requestContext?.unstable_previewProvenanceReadLifecycle) {
+                        attachQueryPreviewDependencies(result, compiled);
+                    }
+                    return attachPreviewQueryReceipt(result, response.previewQueryReceiptId);
+                },
+            });
+        },
+    };
+    CLIENT_RUNTIMES.set(client, {
+        contextEpoch,
+        executionHost,
+        transport,
+        requestContext: options.requestContext,
+        defaults: options.defaults,
+        localeRouting: options.localeRouting,
+    });
+    return Object.freeze(client);
+}
+function mergeQueryExecuteOptions(defaults, executeOptions) {
+    const defaultNext = defaults?.next;
+    const callNext = executeOptions?.next;
+    const tags = [
+        ...(defaultNext?.tags ?? []),
+        ...(callNext?.tags ?? []),
+    ];
+    return {
+        signal: executeOptions?.signal,
+        cache: executeOptions?.cache ?? defaults?.cache,
+        deliveryCache: executeOptions?.deliveryCache ?? defaults?.deliveryCache,
+        next: {
+            revalidate: callNext?.revalidate ?? defaultNext?.revalidate,
+            tags: tags.length > 0 ? tags : undefined,
+        },
+    };
+}
+function previewReadCacheAuthority(context) {
+    if (!context?.previewToken)
+        return { mode: 'production' };
+    return {
+        mode: 'preview',
+        sessionId: context.previewSessionId ?? null,
+        observationId: context.previewObservationId ?? null,
+        variantId: context.variantId ?? null,
+        releaseId: context.releaseId ?? null,
+        codeVersion: context.previewCodeVersion ?? null,
+    };
+}
+function attachQueryPreviewDependencies(result, compiled) {
+    try {
+        attachPreviewFrameDependencies(result, [
+            ...previewDependenciesForCompiledQuery(compiled),
+            ...previewAssetDependenciesFromValue(result),
+        ]);
+    }
+    catch {
+        // Provenance bookkeeping is optional and must never fail a content read.
+    }
+}
+function previewDependenciesForCompiledQuery(compiled) {
+    const storyType = compiled.target.storyType;
+    if (compiled.cardinality === 'many') {
+        return [{
+                kind: 'list',
+                storyType,
+                ...(compiled.filter === undefined ? {} : { where: compiled.filter }),
+                ...(compiled.page === undefined ? {} : { limit: compiled.page.first }),
+            }];
+    }
+    const address = compiled.address;
+    if (address?.kind === 'id') {
+        return [{ kind: 'batch-get', documentIds: [address.value] }];
+    }
+    if (address?.kind === 'slug') {
+        return [{ kind: 'get-by-slug', storyType, slug: address.value }];
+    }
+    if (address?.kind === 'pathname') {
+        return [{ kind: 'get-by-pathname', storyType, pathname: address.value }];
+    }
+    return [{ kind: 'list', storyType, limit: 1 }];
+}
+function assertAuthoritativeExecutionIdentity(input) {
+    const identity = input.response.executionIdentity;
+    const publicQueryHash = input.response.data && typeof input.response.data === 'object'
+        ? input.response.data.meta?.queryHash
+        : undefined;
+    if (!identity || typeof publicQueryHash !== 'string' || identity.queryHash !== publicQueryHash) {
+        throw new StorystickError('The Query V2 gateway omitted or mismatched its execution identity.', {
+            code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false,
+        });
+    }
+    const context = input.requestContext;
+    const source = !context?.previewToken || context.previewReadContext?.perspective.kind === 'published'
+        ? 'activePublication'
+        : context.releaseId
+            ? 'release'
+            : context.variantId
+                ? 'variant'
+                : 'living';
+    const expected = [
+        source,
+        'none',
+        input.compiled.locale.code,
+        input.compiled.locale.fallback === 'configured' ? 'explicit' : 'none',
+        ...(source === 'variant' ? [`variant:${context.variantId}`] : []),
+        ...(source === 'release' ? [`release:${context.releaseId}`] : []),
+    ].join('|');
+    if (identity.readScopeIdentity !== expected) {
+        throw new StorystickError('The Query V2 response belongs to a different authoritative read scope.', {
+            code: 'storystick/QUERY_SCOPE_MISMATCH', category: 'auth', retryable: false,
+        });
+    }
+}
+function validateSchema(schema) {
+    if (!schema || schema.contractVersion !== 2 || typeof schema.fingerprint !== 'string' ||
+        !schema.stories || typeof schema.stories !== 'object') {
+        throw new TypeError('storystick/QUERY_INVALID: schema must be a generated QuerySchema V2.');
+    }
+}
+function contextEpochFor(options) {
+    const context = options.requestContext;
+    if (!context?.previewToken)
+        return 'production';
+    return [
+        'preview',
+        context.previewSessionId ?? '',
+        context.previewObservationId ?? '',
+        context.variantId ?? '',
+        context.releaseId ?? '',
+        context.previewReadContext?.contextId ?? '',
+        context.previewReadContext?.revision ?? '',
+    ].join(':');
+}

package/dist/query-compiler.d.ts

@@ -0,0 +1,5 @@
+import type { CompiledQueryV2 } from '@storystick/types/query-contract';
+export declare function compileQueryState(owner: object, state: CompiledQueryV2): {
+    query: CompiledQueryV2;
+    canonical: string;
+};

package/dist/query-compiler.js

@@ -0,0 +1,12 @@
+import { canonicalConversationJson } from '@storystick/types/internal/canonical-json';
+const canonicalByQuery = new WeakMap();
+export function compileQueryState(owner, state) {
+    const cached = canonicalByQuery.get(owner);
+    if (cached)
+        return cached;
+    const canonical = canonicalConversationJson(state);
+    const query = JSON.parse(canonical);
+    const result = Object.freeze({ query: Object.freeze(query), canonical });
+    canonicalByQuery.set(owner, result);
+    return result;
+}

package/dist/query-schema.d.ts

@@ -0,0 +1,32 @@
+export type QueryDslOperator = 'is' | 'isNot' | 'isAnyOf' | 'startsWith' | 'contains' | 'gt' | 'lt' | 'after' | 'before' | 'between' | 'isEmpty' | 'isNotEmpty' | 'hasAny' | 'hasAll' | 'doesNotInclude';
+export interface QueryFieldType<TValue = unknown, TOperators extends QueryDslOperator = never, TSortable extends boolean = false, TOptional extends boolean = false, TArray extends boolean = false, TChildren extends object | never = never, TTargets extends object | never = never> {
+    readonly value: TValue;
+    readonly operators: TOperators;
+    readonly sortable: TSortable;
+    readonly optional: TOptional;
+    readonly array: TArray;
+    readonly children: TChildren;
+    readonly targets: TTargets;
+}
+/** Structural marker: generated named interfaces deliberately need no index signature. */
+export type QueryFieldMap = object;
+export interface QueryStoryType<TDocument = unknown, TFields extends object = object, TSingleton extends boolean = boolean, TSlug extends boolean = boolean, TPathname extends boolean = boolean> {
+    readonly document: TDocument;
+    readonly fields: TFields;
+    readonly singleton: TSingleton;
+    readonly slug: TSlug;
+    readonly pathname: TPathname;
+}
+/** Structural marker: generated named interfaces deliberately need no index signature. */
+export type QueryStoryMap = object;
+export interface QuerySchemaDefinition<TStories extends object = object> {
+    readonly contractVersion: 2;
+    readonly fingerprint: string;
+    readonly stories: Readonly<Record<string, {
+        readonly singleton: boolean;
+        readonly addresses: readonly ('id' | 'slug' | 'pathname')[];
+    }>>;
+    /** Type-only carrier. Generated values never serialize this property. */
+    readonly __types?: TStories;
+}
+export type QueryStoriesOf<TSchema extends QuerySchemaDefinition> = NonNullable<TSchema['__types']>;

package/dist/query-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/redirect-search.d.ts

@@ -0,0 +1,4 @@
+type SearchParamValue = string | readonly string[] | undefined;
+/** Keep repeated customer query parameters when a CMS route redirects. */
+export declare function appendSearchParamsToRedirect(redirectTo: string, searchParams: URLSearchParams | Readonly<Record<string, SearchParamValue>>): string;
+export {};

package/dist/redirect-search.js

@@ -0,0 +1,14 @@
+/** Keep repeated customer query parameters when a CMS route redirects. */
+export function appendSearchParamsToRedirect(redirectTo, searchParams) {
+    const destination = new URL(redirectTo, 'http://redirect.invalid');
+    const entries = searchParams instanceof URLSearchParams ? searchParams.entries() : Object.entries(searchParams);
+    for (const [key, rawValue] of entries) {
+        const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+        for (const value of values) {
+            if (typeof value === 'string')
+                destination.searchParams.append(key, value);
+        }
+    }
+    const path = `${destination.pathname}${destination.search}${destination.hash}`;
+    return /^[a-z][a-z\d+.-]*:/i.test(redirectTo) ? destination.href : redirectTo.startsWith('//') ? `//${destination.host}${path}` : path;
+}

package/dist/reference-resolver.d.ts

@@ -0,0 +1,37 @@
+import { type ReferencedDocumentFailureReason, type ReferencedDocumentSidecarEntry, type ReferencedDocumentSidecarFailure } from '@storystick/types';
+import type { QuerySchemaDefinition, QueryStoriesOf } from './query-schema.js';
+type StoryName<TSchema extends QuerySchemaDefinition> = keyof QueryStoriesOf<TSchema> & string;
+/** Address metadata only. Read document fields through an explicit Query V2 selection. */
+export type ReferenceDocument = Omit<ReferencedDocumentSidecarEntry, 'fields'>;
+export interface ResolveReferenceOptions {
+    /** A delivery document or `_referencedDocs` sidecar. */
+    readonly source?: unknown;
+    /** Canonical source field path, for example `author` or `members[0]`. */
+    readonly path?: string;
+}
+export type ResolvedReference = {
+    readonly status: 'ok';
+    readonly document: ReferenceDocument;
+} | {
+    readonly status: 'empty';
+    readonly documentId?: never;
+} | {
+    readonly status: 'no-sidecar';
+    readonly documentId: string;
+} | {
+    readonly status: ReferencedDocumentFailureReason;
+    readonly documentId: string;
+    readonly failure: ReferencedDocumentSidecarFailure;
+} | {
+    readonly status: 'wrong-type';
+    readonly documentId: string;
+    readonly expectedStoryType: string;
+    readonly actualStoryType: string;
+} | {
+    readonly status: 'ambiguous';
+    readonly documentId: string;
+    readonly paths: readonly string[];
+};
+export declare function resolveReference<const TSchema extends QuerySchemaDefinition, const TStoryName extends StoryName<TSchema>>(schema: TSchema, storyType: TStoryName, value: string | null | undefined, options?: ResolveReferenceOptions): ResolvedReference;
+export declare function resolveReferences<const TSchema extends QuerySchemaDefinition, const TStoryName extends StoryName<TSchema>>(schema: TSchema, storyType: TStoryName, values: readonly (string | null | undefined)[] | null | undefined, options?: ResolveReferenceOptions): readonly ResolvedReference[];
+export {};

package/dist/reference-resolver.js

@@ -0,0 +1,126 @@
+import { getReferencedDocumentsSidecar, } from '@storystick/types';
+export function resolveReference(schema, storyType, value, options = {}) {
+    assertStory(schema, storyType);
+    const documentId = nonEmptyString(value);
+    if (!documentId)
+        return { status: 'empty' };
+    const sidecar = getReferencedDocumentsSidecar(options.source);
+    if (!sidecar)
+        return { status: 'no-sidecar', documentId };
+    const exact = options.path
+        ? exactOutcome(sidecar, options.path, documentId)
+        : undefined;
+    if (exact)
+        return finish(exact, storyType, documentId);
+    const candidates = outcomesForDocument(sidecar, documentId);
+    if (candidates.length === 0) {
+        const byId = sidecar.byId[documentId];
+        if (byId)
+            return finish({ path: '$byId', entry: byId }, storyType, documentId);
+        return finish({
+            path: options.path ?? '$unknown',
+            failure: {
+                documentId,
+                policy: 'activePublication',
+                reason: 'missing',
+            },
+        }, storyType, documentId);
+    }
+    const byId = sidecar.byId[documentId];
+    const comparable = byId
+        ? [...candidates, { path: '$byId', entry: byId }]
+        : candidates;
+    if (!outcomesAgree(comparable)) {
+        return {
+            status: 'ambiguous',
+            documentId,
+            paths: comparable.map((candidate) => candidate.path).sort(),
+        };
+    }
+    const candidate = byId && candidates[0]?.entry
+        ? { path: '$byId', entry: byId }
+        : candidates[0];
+    return finish(candidate, storyType, documentId);
+}
+export function resolveReferences(schema, storyType, values, options = {}) {
+    assertStory(schema, storyType);
+    if (!values)
+        return [];
+    return values.map((value, index) => resolveReference(schema, storyType, value, {
+        ...options,
+        ...(options.path ? { path: `${options.path}[${index}]` } : {}),
+    }));
+}
+function exactOutcome(sidecar, path, documentId) {
+    const entry = sidecar.byRef[path];
+    if (entry?.documentId === documentId)
+        return { path, entry };
+    const failure = sidecar.unresolved?.[path];
+    if (failure?.documentId === documentId)
+        return { path, failure };
+    return undefined;
+}
+function outcomesForDocument(sidecar, documentId) {
+    const outcomes = [];
+    for (const [path, entry] of Object.entries(sidecar.byRef)) {
+        if (entry.documentId === documentId)
+            outcomes.push({ path, entry });
+    }
+    for (const [path, failure] of Object.entries(sidecar.unresolved ?? {})) {
+        if (failure.documentId === documentId)
+            outcomes.push({ path, failure });
+    }
+    return outcomes;
+}
+function outcomesAgree(outcomes) {
+    const first = outcomeIdentity(outcomes[0]);
+    return outcomes.every((outcome) => outcomeIdentity(outcome) === first);
+}
+function outcomeIdentity(outcome) {
+    if (outcome.failure) {
+        return [
+            'failure',
+            outcome.failure.reason,
+            outcome.failure.policy,
+            outcome.failure.pinnedSnapshotId ?? '',
+        ].join(':');
+    }
+    return [
+        'ok',
+        outcome.entry.storyType,
+        outcome.entry.policy,
+        outcome.entry.snapshotId ?? '',
+        outcome.entry.locale ?? '',
+        outcome.entry.resolvedPathname ?? '',
+    ].join(':');
+}
+function finish(outcome, expectedStoryType, documentId) {
+    if (outcome.failure) {
+        return {
+            status: outcome.failure.reason,
+            documentId,
+            failure: outcome.failure,
+        };
+    }
+    if (outcome.entry.storyType !== expectedStoryType) {
+        return {
+            status: 'wrong-type',
+            documentId,
+            expectedStoryType,
+            actualStoryType: outcome.entry.storyType,
+        };
+    }
+    const { fields: _fields, ...address } = outcome.entry;
+    return { status: 'ok', document: address };
+}
+function assertStory(schema, storyType) {
+    if (!Object.prototype.hasOwnProperty.call(schema.stories, storyType)) {
+        throw new TypeError(`storystick/QUERY_INVALID: Unknown reference target story ${JSON.stringify(storyType)}.`);
+    }
+}
+function nonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/resolve-route.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `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 type { ResolvedRoute, ResolveRouteInput } from './types.js';
+import type { Client } from './query-client.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 declare function resolveStorystickPage(client: Client, input: ResolveRouteInput): Promise<ResolvedRoute>;