@dalgoridim/headless-cms 0.1.0

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 dalgoridim. All rights reserved.
+
+This software and its source code are proprietary and confidential. No license,
+express or implied, is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell copies of this software without the prior written permission
+of the copyright holder.
+
+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.

package/README.md

@@ -0,0 +1,178 @@
+# @dalgoridim/headless-cms
+
+Database-agnostic, inline-edit headless CMS engine for React / Next.js apps.
+
+Content lives in your database and is editable **inline on the live site** by an
+authenticated admin. The persistence, auth, and storage layers are fully
+pluggable — swap Firestore for Postgres, Cloudinary for S3, Firebase auth for
+NextAuth, without touching the editing UI.
+
+## Install
+
+```bash
+npm install @dalgoridim/headless-cms
+# plus the adapters you actually use, e.g.:
+npm install firebase firebase-admin cloudinary   # Firestore + Cloudinary + Firebase
+npm install pg                                    # Postgres
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner  # S3
+```
+
+`react` / `react-dom` are peer deps; every backend SDK is an **optional** peer —
+you only install the ones your chosen adapters need.
+
+## Subpath exports
+
+Server-only code never leaks into the client bundle. Import from the right entry:
+
+| Entry | Contents |
+|---|---|
+| `@dalgoridim/headless-cms` | Shared types only (safe anywhere) |
+| `.../client` | `PageProvider`, `usePageContext`, `ContentEditSpan`, `EditableImage`, `MarkdownEditor`, `CmsAuthProvider`, `useCmsAuth` |
+| `.../server` | `createCmsHandlers`, `createAdminGate` |
+| `.../adapters/firestore` | `FirestoreDataAdapter` |
+| `.../adapters/postgres` | `PostgresDataAdapter` (hybrid JSONB + typed tables) |
+| `.../storage/cloudinary` \| `.../storage/s3` \| `.../storage/local` | **Client** upload adapters (`cloudinaryStorage`, `s3Storage`, `localStorage`) — pure `fetch`, safe in client components |
+| `.../storage/cloudinary/server` \| `.../storage/s3/server` \| `.../storage/local/server` | **Server** signers (`cloudinarySign`, `s3Sign`, `localSign`) — pull in SDKs, server-only |
+| `.../auth/firebase` | `firebaseAuth` (server gate) |
+| `.../auth/firebase/client` | `FirebaseAuthProvider`, `useFirebaseAuth` |
+| `.../auth/nextauth` | `nextAuthAuth`, `customAuth` |
+
+## The three core interfaces
+
+```ts
+import type { DataAdapter, AuthAdapter, StorageAdapter } from "@dalgoridim/headless-cms";
+```
+
+- **`DataAdapter`** — backend CRUD over a neutral `Query`.
+- **`AuthAdapter`** — `verifyRequest(req)` gates every admin route, server-side.
+- **Storage** is split into two halves so server SDKs never reach the client
+  bundle: `ClientStorageAdapter` (`upload`, from `.../storage/<x>`) and
+  `ServerStorageAdapter` (`sign`, from `.../storage/<x>/server`).
+
+## Wiring (Next.js App Router)
+
+**1. The admin CRUD route** — replaces a hand-written handler:
+
+```ts
+// app/api/admin/[collection]/[id]/route.ts
+import { createCmsHandlers } from "@dalgoridim/headless-cms/server";
+import { FirestoreDataAdapter } from "@dalgoridim/headless-cms/adapters/firestore";
+import { firebaseAuth } from "@dalgoridim/headless-cms/auth/firebase";
+
+export const { GET, PATCH, PUT, DELETE } = createCmsHandlers({
+  data: new FirestoreDataAdapter({
+    credentials: {
+      projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+      clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
+      privateKey: process.env.FIREBASE_PRIVATE_KEY,
+    },
+  }),
+  auth: firebaseAuth({ adminEmails: process.env.ADMIN_EMAILS!.split(",") }),
+});
+```
+
+**2. The storage sign route** — uses the **server** signer:
+
+```ts
+// app/api/admin/sign/route.ts
+import { createCmsHandlers } from "@dalgoridim/headless-cms/server";
+import { cloudinarySign } from "@dalgoridim/headless-cms/storage/cloudinary/server";
+// ...same data + auth as above...
+export const POST = createCmsHandlers({
+  data,
+  auth,
+  storage: cloudinarySign({
+    cloudName: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME,
+    apiKey: process.env.CLOUDINARY_API_KEY,
+    apiSecret: process.env.CLOUDINARY_API_SECRET,
+    folder: "uploads", // must match the client's folder
+  }),
+}).sign;
+```
+
+**3. Providers + editable content** (client):
+
+```tsx
+"use client";
+import { PageProvider, ContentEditSpan, EditableImage } from "@dalgoridim/headless-cms/client";
+import { FirebaseAuthProvider } from "@dalgoridim/headless-cms/auth/firebase/client";
+import { cloudinaryStorage } from "@dalgoridim/headless-cms/storage/cloudinary";
+import { auth, googleProvider } from "@/lib/firebase/config";
+
+// Client upload adapter — posts to the sign route, then to Cloudinary.
+const storage = cloudinaryStorage({ folder: "uploads", signEndpoint: "/api/admin/sign" });
+
+export function Providers({ initialSections, children }) {
+  return (
+    <FirebaseAuthProvider auth={auth} googleProvider={googleProvider}>
+      <PageProvider initialSections={initialSections} storage={storage}>
+        {children}
+      </PageProvider>
+    </FirebaseAuthProvider>
+  );
+}
+
+// Anywhere inside:
+<ContentEditSpan collection="portfolio" sectionKey="hero" fieldKey="title" as="h1">
+  Default title
+</ContentEditSpan>
+<EditableImage collection="portfolio" sectionKey="hero" fieldKey="image"
+  docId="hero" src={section.image} />
+```
+
+`PageProvider` saves `PATCH ${apiBasePath}/{collection}/{id}` (default
+`apiBasePath` = `/api/admin`). Edit mode is driven by `useCmsAuth().isEditing`;
+the built-in auth providers feed that context.
+
+## Postgres (hybrid)
+
+Unregistered collections live in a shared JSONB `documents` table; registered
+collections map flat fields onto typed columns, with a JSONB `extra` column so
+unmapped fields are never dropped.
+
+```ts
+import { PostgresDataAdapter } from "@dalgoridim/headless-cms/adapters/postgres";
+
+const data = new PostgresDataAdapter({
+  connectionString: process.env.DATABASE_URL!,
+  collections: {
+    projects: { table: "projects", columns: { title: "text", date: "date" } },
+  },
+});
+await data.migrate(); // creates documents + registered tables if missing
+```
+
+## Content markup
+
+`ContentEditSpan` supports inline marks: `**bold**`, `*italic*`, `~~strike~~`,
+`^^primary color^^`, `__underline__`, `~~br~~`, and `[label](https://url)`.
+`MarkdownEditor` provides full GitHub-flavored markdown editing.
+
+## Styling
+
+The client components ship **Tailwind utility classes** (and use a `--color-primary`
+custom property / `text-primary` utility for accents). The consuming app is
+responsible for Tailwind. With Tailwind v4, point it at the package so those
+classes are generated, and define a primary color:
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@source "../node_modules/@dalgoridim/headless-cms/dist";
+
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+## Build
+
+```bash
+npm run build      # tsup → dist (esm + cjs + d.ts), per subpath
+npm run typecheck  # tsc --noEmit
+```
+
+## Stability
+
+Pre-`1.0`: the API may change between minor versions as the engine evolves.
+Pin an exact version if you depend on it in production.

package/dist/adapters/firestore/index.cjs

@@ -0,0 +1,152 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/firestore/index.ts
+var firestore_exports = {};
+__export(firestore_exports, {
+  FirestoreDataAdapter: () => FirestoreDataAdapter
+});
+module.exports = __toCommonJS(firestore_exports);
+var import_firebase_admin = __toESM(require("firebase-admin"), 1);
+var OP_MAP = {
+  eq: "==",
+  lt: "<",
+  lte: "<=",
+  gt: ">",
+  gte: ">=",
+  in: "in"
+};
+function serialize(data) {
+  if (Array.isArray(data)) {
+    return data.map(serialize);
+  }
+  if (data && typeof data === "object") {
+    const obj = data;
+    if ("_seconds" in obj && "_nanoseconds" in obj) {
+      return new Date(
+        obj._seconds * 1e3 + obj._nanoseconds / 1e6
+      ).toISOString();
+    }
+    if (typeof obj.toDate === "function") {
+      return obj.toDate().toISOString();
+    }
+    const out = {};
+    for (const key in obj) out[key] = serialize(obj[key]);
+    return out;
+  }
+  return data;
+}
+var FirestoreDataAdapter = class {
+  constructor(config = {}) {
+    var _a, _b;
+    this.defaultOrderByField = (_a = config.defaultOrderByField) != null ? _a : "createdAt";
+    if (config.db) {
+      this.db = config.db;
+      return;
+    }
+    if (!import_firebase_admin.default.apps.length) {
+      const c = (_b = config.credentials) != null ? _b : {};
+      import_firebase_admin.default.initializeApp({
+        credential: import_firebase_admin.default.credential.cert({
+          projectId: c.projectId,
+          clientEmail: c.clientEmail,
+          privateKey: c.privateKey
+        }),
+        databaseURL: c.databaseURL
+      });
+    }
+    this.db = import_firebase_admin.default.firestore();
+  }
+  buildQuery(collection, q) {
+    var _a, _b;
+    let ref = this.db.collection(collection);
+    if (!q) {
+      return ref.orderBy(this.defaultOrderByField, "desc");
+    }
+    for (const f of (_a = q.filters) != null ? _a : []) {
+      ref = ref.where(f.field, OP_MAP[f.op], f.value);
+    }
+    for (const o of (_b = q.orderBy) != null ? _b : []) {
+      ref = ref.orderBy(o.field, o.direction);
+    }
+    if (q.limit != null) ref = ref.limit(q.limit);
+    return ref;
+  }
+  async fetchCollection(collection, q) {
+    const snap = await this.buildQuery(collection, q).get();
+    return snap.docs.map(
+      (doc) => serialize(__spreadValues({ id: doc.id }, doc.data()))
+    );
+  }
+  async fetchById(collection, id) {
+    const doc = await this.db.collection(collection).doc(id).get();
+    if (!doc.exists) return null;
+    return serialize(__spreadValues({ id: doc.id }, doc.data()));
+  }
+  async create(collection, data) {
+    const ref = this.db.collection(collection).doc();
+    await ref.set(__spreadProps(__spreadValues({}, data), { createdAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() }));
+    return __spreadValues({ id: ref.id }, data);
+  }
+  async createWithId(collection, id, data) {
+    await this.db.collection(collection).doc(id).set(__spreadProps(__spreadValues({}, data), { createdAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() }));
+    return __spreadValues({ id }, data);
+  }
+  async update(collection, id, data) {
+    await this.db.collection(collection).doc(id).update(__spreadProps(__spreadValues({}, data), { updatedAt: /* @__PURE__ */ new Date() }));
+  }
+  async upsert(collection, id, data) {
+    await this.db.collection(collection).doc(id).set(__spreadProps(__spreadValues({}, data), { updatedAt: /* @__PURE__ */ new Date() }), { merge: true });
+  }
+  async delete(collection, id) {
+    await this.db.collection(collection).doc(id).delete();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FirestoreDataAdapter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/adapters/firestore/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/firestore/index.ts"],"sourcesContent":["import admin from \"firebase-admin\";\nimport type {\n  Firestore,\n  Query as FirestoreQuery,\n  WhereFilterOp,\n} from \"firebase-admin/firestore\";\nimport type { DataAdapter, Query, QueryFilterOp } from \"../../types\";\n\nexport interface FirestoreAdapterConfig {\n  /** Provide an existing admin Firestore instance… */\n  db?: Firestore;\n  /** …or service-account credentials to initialize firebase-admin lazily. */\n  credentials?: {\n    projectId?: string;\n    clientEmail?: string;\n    privateKey?: string;\n    databaseURL?: string;\n  };\n  /** Field used for default ordering when no query is given. Default `createdAt`. */\n  defaultOrderByField?: string;\n}\n\nconst OP_MAP: Record<QueryFilterOp, WhereFilterOp> = {\n  eq: \"==\",\n  lt: \"<\",\n  lte: \"<=\",\n  gt: \">\",\n  gte: \">=\",\n  in: \"in\",\n};\n\n/** Firestore Timestamps → ISO strings, recursively, so the API returns plain JSON. */\nfunction serialize<T>(data: T): T {\n  if (Array.isArray(data)) {\n    return data.map(serialize) as unknown as T;\n  }\n  if (data && typeof data === \"object\") {\n    const obj = data as Record<string, unknown>;\n    if (\"_seconds\" in obj && \"_nanoseconds\" in obj) {\n      return new Date(\n        (obj._seconds as number) * 1000 + (obj._nanoseconds as number) / 1e6,\n      ).toISOString() as unknown as T;\n    }\n    if (typeof (obj as { toDate?: unknown }).toDate === \"function\") {\n      return (obj as { toDate: () => Date }).toDate().toISOString() as unknown as T;\n    }\n    const out: Record<string, unknown> = {};\n    for (const key in obj) out[key] = serialize(obj[key]);\n    return out as T;\n  }\n  return data;\n}\n\nexport class FirestoreDataAdapter implements DataAdapter {\n  private readonly db: Firestore;\n  private readonly defaultOrderByField: string;\n\n  constructor(config: FirestoreAdapterConfig = {}) {\n    this.defaultOrderByField = config.defaultOrderByField ?? \"createdAt\";\n\n    if (config.db) {\n      this.db = config.db;\n      return;\n    }\n\n    if (!admin.apps.length) {\n      const c = config.credentials ?? {};\n      admin.initializeApp({\n        credential: admin.credential.cert({\n          projectId: c.projectId,\n          clientEmail: c.clientEmail,\n          privateKey: c.privateKey,\n        }),\n        databaseURL: c.databaseURL,\n      });\n    }\n    this.db = admin.firestore();\n  }\n\n  private buildQuery(collection: string, q?: Query): FirestoreQuery {\n    let ref: FirestoreQuery = this.db.collection(collection);\n\n    if (!q) {\n      return ref.orderBy(this.defaultOrderByField, \"desc\");\n    }\n\n    for (const f of q.filters ?? []) {\n      ref = ref.where(f.field, OP_MAP[f.op], f.value);\n    }\n    for (const o of q.orderBy ?? []) {\n      ref = ref.orderBy(o.field, o.direction);\n    }\n    if (q.limit != null) ref = ref.limit(q.limit);\n    return ref;\n  }\n\n  async fetchCollection<T = Record<string, unknown>>(\n    collection: string,\n    q?: Query,\n  ): Promise<(T & { id: string })[]> {\n    const snap = await this.buildQuery(collection, q).get();\n    return snap.docs.map((doc) =>\n      serialize({ id: doc.id, ...(doc.data() as T) }),\n    );\n  }\n\n  async fetchById<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n  ): Promise<(T & { id: string }) | null> {\n    const doc = await this.db.collection(collection).doc(id).get();\n    if (!doc.exists) return null;\n    return serialize({ id: doc.id, ...(doc.data() as T) });\n  }\n\n  async create<T = Record<string, unknown>>(\n    collection: string,\n    data: T,\n  ): Promise<T & { id: string }> {\n    const ref = this.db.collection(collection).doc();\n    await ref.set({ ...data, createdAt: new Date(), updatedAt: new Date() });\n    return { id: ref.id, ...(data as T) };\n  }\n\n  async createWithId<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: T,\n  ): Promise<T & { id: string }> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .set({ ...data, createdAt: new Date(), updatedAt: new Date() });\n    return { id, ...(data as T) };\n  }\n\n  async update<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .update({ ...data, updatedAt: new Date() });\n  }\n\n  async upsert<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .set({ ...data, updatedAt: new Date() }, { merge: true });\n  }\n\n  async delete(collection: string, id: string): Promise<void> {\n    await this.db.collection(collection).doc(id).delete();\n  }\n}\n"],"mappings":"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","names":["admin"]}

