@zenith-open/zenithcms-sdk 1.0.0 → 1.0.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/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/package.json

@@ -1,29 +1,33 @@
-{
-  "name": "@zenith-open/zenithcms-sdk",
-  "version": "1.0.0",
-  "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"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "lint": "echo 'Lint bypassed for sdk'"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@zenith-open/zenithcms-types": "workspace:*",
-    "vitest": "^1.6.0"
-  }
-}
+{
+  "name": "@zenith-open/zenithcms-sdk",
+  "version": "1.0.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": {
+    "@zenith-open/zenithcms-types": "^1.0.1",
+    "vitest": "^1.6.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "echo 'Lint bypassed for sdk'"
+  }
+}

package/src/index.test.ts

@@ -1,117 +0,0 @@
-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' }] } }
-
-    // First request — pre-populate cache with stale data
-    ;(fetch as ReturnType<typeof vi.fn>).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 as ReturnType<typeof vi.fn>).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 as ReturnType<typeof vi.fn>).mock.calls.length).toBeGreaterThanOrEqual(2)
-  })
-})
-
-describe('ZenithClient — batch', () => {
-  it('executes multiple requests in parallel', async () => {
-    const client = makeClient()
-    ;(fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
-      ok: true,
-      json: () => Promise.resolve({ data: { posts: [] } }),
-    })
-
-    await client.batch([
-      { method: 'GET', path: '/api/v1/posts' },
-      { method: 'GET', path: '/api/v1/authors' },
-    ])
-
-    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBe(2)
-  })
-})
-
-describe('ZenithClient — upload', () => {
-  it('sends FormData for file uploads and omits Content-Type header', async () => {
-    const client = makeClient()
-    ;(fetch as ReturnType<typeof vi.fn>).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 as ReturnType<typeof vi.fn>).mock.calls[0]
-    expect(url).toContain('/api/v1/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 as ReturnType<typeof vi.fn>)
-      .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 as ReturnType<typeof vi.fn>).mock.calls[1]
-    expect(lastCall[1].headers.get('X-Zenith-Site-Id')).toBe('site-b')
-  })
-})

package/src/index.ts

