@cmssy/core 9.0.0 → 9.1.1

package/dist/content-client-D0EdiqbQ.d.cts

@@ -0,0 +1,63 @@
+import { CmssyClientConfig, CmssyLayoutGroup, CmssyPageData, CmssyPageMeta, CmssyPageSummary } from '@cmssy/types';
+
+/** 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[]>;
+
+export { CmssyRequestError as C, DEFAULT_CMSSY_API_URL as D, type FetchLike as F, type RetryPolicy as R, type FetchLikeResponse as a, type FetchPageOptions as b, fetchPage as c, fetchPageById as d, fetchPageMeta as e, fetchLayouts as f, fetchPages as g, resolvePublicUrl as h, normalizeSlug as n, resolveApiUrl as r };

package/dist/content-client-D0EdiqbQ.d.ts

@@ -0,0 +1,63 @@
+import { CmssyClientConfig, CmssyLayoutGroup, CmssyPageData, CmssyPageMeta, CmssyPageSummary } from '@cmssy/types';
+
+/** 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[]>;
+
+export { CmssyRequestError as C, DEFAULT_CMSSY_API_URL as D, type FetchLike as F, type RetryPolicy as R, type FetchLikeResponse as a, type FetchPageOptions as b, fetchPage as c, fetchPageById as d, fetchPageMeta as e, fetchLayouts as f, fetchPages as g, resolvePublicUrl as h, normalizeSlug as n, resolveApiUrl as r };

package/dist/index.d.cts

@@ -1,6 +1,8 @@
 import * as _cmssy_types from '@cmssy/types';
-import { CmssyAuthConfig, CmssyClientConfig, CmssyLayoutGroup, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
+import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
 export { BlockMeta, BlockPropsSchema, 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, FieldOptions, FieldType, InferBlockContent, MyOrdersResult, RawBlock, RawLayoutBlock, SessionCookieOptions, SubmitFormInput, TypedField, VerifyCmssyWebhookOptions, evaluateFieldConditionGroup } from '@cmssy/types';
+import { F as FetchLike, R as RetryPolicy } from './content-client-D0EdiqbQ.cjs';
+export { C as CmssyRequestError, D as DEFAULT_CMSSY_API_URL, a as FetchLikeResponse, b as FetchPageOptions, f as fetchLayouts, c as fetchPage, d as fetchPageById, e as fetchPageMeta, g as fetchPages, n as normalizeSlug, r as resolveApiUrl, h as resolvePublicUrl } from './content-client-D0EdiqbQ.cjs';
 
 declare const DEFAULT_CMSSY_EDITOR_ORIGINS: string[];
 declare function isDevelopment(): boolean;
@@ -65,66 +67,6 @@ type CmssyEnvConfig = Omit<CmssyConfig, "org" | "workspaceSlug" | "draftSecret">
 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
@@ -502,4 +444,4 @@ declare class CmssyWebhookError extends Error {
  */
 declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): Promise<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, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, normalizeSlug, openSession, parseEditorMessage, postToEditor, resolveApiUrl, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };
+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, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, 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, 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, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as _cmssy_types from '@cmssy/types';
-import { CmssyAuthConfig, CmssyClientConfig, CmssyLayoutGroup, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
+import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
 export { BlockMeta, BlockPropsSchema, 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, FieldOptions, FieldType, InferBlockContent, MyOrdersResult, RawBlock, RawLayoutBlock, SessionCookieOptions, SubmitFormInput, TypedField, VerifyCmssyWebhookOptions, evaluateFieldConditionGroup } from '@cmssy/types';
+import { F as FetchLike, R as RetryPolicy } from './content-client-D0EdiqbQ.js';
+export { C as CmssyRequestError, D as DEFAULT_CMSSY_API_URL, a as FetchLikeResponse, b as FetchPageOptions, f as fetchLayouts, c as fetchPage, d as fetchPageById, e as fetchPageMeta, g as fetchPages, n as normalizeSlug, r as resolveApiUrl, h as resolvePublicUrl } from './content-client-D0EdiqbQ.js';
 
 declare const DEFAULT_CMSSY_EDITOR_ORIGINS: string[];
 declare function isDevelopment(): boolean;
@@ -65,66 +67,6 @@ type CmssyEnvConfig = Omit<CmssyConfig, "org" | "workspaceSlug" | "draftSecret">
 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
@@ -502,4 +444,4 @@ declare class CmssyWebhookError extends Error {
  */
 declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): Promise<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, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, normalizeSlug, openSession, parseEditorMessage, postToEditor, resolveApiUrl, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };
+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, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, 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, 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, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };

package/dist/preflight.cjs

@@ -0,0 +1,273 @@
+'use strict';
+
+// src/content/content-client.ts
+var DEFAULT_CMSSY_API_URL = "https://api.cmssy.io/graphql";
+function resolveApiUrl(apiUrl) {
+  const explicit = apiUrl?.trim();
+  if (explicit) return explicit;
+  const env = globalThis.process?.env;
+  const fromEnv = env?.CMSSY_API_URL?.trim() ?? "";
+  return fromEnv.length > 0 ? fromEnv : DEFAULT_CMSSY_API_URL;
+}
+function resolvePublicUrl(config) {
+  const base = resolveApiUrl(config.apiUrl).replace(/\/graphql\/?$/, "");
+  return `${base}/public/${config.org}/${config.workspaceSlug}/graphql`;
+}
+
+// src/preflight.ts
+var CMSSY_ADMIN_ORIGIN = "https://www.cmssy.io";
+var ALLOWED_FRAME_HOSTS = ["cmssy.io", "www.cmssy.io"];
+var SETTINGS_PATH = "Settings \u2192 Headless";
+var PREFLIGHT_SITE_CONFIG_QUERY = `query PreflightSiteConfig($workspaceSlug: String!) {
+  public {
+    siteConfig(workspaceSlug: $workspaceSlug) {
+      previewUrl
+      publicSiteUrl
+    }
+  }
+}`;
+var DRAFT_SECRET_VALID_QUERY = `query PreflightDraftSecretValid($workspaceSlug: String!, $secret: String!) {
+  public {
+    draftSecretValid(workspaceSlug: $workspaceSlug, secret: $secret)
+  }
+}`;
+async function postPreflightQuery(config, query, variables) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    return {
+      kind: "network",
+      error: new Error("cmssy: no fetch implementation available")
+    };
+  }
+  const url = resolvePublicUrl(config);
+  let response;
+  try {
+    response = await doFetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ query, variables })
+    });
+  } catch (error) {
+    return { kind: "network", error };
+  }
+  let envelope = null;
+  try {
+    envelope = await response.json();
+  } catch {
+    envelope = null;
+  }
+  const errors = Array.isArray(envelope?.errors) ? envelope.errors : [];
+  if (errors.length > 0) {
+    return { kind: "errors", errors, httpStatus: response.status };
+  }
+  if (!response.ok) {
+    return { kind: "http", status: response.status };
+  }
+  return { kind: "data", data: envelope?.data };
+}
+function errorMessages(errors) {
+  return errors.map((error) => error.message ?? "GraphQL error").join("; ");
+}
+function hasErrorCode(errors, code) {
+  return errors.some((error) => error.extensions?.code === code);
+}
+function isValidationError(errors) {
+  return errors.some(
+    (error) => error.extensions?.code === "GRAPHQL_VALIDATION_FAILED" || /cannot query field/i.test(error.message ?? "")
+  );
+}
+function isNotFound(errors, httpStatus) {
+  return httpStatus === 404 || hasErrorCode(errors, "NOT_FOUND") || errors.some((error) => /not found/i.test(error.message ?? ""));
+}
+async function checkWorkspaceReachable(config) {
+  const workspace = `${config.org}/${config.workspaceSlug}`;
+  const outcome = await postPreflightQuery(config, PREFLIGHT_SITE_CONFIG_QUERY, {
+    workspaceSlug: config.workspaceSlug
+  });
+  if (outcome.kind === "network") {
+    return {
+      status: "fail",
+      message: `cannot reach the cmssy API at ${resolvePublicUrl(config)}`,
+      fix: "check your network connection and CMSSY_API_URL (leave it unset for cmssy cloud)"
+    };
+  }
+  if (outcome.kind === "http" && outcome.status === 429 || outcome.kind === "errors" && (outcome.httpStatus === 429 || hasErrorCode(outcome.errors, "TOO_MANY_REQUESTS"))) {
+    return {
+      status: "fail",
+      message: `workspace ${workspace} is over its delivery limit (rate limited)`,
+      fix: "upgrade the organization plan or wait for the usage window to reset"
+    };
+  }
+  if (outcome.kind === "errors") {
+    if (isNotFound(outcome.errors, outcome.httpStatus)) {
+      return {
+        status: "fail",
+        message: `workspace ${workspace} was not found`,
+        fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+      };
+    }
+    return {
+      status: "fail",
+      message: `the cmssy API rejected the request - ${errorMessages(outcome.errors)}`
+    };
+  }
+  if (outcome.kind === "http") {
+    if (outcome.status === 404) {
+      return {
+        status: "fail",
+        message: `workspace ${workspace} was not found`,
+        fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+      };
+    }
+    return {
+      status: "fail",
+      message: `the cmssy API responded with HTTP ${outcome.status}`
+    };
+  }
+  const siteConfig = outcome.data?.public?.siteConfig;
+  if (!siteConfig) {
+    return {
+      status: "fail",
+      message: `workspace ${workspace} was not found`,
+      fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+    };
+  }
+  const previewUrl = siteConfig.previewUrl?.trim();
+  return {
+    status: "ok",
+    message: `workspace ${workspace} is reachable`,
+    ...previewUrl ? { previewUrl } : {}
+  };
+}
+async function checkDraftSecret(config) {
+  const secret = config.draftSecret?.trim();
+  if (!secret) {
+    return {
+      status: "fail",
+      message: "CMSSY_DRAFT_SECRET is not set",
+      fix: `copy the draft secret from ${SETTINGS_PATH}`
+    };
+  }
+  const outcome = await postPreflightQuery(config, DRAFT_SECRET_VALID_QUERY, {
+    workspaceSlug: config.workspaceSlug,
+    secret
+  });
+  if (outcome.kind === "network") {
+    return {
+      status: "unknown",
+      message: "could not verify the draft secret (network error)"
+    };
+  }
+  if (outcome.kind === "errors") {
+    if (isValidationError(outcome.errors)) {
+      return {
+        status: "unknown",
+        message: "this cmssy platform does not support draft secret verification yet"
+      };
+    }
+    return {
+      status: "unknown",
+      message: `could not verify the draft secret - ${errorMessages(outcome.errors)}`
+    };
+  }
+  if (outcome.kind === "http") {
+    return {
+      status: "unknown",
+      message: `could not verify the draft secret (HTTP ${outcome.status})`
+    };
+  }
+  if (outcome.data?.public?.draftSecretValid === true) {
+    return { status: "ok", message: "the draft secret is valid" };
+  }
+  return {
+    status: "fail",
+    message: "the draft secret does not match this workspace",
+    fix: `copy the secret from ${SETTINGS_PATH} into CMSSY_DRAFT_SECRET`
+  };
+}
+function parseOrigin(value) {
+  try {
+    const origin = new URL(value).origin;
+    return origin === "null" ? null : origin;
+  } catch {
+    return null;
+  }
+}
+function checkPreviewUrl(previewUrl, devOrigin) {
+  const trimmed = previewUrl?.trim();
+  if (!trimmed) {
+    return {
+      status: "fail",
+      message: "no preview URL is set for this workspace",
+      fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+    };
+  }
+  const previewOrigin = parseOrigin(trimmed);
+  if (!previewOrigin) {
+    return {
+      status: "fail",
+      message: `the workspace preview URL "${trimmed}" is not a valid URL`,
+      fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+    };
+  }
+  const localOrigin = parseOrigin(devOrigin);
+  if (previewOrigin === localOrigin) {
+    return {
+      status: "ok",
+      message: `the workspace preview URL matches ${devOrigin}`
+    };
+  }
+  return {
+    status: "fail",
+    message: `the workspace preview URL is ${previewOrigin} but your dev server runs at ${devOrigin}`,
+    fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+  };
+}
+function frameAncestorSources(cspHeaderValue) {
+  const directive = cspHeaderValue.split(";").map((part) => part.trim()).find((part) => /^frame-ancestors\b/i.test(part));
+  if (!directive) return null;
+  return directive.split(/\s+/).slice(1).map((source) => source.toLowerCase().replace(/^'|'$/g, ""));
+}
+function allowsCmssyAdmin(source) {
+  if (source === "*" || source === "https:") return true;
+  const host = source.replace(/^[a-z][a-z0-9+.-]*:\/\//, "").split("/")[0];
+  if (!host) return false;
+  if (host === "*.cmssy.io") return true;
+  return ALLOWED_FRAME_HOSTS.includes(host);
+}
+function checkFrameAncestors(cspHeaderValue) {
+  if (!cspHeaderValue || cspHeaderValue.trim().length === 0) {
+    return {
+      status: "ok",
+      message: "no Content-Security-Policy restricts framing"
+    };
+  }
+  const sources = frameAncestorSources(cspHeaderValue);
+  if (sources === null) {
+    return {
+      status: "ok",
+      message: "the Content-Security-Policy has no frame-ancestors directive"
+    };
+  }
+  if (sources.some(allowsCmssyAdmin)) {
+    return {
+      status: "ok",
+      message: "frame-ancestors allows the cmssy editor"
+    };
+  }
+  return {
+    status: "fail",
+    message: `frame-ancestors (${sources.join(" ") || "'none'"}) blocks the cmssy editor`,
+    fix: "add https://cmssy.io https://www.cmssy.io to the frame-ancestors directive (applyCmssyCsp does this for you)"
+  };
+}
+function buildEditorUrl(config, pageId) {
+  const base = `${CMSSY_ADMIN_ORIGIN}/dashboard/organizations/${config.org}/workspaces/${config.workspaceSlug}/editor`;
+  return pageId ? `${base}?pageId=${encodeURIComponent(pageId)}` : base;
+}
+
+exports.buildEditorUrl = buildEditorUrl;
+exports.checkDraftSecret = checkDraftSecret;
+exports.checkFrameAncestors = checkFrameAncestors;
+exports.checkPreviewUrl = checkPreviewUrl;
+exports.checkWorkspaceReachable = checkWorkspaceReachable;

package/dist/preflight.d.cts

@@ -0,0 +1,23 @@
+import { F as FetchLike } from './content-client-D0EdiqbQ.cjs';
+import { CmssyClientConfig } from '@cmssy/types';
+
+type PreflightStatus = "ok" | "fail" | "unknown";
+interface PreflightResult {
+    status: PreflightStatus;
+    message: string;
+    fix?: string;
+}
+interface WorkspaceReachableResult extends PreflightResult {
+    previewUrl?: string;
+}
+interface PreflightConfig extends CmssyClientConfig {
+    draftSecret?: string;
+    fetch?: FetchLike;
+}
+declare function checkWorkspaceReachable(config: PreflightConfig): Promise<WorkspaceReachableResult>;
+declare function checkDraftSecret(config: PreflightConfig): Promise<PreflightResult>;
+declare function checkPreviewUrl(previewUrl: string | null | undefined, devOrigin: string): PreflightResult;
+declare function checkFrameAncestors(cspHeaderValue: string | null | undefined): PreflightResult;
+declare function buildEditorUrl(config: Pick<CmssyClientConfig, "org" | "workspaceSlug">, pageId?: string): string;
+
+export { type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };

package/dist/preflight.d.ts

@@ -0,0 +1,23 @@
+import { F as FetchLike } from './content-client-D0EdiqbQ.js';
+import { CmssyClientConfig } from '@cmssy/types';
+
+type PreflightStatus = "ok" | "fail" | "unknown";
+interface PreflightResult {
+    status: PreflightStatus;
+    message: string;
+    fix?: string;
+}
+interface WorkspaceReachableResult extends PreflightResult {
+    previewUrl?: string;
+}
+interface PreflightConfig extends CmssyClientConfig {
+    draftSecret?: string;
+    fetch?: FetchLike;
+}
+declare function checkWorkspaceReachable(config: PreflightConfig): Promise<WorkspaceReachableResult>;
+declare function checkDraftSecret(config: PreflightConfig): Promise<PreflightResult>;
+declare function checkPreviewUrl(previewUrl: string | null | undefined, devOrigin: string): PreflightResult;
+declare function checkFrameAncestors(cspHeaderValue: string | null | undefined): PreflightResult;
+declare function buildEditorUrl(config: Pick<CmssyClientConfig, "org" | "workspaceSlug">, pageId?: string): string;
+
+export { type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };

package/dist/preflight.js

@@ -0,0 +1,267 @@
+// src/content/content-client.ts
+var DEFAULT_CMSSY_API_URL = "https://api.cmssy.io/graphql";
+function resolveApiUrl(apiUrl) {
+  const explicit = apiUrl?.trim();
+  if (explicit) return explicit;
+  const env = globalThis.process?.env;
+  const fromEnv = env?.CMSSY_API_URL?.trim() ?? "";
+  return fromEnv.length > 0 ? fromEnv : DEFAULT_CMSSY_API_URL;
+}
+function resolvePublicUrl(config) {
+  const base = resolveApiUrl(config.apiUrl).replace(/\/graphql\/?$/, "");
+  return `${base}/public/${config.org}/${config.workspaceSlug}/graphql`;
+}
+
+// src/preflight.ts
+var CMSSY_ADMIN_ORIGIN = "https://www.cmssy.io";
+var ALLOWED_FRAME_HOSTS = ["cmssy.io", "www.cmssy.io"];
+var SETTINGS_PATH = "Settings \u2192 Headless";
+var PREFLIGHT_SITE_CONFIG_QUERY = `query PreflightSiteConfig($workspaceSlug: String!) {
+  public {
+    siteConfig(workspaceSlug: $workspaceSlug) {
+      previewUrl
+      publicSiteUrl
+    }
+  }
+}`;
+var DRAFT_SECRET_VALID_QUERY = `query PreflightDraftSecretValid($workspaceSlug: String!, $secret: String!) {
+  public {
+    draftSecretValid(workspaceSlug: $workspaceSlug, secret: $secret)
+  }
+}`;
+async function postPreflightQuery(config, query, variables) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    return {
+      kind: "network",
+      error: new Error("cmssy: no fetch implementation available")
+    };
+  }
+  const url = resolvePublicUrl(config);
+  let response;
+  try {
+    response = await doFetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ query, variables })
+    });
+  } catch (error) {
+    return { kind: "network", error };
+  }
+  let envelope = null;
+  try {
+    envelope = await response.json();
+  } catch {
+    envelope = null;
+  }
+  const errors = Array.isArray(envelope?.errors) ? envelope.errors : [];
+  if (errors.length > 0) {
+    return { kind: "errors", errors, httpStatus: response.status };
+  }
+  if (!response.ok) {
+    return { kind: "http", status: response.status };
+  }
+  return { kind: "data", data: envelope?.data };
+}
+function errorMessages(errors) {
+  return errors.map((error) => error.message ?? "GraphQL error").join("; ");
+}
+function hasErrorCode(errors, code) {
+  return errors.some((error) => error.extensions?.code === code);
+}
+function isValidationError(errors) {
+  return errors.some(
+    (error) => error.extensions?.code === "GRAPHQL_VALIDATION_FAILED" || /cannot query field/i.test(error.message ?? "")
+  );
+}
+function isNotFound(errors, httpStatus) {
+  return httpStatus === 404 || hasErrorCode(errors, "NOT_FOUND") || errors.some((error) => /not found/i.test(error.message ?? ""));
+}
+async function checkWorkspaceReachable(config) {
+  const workspace = `${config.org}/${config.workspaceSlug}`;
+  const outcome = await postPreflightQuery(config, PREFLIGHT_SITE_CONFIG_QUERY, {
+    workspaceSlug: config.workspaceSlug
+  });
+  if (outcome.kind === "network") {
+    return {
+      status: "fail",
+      message: `cannot reach the cmssy API at ${resolvePublicUrl(config)}`,
+      fix: "check your network connection and CMSSY_API_URL (leave it unset for cmssy cloud)"
+    };
+  }
+  if (outcome.kind === "http" && outcome.status === 429 || outcome.kind === "errors" && (outcome.httpStatus === 429 || hasErrorCode(outcome.errors, "TOO_MANY_REQUESTS"))) {
+    return {
+      status: "fail",
+      message: `workspace ${workspace} is over its delivery limit (rate limited)`,
+      fix: "upgrade the organization plan or wait for the usage window to reset"
+    };
+  }
+  if (outcome.kind === "errors") {
+    if (isNotFound(outcome.errors, outcome.httpStatus)) {
+      return {
+        status: "fail",
+        message: `workspace ${workspace} was not found`,
+        fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+      };
+    }
+    return {
+      status: "fail",
+      message: `the cmssy API rejected the request - ${errorMessages(outcome.errors)}`
+    };
+  }
+  if (outcome.kind === "http") {
+    if (outcome.status === 404) {
+      return {
+        status: "fail",
+        message: `workspace ${workspace} was not found`,
+        fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+      };
+    }
+    return {
+      status: "fail",
+      message: `the cmssy API responded with HTTP ${outcome.status}`
+    };
+  }
+  const siteConfig = outcome.data?.public?.siteConfig;
+  if (!siteConfig) {
+    return {
+      status: "fail",
+      message: `workspace ${workspace} was not found`,
+      fix: "check CMSSY_ORG_SLUG and CMSSY_WORKSPACE_SLUG against your dashboard URL"
+    };
+  }
+  const previewUrl = siteConfig.previewUrl?.trim();
+  return {
+    status: "ok",
+    message: `workspace ${workspace} is reachable`,
+    ...previewUrl ? { previewUrl } : {}
+  };
+}
+async function checkDraftSecret(config) {
+  const secret = config.draftSecret?.trim();
+  if (!secret) {
+    return {
+      status: "fail",
+      message: "CMSSY_DRAFT_SECRET is not set",
+      fix: `copy the draft secret from ${SETTINGS_PATH}`
+    };
+  }
+  const outcome = await postPreflightQuery(config, DRAFT_SECRET_VALID_QUERY, {
+    workspaceSlug: config.workspaceSlug,
+    secret
+  });
+  if (outcome.kind === "network") {
+    return {
+      status: "unknown",
+      message: "could not verify the draft secret (network error)"
+    };
+  }
+  if (outcome.kind === "errors") {
+    if (isValidationError(outcome.errors)) {
+      return {
+        status: "unknown",
+        message: "this cmssy platform does not support draft secret verification yet"
+      };
+    }
+    return {
+      status: "unknown",
+      message: `could not verify the draft secret - ${errorMessages(outcome.errors)}`
+    };
+  }
+  if (outcome.kind === "http") {
+    return {
+      status: "unknown",
+      message: `could not verify the draft secret (HTTP ${outcome.status})`
+    };
+  }
+  if (outcome.data?.public?.draftSecretValid === true) {
+    return { status: "ok", message: "the draft secret is valid" };
+  }
+  return {
+    status: "fail",
+    message: "the draft secret does not match this workspace",
+    fix: `copy the secret from ${SETTINGS_PATH} into CMSSY_DRAFT_SECRET`
+  };
+}
+function parseOrigin(value) {
+  try {
+    const origin = new URL(value).origin;
+    return origin === "null" ? null : origin;
+  } catch {
+    return null;
+  }
+}
+function checkPreviewUrl(previewUrl, devOrigin) {
+  const trimmed = previewUrl?.trim();
+  if (!trimmed) {
+    return {
+      status: "fail",
+      message: "no preview URL is set for this workspace",
+      fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+    };
+  }
+  const previewOrigin = parseOrigin(trimmed);
+  if (!previewOrigin) {
+    return {
+      status: "fail",
+      message: `the workspace preview URL "${trimmed}" is not a valid URL`,
+      fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+    };
+  }
+  const localOrigin = parseOrigin(devOrigin);
+  if (previewOrigin === localOrigin) {
+    return {
+      status: "ok",
+      message: `the workspace preview URL matches ${devOrigin}`
+    };
+  }
+  return {
+    status: "fail",
+    message: `the workspace preview URL is ${previewOrigin} but your dev server runs at ${devOrigin}`,
+    fix: `paste ${devOrigin} into the preview URL field in ${SETTINGS_PATH}`
+  };
+}
+function frameAncestorSources(cspHeaderValue) {
+  const directive = cspHeaderValue.split(";").map((part) => part.trim()).find((part) => /^frame-ancestors\b/i.test(part));
+  if (!directive) return null;
+  return directive.split(/\s+/).slice(1).map((source) => source.toLowerCase().replace(/^'|'$/g, ""));
+}
+function allowsCmssyAdmin(source) {
+  if (source === "*" || source === "https:") return true;
+  const host = source.replace(/^[a-z][a-z0-9+.-]*:\/\//, "").split("/")[0];
+  if (!host) return false;
+  if (host === "*.cmssy.io") return true;
+  return ALLOWED_FRAME_HOSTS.includes(host);
+}
+function checkFrameAncestors(cspHeaderValue) {
+  if (!cspHeaderValue || cspHeaderValue.trim().length === 0) {
+    return {
+      status: "ok",
+      message: "no Content-Security-Policy restricts framing"
+    };
+  }
+  const sources = frameAncestorSources(cspHeaderValue);
+  if (sources === null) {
+    return {
+      status: "ok",
+      message: "the Content-Security-Policy has no frame-ancestors directive"
+    };
+  }
+  if (sources.some(allowsCmssyAdmin)) {
+    return {
+      status: "ok",
+      message: "frame-ancestors allows the cmssy editor"
+    };
+  }
+  return {
+    status: "fail",
+    message: `frame-ancestors (${sources.join(" ") || "'none'"}) blocks the cmssy editor`,
+    fix: "add https://cmssy.io https://www.cmssy.io to the frame-ancestors directive (applyCmssyCsp does this for you)"
+  };
+}
+function buildEditorUrl(config, pageId) {
+  const base = `${CMSSY_ADMIN_ORIGIN}/dashboard/organizations/${config.org}/workspaces/${config.workspaceSlug}/editor`;
+  return pageId ? `${base}?pageId=${encodeURIComponent(pageId)}` : base;
+}
+
+export { buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/core",
-  "version": "9.0.0",
+  "version": "9.1.1",
   "description": "Framework-agnostic cmssy client: content, commerce, config, editor protocol. No React, no Next.",
   "keywords": [
     "cmssy",
@@ -31,6 +31,11 @@
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js",
       "require": "./dist/testing.cjs"
+    },
+    "./preflight": {
+      "types": "./dist/preflight.d.ts",
+      "import": "./dist/preflight.js",
+      "require": "./dist/preflight.cjs"
     }
   },
   "main": "./dist/index.cjs",