package/dist/adapters/firestore/index.d.cts

@@ -0,0 +1,39 @@
+import { Firestore } from 'firebase-admin/firestore';
+import { DataAdapter, Query } from '../../index.cjs';
+
+interface FirestoreAdapterConfig {
+    /** Provide an existing admin Firestore instance… */
+    db?: Firestore;
+    /** …or service-account credentials to initialize firebase-admin lazily. */
+    credentials?: {
+        projectId?: string;
+        clientEmail?: string;
+        privateKey?: string;
+        databaseURL?: string;
+    };
+    /** Field used for default ordering when no query is given. Default `createdAt`. */
+    defaultOrderByField?: string;
+}
+declare class FirestoreDataAdapter implements DataAdapter {
+    private readonly db;
+    private readonly defaultOrderByField;
+    constructor(config?: FirestoreAdapterConfig);
+    private buildQuery;
+    fetchCollection<T = Record<string, unknown>>(collection: string, q?: Query): Promise<(T & {
+        id: string;
+    })[]>;
+    fetchById<T = Record<string, unknown>>(collection: string, id: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    create<T = Record<string, unknown>>(collection: string, data: T): Promise<T & {
+        id: string;
+    }>;
+    createWithId<T = Record<string, unknown>>(collection: string, id: string, data: T): Promise<T & {
+        id: string;
+    }>;
+    update<T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>): Promise<void>;
+    upsert<T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>): Promise<void>;
+    delete(collection: string, id: string): Promise<void>;
+}
+
+export { type FirestoreAdapterConfig, FirestoreDataAdapter };

