@lemonadecms/client 0.2.0 → 0.2.1

package/dist/types.d.ts

@@ -3,7 +3,14 @@ export type ModelMap<Models> = {
 };
 export type UntypedModels = Record<string, Record<string, unknown>>;
 export type FieldName<Fields> = Extract<keyof Fields, string>;
-export interface CMSBaseOptions {
+/** Generated reverse names point to source model keys; no relationship data is fetched eagerly. */
+export type RelationshipMap<Models> = {
+    [Model in Extract<keyof Models, string>]?: Record<string, Extract<keyof Models, string>>;
+};
+export type RelationshipName<Relationships, Model extends string> = keyof Relationships extends never ? string : Model extends keyof Relationships ? Extract<keyof Relationships[Model], string> : never;
+export type RelatedModel<Models, Relationships, Model extends string, Relation extends string> = Model extends keyof Relationships ? Relation extends keyof Relationships[Model] ? Extract<Relationships[Model][Relation], Extract<keyof Models, string>> : never : string;
+export type RelatedFields<Models, Relationships, Model extends string, Relation extends string> = RelatedModel<Models, Relationships, Model, Relation> extends keyof Models ? Models[RelatedModel<Models, Relationships, Model, Relation>] : Record<string, unknown>;
+export interface CMSBaseOptions<Models extends ModelMap<Models> = {}> {
     /** Requests always use https://api.lemonadecms.com. Custom CMS hosts are unsupported. */
     url?: never;
     projectId: string;
@@ -14,11 +21,19 @@ export interface CMSBaseOptions {
      * No default deadline. Combining with a caller signal requires AbortSignal.any.
      */
     timeoutMs?: number;
+    /** Explicitly accept opt-in rich-text v2 documents. Defaults to the v1 contract. */
+    richTextVersion?: 1 | 2;
+    /** Query conveniences, never an authorization boundary. Filters combine with AND. */
+    defaults?: keyof Models extends never ? never : CMSQueryDefaults<Models[Extract<keyof Models, string>]>;
+    /** Checked model names and source fields; scalar values override global defaults. */
+    collections?: keyof Models extends never ? never : {
+        [Model in Extract<keyof Models, string>]?: CMSQueryDefaults<Models[Model]>;
+    };
 }
-export interface CMSClientOptions extends CMSBaseOptions {
+export interface CMSClientOptions<Models extends ModelMap<Models> = {}> extends CMSBaseOptions<Models> {
     publicKey: string;
 }
-export interface CMSPreviewOptions extends CMSBaseOptions {
+export interface CMSPreviewOptions<Models extends ModelMap<Models> = {}> extends CMSBaseOptions<Models> {
     secretKey: string;
 }
 type Scalar = string | number | boolean;
@@ -51,6 +66,30 @@ type ChoicesContentFilter<Fields> = {
         value: readonly ChoicesValue<Fields[Key]>[];
     };
 }[ChoicesField<Fields>];
+type ReferenceIdentity = {
+    id: string;
+    url?: never;
+};
+type ReferenceField<Fields, Many extends boolean> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? never : [NonNullable<Fields[Key]>] extends [never] ? never : NonNullable<Fields[Key]> extends (Many extends true ? readonly ReferenceIdentity[] : ReferenceIdentity) ? Key : never;
+}[FieldName<Fields>];
+type ReferenceContentFilter<Fields> = {
+    [Key in ReferenceField<Fields, false>]: {
+        field: Key;
+        op: "eq" | "ne";
+        value: string | null;
+    } | {
+        field: Key;
+        op: "in" | "not_in";
+        value: readonly string[];
+    };
+}[ReferenceField<Fields, false>] | {
+    [Key in ReferenceField<Fields, true>]: {
+        field: Key;
+        op: "contains_any" | "contains_all";
+        value: readonly string[];
+    };
+}[ReferenceField<Fields, true>];
 export type TextField<Fields> = {
     [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends string ? Key : never;
 }[FieldName<Fields>];
@@ -61,7 +100,7 @@ type TextContentFilter<Fields> = {
         value: string;
     };
 }[TextField<Fields>];
-export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | {
+export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | ReferenceContentFilter<Fields> | {
     and: readonly ContentFilter<Fields>[];
 } | {
     or: readonly ContentFilter<Fields>[];
@@ -90,6 +129,14 @@ interface BaseListOptions<Key extends string, Fields> {
     /** Explicit live enrichment, independently cached from the saved publication. */
     includeRemote?: boolean;
 }
+/** Defaults never include projections, cursors, search text or cancellation signals.
+ * ID reads inherit locale/includeRemote only; statistics inherit locale/filters only.
+ * Global fields must be valid on every collection queried with those defaults.
+ */
+export type CMSQueryDefaults<Fields = Record<string, unknown>> = Pick<BaseListOptions<string, Fields>, "locale" | "limit" | "filters" | "sort" | "includeRemote"> & {
+    /** Forward traversal only. Default 1,000; maximum 10,000. */
+    maxPages?: number;
+};
 /** Follow a returned boundary in exactly one direction; or request a numbered page; modes cannot be combined. */
 export type ListOptions<Key extends string = string, Fields = Record<string, unknown>> = BaseListOptions<Key, Fields> & ({
     after?: string;
@@ -170,7 +217,9 @@ export interface ContentPage<Fields, Model extends string = string> {
         hasPreviousPage?: boolean;
     };
 }
-export interface ContentCollection<Fields extends object, Model extends string = string> {
+export interface ContentCollection<Fields extends object, Model extends string = string, Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}> {
+    /** Read one explicitly configured reverse collection; edit its source references in Studio. */
+    related<Relation extends RelationshipName<Relationships, Model>, const Key extends FieldName<RelatedFields<Models, Relationships, Model, Relation>> = FieldName<RelatedFields<Models, Relationships, Model, Relation>>>(id: string, relation: Relation, options?: ListOptions<Key, RelatedFields<Models, Relationships, Model, Relation>>): Promise<ContentPage<Pick<RelatedFields<Models, Relationships, Model, Relation>, Key>, RelatedModel<Models, Relationships, Model, Relation>>>;
     list<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: ListOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
     /** One page of plain text matches; relevance order unless an explicit sort is supplied. */
     search<const Key extends FieldName<Fields> = FieldName<Fields>>(query: string, options?: SearchOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
@@ -190,8 +239,8 @@ export interface ContentCollection<Fields extends object, Model extends string =
     entries<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentEntry<Pick<Fields, Key>, Model>>;
     get<const Key extends FieldName<Fields> = FieldName<Fields>>(id: string, options?: Pick<ListOptions<Key, Fields>, "select" | "locale" | "signal" | "includeRemote">): Promise<ContentEntry<Pick<Fields, Key>, Model>>;
 }
-export interface CMSClient<Models extends ModelMap<Models> = UntypedModels> {
-    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model>;
+export interface CMSClient<Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}> {
+    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model, Models, Relationships>;
 }
 /** A draft may omit required fields or contain nulls until it is published. */
 export type PreviewModels<Models> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemonadecms/client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
   "license": "MIT",
   "homepage": "https://lemonadecms.com/guides/sdk",