@dalgoridim/headless-cms 0.4.0 → 0.5.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/types.ts"],"sourcesContent":["// Root entry — shared types only. No runtime; safe to import anywhere.\nexport * from \"./types\";\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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACuGO,SAAS,cAAc,GAA0C;AACtE,SAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,QAAQ;AACxD;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/types.ts"],"sourcesContent":["// Root entry — shared types only. No runtime; safe to import anywhere.\nexport * from \"./types\";\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 * A single item in an editable collection list (e.g. a project or a tool). Just\n * a record with a stable `id`. Used by the client provider's collection ops\n * (create / delete / reorder) which manage *which* items exist and their order,\n * complementing {@link Section}s which manage a single item's editable fields.\n */\nexport type CollectionItem = Record<string, unknown> & { id: string };\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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+GO,SAAS,cAAc,GAA0C;AACtE,SAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,QAAQ;AACxD;","names":[]}

package/dist/index.d.cts

@@ -34,6 +34,15 @@ type NestedSections = {
         [sectionKey: string]: Section;
     };
 };
+/**
+ * A single item in an editable collection list (e.g. a project or a tool). Just
+ * a record with a stable `id`. Used by the client provider's collection ops
+ * (create / delete / reorder) which manage *which* items exist and their order,
+ * complementing {@link Section}s which manage a single item's editable fields.
+ */
+type CollectionItem = Record<string, unknown> & {
+    id: string;
+};
 /**
  * An image edit queued in the provider. The actual upload is deferred until
  * save. `file` is null when the user pasted an external URL (`isExternal`).
@@ -184,4 +193,4 @@ interface CmsAuthState {
     toggleEdit: () => void;
 }
 
-export { type AuthAdapter, type AuthIdentity, type AuthorizeFn, type ClientStorageAdapter, type CmsAuthState, type DataAdapter, type Editable, type EntityAddress, type NestedSections, type PendingImage, type Query, type QueryCondition, type QueryFilter, type QueryFilterGroup, type QueryFilterOp, type Ref, type RelationConfig, type Section, type SectionMap, type ServerStorageAdapter, type StorageAdapter, isFilterGroup };
+export { type AuthAdapter, type AuthIdentity, type AuthorizeFn, type ClientStorageAdapter, type CmsAuthState, type CollectionItem, type DataAdapter, type Editable, type EntityAddress, type NestedSections, type PendingImage, type Query, type QueryCondition, type QueryFilter, type QueryFilterGroup, type QueryFilterOp, type Ref, type RelationConfig, type Section, type SectionMap, type ServerStorageAdapter, type StorageAdapter, isFilterGroup };

package/dist/index.d.ts

@@ -34,6 +34,15 @@ type NestedSections = {
         [sectionKey: string]: Section;
     };
 };
+/**
+ * A single item in an editable collection list (e.g. a project or a tool). Just
+ * a record with a stable `id`. Used by the client provider's collection ops
+ * (create / delete / reorder) which manage *which* items exist and their order,
+ * complementing {@link Section}s which manage a single item's editable fields.
+ */
+type CollectionItem = Record<string, unknown> & {
+    id: string;
+};
 /**
  * An image edit queued in the provider. The actual upload is deferred until
  * save. `file` is null when the user pasted an external URL (`isExternal`).
@@ -184,4 +193,4 @@ interface CmsAuthState {
     toggleEdit: () => void;
 }
 
-export { type AuthAdapter, type AuthIdentity, type AuthorizeFn, type ClientStorageAdapter, type CmsAuthState, type DataAdapter, type Editable, type EntityAddress, type NestedSections, type PendingImage, type Query, type QueryCondition, type QueryFilter, type QueryFilterGroup, type QueryFilterOp, type Ref, type RelationConfig, type Section, type SectionMap, type ServerStorageAdapter, type StorageAdapter, isFilterGroup };
+export { type AuthAdapter, type AuthIdentity, type AuthorizeFn, type ClientStorageAdapter, type CmsAuthState, type CollectionItem, type DataAdapter, type Editable, type EntityAddress, type NestedSections, type PendingImage, type Query, type QueryCondition, type QueryFilter, type QueryFilterGroup, type QueryFilterOp, type Ref, type RelationConfig, type Section, type SectionMap, type ServerStorageAdapter, type StorageAdapter, isFilterGroup };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\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":";AAuGO,SAAS,cAAc,GAA0C;AACtE,SAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,QAAQ;AACxD;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\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 * A single item in an editable collection list (e.g. a project or a tool). Just\n * a record with a stable `id`. Used by the client provider's collection ops\n * (create / delete / reorder) which manage *which* items exist and their order,\n * complementing {@link Section}s which manage a single item's editable fields.\n */\nexport type CollectionItem = Record<string, unknown> & { id: string };\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":";AA+GO,SAAS,cAAc,GAA0C;AACtE,SAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,QAAQ;AACxD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalgoridim/headless-cms",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Database-agnostic, inline-edit headless CMS engine for React / Next.js apps",
   "license": "UNLICENSED",
   "author": "dalgoridim",