@dalgoridim/headless-cms 0.1.0 → 0.2.1

package/ARCHITECTURE.md

@@ -0,0 +1,125 @@
+# Architecture & design notes
+
+Core/internal documentation for `@dalgoridim/headless-cms`. For consumer usage,
+see the [README](./README.md).
+
+## Philosophy: harness, not framework
+
+The package wires **behavior** and imposes nothing else. Concretely:
+
+- **Zero runtime dependencies.** No CSS framework, icon set, toast library, or
+  markdown renderer is bundled. Anything visual or opinionated is the consumer's.
+- **The UI primitives are headless.** They manage `contentEditable`, uploads,
+  saves, and edit state, and expose that state (via `data-*` attributes,
+  render-props, and hooks) so the consumer owns 100% of the markup.
+- **The store is schemaless.** The engine only ever adds an `id` and `collection`
+  for addressing; your content type `T` is never forced to declare them
+  (`Editable<T> = T & { id; collection }`).
+
+This is a deliberate reaction to the original extraction, where the components
+shipped a finished, portfolio-specific look (Tailwind + a dark palette + a
+`primary` token + a bespoke markup syntax). Adopting the package then meant
+inheriting that design. The redesign split **behavior (package)** from
+**appearance (consumer)**.
+
+## Two layers
+
+| Layer | Responsibility | Freedom |
+|---|---|---|
+| **Data / server** | CRUD, the neutral `Query`, auth gating, storage signing | Schemaless; adapters are generic over `T` |
+| **UI / client** | inline-edit behavior, save buffering, upload flow | Headless; consumer supplies all styling/markup |
+
+## Subpath exports & the client/server bundle boundary
+
+Server-only SDKs must never reach the client bundle. Two mechanisms enforce this:
+
+1. **Split entries per concern.** Each storage adapter is two modules:
+   - `storage/<x>` — the **client** half (`upload`), pure `fetch`, safe in client
+     components.
+   - `storage/<x>/server` — the **server** half (`sign`), pulls in the SDK.
+
+   This split exists because a single module that *also* contained a lazy
+   `import("cloudinary")` still got traced into the client bundle by
+   Next/Turbopack → `Can't resolve 'fs'`. Splitting the entry removes the trace
+   entirely.
+
+2. **Auth/data adapters live behind `/server`, `/adapters/*`, `/auth/*`** so a
+   client import can never transitively pull a Node-only SDK.
+
+## One React context across entries
+
+The built-in auth providers (e.g. `auth/firebase/client`) import
+`CmsAuthProvider` through the package's **public** `@dalgoridim/headless-cms/client`
+specifier — not a relative path — so the provider and the consumer's primitives
+share the **same** context instance at runtime. This is enforced with a tsup
+`external` regex (`/^@dalgoridim\/headless-cms(\/.*)?$/`) plus `tsconfig` paths.
+Using a relative import here would create a second context instance and silently
+break `useCmsAuth`.
+
+## The neutral Query & backend parity
+
+`Query` is intentionally backend-agnostic so no native query type (Firestore's
+`Query`, raw SQL) leaks through the engine. Not every backend can honor every
+operator; rather than return wrong results, an adapter **throws** on what it
+cannot do.
+
+| Capability | Postgres | Firestore |
+|---|:--:|:--:|
+| `eq` `ne` `lt` `lte` `gt` `gte` | ✅ | ✅ |
+| `in` / `nin` | ✅ | ✅ |
+| `contains` (case-insensitive substring) | ✅ (`ILIKE`) | ❌ throws (no native substring) |
+| `{ or: [...] }` groups | ✅ | ❌ throws |
+| `offset` pagination | ✅ | ✅ |
+
+## Hybrid Postgres adapter
+
+Two storage strategies under one adapter:
+
+- **Unregistered collections** → a shared JSONB `documents` table, keyed by a
+  composite `PRIMARY KEY (collection, id)` (global `id` PKs collided across
+  collections — e.g. `project/1`, `skill/1`). Fully schemaless, zero config.
+- **Registered collections** → flat fields mapped onto typed columns, **plus** a
+  JSONB `extra` column so unmapped fields are never dropped.
+
+Notable details:
+
+- `ON CONFLICT DO UPDATE` for typed-table upsert qualifies `extra` as
+  `<table>.extra` — a bare `extra` is ambiguous between the target table and the
+  `excluded` pseudo-relation.
+- **Caveat:** JSONB fields are extracted as **text** (`data->>'field'`), so
+  numeric ordering/comparison in the schemaless table is lexicographic
+  (`"10" < "5"`). Register the collection with a typed `int`/`float` column for
+  true numeric behavior.
+
+## Relations
+
+References are plain field values — a self-describing `{ collection, id }`, a bare
+id string, or an array of either. `resolveRelations(adapter, docs, opts)` runs
+**engine-side** (never in an adapter) so it works identically over Postgres,
+Firestore, or any custom `DataAdapter`. Loads are deduplicated (one `fetchById`
+per unique `(collection, id)`) and parallelized; unresolved refs are left
+untouched.
+
+## Auth model
+
+`AuthIdentity` is minimal and open: only `isAdmin` is meaningful to the default
+gate; carry any other claims (roles, scopes, tenant) as extra keys. The gate
+authorizes via an injectable `AuthorizeFn` (`(identity, req) => boolean`),
+defaulting to `identity.isAdmin === true`. This lets a consumer gate on anything
+without the package prescribing an identity shape.
+
+## Headless UI internals
+
+- **`ContentEditSpan`** — wires `contentEditable`, persists on blur, and emits
+  `data-cms-editable` / `data-cms-editing` / `data-cms-focused`. Rich-text
+  rendering is injected via `renderValue(raw) => ReactNode` (default: plain text).
+- **`EditableImage`** — owns the file input, object-URL previews, external-URL
+  validation, and the pending-upload queue; hands all state to a render-prop.
+- **`useMarkdownEditor`** — value state + a selection-aware `insert` command +
+  save/reset, with no UI. (The reference app skins it with `@uiw/react-md-editor`.)
+
+## Build
+
+`tsup` produces ESM + CJS + `.d.ts` per subpath entry, with every backend SDK and
+the package's own specifier marked `external`. `files: ["dist"]` (plus the
+markdown docs) controls what ships to npm.

package/README.md

@@ -1,24 +1,35 @@
 # @dalgoridim/headless-cms
 
-Database-agnostic, inline-edit headless CMS engine for React / Next.js apps.
+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.
+Content lives in *your* database and is editable **inline on the live site** by an
+authenticated admin. Persistence, auth, and storage are fully pluggable — swap
+Firestore for Postgres, Cloudinary for S3, Firebase auth for NextAuth, without
+touching your UI.
+
+**Harness, not framework.** Zero runtime dependencies; the editing components are
+headless (you own all markup and styling); your content shape stays unconstrained.
+You build a thin skin over the primitives (see [Styling](#styling-bring-your-own-look)) —
+the package never pushes a look onto your site. The design rationale and internals
+live in [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+**Live example:** [dalgoridim.com](https://dalgoridim.com) runs on this package.
+Try it: anyone can toggle edit mode and change the content inline, right on the
+page — but saves are gated, so only the authenticated owner's edits actually
+persist. Your changes are yours alone to play with.
 
 ## Install
 
 ```bash
 npm install @dalgoridim/headless-cms
-# plus the adapters you actually use, e.g.:
+# plus only the adapters you actually use:
 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.
+install only what your chosen adapters need.
 
 ## Subpath exports
 
@@ -27,31 +38,32 @@ 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` |
+| `.../client` | `PageProvider`, `usePageContext`, `ContentEditSpan`, `EditableImage`, `useMarkdownEditor`, `CmsAuthProvider`, `useCmsAuth` |
+| `.../server` | `createCmsHandlers`, `createAdminGate`, `resolveRelations` |
 | `.../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 |
+| `.../storage/{cloudinary,s3,local}` | **Client** upload adapters — pure `fetch`, safe in client components |
+| `.../storage/{cloudinary,s3,local}/server` | **Server** signers — pull in SDKs, server-only |
 | `.../auth/firebase` | `firebaseAuth` (server gate) |
 | `.../auth/firebase/client` | `FirebaseAuthProvider`, `useFirebaseAuth` |
 | `.../auth/nextauth` | `nextAuthAuth`, `customAuth` |
 
-## The three core interfaces
+## 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
+- **`DataAdapter`** — backend CRUD over a neutral [`Query`](#the-query-language).
+- **`AuthAdapter`** — `verifyRequest(req)` resolves an identity; the gate decides
+  ([auth](#auth-the-gate-is-yours)).
+- **Storage** is split in two 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)
+## Quick start (Next.js App Router)
 
-**1. The admin CRUD route** — replaces a hand-written handler:
+### 1. Admin CRUD route
 
 ```ts
 // app/api/admin/[collection]/[id]/route.ts
@@ -71,7 +83,7 @@ export const { GET, PATCH, PUT, DELETE } = createCmsHandlers({
 });
 ```
 
-**2. The storage sign route** — uses the **server** signer:
+### 2. Storage sign route (server signer)
 
 ```ts
 // app/api/admin/sign/route.ts
@@ -90,16 +102,15 @@ export const POST = createCmsHandlers({
 }).sign;
 ```
 
-**3. Providers + editable content** (client):
+### 3. Providers (client)
 
 ```tsx
 "use client";
-import { PageProvider, ContentEditSpan, EditableImage } from "@dalgoridim/headless-cms/client";
+import { PageProvider } 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 }) {
@@ -111,18 +122,156 @@ export function Providers({ initialSections, children }) {
     </FirebaseAuthProvider>
   );
 }
+```
+
+`PageProvider` saves `PATCH ${apiBasePath}/{collection}/{id}` (default `apiBasePath`
+= `/api/admin`). Edit mode is driven by `useCmsAuth().isEditing`, which the auth
+providers feed. Pass `notify` to surface your own toasts — the default logs to the
+console so the package carries no toast dependency.
+
+## The editing primitives (headless)
 
-// Anywhere inside:
-<ContentEditSpan collection="portfolio" sectionKey="hero" fieldKey="title" as="h1">
+### `ContentEditSpan` — inline-editable text
+
+Wires `contentEditable`, reads/writes the field, and exposes edit state via
+`data-*` attributes. It ships **no styling and no markup language** — supply your
+own via `className` and `renderValue`.
+
+```tsx
+import { ContentEditSpan } from "@dalgoridim/headless-cms/client";
+
+<ContentEditSpan
+  collection="pages"
+  sectionKey="hero"
+  fieldKey="title"
+  as="h1"                       // any element/tag; defaults to "span"
+  renderValue={(raw) => raw}    // turn the stored string into nodes (default: plain text)
+  className="my-heading"
+>
   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.
+State is exposed as attributes so you can style with plain CSS (or Tailwind
+`data-[...]` variants):
+
+| Attribute | Present when |
+|---|---|
+| `data-cms-editable` | always (the primitive is mounted) |
+| `data-cms-editing` | the current user is in edit mode |
+| `data-cms-focused` | the field is actively being edited |
+
+```css
+[data-cms-focused] { outline: 2px solid var(--accent); border-radius: 4px; }
+[data-cms-editing]:hover { outline: 1px dashed var(--accent); cursor: text; }
+```
+
+Want rich text? Pass a `renderValue` that parses your own syntax (markdown, a
+custom mini-language, etc.) into React nodes — the package no longer dictates one.
+
+### `EditableImage` — upload / external-URL via render-prop
+
+Manages file picking, object URLs, external-URL validation, and the pending-upload
+queue. You render the chrome:
+
+```tsx
+import { EditableImage } from "@dalgoridim/headless-cms/client";
+
+<EditableImage collection="pages" sectionKey="hero" fieldKey="image"
+  docId="hero" src={section.image}>
+  {({ isEditing, saving, hasError, openFilePicker, setExternalUrl, imgProps }) => (
+    <div className="relative">
+      <img {...imgProps} alt="" />
+      {isEditing && (
+        <button onClick={openFilePicker} disabled={saving}>Replace</button>
+      )}
+    </div>
+  )}
+</EditableImage>
+```
+
+Omit the render-prop child and it falls back to a bare unstyled `<img>`.
+
+### `useMarkdownEditor` — headless markdown editing
+
+State + a selection-aware `insert` command. Bring your own modal, toolbar, icons,
+and preview (e.g. `react-markdown`):
+
+```tsx
+import { useMarkdownEditor } from "@dalgoridim/headless-cms/client";
+
+function Editor({ initialValue, onSave }) {
+  const md = useMarkdownEditor({ initialValue, onSave });
+  return (
+    <>
+      <button onClick={() => md.insert("**", "**", "bold")}>Bold</button>
+      <textarea ref={md.textareaRef} value={md.value}
+        onChange={(e) => md.setValue(e.target.value)} />
+      <span>{md.charCount} chars</span>
+      <button onClick={md.save}>Save</button>
+    </>
+  );
+}
+```
+
+## The Query language
+
+A neutral, backend-agnostic query passed to `DataAdapter.fetchCollection`:
+
+```ts
+type Query = {
+  filters?: (QueryFilter | { or: QueryFilter[] })[];   // top level AND; groups OR
+  orderBy?: { field: string; direction: "asc" | "desc" }[];
+  limit?: number;
+  offset?: number;
+  populate?: string[];   // reference fields to inline-resolve (see Relations)
+};
+```
+
+**Operators** (`QueryFilter = { field, op, value }`):
+
+| op | meaning | Postgres | Firestore |
+|---|---|:--:|:--:|
+| `eq` / `ne` | equals / not equals | ✅ | ✅ |
+| `lt` `lte` `gt` `gte` | comparisons | ✅ | ✅ |
+| `in` / `nin` | value in / not in array | ✅ | ✅ |
+| `contains` | case-insensitive substring | ✅ | ❌ throws |
+| `{ or: [...] }` | disjunction | ✅ | ❌ throws |
+
+Where a backend can't honor an op, it throws a clear error rather than returning
+wrong results.
+
+```ts
+await data.fetchCollection("posts", {
+  filters: [
+    { field: "title", op: "contains", value: "hello" },
+    { or: [{ field: "tag", op: "eq", value: "react" },
+           { field: "tag", op: "eq", value: "sql" }] },
+  ],
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+  limit: 20,
+  offset: 40,
+});
+```
+
+## Relations
+
+References are just fields — a self-describing `{ collection, id }`, a bare id
+string, or an array of either. Resolve them after a fetch with `resolveRelations`
+(engine-side, works over any adapter):
+
+```ts
+import { resolveRelations } from "@dalgoridim/headless-cms/server";
+
+const posts = await data.fetchCollection("posts");
+await resolveRelations(data, posts, {
+  populate: ["authorId"],
+  relations: { authorId: { collection: "authors" } }, // needed for bare-id refs
+});
+// each post.authorId is now the resolved author document
+```
+
+Loads are deduplicated and parallelized; unresolved refs are left untouched.
 
 ## Postgres (hybrid)
 
@@ -136,35 +285,80 @@ 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" } },
+    projects: { table: "projects", columns: { title: "text", views: "int", date: "date" } },
   },
 });
 await data.migrate(); // creates documents + registered tables if missing
 ```
 
-## Content markup
+> **Caveat:** fields in the schemaless JSONB `documents` table are extracted as
+> **text**, so numeric ordering/comparison is lexicographic (`"10" < "5"`).
+> Register the collection with a typed `int`/`float` column for true numeric
+> behavior.
 
-`ContentEditSpan` supports inline marks: `**bold**`, `*italic*`, `~~strike~~`,
-`^^primary color^^`, `__underline__`, `~~br~~`, and `[label](https://url)`.
-`MarkdownEditor` provides full GitHub-flavored markdown editing.
+## Auth: the gate is yours
 
-## Styling
+`AuthIdentity` is intentionally minimal and open — only `isAdmin` is meaningful to
+the default gate; carry any other claims and authorize on them yourself.
 
-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:
+```ts
+interface AuthIdentity {
+  isAdmin: boolean;
+  userId?: string;
+  email?: string;
+  [claim: string]: unknown;   // roles, scopes, tenant, …
+}
+```
 
-```css
-/* globals.css */
-@import "tailwindcss";
-@source "../node_modules/@dalgoridim/headless-cms/dist";
+Pass an `authorize` predicate to gate on whatever you like (defaults to
+`identity.isAdmin === true`):
 
-@theme inline {
-  --color-primary: var(--primary);
-}
+```ts
+createCmsHandlers({
+  data,
+  auth,
+  authorize: (identity) => identity.role === "editor" || identity.isAdmin,
+});
+```
+
+## Your content types stay unconstrained
+
+The engine only adds addressing fields; your domain type `T` is never forced to
+declare them:
+
+```ts
+import type { Editable } from "@dalgoridim/headless-cms";
+
+interface Post { title: string; body: string }   // your shape — clean
+type StoredPost = Editable<Post>;                 // Post & { id: string; collection: string }
 ```
 
+## Styling: bring your own look
+
+The package ships **no styles**. Skin the primitives in your app — for example, a
+thin wrapper that applies your design system:
+
+```tsx
+// components/EditableTitle.tsx
+import { ContentEditSpan } from "@dalgoridim/headless-cms/client";
+
+export const EditableTitle = (props) => (
+  <ContentEditSpan
+    {...props}
+    className="text-4xl font-bold data-[cms-focused]:ring-2 data-[cms-focused]:ring-blue-500"
+  />
+);
+```
+
+This keeps your design isolated from the engine and lets the package upgrade
+without ever changing how your site looks.
+
+## Documentation
+
+- **[README](./README.md)** — this guide: install and usage.
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — design rationale and internals
+  (bundle boundaries, backend parity, the hybrid Postgres model, headless UI).
+
 ## Build
 
 ```bash
@@ -174,5 +368,5 @@ 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.
+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

@@ -51,13 +51,22 @@ __export(firestore_exports, {
 });
 module.exports = __toCommonJS(firestore_exports);
 var import_firebase_admin = __toESM(require("firebase-admin"), 1);
+
+// src/types.ts
+function isFilterGroup(c) {
+  return typeof c === "object" && c !== null && "or" in c;
+}
+
+// src/adapters/firestore/index.ts
 var OP_MAP = {
   eq: "==",
+  ne: "!=",
   lt: "<",
   lte: "<=",
   gt: ">",
   gte: ">=",
-  in: "in"
+  in: "in",
+  nin: "not-in"
 };
 function serialize(data) {
   if (Array.isArray(data)) {
@@ -106,12 +115,24 @@ var FirestoreDataAdapter = class {
     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 c of (_a = q.filters) != null ? _a : []) {
+      if (isFilterGroup(c)) {
+        throw new Error(
+          "FirestoreDataAdapter does not support OR filter groups. Use a backend with richer query support (e.g. Postgres) or split into separate reads."
+        );
+      }
+      const op = OP_MAP[c.op];
+      if (!op) {
+        throw new Error(
+          `FirestoreDataAdapter does not support the '${c.op}' operator` + (c.op === "contains" ? " (no native substring search)." : ".")
+        );
+      }
+      ref = ref.where(c.field, op, c.value);
     }
     for (const o of (_b = q.orderBy) != null ? _b : []) {
       ref = ref.orderBy(o.field, o.direction);
     }
+    if (q.offset != null) ref = ref.offset(q.offset);
     if (q.limit != null) ref = ref.limit(q.limit);
     return ref;
   }

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

@@ -1 +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"]}
+{"version":3,"sources":["../../../src/adapters/firestore/index.ts","../../../src/types.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\";\nimport { isFilterGroup } 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\n/**\n * Ops Firestore can honor natively. `contains` (substring search) has no\n * Firestore equivalent and is intentionally absent — using it throws.\n */\nconst OP_MAP: Partial<Record<QueryFilterOp, WhereFilterOp>> = {\n  eq: \"==\",\n  ne: \"!=\",\n  lt: \"<\",\n  lte: \"<=\",\n  gt: \">\",\n  gte: \">=\",\n  in: \"in\",\n  nin: \"not-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 c of q.filters ?? []) {\n      if (isFilterGroup(c)) {\n        throw new Error(\n          \"FirestoreDataAdapter does not support OR filter groups. Use a backend \" +\n            \"with richer query support (e.g. Postgres) or split into separate reads.\",\n        );\n      }\n      const op = OP_MAP[c.op];\n      if (!op) {\n        throw new Error(\n          `FirestoreDataAdapter does not support the '${c.op}' operator` +\n            (c.op === \"contains\" ? \" (no native substring search).\" : \".\"),\n        );\n      }\n      ref = ref.where(c.field, op, c.value);\n    }\n    for (const o of q.orderBy ?? []) {\n      ref = ref.orderBy(o.field, o.direction);\n    }\n    if (q.offset != null) ref = ref.offset(q.offset);\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","/**\n * Shared, runtime-free types. Safe to import in any environment (client or\n * server) — this module pulls in zero runtime dependencies.\n */\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/**\n * Engine addressing fields. The engine needs to know an entity's `id` and which\n * `collection` it lives in to route saves; everything else is the consumer's own\n * shape. Kept separate from the user's content type `T` so we never force these\n * onto domain models — use {@link Editable}<YourType> when you want both.\n */\nexport interface EntityAddress {\n  id: string;\n  collection: string;\n}\n\n/**\n * The user's content type `T` decorated with the engine's addressing fields.\n * `T` is completely unconstrained — bring any shape; the engine only adds `id`\n * and `collection`.\n */\nexport type Editable<T = Record<string, any>> = T & EntityAddress;\n\n/**\n * A single editable record. Schemaless by design. Equivalent to\n * `Editable<Record<string, any>>`; kept as a named alias for the common case and\n * for backwards compatibility.\n */\nexport type Section = Editable;\n\nexport type SectionMap = Record<string, Section>;\n\n/**\n * The shape the engine holds in memory:\n * `{ [collection]: { [sectionKey]: Section } }`.\n */\nexport type NestedSections = {\n  [collection: string]: {\n    [sectionKey: string]: Section;\n  };\n};\n\n/**\n * An image edit queued in the provider. The actual upload is deferred until\n * save. `file` is null when the user pasted an external URL (`isExternal`).\n */\nexport interface PendingImage {\n  file: File | null;\n  localUrl: string;\n  sectionKey: string;\n  fieldKey: string;\n  collection: string;\n  docId: string;\n  isExternal?: boolean;\n}\n\n/**\n * Neutral query language. Keeps any backend's native query type (Firestore's\n * `Query`, SQL, etc.) from leaking through the engine.\n *\n * Op support is backend-dependent — see each adapter. `contains` is a\n * case-insensitive substring match; `in`/`nin` take an array value.\n */\nexport type QueryFilterOp =\n  | \"eq\"\n  | \"ne\"\n  | \"lt\"\n  | \"lte\"\n  | \"gt\"\n  | \"gte\"\n  | \"in\"\n  | \"nin\"\n  | \"contains\";\n\n/** A single field condition. */\nexport type QueryFilter = { field: string; op: QueryFilterOp; value: unknown };\n\n/**\n * A disjunction: the inner filters are combined with OR. Sits alongside plain\n * filters in `Query.filters`, which are combined with AND at the top level.\n */\nexport type QueryFilterGroup = { or: QueryFilter[] };\n\n/** Either a bare condition (AND-ed) or an OR group. */\nexport type QueryCondition = QueryFilter | QueryFilterGroup;\n\nexport type Query = {\n  /** Top-level conditions combined with AND. Use `{ or: [...] }` for disjunction. */\n  filters?: QueryCondition[];\n  orderBy?: { field: string; direction: \"asc\" | \"desc\" }[];\n  limit?: number;\n  /** Skip this many rows (offset pagination). */\n  offset?: number;\n  /**\n   * Fields holding references to other documents to inline-resolve after the\n   * primary fetch. Resolved by {@link resolveRelations}, never by the adapter.\n   */\n  populate?: string[];\n};\n\n/** Narrow a {@link QueryCondition} to an OR group. */\nexport function isFilterGroup(c: QueryCondition): c is QueryFilterGroup {\n  return typeof c === \"object\" && c !== null && \"or\" in c;\n}\n\n/**\n * A reference to another document. Either self-describing (`{ collection, id }`)\n * or a bare id string resolved via a {@link RelationConfig}.\n */\nexport type Ref = { collection: string; id: string };\n\n/**\n * Maps a reference field name → the collection it points to. Needed only when\n * refs are stored as bare id strings (self-describing `Ref` objects don't need\n * it). Used by {@link resolveRelations}.\n */\nexport type RelationConfig = Record<string, { collection: string }>;\n\n/**\n * Persistence contract. Every backend (Firestore, Postgres, …) implements this;\n * the engine and the route factory only ever speak to this interface.\n */\nexport interface DataAdapter {\n  fetchCollection<T = Record<string, any>>(\n    collection: string,\n    q?: Query,\n  ): Promise<(T & { id: string })[]>;\n  fetchById<T = Record<string, any>>(\n    collection: string,\n    id: string,\n  ): Promise<(T & { id: string }) | null>;\n  create<T = Record<string, any>>(\n    collection: string,\n    data: T,\n  ): Promise<T & { id: string }>;\n  createWithId<T = Record<string, any>>(\n    collection: string,\n    id: string,\n    data: T,\n  ): Promise<T & { id: string }>;\n  update<T = Record<string, any>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void>;\n  upsert<T = Record<string, any>>(\n    collection: string,\n    id: string,\n    data: Partial<T>,\n  ): Promise<void>;\n  delete(collection: string, id: string): Promise<void>;\n}\n\n/**\n * The identity resolved from an incoming request by an {@link AuthAdapter}.\n * Minimal by design: only `isAdmin` is meaningful to the default gate. Carry any\n * additional claims (roles, scopes, tenant, …) as extra keys and authorize on\n * them with a custom `authorize` predicate. `userId`/`email` are conventional\n * but optional.\n */\nexport interface AuthIdentity {\n  isAdmin: boolean;\n  userId?: string;\n  email?: string;\n  [claim: string]: unknown;\n}\n\n/**\n * Decides whether a resolved identity may perform admin actions. Defaults to\n * `identity.isAdmin === true`; override to gate on roles/scopes/etc.\n */\nexport type AuthorizeFn = (\n  identity: AuthIdentity,\n  req: Request,\n) => boolean | Promise<boolean>;\n\n/**\n * Server-side auth contract. Gates every admin API route. Return `null` to\n * reject outright; otherwise the gate's `authorize` predicate decides.\n */\nexport interface AuthAdapter {\n  verifyRequest(req: Request): Promise<AuthIdentity | null>;\n}\n\n/**\n * Client half of storage: performs the browser-side upload and returns the\n * final URL. Has zero server dependencies, so it is safe to import in client\n * components. Built from e.g. `@dalgoridim/headless-cms/storage/cloudinary`.\n */\nexport interface ClientStorageAdapter {\n  upload(file: File): Promise<{ url: string }>;\n}\n\n/**\n * Server half of storage: issues a presign / signature (or, for local storage,\n * writes the file). Mounted by the route factory at `${apiBasePath}/sign`.\n * Pulls in server-only SDKs, so it lives in a `/server` subpath. Built from e.g.\n * `@dalgoridim/headless-cms/storage/cloudinary/server`.\n */\nexport interface ServerStorageAdapter {\n  sign(req: Request): Promise<unknown>;\n}\n\n/** Full two-sided contract (rarely needed; client and server halves are split). */\nexport interface StorageAdapter extends ClientStorageAdapter {\n  sign?(req: Request): Promise<unknown>;\n}\n\n/**\n * Minimal client-side auth state the edit primitives depend on. Any auth\n * implementation (Firebase, NextAuth, custom) provides this via a context;\n * `@dalgoridim/headless-cms/auth/firebase/client` ships the default.\n */\nexport interface CmsAuthState {\n  isAdmin: boolean;\n  isEditing: boolean;\n  toggleEdit: () => void;\n}\n"],"mappings":"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","names":["admin"]}

package/dist/adapters/firestore/index.js

@@ -20,13 +20,22 @@ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 
 // src/adapters/firestore/index.ts
 import admin from "firebase-admin";
+
+// src/types.ts
+function isFilterGroup(c) {
+  return typeof c === "object" && c !== null && "or" in c;
+}
+
+// src/adapters/firestore/index.ts
 var OP_MAP = {
   eq: "==",
+  ne: "!=",
   lt: "<",
   lte: "<=",
   gt: ">",
   gte: ">=",
-  in: "in"
+  in: "in",
+  nin: "not-in"
 };
 function serialize(data) {
   if (Array.isArray(data)) {
@@ -75,12 +84,24 @@ var FirestoreDataAdapter = class {
     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 c of (_a = q.filters) != null ? _a : []) {
+      if (isFilterGroup(c)) {
+        throw new Error(
+          "FirestoreDataAdapter does not support OR filter groups. Use a backend with richer query support (e.g. Postgres) or split into separate reads."
+        );
+      }
+      const op = OP_MAP[c.op];
+      if (!op) {
+        throw new Error(
+          `FirestoreDataAdapter does not support the '${c.op}' operator` + (c.op === "contains" ? " (no native substring search)." : ".")
+        );
+      }
+      ref = ref.where(c.field, op, c.value);
     }
     for (const o of (_b = q.orderBy) != null ? _b : []) {
       ref = ref.orderBy(o.field, o.direction);
     }
+    if (q.offset != null) ref = ref.offset(q.offset);
     if (q.limit != null) ref = ref.limit(q.limit);
     return ref;
   }