@relyio/sdk 0.6.0 → 0.7.0

package/dist/index-BOQIHnsh.d.ts

@@ -0,0 +1,818 @@
+import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-DiVpbwNs.js';
+
+/**
+ * Where the SDK's transport gets its truth.
+ *
+ * Every route this client calls is named by its **path template as the
+ * committed document spells it**, and the body type it expects is read out of
+ * that document rather than written down here. `api-schema.ts` beside this file
+ * is generated by `pnpm api:types` from `apps/services/api/openapi-spec.json`,
+ * which is itself generated from that service's `RouteContract`s
+ * (`INV-API-DOCUMENT-IS-DERIVED`). So the chain is: one declaration in
+ * `routes.ts` → the serializer that produces the body → the document → these
+ * types → the method that reads it.
+ *
+ * That chain is the answer to the question this phase exists to close. Before
+ * it, six SDK methods read a key the server does not send; each had no caller
+ * and no test, so nothing could see them. Now:
+ *
+ * - A route that changes **kind** — `collection` to `object`, say — changes
+ *   whether the document's 200 body carries `page` and whether `data` is an
+ *   array. `Wire<…>` follows, `readPayload` follows, and the method's declared
+ *   return type stops matching. `tsc` names the method.
+ * - A route that changes **path** or is deleted stops being a `keyof paths`, so
+ *   the call site fails on the literal.
+ * - A route that changes **dialect** changes `page` from `CursorPage` to
+ *   `OffsetPage`, and anything reading `nextCursor` fails.
+ *
+ * `/v1` lives in these templates because it lives in the document
+ * (`INV-API-VERSION-IS-DECIDED-ONCE`). Before this phase the SDK's base URL was
+ * `https://api.relyio.com` and its paths were `/{contentType}`, so every
+ * versioned request went to a path the router does not serve.
+ *
+ * Spec: `devtools/docs/guide/engineering/api-contract-spec.md`,
+ * `INV-API-CLIENT-IS-DERIVED`.
+ */
+
+/** Every path the committed document declares. */
+type ApiPath = keyof paths;
+type Verb = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/** The verbs the document declares on this path — not the seven HTTP has. */
+type ApiMethod<P extends ApiPath> = {
+    [M in Verb]: M extends keyof paths[P] ? paths[P][M] extends {
+        responses: unknown;
+    } ? M : never : never;
+}[Verb];
+type Operation<P extends ApiPath, M extends ApiMethod<P>> = M extends keyof paths[P] ? paths[P][M] : never;
+type JsonBody<R> = R extends {
+    content: {
+        'application/json': infer B;
+    };
+} ? B : never;
+/**
+ * The success body the document declares, preferring 200 where a route serves
+ * both. A route with neither — `kind: 'empty'`, which serves 204 — resolves to
+ * `never`, and `readPayload` cannot be called on it.
+ */
+type ApiSuccessBody<P extends ApiPath, M extends ApiMethod<P>> = Operation<P, M> extends {
+    responses: infer R;
+} ? 200 extends keyof R ? JsonBody<R[200]> : 201 extends keyof R ? JsonBody<R[201]> : never : never;
+/**
+ * The document's success body with the payload typed as the caller's `T`.
+ *
+ * The array arm is tested **first** on purpose: `{ data: unknown[] }` also
+ * satisfies `{ data: unknown }`, so the object arm would swallow every
+ * collection and hand a list route's caller a single entity — which is the
+ * exact defect class (`ContentClient.children` reading `.data.items` from an
+ * object route) that this phase makes unrepresentable.
+ */
+type Wire<P extends ApiPath, M extends ApiMethod<P>, T> = ApiSuccessBody<P, M> extends {
+    data: unknown[];
+} ? Omit<ApiSuccessBody<P, M>, 'data'> & {
+    data: T[];
+} : ApiSuccessBody<P, M> extends {
+    data: unknown;
+} ? Omit<ApiSuccessBody<P, M>, 'data'> & {
+    data: T;
+} : ApiSuccessBody<P, M>;
+/**
+ * The path parameters the document declares for this operation, or `never`
+ * where it declares none.
+ *
+ * `never` rather than `{}`: a route with no segments must **forbid** a `path`
+ * argument, not merely tolerate an empty one, and `keyof Record<string, never>`
+ * is `string`, so an empty-object encoding cannot be told apart from a real
+ * one at the type level.
+ */
+type PathParamsOf<P extends ApiPath, M extends ApiMethod<P>> = Operation<P, M> extends {
+    parameters: {
+        path?: infer X;
+    };
+} ? [X] extends [undefined] ? never : NonNullable<X> : never;
+/** What {@link matchRoute} recovers from a URL the client emitted. */
+interface RouteMatch {
+    /** The document's path template — the value a tag translator switches on. */
+    path: ApiPath;
+    /** The template's `{name}` segments, decoded: the inverse of {@link fillPath}. */
+    params: Record<string, string>;
+    /** The query string; a key that appears more than once comes back as an array. */
+    query: Record<string, string | string[]>;
+}
+interface MatchRouteOptions {
+    /**
+     * The client's `baseUrl`, when it carries a path prefix of its own
+     * (`https://example.com/relyio`). Its path is removed before the template is
+     * matched. Unneeded for the default `https://api.relyio.com`.
+     */
+    baseUrl?: string;
+}
+/**
+ * Recover the route a URL names: the inverse of {@link fillPath}, over the same
+ * committed document (`INV-API-CLIENT-IS-DERIVED`).
+ *
+ * `matchRoute(url).path` is an `ApiPath`, so anything that keys behaviour on a
+ * request — a cache-tag translator, say — switches on the document's templates
+ * and never on a route table of its own.
+ *
+ * Returns `null` for a URL no declared template matches — a presigned storage
+ * URL, or a path outside `baseUrl` — rather than a guess.
+ */
+declare function matchRoute(url: string | URL, options?: MatchRouteOptions): RouteMatch | null;
+
+/**
+ * Configuration types for the RelyIO SDK
+ */
+
+interface RelyIOConfig {
+    /**
+     * API key for authentication, sent as `X-API-Key`.
+     *
+     * Required by every request, not by construction: a client built without one — a module-scope
+     * client whose `process.env` variable is unset during a build — constructs, and each request it
+     * makes rejects with `MissingApiKeyError` before anything is sent. Under `relyio dev` the
+     * sandbox's key is used instead, so none need be configured.
+     */
+    apiKey: string;
+    /** Base URL for the RelyIO API */
+    baseUrl?: string;
+    /** Dataset to use */
+    dataset?: string;
+    /**
+     * Default locale for all content queries
+     * Can be overridden per-query using .locale() or .withLocale()
+     *
+     * @example
+     * const client = createClient({
+     *   apiKey: '...',
+     *   locale: 'en-US', // All queries default to English
+     * })
+     */
+    locale?: string;
+    /**
+     * How long one request may take, in milliseconds, before it ends as a `TimeoutError` (defaults
+     * to 30000). A number from 1 to 2147483647, the longest a timer waits; `0`, `NaN`, `Infinity` or
+     * anything larger is refused, and no value turns the timeout off.
+     */
+    timeout?: number;
+    /**
+     * The most attempts one request makes, the first included (defaults to 3). `1` turns retrying
+     * off; a value that is not a whole number of at least 1 is refused. Only a failure a later attempt
+     * can change is retried, and only where sending the request twice cannot apply it twice.
+     */
+    retryAttempts?: number;
+    /** Whether to use HTTPS (defaults to true) */
+    useSsl?: boolean;
+    /** Environment mode */
+    environment?: 'development' | 'staging' | 'production';
+    /**
+     * Cache configuration.
+     *
+     * Declarative only: the client keeps no response cache, and nothing in it reads
+     * these values, so every call goes to `fetch`. There is no SDK-side cache to
+     * turn off under a framework that caches `fetch` itself (Next.js).
+     */
+    cache?: CacheConfig;
+    /** Real-time configuration */
+    realtime?: RealtimeConfig;
+    /** Debug configuration */
+    debug?: DebugConfig;
+    /** Custom headers to include with requests */
+    headers?: Record<string, string>;
+    /**
+     * The function every request to the RelyIO API is sent through. Omit it and the
+     * client calls the runtime's `globalThis.fetch`, looked up per request. File
+     * bytes an asset upload PUTs straight to a presigned storage URL do not pass
+     * through it.
+     *
+     * The client still builds every request — URL, method, headers, body, signal —
+     * and hands this function that `RequestInit` unchanged, retries included, so an
+     * `Idempotency-Key` minted for a write is the same on every attempt. Supply one
+     * to add what your framework reads off the `RequestInit`, for example Next.js
+     * cache tags:
+     *
+     * @example
+     * const client = createClient({
+     *   apiKey: '...',
+     *   fetch: (input, init) => fetch(input, { ...init, next: { tags: ['posts'] } }),
+     * })
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Browser-specific configuration */
+    browser?: BrowserConfig;
+    /**
+     * `relyio dev` sandbox detection.
+     *
+     * When developing under `relyio dev`, the CLI injects an ephemeral sandbox's dataset + scoped
+     * preview API key (via env vars or a local `.relyio/dev.json`). The SDK then transparently
+     * targets that sandbox instead of production — no code changes required.
+     *
+     * - Omit (default): detection runs automatically unless `NODE_ENV === 'production'`, so
+     *   `relyio dev -- pnpm dev` "just works" while production builds stay untouched.
+     * - `false`: disable detection entirely (force production targeting even in a dev shell).
+     * - `true`: force detection even when `NODE_ENV === 'production'`.
+     */
+    dev?: boolean;
+}
+/**
+ * What `updateConfig()` takes: any option of {@link RelyIOConfig}, each laid over the value the
+ * client holds rather than over its default.
+ *
+ * An option left out or given as `undefined` keeps the value the client holds, and a bag of options
+ * you name keeps every field you do not name. `null` removes — "`undefined` keeps, `null` removes" —
+ * and the types accept it only where a value can go: an option with no default (`locale`,
+ * `dataset`, `fetch`, `browser.onCorsError`, `debug.logger`, …), which is then absent, and a header,
+ * which is then no longer sent. An option with a default takes no `null`: removed, it would leave
+ * nothing but that default. `createClient()` has nothing to remove, so its options take no `null`.
+ *
+ * Which options have no default is read off {@link UndefaultedOption} and {@link UndefaultedField} —
+ * the names {@link ConfigDefaults} leaves optional — so an option that gains or loses a default
+ * changes what `null` can clear with no edit here.
+ */
+type RelyIOConfigUpdate = Update<Omit<RelyIOConfig, OptionBag | 'headers'>, UndefaultedOption> & {
+    browser?: Update<BrowserConfig, UndefaultedField['browser']>;
+    cache?: Update<CacheConfig, UndefaultedField['cache']>;
+    realtime?: Update<RealtimeConfig, UndefaultedField['realtime']>;
+    debug?: Update<DebugConfig, UndefaultedField['debug']>;
+    /** Headers to add or replace, each kept until named again; `null` stops sending that header. */
+    headers?: Record<string, string | null>;
+};
+/** `T`'s options, each one optional, with `null` accepted for the ones named in `Clearable`. */
+type Update<T, Clearable extends keyof T> = {
+    [K in keyof T]?: K extends Clearable ? T[K] | null : T[K];
+};
+interface CacheConfig {
+    /** Whether caching is enabled (defaults to true) */
+    enabled?: boolean;
+    /** Cache TTL in milliseconds (defaults to 5 minutes) */
+    ttl?: number;
+    /** Maximum number of cache entries (defaults to 1000) */
+    maxEntries?: number;
+    /** Maximum cache size in bytes (defaults to 50MB) */
+    maxSize?: number;
+    /** Cache strategies to use */
+    strategies?: CacheStrategy[];
+}
+interface RealtimeConfig {
+    /** Whether real-time features are enabled (defaults to true) */
+    enabled?: boolean;
+    /** WebSocket URL for real-time connections */
+    wsUrl?: string;
+    /** Maximum number of reconnection attempts (defaults to 10) */
+    maxReconnectAttempts?: number;
+    /** Reconnection delay in milliseconds (defaults to 1000) */
+    reconnectDelay?: number;
+    /** Heartbeat interval in milliseconds (defaults to 30000) */
+    heartbeatInterval?: number;
+}
+interface DebugConfig {
+    /** Whether debug mode is enabled (defaults to false) */
+    enabled?: boolean;
+    /** Whether to log network requests (defaults to false) */
+    logRequests?: boolean;
+    /** Whether to log cache operations (defaults to false) */
+    logCache?: boolean;
+    /** Whether to log WebSocket events (defaults to false) */
+    logWebSocket?: boolean;
+    /** Custom logger function */
+    logger?: (_level: LogLevel, _message: string, _data?: unknown) => void;
+}
+/**
+ * The numbers the retry backoff is computed from.
+ *
+ * There is no `retryCondition` here any more. It was a predicate over
+ * `(error, attempt)`, which is structurally unable to see the request — so the
+ * only rule it could express is "is this error retryable", and the rule that
+ * matters is "may this request be sent twice". That question, and the answer,
+ * live in `RetryPolicy` (`http/retry-policy.ts`).
+ */
+interface RetryConfig {
+    /** Maximum number of attempts, including the first. */
+    maxAttempts: number;
+    /** Base delay between retries in milliseconds */
+    baseDelay: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelay: number;
+    /** Backoff factor for exponential backoff */
+    backoffFactor: number;
+    /** Whether to add jitter to retry delays */
+    jitter: boolean;
+}
+interface RequestConfig {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request URL */
+    url: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body */
+    body?: unknown;
+    /** Query parameters */
+    params?: Record<string, unknown>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Whether to retry this request on failure */
+    retryable?: boolean;
+    /** Abort signal for canceling requests */
+    signal?: AbortSignal;
+    /** Additional metadata for the request */
+    metadata?: Record<string, unknown>;
+}
+interface ApiResponse<T = unknown> {
+    /**
+     * The response body exactly as the route's contract declares it —
+     * `{ data }`, `{ data, page }`, `{ data, page, meta }` or `{ empty }`.
+     *
+     * Named `body`, not `data`, because the envelope's own key is `data`: the
+     * incumbent `response.data.data` read like a typo and was one 33 times, in
+     * six methods that read a key the server never sent. One `data` in the
+     * spelling means `readPayload(response.body)` is the only way to reach a
+     * payload (`INV-API-CLIENT-IS-DERIVED`).
+     */
+    body: T;
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Request configuration that generated this response */
+    config: RequestConfig;
+    /** Whether this response came from cache */
+    fromCache?: boolean;
+    /** Cache metadata */
+    cacheMetadata?: {
+        key: string;
+        timestamp: number;
+        ttl: number;
+    };
+}
+interface BrowserConfig {
+    /**
+     * Whether requests the client sends from a web page carry the browser's cookies to another
+     * origin (defaults to `false`).
+     *
+     * `false` — and leaving it out, or writing `undefined` — sends every request with
+     * `credentials: 'same-origin'`: nothing to another origin, and a same-origin request — the API
+     * behind a proxy on your own host — sent as the platform's own `fetch` would send it. `true`
+     * sends it with `credentials: 'include'`, which a browser completes only when the answer names
+     * your page's origin in `Access-Control-Allow-Origin` (not `*`) and carries
+     * `Access-Control-Allow-Credentials: true`. The RelyIO API authenticates with your API key and
+     * reads no cookie, so set `true` only for a server of your own in front of it that does.
+     *
+     * Applied only in a web page. On a server, in an edge runtime or in a Web Worker the client sets
+     * no `credentials` mode at all, whatever this says.
+     */
+    includeCredentials?: boolean;
+    /** Whether to use relative URLs for same-origin requests (defaults to false) */
+    useRelativeUrls?: boolean;
+    /** Custom CORS error handling */
+    onCorsError?: (_error: Error, _context: unknown) => void;
+}
+type CacheStrategy = 'memory' | 'persistent' | 'network-first' | 'cache-first' | 'stale-while-revalidate';
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type Environment = 'development' | 'staging' | 'production';
+/**
+ * `T` once its defaults are applied: every field present, except the ones named in `NoDefault`,
+ * which stay as optional as `T` declares them because nothing stands in for them.
+ */
+type WithDefaults<T, NoDefault extends keyof T = never> = Required<Omit<T, NoDefault>> & Pick<T, NoDefault>;
+/**
+ * The options with no default, absent from a merged configuration until the caller gives one.
+ * `fetch` among them: absent means the runtime's own, and that is read per request rather than
+ * captured here.
+ */
+type UndefaultedOption = 'apiKey' | 'dataset' | 'locale' | 'dev' | 'fetch';
+/** The options that are themselves bags of options, each merged field by field. */
+type OptionBag = 'browser' | 'cache' | 'realtime' | 'debug';
+/**
+ * The fields of each bag with no default, absent from a merged configuration until the caller gives
+ * one — and the fields of a bag `updateConfig()` can clear with `null`.
+ */
+interface UndefaultedField {
+    browser: 'onCorsError';
+    cache: never;
+    realtime: 'wsUrl';
+    debug: 'logger';
+}
+/**
+ * The value each option takes when the caller gives none, down to each field of each bag — so a
+ * field of a merged configuration that has a default is never `undefined`, and a reader does not
+ * restate the default. A field with no default (`onCorsError`, `wsUrl`, `logger`) is named in
+ * {@link UndefaultedField}; a field added to a bag without one fails to compile at
+ * {@link DEFAULT_CONFIG} until it gets a default or a name there.
+ */
+type ConfigDefaults = WithDefaults<Omit<RelyIOConfig, UndefaultedOption | OptionBag>> & {
+    browser: WithDefaults<BrowserConfig, UndefaultedField['browser']>;
+    cache: WithDefaults<CacheConfig, UndefaultedField['cache']>;
+    realtime: WithDefaults<RealtimeConfig, UndefaultedField['realtime']>;
+    debug: WithDefaults<DebugConfig, UndefaultedField['debug']>;
+};
+/** The configuration a client runs on: each option the caller gave, and its default where not. */
+type MergedRelyIOConfig = ConfigDefaults & Pick<RelyIOConfig, UndefaultedOption>;
+
+/**
+ * Base error class for all RelyIO SDK errors
+ * Provides consistent error handling, context tracking, and retry logic
+ */
+declare abstract class SDKError extends Error {
+    /** Unique error code for programmatic error handling */
+    abstract readonly code: string;
+    /** Whether this error is retryable */
+    abstract readonly retryable: boolean;
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    /** Original error that caused this error */
+    readonly cause?: Error;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    /** Timestamp when the error occurred */
+    readonly timestamp: number;
+    constructor(message: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for logging and debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        statusCode: number | undefined;
+        retryable: boolean;
+        context: Record<string, unknown> | undefined;
+        timestamp: number;
+        stack: string | undefined;
+    };
+    /**
+     * Get a user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Get detailed error information for debugging
+     */
+    getDebugInfo(): string;
+    /**
+     * Check if this error is of a specific type
+     */
+    isType(errorType: string): boolean;
+    /**
+     * Create a new error with additional context
+     */
+    withContext(context: Record<string, unknown>): this;
+}
+
+/**
+ * Validation errors and related interfaces.
+ *
+ * `SchemaValidationError`, `RequiredFieldError` and `InvalidFieldTypeError` were deleted by
+ * REL-1471: nothing constructed them. The API refuses content the schema does not accept with one
+ * code, `CONTENT_INVALID`, whose `details.issues` name each field and its problem — the mapper
+ * throws `ValidationError` for it, and a missing required field or a value of the wrong type is a
+ * `violations` entry whose `code` says which.
+ */
+interface ValidationViolation {
+    field: string;
+    message: string;
+    code: string;
+    value?: unknown;
+    path?: string[];
+}
+declare abstract class BaseValidationError extends SDKError {
+    readonly retryable = false;
+    readonly violations: ValidationViolation[];
+    /**
+     * @param context - Carried beside `violations`. The mapper passes the refusal body as
+     *   `context.response`, as it does for every other contract code, so a consumer that hands the
+     *   service's own words on can read them here too.
+     */
+    constructor(message?: string, violations?: ValidationViolation[], statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+    /**
+     * Get violations for a specific field
+     */
+    getViolationsForField(fieldName: string): ValidationViolation[];
+    /**
+     * Check if a specific field has validation errors
+     */
+    hasFieldError(fieldName: string): boolean;
+    /**
+     * Get all validation messages as a formatted string
+     */
+    getFormattedMessages(): string;
+}
+declare class ValidationError extends BaseValidationError {
+    readonly code = "VALIDATION_ERROR";
+}
+declare class InvalidPayloadError extends BaseValidationError {
+    readonly code = "INVALID_PAYLOAD";
+    constructor(message?: string, violations?: ValidationViolation[], cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+
+/**
+ * Core type definitions for the RelyIO SDK
+ */
+
+/**
+ * Base interface for all content items
+ * Matches the actual RelyIO API structure with _metadata object
+ */
+interface BaseContent {
+    /**
+     * What the read reports about the entry beside its fields: the committed document's
+     * `EntryMetadata`, and nothing added to it. A `sourceDatasetId` was declared here for an entry
+     * inherited from a linked dataset's source; no read sends one.
+     */
+    _metadata: EntryMetadata;
+}
+/**
+ * Whether `T` declares no field: `BaseContent`, the entry of a client with no schema registered.
+ *
+ * Every input that names fields — a condition, a sort, a selection, a write — takes any name then,
+ * because nothing declares which exist; the API checks them against the deployed schema. Before
+ * REL-1406 only `where` asked, so the others took no field at all from an unregistered client.
+ */
+type DeclaresNoField<T> = [Exclude<keyof T, '_metadata'>] extends [never] ? true : false;
+/**
+ * The value a `where` condition compares a field against: one of the values the field holds.
+ *
+ * Not the field's read type. The REST dialect (`fromRestWhere` in `@relyio/entry-reads`) reads a
+ * bare value as `eq`, an array as `in` and an object as operators — refusing an object with none —
+ * and drops `null`. So a list field (`tags`) is matched by one of its items, a reference by the
+ * target's id, and a component or an expanded entry is never a value to send.
+ */
+type WhereScalar<V> = Exclude<V extends readonly (infer Item)[] ? Item : V, null | undefined | object>;
+/** One field's condition: a value (`eq`), a list of values (`in`), or operators. */
+type WhereFieldCondition<V> = WhereScalar<V> | WhereScalar<V>[] | WhereOperator<WhereScalar<V>>;
+/**
+ * Query conditions for filtering content: conditions on the fields the content type declares.
+ *
+ * Typed by the content type's fields where a schema types the client: each key is a declared field
+ * and each value one of that field's values. Untyped (`BaseContent`, which declares no fields), any
+ * field name is accepted — nothing declares which exist.
+ *
+ * Nothing under `_metadata` is a field. This type used to accept `{ _metadata: { status } }`, and
+ * the API filters on no `_metadata` key: measured through a real request (REL-1413), that condition
+ * answered `500 INTERNAL_ERROR` and a dotted `_metadata.status` an empty page. A typed client is now
+ * refused at compile time, and every client before sending (`refuseMetadataConditions`).
+ */
+type WhereClause<T extends BaseContent = BaseContent> = DeclaresNoField<T> extends true ? {
+    [field: string]: unknown;
+} : {
+    [K in Exclude<keyof T, '_metadata'>]?: WhereFieldCondition<T[K]>;
+};
+/**
+ * Query operators for advanced filtering
+ */
+interface WhereOperator<T = unknown> {
+    /** Equals */
+    $eq?: T;
+    /** Not equals */
+    $ne?: T;
+    /** Greater than */
+    $gt?: T;
+    /** Greater than or equal */
+    $gte?: T;
+    /** Less than */
+    $lt?: T;
+    /** Less than or equal */
+    $lte?: T;
+    /** In array */
+    $in?: T[];
+    /** Not in array */
+    $nin?: T[];
+    /** Contains (for strings) */
+    $contains?: string;
+    /** Starts with (for strings) */
+    $startsWith?: string;
+    /** Ends with (for strings) */
+    $endsWith?: string;
+    /** Regular expression match */
+    $regex?: string;
+    /** Exists (field is not null/undefined) */
+    $exists?: boolean;
+}
+/**
+ * Sort options for query results: by a key `T` declares, or by any field where it declares none.
+ */
+type SortOptions<T extends BaseContent = BaseContent> = {
+    [K in DeclaresNoField<T> extends true ? string : keyof T]?: 'asc' | 'desc';
+};
+/**
+ * Query options for content requests
+ *
+ * `F` is the shape whose fields a condition or a sort names, which is the read's own except for an
+ * asset: its read adds the `file` and `urls` blocks beside the fields, and a condition on those
+ * would name no field — and would make an unregistered asset client refuse every field it was given.
+ */
+interface QueryOptions<T extends BaseContent = BaseContent, F extends BaseContent = T> {
+    /** Conditions to filter by */
+    where?: WhereClause<F>;
+    /** Fields to include in response: any, where nothing declares them */
+    select?: (DeclaresNoField<F> extends true ? string : keyof T)[];
+    /** Related content to include */
+    include?: string[];
+    /** Sort options */
+    sort?: SortOptions<F>;
+    /** Limit number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Cursor for cursor-based pagination */
+    cursor?: string;
+}
+/**
+ * The fields a write sends: the ones the content type declares, as it declares them — or, where
+ * nothing declares any (`BaseContent`, the entry of a client with no schema registered), any field.
+ * The API validates the body against the deployed schema, the only place those names exist.
+ *
+ * `Omit<BaseContent, '_metadata'>` declares no key at all, so before this every write from an
+ * unregistered client — `relyio.content('post').create({ title })`, the SDK without codegen — was
+ * TS2353, and so was every `batch()` operation, whose `content` is untyped for every client.
+ */
+type WriteFields<T extends BaseContent> = DeclaresNoField<T> extends true ? {
+    [field: string]: unknown;
+} : Omit<T, '_metadata'>;
+/**
+ * Content creation input - excludes metadata fields that are managed by the system
+ */
+type CreateInput<T extends BaseContent> = WriteFields<T> & {
+    /** Optional metadata that can be set during creation */
+    _metadata?: {
+        /** Parent ID for hierarchical content */
+        parentId?: string | null;
+        /** Content locale */
+        locale?: string;
+    };
+};
+/**
+ * Content update input - excludes system-managed metadata fields
+ */
+type UpdateInput<T extends BaseContent> = Partial<WriteFields<T>> & {
+    /** Optional metadata that can be updated */
+    _metadata?: {
+        /** Parent ID for hierarchical content */
+        parentId?: string | null;
+        /** Content locale */
+        locale?: string;
+    };
+};
+/**
+ * What the entry list serves — **read from the committed document**, not
+ * written down here.
+ *
+ * It used to be a hand-written `{ items, total?, hasMore, nextCursor }`, and
+ * every field of it was wrong after API2: the route is the cursor dialect, so
+ * the body is `{ data, page: { nextCursor, hasMore } }` and there is no total
+ * at all. `execute()` therefore resolved `result.items` — `undefined` — for
+ * every caller of the SDK's most-used method, and nothing could see it because
+ * the type said otherwise.
+ *
+ * Deriving it means the next dialect change is a compile error in user code
+ * rather than an `undefined` at runtime (`INV-API-CLIENT-IS-DERIVED`).
+ */
+type ContentQueryResult<T extends BaseContent = BaseContent> = Wire<'/v1/{contentType}', 'get', T>;
+/**
+ * A singleton as `GET /v1/singletons/{key}` serves it: its fields at the top level and
+ * `_metadata`, the document's `Singleton` rather than a second declaration of it.
+ */
+type SingletonContent = components['schemas']['Singleton'];
+/**
+ * Custom query definition
+ */
+interface CustomQuery<TVariables = unknown, TResponse = unknown> {
+    /** Query name */
+    name: string;
+    /** Query variables */
+    variables?: TVariables;
+    /** Expected response type */
+    response?: TResponse;
+}
+/**
+ * Content type schema information
+ */
+interface ContentTypeSchema {
+    /** Content type name */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Description */
+    description?: string;
+    /** Field definitions */
+    fields: FieldDefinition[];
+    /** Whether this content type is hierarchical */
+    hierarchical?: boolean;
+    /** Preview configuration */
+    preview?: {
+        select?: Record<string, string>;
+        prepare?: (_selection: Record<string, unknown>) => Record<string, unknown>;
+    };
+}
+/**
+ * Field definition for content types
+ */
+interface FieldDefinition {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: FieldTypeName;
+    /** Display title */
+    title?: string;
+    /** Field description */
+    description?: string;
+    /** Whether field is required */
+    required?: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Validation rules */
+    validation?: ValidationRule[];
+    /** Field options */
+    options?: FieldOptions;
+}
+/**
+ * Supported field type names (string identifiers)
+ */
+type FieldTypeName = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'text' | 'markdown' | 'richtext' | 'slug' | 'url' | 'email' | 'image' | 'file' | 'reference' | 'array' | 'object' | 'geopoint' | 'color';
+/**
+ * Field validation rules
+ */
+interface ValidationRule {
+    /** Rule type */
+    type: 'required' | 'min' | 'max' | 'pattern' | 'custom';
+    /** Rule value */
+    value?: unknown;
+    /** Error message */
+    message?: string;
+}
+/**
+ * Field-specific options
+ */
+interface FieldOptions {
+    /** For array fields */
+    of?: FieldDefinition;
+    /** For reference fields */
+    to?: string | string[];
+    /** For string fields */
+    list?: string[];
+    /** For number fields */
+    min?: number;
+    max?: number;
+    /** For image/file fields */
+    accept?: string[];
+    /** For rich text fields */
+    marks?: string[];
+    blocks?: string[];
+}
+/**
+ * Real-time event types
+ */
+type RealtimeEventType = 'created' | 'updated' | 'deleted' | 'published' | 'unpublished';
+/**
+ * Real-time event payload
+ */
+interface RealtimeEvent<T extends BaseContent = BaseContent> {
+    /** Event type */
+    type: RealtimeEventType;
+    /** Content type */
+    contentType: string;
+    /** Content item (for created/updated events) */
+    item?: T;
+    /** Content ID (for deleted events) */
+    id?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Event metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Subscription options
+ */
+interface SubscriptionOptions<T extends BaseContent = BaseContent> {
+    /** Content type to subscribe to */
+    contentType: string;
+    /** Filter conditions */
+    where?: WhereClause<T>;
+    /** Events to listen for */
+    events?: RealtimeEventType[];
+    /** Subscription metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Performance metrics
+ */
+interface PerformanceMetrics {
+    /** Request duration in milliseconds */
+    duration: number;
+    /** Request timestamp */
+    timestamp: number;
+    /** Request URL */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Response status code */
+    statusCode: number;
+    /** Whether response came from cache */
+    fromCache: boolean;
+    /** Cache hit ratio */
+    cacheHitRatio?: number;
+}
+
+export { type ApiPath as A, type BaseContent as B, type CreateInput as C, type DebugConfig as D, type Environment as E, type FieldTypeName as F, ValidationError as G, type MergedRelyIOConfig as H, InvalidPayloadError as I, type PathParamsOf as J, type FieldDefinition as K, type LogLevel as L, type MatchRouteOptions as M, type PerformanceMetrics as P, type QueryOptions as Q, type RelyIOConfig as R, SDKError as S, type UpdateInput as U, type ValidationRule as V, type Wire as W, type RelyIOConfigUpdate as a, type ApiMethod as b, type ApiSuccessBody as c, type RouteMatch as d, type WhereScalar as e, type WhereFieldCondition as f, type WhereClause as g, type WhereOperator as h, type SortOptions as i, type ContentQueryResult as j, type SingletonContent as k, type CustomQuery as l, matchRoute as m, type ContentTypeSchema as n, type FieldOptions as o, type RealtimeEventType as p, type RealtimeEvent as q, type SubscriptionOptions as r, type CacheConfig as s, type RealtimeConfig as t, type RequestConfig as u, type ApiResponse as v, type RetryConfig as w, type CacheStrategy as x, type ValidationViolation as y, BaseValidationError as z };