@relyio/sdk 0.2.0

package/dist/index-B-KiFHbx.d.ts

@@ -0,0 +1,2708 @@
+import { M as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, G as PathParamsOf, r as ApiResponse, W as Wire, q as RequestConfig, B as BaseContent, c as WhereClause, e as SortOptions, f as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, v as BaseValidationError, u as ValidationViolation, H as components, R as RelyIOConfig } from './index-BsUqCAu8.js';
+import { x as SchemaDefinition, y as SchemaContentTypeNames, a6 as InferContentType, K as SchemaAssetTypeNames, at as InferAssetType, z as SchemaSingletonNames, ac as InferSingleton, J as SchemaSettingsGroupNames, an as InferSettingsGroup, G as SchemaQueryNames, H as SchemaLocaleCodes } from './define-schema-DHvUCKwj.js';
+
+/**
+ * What a call site supplies beside the route it named.
+ *
+ * `path` is required exactly when the document's template has segments, and
+ * forbidden when it does not — so a call that forgot to scope a request, or one
+ * that scoped a request the route does not scope, is a compile error rather
+ * than a URL with a literal `{id}` in it.
+ */
+type SendOptions<P extends ApiPath, M extends ApiMethod<P>> = {
+    /** Query string values. The document declares none, so this stays untyped — see `api-routes.ts`. */
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** Request headers this call adds, e.g. `If-Match` / `Idempotency-Key` (API4). */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeout?: number;
+} & ([PathParamsOf<P, M>] extends [never] ? {
+    path?: never;
+} : {
+    path: PathParamsOf<P, M>;
+});
+/**
+ * Core HTTP client for the RelyIO SDK.
+ *
+ * `send` is **the** typed entry: it names a route by the path template the
+ * committed document declares, and returns that operation's body type with the
+ * payload typed as `T`. `readPayload` from `@relyio/api-contract/client` is
+ * then the one unwrap — there is no second spelling and no runtime test of
+ * which envelope arrived (`INV-API-CLIENT-IS-DERIVED`).
+ *
+ * The verb helpers below stay for the escape hatch `getHttpClient()` exposes;
+ * nothing inside the SDK uses them.
+ */
+declare class HttpClient {
+    private baseUrl;
+    private defaultHeaders;
+    private timeout;
+    private retryConfig;
+    private debug;
+    private logger?;
+    private config;
+    constructor(config: MergedRelyIOConfig);
+    /**
+     * Call a route the committed document declares, and get back the body that
+     * document says it serves.
+     */
+    send<P extends ApiPath, M extends ApiMethod<P>, T = unknown>(path: P, method: M, options: SendOptions<P, M>): Promise<ApiResponse<Wire<P, M, T>>>;
+    /**
+     * Call a route and return its payload — `send` plus the one unwrap, which is
+     * what all but a handful of call sites want.
+     */
+    fetchPayload<P extends ApiPath, M extends ApiMethod<P>, T = unknown>(path: P, method: M, options: SendOptions<P, M>): Promise<Wire<P, M, T> extends {
+        data: unknown;
+    } ? Wire<P, M, T>['data'] : never>;
+    /**
+     * Make an HTTP request with retry logic
+     */
+    request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make a GET request
+     */
+    get<T = unknown>(url: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * Make a POST request
+     */
+    post<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * Make a PUT request
+     */
+    put<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * Make a DELETE request
+     */
+    delete<T = unknown>(url: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * Make a PATCH request
+     */
+    patch<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * Set default headers for all requests
+     */
+    setDefaultHeaders(headers: Record<string, string>): void;
+    /**
+     * Set authentication token
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Get current default headers
+     */
+    getDefaultHeaders(): Record<string, string>;
+    /**
+     * Update base URL
+     */
+    setBaseUrl(baseUrl: string): void;
+    /**
+     * Get current base URL
+     */
+    getBaseUrl(): string;
+    private makeRequest;
+    /**
+     * Filter headers that browsers don't allow to be set manually
+     */
+    private filterHeadersForBrowser;
+    /**
+     * Prepare request body based on content type and environment
+     */
+    private prepareRequestBody;
+    private parseResponse;
+    private resolveUrl;
+    private mergeRequestConfig;
+    private buildQueryString;
+    private headersToObject;
+    private calculateRetryDelay;
+    private sleep;
+    private log;
+}
+
+/**
+ * Children population options
+ */
+interface ChildrenOptions {
+    /** Content types of children to include */
+    contentTypes?: string[];
+    /** Maximum children per entry */
+    limit?: number;
+    /** Recursion depth */
+    depth?: number;
+}
+/**
+ * Retained as an alias of {@link ContentQueryResult}.
+ *
+ * It used to add an optional `pagination: { page, pageSize, pageCount, total }`
+ * that the list route emitted only when `withCount` arrived — "a shape no
+ * generated type can describe", as that controller's own comment now puts it.
+ * API2 made the customer list the **cursor** dialect unconditionally
+ * (`INV-API-ONE-CUSTOMER-PAGE-DIALECT`), so no total reaches this surface and
+ * the extra member described a body the service cannot send.
+ */
+type ExtendedQueryResult<T extends BaseContent = BaseContent> = ContentQueryResult<T>;
+/**
+ * Fluent query builder for content operations
+ * Provides a chainable API for building complex content queries
+ *
+ * @example
+ * ```typescript
+ * const products = await client.content('product')
+ *   .query()
+ *   .where({ status: 'active' })
+ *   .locale('en')
+ *   .fields(['id', 'title', 'price'])
+ *   .include(['brand', 'categories'])
+ *   .sort({ title: 'asc' })
+ *   .limit(20)
+ *   .execute()
+ * ```
+ */
+declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly contentType;
+    private readonly defaultLocale?;
+    private queryOptions;
+    private localeValue?;
+    private localesArray?;
+    private fetchAllLocales;
+    private fieldsProjection?;
+    private childrenOptions?;
+    private pageNumber?;
+    private pageSizeValue?;
+    constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    /**
+     * Add where conditions to the query
+     */
+    where(conditions: WhereClause<T>): this;
+    /**
+     * Select specific fields to return
+     */
+    select(fields: (keyof T)[]): this;
+    /**
+     * Include related content in the response
+     */
+    include(relations: string[]): this;
+    /**
+     * Add sorting to the query
+     *
+     * @example
+     * ```typescript
+     * // Object format
+     * .sort({ createdAt: 'desc', title: 'asc' })
+     *
+     * // Field and direction format
+     * .sort('createdAt', 'desc')
+     * ```
+     */
+    sort(field: string, direction: 'asc' | 'desc'): this;
+    sort(sortOptions: SortOptions<T>): this;
+    /**
+     * Sort by a specific field in ascending order
+     */
+    sortAsc(field: keyof T | string): this;
+    /**
+     * Sort by a specific field in descending order
+     */
+    sortDesc(field: keyof T | string): this;
+    /**
+     * Limit the number of results
+     */
+    limit(count: number): this;
+    /**
+     * Set offset for pagination
+     */
+    offset(count: number): this;
+    /**
+     * Set cursor for cursor-based pagination
+     */
+    cursor(cursor: string): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code (e.g., 'en-US', 'de-DE', 'fr-FR')
+     *
+     * @example
+     * ```typescript
+     * // Fetch in Spanish
+     * .locale('es-ES')
+     * ```
+     */
+    locale(locale: string): this;
+    /**
+     * Fetch content in multiple specific locales
+     * Returns primary locale at top level, others in _metadata.localizations
+     *
+     * @param localeCodes - Array of locale codes to fetch
+     *
+     * @example
+     * ```typescript
+     * const product = await client.content('product')
+     *   .findById('prod_123')
+     *   .locales(['en-US', 'es-ES', 'de-DE'])
+     *   .execute()
+     *
+     * // Access: product.title (first locale)
+     * // Access: product._metadata.localizations['es-ES'].title
+     * ```
+     */
+    locales(localeCodes: string[]): this;
+    /**
+     * Fetch content in all available locales
+     * Returns default locale at top level, others in _metadata.localizations
+     *
+     * @example
+     * ```typescript
+     * const product = await client.content('product')
+     *   .findById('prod_123')
+     *   .allLocales()
+     *   .execute()
+     *
+     * // Access: product.title (default locale)
+     * // Access: product._metadata.localizations['es-ES'].title
+     * // Access: product._metadata.availableLocales
+     * ```
+     */
+    allLocales(): this;
+    /**
+     * Select specific fields to return (projection)
+     * @param fieldNames - Array of field names to include
+     *
+     * @example
+     * ```typescript
+     * .fields(['id', 'title', 'price', 'brand.name'])
+     * ```
+     */
+    fields(fieldNames: string[]): this;
+    /**
+     * Include children in results (for hierarchical content)
+     * @param options - Children options or boolean to enable with defaults
+     *
+     * @example
+     * ```typescript
+     * // Include all children
+     * .children(true)
+     *
+     * // Include with options
+     * .children({ contentTypes: ['variant'], limit: 10 })
+     * ```
+     */
+    children(options: ChildrenOptions | boolean): this;
+    /**
+     * Set page number for page-based pagination
+     * @param pageNum - Page number (1-based)
+     */
+    page(pageNum: number): this;
+    /**
+     * Set page size for page-based pagination
+     * @param size - Items per page
+     */
+    pageSize(size: number): this;
+    /**
+     * Execute the query and return all matching results
+     */
+    execute(): Promise<T[]>;
+    /**
+     * Execute the query and return the whole body — the items under `data`, the
+     * cursor facts under `page`.
+     */
+    executeWithMeta(): Promise<ContentQueryResult<T>>;
+    /**
+     * Execute the query and return a single result (first match)
+     */
+    first(): Promise<T | null>;
+    /**
+     * Get paginated results
+     */
+    paginate(limit?: number): Promise<ContentQueryResult<T>>;
+    /**
+     * Create an async iterator for streaming results
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * Execute the query and return all results as an array (for large datasets)
+     */
+    all(): Promise<T[]>;
+    /**
+     * Clone the query builder
+     */
+    clone(): ContentQueryBuilder<T>;
+    /**
+     * Get the current query options
+     */
+    getQueryOptions(): QueryOptions<T>;
+    /**
+     * Execute the query and return the whole body.
+     *
+     * Identical to {@link executeWithMeta} now that the list serves one shape;
+     * kept as the name callers already import.
+     */
+    executeWithMetaExtended(): Promise<ExtendedQueryResult<T>>;
+    /**
+     * `count()` and `exists()` are gone, and their absence is the honest answer
+     * rather than an omission (`INV-RD-CAPABILITY-IS-HONEST`).
+     *
+     * `count()` sent `withCount` and read `pagination.total`; API2 moved the
+     * customer list onto the **cursor** dialect, whose page facts are
+     * `{ nextCursor, hasMore }` and nothing else, so no total reaches this
+     * surface at all. Keeping the method would have meant either a request that
+     * always throws or a number assembled from a page the caller happened to
+     * fetch — a count of what was returned, presented as a count of what matched
+     * (rule 6). The plan's §3.3 listed `count` among six methods a type would
+     * repair; what the type actually shows is that the capability is no longer
+     * there. A caller that wants "is there at least one" fetches one and looks at
+     * `data.length`; a caller that wants a true total uses `POST /v1/search`,
+     * which is the offset dialect precisely because a facet-bearing result wants
+     * one (Decision 5).
+     */
+    /**
+     * Build query parameters for the HTTP request
+     */
+    private buildQueryParams;
+}
+/**
+ * Specialized query builder for finding by ID
+ */
+declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly contentType;
+    private readonly id;
+    private readonly defaultLocale?;
+    private includeRelations?;
+    private localeValue?;
+    private localesArray?;
+    private fetchAllLocales;
+    private childrenOptions?;
+    constructor(httpClient: HttpClient, contentType: string, id: string, defaultLocale?: string | undefined);
+    /**
+     * Include related content in the response
+     */
+    include(relations: string[]): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code (e.g., 'en-US', 'de-DE', 'fr-FR')
+     */
+    locale(locale: string): this;
+    /**
+     * Fetch content in multiple specific locales
+     * Returns primary locale at top level, others in _metadata.localizations
+     *
+     * @param localeCodes - Array of locale codes to fetch
+     */
+    locales(localeCodes: string[]): this;
+    /**
+     * Fetch content in all available locales
+     * Returns default locale at top level, others in _metadata.localizations
+     */
+    allLocales(): this;
+    /**
+     * Include children in results (for hierarchical content)
+     * @param options - Children options or boolean to enable with defaults
+     */
+    children(options: ChildrenOptions | boolean): this;
+    /**
+     * Execute the query and return the content item
+     */
+    execute(): Promise<T | null>;
+}
+
+/**
+ * API4's two request headers, exposed the way the SDK's ergonomics already
+ * expose everything else: as options on the call, not as raw headers.
+ *
+ * `apps/services/api` declares them on exactly six and seven routes
+ * respectively (`CONDITIONAL_WRITE_HEADERS` / `RETRYABLE_WRITE_HEADERS` in that
+ * service's `contract/routes.ts`), and the API4 closeout is explicit that the
+ * ten `/file/*` routes and `POST /batch` declare **neither**, because they
+ * write through `@relyio/asset-files` and the batch planner and would silently
+ * ignore the header. So these options are on the six and seven methods that
+ * reach them and nowhere else: a client that could pass `ifMatch` to a route
+ * that ignores it has been told a lie no gate can catch
+ * (`INV-RD-CAPABILITY-IS-HONEST`).
+ *
+ * The tag itself comes from `X-Entity-Tag`, which the single-entity reads serve
+ * and the list routes deliberately do not — one header cannot name every
+ * member's per-locale version. `entityTagOf` reads it off the response the SDK
+ * already returns, so the round trip is "read one, write it back" with no
+ * assembly from `_metadata` in between
+ * (`INV-API-CONDITIONAL-WRITE-IS-REACHABLE`).
+ */
+interface RetryableWriteOptions {
+    /**
+     * A caller-chosen key that makes a retry of **this** write safe.
+     *
+     * A replay inside the service's window returns the original outcome rather
+     * than applying twice. The service derives that response from committed state
+     * pinned to the recorded version — it does not store bytes — so a replay after
+     * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
+     * answered from a stale copy.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * The six routes that additionally take `If-Match`.
+ *
+ * A creation has no prior entity to precondition on, so `POST /v1/{contentType}`
+ * takes `Idempotency-Key` and not this — which is why the two option types are
+ * separate rather than one optional-everything bag.
+ */
+interface ConditionalWriteOptions extends RetryableWriteOptions {
+    /**
+     * The `X-Entity-Tag` value a prior read served, sent back as `If-Match`.
+     *
+     * The write applies only if that locale of that entry is still at the version
+     * the tag names; otherwise the service refuses `RESOURCE_CONFLICT` and names
+     * both versions.
+     */
+    ifMatch?: string;
+}
+/**
+ * The entity tag a single-entity read served, or `undefined` where the route
+ * serves none — a list, or a cache HIT, which cannot know the current version
+ * and honestly says nothing rather than serving a stale tag.
+ */
+declare function entityTagOf(response: {
+    headers: Record<string, string>;
+}): string | undefined;
+
+/**
+ * Content fetch options
+ */
+interface ContentFetchOptions<T extends BaseContent = BaseContent> {
+    /** Filter conditions */
+    where?: WhereClause<T>;
+    /** Maximum entries to return */
+    limit?: number;
+    /** Entries to skip (offset pagination) */
+    offset?: number;
+    /** Sort configuration */
+    sort?: Record<string, 'asc' | 'desc'>;
+    /** Reference fields to populate */
+    include?: string[];
+    /** Locale for localized content */
+    locale?: string;
+    /** Fields to select (projection) */
+    fields?: string[];
+    /** Children population options */
+    children?: ChildrenOptions | boolean;
+}
+/**
+ * Content client for managing content operations
+ * Provides CRUD operations and query building for a specific content type
+ *
+ * @example
+ * ```typescript
+ * const products = client.content('product')
+ *
+ * // Query with fluent API
+ * const active = await products.query()
+ *   .where({ status: 'active' })
+ *   .locale('en')
+ *   .include(['brand'])
+ *   .limit(20)
+ *   .execute()
+ *
+ * // Quick fetch
+ * const all = await products.fetchAll()
+ * ```
+ */
+declare class ContentClient<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly contentType;
+    private readonly defaultLocale?;
+    constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    /**
+     * Create a new query builder for this content type
+     */
+    query(): ContentQueryBuilder<T>;
+    /**
+     * Find content by ID with fluent options
+     */
+    findById(id: string): ContentByIdBuilder<T>;
+    /**
+     * Fetch all content items
+     * @param locale - Optional locale for localized content
+     */
+    fetchAll(locale?: string): Promise<T[]>;
+    /**
+     * Fetch content with query options
+     */
+    fetch(options?: ContentFetchOptions<T>): Promise<T[]>;
+    /**
+     * Fetch a single content item by ID
+     * @param id - Entry ID or slug
+     * @param options - Fetch options (include, locale)
+     */
+    fetchOne(id: string, options?: {
+        include?: string[];
+        locale?: string;
+    }): Promise<T | null>;
+    /**
+     * Fetch one entry **and the entity tag that read served**.
+     *
+     * This is the read half of a conditional write. `X-Entity-Tag` is minted from
+     * `(entryUid, locale, localeVersion)` and is exactly what `If-Match` takes,
+     * so a caller reads here, edits, and hands the same string back to `update`
+     * — with nothing to assemble in between
+     * (`INV-API-CONDITIONAL-WRITE-IS-REACHABLE`).
+     *
+     * `entityTag` is `undefined` when the response came from the cache: a cached
+     * body cannot know the current version, and an absent tag beats a stale one
+     * that would refuse the next write.
+     */
+    fetchOneWithTag(id: string, options?: {
+        include?: string[];
+        locale?: string;
+    }): Promise<{
+        entry: T;
+        entityTag?: string;
+    }>;
+    /**
+     * Fetch the first content item matching the conditions
+     * @param where - Filter conditions
+     * @param locale - Optional locale
+     */
+    fetchFirst(where?: WhereClause<T>, locale?: string): Promise<T | null>;
+    /**
+     * Create a new content item
+     * @param data - Content data
+     * @param options - Create options (slug, locale, parentId, sortOrder)
+     */
+    create(data: CreateInput<T>, options?: {
+        slug?: string;
+        locale?: string;
+        parentId?: string;
+        sortOrder?: number;
+    } & RetryableWriteOptions): Promise<T>;
+    /**
+     * Update a content item by ID (partial update)
+     * @param id - Entry ID
+     * @param data - Fields to update
+     * @param options - Update options (slug, locale, parentId, sortOrder)
+     */
+    update(id: string, data: UpdateInput<T>, options?: {
+        slug?: string;
+        locale?: string;
+        parentId?: string;
+        sortOrder?: number;
+    } & ConditionalWriteOptions): Promise<T>;
+    /**
+     * Delete a content item by ID
+     */
+    delete(id: string, options?: ConditionalWriteOptions): Promise<void>;
+    /**
+     * Check if content exists by ID
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Get version history for one locale of an entry.
+     *
+     * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
+     * schema default, no fallback is applied, and a locale with no history returns an empty array
+     * rather than another locale's rows. Every row names the locale it belongs to.
+     */
+    versions(id: string, options?: {
+        limit?: number;
+        locale?: string;
+    }): Promise<Array<T & {
+        versionNumber: number;
+        locale: string;
+    }>>;
+    /**
+     * Get a specific version of an entry.
+     *
+     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
+     * different content in each one.
+     */
+    version(id: string, versionNumber: number, options?: {
+        locale?: string;
+    }): Promise<T | null>;
+    /**
+     * Revert one locale of an entry to a previous version.
+     *
+     * `locale` is **required**, and that is not a convention: versions are numbered per locale, so
+     * `versionNumber` alone is ambiguous, and defaulting it would silently revert the wrong
+     * translation. Only that locale's fields change — shared fields and every other locale are left
+     * untouched.
+     *
+     * The restore is validated as strictly as a publish, so it cannot publish invalid content, and it
+     * records a new version of its own rather than rewinding the counter — so the revert is auditable
+     * and itself reversible.
+     */
+    restore(id: string, versionNumber: number, locale: string, options?: ConditionalWriteOptions): Promise<T>;
+    /**
+     * Get children of a hierarchical entry
+     * @param id - Parent entry ID
+     * @param options - Fetch options
+     */
+    children(id: string, options?: {
+        depth?: number;
+        include?: string[];
+        locale?: string;
+    }): Promise<T[]>;
+    /**
+     * Get the content type name
+     */
+    getContentType(): string;
+    /**
+     * Create a new ContentClient for a different content type
+     */
+    ofType<U extends BaseContent = BaseContent>(contentType: string): ContentClient<U>;
+    /**
+     * Create a new ContentClient with a different default locale
+     */
+    withLocale(locale: string): ContentClient<T>;
+    /**
+     * Get the current default locale
+     */
+    getDefaultLocale(): string | undefined;
+}
+
+/**
+ * Upload/processing error taxonomy (plan 17, 00b Step 4).
+ *
+ * A **thin customer-side mirror** of the realtime-contracts `FileErrorCode`
+ * (correction C6 — the SDK must not import the server/Studio contracts package).
+ * Keep the members in sync with `@relyio/realtime-contracts`.
+ */
+type FileErrorCode = 'UPLOAD_TOO_LARGE' | 'UNSUPPORTED_MIME' | 'DIMENSION_OUT_OF_RANGE' | 'ASPECT_RATIO' | 'CORRUPT_FILE' | 'UNSUPPORTED_CODEC' | 'IMAGES_LIMIT_EXCEEDED' | 'STREAM_ENCODE_FAILED' | 'SCAN_INFECTED' | 'INTERNAL';
+/**
+ * A failure during the upload protocol (presign / PUT / multipart / confirm) or
+ * surfaced by the server's processing pipeline. Carries a typed {@link FileErrorCode}
+ * and a `retriable` hint so callers (and `upload()`'s bounded auto-retry) can
+ * decide whether to retry on the same entry.
+ */
+declare class FileUploadError extends SDKError {
+    readonly code: FileErrorCode;
+    readonly retryable: boolean;
+    constructor(code: FileErrorCode, message: string, options?: {
+        retriable?: boolean;
+        statusCode?: number;
+        cause?: Error;
+    });
+    getUserMessage(): string;
+}
+/**
+ * Client-side file validation failure (MIME/size/etc.) raised **before** any
+ * bytes leave the machine (UX only — the server presign stays authoritative).
+ */
+declare class FileValidationError extends BaseValidationError {
+    readonly code = "FILE_VALIDATION_ERROR";
+    constructor(message: string, violations?: ValidationViolation[], cause?: Error);
+    getUserMessage(): string;
+}
+/** Constraints `validateFile` checks a file against (subset of the schema upload gate). */
+interface FileValidationConstraints {
+    /** Allowed MIME types (exact match). */
+    allowedMimeTypes?: string[];
+    /** Max size in bytes. */
+    maxSizeBytes?: number;
+}
+/**
+ * Validate a file against explicit constraints, returning typed violations.
+ *
+ * The customer SDK does not carry a `SchemaReader` (that lives in the Studio
+ * layer), so callers pass the constraints they want enforced client-side; the
+ * server presign remains the authority. Returns an empty array when valid.
+ */
+declare function validateFile(file: {
+    type?: string;
+    size?: number;
+}, constraints?: FileValidationConstraints): ValidationViolation[];
+
+/** Delivery visibility for a file binding (gateway-enforced, no byte relocation). */
+type AssetVisibility = 'public' | 'protected' | 'private';
+/** Binary lifecycle status — independent of the entry's publishing status. */
+type FileStatus = 'pending_upload' | 'uploading' | 'processing' | 'ready' | 'failed';
+/** Storage backend: `r2` = image + file kinds, `stream` = video kind. */
+type FileBackend = 'r2' | 'stream';
+/** Extracted media metadata (Phase 1 basics + Phase 2 enrichment, plans 15–19). */
+interface AssetFileExtracted {
+    width?: number;
+    height?: number;
+    format?: string;
+    duration?: number;
+    hasAlpha?: boolean;
+    isAnimated?: boolean;
+    orientation?: number;
+    placeholder?: string;
+    dominantColor?: string;
+    palette?: string[];
+    exif?: Record<string, unknown>;
+    video?: {
+        codec?: string;
+        bitrate?: number;
+        framerate?: number;
+        audioTracks?: unknown[];
+    };
+    pageCount?: number;
+    text?: string;
+    safety?: {
+        nsfwScore?: number;
+        flagged?: boolean;
+        categories?: string[];
+    };
+    [key: string]: unknown;
+}
+/** Customer-facing file binding block on an asset entry. */
+interface AssetFileBlock {
+    status: FileStatus;
+    backend: FileBackend;
+    fileName: string;
+    mimeType?: string | null;
+    size?: number | null;
+    /** Advisory client-computed SHA-256 (duplicate detection only). */
+    hash?: string | null;
+    visibility: AssetVisibility;
+    extracted?: AssetFileExtracted;
+    /** 0..1 normalized smart-crop anchor (written by plan 18). */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Phase-2 enrichment status — independent of `status` (plan 15). */
+    enrichment?: {
+        status: 'pending' | 'running' | 'complete' | 'partial' | 'failed';
+    };
+    /** File-kind malware scan status (plan 19). */
+    scan?: {
+        status: 'pending' | 'clean' | 'infected' | 'error' | 'skipped';
+    };
+    /** Processing progress (e.g. video encoding %) + terminal error. */
+    processing?: {
+        stage?: string;
+        progress?: number;
+        error?: {
+            code?: string;
+            message?: string;
+            retriable?: boolean;
+        };
+    };
+    /** Video playback readiness. */
+    playback?: {
+        ready?: boolean;
+    };
+}
+/**
+ * Computed gateway delivery URLs (the reserved `urls` key). Always served from
+ * `cdn.relyio.net`. Image bindings expose `original` + `variants`; video bindings
+ * expose `playback`/`poster`/`download`. Present only when `file.status` is
+ * `ready` — otherwise the response omits `urls` and callers read `file.status`.
+ */
+interface AssetUrls {
+    /** Image: canonical original delivery URL. */
+    original?: string;
+    /** Image: variant id → delivery URL map. */
+    variants?: Record<string, string>;
+    /** Video: HLS/DASH manifest URL. */
+    playback?: string;
+    /** Video: poster image URL. */
+    poster?: string;
+    /** Video: downloadable MP4 URL (when enabled). */
+    download?: string;
+    [key: string]: unknown;
+}
+/**
+ * An asset entry response: schema fields at the top level plus the reserved
+ * `file` + `urls` blocks and `_metadata`. `T` carries the inferred field shape.
+ */
+type AssetEntryResponse<T extends BaseContent = BaseContent> = T & {
+    file?: AssetFileBlock;
+    urls?: AssetUrls;
+};
+/** Request a single upload target for the binding. */
+interface PresignInput {
+    /** Original file name (required). */
+    fileName: string;
+    /** MIME type the client will upload with. */
+    contentType?: string;
+    /** File size in bytes (early upload-gate validation). */
+    size?: number;
+    /** Locale to target for file-localized asset types. */
+    locale?: string;
+    /** Advisory client-computed SHA-256 (duplicate detection). */
+    hash?: string;
+}
+/** Single upload target returned by `presign`. */
+interface PresignResult {
+    backend: FileBackend;
+    /** `put` = single PUT / Stream POST; `multipart` = resumable R2 session (plan 17). */
+    mode?: 'put' | 'multipart';
+    /** R2 presigned PUT (image/file) or Stream direct-creator URL (video). */
+    uploadUrl?: string;
+    method: 'PUT' | 'POST';
+    headers?: Record<string, string>;
+    /** Object key for the binding — present for R2 (needed to drive multipart). */
+    objectKey?: string;
+    storageVersion?: number;
+    /** Multipart upload id — present only for `mode: 'multipart'`. */
+    uploadId?: string;
+    /** Multipart part size in bytes — present only for `mode: 'multipart'`. */
+    partSize?: number;
+    expiresAt: string;
+    locale?: string;
+}
+/** Result of opening a multipart session (`file(uid).createMultipart()`). */
+interface MultipartCreateResult {
+    uploadId: string;
+    objectKey: string;
+    partSize: number;
+    storageVersion: number;
+    locale?: string;
+}
+/** A single uploaded part (`{ PartNumber, ETag }` ordering for `complete`). */
+interface MultipartPart {
+    partNumber: number;
+    etag: string;
+    size?: number;
+}
+/** Target a multipart session in subsequent ops. */
+interface MultipartTarget {
+    uploadId: string;
+    objectKey: string;
+    locale?: string;
+}
+/** Upload progress tick handed to `.onProgress()`. */
+interface UploadProgress {
+    /** `upload` for client → storage bytes. */
+    phase: 'upload';
+    /** Bytes transferred so far. */
+    loaded: number;
+    /** Total bytes (when known). */
+    total: number;
+    /** 0–100 integer. */
+    progress: number;
+}
+/** Acknowledge a completed client upload. */
+interface ConfirmInput {
+    locale?: string;
+    hash?: string;
+}
+/** Result of `confirm`. */
+interface ConfirmResult {
+    accepted: boolean;
+}
+/** Resolve a single gateway delivery URL. */
+interface ResolveUrlInput {
+    locale?: string;
+    /** Named image variant id. */
+    variantId?: string;
+    /** Video delivery target. */
+    purpose?: 'playback' | 'poster' | 'download';
+}
+/** Result of `url`. `expiresAt` is omitted for `public` bindings. */
+interface ResolveUrlResult {
+    url: string;
+    expiresAt?: string;
+}
+/** Options when creating an asset entry. */
+interface CreateAssetOptions {
+    slug?: string;
+    locale?: string;
+    /** Original file name (also settable at presign). */
+    fileName?: string;
+    /** Initial delivery visibility (default `public`). */
+    visibility?: AssetVisibility;
+    /** Auto-publish the entry when the file becomes ready (default `true`). */
+    publish?: boolean;
+}
+/** Options for {@link AssetClient.update}: the entry route takes both API4 headers. */
+type UpdateAssetOptions = {
+    slug?: string;
+    locale?: string;
+} & ConditionalWriteOptions;
+/** Options for {@link AssetFileBuilder.waitUntilReady}. */
+interface WaitUntilReadyOptions {
+    /** Locale of the binding to watch. */
+    locale?: string;
+    /** Total time to wait before giving up (ms). Default 60000. */
+    timeoutMs?: number;
+    /** Delay between polls (ms). Default 1500. */
+    pollIntervalMs?: number;
+}
+/**
+ * Operations on a single asset entry's file binding, backed by the
+ * `/{assetType}/{entryUid}/file/*` routes (plan 06 §2).
+ */
+declare class AssetFileBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly assetType;
+    private readonly entryUid;
+    private readonly defaultLocale?;
+    constructor(httpClient: HttpClient, assetType: string, entryUid: string, defaultLocale?: string | undefined);
+    /**
+     * The path parameters every `/file/*` route on this builder takes.
+     *
+     * The path *template* is the document's; only these two values are the
+     * builder's, so a route that gains or loses a segment is a compile error here
+     * rather than a hand-built string that silently misses.
+     */
+    private get target();
+    private withLocale;
+    /**
+     * Issue a single upload target — an R2 presigned PUT (image/file) or a
+     * Cloudflare Stream direct-creator URL (video). Resumable multipart is plan 17.
+     */
+    presign(input: PresignInput): Promise<PresignResult>;
+    /**
+     * Acknowledge a completed client upload (kicks off the fast-path intake for
+     * R2; a no-op for Stream, whose readiness is webhook-driven).
+     */
+    confirm(input?: ConfirmInput): Promise<ConfirmResult>;
+    /** Open an R2 multipart session for a large file (standalone of `presign`). */
+    createMultipart(input: PresignInput): Promise<MultipartCreateResult>;
+    /** Presign a single part PUT (1-based `partNumber`). */
+    signPart(target: MultipartTarget & {
+        partNumber: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** List parts already uploaded (cross-session resume). */
+    listParts(target: MultipartTarget): Promise<MultipartPart[]>;
+    /** Finalize a multipart session. */
+    completeMultipart(target: MultipartTarget & {
+        parts: MultipartPart[];
+    }): Promise<{
+        ok: boolean;
+        etag?: string;
+    }>;
+    /** Abort a multipart session, freeing staged parts. */
+    abortMultipart(target: MultipartTarget): Promise<{
+        aborted: boolean;
+    }>;
+    /**
+     * Resolve a single gateway delivery URL for the requested locale/variant/purpose.
+     * Throws if the binding is not `ready`.
+     */
+    url(input?: ResolveUrlInput): Promise<ResolveUrlResult>;
+    /**
+     * Update the binding's delivery visibility (token-based; no byte relocation —
+     * a downgrade purges the gateway cache). Returns the refreshed asset entry.
+     */
+    updateVisibility(visibility: AssetVisibility, options?: {
+        locale?: string;
+    }): Promise<AssetEntryResponse<T>>;
+    /**
+     * Set the binding's normalized (0..1, origin top-left) smart-crop focal point
+     * (plan 18) so `cover`/`crop` variants frame the subject. Per locale for
+     * file-localized asset types; token-based (no byte change). Returns the
+     * refreshed asset entry.
+     */
+    setFocalPoint(focalPoint: {
+        x: number;
+        y: number;
+    }, options?: {
+        locale?: string;
+    }): Promise<AssetEntryResponse<T>>;
+    /**
+     * Remove the file binding, clean up the underlying bytes, and purge the
+     * gateway cache. The asset entry itself is preserved.
+     */
+    delete(options?: {
+        locale?: string;
+    }): Promise<void>;
+    /**
+     * Poll the asset entry until its file binding reaches `ready` (resolves with
+     * the ready entry) or `failed` (throws). Times out after `timeoutMs`.
+     */
+    waitUntilReady(options?: WaitUntilReadyOptions): Promise<AssetEntryResponse<T>>;
+}
+/**
+ * High-level one-shot upload: create draft entry → presign → PUT bytes →
+ * confirm → (optionally) wait for `ready`. Handles the common image/file flow
+ * (single R2 PUT). For advanced/resumable flows (large files, video tus,
+ * progress) use the lower-level `file(uid)` builder — full upload resilience is
+ * plan 17.
+ */
+declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly assetType;
+    private readonly file;
+    private readonly defaultLocale?;
+    private _fileName?;
+    private _visibility?;
+    private _locale?;
+    private _publish?;
+    private _content;
+    private _slug?;
+    private _waitForReady;
+    private _waitOptions;
+    private _onProgress?;
+    private _validate?;
+    private _maxPartRetries;
+    constructor(httpClient: HttpClient, assetType: string, file: Blob, defaultLocale?: string | undefined);
+    /** Subscribe to client → storage upload progress (single PUT + multipart). */
+    onProgress(callback: (_progress: UploadProgress) => void): this;
+    /**
+     * Validate the file client-side (UX only) against explicit constraints before
+     * any bytes leave the machine. Rejects instantly with a {@link FileValidationError}.
+     */
+    validate(constraints: FileValidationConstraints): this;
+    /** Bounded per-part retry attempts for multipart (default 3). */
+    maxPartRetries(attempts: number): this;
+    /** Set the original file name (defaults to `file.name` for `File` inputs). */
+    filename(name: string): this;
+    /** Set the initial delivery visibility (default `public`). */
+    visibility(visibility: AssetVisibility): this;
+    /** Target locale for file-localized asset types. */
+    locale(locale: string): this;
+    /** Suppress (or enable) auto-publish on ready. */
+    publish(publish: boolean): this;
+    /** Set the asset's metadata field values (e.g. `{ alt: '...' }`). */
+    content(content: Record<string, unknown>): this;
+    /** Set an explicit slug for the new entry. */
+    slug(slug: string): this;
+    /** Wait until the file binding becomes `ready` before resolving. */
+    waitForReady(options?: boolean | Omit<WaitUntilReadyOptions, 'locale'>): this;
+    /** Execute the full upload flow and resolve with the asset entry. */
+    execute(): Promise<AssetEntryResponse<T>>;
+    /** Single presigned PUT (≤ 50 MB / Stream POST). */
+    private uploadSingle;
+    /**
+     * Resumable R2 multipart: slice into `partSize` chunks, skip already-uploaded
+     * parts (resume via `list-parts`), PUT each remaining part with bounded retry,
+     * then `complete`. Aborts the session on unrecoverable failure.
+     */
+    private uploadMultipart;
+    /** PUT a single part, retrying transient failures up to `_maxPartRetries`. */
+    private putPartWithRetry;
+    private emitProgress;
+}
+/**
+ * Client for a single asset type. Mirrors {@link ContentClient} (CRUD + query
+ * over the same dynamic `/{assetType}` routes — assets are `entryType: 'asset'`
+ * entries) and adds the `file(uid)` sub-resource builder + an `upload()` helper.
+ */
+declare class AssetClient<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private readonly assetType;
+    private readonly defaultLocale?;
+    constructor(httpClient: HttpClient, assetType: string, defaultLocale?: string | undefined);
+    /** Create a query builder for this asset type. */
+    query(): ContentQueryBuilder<AssetEntryResponse<T>>;
+    /** Find an asset entry by id (or slug) with fluent options. */
+    findById(id: string): ContentByIdBuilder<AssetEntryResponse<T>>;
+    /** Fetch a single asset entry by id (or slug), or `null` if not found. */
+    fetchOne(id: string, options?: {
+        include?: string[];
+        locale?: string;
+    }): Promise<AssetEntryResponse<T> | null>;
+    /** Fetch the first asset entry matching the conditions, or `null`. */
+    fetchFirst(where?: WhereClause<AssetEntryResponse<T>>, locale?: string): Promise<AssetEntryResponse<T> | null>;
+    /**
+     * Create a new asset entry as a draft. The binary is uploaded separately via
+     * `file(uid)` (or use the high-level `upload()` helper), and the entry
+     * auto-publishes when its file becomes ready (unless `publish: false`).
+     */
+    create(data: CreateInput<T>, options?: CreateAssetOptions & RetryableWriteOptions): Promise<AssetEntryResponse<T>>;
+    /** Update an asset entry's metadata fields (and/or slug). */
+    update(id: string, data: UpdateInput<T>, options?: UpdateAssetOptions): Promise<AssetEntryResponse<T>>;
+    /** Delete an asset entry (cascades file-byte cleanup + gateway purge). */
+    delete(id: string, options?: ConditionalWriteOptions): Promise<void>;
+    /** Get the file sub-resource builder for a specific asset entry. */
+    file(entryUid: string): AssetFileBuilder<T>;
+    /** Start a high-level upload (create → presign → PUT → confirm). */
+    upload(file: Blob): AssetUploadBuilder<T>;
+    /** Get the asset type id. */
+    getAssetType(): string;
+    /** Get the current default locale. */
+    getDefaultLocale(): string | undefined;
+    /** Create a new AssetClient for this type with a different default locale. */
+    withLocale(locale: string): AssetClient<T>;
+}
+/**
+ * Narrow an entry (e.g. a populated reference from `include`) to an asset entry.
+ * Relies on the `_metadata.entryType` discriminator the API emits (plan 06).
+ *
+ * @example
+ * ```typescript
+ * const article = await relyio.content('article').fetchOne(id, { include: ['hero'] })
+ * if (isAssetEntry(article?.hero)) {
+ *   console.log(article.hero.urls?.original)
+ * }
+ * ```
+ */
+declare function isAssetEntry<T extends BaseContent = BaseContent>(entry: unknown): entry is AssetEntryResponse<T>;
+/**
+ * A reference field populated (via `include`) with a full asset entry. Identical
+ * to {@link AssetEntryResponse}; named for readability at reference call sites.
+ */
+type PopulatedAssetReference<T extends BaseContent = BaseContent> = AssetEntryResponse<T>;
+
+/**
+ * Singleton fetch options
+ */
+interface SingletonFetchOptions {
+    /** Locale for localized content */
+    locale?: string;
+    /** Reference fields to populate */
+    include?: string[];
+}
+/**
+ * Singleton client for managing singleton content operations
+ * Provides a fluent API for singleton operations following the same pattern as ContentClient
+ *
+ * @example
+ * ```typescript
+ * const homepage = await client.singleton('homepage')
+ *   .include(['featuredProducts', 'heroImage'])
+ *   .locale('en')
+ *   .fetch()
+ * ```
+ */
+declare class SingletonClient<T = unknown> {
+    private httpClient;
+    private singletonKey;
+    private includeFields?;
+    private localeValue?;
+    constructor(httpClient: HttpClient, singletonKey: string);
+    /**
+     * Include reference fields in the response
+     * @param fields - Reference field names to populate
+     */
+    include(fields: string[]): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code (e.g., 'en', 'de', 'fr')
+     */
+    locale(locale: string): this;
+    /**
+     * Fetch the singleton content
+     * @param options - Optional fetch options (alternative to fluent methods)
+     */
+    fetch(options?: SingletonFetchOptions): Promise<T | null>;
+    /**
+     * Fetch the singleton **and the entity tag that read served**, which is what
+     * `update`'s `ifMatch` takes (`INV-API-CONDITIONAL-WRITE-IS-REACHABLE`).
+     *
+     * `entityTag` is absent on a cache HIT: a cached body cannot know the current
+     * version, and a stale tag would refuse the very next write.
+     */
+    fetchWithTag(options?: SingletonFetchOptions): Promise<{
+        content: T;
+        entityTag?: string;
+    }>;
+    /**
+     * Update singleton content. The API auto-publishes on PATCH — there is no
+     * separate publish route; calling `update()` writes and publishes.
+     * @param data - The content fields to update
+     * @param locale - Optional locale for localized content (overrides fluent locale)
+     * @param options - `If-Match` / `Idempotency-Key`, both declared on this route
+     */
+    update(data: Partial<T>, locale?: string, options?: ConditionalWriteOptions): Promise<T>;
+    /**
+     * Check if singleton exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Get version history for one locale of the singleton.
+     *
+     * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
+     * schema default, no fallback is applied, and a locale with no history returns an empty array
+     * rather than another locale's rows. Every row names the locale it belongs to.
+     */
+    versions(options?: {
+        limit?: number;
+        locale?: string;
+    }): Promise<Array<T & {
+        versionNumber: number;
+        locale: string;
+    }>>;
+    /**
+     * Get a specific version of the singleton.
+     *
+     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
+     * different content in each one.
+     */
+    version(versionNumber: number, options?: {
+        locale?: string;
+    }): Promise<T | null>;
+    /**
+     * Get the singleton key
+     */
+    getSingletonKey(): string;
+    /**
+     * Reset fluent options for reuse
+     */
+    reset(): this;
+}
+
+/**
+ * Settings fetch options
+ */
+interface SettingsFetchOptions {
+    /** Locale for localized settings */
+    locale?: string;
+    /** Reference fields to populate */
+    include?: string[];
+}
+/**
+ * Settings client for managing settings group operations
+ * Provides a fluent API for settings operations following the same pattern as ContentClient
+ *
+ * @example
+ * ```typescript
+ * const emailConfig = await client.settings('email-config')
+ *   .include(['defaultTemplate'])
+ *   .locale('en')
+ *   .fetch()
+ * ```
+ */
+declare class SettingsClient<T = unknown> {
+    private readonly httpClient;
+    private readonly groupId;
+    private includeFields?;
+    private localeValue?;
+    constructor(httpClient: HttpClient, groupId: string);
+    /**
+     * Include reference fields in the response
+     * @param fields - Reference field names to populate
+     */
+    include(fields: string[]): this;
+    /**
+     * Set locale for localized settings
+     * @param locale - Locale code (e.g., 'en', 'de', 'fr')
+     */
+    locale(locale: string): this;
+    /**
+     * Fetch the settings group
+     * @param options - Optional fetch options (alternative to fluent methods)
+     */
+    fetch(options?: SettingsFetchOptions): Promise<T | null>;
+    /**
+     * Update settings group
+     * @param settings - The settings fields to update
+     * @param locale - Optional locale for localized settings (overrides fluent locale)
+     */
+    update(settings: Partial<T>, locale?: string, options?: ConditionalWriteOptions): Promise<T>;
+    /**
+     * Fetch the group **and the entity tag that read served**, which is what
+     * `update`'s and `reset`'s `ifMatch` take
+     * (`INV-API-CONDITIONAL-WRITE-IS-REACHABLE`).
+     */
+    fetchWithTag(options?: SettingsFetchOptions): Promise<{
+        settings: T;
+        entityTag?: string;
+    }>;
+    /**
+     * Reset settings to default values
+     * @param locale - Optional locale for localized settings
+     */
+    reset(locale?: string, options?: ConditionalWriteOptions): Promise<T>;
+    /**
+     * Get default settings for this group
+     */
+    getDefaults(): Promise<T>;
+    /**
+     * Check if settings group exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Get version history for one locale of the settings group.
+     *
+     * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
+     * schema default, no fallback is applied, and a locale with no history returns an empty array
+     * rather than another locale's rows. Every row names the locale it belongs to.
+     */
+    versions(options?: {
+        limit?: number;
+        locale?: string;
+    }): Promise<Array<T & {
+        versionNumber: number;
+        locale: string;
+    }>>;
+    /**
+     * Get a specific version of the settings.
+     *
+     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
+     * different content in each one.
+     */
+    version(versionNumber: number, options?: {
+        locale?: string;
+    }): Promise<T | null>;
+    /**
+     * Get the settings group ID
+     */
+    getGroupId(): string;
+    /**
+     * Reset fluent options for reuse
+     */
+    resetOptions(): this;
+}
+
+/**
+ * Search mode for content queries
+ */
+type SearchMode = 'keyword' | 'semantic' | 'hybrid';
+/**
+ * One search hit as the route emits it: the entry fields at the top level,
+ * plus optional score annotations. There is no per-item `data` wrapper.
+ */
+type SearchResultItem<T = unknown> = T & {
+    _score?: number;
+    _scoreBreakdown?: {
+        keyword?: number;
+        semantic?: number;
+    };
+    _highlights?: Record<string, string[]>;
+};
+/**
+ * Search response from API
+ */
+/**
+ * What `POST /v1/search` serves, **read from the committed document**.
+ *
+ * `{ data, page: { offset, limit, total }, meta }` — search is the offset
+ * dialect precisely because a facet-bearing result wants a total and an offset
+ * (Decision 5), and the facets, the strategy the engine chose and its warnings
+ * ride the declared `meta` sibling because none of them is an item or a page
+ * fact.
+ *
+ * The hand-written `{ items, total?, metadata? }` this replaces named three
+ * keys the route does not send. `SearchBuilder.items()` returned `undefined`
+ * and `.total` was always `undefined` — with nothing able to see either,
+ * because the type asserted them.
+ */
+type SearchResponse<T = unknown> = Wire<'/v1/search', 'post', SearchResultItem<T>>;
+/**
+ * Autocomplete suggestion
+ */
+interface AutocompleteSuggestion {
+    /** Suggested text */
+    text: string;
+    /** Highlighted version */
+    highlighted?: string;
+    /** Score */
+    score?: number;
+    /** Source entry ID */
+    entryId?: string;
+    /** Content type */
+    contentType?: string;
+}
+/**
+ * Autocomplete response
+ */
+/**
+ * What `POST /v1/search/autocomplete` serves. The suggestions are the
+ * collection's `data`; the query it completed and the field it matched on ride
+ * `meta`. Autocomplete is unpaginated, so its page reports `offset: 0` and a
+ * `total` equal to what it returned — the dialect is declared rather than
+ * omitted so one collection shape covers every list.
+ */
+type AutocompleteResponse = Wire<'/v1/search/autocomplete', 'post', AutocompleteSuggestion>;
+/**
+ * One similar-content hit as the route emits it — a flat entry, no `data` wrapper.
+ */
+type SimilarResult<T = unknown> = T & {
+    _score?: number;
+};
+/**
+ * Similar response
+ */
+/** What `POST /v1/search/similar` serves. */
+type SimilarResponse<T = unknown> = Wire<'/v1/search/similar', 'post', SimilarResult<T>>;
+/**
+ * Filter conditions for search
+ */
+type SearchFilter = Record<string, unknown>;
+/**
+ * Field projection for search results
+ */
+type SearchFields<T> = {
+    [K: string]: keyof T | string;
+};
+/**
+ * Fluent builder for search queries
+ *
+ * @example
+ * ```typescript
+ * const results = await relyio.search('wireless headphones')
+ *   .in('product')
+ *   .where({ status: 'active' })
+ *   .searchFields(['title', 'description'])
+ *   .limit(20)
+ *   .includeScore()
+ *   .execute()
+ * ```
+ */
+declare class SearchBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private query;
+    private searchOptions;
+    constructor(httpClient: HttpClient, query: string);
+    /**
+     * Search within a single content type
+     * @param contentType - Content type to search in
+     */
+    in<K extends string>(contentType: K): SearchBuilder<T>;
+    /**
+     * Search across multiple content types
+     * @param contentTypes - Array of content types or '*' for all
+     */
+    across(contentTypes: string[] | '*'): SearchBuilder<T>;
+    /**
+     * Add filter conditions
+     * @param conditions - Filter conditions
+     */
+    where(conditions: SearchFilter): this;
+    /**
+     * Specify which fields to search in
+     * @param fields - Field names to search
+     */
+    searchFields(fields: string[]): this;
+    /**
+     * Project specific fields in results
+     * @param projection - Field mapping
+     */
+    fields(projection: Record<string, string>): this;
+    /**
+     * Limit number of results
+     * @param count - Maximum results
+     */
+    limit(count: number): this;
+    /**
+     * Skip results for pagination
+     * @param count - Number to skip
+     */
+    offset(count: number): this;
+    /**
+     * Include relevance scores in results
+     */
+    includeScore(): this;
+    /**
+     * Include score breakdown explanation
+     */
+    explain(): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code
+     */
+    locale(locale: string): this;
+    /**
+     * Execute the search query
+     */
+    execute(): Promise<SearchResponse<T>>;
+    /**
+     * Execute and return just the items (convenience method)
+     */
+    items(): Promise<Array<SearchResultItem<T>>>;
+    /**
+     * Get the first result
+     */
+    first(): Promise<SearchResultItem<T> | null>;
+}
+/**
+ * Fluent builder for autocomplete queries
+ *
+ * @example
+ * ```typescript
+ * const suggestions = await relyio.autocomplete('wire')
+ *   .in('product')
+ *   .field('title')
+ *   .fuzzy()
+ *   .limit(10)
+ *   .execute()
+ * ```
+ */
+declare class AutocompleteBuilder {
+    private readonly httpClient;
+    private query;
+    private autocompleteOptions;
+    constructor(httpClient: HttpClient, query: string);
+    /**
+     * Autocomplete within a content type
+     * @param contentType - Content type to search
+     */
+    in(contentType: string): this;
+    /**
+     * Field to autocomplete on
+     * @param fieldName - Field name (supports nested like 'category.name')
+     */
+    field(fieldName: string): this;
+    /**
+     * Enable fuzzy matching for typo tolerance
+     */
+    fuzzy(): this;
+    /**
+     * Add filter conditions
+     * @param conditions - Filter conditions
+     */
+    where(conditions: SearchFilter): this;
+    /**
+     * Limit number of suggestions
+     * @param count - Maximum suggestions
+     */
+    limit(count: number): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code
+     */
+    locale(locale: string): this;
+    /**
+     * Execute the autocomplete query
+     */
+    execute(): Promise<AutocompleteResponse>;
+    /**
+     * Get just the suggestion texts
+     */
+    texts(): Promise<string[]>;
+}
+/**
+ * Fluent builder for finding similar content
+ *
+ * @example
+ * ```typescript
+ * const similar = await relyio.similar('entry_abc123')
+ *   .in('product')
+ *   .locale('fr-FR')
+ *   .limit(5)
+ *   .execute()
+ * ```
+ */
+declare class SimilarBuilder<T extends BaseContent = BaseContent> {
+    private readonly httpClient;
+    private sourceId;
+    private similarOptions;
+    constructor(httpClient: HttpClient, sourceId: string);
+    /**
+     * Find similar content within a content type
+     * @param contentType - Content type to search
+     */
+    in(contentType: string): this;
+    /**
+     * Add filter conditions
+     * @param conditions - Filter conditions
+     */
+    where(conditions: SearchFilter): this;
+    /**
+     * Limit number of results
+     * @param count - Maximum results
+     */
+    limit(count: number): this;
+    /**
+     * Set locale for localized content
+     * @param locale - Locale code
+     */
+    locale(locale: string): this;
+    /**
+     * Execute the similar query
+     */
+    execute(): Promise<SimilarResponse<T>>;
+    /**
+     * Get just the similar items
+     */
+    items(): Promise<Array<SimilarResult<T>>>;
+    /**
+     * Get the most similar item
+     */
+    first(): Promise<SimilarResult<T> | null>;
+}
+/**
+ * Search client providing fluent access to all search capabilities
+ *
+ * @example
+ * ```typescript
+ * const searchClient = new SearchClient(httpClient)
+ *
+ * // Full-text/hybrid search
+ * const products = await searchClient.search('wireless')
+ *   .in('product')
+ *   .limit(20)
+ *   .execute()
+ *
+ * // Autocomplete
+ * const suggestions = await searchClient.autocomplete('wire')
+ *   .in('product')
+ *   .field('title')
+ *   .execute()
+ *
+ * // Find similar
+ * const similar = await searchClient.similar('entry_123')
+ *   .in('product')
+ *   .execute()
+ * ```
+ */
+declare class SearchClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Start a search query
+     * @param query - Search query string
+     */
+    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    /**
+     * Start an autocomplete query
+     * @param query - Partial query to autocomplete
+     */
+    autocomplete(query: string): AutocompleteBuilder;
+    /**
+     * Find content similar to a given entry
+     * @param sourceId - Entry ID to find similar content for
+     */
+    similar<T extends BaseContent = BaseContent>(sourceId: string): SimilarBuilder<T>;
+    /**
+     * Quick search helper - searches all content types
+     * @param query - Search query
+     * @param limit - Max results (default 20)
+     */
+    global<T extends BaseContent = BaseContent>(query: string, limit?: number): Promise<SearchResponse<T>>;
+}
+
+/**
+ * HTTP methods supported in batch operations
+ */
+type BatchMethod = 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+/**
+ * A single batch operation
+ */
+interface BatchOperation {
+    /** Optional operation ID for tracking */
+    id?: string;
+    /** HTTP method */
+    method: BatchMethod;
+    /** Path to resource (e.g., '/product' or '/product/entry_123') */
+    path: string;
+    /** Request body for create/update operations */
+    body?: Record<string, unknown>;
+}
+/**
+ * Batch execution options
+ */
+interface BatchOptions {
+    /**
+     * If true, the batch runs as one transaction: every operation lands or none does.
+     *
+     * Requires that all operations be the same kind of write — one transaction cannot span two
+     * calls — so a batch mixing creates and deletes, or `update` and `replace`, is rejected with
+     * a 400 before anything is attempted.
+     *
+     * @default false
+     */
+    atomic?: boolean;
+    /**
+     * If true, run the checks and write nothing.
+     *
+     * Every entry is resolved, authorized and validated against its schema, so what passes a dry
+     * run is what a real write accepts.
+     *
+     * @default false
+     */
+    dryRun?: boolean;
+    /**
+     * If true, include full data in response
+     * @default true
+     */
+    returnData?: boolean;
+    /**
+     * If true, continue executing after failures (non-atomic mode only)
+     * @default true
+     */
+    continueOnError?: boolean;
+}
+/**
+ * Result of a single operation in the batch
+ */
+/**
+ * One batch item, **as the committed document describes the `multi` kind**.
+ *
+ * Read from `api-schema.ts` rather than imported from `@relyio/api-contract`
+ * for the same reason every other response type here is: the document is the
+ * one source, and a type this package publishes must resolve for a customer who
+ * installs `@relyio/sdk` alone. The contract's runtime half is bundled; its
+ * `.d.ts` is not something a consumer can reach.
+ *
+ * The hand-written version carried `success: boolean` and a per-item `status`
+ * number. Both are gone from the wire and neither loss is a gap: the presence
+ * of `error` already says whether the item succeeded (Decision 2, gap 16), and
+ * a sub-response carrying its own HTTP status is exactly the duplication
+ * `INV-API-NO-DUPLICATE-STATUS` removes. What replaced them says more, not
+ * less — `outcome` distinguishes `created` from `updated` from `unchanged`
+ * from `duplicate` from `skipped`, which one boolean never could.
+ */
+type BatchOperationResult = components['schemas']['MultiPayload']['results'][number];
+/** Summary of batch execution, from the contract. */
+type BatchSummary = components['schemas']['MultiSummary'];
+/**
+ * The full batch payload: `{ results, summary }`.
+ *
+ * `transactionId`, `executionTimeMs` and `dryRun` were named here and are not
+ * on the wire; nothing produced them and nothing could read them.
+ */
+type BatchResponse = components['schemas']['MultiPayload'];
+/**
+ * Fluent builder for batch operations
+ *
+ * @example
+ * ```typescript
+ * const result = await relyio.batch()
+ *   .create('product', { content: { title: 'iPhone', price: 999 } })
+ *   .update('product', 'entry_abc', { content: { price: 899 } })
+ *   .delete('product', 'entry_xyz')
+ *   .upsertSingleton('homepage', { content: { hero: 'Welcome!' } })
+ *   .execute({ atomic: true })
+ *
+ * console.log(result.summary.succeeded) // 4
+ * ```
+ */
+declare class BatchBuilder<TSchema = unknown> {
+    private readonly httpClient;
+    private operations;
+    private defaultOptions;
+    constructor(httpClient: HttpClient);
+    /**
+     * Add a create operation
+     * @param contentType - Content type to create
+     * @param data - Entry data with content field
+     * @param id - Optional operation ID for tracking
+     */
+    create<T extends BaseContent = BaseContent>(contentType: string, data: {
+        content: CreateInput<T>;
+        slug?: string;
+        locale?: string;
+        parentId?: string;
+        sortOrder?: number;
+    }, id?: string): this;
+    /**
+     * Add an update operation (partial update).
+     *
+     * The submitted fields are merged into the entry and the rest are left as they are. The merge is
+     * field-level rather than deep: sending an object-typed field replaces that field's whole value.
+     *
+     * @param contentType - Content type
+     * @param entryId - Entry ID to update
+     * @param data - Fields to update
+     * @param id - Optional operation ID for tracking
+     */
+    update<T extends BaseContent = BaseContent>(contentType: string, entryId: string, data: {
+        content?: UpdateInput<T>;
+        slug?: string;
+        locale?: string;
+        parentId?: string;
+        sortOrder?: number;
+    }, id?: string): this;
+    /**
+     * Add a replace operation (full replacement).
+     *
+     * The payload becomes the entry's content for the addressed locale: fields you do not send are
+     * cleared. Send the whole entry, or use {@link BatchClient.update} to change part of one.
+     *
+     * @param contentType - Content type
+     * @param entryId - Entry ID to replace
+     * @param data - Complete entry data
+     * @param id - Optional operation ID for tracking
+     */
+    replace<T extends BaseContent = BaseContent>(contentType: string, entryId: string, data: {
+        content: CreateInput<T>;
+        slug?: string;
+        locale?: string;
+        parentId?: string;
+        sortOrder?: number;
+    }, id?: string): this;
+    /**
+     * Add a delete operation
+     * @param contentType - Content type
+     * @param entryId - Entry ID to delete
+     * @param id - Optional operation ID for tracking
+     */
+    delete(contentType: string, entryId: string, id?: string): this;
+    /**
+     * Add a singleton upsert operation
+     * @param singletonKey - Singleton key
+     * @param data - Singleton content
+     * @param id - Optional operation ID for tracking
+     */
+    upsertSingleton(singletonKey: string, data: {
+        content: Record<string, unknown>;
+        locale?: string;
+    }, id?: string): this;
+    /**
+     * Add a singleton create operation (alias for upsert with POST)
+     * @param singletonKey - Singleton key
+     * @param data - Singleton content
+     * @param id - Optional operation ID for tracking
+     */
+    createSingleton(singletonKey: string, data: {
+        content: Record<string, unknown>;
+        locale?: string;
+    }, id?: string): this;
+    /**
+     * Add a raw operation (for advanced use cases)
+     * @param operation - The operation to add
+     */
+    raw(operation: BatchOperation): this;
+    /**
+     * Add multiple raw operations
+     * @param operations - Operations to add
+     */
+    rawMany(operations: BatchOperation[]): this;
+    /**
+     * Bulk create multiple entries of the same content type
+     * @param contentType - Content type
+     * @param items - Array of entry data
+     */
+    bulkCreate<T extends BaseContent = BaseContent>(contentType: string, items: Array<{
+        content: CreateInput<T>;
+        slug?: string;
+        locale?: string;
+        id?: string;
+    }>): this;
+    /**
+     * Bulk update multiple entries
+     * @param contentType - Content type
+     * @param updates - Array of { entryId, data } pairs
+     */
+    bulkUpdate<T extends BaseContent = BaseContent>(contentType: string, updates: Array<{
+        entryId: string;
+        data: {
+            content?: UpdateInput<T>;
+        };
+        id?: string;
+    }>): this;
+    /**
+     * Bulk delete multiple entries
+     * @param contentType - Content type
+     * @param entryIds - Entry IDs to delete
+     */
+    bulkDelete(contentType: string, entryIds: string[]): this;
+    /**
+     * Configure default options for execution
+     * @param options - Batch options
+     */
+    configure(options: BatchOptions): this;
+    /**
+     * Enable atomic mode (all-or-nothing)
+     */
+    atomic(): this;
+    /**
+     * Enable dry-run mode (validate without executing)
+     */
+    dryRun(): this;
+    /**
+     * Disable returning full data in response
+     */
+    noData(): this;
+    /**
+     * Stop on first error (non-atomic mode)
+     */
+    stopOnError(): this;
+    /**
+     * Get the current list of operations
+     */
+    getOperations(): BatchOperation[];
+    /**
+     * Get the number of operations
+     */
+    size(): number;
+    /**
+     * Clear all operations
+     */
+    clear(): this;
+    /**
+     * Clone the builder
+     */
+    clone(): BatchBuilder<TSchema>;
+    /**
+     * Execute the batch operations
+     * @param options - Override default options
+     */
+    execute(options?: BatchOptions): Promise<BatchResponse>;
+    /**
+     * Validate operations without executing (convenience for dry-run)
+     */
+    validate(): Promise<BatchResponse>;
+    /**
+     * Execute and throw if any operation failed
+     */
+    executeOrThrow(options?: BatchOptions): Promise<BatchResponse>;
+}
+/**
+ * Batch client for bulk operations
+ *
+ * @example
+ * ```typescript
+ * const batchClient = new BatchClient(httpClient)
+ *
+ * // Create a batch with fluent API
+ * const result = await batchClient.create()
+ *   .create('product', { content: { title: 'New Product' } })
+ *   .update('product', 'entry_123', { content: { price: 99 } })
+ *   .execute()
+ *
+ * // Quick bulk create
+ * const products = await batchClient.bulkCreate('product', [
+ *   { content: { title: 'Product 1' } },
+ *   { content: { title: 'Product 2' } },
+ * ])
+ * ```
+ */
+declare class BatchClient<TSchema = unknown> {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new batch builder
+     */
+    create(): BatchBuilder<TSchema>;
+    /**
+     * Quick bulk create entries
+     * @param contentType - Content type
+     * @param items - Array of entry data
+     * @param options - Batch options
+     */
+    bulkCreate<T extends BaseContent = BaseContent>(contentType: string, items: Array<{
+        content: CreateInput<T>;
+        slug?: string;
+        locale?: string;
+    }>, options?: BatchOptions): Promise<BatchResponse>;
+    /**
+     * Quick bulk update entries
+     * @param contentType - Content type
+     * @param updates - Array of updates
+     * @param options - Batch options
+     */
+    bulkUpdate<T extends BaseContent = BaseContent>(contentType: string, updates: Array<{
+        entryId: string;
+        data: {
+            content?: UpdateInput<T>;
+        };
+    }>, options?: BatchOptions): Promise<BatchResponse>;
+    /**
+     * Quick bulk delete entries
+     * @param contentType - Content type
+     * @param entryIds - Entry IDs to delete
+     * @param options - Batch options
+     */
+    bulkDelete(contentType: string, entryIds: string[], options?: BatchOptions): Promise<BatchResponse>;
+    /**
+     * Execute raw batch operations
+     * @param operations - Array of operations
+     * @param options - Batch options
+     */
+    execute(operations: BatchOperation[], options?: BatchOptions): Promise<BatchResponse>;
+}
+
+/**
+ * Fetch block for retrieving content
+ */
+interface FetchBlock {
+    /** Content type to fetch (mutually exclusive with singleton) */
+    contentType?: string;
+    /** Singleton key to fetch (mutually exclusive with contentType) */
+    singleton?: string;
+    /** Filter conditions */
+    where?: Record<string, unknown>;
+    /** Reference fields to populate */
+    include?: string | string[];
+    /** Sort specification */
+    sort?: Record<string, 'asc' | 'desc'>;
+    /** Maximum entries to return */
+    limit?: number;
+    /** Entries to skip */
+    offset?: number;
+}
+/**
+ * Aggregate block for computing metrics
+ */
+interface AggregateBlock {
+    /** Source content type or query reference */
+    source: string;
+    /** Field to group by */
+    by?: string | string[];
+    /** Metrics to compute */
+    metrics: Record<string, AggregateMetric>;
+}
+/**
+ * Aggregate metric definition
+ */
+interface AggregateMetric {
+    /** Aggregation function */
+    fn: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last';
+    /** Field to aggregate (optional for count) */
+    field?: string;
+}
+/**
+ * Search block for full-text/semantic search
+ */
+interface SearchBlock {
+    /** Content type to search */
+    contentType: string;
+    /** Search query (can use ${param} syntax) */
+    query: string;
+    /** Search mode */
+    mode?: 'keyword' | 'semantic' | 'hybrid';
+    /** Fields to search */
+    searchFields?: string[];
+    /** Additional filters */
+    where?: Record<string, unknown>;
+    /** Maximum results */
+    limit?: number;
+}
+/**
+ * Similar block for vector similarity search
+ */
+interface SimilarBlock {
+    /** Content type */
+    contentType: string;
+    /** Source entry ID */
+    source: string;
+    /** Minimum similarity threshold */
+    threshold?: number;
+    /** Additional filters */
+    where?: Record<string, unknown>;
+    /** Maximum results */
+    limit?: number;
+}
+/**
+ * Post-fetch filters with parameter support
+ */
+type FilterValue = string | number | boolean | {
+    eq?: unknown;
+    ne?: unknown;
+    gt?: unknown;
+    gte?: unknown;
+    lt?: unknown;
+    lte?: unknown;
+    in?: unknown[];
+    nin?: unknown[];
+    contains?: unknown;
+    startsWith?: string;
+    endsWith?: string;
+};
+/**
+ * Full-text search configuration
+ */
+interface FullTextConfig {
+    /** Search query (can use ${param} syntax) */
+    query: string;
+    /** Fields to search */
+    fields?: string[];
+    /** Minimum score threshold */
+    minScore?: number;
+}
+/**
+ * Ad-hoc query definition
+ */
+interface AdhocQueryDefinition {
+    /** Fetch block - retrieve content */
+    fetch?: FetchBlock;
+    /** Aggregate block - compute metrics */
+    aggregate?: AggregateBlock;
+    /** Search block - full-text/semantic search */
+    search?: SearchBlock;
+    /** Similar block - vector similarity */
+    similar?: SimilarBlock;
+    /** Field selection/transformation */
+    select?: Record<string, string>;
+    /** Post-fetch filters with parameter support */
+    filters?: Record<string, FilterValue>;
+    /** Full-text search configuration */
+    fullText?: FullTextConfig;
+    /** Cache policy */
+    cache?: {
+        ttl?: number;
+        strategy?: 'stale-while-revalidate' | 'cache-first' | 'network-first';
+    };
+}
+/**
+ * Ad-hoc query execution options
+ */
+interface AdhocQueryOptions {
+    /** Include debug information in response */
+    debug?: boolean;
+    /** Bypass cache for this request */
+    skipCache?: boolean;
+    /** Custom timeout in milliseconds (1000-60000) */
+    timeout?: number;
+}
+/**
+ * Query execution metadata
+ */
+interface QueryMetadata {
+    /** Query identifier */
+    queryId: string;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Number of results */
+    resultCount: number;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Whether result was from cache */
+    cacheHit?: boolean;
+    /** Generated pipeline (if debug enabled) */
+    pipeline?: unknown[];
+    /** Resolved parameters (if debug enabled) */
+    parameters?: Record<string, unknown>;
+    /** Validation warnings */
+    warnings?: string[];
+}
+/**
+ * The payload `POST /v1/query` serves: `{ result, metadata }`.
+ *
+ * The route is an `object` kind, so there is one payload key whether the query
+ * fetched a list or a singleton — `result` is the records either way. Three
+ * members of the hand-written type are gone and each for a stated reason:
+ * `success` because the status line says it, `items` because no contract shape
+ * introduces that key (`INV-API-SUCCESS-HAS-ONE-SHAPE`), and `errors` because a
+ * failed query is a **refusal**, which arrives as `{ error: { code, messages } }`
+ * and is thrown as a typed SDK error rather than returned as a 200 with a flag.
+ */
+interface AdhocQueryResult<T = unknown> {
+    /** The records the query produced — an array for a list, one item for a singleton. */
+    result?: T | T[];
+    /** Execution metadata */
+    metadata?: QueryMetadata;
+}
+/**
+ * Fluent builder for ad-hoc queries
+ *
+ * @example
+ * ```typescript
+ * const result = await relyio.query.adhoc()
+ *   .fetch({
+ *     contentType: 'product',
+ *     where: { status: 'active' },
+ *     include: ['brand', 'categories'],
+ *     limit: 20
+ *   })
+ *   .select({
+ *     id: 'id',
+ *     title: 'title',
+ *     price: 'pricing.basePrice',
+ *     brandName: 'brand.name'
+ *   })
+ *   .filter('pricing.basePrice', { gte: '${minPrice}', lte: '${maxPrice}' })
+ *   .params({ minPrice: 100, maxPrice: 500 })
+ *   .debug()
+ *   .execute()
+ * ```
+ */
+declare class AdhocQueryBuilder<T = unknown> {
+    private readonly httpClient;
+    private queryDef;
+    private parameters;
+    private options;
+    constructor(httpClient: HttpClient);
+    /**
+     * Add a fetch block to retrieve content
+     * @param config - Fetch configuration
+     */
+    fetch(config: FetchBlock): this;
+    /**
+     * Fetch from a content type
+     * @param contentType - Content type to fetch
+     */
+    from(contentType: string): this;
+    /**
+     * Fetch a singleton
+     * @param singletonKey - Singleton key
+     */
+    singleton(singletonKey: string): this;
+    /**
+     * Add aggregate block
+     * @param config - Aggregate configuration
+     */
+    aggregate(config: AggregateBlock): this;
+    /**
+     * Add search block
+     * @param config - Search configuration
+     */
+    search(config: SearchBlock): this;
+    /**
+     * Add similar block
+     * @param config - Similar configuration
+     */
+    similar(config: SimilarBlock): this;
+    /**
+     * Add where conditions to fetch
+     * @param conditions - Filter conditions
+     */
+    where(conditions: Record<string, unknown>): this;
+    /**
+     * Add include for reference population
+     * @param fields - Reference fields to include
+     */
+    include(fields: string | string[]): this;
+    /**
+     * Add sort specification
+     * @param sort - Sort configuration
+     */
+    sort(sort: Record<string, 'asc' | 'desc'>): this;
+    /**
+     * Sort by field ascending
+     * @param field - Field to sort by
+     */
+    sortAsc(field: string): this;
+    /**
+     * Sort by field descending
+     * @param field - Field to sort by
+     */
+    sortDesc(field: string): this;
+    /**
+     * Limit results
+     * @param count - Maximum results
+     */
+    limit(count: number): this;
+    /**
+     * Skip results
+     * @param count - Number to skip
+     */
+    offset(count: number): this;
+    /**
+     * Select and transform fields in output
+     * @param projection - Field mapping (outputField: sourceField)
+     */
+    select(projection: Record<string, string>): this;
+    /**
+     * Add a post-fetch filter (supports ${param} syntax)
+     * @param field - Field path to filter
+     * @param condition - Filter condition
+     */
+    filter(field: string, condition: FilterValue): this;
+    /**
+     * Add full-text search
+     * @param config - Full-text configuration
+     */
+    fullText(config: FullTextConfig): this;
+    /**
+     * Set query parameters
+     * @param params - Parameter values
+     */
+    params(params: Record<string, unknown>): this;
+    /**
+     * Set a single parameter
+     * @param name - Parameter name
+     * @param value - Parameter value
+     */
+    param(name: string, value: unknown): this;
+    /**
+     * Enable debug mode
+     */
+    debug(): this;
+    /**
+     * Skip cache for this request
+     */
+    skipCache(): this;
+    /**
+     * Set custom timeout
+     * @param ms - Timeout in milliseconds (1000-60000)
+     */
+    timeout(ms: number): this;
+    /**
+     * Set cache policy
+     * @param ttl - Cache TTL in seconds
+     * @param strategy - Cache strategy
+     */
+    cache(ttl: number, strategy?: 'stale-while-revalidate' | 'cache-first' | 'network-first'): this;
+    /**
+     * Get the query definition (for debugging)
+     */
+    getDefinition(): AdhocQueryDefinition;
+    /**
+     * Get the parameters (for debugging)
+     */
+    getParameters(): Record<string, unknown>;
+    /**
+     * Execute the query
+     */
+    execute(): Promise<AdhocQueryResult<T>>;
+    /**
+     * Execute and return the records as an array (for list queries).
+     */
+    items(): Promise<T[]>;
+    /**
+     * Execute and return the single record (for singleton queries).
+     */
+    data(): Promise<T | undefined>;
+    /**
+     * Clone the builder
+     */
+    clone(): AdhocQueryBuilder<T>;
+}
+/**
+ * Client for executing ad-hoc queries
+ *
+ * @example
+ * ```typescript
+ * const queryClient = new AdhocQueryClient(httpClient)
+ *
+ * // Fluent builder
+ * const products = await queryClient.build()
+ *   .from('product')
+ *   .where({ status: 'active' })
+ *   .limit(20)
+ *   .execute()
+ *
+ * // Direct execution
+ * const result = await queryClient.execute({
+ *   fetch: { contentType: 'product', limit: 10 }
+ * })
+ * ```
+ */
+declare class AdhocQueryClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new query builder
+     */
+    build<T = unknown>(): AdhocQueryBuilder<T>;
+    /**
+     * Execute a query definition directly
+     * @param definition - Query definition
+     * @param parameters - Parameter values
+     * @param options - Execution options
+     */
+    execute<T = unknown>(definition: AdhocQueryDefinition, parameters?: Record<string, unknown>, options?: AdhocQueryOptions): Promise<AdhocQueryResult<T>>;
+    /**
+     * Quick fetch helper
+     * @param contentType - Content type
+     * @param options - Fetch options
+     */
+    fetch<T = unknown>(contentType: string, options?: Omit<FetchBlock, 'contentType'>): Promise<T[]>;
+    /**
+     * Quick singleton fetch helper
+     * @param singletonKey - Singleton key
+     */
+    fetchSingleton<T = unknown>(singletonKey: string): Promise<T | undefined>;
+    /**
+     * Quick aggregate helper
+     * @param source - Source content type
+     * @param metrics - Metrics to compute
+     * @param groupBy - Optional grouping field
+     */
+    aggregate<T = unknown>(source: string, metrics: Record<string, AggregateMetric>, groupBy?: string | string[]): Promise<T[]>;
+}
+
+/**
+ * Type alias for any schema definition.
+ * Uses `any` intentionally to accept schemas with any content types, components, etc.
+ * This is necessary for the SDK to be flexible with user-defined schemas.
+ */
+type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
+/**
+ * Client configuration with optional schema
+ */
+interface TypedClientConfig<TSchema extends AnySchemaDefinition | undefined = undefined> extends RelyIOConfig {
+    /** Schema definition for type inference (optional - omit for dynamic/untyped usage) */
+    schema?: TSchema;
+}
+/**
+ * Typed RelyIO client with full schema awareness
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ * import { schema } from './schema'
+ *
+ * const relyio = createClient({
+ *   apiKey: process.env.RELYIO_API_KEY!,
+ *   schema,
+ * })
+ *
+ * // Content operations
+ * const products = await relyio.content('product').query().execute()
+ *
+ * // Search
+ * const results = await relyio.search('wireless').in('product').execute()
+ *
+ * // Batch operations
+ * const batch = await relyio.batch()
+ *   .create('product', { content: { title: 'New' } })
+ *   .execute()
+ * ```
+ */
+declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined = undefined> {
+    private httpClient;
+    private config;
+    private _search;
+    private _batch;
+    private _adhocQuery;
+    private _schema;
+    constructor(config: TypedClientConfig<TSchema>);
+    /**
+     * Get the schema definition
+     */
+    get schema(): TSchema;
+    /**
+     * Get the ad-hoc query client
+     */
+    get query(): AdhocQueryClient;
+    /**
+     * Get a content client for a specific content type
+     * Type-safe when schema is provided: autocompletes content type names AND field names
+     *
+     * @example
+     * ```typescript
+     * const products = await relyio.content('product')
+     *   .query()
+     *   .where({ status: 'active' })  // ← Field names autocomplete with schema!
+     *   .locale('en-US')
+     *   .limit(20)
+     *   .execute()
+     * ```
+     */
+    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']]>> : ContentClient<BaseContent>;
+    /**
+     * Get an asset client for a specific asset type.
+     *
+     * Mirrors `content()` but targets `entryType: 'asset'` entries on the same
+     * dynamic `/{assetTypeId}` routes, and adds the `file(entryUid)` sub-resource
+     * builder + a high-level `upload()` helper. Type-safe when a schema is
+     * provided: autocompletes asset type names AND metadata field names.
+     *
+     * @example
+     * ```typescript
+     * const photo = await relyio.asset('productPhoto').upload(file)
+     *   .filename('shoe.jpg')
+     *   .visibility('public')
+     *   .execute()
+     *
+     * const heroUrl = await relyio.asset('productPhoto').file(photo._metadata.id).url({ variantId: 'hero' })
+     * ```
+     */
+    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>]>> : AssetClient<BaseContent>;
+    /**
+     * Get a singleton client for a specific singleton key
+     * Type-safe when schema is provided: autocompletes singleton names AND field names
+     *
+     * @example
+     * ```typescript
+     * const homepage = await relyio.singleton('homepage')
+     *   .include(['featuredProducts'])
+     *   .locale('en')
+     *   .fetch()
+     * ```
+     */
+    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']]>> : SingletonClient<unknown>;
+    /**
+     * Get a settings client for a specific settings group
+     * Type-safe when schema is provided: autocompletes settings group names AND field names
+     *
+     * @example
+     * ```typescript
+     * const emailConfig = await relyio.settings('email-config')
+     *   .include(['defaultTemplate'])
+     *   .fetch()
+     * ```
+     */
+    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>]>> : SettingsClient<unknown>;
+    /**
+     * Start a search query with full-text, semantic, or hybrid search
+     *
+     * @example
+     * ```typescript
+     * const results = await relyio.search('wireless headphones')
+     *   .in('product')
+     *   .where({ status: 'active' })
+     *   .limit(20)
+     *   .includeScore()
+     *   .execute()
+     * ```
+     */
+    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    /**
+     * Start an autocomplete query for search suggestions
+     *
+     * @example
+     * ```typescript
+     * const suggestions = await relyio.autocomplete('wire')
+     *   .in('product')
+     *   .field('title')
+     *   .fuzzy()
+     *   .limit(10)
+     *   .execute()
+     * ```
+     */
+    autocomplete(query: string): AutocompleteBuilder;
+    /**
+     * Find content similar to a given entry using vector search
+     *
+     * @example
+     * ```typescript
+     * const similar = await relyio.similar('entry_abc123')
+     *   .in('product')
+     *   .locale('fr-FR')
+     *   .limit(5)
+     *   .execute()
+     * ```
+     */
+    similar<T extends BaseContent = BaseContent>(sourceId: string): SimilarBuilder<T>;
+    /**
+     * Start a batch operation for bulk create/update/delete
+     *
+     * @example
+     * ```typescript
+     * const result = await relyio.batch()
+     *   .create('product', { content: { title: 'iPhone', price: 999 } })
+     *   .update('product', 'entry_abc', { content: { price: 899 } })
+     *   .delete('product', 'entry_xyz')
+     *   .upsertSingleton('homepage', { content: { hero: 'Welcome!' } })
+     *   .execute({ atomic: true })
+     *
+     * console.log(result.summary.succeeded)
+     * ```
+     */
+    batch(): BatchBuilder<NonNullable<TSchema>>;
+    /**
+     * Build and execute an ad-hoc query dynamically
+     *
+     * @example
+     * ```typescript
+     * const result = await relyio.adhoc()
+     *   .from('product')
+     *   .where({ status: 'active' })
+     *   .include(['brand', 'categories'])
+     *   .select({
+     *     id: 'id',
+     *     title: 'title',
+     *     price: 'pricing.basePrice'
+     *   })
+     *   .limit(20)
+     *   .execute()
+     * ```
+     */
+    adhoc<T = unknown>(): AdhocQueryBuilder<T>;
+    /**
+     * Execute a predefined query by name (from schema)
+     * Type-safe when schema is provided: autocompletes query names
+     *
+     * @example
+     * ```typescript
+     * const featured = await relyio.executeQuery('featured-products', {
+     *   limit: 10,
+     *   category: 'electronics'
+     * })
+     * ```
+     */
+    executeQuery<K extends TSchema extends AnySchemaDefinition ? SchemaQueryNames<TSchema> : string>(queryName: K, params?: Record<string, unknown>): Promise<unknown[]>;
+    /**
+     * Get schema information from the API
+     */
+    getSchemaInfo(contentType?: string): Promise<unknown>;
+    /**
+     * List all content types from the API
+     */
+    listContentTypes(): Promise<Array<{
+        id: string;
+        name: string;
+        type: 'content' | 'singleton';
+    }>>;
+    /**
+     * Get API health status
+     */
+    health(): Promise<{
+        status: 'ok' | 'degraded' | 'down';
+        timestamp: string;
+    }>;
+    /**
+     * Check if the API is ready
+     */
+    ready(): Promise<boolean>;
+    /**
+     * Test the connection to the API
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Update the configuration and reinitialize all clients
+     */
+    updateConfig(newConfig: Partial<RelyIOConfig>): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Readonly<MergedRelyIOConfig>;
+    /**
+     * Set the API key
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Get the HTTP client instance (for advanced usage)
+     */
+    getHttpClient(): HttpClient;
+    /**
+     * Create a locale-scoped client
+     * All content operations on the returned client will use the specified locale
+     *
+     * Type-safe when schema is provided: autocompletes valid locale codes!
+     *
+     * @example
+     * ```typescript
+     * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
+     *
+     * // All operations use Spanish
+     * const products = await spanish.content('product').query().execute()
+     * const homepage = await spanish.singleton('homepage').fetch()
+     *
+     * // Original client unchanged
+     * const englishProducts = await relyio.content('product').query().execute()
+     * ```
+     */
+    withLocale<L extends TSchema extends AnySchemaDefinition ? SchemaLocaleCodes<TSchema> : string>(locale: L): TypedRelyIOClient<TSchema>;
+    /**
+     * Get the current default locale
+     */
+    getLocale(): string | undefined;
+    /**
+     * Get available locales from the API
+     *
+     * @example
+     * ```typescript
+     * const { locales, defaultLocale } = await relyio.getLocales()
+     *
+     * // Build language switcher
+     * const options = locales.map(l => ({
+     *   code: l.code,
+     *   label: l.displayName,
+     *   isDefault: l.default,
+     * }))
+     * ```
+     */
+    getLocales(search?: string): Promise<{
+        locales: Array<{
+            code: string;
+            displayName?: string;
+            default?: boolean;
+            fallback?: string[];
+            direction?: 'ltr' | 'rtl';
+            active?: boolean;
+        }>;
+        defaultLocale: string | null;
+        total: number;
+    }>;
+    /**
+     * Get the default locale from the API
+     */
+    getDefaultLocale(): Promise<string | null>;
+}
+/**
+ * Create a RelyIO client
+ *
+ * @example Without schema (dynamic usage)
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ *
+ * const relyio = createClient({
+ *   apiKey: process.env.RELYIO_API_KEY!,
+ * })
+ *
+ * // Works but no autocomplete for content types
+ * const products = await relyio.content('product').fetchAll()
+ * ```
+ *
+ * @example With schema (fully typed)
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ * import { schema } from './schema'
+ *
+ * const relyio = createClient({
+ *   apiKey: process.env.RELYIO_API_KEY!,
+ *   schema,
+ * })
+ *
+ * // Content type names autocomplete!
+ * const products = await relyio.content('product').fetchAll()
+ * ```
+ */
+declare function createClient<TSchema extends AnySchemaDefinition>(config: TypedClientConfig<TSchema>): TypedRelyIOClient<TSchema>;
+declare function createClient(config: RelyIOConfig): TypedRelyIOClient<undefined>;
+/**
+ * Helper type to extract schema from client
+ */
+type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
+
+export { AssetFileBuilder as $, AutocompleteBuilder as A, BatchClient as B, type ClientSchema as C, type BatchOperation as D, type ExtendedQueryResult as E, type BatchOptions as F, type BatchOperationResult as G, HttpClient as H, type BatchSummary as I, type BatchResponse as J, AdhocQueryClient as K, AdhocQueryBuilder as L, type FetchBlock as M, type AggregateBlock as N, type AggregateMetric as O, type SearchBlock as P, type SimilarBlock as Q, type RetryableWriteOptions as R, type SendOptions as S, TypedRelyIOClient as T, type FilterValue as U, type FullTextConfig as V, type AdhocQueryDefinition as W, type AdhocQueryOptions as X, type QueryMetadata as Y, type AdhocQueryResult as Z, AssetClient as _, type TypedClientConfig as a, AssetUploadBuilder as a0, isAssetEntry as a1, type AssetVisibility as a2, type FileStatus as a3, type FileBackend as a4, type AssetFileBlock as a5, type AssetFileExtracted as a6, type AssetUrls as a7, type AssetEntryResponse as a8, type PopulatedAssetReference as a9, type PresignInput as aa, type PresignResult as ab, type ConfirmInput as ac, type ConfirmResult as ad, type ResolveUrlInput as ae, type ResolveUrlResult as af, type CreateAssetOptions as ag, type WaitUntilReadyOptions as ah, type MultipartCreateResult as ai, type MultipartPart as aj, type MultipartTarget as ak, type UploadProgress as al, type FileErrorCode as am, FileUploadError as an, FileValidationError as ao, type FileValidationConstraints as ap, validateFile as aq, type ConditionalWriteOptions as b, createClient as c, ContentClient as d, entityTagOf as e, SingletonClient as f, SettingsClient as g, ContentQueryBuilder as h, ContentByIdBuilder as i, type ChildrenOptions as j, type SingletonFetchOptions as k, type SettingsFetchOptions as l, SearchClient as m, SearchBuilder as n, SimilarBuilder as o, type SearchMode as p, type SearchResultItem as q, type SearchResponse as r, type AutocompleteSuggestion as s, type AutocompleteResponse as t, type SimilarResult as u, type SimilarResponse as v, type SearchFilter as w, type SearchFields as x, BatchBuilder as y, type BatchMethod as z };