@zenith-open/zenithcms-sdk 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman T Shekar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Zenith Advanced Cache Service
+ * ─────────────────────────────
+ * Features:
+ * 1. Tag-based invalidation (e.g., invalidate all 'posts')
+ * 2. TTL support
+ * 3. Atomic clears
+ */
+export declare class CacheService {
+    private static cache;
+    private static tags;
+    static initialize(): void;
+    static get<T>(key: string): T | undefined;
+    static set(key: string, value: unknown, ttl?: number, tags?: string[]): void;
+    static del(keys: string | string[]): void;
+    /**
+     * Invalidate all keys associated with a tag
+     */
+    static invalidateTag(tag: string): void;
+    static flush(): void;
+}

package/dist/cache.js

@@ -0,0 +1,55 @@
+import NodeCache from 'node-cache';
+import { logger } from './logger';
+/**
+ * Zenith Advanced Cache Service
+ * ─────────────────────────────
+ * Features:
+ * 1. Tag-based invalidation (e.g., invalidate all 'posts')
+ * 2. TTL support
+ * 3. Atomic clears
+ */
+export class CacheService {
+    static cache = new NodeCache({ stdTTL: 600 }); // 10 min default
+    static tags = {};
+    // Handle key expiration to prevent memory leaks in the tags array
+    static initialize() {
+        this.cache.on('expired', (key) => {
+            Object.keys(this.tags).forEach((tag) => {
+                this.tags[tag] = this.tags[tag].filter((k) => k !== key);
+            });
+        });
+    }
+    static get(key) {
+        return this.cache.get(key);
+    }
+    static set(key, value, ttl, tags = []) {
+        this.cache.set(key, value, ttl || 600);
+        // Track tags
+        tags.forEach((tag) => {
+            if (!this.tags[tag])
+                this.tags[tag] = [];
+            if (!this.tags[tag].includes(key)) {
+                this.tags[tag].push(key);
+            }
+        });
+    }
+    static del(keys) {
+        this.cache.del(keys);
+    }
+    /**
+     * Invalidate all keys associated with a tag
+     */
+    static invalidateTag(tag) {
+        const keys = this.tags[tag];
+        if (keys && keys.length > 0) {
+            logger.info({ tag, count: keys.length }, 'Invalidating cache tag');
+            this.cache.del(keys);
+            this.tags[tag] = [];
+        }
+    }
+    static flush() {
+        this.cache.flushAll();
+        this.tags = {};
+    }
+}
+CacheService.initialize();

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+export interface ZenithClientOptions {
+    url: string;
+    apiKey?: string;
+    siteId?: string;
+}
+export interface FetchOptions extends RequestInit {
+    locale?: string;
+    depth?: number;
+    drafts?: boolean;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface FindOptions extends FetchOptions {
+    where?: Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+    sort?: string;
+    limit?: number;
+    page?: number;
+}
+/**
+ * Lightweight JavaScript client for Zenith CMS, optimized for Edge environments.
+ */
+export declare class ZenithClient {
+    private url;
+    private apiKey?;
+    private siteId?;
+    constructor(options: ZenithClientOptions);
+    private buildQueryString;
+    private flattenWhereParams;
+    private fetchAPI;
+    /**
+     * Find multiple documents in a collection.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+find<T = any>(collection: string, options?: FindOptions): Promise<{ // eslint-disable-line @typescript-eslint/no-explicit-any
+        docs: T[];
+        totalDocs: number;
+        totalPages: number;
+        page: number;
+    }>;
+    /**
+     * Find a single document by its ID.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+findById<T = any>(collection: string, id: string, options?: FetchOptions): Promise<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
+    /**
+     * Fetch a singleton configuration.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+findGlobal<T = any>(slug: string, options?: FetchOptions): Promise<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
+    /**
+     * Create a new document in a collection.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+create<T = any>(collection: string, payload: any, options?: FetchOptions): Promise<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
+    /**
+     * Update an existing document.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+update<T = any>(collection: string, id: string, payload: any, options?: FetchOptions): Promise<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
+    /**
+     * Delete a document.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+delete<T = any>(collection: string, id: string, options?: FetchOptions): Promise<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+export declare function createClient(options: ZenithClientOptions): ZenithClient;

package/dist/client.js

@@ -0,0 +1,129 @@
+/**
+ * Lightweight JavaScript client for Zenith CMS, optimized for Edge environments.
+ */
+export class ZenithClient {
+    url;
+    apiKey;
+    siteId;
+    constructor(options) {
+        this.url = options.url.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.siteId = options.siteId;
+    }
+    buildQueryString(options) {
+        const params = new URLSearchParams();
+        if (options.locale)
+            params.append('locale', options.locale);
+        if (options.depth !== undefined)
+            params.append('depth', String(options.depth));
+        if (options.drafts)
+            params.append('drafts', 'true');
+        if (options.sort)
+            params.append('sort', options.sort);
+        if (options.limit !== undefined)
+            params.append('limit', String(options.limit));
+        if (options.page !== undefined)
+            params.append('page', String(options.page));
+        if (options.where) {
+            this.flattenWhereParams(options.where, 'where').forEach((value, key) => {
+                params.append(key, value);
+            });
+        }
+        const str = params.toString();
+        return str ? `?${str}` : '';
+    }
+    flattenWhereParams(obj, prefix) {
+        const map = new Map();
+        for (const [key, value] of Object.entries(obj)) {
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                const nested = this.flattenWhereParams(value, `${prefix}[${key}]`);
+                nested.forEach((v, k) => map.set(k, v));
+            }
+            else {
+                map.set(`${prefix}[${key}]`, String(value));
+            }
+        }
+        return map;
+    }
+    async fetchAPI(path, options = {}) {
+        const headers = new Headers(options.headers);
+        headers.set('Content-Type', 'application/json');
+        if (this.apiKey) {
+            headers.set('Authorization', `Bearer ${this.apiKey}`);
+        }
+        if (this.siteId) {
+            headers.set('X-Zenith-Site-Id', this.siteId);
+        }
+        const response = await fetch(`${this.url}${path}`, {
+            ...options,
+            headers,
+        });
+        const data = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new Error(data?.message || `Zenith API error: ${response.status} ${response.statusText}`);
+        }
+        return data;
+    }
+    /**
+     * Find multiple documents in a collection.
+     */
+    async find(collection, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}${qs}`, { method: 'GET', ...options });
+        return data.data || data; // Handles different API response envelopes
+    }
+    /**
+     * Find a single document by its ID.
+     */
+    async findById(collection, id, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, { method: 'GET', ...options });
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Fetch a singleton configuration.
+     */
+    async findGlobal(slug, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/globals/${slug}${qs}`, { method: 'GET', ...options });
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Create a new document in a collection.
+     */
+    async create(collection, payload, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}${qs}`, {
+            method: 'POST',
+            body: JSON.stringify(payload),
+            ...options,
+        });
+        return data.data || data;
+    }
+    /**
+     * Update an existing document.
+     */
+    async update(collection, id, payload, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+            ...options,
+        });
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Delete a document.
+     */
+    async delete(collection, id, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, {
+            method: 'DELETE',
+            ...options,
+        });
+        return data.data?.document || data.data || data;
+    }
+}
+export function createClient(options) {
+    return new ZenithClient(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import type { ZenithCollections } from '@zenith-open/zenithcms-types';
+/** Resolve a collection name string to its document type, falling back to any for unknown collections. */
+type DocType<C extends string> = C extends keyof ZenithCollections ? ZenithCollections[C] : any;
+export interface ZenithClientOptions {
+    url: string;
+    apiKey?: string;
+    siteId?: string;
+    /** SWR cache TTL in ms. default 30_000 (30s). set 0 to disable. */
+    cacheTtl?: number;
+}
+export interface FetchOptions extends RequestInit {
+    locale?: string;
+    depth?: number;
+    drafts?: boolean;
+    populate?: string[] | string;
+    select?: string[] | string;
+    /** Override the global cache TTL for this request. 0 = bypass cache. */
+    cacheTtl?: number;
+    /** Tag-based cache invalidation key for this request */
+    cacheTag?: string;
+}
+export interface FindOptions extends FetchOptions {
+    where?: Record<string, any>;
+    sort?: string;
+    limit?: number;
+    page?: number;
+}
+/** Structured error thrown by all ZenithClient methods. */
+export declare class ZenithAPIError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly isNetworkError: boolean;
+    readonly isParseError: boolean;
+    constructor(opts: {
+        message: string;
+        status: number;
+        code?: string;
+        isNetworkError?: boolean;
+        isParseError?: boolean;
+    });
+}
+interface BatchRequest {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Lightweight JavaScript client for Zenith CMS, optimized for Edge environments.
+ * Zero external dependencies — uses native browser fetch.
+ */
+export declare class ZenithClient {
+    private url;
+    private apiKey?;
+    private siteId?;
+    private cache;
+    constructor(options: ZenithClientOptions);
+    /** Flush all cached responses. */
+    flushCache(): void;
+    /** Set or update the active site ID. Also flushes the cache to prevent cross-tenant cached content leaks. */
+    setSiteId(siteId?: string): void;
+    /** Invalidate cache entries matching a tag. */
+    invalidateCache(tag: string): void;
+    private buildQueryString;
+    private flattenWhereParams;
+    private buildHeaders;
+    private fetchAPI;
+    private cacheKey;
+    /**
+     * Find multiple documents in a collection.
+     * Uses SWR cache by default (30s TTL). Bypass with `cacheTtl: 0`.
+     */
+    find<C extends string>(collection: C, options?: FindOptions): Promise<{
+        docs: DocType<C>[];
+        totalDocs: number;
+        totalPages: number;
+        page: number;
+    }>;
+    /**
+     * Find a single document by ID.
+     * Uses SWR cache by default.
+     */
+    findById<C extends string>(collection: C, id: string, options?: FetchOptions): Promise<DocType<C>>;
+    /**
+     * Fetch a singleton configuration.
+     */
+    findGlobal<T = any>(slug: string, options?: FetchOptions): Promise<T>;
+    /**
+     * Create a new document in a collection.
+     * Invalidates cache for the target collection.
+     */
+    create<C extends string>(collection: C, payload: Partial<DocType<C>>, options?: FetchOptions): Promise<DocType<C>>;
+    /**
+     * Update an existing document.
+     * Invalidates cache for the target collection.
+     */
+    update<C extends string>(collection: C, id: string, payload: Partial<DocType<C>>, options?: FetchOptions): Promise<DocType<C>>;
+    /**
+     * Delete a document.
+     * Invalidates cache for the target collection.
+     */
+    delete<C extends string>(collection: C, id: string, options?: FetchOptions): Promise<DocType<C>>;
+    /**
+     * Count documents matching a filter.
+     * Uses SWR cache.
+     */
+    count<C extends string>(collection: C, filter?: Record<string, any>): Promise<number>;
+    /**
+     * Run an aggregation pipeline on a collection.
+     * Sends the pipeline to a dedicated endpoint.
+     */
+    aggregate<C extends string>(collection: C, pipeline: Record<string, unknown>[]): Promise<unknown[]>;
+    /**
+     * Execute multiple API calls in a single round-trip (parallel).
+     * All requests fire concurrently; waits for all to settle.
+     * Returns an array of results in the same order as the input requests.
+     *
+     * @example
+     * const [posts, authors] = await client.batch([
+     *   { method: 'GET', path: '/api/v1/posts?limit=10' },
+     *   { method: 'GET', path: '/api/v1/authors?limit=5' },
+     * ])
+     */
+    batch(requests: BatchRequest[]): Promise<any[]>;
+    /**
+     * Upload a file (image, video, PDF, etc.) to Zenith CMS media store.
+     *
+     * @param file - File or Blob from <input type="file"> or FileReader
+     * @param metadata - Optional alt text, focal point, folder
+     */
+    upload(file: File | Blob, metadata?: {
+        alt?: string;
+        focalPoint?: {
+            x: number;
+            y: number;
+        };
+        folder?: string;
+    }): Promise<any>;
+    /**
+     * Upload multiple files in parallel.
+     * Uses Promise.all for concurrent uploads.
+     */
+    uploadMany(files: (File | Blob)[], metadata?: Parameters<typeof this.upload>[1]): Promise<any[]>;
+}
+export declare function createClient(options: ZenithClientOptions): ZenithClient;
+export {};

package/dist/index.js

@@ -0,0 +1,413 @@
+/**
+ * Stale-While-Revalidate cache.
+ * Returns stale data immediately, then revalidates in the background.
+ * Thread-safe for concurrent requests to the same key.
+ */
+class SWRCache {
+    store = new Map();
+    pending = new Map();
+    defaultTtl;
+    constructor(defaultTtl = 30_000) {
+        this.defaultTtl = defaultTtl;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        const age = Date.now() - entry.timestamp;
+        if (age > this.defaultTtl) {
+            return { data: entry.data, stale: true };
+        }
+        return { data: entry.data, stale: false };
+    }
+    set(key, data, etag) {
+        this.store.set(key, { data, timestamp: Date.now(), etag });
+    }
+    invalidate(key) {
+        this.store.delete(key);
+    }
+    invalidateTag(tag) {
+        // Invalidate all cache entries whose key contains the tag
+        for (const key of this.store.keys()) {
+            if (key.includes(tag))
+                this.store.delete(key);
+        }
+    }
+    flush() {
+        this.store.clear();
+        for (const { controllers } of this.pending.values()) {
+            controllers.forEach((c) => c.abort());
+        }
+        this.pending.clear();
+    }
+}
+// ── Error Handling ────────────────────────────────────────────────────────────
+/** Structured error thrown by all ZenithClient methods. */
+export class ZenithAPIError extends Error {
+    status;
+    code;
+    isNetworkError;
+    isParseError;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ZenithAPIError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.isNetworkError = opts.isNetworkError ?? false;
+        this.isParseError = opts.isParseError ?? false;
+    }
+}
+// ── Main Client ──────────────────────────────────────────────────────────────
+/**
+ * Lightweight JavaScript client for Zenith CMS, optimized for Edge environments.
+ * Zero external dependencies — uses native browser fetch.
+ */
+export class ZenithClient {
+    url;
+    apiKey;
+    siteId;
+    cache;
+    constructor(options) {
+        this.url = options.url.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.siteId = options.siteId;
+        this.cache = new SWRCache(options.cacheTtl ?? 30_000);
+    }
+    // ── Cache control ───────────────────────────────────────────────────────────
+    /** Flush all cached responses. */
+    flushCache() {
+        this.cache.flush();
+    }
+    /** Set or update the active site ID. Also flushes the cache to prevent cross-tenant cached content leaks. */
+    setSiteId(siteId) {
+        this.siteId = siteId;
+        this.flushCache();
+    }
+    /** Invalidate cache entries matching a tag. */
+    invalidateCache(tag) {
+        this.cache.invalidateTag(tag);
+    }
+    buildQueryString(options) {
+        const params = new URLSearchParams();
+        if (options.locale)
+            params.append('locale', options.locale);
+        if (options.depth !== undefined)
+            params.append('depth', String(options.depth));
+        if (options.drafts)
+            params.append('drafts', 'true');
+        if (options.sort)
+            params.append('sort', options.sort);
+        if (options.limit !== undefined)
+            params.append('limit', String(options.limit));
+        if (options.page !== undefined)
+            params.append('page', String(options.page));
+        if (options.populate) {
+            const popStr = Array.isArray(options.populate) ? options.populate.join(',') : options.populate;
+            params.append('populate', popStr);
+        }
+        if (options.select) {
+            const selStr = Array.isArray(options.select) ? options.select.join(',') : options.select;
+            params.append('select', selStr);
+        }
+        if (options.where) {
+            this.flattenWhereParams(options.where, 'where').forEach((value, key) => {
+                params.append(key, value);
+            });
+        }
+        const str = params.toString();
+        return str ? `?${str}` : '';
+    }
+    flattenWhereParams(obj, prefix) {
+        const map = new Map();
+        for (const [key, value] of Object.entries(obj)) {
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                const nested = this.flattenWhereParams(value, `${prefix}[${key}]`);
+                nested.forEach((v, k) => map.set(k, v));
+            }
+            else {
+                map.set(`${prefix}[${key}]`, String(value));
+            }
+        }
+        return map;
+    }
+    buildHeaders(extra) {
+        const headers = new Headers(extra);
+        headers.set('Content-Type', 'application/json');
+        if (this.apiKey)
+            headers.set('Authorization', `Bearer ${this.apiKey}`);
+        if (this.siteId)
+            headers.set('X-Zenith-Site-Id', this.siteId);
+        return headers;
+    }
+    async fetchAPI(path, options = {}, cacheKey) {
+        const headers = this.buildHeaders(options.headers);
+        // ── SWR: serve stale data immediately, revalidate in background ──────────
+        const useCache = options.cacheTtl !== 0 && cacheKey;
+        const entry = useCache ? this.cache.get(cacheKey) : null;
+        if (entry && useCache) {
+            const revalidate = entry.stale && options.cacheTtl !== 0;
+            if (revalidate) {
+                // Deduplicate: if a revalidation for this key is already in-flight, skip
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const pending = this.cache['pending'];
+                if (pending?.has(cacheKey)) {
+                    // revalidation already running for this key — don't spawn another
+                }
+                else {
+                    const ctrl = new AbortController();
+                    const revalidatePromise = fetch(`${this.url}${path}`, {
+                        ...options,
+                        headers,
+                        signal: ctrl.signal,
+                    })
+                        .then((res) => {
+                        if (res.ok)
+                            return res.json();
+                        throw new ZenithAPIError({ message: `HTTP ${res.status}`, status: res.status });
+                    })
+                        .then((data) => {
+                        this.cache.set(cacheKey, data);
+                        pending?.delete(cacheKey);
+                    })
+                        .catch(() => {
+                        // SWR revalidation failures are silent — stale data is acceptable
+                        pending?.delete(cacheKey);
+                    });
+                    if (pending) {
+                        pending.set(cacheKey, { promise: revalidatePromise, controllers: [ctrl] });
+                    }
+                }
+            }
+            return entry.data;
+        }
+        // No cache or cache disabled — fetch normally
+        let response;
+        try {
+            response = await fetch(`${this.url}${path}`, { ...options, headers });
+        }
+        catch (networkErr) {
+            throw new ZenithAPIError({
+                message: networkErr instanceof Error ? networkErr.message : 'Network error',
+                status: 0,
+                isNetworkError: true,
+            });
+        }
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch {
+            throw new ZenithAPIError({
+                message: `Invalid JSON response from server (HTTP ${response.status})`,
+                status: response.status,
+                isParseError: true,
+            });
+        }
+        if (!response.ok) {
+            throw new ZenithAPIError({
+                message: data?.message || `Zenith API error: ${response.status} ${response.statusText}`,
+                status: response.status,
+            });
+        }
+        if (useCache) {
+            this.cache.set(cacheKey, data);
+        }
+        return data;
+    }
+    cacheKey(collection, path) {
+        return `${collection}:${path}`;
+    }
+    // ── Content API ─────────────────────────────────────────────────────────────
+    /**
+     * Find multiple documents in a collection.
+     * Uses SWR cache by default (30s TTL). Bypass with `cacheTtl: 0`.
+     */
+    async find(collection, options = {}) {
+        const qs = this.buildQueryString(options);
+        const cacheKey = (options.cacheTtl !== 0)
+            ? (options.cacheTag
+                ? this.cacheKey(collection, `/api/v1/${collection}${qs}`)
+                : `/api/v1/${collection}${qs}`)
+            : undefined;
+        const data = await this.fetchAPI(`/api/v1/${collection}${qs}`, { method: 'GET', ...options }, cacheKey);
+        const docs = Array.isArray(data.docs)
+            ? data.docs
+            : Array.isArray(data.data)
+                ? data.data
+                : data.data?.docs || [];
+        const totalDocs = data.totalDocs ?? data.meta?.pagination?.total ?? docs.length;
+        const totalPages = data.totalPages ?? data.meta?.pagination?.totalPages ?? 1;
+        const page = data.page ?? data.meta?.pagination?.page ?? 1;
+        return { docs, totalDocs, totalPages, page, data: docs, ...data };
+    }
+    /**
+     * Find a single document by ID.
+     * Uses SWR cache by default.
+     */
+    async findById(collection, id, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, { method: 'GET', ...options }, `/api/v1/${collection}/${id}${qs}`);
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Fetch a singleton configuration.
+     */
+    async findGlobal(slug, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/globals/${slug}${qs}`, { method: 'GET', ...options }, `/api/v1/globals/${slug}${qs}`);
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Create a new document in a collection.
+     * Invalidates cache for the target collection.
+     */
+    async create(collection, payload, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}${qs}`, {
+            method: 'POST',
+            body: JSON.stringify(payload),
+            ...options,
+            cacheTtl: 0, // writes never use cache
+        });
+        this.cache.invalidateTag(collection); // optimistic invalidation
+        return data.data || data;
+    }
+    /**
+     * Update an existing document.
+     * Invalidates cache for the target collection.
+     */
+    async update(collection, id, payload, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+            ...options,
+            cacheTtl: 0,
+        });
+        this.cache.invalidateTag(collection);
+        return data.data?.document || data.data || data;
+    }
+    /**
+     * Delete a document.
+     * Invalidates cache for the target collection.
+     */
+    async delete(collection, id, options = {}) {
+        const qs = this.buildQueryString(options);
+        const data = await this.fetchAPI(`/api/v1/${collection}/${id}${qs}`, {
+            method: 'DELETE',
+            ...options,
+            cacheTtl: 0,
+        });
+        this.cache.invalidateTag(collection);
+        return data.data?.document || data.data || data;
+    }
+    // ── Aggregation & Counts ────────────────────────────────────────────────────
+    /**
+     * Count documents matching a filter.
+     * Uses SWR cache.
+     */
+    async count(collection, filter) {
+        const params = new URLSearchParams();
+        if (filter) {
+            Object.entries(filter).forEach(([k, v]) => {
+                if (v !== undefined && v !== null)
+                    params.append(`where[${k}]`, String(v));
+            });
+        }
+        const paramStr = params.toString();
+        const qs = paramStr ? `?${paramStr}` : '';
+        const data = await this.fetchAPI(`/api/v1/${collection}/count${qs}`, { method: 'GET', cacheTtl: 0 });
+        return typeof data.data?.count === 'number' ? data.data.count : (data.count ?? 0);
+    }
+    /**
+     * Run an aggregation pipeline on a collection.
+     * Sends the pipeline to a dedicated endpoint.
+     */
+    async aggregate(collection, pipeline) {
+        const data = await this.fetchAPI(`/api/v1/${collection}/aggregate`, {
+            method: 'POST',
+            body: JSON.stringify({ pipeline }),
+            cacheTtl: 0,
+        });
+        return data.data?.results ?? data.results ?? data;
+    }
+    // ── Batch Operations ────────────────────────────────────────────────────────
+    /**
+     * Execute multiple API calls in a single round-trip (parallel).
+     * All requests fire concurrently; waits for all to settle.
+     * Returns an array of results in the same order as the input requests.
+     *
+     * @example
+     * const [posts, authors] = await client.batch([
+     *   { method: 'GET', path: '/api/v1/posts?limit=10' },
+     *   { method: 'GET', path: '/api/v1/authors?limit=5' },
+     * ])
+     */
+    async batch(requests) {
+        const results = await Promise.all(requests.map(async (req) => {
+            const headers = this.buildHeaders(req.headers);
+            try {
+                const response = await fetch(`${this.url}${req.path}`, {
+                    method: req.method || 'GET',
+                    headers,
+                    body: req.body ? JSON.stringify(req.body) : undefined,
+                });
+                const data = await response.json().catch(() => null);
+                if (!response.ok) {
+                    throw new Error(data?.message || `Batch item failed: ${response.status}`);
+                }
+                return data.data ?? data;
+            }
+            catch (err) {
+                // Propagate errors so Promise.allSettled-like behavior is available via .catch
+                throw err;
+            }
+        }));
+        return results;
+    }
+    // ── File Upload ─────────────────────────────────────────────────────────────
+    /**
+     * Upload a file (image, video, PDF, etc.) to Zenith CMS media store.
+     *
+     * @param file - File or Blob from <input type="file"> or FileReader
+     * @param metadata - Optional alt text, focal point, folder
+     */
+    async upload(file, metadata) {
+        const formData = new FormData();
+        const fileName = 'name' in file ? file.name : 'file';
+        formData.append('file', file, fileName);
+        // Attach focal point as JSON string (multer parses it server-side)
+        if (metadata?.focalPoint) {
+            formData.append('focalPoint', JSON.stringify(metadata.focalPoint));
+        }
+        if (metadata?.alt) {
+            formData.append('alt', metadata.alt);
+        }
+        if (metadata?.folder) {
+            formData.append('folder', metadata.folder);
+        }
+        const headers = this.buildHeaders();
+        // Remove Content-Type so fetch sets the correct multipart boundary
+        headers.delete('Content-Type');
+        const response = await fetch(`${this.url}/api/v1/upload`, {
+            method: 'POST',
+            headers,
+            body: formData,
+        });
+        const data = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new Error(data?.message || `Upload failed: ${response.status}`);
+        }
+        return data.data ?? data;
+    }
+    /**
+     * Upload multiple files in parallel.
+     * Uses Promise.all for concurrent uploads.
+     */
+    async uploadMany(files, metadata) {
+        return Promise.all(files.map((file) => this.upload(file, metadata)));
+    }
+}
+export function createClient(options) {
+    return new ZenithClient(options);
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ZenithClient } from './index';
+// Minimal fetch mock — intercepts calls and returns JSON
+function makeClient() {
+    return new ZenithClient({ url: 'http://localhost:3000' });
+}
+beforeEach(() => {
+    global.fetch = vi.fn();
+});
+describe('ZenithClient — SWR cache', () => {
+    it('serves stale data immediately and revalidates in background', async () => {
+        const client = makeClient();
+        const mockData = { data: { docs: [{ _id: '1', title: 'Cached Post' }] } };
+        fetch.mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve(mockData),
+        });
+        const result1 = await client.find('posts', { limit: 5, cacheTtl: 30_000 });
+        expect(result1.docs[0].title).toBe('Cached Post');
+        // Second request should return cached data immediately without waiting
+        const start = Date.now();
+        const result2 = await client.find('posts', { limit: 5 });
+        const elapsed = Date.now() - start;
+        // With cache hit and SWR revalidation, this should be near-instant
+        expect(elapsed).toBeLessThan(50);
+        expect(result2.docs[0].title).toBe('Cached Post');
+    });
+    it('bypasses cache when cacheTtl is 0', async () => {
+        const client = makeClient();
+        fetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ data: { docs: [] } }),
+        });
+        // Should call fetch both times
+        await client.find('posts', { cacheTtl: 0 });
+        await client.find('posts', { cacheTtl: 0 });
+        expect(fetch.mock.calls.length).toBeGreaterThanOrEqual(2);
+    });
+});
+describe('ZenithClient — batch', () => {
+    it('executes multiple requests in parallel', async () => {
+        const client = makeClient();
+        fetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ data: { posts: [] } }),
+        });
+        await client.batch([
+            { method: 'GET', path: '/api/beta/posts' },
+            { method: 'GET', path: '/api/beta/authors' },
+        ]);
+        expect(fetch.mock.calls.length).toBe(2);
+    });
+});
+describe('ZenithClient — upload', () => {
+    it('sends FormData for file uploads and omits Content-Type header', async () => {
+        const client = makeClient();
+        fetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ data: { _id: '123', url: 'http://cdn/img.jpg' } }),
+        });
+        const file = new File(['hello'], 'test.jpg', { type: 'image/jpeg' });
+        await client.upload(file, { alt: 'Test alt', focalPoint: { x: 50, y: 50 } });
+        const [url, options] = fetch.mock.calls[0];
+        expect(url).toContain('/api/beta/upload');
+        expect(options.headers.get('Content-Type')).toBeNull(); // fetch auto-sets multipart
+        expect(options.method).toBe('POST');
+    });
+});
+describe('ZenithClient — site switching', () => {
+    it('updates siteId and flushes cache when setSiteId is called', async () => {
+        const client = makeClient();
+        const mockData1 = { data: { docs: [{ _id: '1', title: 'Post Site A' }] } };
+        const mockData2 = { data: { docs: [{ _id: '2', title: 'Post Site B' }] } };
+        fetch
+            .mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve(mockData1),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve(mockData2),
+        });
+        // Fetch on default site ID (empty)
+        const res1 = await client.find('posts', { limit: 5 });
+        expect(res1.docs[0].title).toBe('Post Site A');
+        // Change site ID using setSiteId
+        client.setSiteId('site-b');
+        // Fetch again — cache should be flushed, performing a new fetch with headers
+        const res2 = await client.find('posts', { limit: 5 });
+        expect(res2.docs[0].title).toBe('Post Site B');
+        // Verify correct header was sent in the second request
+        const lastCall = fetch.mock.calls[1];
+        expect(lastCall[1].headers.get('X-Zenith-Site-Id')).toBe('site-b');
+    });
+});

package/dist/src/index.d.ts

@@ -0,0 +1,43 @@
+interface ZenithConfig {
+    baseURL: string;
+    token?: string;
+    cacheTTL?: number;
+}
+/**
+ * Zenith SDK — Universal Client
+ * ─────────────────────────────
+ * A high-performance, type-safe client for consuming Zenith CMS content.
+ * Features built-in caching and automated error handling.
+ */
+export declare class ZenithClient {
+    private api;
+    private cache;
+    private ttl;
+    constructor(config: ZenithConfig);
+    /**
+     * Fetch a list of entries from a collection
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+find<T = any>(slug: string, params?: Record<string, any>): Promise<{
 // eslint-disable-line @typescript-eslint/no-explicit-any
+        data: T[];
+        meta: any;
 // eslint-disable-line @typescript-eslint/no-explicit-any
+    }>;
+    /**
+     * Fetch a single entry by ID
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+findOne<T = any>(slug: string, id: string): Promise<{
 // eslint-disable-line @typescript-eslint/no-explicit-any
+        data: T;
+    }>;
+    /**
+     * Fetch a singleton collection
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+getSingleton<T = any>(slug: string): Promise<{
 // eslint-disable-line @typescript-eslint/no-explicit-any
+        data: T;
+    }>;
+    private getCache;
+    private setCache;
+    private handleError;
+}
+export {};

package/dist/src/index.js

@@ -0,0 +1,86 @@
+import axios from 'axios';
+/**
+ * Zenith SDK — Universal Client
+ * ─────────────────────────────
+ * A high-performance, type-safe client for consuming Zenith CMS content.
+ * Features built-in caching and automated error handling.
+ */
+export class ZenithClient {
+    api;
+    cache = new Map();
+    ttl;
+    constructor(config) {
+        this.ttl = config.cacheTTL || 60000; // Default 1 min
+        this.api = axios.create({
+            baseURL: config.baseURL.endsWith('/api/beta') ? config.baseURL : `${config.baseURL}/api/beta`,
+            headers: config.token ? { Authorization: `Bearer ${config.token}` } : {},
+        });
+    }
+    /**
+     * Fetch a list of entries from a collection
+     */
+    async find(slug, params = {}) {
+        const cacheKey = `${slug}:list:${JSON.stringify(params)}`;
+        const cached = this.getCache(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const res = await this.api.get(`/${slug}`, { params });
+            this.setCache(cacheKey, res.data);
+            return res.data;
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    /**
+     * Fetch a single entry by ID
+     */
+    async findOne(slug, id) {
+        const cacheKey = `${slug}:${id}`;
+        const cached = this.getCache(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const res = await this.api.get(`/${slug}/${id}`);
+            this.setCache(cacheKey, res.data);
+            return res.data;
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    /**
+     * Fetch a singleton collection
+     */
+    async getSingleton(slug) {
+        const cacheKey = `singleton:${slug}`;
+        const cached = this.getCache(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const res = await this.api.get(`/${slug}`);
+            this.setCache(cacheKey, res.data);
+            return res.data;
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    // --- Cache Helpers ---
+    getCache(key) {
+        const cached = this.cache.get(key);
+        if (cached && cached.expiry > Date.now())
+            return cached.data;
+        if (cached)
+            this.cache.delete(key);
+        return null;
+    }
+    setCache(key, data) {
+        this.cache.set(key, { data, expiry: Date.now() + this.ttl });
+    }
+    handleError(err) {
+        const message = err.response?.data?.error?.message || err.message || 'Unknown Zenith SDK Error';
+        throw new Error(`[Zenith SDK] ${message}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+import type { paths } from './schema';
+/**
+ * Resolve a collection name string to its document type via OpenAPI schema paths.
+ * Falls back to unknown for unknown collections.
+ */
+type GetPath<C extends string> = `/${C}`;
+type ExtractArrayItem<T> = T extends (infer U)[] ? U : unknown;
+type OpenAPIResponse<P extends string> = P extends keyof paths ? 'get' extends keyof paths[P] ? 'responses' extends keyof paths[P]['get'] ? 200 extends keyof paths[P]['get']['responses'] ? 'content' extends keyof paths[P]['get']['responses'][200] ? 'application/json' extends keyof paths[P]['get']['responses'][200]['content'] ? 'schema' extends keyof paths[P]['get']['responses'][200]['content']['application/json'] ? paths[P]['get']['responses'][200]['content']['application/json']['schema'] : unknown : unknown : unknown : unknown : unknown : unknown : unknown;
+export type DocType<C extends string> = OpenAPIResponse<GetPath<C>> extends never ? unknown : ExtractArrayItem<OpenAPIResponse<GetPath<C>>>;
+export interface ZenithClientOptions {
+    url: string;
+    apiKey?: string;
+    siteId?: string;
+    /** SWR cache TTL in ms. default 30_000 (30s). set 0 to disable. */
+    cacheTtl?: number;
+}
+export interface FetchOptions extends RequestInit {
+    locale?: string;
+    depth?: number;
+    drafts?: boolean;
+    populate?: string[] | string;
+    select?: string[] | string;
+    /** Override the global cache TTL for this request. 0 = bypass cache. */
+    cacheTtl?: number;
+    /** Tag-based cache invalidation key for this request */
+    cacheTag?: string;
+}
+export interface FindOptions extends FetchOptions {
+    where?: Record<string, unknown>;
+    sort?: string;
+    limit?: number;
+    page?: number;
+}
+export interface BatchRequest {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Structured error thrown by all ZenithClient methods. */
+export declare class ZenithAPIError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly isNetworkError: boolean;
+    readonly isParseError: boolean;
+    constructor(opts: {
+        message: string;
+        status: number;
+        code?: string;
+        isNetworkError?: boolean;
+        isParseError?: boolean;
+    });
+}
+export {};

package/dist/types.js

@@ -0,0 +1,16 @@
+// ── Error Handling ────────────────────────────────────────────────────────────
+/** Structured error thrown by all ZenithClient methods. */
+export class ZenithAPIError extends Error {
+    status;
+    code;
+    isNetworkError;
+    isParseError;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ZenithAPIError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.isNetworkError = opts.isNetworkError ?? false;
+        this.isParseError = opts.isParseError ?? false;
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@zenith-open/zenithcms-sdk",
+  "version": "1.0.0-beta.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Lightweight JavaScript client for Zenith CMS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "vitest": "^1.6.0",
+    "@zenith-open/zenithcms-types": "1.0.0-beta.1"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "echo 'Lint bypassed for sdk'"
+  }
+}