@lyeve-labs/client 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,465 @@
+/**
+ * Framework-agnostic HTTP client for the LyEve CMS API.
+ *
+ * The `createClient` factory accepts any `fetch`-compatible function
+ * (globalThis.fetch, SvelteKit's event.fetch, a Node.js polyfill) and
+ * returns a typed client with get/post/put/delete methods that handle
+ * JSON serialization, error mapping, and timeout.
+ */
+declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+type HttpClient = ReturnType<typeof createClient>;
+declare function createClient(fetchFn: typeof fetch, defaultHeaders?: Record<string, string>): {
+    get: <T>(url: string, init?: RequestInit) => Promise<T>;
+    post: <T>(url: string, body: unknown, init?: RequestInit) => Promise<T>;
+    put: <T>(url: string, body: unknown, init?: RequestInit) => Promise<T>;
+    patch: <T>(url: string, body: unknown, init?: RequestInit) => Promise<T>;
+    delete: <T>(url: string, init?: RequestInit) => Promise<T>;
+};
+
+interface Schema {
+    name: string;
+    display_name: string;
+    fields: SchemaField[];
+    /** Whether to include a created_at system field (TIMESTAMPTZ, auto-set on insert). */
+    with_created_at?: boolean;
+    /** Whether to include an updated_at system field (TIMESTAMPTZ, auto-set on update). */
+    with_updated_at?: boolean;
+    /** Whether content entries support draft/published/archived status. */
+    with_draft_publish?: boolean;
+    /** Whether to include a deleted_at soft-delete column. */
+    with_soft_delete?: boolean;
+    /** Whether to support per-row localization. */
+    with_localization?: boolean;
+    /** Canvas position : stored client-side in localStorage. */
+    _pos?: {
+        x: number;
+        y: number;
+    };
+}
+interface SchemaField {
+    /** Client-side stable id for drag-and-drop : not sent to the server. */
+    id?: string;
+    name: string;
+    field_type: FieldType;
+    required: boolean;
+    unique: boolean;
+    indexed: boolean;
+    default?: unknown;
+    relation_to?: string;
+    /** 'belongs_to' (FK on this table) | 'has_one' | 'has_many' | 'many_to_many' (pivot table). */
+    relation_type?: "belongs_to" | "has_one" | "has_many" | "many_to_many";
+    /** Override the auto-generated pivot table name (many_to_many only). */
+    relation_through?: string;
+    /** Override the auto-generated FK column name (belongs_to only). */
+    relation_fk_name?: string;
+    /** Set by the server : these fields cannot be edited or removed in the UI. */
+    system?: boolean;
+}
+type FieldType = "text" | "rich_text" | "number" | "boolean" | "date" | "datetime" | "json" | "relation" | "media" | "email" | "url" | "uid";
+interface Content {
+    id: string;
+    schema_name: string;
+    slug?: string;
+    status?: string;
+    data: Record<string, unknown>;
+    tenant_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface APIKey {
+    id: string;
+    name: string;
+    roles: string[];
+    schemas: string[];
+    enabled: boolean;
+    monthly_limit: number;
+    created_at: string;
+    expires_at: string | null;
+}
+interface CreateAPIKeyResponse extends APIKey {
+    raw_key: string;
+}
+interface Webhook {
+    id: string;
+    name: string;
+    url: string;
+    /** Subset of: before_create | after_create | before_update | after_update | before_delete | after_delete. */
+    events: string[];
+    /** Empty array = all schemas. */
+    schemas: string[];
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface WebhookTestResult {
+    success: boolean;
+    status_code: number;
+    message: string;
+}
+interface WebhookDelivery {
+    id: string;
+    webhook_id: string;
+    event_type: string;
+    schema_name: string;
+    status_code?: number;
+    success: boolean;
+    duration_ms?: number;
+    request_body: string;
+    error?: string;
+    attempted_at: string;
+    retry_count: number;
+    next_retry_at?: string;
+}
+interface RetryDeliveryResult {
+    success: boolean;
+    status_code: number;
+    message: string;
+    delivery_id: string;
+}
+interface RetryConfig$1 {
+    id: string;
+    webhook_id: string;
+    max_attempts: number;
+    base_delay_ms: number;
+    max_delay_ms: number;
+    strategy: "exponential" | "fixed" | "linear";
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+type RetryConfigInput = Partial<Pick<RetryConfig$1, "max_attempts" | "base_delay_ms" | "max_delay_ms" | "strategy" | "enabled">>;
+type DLQStatus = "pending" | "replayed" | "dismissed";
+interface DeadLetter {
+    id: string;
+    webhook_id: string;
+    webhook_name: string;
+    webhook_url: string;
+    event_type: string;
+    schema_name: string;
+    request_body: string;
+    last_status_code?: number;
+    last_error?: string;
+    total_attempts: number;
+    status: DLQStatus;
+    dead_at: string;
+    replayed_at?: string;
+    created_at: string;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface WebhookHealthStats {
+    webhook_id: string;
+    webhook_name: string;
+    total_attempts: number;
+    success_count: number;
+    failed_count: number;
+    exhausted_count: number;
+    dlq_pending: number;
+    average_duration_ms?: number;
+    healthy: boolean;
+}
+interface GlobalHealthStats {
+    total_webhooks: number;
+    healthy_webhooks: number;
+    unhealthy_webhooks: number;
+    pending_retries: number;
+    total_dlq: number;
+    pending_dlq: number;
+}
+interface IncomingWebhook {
+    id: string;
+    name: string;
+    schema_name: string;
+    field_map: Record<string, string>;
+    enabled: boolean;
+    allowed_ips: string[];
+    created_at: string;
+    updated_at: string;
+}
+interface User {
+    id: string;
+    email: string;
+    roles: string[];
+    tenant_id: string;
+    disabled: boolean;
+    created_at: string;
+    expires_at?: string | null;
+}
+interface ListResponse<T> {
+    items: T[];
+    total?: number;
+}
+interface OAuthProvider {
+    id: string;
+    name: string;
+    client_id: string;
+    /** Not returned by the server : only sent on create/update. */
+    client_secret?: string;
+    issuer_url: string;
+    scopes: string[];
+    roles_claim: string;
+    default_roles: string[];
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface Permission {
+    id: string;
+    role: string;
+    schema_name: string;
+    /** Subset of: create | read | update | delete. */
+    actions: string[];
+    /** Field names stripped from read responses for this role. */
+    field_mask: string[];
+    created_at: string;
+}
+/**
+ * License entitlement snapshot : mirrors the Go `license.Snapshot` returned by
+ * GET /api/admin/entitlements. Drives free-tier UI gating and upgrade prompts.
+ */
+interface Entitlements {
+    /** Active plan, "free" when unlicensed. */
+    plan: string;
+    /** License state: free | active | grace | expired. */
+    state: string;
+    /** Entitled feature ids (e.g. "feature:rbac", "feature:schema_ui"). */
+    features: string[];
+    /** License expiry (ISO 8601), null when unlicensed or perpetual. */
+    expires_at: string | null;
+    /** Full days until expiry, -1 when unlicensed or perpetual. */
+    days_remaining: number;
+}
+
+/**
+ * Async iterator for cursor-based content pagination.
+ *
+ * Walks the Content API's cursor endpoint, yielding records one at a time.
+ * Each call to `.next()` returns the next record.
+ *
+ * ## Usage
+ * ```ts
+ * const paginator = new PaginationIterator<MyRecord>({
+ *   fetchPage: (cursor) => api.getPage(cursor),
+ * });
+ *
+ * for await (const record of paginator) {
+ *   console.log(record);
+ * }
+ *
+ * // With AbortController:
+ * const ac = new AbortController();
+ * setTimeout(() => ac.abort(), 5000);
+ * for await (const record of paginator.withSignal(ac.signal)) {
+ *   // stops after 5 seconds
+ * }
+ * ```
+ */
+/** Response shape from a cursor-paginated endpoint. */
+interface CursorPage<T> {
+    items: T[];
+    /** Present when more pages are available. */
+    next_cursor?: string;
+}
+/** Function that fetches a single cursor page. */
+type PageFetcher<T> = (cursor?: string) => Promise<CursorPage<T>>;
+interface PaginationConfig<T> {
+    /** Function that fetches a single cursor page. */
+    fetchPage: PageFetcher<T>;
+}
+/**
+ * Async iterable iterator over paginated records.
+ *
+ * Implements `AsyncIterableIterator<T>` so it can be used directly in
+ * `for await...of` loops. Also exposes `.withSignal()` for AbortController
+ * integration.
+ */
+declare class PaginationIterator<T> implements AsyncIterableIterator<T> {
+    #private;
+    constructor(config: PaginationConfig<T>);
+    /**
+     * Return a new iterator sharing the same underlying state but with a
+     * different AbortSignal. Useful when the signal is only known at the
+     * call site, not at construction time.
+     */
+    withSignal(signal: AbortSignal): PaginationIterator<T>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    next(): Promise<IteratorResult<T>>;
+    return?(value?: unknown): Promise<IteratorResult<T>>;
+    throw?(e?: unknown): Promise<IteratorResult<T>>;
+}
+
+/**
+ * Fluent query builder for LyEve CMS Content API queries.
+ *
+ * Produces ContentQuery objects with a chainable API.
+ *
+ * ## Usage
+ * ```ts
+ * import { query } from '@lyeve/cms-client';
+ *
+ * const q = query('posts')
+ *   .where('status', 'eq:published')
+ *   .sort('-created_at')
+ *   .limit(20)
+ *   .build();
+ * ```
+ */
+type ContentStatus = "draft" | "published" | "archived";
+interface ContentQuery {
+    /** Filter by status. */
+    status?: ContentStatus;
+    /** Max records per page. */
+    limit?: number;
+    /** Offset for offset-based pagination. Mutually exclusive with cursor. */
+    offset?: number;
+    /** Cursor for cursor-based pagination. Mutually exclusive with offset. */
+    cursor?: string;
+    /** Field-level filters in `field=op:value` format. */
+    filters?: Record<string, string>;
+    /** Sort field(s), comma-separated. Prefix with `-` for descending. */
+    sort?: string;
+}
+/**
+ * Builder for ContentQuery objects.
+ *
+ * Each field can only hold one filter (Record<string, string>). Calling
+ * where() (or whereEq/whereGt etc.) with an already-set field name
+ * overwrites the previous filter. For range queries on the same field,
+ * use the server's range filter syntax in a single call.
+ */
+declare class QueryBuilder {
+    #private;
+    constructor(schema: string);
+    /** The schema/collection this query targets. */
+    get schema(): string;
+    /** Filter by content status (published, draft, archived). */
+    whereStatus(s: ContentStatus | undefined): this;
+    /** Add a field filter in `op:value` format. */
+    where(field: string, value: string): this;
+    /** Add a field-level equality filter. */
+    whereEq(field: string, value: string | number | boolean): this;
+    /** Add a field-level "in" filter (value is a JSON array). */
+    whereIn(field: string, values: (string | number)[]): this;
+    /** Greater-than comparison. */
+    whereGt(field: string, value: number): this;
+    /** Greater-than-or-equal comparison. */
+    whereGte(field: string, value: number): this;
+    /** Less-than comparison. */
+    whereLt(field: string, value: number): this;
+    /** Less-than-or-equal comparison. */
+    whereLte(field: string, value: number): this;
+    /** Full-text search (if the schema supports it). */
+    whereSearch(field: string, query: string): this;
+    /** Set the max records per page. */
+    limit(n: number | undefined): this;
+    /** Set the offset for offset-based pagination. Clears cursor. */
+    offset(n: number | undefined): this;
+    /** Set the cursor for cursor-based pagination. Clears offset. */
+    cursor(c: string | undefined): this;
+    /** Set sort fields. Prefix with `-` for descending. */
+    sort(...fields: string[]): this;
+    /** Clear all filters, keeping only the schema name. */
+    resetFilters(): this;
+    /** Produce the ContentQuery object. */
+    build(): ContentQuery;
+}
+/**
+ * Create a new query builder for the given schema.
+ * Equivalent to `new QueryBuilder(schema)`.
+ */
+declare function query(schema: string): QueryBuilder;
+
+/**
+ * Automatic retry with exponential backoff and jitter.
+ *
+ * Wraps fetch to retry on transient errors (429, 5xx, network failures).
+ * Uses "full jitter" backoff: `random(0, min(cap, base * 2^attempt))`.
+ *
+ * Usage:
+ *   const fetchWithRetry = createRetryFetch(fetch, {
+ *     maxRetries: 3,
+ *     baseDelay: 1000,
+ *     maxDelay: 30000,
+ *     retryOn: [429, 500, 502, 503, 504],
+ *     onRetry: (attempt, err, delay) => console.warn(`Retry ${attempt} in ${delay}ms`),
+ *   });
+ *   const res = await fetchWithRetry(url, init);
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3). */
+    maxRetries?: number;
+    /** Base delay in ms before first retry (default: 1000). */
+    baseDelay?: number;
+    /** Maximum delay in ms between retries (default: 30000). */
+    maxDelay?: number;
+    /** HTTP status codes that trigger a retry (default: [429, 500, 502, 503, 504]). */
+    retryOn?: number[];
+    /** If true, retry on network/abort errors as well (default: true). */
+    retryOnNetworkError?: boolean;
+    /** Called before each retry with (attempt, error, delayMs). */
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * Create a fetch wrapper that automatically retries on transient failures.
+ *
+ * Retry logic:
+ * 1. If the response status is in `retryOn`, read+discard the body, then retry.
+ * 2. If the request threw a network/abort error and `retryOnNetworkError` is true,
+ *    retry.
+ * 3. Exponential backoff with full jitter.
+ * 4. Respects AbortSignal : aborts cancel the current attempt and skip remaining
+ *    retries.
+ */
+declare function createRetryFetch(fetchImpl: typeof globalThis.fetch, config?: RetryConfig): typeof globalThis.fetch;
+
+/**
+ * In-flight request deduplication.
+ *
+ * When multiple callers request the same URL+method+body combination
+ * concurrently, only one network request is made. All callers receive
+ * the same response (the promise is shared).
+ *
+ * Cache entries are evicted when the shared promise settles (success or
+ * failure). Late subscribers that arrive after eviction start fresh.
+ */
+/**
+ * Deduplicator for in-flight HTTP requests.
+ *
+ * ## Usage
+ * ```ts
+ * const dedupe = new RequestDeduplicator();
+ *
+ * async function fetchDeduped(url: string, init?: RequestInit): Promise<Response> {
+ *   const method = init?.method ?? 'GET';
+ *   const key = `${method}:${url}:${JSON.stringify(init?.body ?? '')}`;
+ *   return dedupe.dedup(key, () => fetch(url, init), init?.signal);
+ * }
+ * ```
+ */
+declare class RequestDeduplicator {
+    #private;
+    /**
+     * Execute `factory` once for the given key. Concurrent callers with
+     * the same key receive the same promise. The entry is evicted after
+     * the shared promise settles.
+     *
+     * @param key     - Unique request key (method + URL + stable body hash).
+     * @param factory - The network operation to perform.
+     * @param signal  - Optional AbortSignal. If it fires, this caller gets
+     *                  an AbortError. The shared request continues.
+     */
+    dedup<T>(key: string, factory: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** How many unique requests are currently in flight. */
+    get inflight(): number;
+    /** Remove all pending deduplication entries. */
+    clear(): void;
+}
+
+export { type APIKey, ApiError, type Content, type ContentQuery, type ContentStatus, type CreateAPIKeyResponse, type CursorPage, type DLQStatus, type DeadLetter, type Entitlements, type FieldType, type GlobalHealthStats, type HttpClient, type IncomingWebhook, type ListResponse, type OAuthProvider, type PageFetcher, type PaginatedResponse, type PaginationConfig, PaginationIterator, type Permission, QueryBuilder, RequestDeduplicator, type RetryConfig$1 as RetryConfig, type RetryConfigInput, type RetryDeliveryResult, type RetryConfig as RetryFetchConfig, type Schema, type SchemaField, type User, type Webhook, type WebhookDelivery, type WebhookHealthStats, type WebhookTestResult, createClient, createRetryFetch, query };