@createcms/core 0.1.1

package/dist/react/index.d.cts

@@ -0,0 +1,992 @@
+import { WritableAtom, ReadableAtom } from 'nanostores';
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { AnyPgTable, PgDatabase } from 'drizzle-orm/pg-core';
+import { AnyColumn, SQL } from 'drizzle-orm';
+import { Endpoint, Middleware } from 'better-call';
+export { BlockComponentProps, BlockProps, BlocksMap, BlocksRenderer, createBlocksMap, createBlocksRenderer, createContentRenderer, extractBlockEvents } from './blocks.cjs';
+export { pickVariant } from './variant.cjs';
+
+type ResolvedUserConfig = {
+    table: AnyPgTable;
+    tableName: string;
+    schemaName: string | null;
+    idColumn: AnyColumn;
+    /** The camelCase key used in the Drizzle table definition (e.g. "id"). */
+    idColumnKey: string;
+    /** The actual database column name (e.g. "id" or "user_id"). */
+    idColumnDbName: string;
+    allColumns: Record<string, AnyColumn>;
+    /** Allowlist (camelCase keys) of columns exposable via `withUser`. */
+    exposeColumns: string[];
+    sqlTableRef: string;
+};
+
+type DrizzleInstance = PgDatabase<any, Record<string, unknown>, any>;
+
+declare const notificationTypeEnum: drizzle_orm_pg_core.PgEnum<["mention", "comment", "threadResolved", "approvalRequested", "approvalApproved", "approvalRejected", "mergeRequestOpened", "mergeRequestMerged", "mergeRequestClosed", "mergeRequestReopened", "published", "custom"]>;
+
+type NotificationType = (typeof notificationTypeEnum.enumValues)[number];
+type NotificationPayload = {
+    id: string;
+    recipientId: string;
+    actorId: string | null;
+    type: NotificationType;
+    title: string;
+    body: string | null;
+    resourceType: string | null;
+    resourceId: string | null;
+    collection: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: Date;
+};
+type OnNotificationHandler = (notification: NotificationPayload) => void | Promise<void>;
+type NotificationInput = Omit<NotificationPayload, 'id' | 'createdAt'>;
+
+type NotificationService = ReturnType<typeof createNotificationService>;
+declare function createNotificationService(db: DrizzleInstance, handlers: OnNotificationHandler[]): {
+    notify(input: NotificationInput): Promise<NotificationPayload>;
+    notifyMany(inputs: NotificationInput[]): Promise<NotificationPayload[]>;
+};
+
+/**
+ * Per-request scope produced by a ScopeConditionFactory.
+ * `where` — appended to SELECT/UPDATE/DELETE queries.
+ * `insertColumns` — snake_case column name → value pairs merged directly
+ *   into the raw SQL INSERT via `scopedInsert` / `scopedInsertBatch`.
+ */
+type TableScope = {
+    where?: SQL;
+    insertColumns?: Record<string, unknown>;
+};
+/**
+ * `roots` scope additionally supports a per-NEW-ENTRY column contributor: a
+ * plugin can compute fresh insert columns once per newly-created logical entry
+ * (e.g. a freshly minted translation-group id), which the static `insertColumns`
+ * channel (same value on every row) can't express. Called once per
+ * createRoot / root-duplication. Generic — core names no column. (Seam D.)
+ */
+type RootTableScope = TableScope & {
+    newEntryColumns?: () => Record<string, unknown>;
+    /**
+     * Scope columns to EXCLUDE from cross-scope read filtering — columns the
+     * plugin varies INDEPENDENTLY of a query so that cross-scope reads (a
+     * reference/host/usage that legitimately spans them) must not filter on them.
+     * The i18n plugin declares `['language']` (a host/reference in any sibling
+     * language still counts; the read path already resolved a specific sibling).
+     * Generic — core names no column; passed to `rootScopeConditions` as its
+     * `exclude`. Empty/absent → every scope column filters. (Seam D6.)
+     */
+    crossScopeExclude?: readonly string[];
+};
+/**
+ * A plugin-provided resolver for reference values (rootId / group-key strings),
+ * carried on the resolved scope and consumed by the read path and the A/B
+ * co-render walk. Core ships an IDENTITY default (`coreReferenceResolver`)
+ * reproducing the single-language, no-plugin behaviour byte-for-byte; the i18n
+ * plugin supplies a real one that understands translation groups + the fallback
+ * chain. Core never names any i18n concept — it knows only this interface.
+ *
+ * `db` AND `scopeColumns` are passed PER CALL (not closed over): `db` so a
+ * caller inside a transaction (e.g. the A/B →running guard under FOR UPDATE)
+ * resolves against its own tx handle; `scopeColumns` because the MERGED root
+ * scope columns (tenant + language) exist only AFTER every scope factory has
+ * run — the i18n factory that builds the resolver sees only its OWN column at
+ * build time. The resolver therefore closes over just its resolution POLICY
+ * (e.g. the i18n active language + fallback chain). `scopeColumns` is the
+ * scope predicate; the resolver excludes its own cross-scope columns.
+ * (Seam B.)
+ */
+type ReferenceResolver = {
+    /**
+     * Read-time render pick: stored reference value → the ONE rootId it renders
+     * as (omit a key to leave it unresolved). Identity default: `value → value`.
+     */
+    resolveRenderTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, collection: string, storedValues: string[]): Promise<Map<string, string>>;
+    /**
+     * Conflict superset: stored reference keys → ALL rootIds they could render as
+     * (a group key expands to its whole group). Used by the A/B co-render walk;
+     * collection-agnostic (a reference may target any collection). Identity
+     * default: the existing, non-archived roots among `storedKeys` (by id).
+     */
+    resolveConflictTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, storedKeys: string[]): Promise<string[]>;
+    /** rootIds → all their group siblings. Identity default: the input rootIds. */
+    expandGroup(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+    /** rootIds → the group keys a host could embed them by. Default: `[]`. */
+    groupKeysFor(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+};
+/** One variant branch of a running A/B test on a referenced root. */
+type RunningAbTestVariant = {
+    branchId: string;
+    isControl: boolean;
+};
+/** A running A/B test on one root: the test plus its variant branches. */
+type RunningAbTest = {
+    testId: string;
+    trafficPercentage: number;
+    variants: RunningAbTestVariant[];
+};
+/**
+ * A plugin-provided resolver that reports which referenced roots currently have
+ * a RUNNING A/B test (with that test's variant branches). Carried on the
+ * resolved scope and consumed by the read path's reference loader to fan the one
+ * XOR-guaranteed varying block's branches out to the client (AB_FANOUT F2). Core
+ * ships NO default — when absent (no ab-test plugin) the read path assumes no
+ * running tests and every embed stays on its deterministic single pick (F0).
+ * Core never names any A/B concept beyond this interface. (Seam F.)
+ */
+type AbTestResolver = {
+    /**
+     * The subset of `rootIds` that have a running test, each mapped to its test +
+     * variant branches. `db` AND `scopeColumns` are passed PER CALL (same
+     * rationale as {@link ReferenceResolver}). The caller passes already
+     * render-resolved (active-language) rootIds, so this needs no group expansion.
+     */
+    runningTests(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<Map<string, RunningAbTest>>;
+};
+type ResolvedScope = {
+    roots?: RootTableScope;
+    assets?: TableScope;
+    assetFolders?: TableScope;
+    redirects?: TableScope;
+    /**
+     * Plugin-provided reference resolver (i18n translation-group resolution). When
+     * absent, callers use core's identity default. Generic — see `ReferenceResolver`.
+     */
+    referenceResolver?: ReferenceResolver;
+    /**
+     * Plugin-provided running-A/B-test resolver (AB_FANOUT F2 server fan-out).
+     * When absent, the read path assumes no running tests. Generic — see
+     * {@link AbTestResolver}.
+     */
+    abTestResolver?: AbTestResolver;
+    /**
+     * Opaque per-plugin context slots, keyed by plugin id. Core never reads it;
+     * each plugin stashes its own per-request context here from a scope factory
+     * and reads it back via its own exported accessor. Merged generically in
+     * computeScope (shallow, last-writer-wins per slot).
+     */
+    pluginContext?: Record<string, unknown>;
+};
+/**
+ * Factory registered by plugins during `init`.
+ * Called once per request with the middleware result to produce
+ * table-level WHERE conditions and extra INSERT values.
+ */
+type ScopeConditionFactory = (mwResult: MiddlewareResult) => ResolvedScope;
+type BlockTypes = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    richText: string;
+    image: string;
+    select: string;
+    reference: string;
+};
+type BlockPropertyType = keyof BlockTypes;
+type SelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+type BlockPropertySpec<T extends BlockPropertyType> = {
+    type: T;
+    required?: boolean;
+    defaultValue?: BlockTypes[T];
+    label: string;
+    description?: string;
+    placeholder?: string;
+} & (T extends 'select' ? {
+    options: readonly SelectOption[];
+} : {}) & (T extends 'reference' ? {
+    collection: string;
+} : {});
+/** Discriminated union over all concrete block-property specs. */
+type BlockProperty = {
+    [K in BlockPropertyType]: BlockPropertySpec<K>;
+}[BlockPropertyType];
+/** Scalar property subset usable as an event parameter (no references/media). */
+type ScalarBlockProperty = Extract<BlockProperty, {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'date';
+}>;
+/**
+ * Declares a meaningful event a functional block can emit (e.g. a form's
+ * `submitSuccess`). Living on the block DEFINITION makes it the single source of
+ * truth for the typed `fire(...)` union, the test-creation goal picker, and the
+ * analytics wire name. `name` overrides the GA4/dataLayer wire name (defaults to
+ * `cms_<blockType>_<eventKey>`, computed by the measurement layer). Whether an
+ * event counts as a conversion is decided per test in the UI, not here.
+ */
+type EventDeclaration = {
+    /** Analytics wire-name override (snake_case). Defaults to cms_<type>_<key>. */
+    name?: string;
+    /** Typed parameters carried with the event (scalar only). */
+    params?: Record<string, ScalarBlockProperty>;
+    /** Human label for the goal picker. */
+    label?: string;
+};
+type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TEvents extends Record<string, EventDeclaration> = Record<string, never>> = {
+    properties: TProps;
+    label: string;
+    description?: string;
+    previewImageUrl?: string;
+    /** Events this (functional) block can emit — see {@link EventDeclaration}. */
+    events?: TEvents;
+} & ({
+    allowChildren?: false;
+} | {
+    allowChildren: true;
+    allowedChildBlocks?: string[];
+});
+type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
+type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: TProps;
+};
+type SlugConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    root: string;
+    allowRoot?: boolean;
+    normalize?: boolean;
+    nested?: boolean;
+};
+type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition> = Record<string, AnyBlockDefinition>> = {
+    slug?: SlugConfig;
+    root: RootDefinition<TProps>;
+    blocks?: TBlocks;
+    label: string;
+    description?: string;
+    /**
+     * Marks this collection as one whose roots are meant to be EMBEDDED into other
+     * roots via a `reference` property (a "reusable block" library). Purely an
+     * ergonomic hint — it informs editor pickers and which endpoints to surface; it
+     * NEVER gates safety (the delete-in-use guard protects every referenced root
+     * regardless of this flag). Any collection can still be a reference target.
+     */
+    reusableBlock?: boolean;
+};
+type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
+type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {
+    name: string;
+    blocks: Record<string, AnyBlockDefinition>;
+};
+type DataRetentionConfig = {
+    keepDays: number;
+    keepMinCommits: number;
+    /**
+     * Grace period (days) before a soft-archived root (`archivedAt`) is physically
+     * hard-deleted by pruning. Defaults to `keepDays` when omitted — a trash
+     * window after which the page and its whole history are reclaimed.
+     */
+    archiveKeepDays?: number;
+};
+/** Result that user middleware can return to extend context */
+type MiddlewareResult = {
+    userId?: string;
+    [key: string]: unknown;
+};
+/** Base ctx injected by withCMSContext middleware. */
+type CMSProcedureCtx = {
+    db: DrizzleInstance;
+    collections: Record<string, CollectionWithName>;
+    dataRetention?: DataRetentionConfig;
+    scopeConditions?: ScopeConditionFactory[];
+    notificationService?: NotificationService;
+    resolvedUser?: ResolvedUserConfig;
+};
+
+type SchemaNamespace = 'cms';
+type ColumnScalarType = 'text' | 'boolean' | 'integer' | 'timestamp' | 'jsonb' | 'tsvector';
+type ColumnType<EnumTarget extends string = string> = ColumnScalarType | {
+    enum: EnumTarget;
+};
+type DefaultValue = {
+    kind: 'literal';
+    value: boolean | number | string | string[] | Record<string, unknown>;
+} | {
+    kind: 'sql';
+    value: string;
+};
+type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+type IndexUsing = 'btree' | 'gin';
+type ColumnDefinition<ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    type: ColumnType<EnumTarget>;
+    columnName?: string;
+    notNull?: boolean;
+    primaryKey?: boolean;
+    unique?: boolean;
+    default?: DefaultValue;
+    defaultId?: boolean;
+    defaultIdPrefix?: string;
+    defaultNow?: boolean;
+    jsonType?: string;
+    references?: {
+        table: ReferenceTarget;
+        column: string;
+        onDelete?: ForeignKeyAction;
+        onUpdate?: ForeignKeyAction;
+    };
+};
+type TableColumns<ReferenceTarget extends string = string, EnumTarget extends string = string> = Record<string, ColumnDefinition<ReferenceTarget, EnumTarget>>;
+type IndexDefinition<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+    unique?: boolean;
+    using?: IndexUsing;
+    where?: string;
+};
+type CompositePrimaryKey<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+};
+type TableLevelForeignKey<ColumnName extends string = string> = {
+    columns: readonly ColumnName[];
+    foreignTable: string;
+    foreignColumns: readonly string[];
+    name?: string;
+    onDelete?: ForeignKeyAction;
+    onUpdate?: ForeignKeyAction;
+};
+type TableDefinition<Columns extends TableColumns = TableColumns, ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    tableName?: string;
+    indexPrefix?: string;
+    columns: Columns;
+    indexes?: Record<string, IndexDefinition<Extract<keyof Columns, string>>>;
+    compositePrimaryKey?: CompositePrimaryKey<Extract<keyof Columns, string>>;
+    foreignKeys?: TableLevelForeignKey<Extract<keyof Columns, string>>[];
+};
+type EnumDefinition = {
+    values: readonly string[];
+    enumName?: string;
+};
+type EnumMap = Record<string, EnumDefinition>;
+type TableMap = Record<string, TableDefinition>;
+type SchemaModule<_Namespace extends SchemaNamespace = SchemaNamespace, Tables extends TableMap = {}, Enums extends EnumMap = {}, Extensions = {}> = {
+    enums?: Enums;
+    tables?: Tables;
+    extend?: Extensions;
+};
+
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Endpoint key used as a hook action identifier.
+ * Accepts any string so internal plumbing doesn't need the full union,
+ * but the exported `CMSEndpointKey` (from `index.ts`) provides a narrowed
+ * union with autocomplete for hook authors.
+ */
+type CMSHookAction = string & {};
+type CMSBeforeHookContext = {
+    action: CMSHookAction;
+    collection: string;
+    db: DrizzleInstance;
+    input: Record<string, unknown>;
+    /**
+     * The resolved per-request scope (tenant/i18n), available to before-hooks so
+     * they can tenant-scope any cross-resource reads they perform. Set by the
+     * endpoint wrapper before hooks run; may be undefined for hooks invoked
+     * outside that path.
+     */
+    scope?: ResolvedScope;
+};
+type CMSAfterHookContext = CMSBeforeHookContext & {
+    result: unknown;
+};
+type CMSBeforeHook = {
+    action: CMSHookAction | '*';
+    collection?: string;
+    handler: (ctx: CMSBeforeHookContext) => Promise<void | {
+        override?: Record<string, unknown>;
+    }>;
+};
+type CMSAfterHook = {
+    action: CMSHookAction | '*';
+    collection?: string;
+    handler: (ctx: CMSAfterHookContext) => Promise<void | {
+        response: unknown;
+    }>;
+};
+type CMSHooks = {
+    before?: CMSBeforeHook[];
+    after?: CMSAfterHook[];
+};
+type CMSPluginContext = CMSProcedureCtx & {
+    collections: Record<string, CollectionWithName>;
+};
+type CMSCoreRootPruningPlan = {
+    rootId: string;
+    deletableCommitIds: string[];
+    deletableBlockVersionIds: string[];
+    deletableSnapshotCount: number;
+    deletableMergeRequestIds: string[];
+    deletableApprovalIds: string[];
+    initialCommitId: string;
+};
+type CMSPluginPruningMetrics = Record<string, number>;
+type CMSPluginRootPruningPlan<TData = unknown> = {
+    rootId: string;
+    data?: TData;
+    metrics?: CMSPluginPruningMetrics;
+};
+type CMSPluginPruningPlanContext = Omit<CMSPluginContext, 'dataRetention'> & {
+    db: DrizzleInstance;
+    dataRetention: DataRetentionConfig;
+    rootPlan: CMSCoreRootPruningPlan;
+};
+type CMSPluginPruningExecuteContext<TData = unknown> = Omit<CMSPluginContext, 'db' | 'dataRetention'> & {
+    tx: DrizzleInstance;
+    dataRetention: DataRetentionConfig;
+    rootPlan: CMSCoreRootPruningPlan;
+    pluginPlan: CMSPluginRootPruningPlan<TData>;
+};
+type CMSPluginPruningExecuteResult = {
+    metrics?: CMSPluginPruningMetrics;
+};
+type CMSPluginPruning<TData = unknown> = {
+    plan: (ctx: CMSPluginPruningPlanContext) => Promise<CMSPluginRootPruningPlan<TData> | null>;
+    execute?: (ctx: CMSPluginPruningExecuteContext<TData>) => Promise<CMSPluginPruningExecuteResult | void>;
+};
+type CMSPluginInitOptions = {
+    hooks?: CMSHooks;
+};
+type CMSPluginInitResult = {
+    context?: Record<string, unknown>;
+    options?: Partial<CMSPluginInitOptions>;
+};
+/**
+ * A CMS plugin can extend the system with custom endpoints, hooks,
+ * middleware, database tables, and data-retention pruning logic.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: CMSPlugin = {
+ *   id: 'my-plugin',
+ *   endpoints: { ... },
+ *   hooks: { before: [...], after: [...] },
+ *   async init(ctx) { return { context: { myService } }; },
+ * };
+ * ```
+ */
+type CMSPlugin<TPruningData = unknown> = {
+    id: string;
+    endpoints?: Record<string, Endpoint>;
+    /**
+     * Per-COLLECTION endpoints contributed by the plugin: called once per
+     * collection during API assembly, returning routes merged into THAT
+     * collection's endpoint record (so they surface at `cms.api.<collection>.x`,
+     * not the flat `cms.api.<pluginId>.x`). The per-collection analogue of the
+     * flat `endpoints` above. Generic — any plugin can attach a route to every
+     * collection (the i18n plugin uses it for createTranslation / listTranslations).
+     * (Seam A.)
+     */
+    collectionEndpoints?: (def: CollectionWithName, ctx: CMSPluginContext) => Record<string, Endpoint>;
+    hooks?: {
+        before?: CMSBeforeHook[];
+        after?: CMSAfterHook[];
+    };
+    middlewares?: {
+        path: string;
+        middleware: Middleware;
+    }[];
+    schema?: SchemaModule;
+    pruning?: CMSPluginPruning<TPruningData>;
+    init?: (ctx: CMSPluginContext) => Awaitable<CMSPluginInitResult | void>;
+    onRequest?: (request: Request, ctx: CMSPluginContext) => Promise<{
+        response: Response;
+    } | {
+        request: Request;
+    } | void>;
+    onResponse?: (response: Response, ctx: CMSPluginContext) => Promise<{
+        response: Response;
+    } | void>;
+    onNotification?: OnNotificationHandler;
+    $ERROR_CODES?: Record<string, {
+        status: number;
+        message: string;
+    }>;
+};
+
+type CMSFetch = (path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: unknown;
+    /**
+     * Forwarded to the underlying `fetch` (better-call → @better-fetch → native
+     * `fetch`). Set for fire-and-forget analytics beacons (the A/B event ingest)
+     * so the POST is NOT cancelled when the page unloads/navigates mid-request.
+     */
+    keepalive?: boolean;
+}) => Promise<unknown>;
+type CMSAtomListener = {
+    matcher: (path: string) => boolean;
+    signal: string;
+    callback?: (path: string) => void;
+};
+interface CMSClientStore {
+    notify: (signal: string) => void;
+    listen: (signal: string, listener: () => void) => void;
+    atoms: Record<string, WritableAtom<unknown>>;
+}
+interface CMSClientPlugin {
+    id: string;
+    $InferServerPlugin?: CMSPlugin;
+    init?: ($fetch: CMSFetch, $store: CMSClientStore) => Promise<{
+        context?: Record<string, unknown>;
+    } | void>;
+    getActions?: ($fetch: CMSFetch, $store: CMSClientStore, baseURL: string) => Record<string, unknown>;
+    pathMethods?: Record<string, 'GET' | 'POST'>;
+    atomListeners?: CMSAtomListener[];
+    $ERROR_CODES?: Record<string, {
+        status: number;
+        message: string;
+    }>;
+}
+type MediaUploadFileState = {
+    name: string;
+    progress: number;
+    status: 'pending' | 'uploading' | 'done' | 'error';
+    error?: string;
+    optimized?: boolean;
+    originalVariantId?: string;
+    result?: {
+        id: string;
+        slug: string;
+        objectKey: string;
+    };
+};
+type MediaUploadOptions = {
+    folderId?: string;
+};
+type MediaUploadState = {
+    isUploading: boolean;
+    isAborted: boolean;
+    files: MediaUploadFileState[];
+    totalProgress: number;
+    error: unknown;
+    upload: (files: File[], options?: MediaUploadOptions) => Promise<void>;
+    abort: () => void;
+    reset: () => void;
+};
+type QueryState<T = unknown> = {
+    data: T | null;
+    error: unknown;
+    isPending: boolean;
+    isRefetching: boolean;
+    refetch: () => Promise<void>;
+};
+interface CMSClientOptions {
+    baseURL: string;
+    plugins?: CMSClientPlugin[];
+}
+type InferApi<T> = T extends {
+    api: infer A;
+} ? A : {};
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type InferPluginActions<P extends CMSClientPlugin[]> = UnionToIntersection<{
+    [K in keyof P]: P[K] extends CMSClientPlugin ? ReturnType<NonNullable<P[K]['getActions']>> extends infer A ? A extends Record<string, unknown> ? A : {} : {} : {};
+}[number]>;
+type InferClientPluginErrorCodes<P extends CMSClientPlugin[]> = UnionToIntersection<P[number] extends infer Plug ? Plug extends CMSClientPlugin ? Plug['$ERROR_CODES'] extends Record<string, any> ? Plug['$ERROR_CODES'] : {} : {} : {}>;
+type WithMedia<T> = T extends {
+    media: infer M;
+} ? Omit<T, 'media'> & {
+    media: M & {
+        useUploadAssets: () => MediaUploadState;
+    };
+} : T & {
+    media: {
+        useUploadAssets: () => MediaUploadState;
+    };
+};
+type CMSClientInstance<TCMS = unknown, TPlugins extends CMSClientPlugin[] = CMSClientPlugin[]> = WithMedia<InferApi<TCMS>> & InferPluginActions<TPlugins> & {
+    $fetch: CMSFetch;
+    $store: CMSClientStore;
+    $ERROR_CODES: InferClientPluginErrorCodes<TPlugins>;
+};
+
+/**
+ * React hook that subscribes to a nanostores atom via `useSyncExternalStore`.
+ * Re-renders the component when the atom value changes.
+ */
+declare function useStore<T>(store: ReadableAtom<T>): T;
+
+/**
+ * Creates a type-safe React CMS client with plugin support.
+ *
+ * Plugin `init` functions run asynchronously on creation. The returned
+ * client is usable immediately — API calls will await init completion
+ * transparently.
+ *
+ * Atom hooks are wrapped in `useStore()` so they work as React hooks:
+ *
+ * ```tsx
+ * import { createCMSClient } from '@createcms/core/react';
+ *
+ * // Preferred: curried call preserves full plugin type inference
+ * const client = createCMSClient<typeof cms>()({
+ *   baseURL: '/api/cms',
+ *   plugins: [mediaOptimizeClient()],
+ * });
+ *
+ * // Also works: single call (plugin types inferred only when TCMS is omitted)
+ * const client2 = createCMSClient({
+ *   baseURL: '/api/cms',
+ *   plugins: [mediaOptimizeClient()],
+ * });
+ *
+ * function MyComponent() {
+ *   const { data, isPending } = client.useMediaLibrary();
+ * }
+ * ```
+ */
+declare function createCMSClient<TCMS = unknown>(options: CMSClientOptions & {
+    plugins?: CMSClientPlugin[];
+}): CMSClientInstance<TCMS, CMSClientPlugin[]>;
+declare function createCMSClient<TCMS = unknown>(): <const TPlugins extends CMSClientPlugin[] = CMSClientPlugin[]>(options: CMSClientOptions & {
+    plugins?: TPlugins;
+}) => CMSClientInstance<TCMS, TPlugins>;
+
+interface CMSQueryOptions {
+    method?: string;
+    query?: Record<string, unknown>;
+}
+/**
+ * Creates a reactive query atom that fetches data from a CMS endpoint.
+ * Subscribes to one or more signal atoms and refetches when they toggle.
+ *
+ * Returns a nanostores `WritableAtom` — framework-agnostic, not a React hook.
+ */
+declare function createCMSQuery<T = unknown>(signals: WritableAtom<boolean> | WritableAtom<boolean>[], path: string, $fetch: CMSFetch, options?: CMSQueryOptions | (() => CMSQueryOptions)): WritableAtom<QueryState<T>>;
+
+declare const CMS_ERRORS: {
+    readonly BRANCH_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Branch not found";
+    };
+    readonly BLOCK_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Block not found in snapshot";
+    };
+    readonly PARENT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Parent block not found";
+    };
+    readonly ROOT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Root block not found in snapshot";
+    };
+    readonly ROOT_HAS_CHILDREN: {
+        readonly status: 400;
+        readonly message: "Cannot delete a page that has child pages; archive or move the children first";
+    };
+    readonly ROOT_IN_USE: {
+        readonly status: 409;
+        readonly message: "Cannot delete: this root is embedded as a reusable block on live pages; remove those references first";
+    };
+    readonly COMMIT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Commit not found";
+    };
+    readonly FOLDER_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Folder not found";
+    };
+    readonly FOLDER_HAS_CONTENT: {
+        readonly status: 400;
+        readonly message: "Cannot delete folder that contains assets or subfolders";
+    };
+    readonly EMPTY_SNAPSHOT: {
+        readonly status: 400;
+        readonly message: "Empty snapshot — no versions found";
+    };
+    readonly BLOCK_ALREADY_DELETED: {
+        readonly status: 400;
+        readonly message: "Block is already deleted";
+    };
+    readonly TYPE_MISMATCH: {
+        readonly status: 400;
+        readonly message: "Block type does not match the expected type";
+    };
+    readonly USER_ID_REQUIRED: {
+        readonly status: 400;
+        readonly message: "userId is required for this route when neither the request nor middleware provides one";
+    };
+    readonly CANNOT_MOVE_ROOT: {
+        readonly status: 400;
+        readonly message: "Cannot move the root block";
+    };
+    readonly CANNOT_MOVE_INTO_SELF: {
+        readonly status: 400;
+        readonly message: "Cannot move an item into itself";
+    };
+    readonly CANNOT_MOVE_INTO_DESCENDANT: {
+        readonly status: 400;
+        readonly message: "Cannot move an item into its own descendant";
+    };
+    readonly MISSING_TARGET_PROPERTIES: {
+        readonly status: 400;
+        readonly message: "targetProperties is required when duplicating a root";
+    };
+    readonly BRANCH_NAME_ALREADY_EXISTS: {
+        readonly status: 400;
+        readonly message: "A branch with this name already exists for this root";
+    };
+    readonly CANNOT_RENAME_MAIN_BRANCH: {
+        readonly status: 400;
+        readonly message: "The main branch cannot be renamed";
+    };
+    readonly CANNOT_DELETE_MAIN_BRANCH: {
+        readonly status: 400;
+        readonly message: "The main branch cannot be deleted";
+    };
+    readonly BRANCH_HAS_PUBLICATIONS: {
+        readonly status: 400;
+        readonly message: "Cannot delete a branch that has active publications";
+    };
+    readonly BRANCH_HAS_OPEN_MERGE_REQUESTS: {
+        readonly status: 400;
+        readonly message: "Cannot delete a branch that is part of open merge requests";
+    };
+    readonly NO_COMMON_ANCESTOR: {
+        readonly status: 400;
+        readonly message: "The two branches share no common ancestor";
+    };
+    readonly MERGE_REQUEST_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Merge request not found";
+    };
+    readonly MERGE_REQUEST_NOT_OPEN: {
+        readonly status: 400;
+        readonly message: "Merge request is not open";
+    };
+    readonly MERGE_REQUEST_NOT_CLOSED: {
+        readonly status: 400;
+        readonly message: "Merge request is not closed";
+    };
+    readonly MERGE_REQUEST_ALREADY_MERGED: {
+        readonly status: 400;
+        readonly message: "Merge request has already been merged and cannot be reopened";
+    };
+    readonly MERGE_REQUEST_ALREADY_EXISTS: {
+        readonly status: 400;
+        readonly message: "An open merge request already exists for this source and target branch";
+    };
+    readonly MERGE_REQUEST_OUTDATED: {
+        readonly status: 400;
+        readonly message: "Merge request is outdated because the source branch changed after it was opened";
+    };
+    readonly UNRESOLVED_CONFLICTS: {
+        readonly status: 400;
+        readonly message: "Cannot merge: there are unresolved conflicts";
+    };
+    readonly CONFLICT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Merge conflict not found";
+    };
+    readonly RESOLVED_VERSION_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "The provided resolvedVersionId does not reference an existing block version";
+    };
+    readonly APPROVAL_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Approval not found";
+    };
+    readonly APPROVAL_ALREADY_REQUESTED: {
+        readonly status: 400;
+        readonly message: "An approval has already been requested from this reviewer";
+    };
+    readonly APPROVAL_NOT_PENDING: {
+        readonly status: 400;
+        readonly message: "Approval is not pending";
+    };
+    readonly APPROVAL_REVIEWER_MISMATCH: {
+        readonly status: 403;
+        readonly message: "Only the requested reviewer can approve or reject this request";
+    };
+    readonly APPROVAL_STALE: {
+        readonly status: 400;
+        readonly message: "Approval is stale: the branch has advanced past the approved commit";
+    };
+    readonly MERGE_APPROVAL_REQUIRED: {
+        readonly status: 400;
+        readonly message: "Cannot merge: approval is required before execution";
+    };
+    readonly PUBLICATION_APPROVAL_REQUIRED: {
+        readonly status: 400;
+        readonly message: "Cannot publish: approval is required before publication";
+    };
+    readonly APPROVALS_NOT_FULLY_APPROVED: {
+        readonly status: 400;
+        readonly message: "Cannot proceed: not all requested approvals are approved";
+    };
+    readonly BRANCHES_NOT_SAME_ROOT: {
+        readonly status: 400;
+        readonly message: "Source and target branches must belong to the same root";
+    };
+    readonly PUBLICATION_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Publication not found for this branch";
+    };
+    readonly PUBLISHED_CONTENT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "No published content found";
+    };
+    readonly AMBIGUOUS_SLUG: {
+        readonly status: 400;
+        readonly message: "Multiple roots match this slug — use rootId for an unambiguous lookup";
+    };
+    readonly DATA_RETENTION_NOT_CONFIGURED: {
+        readonly status: 400;
+        readonly message: "dataRetention is not configured for this CMS instance";
+    };
+    readonly MISSING_REQUIRED_S3_PARAMETERS: {
+        readonly status: 400;
+        readonly message: "Missing required S3 parameters: hostname, accessKeyId, or secretAccessKey";
+    };
+    readonly UNKNOWN_S3_PROVIDER: {
+        readonly status: 400;
+        readonly message: "Unknown S3 provider specified";
+    };
+    readonly SLUG_GENERATION_FAILED: {
+        readonly status: 500;
+        readonly message: "Failed to generate a unique slug after maximum attempts";
+    };
+    readonly TOO_MANY_FILES: {
+        readonly status: 400;
+        readonly message: "Too many files in upload batch";
+    };
+    readonly FILE_TOO_LARGE: {
+        readonly status: 400;
+        readonly message: "One or more files exceed the maximum allowed size";
+    };
+    readonly INVALID_FILE_TYPE: {
+        readonly status: 400;
+        readonly message: "One or more files have a disallowed MIME type";
+    };
+    readonly UPLOAD_FAILED: {
+        readonly status: 500;
+        readonly message: "Server-side upload to S3 failed";
+    };
+    readonly SLUG_ALREADY_EXISTS: {
+        readonly status: 409;
+        readonly message: "A root with this slug on this collection with this parentRootId already exists";
+    };
+    readonly SLUG_NOT_ENABLED: {
+        readonly status: 400;
+        readonly message: "This collection does not have slugs enabled";
+    };
+    readonly REDIRECT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Redirect not found";
+    };
+    readonly REDIRECT_INVALID: {
+        readonly status: 400;
+        readonly message: "A redirect endpoint must be a page (rootId) or a path, matching its type";
+    };
+    readonly REDIRECT_SOURCE_EXISTS: {
+        readonly status: 409;
+        readonly message: "An active redirect already exists for this source";
+    };
+    readonly SLUG_EMPTY_NOT_ALLOWED: {
+        readonly status: 400;
+        readonly message: "Empty slug is not allowed for this collection (allowRoot is false)";
+    };
+    readonly NESTING_NOT_ENABLED: {
+        readonly status: 400;
+        readonly message: "parentRootId is not allowed — this collection does not have nested pages enabled";
+    };
+    readonly CIRCULAR_REFERENCE: {
+        readonly status: 400;
+        readonly message: "Cannot move a page under itself or one of its descendants";
+    };
+    readonly PARENT_ROOT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Parent root not found in this collection";
+    };
+    readonly REFERENCE_DEPTH_EXCEEDED: {
+        readonly status: 422;
+        readonly message: "Reference nesting is too deep (a reusable block embeds others past the limit)";
+    };
+    readonly ASSET_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Asset not found";
+    };
+    readonly VARIABLE_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Variable not found";
+    };
+    readonly VARIABLE_KEY_EXISTS: {
+        readonly status: 409;
+        readonly message: "A variable with this key already exists";
+    };
+    readonly VARIABLE_IN_USE: {
+        readonly status: 409;
+        readonly message: "Cannot delete variable: it is still in use";
+    };
+    readonly TEMPLATE_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Template not found";
+    };
+    readonly TEMPLATE_KEY_EXISTS: {
+        readonly status: 409;
+        readonly message: "A template for this collection/block/property combination already exists";
+    };
+    readonly ASSET_ACCESS_DENIED: {
+        readonly status: 403;
+        readonly message: "This asset is private and requires authentication";
+    };
+    readonly COMMENT_THREAD_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Comment thread not found";
+    };
+    readonly COMMENT_THREAD_ALREADY_RESOLVED: {
+        readonly status: 400;
+        readonly message: "Comment thread is already resolved";
+    };
+    readonly COMMENT_THREAD_NOT_RESOLVED: {
+        readonly status: 400;
+        readonly message: "Comment thread is not resolved";
+    };
+    readonly COMMENT_MESSAGE_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Comment message not found";
+    };
+    readonly COMMENT_MESSAGE_DELETED: {
+        readonly status: 400;
+        readonly message: "Comment message has been deleted";
+    };
+    readonly COMMENT_BODY_REQUIRED: {
+        readonly status: 400;
+        readonly message: "Body is required for comment messages";
+    };
+    readonly COMMENT_AUTHOR_MISMATCH: {
+        readonly status: 403;
+        readonly message: "Only the author can edit or delete this message";
+    };
+    readonly NOTIFICATION_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Notification not found";
+    };
+    readonly NOTIFICATION_RECIPIENT_MISMATCH: {
+        readonly status: 403;
+        readonly message: "You can only access your own notifications";
+    };
+};
+type CMSErrorCode = keyof typeof CMS_ERRORS;
+
+/**
+ * Client-side CMS error thrown by `$fetch` when the server returns an error
+ * response. Unlike the server-side `CMSError` (which extends better-call's
+ * `APIError`), this is a plain `Error` subclass that works in the browser.
+ */
+declare class CMSClientError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly code: string | undefined;
+    constructor(errorBody: {
+        message?: string;
+        code?: string;
+        status?: number;
+        statusText?: string;
+    });
+    get cmsCode(): CMSErrorCode | undefined;
+}
+
+export { CMSClientError, createCMSClient, createCMSQuery, useStore };
+export type { CMSAtomListener, CMSClientInstance, CMSClientOptions, CMSClientPlugin, CMSClientStore, CMSFetch, EventDeclaration, QueryState };