package/dist/adapters/firestore/index.d.ts

@@ -0,0 +1,39 @@
+import { Firestore } from 'firebase-admin/firestore';
+import { DataAdapter, Query } from '../../index.js';
+
+interface FirestoreAdapterConfig {
+    /** Provide an existing admin Firestore instance… */
+    db?: Firestore;
+    /** …or service-account credentials to initialize firebase-admin lazily. */
+    credentials?: {
+        projectId?: string;
+        clientEmail?: string;
+        privateKey?: string;
+        databaseURL?: string;
+    };
+    /** Field used for default ordering when no query is given. Default `createdAt`. */
+    defaultOrderByField?: string;
+}
+declare class FirestoreDataAdapter implements DataAdapter {
+    private readonly db;
+    private readonly defaultOrderByField;
+    constructor(config?: FirestoreAdapterConfig);
+    private buildQuery;
+    fetchCollection<T = Record<string, unknown>>(collection: string, q?: Query): Promise<(T & {
+        id: string;
+    })[]>;
+    fetchById<T = Record<string, unknown>>(collection: string, id: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    create<T = Record<string, unknown>>(collection: string, data: T): Promise<T & {
+        id: string;
+    }>;
+    createWithId<T = Record<string, unknown>>(collection: string, id: string, data: T): Promise<T & {
+        id: string;
+    }>;
+    update<T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>): Promise<void>;
+    upsert<T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>): Promise<void>;
+    delete(collection: string, id: string): Promise<void>;
+}
+
+export { type FirestoreAdapterConfig, FirestoreDataAdapter };

