@cmssy/core 5.0.0

package/dist/index.d.cts

@@ -0,0 +1,496 @@
+import { CmssyAuthConfig, CmssyClientConfig, CmssyLayoutGroup, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldControl, FieldDefinition, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
+export { BlockMeta, BlockRect, BlockSchema, BuildBlockContextExtra, CmssyAddress, CmssyAuthConfig, CmssyBlockAuthContext, CmssyBlockContext, CmssyBlockMember, CmssyBlockWorkspace, CmssyBranding, CmssyCart, CmssyCartDiscount, CmssyCartItem, CmssyCartItemSnapshot, CmssyClientConfig, CmssyFormDefinition, CmssyFormField, CmssyFormSettings, CmssyFormSubmitResponse, CmssyLayoutGroup, CmssyLayoutSettings, CmssyLocaleContext, CmssyLocalizedValue, CmssyModelDefinition, CmssyModelRecord, CmssyOrder, CmssyOrderDiscount, CmssyOrderItem, CmssyOrderTaxSummaryLine, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssyPriceTier, CmssyProduct, CmssyProductPage, CmssyProductVariant, CmssyRecordList, CmssySessionPayload, CmssySessionUser, CmssyShippingMethod, CmssySiteConfig, CmssySiteLocales, CmssyStockState, CmssyTaxSummaryLine, CmssyWebhookEvent, CmssyWebhookOrder, FetchOrderByTokenOptions, FetchProductOptions, FetchProductsOptions, FieldCondition, FieldConditionGroup, FieldConditionLogic, FieldControl, FieldDefinition, FieldType, MyOrdersResult, RawBlock, RawLayoutBlock, SessionCookieOptions, SubmitFormInput, VerifyCmssyWebhookOptions, evaluateFieldConditionGroup } from '@cmssy/types';
+
+declare const DEFAULT_CMSSY_EDITOR_ORIGINS: string[];
+declare function isDevelopment(): boolean;
+declare function resolveEditorOrigin(editorOrigin: string | string[] | undefined): string | string[];
+interface CmssyConfig {
+    /**
+     * Full GraphQL delivery endpoint. Defaults to the cmssy cloud endpoint
+     * (`https://api.cmssy.io/graphql`); set it only for self-hosted / staging.
+     */
+    apiUrl?: string;
+    /** Organization slug - part of the org-scoped delivery path. */
+    org: string;
+    workspaceSlug: string;
+    draftSecret: string;
+    /**
+     * A cmssy API token (`cs_…`) that opts this app into the editor-controlled dev
+     * preview. In development only, the SDK sends it on every page fetch so the
+     * backend can resolve the token's user and honour that user's dev-preview flag
+     * (toggled from the editor's dev-mode switch): flag on + a saved dev draft ⇒
+     * the draft overlay renders, otherwise published content. Server-only (never
+     * reaches the client); ignored outside development. See the Quickstart
+     * "Dev preview" section.
+     */
+    devToken?: string;
+    /**
+     * Origin allowed to frame your app in the editor. Defaults to
+     * {@link DEFAULT_CMSSY_EDITOR_ORIGINS}; set it only for self-hosted admins.
+     */
+    editorOrigin?: string | string[];
+    /**
+     * Canonical absolute site URL (e.g. https://cmssy.com), used by
+     * createCmssyRobots / createCmssySitemap. When omitted the helpers derive the
+     * origin from the request `host` header at render time (multi-domain safe).
+     */
+    siteUrl?: string;
+    auth?: CmssyAuthConfig;
+    defaultLocale?: string;
+    /** All languages enabled on the workspace; exposed to blocks via context.locale.enabled. */
+    enabledLocales?: string[];
+    resolveLocale?: () => string | Promise<string>;
+}
+/**
+ * Env-shaped input for {@link defineCmssyConfig}: the required string fields are
+ * widened to `string | undefined` so a config can pass `process.env.*` straight
+ * through without a `?? ""` fallback (which would mask a missing value as an
+ * empty string) or a cast.
+ */
+type CmssyEnvConfig = Omit<CmssyConfig, "org" | "workspaceSlug" | "draftSecret"> & {
+    org?: string;
+    workspaceSlug?: string;
+    draftSecret?: string;
+};
+/**
+ * Validates an env-sourced config and returns a strictly-typed
+ * {@link CmssyConfig}. Pass raw `process.env.*` values; this throws a clear,
+ * actionable error listing any missing required variables (rendered by the
+ * Next.js error overlay / boundary), so the app fails fast instead of running
+ * with silently-empty config.
+ */
+declare function defineCmssyConfig(config: CmssyEnvConfig): CmssyConfig;
+declare function assertAuthConfig(config: CmssyConfig): CmssyAuthConfig;
+
+/** HTTP-level failure from the cmssy API, with a machine-readable status. */
+declare class CmssyRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface RetryPolicy {
+    /** Additional attempts after the first request (default 3). */
+    maxRetries?: number;
+    /** Exponential backoff base in ms: base * 2^attempt (default 300). */
+    baseDelayMs?: number;
+    /** Upper bound for any single wait, including Retry-After (default 3000). */
+    maxDelayMs?: number;
+    /** HTTP statuses that trigger a retry (default [429, 503]). */
+    retryStatuses?: number[];
+}
+
+/**
+ * The cmssy cloud GraphQL delivery endpoint. It is the same for every workspace,
+ * so consumers never need to set it - `apiUrl` defaults to this. Self-hosted /
+ * staging deployments override it via config.
+ */
+declare const DEFAULT_CMSSY_API_URL = "https://api.cmssy.io/graphql";
+declare function resolveApiUrl(apiUrl: string | undefined): string;
+/**
+ * Public delivery endpoint for a workspace: the org-scoped path
+ * `{base}/public/{orgSlug}/{workspaceSlug}/graphql`. `apiUrl` is the GraphQL
+ * base (its trailing `/graphql` is stripped); the org path is what tells the
+ * backend which workspace to serve, so slugs only need to be unique per org.
+ */
+declare function resolvePublicUrl(config: CmssyClientConfig): string;
+interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    headers?: {
+        get: (name: string) => string | null;
+    };
+}
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<FetchLikeResponse>;
+interface FetchPageOptions {
+    previewSecret?: string;
+    devPreview?: boolean;
+    devToken?: string;
+    workspaceId?: string;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    retry?: RetryPolicy | false;
+}
+declare function normalizeSlug(path: string | string[] | undefined): string;
+declare function fetchPage(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyPageData | null>;
+declare function fetchPageById(config: CmssyClientConfig, pageId: string, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageData | null>;
+declare function fetchPages(config: CmssyClientConfig, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageSummary[]>;
+declare function fetchPageMeta(config: CmssyClientConfig, path: string | string[] | undefined, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageMeta | null>;
+declare function fetchLayouts(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyLayoutGroup[]>;
+
+declare function getBlockContentForLanguage(content: unknown, locale: string, defaultLocale?: string, availableLocales?: string[]): Record<string, unknown>;
+/**
+ * Coerce a block bucket (`style` / `advanced`) to a plain object. These buckets
+ * are flat (not locale-keyed) and free-form; a missing/invalid bucket becomes
+ * an empty object so components can destructure it safely.
+ */
+declare function asBucket(value: unknown): Record<string, unknown>;
+
+interface GraphqlRequestOptions {
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    /**
+     * Route through the org-scoped public delivery path instead of the base
+     * `/graphql` endpoint. Set for unauthenticated public queries so the backend
+     * resolves the workspace from the URL rather than a global slug lookup.
+     */
+    public?: boolean;
+    /**
+     * Retry transient HTTP failures (429/503, honoring Retry-After). Off by
+     * default: this function also carries mutations (auth, cart, checkout),
+     * which must never be blind-retried. Read-only callers opt in with `{}`.
+     */
+    retry?: RetryPolicy | false;
+}
+declare function graphqlRequest<T>(config: CmssyClientConfig, query: string, variables: Record<string, unknown>, options?: GraphqlRequestOptions, label?: string): Promise<T>;
+
+interface QueryScopedOptions extends GraphqlRequestOptions {
+    workspaceId?: string;
+}
+interface CmssyClient {
+    readonly config: CmssyClientConfig;
+    query<T = unknown>(document: string, variables?: Record<string, unknown>, options?: GraphqlRequestOptions): Promise<T>;
+    queryScoped<T = unknown>(document: string, variables?: Record<string, unknown>, options?: QueryScopedOptions): Promise<T>;
+    resolveWorkspaceId(options?: GraphqlRequestOptions): Promise<string>;
+}
+declare function createCmssyClient(input: CmssyClientConfig): CmssyClient;
+
+declare const SITE_CONFIG_QUERY = "query PublicSiteConfig($workspaceSlug: String!) {\n  public {\n    siteConfig(workspaceSlug: $workspaceSlug) {\n      id\n      workspaceId\n      siteName\n      defaultLanguage\n      enabledLanguages\n      enabledFeatures\n      notFoundPageId\n      previewUrl\n      branding {\n        brandName\n        logoUrl\n        faviconUrl\n        ogImageUrl\n      }\n    }\n  }\n}";
+declare const MODEL_DEFINITIONS_QUERY = "query PublicModelDefinitions($workspaceId: String!) {\n  public {\n    model {\n      definitions(workspaceId: $workspaceId) {\n        id name slug description icon color displayField recordCount\n      }\n    }\n  }\n}";
+declare const MODEL_RECORDS_QUERY = "query PublicModelRecords($workspaceId: String!, $modelSlug: String!, $filter: JSON, $sort: String, $locale: String, $limit: Int, $offset: Int, $populate: [String!]) {\n  public {\n    model {\n      records(workspaceId: $workspaceId, modelSlug: $modelSlug, filter: $filter, sort: $sort, locale: $locale, limit: $limit, offset: $offset, populate: $populate) {\n        items { id modelId data status createdAt updatedAt }\n        total\n        hasMore\n      }\n    }\n  }\n}";
+declare const FORM_QUERY = "query PublicForm($formId: ID!) {\n  public {\n    form {\n      get(formId: $formId) {\n        id\n        name\n        slug\n        description\n        fields {\n          id name fieldType label placeholder helpText\n          defaultValue width order showWhen requiredWhen\n          options { value label disabled }\n          validation { required minLength maxLength minValue maxValue pattern customMessage }\n        }\n        settings {\n          actionType submitButtonLabel successMessage errorMessage\n          redirectUrl requireLogin enableCaptcha\n        }\n      }\n    }\n  }\n}";
+declare const SUBMIT_FORM_MUTATION = "mutation SubmitForm($formId: ID!, $input: SubmitFormInput!) {\n  public {\n    form {\n      submit(formId: $formId, input: $input) {\n        success message submissionId redirectUrl accessToken customer\n      }\n    }\n  }\n}";
+
+declare function fetchSiteConfig(config: CmssyClientConfig, options?: GraphqlRequestOptions): Promise<CmssySiteConfig | null>;
+declare function resolveWorkspaceId(config: CmssyClientConfig, options?: GraphqlRequestOptions): Promise<string>;
+/**
+ * Every authenticated operation needs the workspace id, and it never changes for
+ * a given (endpoint, workspace) pair - so it is resolved once and shared. A
+ * failed lookup is evicted, otherwise one bad request would be cached forever.
+ */
+declare function cachedWorkspaceId(config: CmssyClientConfig): Promise<string>;
+declare function clearWorkspaceIdCache(): void;
+
+declare function collectFormIds(blocks: RawBlock[], locale: string, defaultLocale: string): string[];
+declare function resolveForms(config: CmssyClientConfig, blocks: RawBlock[], locale: string, defaultLocale: string, options?: QueryScopedOptions): Promise<Record<string, CmssyFormDefinition>>;
+
+declare function resolveSiteLocales(config: CmssyClientConfig, options?: GraphqlRequestOptions): Promise<CmssySiteLocales>;
+declare function splitLocaleFromPath(path: string[] | undefined, siteLocales: CmssySiteLocales): {
+    locale: string;
+    path: string[] | undefined;
+};
+
+declare function buildBlockContext(locale: string, defaultLocale: string, enabledLocales?: string[], isPreview?: boolean, forms?: Record<string, CmssyFormDefinition>, extra?: BuildBlockContextExtra): CmssyBlockContext;
+
+/**
+ * Rewrites an internal href to carry the active locale as a path prefix.
+ * External hrefs, fragments and relative paths are returned untouched. Already
+ * prefixed hrefs are normalized so the prefix never doubles.
+ */
+declare function localizeHref(href: string, locale: CmssyLocaleContext): string;
+/**
+ * Builds the href that switches the current `pathname` to `target` locale,
+ * preserving the rest of the path. Used by a language switcher.
+ */
+declare function buildLocaleSwitchHref(target: string, pathname: string, locale: CmssyLocaleContext): string;
+/**
+ * Rewrites every `<a href>` inside an HTML string with {@link localizeHref}.
+ * For rich-text content stored in CMS blocks where links are raw markup.
+ */
+declare function localizeHtmlLinks(html: string, locale: CmssyLocaleContext): string;
+
+declare const CMSSY_LOCALE_HEADER = "x-cmssy-locale";
+declare function localeForPathname(config: CmssyClientConfig, pathname: string): Promise<string>;
+declare function splitCmssyLocale(config: CmssyClientConfig, path: string[] | undefined): Promise<{
+    locale: string;
+    path: string[] | undefined;
+}>;
+/**
+ * Resolve the locale a path asks for. The prefix IS the language, so a routed
+ * path is all it takes - no request, no headers, static-safe.
+ */
+declare function localeForPath(config: CmssyClientConfig, path: string | string[]): Promise<string>;
+
+declare const fields: {
+    text: (opts?: FieldControl) => FieldDefinition;
+    textarea: (opts?: FieldControl) => FieldDefinition;
+    richText: (opts?: FieldControl) => FieldDefinition;
+    markdown: (opts?: FieldControl) => FieldDefinition;
+    number: (opts?: FieldControl) => FieldDefinition;
+    date: (opts?: FieldControl) => FieldDefinition;
+    datetime: (opts?: FieldControl) => FieldDefinition;
+    boolean: (opts?: FieldControl) => FieldDefinition;
+    color: (opts?: FieldControl) => FieldDefinition;
+    media: (opts?: FieldControl) => FieldDefinition;
+    link: (opts?: FieldControl) => FieldDefinition;
+    url: (opts?: FieldControl) => FieldDefinition;
+    email: (opts?: FieldControl) => FieldDefinition;
+    select: (opts?: FieldControl) => FieldDefinition;
+    multiselect: (opts?: FieldControl) => FieldDefinition;
+    radio: (opts?: FieldControl) => FieldDefinition;
+    repeater: (opts?: FieldControl) => FieldDefinition;
+    table: (opts?: FieldControl) => FieldDefinition;
+    json: (opts?: FieldControl) => FieldDefinition;
+    form: (opts?: FieldControl) => FieldDefinition;
+    pageSelector: (opts?: FieldControl) => FieldDefinition;
+};
+
+declare const PROTOCOL_VERSION = 2;
+
+interface ReadyMessage {
+    type: "cmssy:ready";
+    protocolVersion: number;
+    blocks: Array<{
+        id: string;
+        type: string;
+        bounds: BlockRect;
+        layoutPosition?: string;
+    }>;
+    schemas: Record<string, BlockSchema>;
+    blockMeta?: Record<string, BlockMeta>;
+}
+interface BoundsMessage {
+    type: "cmssy:bounds";
+    blockId: string;
+    rect: BlockRect;
+}
+interface ClickMessage {
+    type: "cmssy:click";
+    blockId: string;
+    rect: BlockRect;
+    layoutPosition?: string;
+}
+interface MoveMessage {
+    type: "cmssy:move";
+    protocolVersion: number;
+    blockId: string;
+    index: number;
+}
+interface DragIndexMessage {
+    type: "cmssy:drag-index";
+    protocolVersion: number;
+    index: number;
+}
+type AppToEditorMessage = ReadyMessage | BoundsMessage | ClickMessage | MoveMessage | DragIndexMessage;
+interface SelectMessage {
+    type: "cmssy:select";
+    protocolVersion: number;
+    blockId: string;
+}
+interface PatchMessage {
+    type: "cmssy:patch";
+    protocolVersion: number;
+    blockId: string;
+    content: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    advanced?: Record<string, unknown>;
+    layoutPosition?: string;
+}
+interface ParentReadyMessage {
+    type: "cmssy:parent-ready";
+    protocolVersion: number;
+}
+interface InsertMessage {
+    type: "cmssy:insert";
+    protocolVersion: number;
+    blockId: string;
+    blockType: string;
+    content: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    advanced?: Record<string, unknown>;
+    index: number;
+}
+interface ReorderMessage {
+    type: "cmssy:reorder";
+    protocolVersion: number;
+    blockIds: string[];
+}
+interface RemoveMessage {
+    type: "cmssy:remove";
+    protocolVersion: number;
+    blockId: string;
+}
+interface DragOverMessage {
+    type: "cmssy:drag-over";
+    protocolVersion: number;
+    y: number;
+}
+interface DragEndMessage {
+    type: "cmssy:drag-end";
+    protocolVersion: number;
+}
+type EditorToAppMessage = SelectMessage | PatchMessage | ParentReadyMessage | InsertMessage | ReorderMessage | RemoveMessage | DragOverMessage | DragEndMessage;
+declare function isProtocolCompatible(version: number): boolean;
+
+interface PostTarget {
+    postMessage: (message: unknown, targetOrigin: string) => void;
+}
+declare function normalizeOrigin(origin: string): string;
+declare function postToEditor(target: PostTarget, editorOrigin: string, message: AppToEditorMessage): void;
+declare function resolveInitialTarget(editorOrigin: string | string[]): string;
+declare function parseEditorMessage(data: unknown, origin: string, expectedOrigin: string | string[]): EditorToAppMessage | null;
+
+declare const CMSSY_EDIT_HEADER = "x-cmssy-edit";
+declare const CMSSY_EDIT_QUERY_PARAM = "cmssyEdit";
+declare const CMSSY_SECRET_QUERY_PARAM = "cmssySecret";
+interface EditSearchParams {
+    getAll: (name: string) => string[];
+    get: (name: string) => string | null;
+}
+declare function isVerifiedEditUrl(url: {
+    searchParams: EditSearchParams;
+}, config: {
+    draftSecret: string;
+}): Promise<boolean>;
+
+declare function cmssySecretsMatch(a: string, b: string): Promise<boolean>;
+
+interface CmssyCspOptions {
+    /** Defaults to the cmssy cloud admin origin when unset. */
+    editorOrigin?: string | string[];
+}
+interface MutableHeaders {
+    headers: {
+        get: (name: string) => string | null;
+        set: (name: string, value: string) => void;
+        delete: (name: string) => void;
+    };
+}
+declare function toCspOrigin(origin: string): string;
+declare function cmssyCspHeaders(options: CmssyCspOptions): Record<string, string>;
+declare function applyCmssyCsp<T extends MutableHeaders>(response: T, options: CmssyCspOptions): T;
+
+/**
+ * Resolve the default locale and the full locale list from the SDK config,
+ * falling back to the workspace site config (defaultLanguage / enabledLanguages)
+ * then "en". Shared by sitemap + metadata so their hreflang/canonical agree.
+ */
+declare function resolveSeoLocales(config: {
+    defaultLocale?: string;
+    enabledLocales?: string[];
+}, siteConfig: {
+    defaultLanguage?: string | null;
+    enabledLanguages?: string[];
+} | null): {
+    defaultLocale: string;
+    locales: string[];
+};
+/**
+ * Maps a page slug to its path for a locale: the default locale gets no
+ * prefix, others get `/${locale}`. The homepage ("/") stays "/" (or "/${locale}").
+ */
+declare function localizedPath(slug: string, locale: string, defaultLocale: string): string;
+
+declare const CMSSY_SESSION_COOKIE = "cmssy_session";
+declare const SESSION_MAX_AGE_SECONDS: number;
+declare const MIN_SESSION_SECRET_LENGTH = 32;
+declare function sealSession(payload: CmssySessionPayload, secret: string, audience?: string): Promise<string>;
+declare function openSession(token: string, secret: string, audience?: string): Promise<CmssySessionPayload | null>;
+declare function isAccessExpired(payload: CmssySessionPayload, now?: number): boolean;
+declare function sessionCookieOptions(): SessionCookieOptions;
+
+interface AuthMutationResult {
+    success: boolean;
+    message: string;
+}
+interface AuthTokenResult extends AuthMutationResult {
+    accessToken: string | null;
+    refreshToken: string | null;
+    accessTokenExpiresIn: number | null;
+}
+declare function decodeAccessClaims(accessToken: string): CmssySessionUser | null;
+declare function toSessionPayload(result: AuthTokenResult): CmssySessionPayload | null;
+declare function backendSignIn(config: CmssyConfig, modelSlug: string, identity: string, password: string): Promise<AuthTokenResult>;
+declare function backendRegister(config: CmssyConfig, modelSlug: string, identity: string, password: string, fields: Record<string, unknown>): Promise<AuthMutationResult>;
+declare function backendRefresh(config: CmssyConfig, refreshToken: string): Promise<AuthTokenResult>;
+declare function backendSignOut(config: CmssyConfig, refreshToken: string): Promise<void>;
+declare function backendSignOutEverywhere(config: CmssyConfig, accessToken: string): Promise<void>;
+declare function backendForgotPassword(config: CmssyConfig, modelSlug: string, identity: string): Promise<AuthMutationResult>;
+declare function backendResetPassword(config: CmssyConfig, token: string, newPassword: string): Promise<AuthMutationResult>;
+declare function backendVerifyEmail(config: CmssyConfig, token: string): Promise<AuthMutationResult>;
+
+interface CartRequestContext {
+    cartToken: string;
+    accessToken?: string;
+}
+declare function backendGetCart(config: CmssyConfig, ctx: CartRequestContext): Promise<CmssyCart | null>;
+declare function backendAddToCart(config: CmssyConfig, ctx: CartRequestContext, input: {
+    recordId: string;
+    quantity: number;
+    variantSelections?: Record<string, string>;
+    notes?: string;
+}): Promise<CmssyCart>;
+declare function backendUpdateItem(config: CmssyConfig, ctx: CartRequestContext, input: {
+    itemId: string;
+    quantity: number;
+}): Promise<CmssyCart>;
+declare function backendRemoveItem(config: CmssyConfig, ctx: CartRequestContext, itemId: string): Promise<CmssyCart>;
+declare function backendClearCart(config: CmssyConfig, ctx: CartRequestContext): Promise<CmssyCart>;
+declare function backendApplyDiscount(config: CmssyConfig, ctx: CartRequestContext, code: string): Promise<CmssyCart>;
+declare function backendRemoveDiscount(config: CmssyConfig, ctx: CartRequestContext): Promise<CmssyCart>;
+declare function backendSetShippingMethod(config: CmssyConfig, ctx: CartRequestContext, shippingMethodId: string | null): Promise<CmssyCart>;
+declare function backendMergeCart(config: CmssyConfig, ctx: CartRequestContext): Promise<CmssyCart>;
+interface CheckoutInput {
+    customerEmail: string;
+    poNumber?: string | null;
+    customerNote?: string | null;
+    shippingAddress?: CmssyAddress | null;
+}
+declare function backendCheckout(config: CmssyConfig, ctx: CartRequestContext, input: CheckoutInput): Promise<CmssyOrder>;
+declare function backendProduct(config: CmssyConfig, ctx: CartRequestContext, modelSlug: string, filter: Record<string, unknown>): Promise<CmssyProduct | null>;
+
+declare function backendMyOrders(config: CmssyConfig, accessToken: string, options: {
+    skip?: number;
+    limit?: number;
+}): Promise<MyOrdersResult>;
+declare function backendMyOrder(config: CmssyConfig, accessToken: string, id: string): Promise<CmssyOrder | null>;
+declare function backendOrderByToken(config: CmssyConfig, options: {
+    orderId: string;
+    accessToken: string;
+}): Promise<CmssyOrder>;
+
+declare const PRODUCTS_QUERY = "query Products($workspaceId: String!, $modelSlug: String!, $filter: JSON, $stockState: String, $locale: String, $limit: Int, $offset: Int, $sort: String) {\n  public {\n    model {\n      records(workspaceId: $workspaceId, modelSlug: $modelSlug, filter: $filter, stockState: $stockState, locale: $locale, limit: $limit, offset: $offset, sort: $sort) {\n        total\n        hasMore\n        items {\n          id\n          data\n          priceTiers { minQty price }\n          variants { id sku price inventory tiers { minQty price } selectedOptions { name value } }\n        }\n      }\n    }\n  }\n}";
+/**
+ * A catalog read is plain data: it takes the locale it is given. Framework
+ * adapters are the ones that know how to find the locale of the current request
+ * (@cmssy/next reads it from the middleware header) and pass it in. Omitting it
+ * means "the workspace's default language".
+ */
+declare function fetchProducts(config: CmssyConfig, options: FetchProductsOptions): Promise<CmssyProductPage>;
+declare function fetchProduct(config: CmssyConfig, options: FetchProductOptions): Promise<CmssyProduct | null>;
+
+declare function fetchOrderByToken(config: CmssyConfig, options: FetchOrderByTokenOptions): Promise<CmssyOrder>;
+
+declare function fractionDigits(currency: string): number;
+declare function fromMinorUnits(minor: number, currency: string): number;
+declare function toMinorUnits(amount: number, currency: string): number;
+declare function formatPrice(minor: number, currency: string | null | undefined): string;
+
+/**
+ * Verify + parse an inbound cmssy webhook (CMS-693 / CMS-694).
+ *
+ * cmssy signs each delivery with HMAC-SHA256 over `${timestamp}.${body}`
+ * and sends the result in the `X-Cmssy-Signature: t=<ms>,v1=<hex>`
+ * header, plus a unique `X-Cmssy-Webhook-Id`. This helper recomputes the
+ * signature (timing-safe compare), rejects stale timestamps to bound
+ * replay, and returns the typed event.
+ *
+ * IMPORTANT: pass the RAW request body string (e.g. `await req.text()`),
+ * never a re-serialized object - the signed bytes must match exactly.
+ */
+declare class CmssyWebhookError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify the signature + freshness and return the parsed event. Throws
+ * `CmssyWebhookError` on any failure (missing/malformed header, bad
+ * signature, stale timestamp, invalid JSON) - catch it and respond 400.
+ */
+declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): CmssyWebhookEvent;
+
+export { type AppToEditorMessage, type AuthMutationResult, type AuthTokenResult, type BoundsMessage, CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, type CartRequestContext, type CheckoutInput, type ClickMessage, type CmssyClient, type CmssyConfig, type CmssyCspOptions, type CmssyEnvConfig, CmssyRequestError, CmssyWebhookError, DEFAULT_CMSSY_API_URL, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, type FetchLike, type FetchLikeResponse, type FetchPageOptions, type GraphqlRequestOptions, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, type RetryPolicy, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchLayouts, fetchOrderByToken, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, normalizeSlug, openSession, parseEditorMessage, postToEditor, resolveApiUrl, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolvePublicUrl, resolveSeoLocales, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };