@flexacms/client 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,300 @@
+/**
+ * Shapes returned by the Flexa content API (`/api/v1`). Keys are kept exactly
+ * as the API sends them (snake_case), so responses can be passed around as-is.
+ */
+type EntryStatus = 'draft' | 'published' | 'archived';
+/** Values of a translatable field: one entry per configured locale. */
+type Localized<T = string> = {
+    [locale: string]: T | null | undefined;
+};
+/** Field values of an entry, keyed by field key. Narrowed by generated types. */
+type EntryValues = Record<string, unknown>;
+/**
+ * Maps entity slugs to the values of their entries. Generate it for your
+ * workspace with `npx @flexacms/cli generate` to get typed `client.entity()`.
+ */
+type ContentSchema = Record<string, EntryValues>;
+/** A file URL, a list of them, translations of them, or repeater items holding them. */
+type EntryMedia = string | null | (string | null)[] | {
+    [locale: string]: string | string[] | null;
+} | Record<string, string | string[] | null>[];
+interface Category {
+    id: number;
+    name: string;
+    slug: string;
+}
+interface RelatedEntry {
+    id: number;
+    title: string | null;
+    slug: string | null;
+    status: EntryStatus;
+}
+interface Entry<TValues extends object = EntryValues> {
+    id: number;
+    entity_id: number;
+    entity_slug: string;
+    title: string | null;
+    slug: string | null;
+    status: EntryStatus;
+    order: number | null;
+    categories: Category[];
+    values: TValues;
+    /**
+     * Absolute URLs of the files in image and file fields, keyed by field key
+     * and shaped like their values (`values` keeps the stored paths).
+     * Repeaters list their media sub-fields per item. Sent by Flexa 0.2+.
+     */
+    media?: Record<string, EntryMedia>;
+    /** Present when the request includes `relations`. */
+    relations?: Record<string, RelatedEntry[]>;
+    created_at: string | null;
+    updated_at: string | null;
+    deleted_at: string | null;
+}
+interface EntitySummary {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    icon: string | null;
+    color: string | null;
+    links: {
+        records: string;
+        schema: string;
+    };
+}
+type FieldType = 'text' | 'textarea' | 'number' | 'email' | 'url' | 'phone' | 'date' | 'datetime' | 'boolean' | 'select' | 'multiselect' | 'color' | 'file' | 'image' | 'richtext' | 'json' | 'tags' | 'repeater' | 'address' | 'relationship' | (string & {});
+interface RepeaterSubfield {
+    key: string;
+    label: string;
+    type: FieldType;
+    [setting: string]: unknown;
+}
+interface FieldSchema {
+    id: number;
+    key: string;
+    label: string;
+    type: FieldType;
+    description: string | null;
+    placeholder: string | null;
+    default_value: string | null;
+    is_required: boolean;
+    is_active: boolean;
+    is_searchable: boolean;
+    is_shown_in_list: boolean;
+    width: string;
+    order: number;
+    group: string | null;
+    options: Record<string, string> | null;
+    validation_rules: string[];
+    settings: Record<string, unknown>;
+    repeater_subfields: RepeaterSubfield[] | null;
+    category_ids: number[];
+    show_when: unknown;
+    translatable: boolean;
+    multiple: boolean;
+    value_format: string;
+    relationship?: {
+        entity: string | null;
+        multiple: boolean;
+    };
+    address_parts?: string[];
+}
+interface FieldGroupSchema {
+    id: number;
+    key: string;
+    label: string;
+    description: string | null;
+    order: number;
+    is_collapsible: boolean;
+    is_collapsed: boolean;
+}
+interface EntitySchema {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    icon: string | null;
+    color: string | null;
+    is_active: boolean;
+    show_in_menu: boolean;
+    menu_order: number;
+    settings: Record<string, unknown>;
+    fields_count: number;
+    records_count: number;
+    fields: FieldSchema[];
+    groups: FieldGroupSchema[];
+    categories: (Category & {
+        parent_id: number | null;
+        description: string | null;
+    })[];
+    record_statuses: EntryStatus[];
+    locales: string[];
+}
+interface PaginationMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+    path: string;
+}
+interface Paginated<T> {
+    data: T[];
+    meta: PaginationMeta;
+    links: {
+        first: string | null;
+        last: string | null;
+        prev: string | null;
+        next: string | null;
+    };
+}
+interface ListParams {
+    status?: EntryStatus;
+    search?: string;
+    /** Category id. */
+    category?: number;
+    page?: number;
+    /** Capped by the server (100 by default). */
+    perPage?: number;
+    /** Include soft-deleted entries (`with`) or only them (`only`). Needs the Write ability. */
+    trashed?: 'with' | 'only';
+    /** Expand relationship fields into `entry.relations`. */
+    includeRelations?: boolean;
+}
+interface GetParams {
+    includeRelations?: boolean;
+}
+interface EntryInput<TValues extends object = EntryValues> {
+    title?: string | null;
+    slug?: string | null;
+    status?: EntryStatus;
+    order?: number;
+    /** Category ids or slugs. */
+    categories?: (number | string)[];
+    values?: Partial<TValues>;
+}
+/**
+ * Per-request options. `init` is merged into the `fetch` call, which is how
+ * framework adapters pass cache settings (e.g. Next.js `next: { tags }`).
+ */
+interface RequestOptions {
+    signal?: AbortSignal;
+    init?: RequestInit & Record<string, unknown>;
+}
+
+interface FlexaClientOptions {
+    /** Base URL of your Flexa installation, e.g. `https://cms.example.com`. */
+    url: string;
+    /**
+     * Workspace API key. Keep it on the server: anyone with the key can do what
+     * its abilities allow. Use a Read-only key for public websites.
+     */
+    apiKey: string;
+    /** Path of the content API. Defaults to `/api/v1`. */
+    apiPath?: string;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Abort requests that take longer than this, in milliseconds. Defaults to 30s. */
+    timeout?: number;
+    /**
+     * How many times to retry reads after a rate limit (429), a gateway error
+     * (502/503/504) or a network failure. Writes are never retried. Defaults to 2.
+     */
+    retries?: number;
+}
+type ValuesOf<TSchema extends object, TEntity extends string> = TEntity extends keyof TSchema ? TSchema[TEntity] extends object ? TSchema[TEntity] : EntryValues : EntryValues;
+/** The part of the client entity helpers need: sending requests. */
+type RequestSender = Pick<FlexaClient, 'request'>;
+/**
+ * Content API client for one Flexa workspace (the workspace is set by the API key).
+ */
+declare class FlexaClient<TSchema extends object = ContentSchema> {
+    readonly baseUrl: string;
+    private readonly options;
+    constructor(options: FlexaClientOptions);
+    /** Entities (content models) the API key can read. */
+    entities(options?: RequestOptions): Promise<EntitySummary[]>;
+    /** Typed access to the entries of one entity. */
+    entity<TEntity extends Extract<keyof TSchema, string> | (string & {})>(slug: TEntity): EntityClient<ValuesOf<TSchema, TEntity>>;
+    /**
+     * Send a request to the content API. Exposed for endpoints the typed helpers
+     * do not cover yet; `path` is relative to the API base (e.g. `/posts`).
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private backoff;
+    private toError;
+}
+/**
+ * Entries of one entity: list, read, create, update, delete and restore.
+ */
+declare class EntityClient<TValues extends object = EntryValues> {
+    private readonly client;
+    readonly slug: string;
+    constructor(client: RequestSender, slug: string);
+    private get path();
+    /** Fields, groups, categories and locales of the entity. */
+    schema(options?: RequestOptions): Promise<EntitySchema>;
+    /** One page of entries. */
+    list(params?: ListParams, options?: RequestOptions): Promise<Paginated<Entry<TValues>>>;
+    /** Iterate over every matching entry, fetching pages as needed. */
+    iterate(params?: Omit<ListParams, 'page'>, options?: RequestOptions): AsyncGenerator<Entry<TValues>>;
+    /** Every matching entry, across all pages. */
+    all(params?: Omit<ListParams, 'page'>, options?: RequestOptions): Promise<Entry<TValues>[]>;
+    /** An entry by id or slug. Throws a 404 `FlexaError` when it does not exist. */
+    get(idOrSlug: number | string, params?: GetParams, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Like `get()`, but resolves to `null` when the entry does not exist. */
+    find(idOrSlug: number | string, params?: GetParams, options?: RequestOptions): Promise<Entry<TValues> | null>;
+    /** Create an entry. Needs the Write ability. */
+    create(input: EntryInput<TValues>, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Partially update an entry. Needs the Write ability. */
+    update(idOrSlug: number | string, input: EntryInput<TValues>, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Move an entry to the trash, or delete it for good with `force`. Needs the Delete ability. */
+    delete(idOrSlug: number | string, params?: {
+        force?: boolean;
+    }, options?: RequestOptions): Promise<void>;
+    /** Restore a trashed entry. Needs the Write ability. */
+    restore(idOrSlug: number | string, options?: RequestOptions): Promise<Entry<TValues>>;
+}
+declare function createClient<TSchema extends object = ContentSchema>(options: FlexaClientOptions): FlexaClient<TSchema>;
+
+/**
+ * Error thrown for every non-2xx response from the content API.
+ */
+declare class FlexaError extends Error {
+    /** HTTP status, or 0 when the request never reached the server. */
+    readonly status: number;
+    /** Validation errors keyed by field (422 responses). */
+    readonly errors: Record<string, string[]>;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    readonly name = "FlexaError";
+    constructor(message: string, 
+    /** HTTP status, or 0 when the request never reached the server. */
+    status: number, 
+    /** Validation errors keyed by field (422 responses). */
+    errors?: Record<string, string[]>, 
+    /** Parsed response body, when there was one. */
+    body?: unknown);
+    get isNotFound(): boolean;
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+    get isValidationError(): boolean;
+    get isRateLimited(): boolean;
+}
+declare function isFlexaError(error: unknown): error is FlexaError;
+
+/**
+ * Whether a field value is a translatable value ({ "en": "...", "es": "..." }).
+ */
+declare function isLocalized(value: unknown, locales?: readonly string[]): value is Localized<unknown>;
+/**
+ * Pick one locale of a translatable value, falling back to the given locales
+ * (and then to the first non-empty translation). Plain values pass through.
+ */
+declare function localize<T>(value: Localized<T> | T | null | undefined, locale: string, fallbacks?: readonly string[]): T | null;
+
+export { type Category, type ContentSchema, EntityClient, type EntitySchema, type EntitySummary, type Entry, type EntryInput, type EntryMedia, type EntryStatus, type EntryValues, type FieldGroupSchema, type FieldSchema, type FieldType, FlexaClient, type FlexaClientOptions, FlexaError, type GetParams, type ListParams, type Localized, type Paginated, type PaginationMeta, type RelatedEntry, type RepeaterSubfield, type RequestOptions, createClient, isFlexaError, isLocalized, localize };

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Shapes returned by the Flexa content API (`/api/v1`). Keys are kept exactly
+ * as the API sends them (snake_case), so responses can be passed around as-is.
+ */
+type EntryStatus = 'draft' | 'published' | 'archived';
+/** Values of a translatable field: one entry per configured locale. */
+type Localized<T = string> = {
+    [locale: string]: T | null | undefined;
+};
+/** Field values of an entry, keyed by field key. Narrowed by generated types. */
+type EntryValues = Record<string, unknown>;
+/**
+ * Maps entity slugs to the values of their entries. Generate it for your
+ * workspace with `npx @flexacms/cli generate` to get typed `client.entity()`.
+ */
+type ContentSchema = Record<string, EntryValues>;
+/** A file URL, a list of them, translations of them, or repeater items holding them. */
+type EntryMedia = string | null | (string | null)[] | {
+    [locale: string]: string | string[] | null;
+} | Record<string, string | string[] | null>[];
+interface Category {
+    id: number;
+    name: string;
+    slug: string;
+}
+interface RelatedEntry {
+    id: number;
+    title: string | null;
+    slug: string | null;
+    status: EntryStatus;
+}
+interface Entry<TValues extends object = EntryValues> {
+    id: number;
+    entity_id: number;
+    entity_slug: string;
+    title: string | null;
+    slug: string | null;
+    status: EntryStatus;
+    order: number | null;
+    categories: Category[];
+    values: TValues;
+    /**
+     * Absolute URLs of the files in image and file fields, keyed by field key
+     * and shaped like their values (`values` keeps the stored paths).
+     * Repeaters list their media sub-fields per item. Sent by Flexa 0.2+.
+     */
+    media?: Record<string, EntryMedia>;
+    /** Present when the request includes `relations`. */
+    relations?: Record<string, RelatedEntry[]>;
+    created_at: string | null;
+    updated_at: string | null;
+    deleted_at: string | null;
+}
+interface EntitySummary {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    icon: string | null;
+    color: string | null;
+    links: {
+        records: string;
+        schema: string;
+    };
+}
+type FieldType = 'text' | 'textarea' | 'number' | 'email' | 'url' | 'phone' | 'date' | 'datetime' | 'boolean' | 'select' | 'multiselect' | 'color' | 'file' | 'image' | 'richtext' | 'json' | 'tags' | 'repeater' | 'address' | 'relationship' | (string & {});
+interface RepeaterSubfield {
+    key: string;
+    label: string;
+    type: FieldType;
+    [setting: string]: unknown;
+}
+interface FieldSchema {
+    id: number;
+    key: string;
+    label: string;
+    type: FieldType;
+    description: string | null;
+    placeholder: string | null;
+    default_value: string | null;
+    is_required: boolean;
+    is_active: boolean;
+    is_searchable: boolean;
+    is_shown_in_list: boolean;
+    width: string;
+    order: number;
+    group: string | null;
+    options: Record<string, string> | null;
+    validation_rules: string[];
+    settings: Record<string, unknown>;
+    repeater_subfields: RepeaterSubfield[] | null;
+    category_ids: number[];
+    show_when: unknown;
+    translatable: boolean;
+    multiple: boolean;
+    value_format: string;
+    relationship?: {
+        entity: string | null;
+        multiple: boolean;
+    };
+    address_parts?: string[];
+}
+interface FieldGroupSchema {
+    id: number;
+    key: string;
+    label: string;
+    description: string | null;
+    order: number;
+    is_collapsible: boolean;
+    is_collapsed: boolean;
+}
+interface EntitySchema {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    icon: string | null;
+    color: string | null;
+    is_active: boolean;
+    show_in_menu: boolean;
+    menu_order: number;
+    settings: Record<string, unknown>;
+    fields_count: number;
+    records_count: number;
+    fields: FieldSchema[];
+    groups: FieldGroupSchema[];
+    categories: (Category & {
+        parent_id: number | null;
+        description: string | null;
+    })[];
+    record_statuses: EntryStatus[];
+    locales: string[];
+}
+interface PaginationMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+    path: string;
+}
+interface Paginated<T> {
+    data: T[];
+    meta: PaginationMeta;
+    links: {
+        first: string | null;
+        last: string | null;
+        prev: string | null;
+        next: string | null;
+    };
+}
+interface ListParams {
+    status?: EntryStatus;
+    search?: string;
+    /** Category id. */
+    category?: number;
+    page?: number;
+    /** Capped by the server (100 by default). */
+    perPage?: number;
+    /** Include soft-deleted entries (`with`) or only them (`only`). Needs the Write ability. */
+    trashed?: 'with' | 'only';
+    /** Expand relationship fields into `entry.relations`. */
+    includeRelations?: boolean;
+}
+interface GetParams {
+    includeRelations?: boolean;
+}
+interface EntryInput<TValues extends object = EntryValues> {
+    title?: string | null;
+    slug?: string | null;
+    status?: EntryStatus;
+    order?: number;
+    /** Category ids or slugs. */
+    categories?: (number | string)[];
+    values?: Partial<TValues>;
+}
+/**
+ * Per-request options. `init` is merged into the `fetch` call, which is how
+ * framework adapters pass cache settings (e.g. Next.js `next: { tags }`).
+ */
+interface RequestOptions {
+    signal?: AbortSignal;
+    init?: RequestInit & Record<string, unknown>;
+}
+
+interface FlexaClientOptions {
+    /** Base URL of your Flexa installation, e.g. `https://cms.example.com`. */
+    url: string;
+    /**
+     * Workspace API key. Keep it on the server: anyone with the key can do what
+     * its abilities allow. Use a Read-only key for public websites.
+     */
+    apiKey: string;
+    /** Path of the content API. Defaults to `/api/v1`. */
+    apiPath?: string;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Abort requests that take longer than this, in milliseconds. Defaults to 30s. */
+    timeout?: number;
+    /**
+     * How many times to retry reads after a rate limit (429), a gateway error
+     * (502/503/504) or a network failure. Writes are never retried. Defaults to 2.
+     */
+    retries?: number;
+}
+type ValuesOf<TSchema extends object, TEntity extends string> = TEntity extends keyof TSchema ? TSchema[TEntity] extends object ? TSchema[TEntity] : EntryValues : EntryValues;
+/** The part of the client entity helpers need: sending requests. */
+type RequestSender = Pick<FlexaClient, 'request'>;
+/**
+ * Content API client for one Flexa workspace (the workspace is set by the API key).
+ */
+declare class FlexaClient<TSchema extends object = ContentSchema> {
+    readonly baseUrl: string;
+    private readonly options;
+    constructor(options: FlexaClientOptions);
+    /** Entities (content models) the API key can read. */
+    entities(options?: RequestOptions): Promise<EntitySummary[]>;
+    /** Typed access to the entries of one entity. */
+    entity<TEntity extends Extract<keyof TSchema, string> | (string & {})>(slug: TEntity): EntityClient<ValuesOf<TSchema, TEntity>>;
+    /**
+     * Send a request to the content API. Exposed for endpoints the typed helpers
+     * do not cover yet; `path` is relative to the API base (e.g. `/posts`).
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private backoff;
+    private toError;
+}
+/**
+ * Entries of one entity: list, read, create, update, delete and restore.
+ */
+declare class EntityClient<TValues extends object = EntryValues> {
+    private readonly client;
+    readonly slug: string;
+    constructor(client: RequestSender, slug: string);
+    private get path();
+    /** Fields, groups, categories and locales of the entity. */
+    schema(options?: RequestOptions): Promise<EntitySchema>;
+    /** One page of entries. */
+    list(params?: ListParams, options?: RequestOptions): Promise<Paginated<Entry<TValues>>>;
+    /** Iterate over every matching entry, fetching pages as needed. */
+    iterate(params?: Omit<ListParams, 'page'>, options?: RequestOptions): AsyncGenerator<Entry<TValues>>;
+    /** Every matching entry, across all pages. */
+    all(params?: Omit<ListParams, 'page'>, options?: RequestOptions): Promise<Entry<TValues>[]>;
+    /** An entry by id or slug. Throws a 404 `FlexaError` when it does not exist. */
+    get(idOrSlug: number | string, params?: GetParams, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Like `get()`, but resolves to `null` when the entry does not exist. */
+    find(idOrSlug: number | string, params?: GetParams, options?: RequestOptions): Promise<Entry<TValues> | null>;
+    /** Create an entry. Needs the Write ability. */
+    create(input: EntryInput<TValues>, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Partially update an entry. Needs the Write ability. */
+    update(idOrSlug: number | string, input: EntryInput<TValues>, options?: RequestOptions): Promise<Entry<TValues>>;
+    /** Move an entry to the trash, or delete it for good with `force`. Needs the Delete ability. */
+    delete(idOrSlug: number | string, params?: {
+        force?: boolean;
+    }, options?: RequestOptions): Promise<void>;
+    /** Restore a trashed entry. Needs the Write ability. */
+    restore(idOrSlug: number | string, options?: RequestOptions): Promise<Entry<TValues>>;
+}
+declare function createClient<TSchema extends object = ContentSchema>(options: FlexaClientOptions): FlexaClient<TSchema>;
+
+/**
+ * Error thrown for every non-2xx response from the content API.
+ */
+declare class FlexaError extends Error {
+    /** HTTP status, or 0 when the request never reached the server. */
+    readonly status: number;
+    /** Validation errors keyed by field (422 responses). */
+    readonly errors: Record<string, string[]>;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    readonly name = "FlexaError";
+    constructor(message: string, 
+    /** HTTP status, or 0 when the request never reached the server. */
+    status: number, 
+    /** Validation errors keyed by field (422 responses). */
+    errors?: Record<string, string[]>, 
+    /** Parsed response body, when there was one. */
+    body?: unknown);
+    get isNotFound(): boolean;
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+    get isValidationError(): boolean;
+    get isRateLimited(): boolean;
+}
+declare function isFlexaError(error: unknown): error is FlexaError;
+
+/**
+ * Whether a field value is a translatable value ({ "en": "...", "es": "..." }).
+ */
+declare function isLocalized(value: unknown, locales?: readonly string[]): value is Localized<unknown>;
+/**
+ * Pick one locale of a translatable value, falling back to the given locales
+ * (and then to the first non-empty translation). Plain values pass through.
+ */
+declare function localize<T>(value: Localized<T> | T | null | undefined, locale: string, fallbacks?: readonly string[]): T | null;
+
+export { type Category, type ContentSchema, EntityClient, type EntitySchema, type EntitySummary, type Entry, type EntryInput, type EntryMedia, type EntryStatus, type EntryValues, type FieldGroupSchema, type FieldSchema, type FieldType, FlexaClient, type FlexaClientOptions, FlexaError, type GetParams, type ListParams, type Localized, type Paginated, type PaginationMeta, type RelatedEntry, type RepeaterSubfield, type RequestOptions, createClient, isFlexaError, isLocalized, localize };