@lemonadecms/client 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type ModelMap<Models> = {
 export type UntypedModels = Record<string, Record<string, unknown>>;
 export type FieldName<Fields> = Extract<keyof Fields, string>;
 export interface CMSBaseOptions {
-    /** Requests always use https://lemonadecms.com. Custom CMS hosts are unsupported. */
+    /** Requests always use https://api.lemonadecms.com. Custom CMS hosts are unsupported. */
     url?: never;
     projectId: string;
     /** Compatible transport for SSR, testing or polyfills; receives production URLs. */
@@ -28,11 +28,11 @@ export type ScalarField<Fields> = {
 type ScalarContentFilter<Fields> = {
     [Key in ScalarField<Fields>]: {
         field: Key;
-        op: "eq";
+        op: "eq" | "ne";
         value: Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never) | null;
     } | {
         field: Key;
-        op: "in";
+        op: "in" | "not_in";
         value: readonly (Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never))[];
     } | (NonNullable<Fields[Key]> extends boolean ? never : {
         field: Key;
@@ -51,7 +51,28 @@ type ChoicesContentFilter<Fields> = {
         value: readonly ChoicesValue<Fields[Key]>[];
     };
 }[ChoicesField<Fields>];
-export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields>;
+export type TextField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends string ? Key : never;
+}[FieldName<Fields>];
+type TextContentFilter<Fields> = {
+    [Key in TextField<Fields>]: {
+        field: Key;
+        op: "eqi" | "contains" | "containsi" | "starts_with" | "starts_withi" | "ends_with" | "ends_withi";
+        value: string;
+    };
+}[TextField<Fields>];
+export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | {
+    and: readonly ContentFilter<Fields>[];
+} | {
+    or: readonly ContentFilter<Fields>[];
+} | {
+    not: ContentFilter<Fields>;
+};
+export interface ContentSearch<Fields = Record<string, unknown>> {
+    query: string;
+    /** Top-level text/long_text/markdown fields; the backend validates stored types. */
+    fields?: readonly TextField<Fields>[];
+}
 export interface ContentSort<Fields> {
     field: ScalarField<Fields>;
     direction: "asc" | "desc";
@@ -60,9 +81,11 @@ interface BaseListOptions<Key extends string, Fields> {
     select?: readonly Key[];
     locale?: string;
     limit?: number;
-    /** Up to ten AND clauses, validated against the workspace schema by the server. */
-    filters?: readonly ContentFilter<Fields>[];
-    sort?: ContentSort<Fields>;
+    /** Ten leaves, depth four, 31 nodes and 4 KiB. Arrays remain implicit AND. */
+    filters?: readonly ContentFilter<Fields>[] | ContentFilter<Fields>;
+    /** One object or 1–3 unique ordered fields; the UUID breaks remaining ties. */
+    sort?: ContentSort<Fields> | readonly ContentSort<Fields>[];
+    search?: ContentSearch<Fields>;
     signal?: AbortSignal;
     /** Explicit live enrichment, independently cached from the saved publication. */
     includeRemote?: boolean;
@@ -85,16 +108,44 @@ export type ListOptions<Key extends string = string, Fields = Record<string, unk
     after?: never;
     before?: never;
 });
+/** One first match, with no caller-controlled page size or boundary. */
+export type FindOneOptions<Key extends string = string, Fields = Record<string, unknown>> = Pick<BaseListOptions<Key, Fields>, "select" | "locale" | "filters" | "sort" | "search" | "signal" | "includeRemote">;
+/** Direct statistics have no pagination, projection, sorting or remote enrichment. */
+export type CountOptions<Fields = Record<string, unknown>> = Pick<BaseListOptions<string, Fields>, "locale" | "filters" | "search" | "signal">;
+export type GetManyOptions<Key extends string = string> = Pick<BaseListOptions<Key, Record<string, unknown>>, "select" | "locale" | "signal" | "includeRemote">;
+/** A paginated search; fields scopes matching, select projects the returned fields. */
+export type SearchOptions<Key extends string = string, Fields = Record<string, unknown>> = ListOptions<Key, Fields> & {
+    fields?: readonly TextField<Fields>[];
+    search?: never;
+};
 /** Lazy forward traversal, capped at 1,000 pages by default (maximum 10,000). */
 export type PaginationOptions<Key extends string = string, Fields = Record<string, unknown>> = Omit<ListOptions<Key, Fields>, "before" | "page" | "pageSize"> & {
     page?: never;
     pageSize?: never;
     maxPages?: number;
 };
-export interface ContentEntry<Fields> {
+/** Identity of the selected model; ID/name can be absent on older CMS responses. */
+export interface ContentTypeIdentity<Model extends string = string> {
+    key: Model;
+    id?: string;
+    name?: string;
+}
+export interface ContentEnvironment {
+    id: string;
+    key: string;
+}
+/** Metadata sits beside modeled fields and is retained by field projections. */
+export interface ContentEntry<Fields, Model extends string = string> {
     id: string;
     fields: Fields;
     publishedAt: string | null;
+    /** Optional in this interface to preserve existing manually constructed entries. */
+    contentType?: ContentTypeIdentity<Model>;
+    projectId?: string;
+    /** Resolved request locale; fallback fields can originate in the base language. */
+    locale?: string;
+    /** Absent when the CMS response predates environment metadata. */
+    environment?: ContentEnvironment;
     remote?: RemoteValue | null;
 }
 export interface RemoteValue<Data = Record<string, string | number | boolean | null>> {
@@ -107,8 +158,8 @@ export interface RemoteValue<Data = Record<string, string | number | boolean | n
     fetchedAt: string | null;
     expiresAt: string | null;
 }
-export interface ContentPage<Fields> {
-    data: ContentEntry<Fields>[];
+export interface ContentPage<Fields, Model extends string = string> {
+    data: ContentEntry<Fields, Model>[];
     meta: {
         nextCursor: string | null;
         limit: number;
@@ -119,16 +170,28 @@ export interface ContentPage<Fields> {
         hasPreviousPage?: boolean;
     };
 }
-export interface ContentCollection<Fields extends object> {
-    list<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: ListOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>>>;
+export interface ContentCollection<Fields extends object, Model extends string = string> {
+    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>>;
+    /** First matching entry or null; all request and response errors still reject. */
+    findOne<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: FindOneOptions<Key, Fields>): Promise<ContentEntry<Pick<Fields, Key>, Model> | null>;
+    /** Required first match; CMSNotFoundError only for a successful empty query. */
+    findOneOrThrow<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: FindOneOptions<Key, Fields>): Promise<ContentEntry<Pick<Fields, Key>, Model>>;
+    /** Matching entries across all pages, counted by the backend without downloading fields. */
+    count(options?: CountOptions<Fields>): Promise<number>;
+    /** Whether any entry matches; backend stops after the first match. */
+    exists(options?: CountOptions<Fields>): Promise<boolean>;
+    /** At most 100 UUIDs in one request; preserves order/duplicates, missing entries become null. */
+    getMany<const Key extends FieldName<Fields> = FieldName<Fields>>(ids: readonly string[], options?: GetManyOptions<Key>): Promise<(ContentEntry<Pick<Fields, Key>, Model> | null)[]>;
     /** Fetch only as the caller requests another page. Breaking stops network work. */
-    pages<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentPage<Pick<Fields, Key>>>;
+    pages<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentPage<Pick<Fields, Key>, Model>>;
     /** Flatten pages lazily, retaining at most one page of entries. */
-    entries<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentEntry<Pick<Fields, Key>>>;
-    get<const Key extends FieldName<Fields> = FieldName<Fields>>(id: string, options?: Pick<ListOptions<Key, Fields>, "select" | "locale" | "signal" | "includeRemote">): Promise<ContentEntry<Pick<Fields, Key>>>;
+    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]>;
+    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model>;
 }
 /** 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.1.0",
+  "version": "0.2.0",
   "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
   "license": "MIT",
   "homepage": "https://lemonadecms.com/guides/sdk",
@@ -44,6 +44,10 @@
     "./preview": {
       "types": "./dist/preview.d.ts",
       "default": "./dist/preview.js"
+    },
+    "./composer": {
+      "types": "./dist/composer.d.ts",
+      "default": "./dist/composer.js"
     }
   },
   "bin": {