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

package/dist/server-runtime.d.ts

@@ -0,0 +1,208 @@
+import type { SchemaStoryName, ResolvedRouteForSchema } from '@storystick/client';
+export type { ResolvedRouteForSchema } from '@storystick/client';
+/** Next server reads, optional CMS routing, and static route inventory. */
+import 'server-only';
+import { type PublicLocaleOrigins } from '@storystick/client/locale-routing';
+import type { Metadata } from 'next';
+import type { PreviewProvenanceEditableTextPathManifest } from '@storystick/preview/provenance';
+import { type RouteHandlerOptions } from './preview/route-handler.js';
+import { type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type QueryResult, StorystickError, type Client, type QuerySchemaDefinition, type QueryStoriesOf, type SelectedDocument } from '@storystick/client';
+import { type StorystickSitemapOptions } from './i18n-seo.js';
+export { buildStorystickSitemap, buildStorystickSitemapShards, STORYSTICK_SITEMAP_MAX_URLS, storystickAlternates, type ResolvedDocumentRoute, type StorystickAlternatesOptions, type StorystickPublishedLocaleRoute, type StorystickSitemapOptions, } from './i18n-seo.js';
+export { appendSearchParamsToRedirect, } from './preview-session-recovery.js';
+export { StorystickError } from '@storystick/client';
+export type { StorystickErrorCategory, StorystickErrorOptions, } from '@storystick/client';
+/**
+ * Natural cookie expiry can arrive as EXPIRED while the cookie is still in
+ * the request jar, or MISSING after the browser evicts it while Draft Mode
+ * remains enabled. Both are the same user-visible ended-session state.
+ */
+export declare function isPreviewSessionEndedError(error: unknown): boolean;
+export { buildPreviewProvenanceFrame, type BuildPreviewProvenanceFrameOptions, type BuildPreviewProvenanceFrameResult, type PreviewProvenanceAttrs, type PreviewProvenanceAttrsByKey, } from './preview/provenance-frame-builder.js';
+export { STORYSTICK_PREVIEW_ROBOTS } from './preview-metadata.js';
+export { readPreviewProvenanceSessionId, resolvePreviewProvenanceRouteIdentity, } from './preview/preview-request-identity.js';
+export { stripPreviewProvenance } from './clean.js';
+export type { PreviewProvenanceRouteIdentity, ReadPreviewProvenanceSessionOptions, ResolvePreviewProvenanceRouteIdentityOptions, } from './preview/preview-request-identity.js';
+export declare function createServerClient<const TSchema extends QuerySchemaDefinition>(querySchema: TSchema): Promise<Client<TSchema>>;
+export interface StorystickSitemapBuildOptions extends StorystickSitemapOptions {
+    readonly storyTypes: readonly string[];
+    readonly id?: number;
+    readonly shardSize?: number;
+    readonly locale?: string;
+}
+import type { ResolveRouteInput, ResolvedRoute } from '@storystick/client';
+export type { ResolveRouteInput, ResolvedRoute } from '@storystick/client';
+export type ResolvePageDataCondition = string | {
+    readonly storyType: string;
+};
+export interface ResolvePageDataDeclaration<StoryName extends string = string> {
+    readonly query: StoryName;
+    readonly for?: readonly ResolvePageDataCondition[];
+    readonly first?: number;
+}
+export type ResolvePageDataDeclarations<StoryName extends string = string> = Readonly<Record<string, ResolvePageDataDeclaration<StoryName>>>;
+export type ResolvedPageData<TData extends ResolvePageDataDeclarations, TSchema extends QuerySchemaDefinition = QuerySchemaDefinition> = {
+    readonly [K in keyof TData]: TData[K]['query'] extends keyof QueryStoriesOf<TSchema> ? readonly SelectedDocument<QueryStoriesOf<TSchema>[TData[K]['query']], 'all'>[] : QueryResult[];
+};
+type ResolvePageSearchParamValue = string | readonly string[] | undefined;
+export type ResolvePageRouteInput = ResolveRouteInput & {
+    readonly publicOrigins?: PublicLocaleOrigins;
+    readonly searchParams?: Readonly<Record<string, ResolvePageSearchParamValue>>;
+};
+export type ResolvePageInput<TData extends ResolvePageDataDeclarations | undefined = undefined> = ResolvePageRouteInput & {
+    readonly data?: TData;
+    readonly querySchema?: QuerySchemaDefinition;
+};
+export type ResolvedRouteWithPageData<TData extends ResolvePageDataDeclarations, TSchema extends QuerySchemaDefinition = QuerySchemaDefinition, TStoryTypes extends readonly SchemaStoryName<TSchema>[] | undefined = undefined> = (Extract<ResolvedRouteForSchema<TSchema, TStoryTypes>, {
+    type: 'document';
+}> & {
+    readonly data: ResolvedPageData<TData, TSchema>;
+}) | Exclude<ResolvedRouteForSchema<TSchema, TStoryTypes>, {
+    type: 'document';
+}>;
+export type TypedResolvePageInput<TSchema extends QuerySchemaDefinition, TStoryTypes extends readonly SchemaStoryName<TSchema>[] | undefined = undefined, TData extends ResolvePageDataDeclarations<SchemaStoryName<TSchema>> | undefined = undefined> = Omit<ResolvePageRouteInput, 'storyTypes'> & {
+    readonly querySchema: TSchema;
+    readonly storyTypes?: TStoryTypes;
+    readonly data?: TData;
+};
+/**
+ * Next.js façade for `resolveStorystickPage` (ADR-094 §1).
+ *
+ * Automatically inherits Draft Mode + preview cookie handling from
+ * `createServerClient()`. Customer code:
+ *
+ *   // app/[[...pathname]]/page.tsx
+ *   export default async function Page({
+ *     params,
+ *   }: { params: Promise<{ pathname: string[] | undefined }> }) {
+ *     const { pathname } = await params
+ *     const route = await resolvePage({ pathname })
+ *     if (route.type === 'notFound') notFound()
+ *     return <Renderer document={route.document} storyType={route.storyType} />
+ *   }
+ *
+ * Returns a `ResolvedRoute` discriminated union (`document` / `notFound`
+ * / future `redirect`). Infrastructure failures (network/auth) throw
+ * `StorystickError` — NOT swallowed into `notFound`. Customers handle
+ * those via Next-native `error.tsx` boundaries (ADR §1 error strategy).
+ *
+ * Single backend call: dispatches `queries:getRouteByPathname` (cross-
+ * storytype, indexed via ADR-086 `by_projectId_resolvedPathname`). No
+ * SDK-side fan-out. The optional `storyTypes` argument filters the
+ * backend lookup to specific types.
+ */
+export declare function resolvePage<const TSchema extends QuerySchemaDefinition, const TStoryTypes extends readonly SchemaStoryName<TSchema>[] | undefined = undefined, const TData extends ResolvePageDataDeclarations<SchemaStoryName<TSchema>> | undefined = undefined>(input: TypedResolvePageInput<TSchema, TStoryTypes, TData>): Promise<TData extends ResolvePageDataDeclarations ? ResolvedRouteWithPageData<TData, TSchema, TStoryTypes> : ResolvedRouteForSchema<TSchema, TStoryTypes>>;
+export declare function resolvePage<const TData extends ResolvePageDataDeclarations>(input: ResolvePageInput<TData>): Promise<ResolvedRouteWithPageData<TData>>;
+export declare function resolvePage(input: ResolvePageRouteInput): Promise<ResolvedRoute>;
+type PreviewRouteRenderDocument = {
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly fields?: unknown;
+};
+export interface ResolveStorystickRouteRenderInput<TDocument extends PreviewRouteRenderDocument, TContext = unknown> {
+    readonly document: TDocument;
+    readonly context?: TContext;
+    readonly pathname?: string;
+}
+export interface ResolvedStorystickRouteRender<TDocument extends PreviewRouteRenderDocument, TContext = unknown> {
+    readonly document: TDocument;
+    readonly context: TContext | undefined;
+}
+/**
+ * Resolve the render-time Source Graph closure for a route body.
+ *
+ * `resolvePage()` can attach identity for the route document itself, but app
+ * renderers often load additional QueryResults afterwards (related posts,
+ * customers, authors, tags, etc.). This helper is the server-side seam that
+ * combines the route document and the actual render context before rendering.
+ * It is a no-op outside Preview V2.
+ */
+export declare function resolveStorystickRouteRender<TDocument extends PreviewRouteRenderDocument, TContext = unknown>({ document, context, pathname, }: ResolveStorystickRouteRenderInput<TDocument, TContext>): Promise<ResolvedStorystickRouteRender<TDocument, TContext>>;
+/**
+ * Visible-failure subclass for preview-draft resolution failures
+ * (CSO-PREVIEW-1 invariant — never silent prod fallback when the editor
+ * is targeting a draft). Categorized as `'system'` to flow through the
+ * existing canonical category union; the subclass identity (via
+ * `instanceof`) is the discriminator for customer error.tsx handlers
+ * that want to render a draft-specific message.
+ */
+export declare class StorystickPreviewDraftError extends StorystickError {
+    constructor(message: string);
+}
+/** @internal The existing server mount attests the same request as its page.
+ * No cookies or infrastructure reads are added to public production renders. */
+export declare const readPreviewServerRenderReceipt: (projectOverride?: string) => Promise<{
+    projectionCheckpoint?: {
+        lensHash?: string | undefined;
+        projectionHash?: string | undefined;
+        projectedThroughSeq?: number | undefined;
+        generation: number;
+        status: "error" | "ready" | "stale" | "rebuilding";
+    } | undefined;
+    readContext: PreviewReadContext;
+    renderId: string;
+} | null>;
+export interface PreviewDraftResolveOptions {
+    /** Explicit view selector from the native page request; never inferred by a layout. */
+    readonly sessionId: string | null;
+    readonly locale?: string;
+}
+export declare function resolvePreviewDraft(options: PreviewDraftResolveOptions): Promise<QueryResult | null>;
+/** Advanced draft guard for an explicitly selected view. Prefer site.resolvePage for CMS routes. */
+export declare const isPreviewDraftActive: (sessionId: string | null) => Promise<boolean>;
+/** Generated, framework-neutral content definition, imported once per site. */
+export interface SiteDefinition<TSchema extends QuerySchemaDefinition = QuerySchemaDefinition> {
+    readonly querySchema: TSchema;
+    readonly previewProvenanceEditableTextPathManifest: PreviewProvenanceEditableTextPathManifest;
+}
+export interface CreateSiteOptions<TSchema extends QuerySchemaDefinition, TStoryTypes extends readonly SchemaStoryName<TSchema>[] | undefined = undefined> {
+    readonly definition: SiteDefinition<TSchema>;
+    readonly storyTypes?: TStoryTypes;
+    readonly siteUrl?: string | URL;
+    /** Default for independent readers. Otherwise use the project's default. */
+    readonly locale?: string;
+    readonly routes?: RouteHandlerOptions;
+    /** Language origins share canonical, unprefixed content paths. */
+    readonly publicOrigins?: PublicLocaleOrigins;
+    /** Locale served by this deployment. Explicit, so static generation needs no Host read. */
+    readonly domainLocale?: string;
+    /** Static requires a unique deployment ID per compilation; request supports live render receipts. */
+    readonly publicRendering?: 'request' | 'static';
+}
+type SiteNativeParams = Record<string, string | string[] | undefined>;
+type SiteNativeProps<TParams extends SiteNativeParams> = {
+    params: Promise<TParams>;
+    searchParams?: Promise<ResolvePageRouteInput['searchParams']>;
+};
+/** Immutable configuration; sessions and request data are resolved per render. */
+export declare function createSite<const TSchema extends QuerySchemaDefinition, const TStoryTypes extends readonly SchemaStoryName<TSchema>[] | undefined = undefined>(options: CreateSiteOptions<TSchema, TStoryTypes>): Readonly<{
+    client: (input?: {
+        locale?: string;
+    }) => Promise<Client<TSchema>>;
+    renderReceipt(input: {
+        pathname: string;
+        results: readonly object[];
+        deploymentId?: string;
+    }): Promise<import("@storystick/client").PublicRenderReceiptV1 | null>;
+    publicationManifest(input?: {
+        deploymentId?: string;
+        sitemapPath?: string;
+    }): Promise<import("@storystick/client").PublicSiteManifestV1>;
+    /** Project default locale, or the explicit locale configured for this site. */
+    locale(): Promise<string>;
+    resolvePage(input: Omit<ResolvePageRouteInput, "storyTypes"> | SiteNativeProps<SiteNativeParams>): Promise<ResolvedRouteForSchema<TSchema, TStoryTypes>>;
+    params: () => Promise<{
+        pathname: string[] | undefined;
+    }[] | {
+        pathname: string[] | undefined;
+    }[]>;
+    /** Only real published translations; no prefix substitution in language switches. */
+    alternates(route: ResolvedRouteForSchema<TSchema, TStoryTypes>): Readonly<Record<string, string>>;
+    metadata(route: ResolvedRouteForSchema<TSchema, TStoryTypes>, metadata?: Metadata): Promise<Metadata>;
+    handlers: Readonly<import("./preview/route-handler.js").RouteHandlers>;
+    sitemap: (input?: Omit<StorystickSitemapBuildOptions, "storyTypes" | "siteUrl">) => Promise<import("@storystick/client/seo").StorystickSitemapEntry[]>;
+    sitemapIds: (input?: Omit<StorystickSitemapBuildOptions, "storyTypes" | "siteUrl" | "id">) => Promise<{
+        id: number;
+    }[]>;
+}>;