@@ -1,556 +0,0 @@
-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
-}
-
-// ── SWR Cache ────────────────────────────────────────────────────────────────
-
-interface CacheEntry<T> {
-  data: T
-  timestamp: number
-  etag?: string
-}
-
-interface PendingRequest {
-  promise: Promise<unknown>
-  controllers: AbortController[]
-}
-
-/**
- * Stale-While-Revalidate cache.
- * Returns stale data immediately, then revalidates in the background.
- * Thread-safe for concurrent requests to the same key.
- */
-class SWRCache {
-  private store = new Map<string, CacheEntry<unknown>>()
-  private pending = new Map<string, PendingRequest>()
-  private defaultTtl: number
-
-  constructor(defaultTtl = 30_000) {
-    this.defaultTtl = defaultTtl
-  }
-
-  get<T>(key: string): { data: T; stale: boolean } | null {
-    const entry = this.store.get(key) as CacheEntry<T> | undefined
-    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<T>(key: string, data: T, etag?: string): void {
-    this.store.set(key, { data, timestamp: Date.now(), etag })
-  }
-
-  invalidate(key: string): void {
-    this.store.delete(key)
-  }
-
-  invalidateTag(tag: string): void {
-    // 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(): void {
-    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 {
-  readonly status: number
-  readonly code?: string
-  readonly isNetworkError: boolean
-  readonly isParseError: boolean
-
-  constructor(opts: {
-    message: string
-    status: number
-    code?: string
-    isNetworkError?: boolean
-    isParseError?: boolean
-  }) {
-    super(opts.message)
-    this.name = 'ZenithAPIError'
-    this.status = opts.status
-    this.code = opts.code
-    this.isNetworkError = opts.isNetworkError ?? false
-    this.isParseError = opts.isParseError ?? false
-  }
-}
-
-// ── Batch Operation Request Descriptor ──────────────────────────────────────
-
-interface BatchRequest {
-  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
-  path: string
-  body?: unknown
-  headers?: Record<string, string>
-}
-
-// ── Main Client ──────────────────────────────────────────────────────────────
-
-/**
- * Lightweight JavaScript client for Zenith CMS, optimized for Edge environments.
- * Zero external dependencies — uses native browser fetch.
- */
-export class ZenithClient {
-  private url: string
-  private apiKey?: string
-  private siteId?: string
-  private cache: SWRCache
-
-  constructor(options: ZenithClientOptions) {
-    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(): void {
-    this.cache.flush()
-  }
-
-  /** Set or update the active site ID. Also flushes the cache to prevent cross-tenant cached content leaks. */
-  setSiteId(siteId?: string): void {
-    this.siteId = siteId
-    this.flushCache()
-  }
-
-  /** Invalidate cache entries matching a tag. */
-  invalidateCache(tag: string): void {
-    this.cache.invalidateTag(tag)
-  }
-
-  private buildQueryString(options: FindOptions): string {
-    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}` : ''
-  }
-
-  private flattenWhereParams(obj: Record<string, any>, prefix: string): Map<string, string> {
-    const map = new Map<string, string>()
-    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
-  }
-
-  private buildHeaders(extra?: Record<string, string>): Headers {
-    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
-  }
-
-  private async fetchAPI(
-    path: string,
-    options: FetchOptions = {},
-    cacheKey?: string
-  ): Promise<any> {
-    const headers = this.buildHeaders(options.headers as Record<string, string>)
-
-    // ── SWR: serve stale data immediately, revalidate in background ──────────
-    const useCache = options.cacheTtl !== 0 && cacheKey
-    const entry = useCache ? this.cache.get<unknown>(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 as any)['pending'] as Map<string, { promise: Promise<unknown>; controllers: AbortController[] }> | undefined
-        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 as Promise<unknown>, controllers: [ctrl] })
-          }
-        }
-      }
-
-      return entry.data as any
-    }
-
-    // No cache or cache disabled — fetch normally
-    let response: 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: any
-    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
-  }
-
-  private cacheKey(collection: string, path: string): string {
-    return `${collection}:${path}`
-  }
-
-  // ── Content API ─────────────────────────────────────────────────────────────
-
-  /**
-   * Find multiple documents in a collection.
-   * Uses SWR cache by default (30s TTL). Bypass with `cacheTtl: 0`.
-   */
-  async find<C extends string>(
-    collection: C,
-    options: FindOptions = {}
-  ): Promise<{ docs: DocType<C>[]; totalDocs: number; totalPages: number; page: number }> {
-    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 } as any
-  }
-
-  /**
-   * Find a single document by ID.
-   * Uses SWR cache by default.
-   */
-  async findById<C extends string>(collection: C, id: string, options: FetchOptions = {}): Promise<DocType<C>> {
-    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<T = any>(slug: string, options: FetchOptions = {}): Promise<T> {
-    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<C extends string>(collection: C, payload: Partial<DocType<C>>, options: FetchOptions = {}): Promise<DocType<C>> {
-    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<C extends string>(
-    collection: C,
-    id: string,
-    payload: Partial<DocType<C>>,
-    options: FetchOptions = {}
-  ): Promise<DocType<C>> {
-    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<C extends string>(collection: C, id: string, options: FetchOptions = {}): Promise<DocType<C>> {
-    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<C extends string>(collection: C, filter?: Record<string, any>): Promise<number> {
-    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<C extends string>(
-    collection: C,
-    pipeline: Record<string, unknown>[]
-  ): Promise<unknown[]> {
-    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: BatchRequest[]): Promise<any[]> {
-    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: File | Blob,
-    metadata?: {
-      alt?: string
-      focalPoint?: { x: number; y: number }
-      folder?: string
-    }
-  ): Promise<any> {
-    const formData = new FormData()
-    const fileName = 'name' in file ? (file as any).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: (File | Blob)[],
-    metadata?: Parameters<typeof this.upload>[1]
-  ): Promise<any[]> {
-    return Promise.all(files.map((file) => this.upload(file, metadata)))
-  }
-}
-
-export function createClient(options: ZenithClientOptions): ZenithClient {
-  return new ZenithClient(options)
-}

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "types": []
-  },
-  "include": ["src"],
-  "exclude": ["**/*.test.ts"]
-}