@lemonadecms/client 0.0.0-stage → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,202 @@
+export type ModelMap<Models> = {
+    [Key in keyof Models]: object;
+};
+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. */
+    url?: never;
+    projectId: string;
+    /** Compatible transport for SSR, testing or polyfills; receives production URLs. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Optional per-request deadline, including JSON reading: 1–2147483647 ms.
+     * No default deadline. Combining with a caller signal requires AbortSignal.any.
+     */
+    timeoutMs?: number;
+}
+export interface CMSClientOptions extends CMSBaseOptions {
+    publicKey: string;
+}
+export interface CMSPreviewOptions extends CMSBaseOptions {
+    secretKey: string;
+}
+type Scalar = string | number | boolean;
+export type ScalarField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends Scalar ? Key : never;
+}[FieldName<Fields>];
+type ScalarContentFilter<Fields> = {
+    [Key in ScalarField<Fields>]: {
+        field: Key;
+        op: "eq" | "ne";
+        value: Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never) | null;
+    } | {
+        field: Key;
+        op: "in" | "not_in";
+        value: readonly (Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never))[];
+    } | (NonNullable<Fields[Key]> extends boolean ? never : {
+        field: Key;
+        op: "gt" | "gte" | "lt" | "lte";
+        value: Extract<Fields[Key], string | number> | (unknown extends Fields[Key] ? string | number : never);
+    });
+}[ScalarField<Fields>];
+type ChoicesField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends readonly string[] ? Key : never;
+}[FieldName<Fields>];
+type ChoicesValue<Value> = NonNullable<Value> extends readonly (infer Option extends string)[] ? Option : string;
+type ChoicesContentFilter<Fields> = {
+    [Key in ChoicesField<Fields>]: {
+        field: Key;
+        op: "contains_any" | "contains_all";
+        value: readonly ChoicesValue<Fields[Key]>[];
+    };
+}[ChoicesField<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";
+}
+interface BaseListOptions<Key extends string, Fields> {
+    select?: readonly Key[];
+    locale?: string;
+    limit?: number;
+    /** 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;
+}
+/** 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;
+    before?: never;
+    page?: never;
+    pageSize?: never;
+} | {
+    before?: string;
+    after?: never;
+    page?: never;
+    pageSize?: never;
+} | {
+    page?: number;
+    pageSize?: number;
+    limit?: never;
+    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;
+};
+/** 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>> {
+    source: string;
+    status: "available" | "error" | "disabled" | "not_linked";
+    readOnly: true;
+    stale: boolean;
+    data: Data | null;
+    error: string | null;
+    fetchedAt: string | null;
+    expiresAt: string | null;
+}
+export interface ContentPage<Fields, Model extends string = string> {
+    data: ContentEntry<Fields, Model>[];
+    meta: {
+        nextCursor: string | null;
+        limit: number;
+        page?: number;
+        pageSize?: number;
+        previousCursor?: string | null;
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+    };
+}
+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>, 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>, 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>;
+}
+/** A draft may omit required fields or contain nulls until it is published. */
+export type PreviewModels<Models> = {
+    [Model in keyof Models]: {
+        [Field in keyof Models[Model]]?: Models[Model][Field] | null;
+    };
+};
+export {};

package/dist/types.js

@@ -0,0 +1,6 @@
+// TypeScript contracts for configuration, fluent queries, and returned pages.
+// A caller can supply a model map to get checked model names and selected fields.
+// These types disappear at runtime: they are not schema discovery or validation
+// of arbitrary model payloads. transport.ts validates the response envelope;
+// the CMS backend validates stored field values when they are written/published.
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@lemonadecms/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
+  "license": "MIT",
+  "homepage": "https://lemonadecms.com/guides/sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ilara-booqself/lemonadecms.git",
+    "directory": "packages/cms-client"
+  },
+  "bugs": {
+    "url": "https://github.com/ilara-booqself/lemonadecms/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "bin/*.mjs",
+    "bin/cli/*.mjs",
+    "bin/codegen/*.mjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "browser": "./dist/server.browser.js",
+      "default": "./dist/server.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.js"
+    }
+  },
+  "bin": {
+    "cms-codegen": "bin/generate-types.mjs",
+    "lemonade": "bin/lemonade.mjs"
+  },
+  "private": false
+}