package/dist/adapters/firestore/index.js

@@ -0,0 +1,120 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+
+// src/adapters/firestore/index.ts
+import admin from "firebase-admin";
+var OP_MAP = {
+  eq: "==",
+  lt: "<",
+  lte: "<=",
+  gt: ">",
+  gte: ">=",
+  in: "in"
+};
+function serialize(data) {
+  if (Array.isArray(data)) {
+    return data.map(serialize);
+  }
+  if (data && typeof data === "object") {
+    const obj = data;
+    if ("_seconds" in obj && "_nanoseconds" in obj) {
+      return new Date(
+        obj._seconds * 1e3 + obj._nanoseconds / 1e6
+      ).toISOString();
+    }
+    if (typeof obj.toDate === "function") {
+      return obj.toDate().toISOString();
+    }
+    const out = {};
+    for (const key in obj) out[key] = serialize(obj[key]);
+    return out;
+  }
+  return data;
+}
+var FirestoreDataAdapter = class {
+  constructor(config = {}) {
+    var _a, _b;
+    this.defaultOrderByField = (_a = config.defaultOrderByField) != null ? _a : "createdAt";
+    if (config.db) {
+      this.db = config.db;
+      return;
+    }
+    if (!admin.apps.length) {
+      const c = (_b = config.credentials) != null ? _b : {};
+      admin.initializeApp({
+        credential: admin.credential.cert({
+          projectId: c.projectId,
+          clientEmail: c.clientEmail,
+          privateKey: c.privateKey
+        }),
+        databaseURL: c.databaseURL
+      });
+    }
+    this.db = admin.firestore();
+  }
+  buildQuery(collection, q) {
+    var _a, _b;
+    let ref = this.db.collection(collection);
+    if (!q) {
+      return ref.orderBy(this.defaultOrderByField, "desc");
+    }
+    for (const f of (_a = q.filters) != null ? _a : []) {
+      ref = ref.where(f.field, OP_MAP[f.op], f.value);
+    }
+    for (const o of (_b = q.orderBy) != null ? _b : []) {
+      ref = ref.orderBy(o.field, o.direction);
+    }
+    if (q.limit != null) ref = ref.limit(q.limit);
+    return ref;
+  }
+  async fetchCollection(collection, q) {
+    const snap = await this.buildQuery(collection, q).get();
+    return snap.docs.map(
+      (doc) => serialize(__spreadValues({ id: doc.id }, doc.data()))
+    );
+  }
+  async fetchById(collection, id) {
+    const doc = await this.db.collection(collection).doc(id).get();
+    if (!doc.exists) return null;
+    return serialize(__spreadValues({ id: doc.id }, doc.data()));
+  }
+  async create(collection, data) {
+    const ref = this.db.collection(collection).doc();
+    await ref.set(__spreadProps(__spreadValues({}, data), { createdAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() }));
+    return __spreadValues({ id: ref.id }, data);
+  }
+  async createWithId(collection, id, data) {
+    await this.db.collection(collection).doc(id).set(__spreadProps(__spreadValues({}, data), { createdAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() }));
+    return __spreadValues({ id }, data);
+  }
+  async update(collection, id, data) {
+    await this.db.collection(collection).doc(id).update(__spreadProps(__spreadValues({}, data), { updatedAt: /* @__PURE__ */ new Date() }));
+  }
+  async upsert(collection, id, data) {
+    await this.db.collection(collection).doc(id).set(__spreadProps(__spreadValues({}, data), { updatedAt: /* @__PURE__ */ new Date() }), { merge: true });
+  }
+  async delete(collection, id) {
+    await this.db.collection(collection).doc(id).delete();
+  }
+};
+export {
+  FirestoreDataAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/firestore/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/firestore/index.ts"],"sourcesContent":["import admin from \"firebase-admin\";\nimport type {\n  Firestore,\n  Query as FirestoreQuery,\n  WhereFilterOp,\n} from \"firebase-admin/firestore\";\nimport type { DataAdapter, Query, QueryFilterOp } from \"../../types\";\n\nexport interface FirestoreAdapterConfig {\n  /** Provide an existing admin Firestore instance… */\n  db?: Firestore;\n  /** …or service-account credentials to initialize firebase-admin lazily. */\n  credentials?: {\n    projectId?: string;\n    clientEmail?: string;\n    privateKey?: string;\n    databaseURL?: string;\n  };\n  /** Field used for default ordering when no query is given. Default `createdAt`. */\n  defaultOrderByField?: string;\n}\n\nconst OP_MAP: Record<QueryFilterOp, WhereFilterOp> = {\n  eq: \"==\",\n  lt: \"<\",\n  lte: \"<=\",\n  gt: \">\",\n  gte: \">=\",\n  in: \"in\",\n};\n\n/** Firestore Timestamps → ISO strings, recursively, so the API returns plain JSON. */\nfunction serialize<T>(data: T): T {\n  if (Array.isArray(data)) {\n    return data.map(serialize) as unknown as T;\n  }\n  if (data && typeof data === \"object\") {\n    const obj = data as Record<string, unknown>;\n    if (\"_seconds\" in obj && \"_nanoseconds\" in obj) {\n      return new Date(\n        (obj._seconds as number) * 1000 + (obj._nanoseconds as number) / 1e6,\n      ).toISOString() as unknown as T;\n    }\n    if (typeof (obj as { toDate?: unknown }).toDate === \"function\") {\n      return (obj as { toDate: () => Date }).toDate().toISOString() as unknown as T;\n    }\n    const out: Record<string, unknown> = {};\n    for (const key in obj) out[key] = serialize(obj[key]);\n    return out as T;\n  }\n  return data;\n}\n\nexport class FirestoreDataAdapter implements DataAdapter {\n  private readonly db: Firestore;\n  private readonly defaultOrderByField: string;\n\n  constructor(config: FirestoreAdapterConfig = {}) {\n    this.defaultOrderByField = config.defaultOrderByField ?? \"createdAt\";\n\n    if (config.db) {\n      this.db = config.db;\n      return;\n    }\n\n    if (!admin.apps.length) {\n      const c = config.credentials ?? {};\n      admin.initializeApp({\n        credential: admin.credential.cert({\n          projectId: c.projectId,\n          clientEmail: c.clientEmail,\n          privateKey: c.privateKey,\n        }),\n        databaseURL: c.databaseURL,\n      });\n    }\n    this.db = admin.firestore();\n  }\n\n  private buildQuery(collection: string, q?: Query): FirestoreQuery {\n    let ref: FirestoreQuery = this.db.collection(collection);\n\n    if (!q) {\n      return ref.orderBy(this.defaultOrderByField, \"desc\");\n    }\n\n    for (const f of q.filters ?? []) {\n      ref = ref.where(f.field, OP_MAP[f.op], f.value);\n    }\n    for (const o of q.orderBy ?? []) {\n      ref = ref.orderBy(o.field, o.direction);\n    }\n    if (q.limit != null) ref = ref.limit(q.limit);\n    return ref;\n  }\n\n  async fetchCollection<T = Record<string, unknown>>(\n    collection: string,\n    q?: Query,\n  ): Promise<(T & { id: string })[]> {\n    const snap = await this.buildQuery(collection, q).get();\n    return snap.docs.map((doc) =>\n      serialize({ id: doc.id, ...(doc.data() as T) }),\n    );\n  }\n\n  async fetchById<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n  ): Promise<(T & { id: string }) | null> {\n    const doc = await this.db.collection(collection).doc(id).get();\n    if (!doc.exists) return null;\n    return serialize({ id: doc.id, ...(doc.data() as T) });\n  }\n\n  async create<T = Record<string, unknown>>(\n    collection: string,\n    data: T,\n  ): Promise<T & { id: string }> {\n    const ref = this.db.collection(collection).doc();\n    await ref.set({ ...data, createdAt: new Date(), updatedAt: new Date() });\n    return { id: ref.id, ...(data as T) };\n  }\n\n  async createWithId<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: T,\n  ): Promise<T & { id: string }> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .set({ ...data, createdAt: new Date(), updatedAt: new Date() });\n    return { id, ...(data as T) };\n  }\n\n  async update<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .update({ ...data, updatedAt: new Date() });\n  }\n\n  async upsert<T = Record<string, unknown>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void> {\n    await this.db\n      .collection(collection)\n      .doc(id)\n      .set({ ...data, updatedAt: new Date() }, { merge: true });\n  }\n\n  async delete(collection: string, id: string): Promise<void> {\n    await this.db.collection(collection).doc(id).delete();\n  }\n}\n"],"mappings":"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","names":[]}