@createcms/core 0.1.1

package/dist/react/index.js

@@ -0,0 +1,872 @@
+import { createClient } from 'better-call/client';
+import { atom, onMount } from 'nanostores';
+import 'better-call';
+import { useRef, useCallback, useSyncExternalStore } from 'react';
+export { BlocksRenderer, createBlocksMap, createBlocksRenderer, createContentRenderer, extractBlockEvents } from './blocks.js';
+export { pickVariant } from './variant.js';
+
+/**
+ * Wire contract for the `withUser` / `withRoot` query flags, shared by the HTTP
+ * client (encode side, `client/proxy.ts`) and the server endpoint wrapper
+ * (decode side, `core/endpoint.ts`) so the two halves can never drift.
+ *
+ * Two transports carry these flags and both must round-trip:
+ *  - **HTTP** — the proxy encodes values as strings (objects → JSON, booleans →
+ *    `String()`); the endpoint decodes the strings back.
+ *  - **In-process** (`cms.api.*`) — callers pass raw values (objects / real
+ *    booleans) straight through, bypassing the proxy, so decode must accept the
+ *    untransformed forms as well.
+ *
+ * This module is intentionally dependency-free (no drizzle, no better-call) so
+ * importing it from the client bundle stays cheap.
+ */ const WITH_USER_KEY = 'withUser';
+const WITH_ROOT_KEY = 'withRoot';
+/**
+ * Encode the flag query for HTTP transport. Pure and copy-on-write: never
+ * mutates its input, and returns the *same* reference when nothing needed
+ * encoding (so an absent query stays absent, preserving GET-without-query).
+ */ function encodeFlagQuery(query) {
+    if (!query) return query;
+    let out = query;
+    const rawWithUser = query[WITH_USER_KEY];
+    if (rawWithUser && typeof rawWithUser === 'object') {
+        out = {
+            ...out,
+            [WITH_USER_KEY]: JSON.stringify(rawWithUser)
+        };
+    }
+    const rawWithRoot = query[WITH_ROOT_KEY];
+    if (rawWithRoot !== undefined) {
+        out = {
+            ...out,
+            [WITH_ROOT_KEY]: String(rawWithRoot)
+        };
+    }
+    return out;
+}
+
+/**
+ * Creates a Proxy-based client that maps property access to API calls.
+ *
+ * - `client.pages.listRoots()` -> `$fetch("/pages/listRoots", ...)`
+ * - Direct properties on `routes` (plugin actions, atom hooks, $fetch, $store)
+ *   are returned as-is.
+ * - On successful API calls, matching `atomListeners` are triggered to
+ *   invalidate dependent query atoms.
+ */ function createDynamicPathProxy(routes, $fetch, pathMethods, atoms, atomListeners) {
+    return new Proxy(routes, {
+        get (target, prop) {
+            if (prop in target) {
+                const value = target[prop];
+                if (typeof value === 'object' && value !== null) {
+                    return createNamespaceProxy(prop, value, $fetch, pathMethods, atoms, atomListeners);
+                }
+                return value;
+            }
+            return createNamespaceProxy(prop, {}, $fetch, pathMethods, atoms, atomListeners);
+        }
+    });
+}
+function createNamespaceProxy(namespace, routes, $fetch, pathMethods, atoms, atomListeners) {
+    return new Proxy(routes, {
+        get (target, method) {
+            if (method in target) return target[method];
+            return (opts)=>{
+                const routePath = `/${namespace}/${method}`;
+                const httpMethod = pathMethods[routePath] ?? (opts?.body !== undefined ? 'POST' : 'GET');
+                const query = encodeFlagQuery(opts?.query);
+                return $fetch(routePath, {
+                    method: httpMethod,
+                    ...opts,
+                    ...query ? {
+                        query
+                    } : {}
+                }).then((data)=>{
+                    triggerListeners(routePath, atoms, atomListeners);
+                    return data;
+                });
+            };
+        }
+    });
+}
+function triggerListeners(routePath, atoms, atomListeners) {
+    const matches = atomListeners.filter((l)=>l.matcher(routePath));
+    if (!matches.length) return;
+    const visited = new Set();
+    for (const match of matches){
+        const signal = atoms[match.signal];
+        if (!signal || visited.has(match.signal)) continue;
+        visited.add(match.signal);
+        // Defer to a microtask so the toggle runs after the current call settles,
+        // and read the CURRENT value at set-time (not a value captured earlier) so
+        // rapid successive mutations can't cancel each other out and drop an
+        // invalidation.
+        setTimeout(()=>{
+            const current = signal.get();
+            signal.set(typeof current === 'boolean' ? !current : current);
+        }, 0);
+        match.callback?.(routePath);
+    }
+}
+
+/**
+ * Shared client assembly for both the vanilla and React entrypoints. The only
+ * thing that differs between them is how `media.useUploadAssets` is exposed:
+ *  - vanilla passes the raw `uploadAssets` nanostores atom (consumers call
+ *    `.get()` / `.subscribe()` themselves);
+ *  - React passes a `() => useStore(uploadAssets)` hook thunk.
+ *
+ * That value is constructed by the caller and handed in as `unknown` so this
+ * module never imports React — keeping it out of the vanilla bundle. The
+ * `as CMSClientInstance` cast (present in both original builders) is the single
+ * intentional escape hatch that normalizes the loosely-typed routes object to
+ * the inferred public client type (`WithMedia` mandates
+ * `useUploadAssets: () => MediaUploadState`).
+ */ function buildClient(config, useUploadAssets) {
+    const { $fetch, $store, pluginsActions, pluginsAtoms, pluginPathMethods, atomListeners, $ERROR_CODES } = config;
+    return createDynamicPathProxy({
+        media: {
+            useUploadAssets
+        },
+        ...pluginsActions,
+        $fetch,
+        $store,
+        $ERROR_CODES
+    }, $fetch, pluginPathMethods, pluginsAtoms, atomListeners);
+}
+
+const CMS_ERRORS = {
+    BRANCH_NOT_FOUND: {
+        status: 404,
+        message: 'Branch not found'
+    },
+    BLOCK_NOT_FOUND: {
+        status: 404,
+        message: 'Block not found in snapshot'
+    },
+    PARENT_NOT_FOUND: {
+        status: 404,
+        message: 'Parent block not found'
+    },
+    ROOT_NOT_FOUND: {
+        status: 404,
+        message: 'Root block not found in snapshot'
+    },
+    ROOT_HAS_CHILDREN: {
+        status: 400,
+        message: 'Cannot delete a page that has child pages; archive or move the children first'
+    },
+    ROOT_IN_USE: {
+        status: 409,
+        message: 'Cannot delete: this root is embedded as a reusable block on live pages; remove those references first'
+    },
+    COMMIT_NOT_FOUND: {
+        status: 404,
+        message: 'Commit not found'
+    },
+    FOLDER_NOT_FOUND: {
+        status: 404,
+        message: 'Folder not found'
+    },
+    FOLDER_HAS_CONTENT: {
+        status: 400,
+        message: 'Cannot delete folder that contains assets or subfolders'
+    },
+    EMPTY_SNAPSHOT: {
+        status: 400,
+        message: 'Empty snapshot — no versions found'
+    },
+    BLOCK_ALREADY_DELETED: {
+        status: 400,
+        message: 'Block is already deleted'
+    },
+    TYPE_MISMATCH: {
+        status: 400,
+        message: 'Block type does not match the expected type'
+    },
+    USER_ID_REQUIRED: {
+        status: 400,
+        message: 'userId is required for this route when neither the request nor middleware provides one'
+    },
+    CANNOT_MOVE_ROOT: {
+        status: 400,
+        message: 'Cannot move the root block'
+    },
+    CANNOT_MOVE_INTO_SELF: {
+        status: 400,
+        message: 'Cannot move an item into itself'
+    },
+    CANNOT_MOVE_INTO_DESCENDANT: {
+        status: 400,
+        message: 'Cannot move an item into its own descendant'
+    },
+    MISSING_TARGET_PROPERTIES: {
+        status: 400,
+        message: 'targetProperties is required when duplicating a root'
+    },
+    BRANCH_NAME_ALREADY_EXISTS: {
+        status: 400,
+        message: 'A branch with this name already exists for this root'
+    },
+    CANNOT_RENAME_MAIN_BRANCH: {
+        status: 400,
+        message: 'The main branch cannot be renamed'
+    },
+    CANNOT_DELETE_MAIN_BRANCH: {
+        status: 400,
+        message: 'The main branch cannot be deleted'
+    },
+    BRANCH_HAS_PUBLICATIONS: {
+        status: 400,
+        message: 'Cannot delete a branch that has active publications'
+    },
+    BRANCH_HAS_OPEN_MERGE_REQUESTS: {
+        status: 400,
+        message: 'Cannot delete a branch that is part of open merge requests'
+    },
+    NO_COMMON_ANCESTOR: {
+        status: 400,
+        message: 'The two branches share no common ancestor'
+    },
+    MERGE_REQUEST_NOT_FOUND: {
+        status: 404,
+        message: 'Merge request not found'
+    },
+    MERGE_REQUEST_NOT_OPEN: {
+        status: 400,
+        message: 'Merge request is not open'
+    },
+    MERGE_REQUEST_NOT_CLOSED: {
+        status: 400,
+        message: 'Merge request is not closed'
+    },
+    MERGE_REQUEST_ALREADY_MERGED: {
+        status: 400,
+        message: 'Merge request has already been merged and cannot be reopened'
+    },
+    MERGE_REQUEST_ALREADY_EXISTS: {
+        status: 400,
+        message: 'An open merge request already exists for this source and target branch'
+    },
+    MERGE_REQUEST_OUTDATED: {
+        status: 400,
+        message: 'Merge request is outdated because the source branch changed after it was opened'
+    },
+    UNRESOLVED_CONFLICTS: {
+        status: 400,
+        message: 'Cannot merge: there are unresolved conflicts'
+    },
+    CONFLICT_NOT_FOUND: {
+        status: 404,
+        message: 'Merge conflict not found'
+    },
+    RESOLVED_VERSION_NOT_FOUND: {
+        status: 404,
+        message: 'The provided resolvedVersionId does not reference an existing block version'
+    },
+    APPROVAL_NOT_FOUND: {
+        status: 404,
+        message: 'Approval not found'
+    },
+    APPROVAL_ALREADY_REQUESTED: {
+        status: 400,
+        message: 'An approval has already been requested from this reviewer'
+    },
+    APPROVAL_NOT_PENDING: {
+        status: 400,
+        message: 'Approval is not pending'
+    },
+    APPROVAL_REVIEWER_MISMATCH: {
+        status: 403,
+        message: 'Only the requested reviewer can approve or reject this request'
+    },
+    APPROVAL_STALE: {
+        status: 400,
+        message: 'Approval is stale: the branch has advanced past the approved commit'
+    },
+    MERGE_APPROVAL_REQUIRED: {
+        status: 400,
+        message: 'Cannot merge: approval is required before execution'
+    },
+    PUBLICATION_APPROVAL_REQUIRED: {
+        status: 400,
+        message: 'Cannot publish: approval is required before publication'
+    },
+    APPROVALS_NOT_FULLY_APPROVED: {
+        status: 400,
+        message: 'Cannot proceed: not all requested approvals are approved'
+    },
+    BRANCHES_NOT_SAME_ROOT: {
+        status: 400,
+        message: 'Source and target branches must belong to the same root'
+    },
+    PUBLICATION_NOT_FOUND: {
+        status: 404,
+        message: 'Publication not found for this branch'
+    },
+    PUBLISHED_CONTENT_NOT_FOUND: {
+        status: 404,
+        message: 'No published content found'
+    },
+    AMBIGUOUS_SLUG: {
+        status: 400,
+        message: 'Multiple roots match this slug — use rootId for an unambiguous lookup'
+    },
+    DATA_RETENTION_NOT_CONFIGURED: {
+        status: 400,
+        message: 'dataRetention is not configured for this CMS instance'
+    },
+    MISSING_REQUIRED_S3_PARAMETERS: {
+        status: 400,
+        message: 'Missing required S3 parameters: hostname, accessKeyId, or secretAccessKey'
+    },
+    UNKNOWN_S3_PROVIDER: {
+        status: 400,
+        message: 'Unknown S3 provider specified'
+    },
+    SLUG_GENERATION_FAILED: {
+        status: 500,
+        message: 'Failed to generate a unique slug after maximum attempts'
+    },
+    TOO_MANY_FILES: {
+        status: 400,
+        message: 'Too many files in upload batch'
+    },
+    FILE_TOO_LARGE: {
+        status: 400,
+        message: 'One or more files exceed the maximum allowed size'
+    },
+    INVALID_FILE_TYPE: {
+        status: 400,
+        message: 'One or more files have a disallowed MIME type'
+    },
+    UPLOAD_FAILED: {
+        status: 500,
+        message: 'Server-side upload to S3 failed'
+    },
+    SLUG_ALREADY_EXISTS: {
+        status: 409,
+        message: 'A root with this slug on this collection with this parentRootId already exists'
+    },
+    SLUG_NOT_ENABLED: {
+        status: 400,
+        message: 'This collection does not have slugs enabled'
+    },
+    REDIRECT_NOT_FOUND: {
+        status: 404,
+        message: 'Redirect not found'
+    },
+    REDIRECT_INVALID: {
+        status: 400,
+        message: 'A redirect endpoint must be a page (rootId) or a path, matching its type'
+    },
+    REDIRECT_SOURCE_EXISTS: {
+        status: 409,
+        message: 'An active redirect already exists for this source'
+    },
+    SLUG_EMPTY_NOT_ALLOWED: {
+        status: 400,
+        message: 'Empty slug is not allowed for this collection (allowRoot is false)'
+    },
+    NESTING_NOT_ENABLED: {
+        status: 400,
+        message: 'parentRootId is not allowed — this collection does not have nested pages enabled'
+    },
+    CIRCULAR_REFERENCE: {
+        status: 400,
+        message: 'Cannot move a page under itself or one of its descendants'
+    },
+    PARENT_ROOT_NOT_FOUND: {
+        status: 404,
+        message: 'Parent root not found in this collection'
+    },
+    REFERENCE_DEPTH_EXCEEDED: {
+        status: 422,
+        message: 'Reference nesting is too deep (a reusable block embeds others past the limit)'
+    },
+    ASSET_NOT_FOUND: {
+        status: 404,
+        message: 'Asset not found'
+    },
+    VARIABLE_NOT_FOUND: {
+        status: 404,
+        message: 'Variable not found'
+    },
+    VARIABLE_KEY_EXISTS: {
+        status: 409,
+        message: 'A variable with this key already exists'
+    },
+    VARIABLE_IN_USE: {
+        status: 409,
+        message: 'Cannot delete variable: it is still in use'
+    },
+    TEMPLATE_NOT_FOUND: {
+        status: 404,
+        message: 'Template not found'
+    },
+    TEMPLATE_KEY_EXISTS: {
+        status: 409,
+        message: 'A template for this collection/block/property combination already exists'
+    },
+    ASSET_ACCESS_DENIED: {
+        status: 403,
+        message: 'This asset is private and requires authentication'
+    },
+    COMMENT_THREAD_NOT_FOUND: {
+        status: 404,
+        message: 'Comment thread not found'
+    },
+    COMMENT_THREAD_ALREADY_RESOLVED: {
+        status: 400,
+        message: 'Comment thread is already resolved'
+    },
+    COMMENT_THREAD_NOT_RESOLVED: {
+        status: 400,
+        message: 'Comment thread is not resolved'
+    },
+    COMMENT_MESSAGE_NOT_FOUND: {
+        status: 404,
+        message: 'Comment message not found'
+    },
+    COMMENT_MESSAGE_DELETED: {
+        status: 400,
+        message: 'Comment message has been deleted'
+    },
+    COMMENT_BODY_REQUIRED: {
+        status: 400,
+        message: 'Body is required for comment messages'
+    },
+    COMMENT_AUTHOR_MISMATCH: {
+        status: 403,
+        message: 'Only the author can edit or delete this message'
+    },
+    NOTIFICATION_NOT_FOUND: {
+        status: 404,
+        message: 'Notification not found'
+    },
+    NOTIFICATION_RECIPIENT_MISMATCH: {
+        status: 403,
+        message: 'You can only access your own notifications'
+    }
+};
+
+/**
+ * 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.
+ */ class CMSClientError extends Error {
+    constructor(errorBody){
+        super(errorBody.message ?? errorBody.statusText ?? 'Unknown CMS error');
+        this.name = 'CMSClientError';
+        this.status = errorBody.status ?? 500;
+        this.statusText = errorBody.statusText ?? '';
+        this.code = errorBody.code;
+    }
+    get cmsCode() {
+        if (this.code && this.code in CMS_ERRORS) {
+            return this.code;
+        }
+        return undefined;
+    }
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+const FORBIDDEN_XHR_HEADERS = new Set([
+    'content-length',
+    'host',
+    'connection',
+    'user-agent',
+    'referer',
+    'origin'
+]);
+// ============================================================================
+// XHR Upload
+// ============================================================================
+function uploadWithXHR(url, file, headers, onProgress, signal) {
+    return new Promise((resolve, reject)=>{
+        if (signal?.aborted) {
+            reject(new DOMException('Upload aborted', 'AbortError'));
+            return;
+        }
+        const xhr = new XMLHttpRequest();
+        xhr.open('PUT', url, true);
+        for (const [key, value] of Object.entries(headers)){
+            if (!FORBIDDEN_XHR_HEADERS.has(key.toLowerCase())) {
+                xhr.setRequestHeader(key, value);
+            }
+        }
+        if (signal) {
+            signal.addEventListener('abort', ()=>{
+                xhr.abort();
+                reject(new DOMException('Upload aborted', 'AbortError'));
+            }, {
+                once: true
+            });
+        }
+        xhr.upload.onprogress = (event)=>{
+            if (event.lengthComputable) {
+                onProgress(event.loaded, event.total);
+            }
+        };
+        xhr.onload = ()=>{
+            if (xhr.status >= 200 && xhr.status < 300) {
+                resolve();
+            } else {
+                reject(new Error(`Upload failed with status ${xhr.status}`));
+            }
+        };
+        xhr.onerror = ()=>reject(new Error('Network error during upload'));
+        xhr.onabort = ()=>reject(new DOMException('Upload aborted', 'AbortError'));
+        xhr.send(file);
+    });
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function computeTotalProgress(files) {
+    if (files.length === 0) return 0;
+    const sum = files.reduce((acc, f)=>acc + f.progress, 0);
+    return Math.round(sum / files.length);
+}
+// ============================================================================
+// Atom Factory
+// ============================================================================
+const INITIAL_STATE = {
+    isUploading: false,
+    isAborted: false,
+    files: [],
+    totalProgress: 0,
+    error: null,
+    upload: ()=>Promise.resolve(),
+    abort: ()=>{},
+    reset: ()=>{}
+};
+/**
+ * Creates a nanostores atom that manages media upload state.
+ *
+ * Pipeline: sign -> upload primary files.
+ *
+ * Server-side validation (file size, count, MIME types) is handled by the
+ * `createSignedUpload` endpoint.
+ */ function createMediaUploadAtom($fetch) {
+    const store = atom({
+        ...INITIAL_STATE
+    });
+    let controller = null;
+    function updateFileState(index, patch) {
+        const current = store.get();
+        const files = [
+            ...current.files
+        ];
+        files[index] = {
+            ...files[index],
+            ...patch
+        };
+        store.set({
+            ...current,
+            files,
+            totalProgress: computeTotalProgress(files)
+        });
+    }
+    function abort() {
+        controller?.abort();
+        controller = null;
+        const current = store.get();
+        store.set({
+            ...current,
+            isUploading: false,
+            isAborted: true
+        });
+    }
+    function reset() {
+        controller?.abort();
+        controller = null;
+        store.set({
+            ...INITIAL_STATE,
+            upload,
+            abort,
+            reset
+        });
+    }
+    async function upload(files, options) {
+        if (files.length === 0) return;
+        controller = new AbortController();
+        const { signal } = controller;
+        store.set({
+            ...store.get(),
+            isUploading: true,
+            isAborted: false,
+            files: files.map((f)=>({
+                    name: f.name,
+                    progress: 0,
+                    status: 'pending'
+                })),
+            totalProgress: 0,
+            error: null
+        });
+        try {
+            if (signal.aborted) return;
+            // 1. Sign files
+            const signResponse = await $fetch('/media/createSignedUpload', {
+                method: 'POST',
+                body: {
+                    files: files.map((f)=>({
+                            name: f.name,
+                            size: f.size,
+                            type: f.type
+                        })),
+                    folderId: options?.folderId
+                }
+            });
+            if (signal.aborted) return;
+            // 2. Upload files to S3
+            const uploadPromises = signResponse.assets.map(async (asset, index)=>{
+                updateFileState(index, {
+                    status: 'uploading'
+                });
+                try {
+                    await uploadWithXHR(asset.signedUrl, files[index], asset.headers, (loaded, total)=>{
+                        updateFileState(index, {
+                            progress: Math.round(loaded / total * 100)
+                        });
+                    }, signal);
+                    updateFileState(index, {
+                        progress: 100,
+                        status: 'done',
+                        result: {
+                            id: asset.id,
+                            slug: asset.slug,
+                            objectKey: asset.objectKey
+                        }
+                    });
+                } catch (err) {
+                    const isAbortErr = err instanceof DOMException && err.name === 'AbortError';
+                    updateFileState(index, {
+                        status: 'error',
+                        error: isAbortErr ? 'Upload aborted.' : err instanceof Error ? err.message : 'Upload failed'
+                    });
+                }
+            });
+            await Promise.allSettled(uploadPromises);
+            // 3. Finalize
+            const finalState = store.get();
+            const hasErrors = finalState.files.some((f)=>f.status === 'error');
+            store.set({
+                ...finalState,
+                isUploading: false,
+                totalProgress: computeTotalProgress(finalState.files),
+                error: hasErrors ? 'Some files failed to upload' : null
+            });
+        } catch (err) {
+            store.set({
+                ...store.get(),
+                isUploading: false,
+                error: err instanceof Error ? err.message : err
+            });
+        }
+    }
+    store.set({
+        ...INITIAL_STATE,
+        upload,
+        abort,
+        reset
+    });
+    return store;
+}
+
+/**
+ * Creates a `CMSClientStore` from a map of atoms.
+ * Provides `notify` (toggle a signal) and `listen` (subscribe to a signal).
+ */ function createStore(atoms) {
+    return {
+        notify (signal) {
+            const atom = atoms[signal];
+            if (atom) {
+                const current = atom.get();
+                atom.set(typeof current === 'boolean' ? !current : current);
+            }
+        },
+        listen (signal, listener) {
+            const atom = atoms[signal];
+            if (atom) atom.subscribe(listener);
+        },
+        atoms
+    };
+}
+
+/**
+ * Builds the client config synchronously. Atoms, actions, listeners and
+ * error codes are available immediately so React hooks work from the
+ * first render. Plugin `init` (async) is NOT called here — use
+ * `runPluginInit` afterwards.
+ */ function getClientConfigSync(options) {
+    const plugins = options.plugins ?? [];
+    const betterCallClient = createClient({
+        baseURL: options.baseURL
+    });
+    const $fetch = async (path, opts)=>{
+        const res = await betterCallClient(path, opts);
+        if (res.error) throw new CMSClientError(res.error);
+        return res.data;
+    };
+    const pluginsAtoms = {
+        $mediaSignal: atom(false),
+        uploadAssets: createMediaUploadAtom($fetch)
+    };
+    const pluginPathMethods = {};
+    const atomListeners = [
+        {
+            matcher: (path)=>path.startsWith('/media/'),
+            signal: '$mediaSignal'
+        }
+    ];
+    const $store = createStore(pluginsAtoms);
+    for (const plugin of plugins){
+        if (plugin.pathMethods) {
+            Object.assign(pluginPathMethods, plugin.pathMethods);
+        }
+        if (plugin.atomListeners) {
+            atomListeners.push(...plugin.atomListeners);
+        }
+    }
+    let pluginsActions = {};
+    for (const plugin of plugins){
+        if (plugin.getActions) {
+            pluginsActions = {
+                ...pluginsActions,
+                ...plugin.getActions($fetch, $store, options.baseURL)
+            };
+        }
+    }
+    const $ERROR_CODES = {};
+    for (const plugin of plugins){
+        if (plugin.$ERROR_CODES) {
+            Object.assign($ERROR_CODES, plugin.$ERROR_CODES);
+        }
+    }
+    return {
+        $fetch,
+        $store,
+        pluginsActions,
+        pluginsAtoms,
+        pluginPathMethods,
+        atomListeners,
+        $ERROR_CODES
+    };
+}
+/**
+ * Runs async plugin `init` functions sequentially. Call this after
+ * `getClientConfigSync` — the config is already usable before init
+ * completes, so React hooks work immediately.
+ */ async function runPluginInit(options, config) {
+    const plugins = options.plugins ?? [];
+    for (const plugin of plugins){
+        // init runs for its side effects. (Client plugins surface state via
+        // getActions/atoms, which already close over their own config — there is
+        // no shared client context to populate, so any returned `context` is
+        // intentionally not collected.)
+        await plugin.init?.(config.$fetch, config.$store);
+    }
+}
+
+/**
+ * React hook that subscribes to a nanostores atom via `useSyncExternalStore`.
+ * Re-renders the component when the atom value changes.
+ */ function useStore(store) {
+    const snapshotRef = useRef(store.get());
+    const subscribe = useCallback((onChange)=>{
+        const emitChange = (value)=>{
+            if (snapshotRef.current === value) return;
+            snapshotRef.current = value;
+            onChange();
+        };
+        emitChange(store.get());
+        return store.listen(emitChange);
+    }, [
+        store
+    ]);
+    const getSnapshot = ()=>snapshotRef.current;
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+function createCMSClient(options) {
+    if (options) {
+        const config = getClientConfigSync(options);
+        runPluginInit(options, config);
+        return buildClient(config, ()=>useStore(config.pluginsAtoms.uploadAssets));
+    }
+    return (opts)=>{
+        const config = getClientConfigSync(opts);
+        runPluginInit(opts, config);
+        return buildClient(config, ()=>useStore(config.pluginsAtoms.uploadAssets));
+    };
+}
+
+const isServer = ()=>typeof window === 'undefined';
+/**
+ * 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.
+ */ function createCMSQuery(signals, path, $fetch, options) {
+    const value = atom({
+        data: null,
+        error: null,
+        isPending: true,
+        isRefetching: false,
+        refetch: ()=>fetchData()
+    });
+    const fetchData = async ()=>{
+        const current = value.get();
+        value.set({
+            ...current,
+            isPending: current.data === null,
+            isRefetching: current.data !== null,
+            error: null
+        });
+        try {
+            const opts = typeof options === 'function' ? options() : options;
+            const data = await $fetch(path, {
+                method: opts?.method ?? 'GET',
+                query: opts?.query
+            });
+            value.set({
+                data,
+                error: null,
+                isPending: false,
+                isRefetching: false,
+                refetch: ()=>fetchData()
+            });
+        } catch (error) {
+            value.set({
+                ...value.get(),
+                error,
+                isPending: false,
+                isRefetching: false
+            });
+        }
+    };
+    const signalList = Array.isArray(signals) ? signals : [
+        signals
+    ];
+    // Activate only while the query atom has subscribers. On mount, do an initial
+    // fetch and listen to each signal for changes; on unmount, call the
+    // per-listener unsubscribers. We deliberately use the unsubscribe functions
+    // returned by `listen` rather than `atom.off()` — `off()` removes EVERY
+    // listener on the (often shared) signal atom, which would break other queries
+    // subscribed to the same signal.
+    onMount(value, ()=>{
+        if (!isServer()) void fetchData();
+        const unsubscribers = signalList.map((signal)=>signal.listen(()=>{
+                if (!isServer()) void fetchData();
+            }));
+        return ()=>{
+            for (const unsubscribe of unsubscribers)unsubscribe();
+        };
+    });
+    return value;
+}
+
+export { CMSClientError, createCMSClient, createCMSQuery, useStore };