@relyio/sdk 0.5.0 → 0.6.0

package/dist/{index-BozPz4n1.d.cts → index-Df1VsfJR.d.cts}

@@ -1,6 +1,6 @@
-import { J as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, K as PathParamsOf, t as ApiResponse, W as Wire, s as RequestConfig, B as BaseContent, d as WhereClause, f as SortOptions, g as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, x as BaseValidationError, w as ValidationViolation, N as components, O as paths, R as RelyIOConfig } from './index-C5mRBb6t.cjs';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, h as SchemaAssetTypeNames, M as InferAssetType, c as SchemaSingletonNames, t as InferSingleton, g as SchemaSettingsGroupNames, E as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-2xbHgtK-.cjs';
-import { J as InferContentType } from './define-content-type-CBfnTWSS.cjs';
+import { N as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, O as PathParamsOf, v as ApiResponse, W as Wire, u as RequestConfig, B as BaseContent, f as WhereClause, h as SortOptions, i as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, z as BaseValidationError, y as ValidationViolation, T as components, X as paths, R as RelyIOConfig } from './index-d1Kz1e19.cjs';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-1kr2HIzN.cjs';
+import { Q as InferContentType, a6 as InferAssetType, a0 as InferSingleton } from './define-content-type-CDB3kyeA.cjs';
 import { DevUnreadableReason } from './dev-handshake/index.cjs';
 
 /**
@@ -130,6 +130,12 @@ declare class HttpClient {
      * The loop always makes one attempt. The incumbent's `while (attempt <
      * maxAttempts)` made none at `retryAttempts: 0` — a value the config validator
      * accepts — and then dereferenced an unassigned `lastError`.
+     *
+     * A request that would carry no `X-API-Key` makes none: it rejects with
+     * `MissingApiKeyError` before `fetch` is called, is not retried, and names
+     * `apiKey`. This is where a client built without a key learns it — the
+     * constructor accepts one so that a module-scope client can be evaluated by a
+     * build that holds no key (REL-1120).
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -196,8 +202,6 @@ declare class HttpClient {
     private mergeRequestConfig;
     private buildQueryString;
     private headersToObject;
-    /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
-    private sleep;
     private log;
 }
 
@@ -252,7 +256,14 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
     private childrenOptions?;
     private pageNumber?;
     private pageSizeValue?;
+    private requestHeaders?;
     constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    /**
+     * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
+     * the key can see. A name the client already sends is replaced for this query only; the client
+     * is not changed.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Add where conditions to the query
      */
@@ -454,6 +465,7 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
     private localesArray?;
     private fetchAllLocales;
     private childrenOptions?;
+    private requestHeaders?;
     constructor(httpClient: HttpClient, contentType: string, id: string, defaultLocale?: string | undefined);
     /**
      * Include related content in the response
@@ -471,6 +483,12 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
      * @param localeCodes - Array of locale codes to fetch
      */
     locales(localeCodes: string[]): this;
+    /**
+     * Headers this one read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
+     * the key can see. A name the client already sends is replaced for this request only; the client
+     * is not changed.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Fetch content in all available locales
      * Returns default locale at top level, others in _metadata.localizations
@@ -619,11 +637,13 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Fetch a single content item by ID
      * @param id - Entry ID or slug
-     * @param options - Fetch options (include, locale)
+     * @param options - Fetch options (include, locale, and `headers` this one request adds — e.g.
+     *   `{ 'X-RelyIO-Dataset': 'staging' }` to read a dataset other than the client's)
      */
     fetchOne(id: string, options?: {
         include?: string[];
         locale?: string;
+        headers?: Record<string, string>;
     }): Promise<T | null>;
     /**
      * Fetch one entry **and the entity tag that read served**.
@@ -637,10 +657,16 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * `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.
+     *
+     * Unlike {@link fetchOne}, a missing entry is not `null`: the service's
+     * `RESOURCE_NOT_FOUND` is thrown as it arrived, with the `kind` that says
+     * whether the entry, the content type or the schema was missing. `headers`
+     * are the ones this read adds, as for `fetchOne`.
      */
     fetchOneWithTag(id: string, options?: {
         include?: string[];
         locale?: string;
+        headers?: Record<string, string>;
     }): Promise<{
         entry: T;
         entityTag?: string;
@@ -654,25 +680,32 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Create a new content item
      * @param data - Content data
-     * @param options - Create options (slug, locale, parentId, sortOrder)
+     * @param options - Create options (slug, locale, parentId, sortOrder), and `headers` this one
+     *   request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset other than the
+     *   client's. They are sent, never put in the body; `idempotencyKey` still wins over an
+     *   `Idempotency-Key` among them.
      */
     create(data: CreateInput<T>, options?: {
         slug?: string;
         locale?: string;
         parentId?: string;
         sortOrder?: number;
+        headers?: Record<string, string>;
     } & 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)
+     * @param options - Update options (slug, locale, parentId, sortOrder), and `headers` this one
+     *   request adds, as for {@link create}. `ifMatch` and `idempotencyKey` win over the same
+     *   header among them.
      */
     update(id: string, data: UpdateInput<T>, options?: {
         slug?: string;
         locale?: string;
         parentId?: string;
         sortOrder?: number;
+        headers?: Record<string, string>;
     } & ConditionalWriteOptions): Promise<T>;
     /**
      * Delete a content item by ID
@@ -1230,6 +1263,9 @@ interface SingletonFetchOptions {
  * Singleton client for managing singleton content operations
  * Provides a fluent API for singleton operations following the same pattern as ContentClient
  *
+ * A read is in the locale it names — `fetch({ locale })`, then `.locale()` — and otherwise in
+ * `defaultLocale`, the client's own (`withLocale()`), as `content()`'s reads are.
+ *
  * @example
  * ```typescript
  * const homepage = await client.singleton('homepage')
@@ -1241,9 +1277,10 @@ interface SingletonFetchOptions {
 declare class SingletonClient<T = unknown> {
     private httpClient;
     private singletonKey;
+    private readonly defaultLocale?;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, singletonKey: string);
+    constructor(httpClient: HttpClient, singletonKey: string, defaultLocale?: string | undefined);
     /**
      * Include reference fields in the response
      * @param fields - Reference field names to populate
@@ -1328,6 +1365,9 @@ interface SettingsFetchOptions {
  * Settings client for managing settings group operations
  * Provides a fluent API for settings operations following the same pattern as ContentClient
  *
+ * A read is in the locale it names — `fetch({ locale })`, then `.locale()` — and otherwise in
+ * `defaultLocale`, the client's own (`withLocale()`), as `content()`'s reads are.
+ *
  * @example
  * ```typescript
  * const emailConfig = await client.settings('email-config')
@@ -1339,9 +1379,10 @@ interface SettingsFetchOptions {
 declare class SettingsClient<T = unknown> {
     private readonly httpClient;
     private readonly groupId;
+    private readonly defaultLocale?;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, groupId: string);
+    constructor(httpClient: HttpClient, groupId: string, defaultLocale?: string | undefined);
     /**
      * Include reference fields in the response
      * @param fields - Reference field names to populate
@@ -1418,6 +1459,41 @@ declare class SettingsClient<T = unknown> {
     resetOptions(): this;
 }
 
+/**
+ * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
+ * types, components, singletons, queries and settings groups a customer declares.
+ *
+ * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
+ * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
+ * inferred against any wider alias would not be provably inside the client's bound.
+ */
+type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
+/**
+ * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
+ *
+ * Empty here on purpose. The generated `schema.ts` augments it —
+ *
+ * ```ts
+ * declare module '@relyio/sdk' {
+ *   interface Register {
+ *     schema: typeof schema
+ *   }
+ * }
+ * ```
+ *
+ * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
+ * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
+ */
+interface Register {
+}
+/**
+ * The schema the project registered through `Register`, or `undefined` when nothing did — which is
+ * the untyped client, exactly as before the generator ran.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S extends AnySchemaDefinition;
+} ? S : undefined;
+
 /**
  * Search mode for content queries
  */
@@ -1493,12 +1569,31 @@ type SimilarResponse<T = unknown> = Wire<'/v1/search/similar', 'post', SimilarRe
  * Filter conditions for search
  */
 type SearchFilter = Record<string, unknown>;
+/**
+ * The content type names a search may be scoped to: the schema's where one types the client, any
+ * name where none does.
+ */
+type SearchTypeName<S extends AnySchemaDefinition | undefined> = S extends AnySchemaDefinition ? SchemaContentTypeNames<S> : string;
+/**
+ * What a search over the content types `K` returns: their entries, typed by the schema
+ * (`INV-SS-TYPES-INFERRED`) — or `T` unchanged where no schema types the client.
+ */
+type SearchEntry<S extends AnySchemaDefinition | undefined, K extends SearchTypeName<S> = SearchTypeName<S>, T extends BaseContent = BaseContent> = S extends AnySchemaDefinition ? SchemaEntryOf<S, K & SchemaContentTypeNames<S>> : T;
 /**
  * Field projection for search results
  */
 type SearchFields<T> = {
     [K: string]: keyof T | string;
 };
+/**
+ * One ordering of `POST /v1/search`'s results, as the route's `sort` array takes it.
+ */
+interface SearchSort {
+    /** Field path, or `_score` for relevance */
+    field: string;
+    /** Direction; the route's default is `desc` */
+    direction: 'asc' | 'desc';
+}
 /**
  * Fluent builder for search queries
  *
@@ -1513,21 +1608,33 @@ type SearchFields<T> = {
  *   .execute()
  * ```
  */
-declare class SearchBuilder<T extends BaseContent = BaseContent> {
+declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySchemaDefinition | undefined = undefined> {
     private readonly httpClient;
+    private readonly defaultLocale?;
     private query;
     private searchOptions;
-    constructor(httpClient: HttpClient, query: string);
+    private requestHeaders?;
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     */
+    constructor(httpClient: HttpClient, query: string, defaultLocale?: string | undefined);
     /**
-     * Search within a single content type
+     * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
+     * dataset the key can see. A name the client already sends is replaced for this search only.
+     */
+    headers(headers: Record<string, string>): this;
+    /**
+     * Search within a single content type. Where a schema types the client, the name is one of its
+     * content types and the results are that type's entries.
      * @param contentType - Content type to search in
      */
-    in<K extends string>(contentType: K): SearchBuilder<T>;
+    in<K extends SearchTypeName<S>>(contentType: K): SearchBuilder<SearchEntry<S, K, T>, S>;
     /**
-     * Search across multiple content types
+     * Search across multiple content types. Where a schema types the client, the names are its content
+     * types and the results are a union of their entries — every type's, for `'*'`.
      * @param contentTypes - Array of content types or '*' for all
      */
-    across(contentTypes: string[] | '*'): SearchBuilder<T>;
+    across<K extends SearchTypeName<S>>(contentTypes: K[] | '*'): SearchBuilder<SearchEntry<S, K, T>, S>;
     /**
      * Add filter conditions
      * @param conditions - Filter conditions
@@ -1543,6 +1650,13 @@ declare class SearchBuilder<T extends BaseContent = BaseContent> {
      * @param projection - Field mapping
      */
     fields(projection: Record<string, string>): this;
+    /**
+     * Order the results by a field instead of by relevance. Called again, it adds a tie-breaker.
+     * `_score` names relevance itself.
+     * @param field - Field path to sort by (e.g. `updatedAt`, `pricing.basePrice`)
+     * @param direction - `asc` or `desc` (the route's default is `desc`)
+     */
+    sort(field: string, direction?: 'asc' | 'desc'): this;
     /**
      * Limit number of results
      * @param count - Maximum results
@@ -1594,9 +1708,13 @@ declare class SearchBuilder<T extends BaseContent = BaseContent> {
  */
 declare class AutocompleteBuilder {
     private readonly httpClient;
+    private readonly defaultLocale?;
     private query;
     private autocompleteOptions;
-    constructor(httpClient: HttpClient, query: string);
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     */
+    constructor(httpClient: HttpClient, query: string, defaultLocale?: string | undefined);
     /**
      * Autocomplete within a content type
      * @param contentType - Content type to search
@@ -1649,14 +1767,29 @@ declare class AutocompleteBuilder {
  */
 declare class SimilarBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
+    private readonly defaultLocale?;
     private sourceId;
     private similarOptions;
-    constructor(httpClient: HttpClient, sourceId: string);
+    private requestHeaders?;
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     */
+    constructor(httpClient: HttpClient, sourceId: string, defaultLocale?: string | undefined);
+    /**
+     * Headers this read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
+     * the key can see. A name the client already sends is replaced for this read only.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Find similar content within a content type
      * @param contentType - Content type to search
      */
     in(contentType: string): this;
+    /**
+     * Find similar content across several content types, or `'*'` for every type
+     * @param contentTypes - Array of content types or '*' for all
+     */
+    across(contentTypes: string[] | '*'): this;
     /**
      * Add filter conditions
      * @param conditions - Filter conditions
@@ -1712,12 +1845,17 @@ declare class SimilarBuilder<T extends BaseContent = BaseContent> {
  */
 declare class SearchClient {
     private readonly httpClient;
-    constructor(httpClient: HttpClient);
+    private readonly defaultLocale?;
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`): every builder here sends it when
+     *   the query names none, as `content()`'s reads do
+     */
+    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
     /**
      * Start a search query
      * @param query - Search query string
      */
-    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    search<T extends BaseContent = BaseContent, S extends AnySchemaDefinition | undefined = undefined>(query: string): SearchBuilder<T, S>;
     /**
      * Start an autocomplete query
      * @param query - Partial query to autocomplete
@@ -1836,6 +1974,7 @@ declare class BatchBuilder<TSchema = unknown> {
     private readonly httpClient;
     private operations;
     private defaultOptions;
+    private requestHeaders;
     constructor(httpClient: HttpClient);
     /**
      * Add a create operation
@@ -1973,6 +2112,12 @@ declare class BatchBuilder<TSchema = unknown> {
      * Stop on first error (non-atomic mode)
      */
     stopOnError(): this;
+    /**
+     * Headers the batch request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset
+     * other than the client's. They replace the client's own header of the same name for this
+     * request alone, and apply to every operation in it: a batch is one request.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Get the current list of operations
      */
@@ -2093,20 +2238,26 @@ interface FetchBlock {
 interface AggregateBlock {
     /** Source content type or query reference */
     source: string;
+    /**
+     * Filter conditions applied before grouping, in the Query DSL's spelling — bare operator names
+     * (`{ price: { gte: 10 } }`), not the list route's `$gte`. A `$`-prefixed key is not an operator
+     * in this dialect: the service reads the object as a nested field and drops it.
+     */
+    where?: Record<string, unknown>;
     /** Field to group by */
     by?: string | string[];
-    /** Metrics to compute */
+    /** Metrics to compute, keyed by the name each one answers under */
     metrics: Record<string, AggregateMetric>;
 }
 /**
- * Aggregate metric definition
+ * One metric, as the Query DSL writes it: `<field>.<fn>`, where `fn` is `count`, `sum`, `avg`,
+ * `min` or `max` — `'id.count'`, `'pricing.basePrice.avg'`. The service validates every metric
+ * against that form (`INVALID_AGGREGATION_EXPRESSION`); `count` ignores the field it names.
+ *
+ * It used to be `{ fn, field? }`, a shape the service refuses on every request: the validator
+ * tests the metric as a string, so an object arrives as `[object Object]`.
  */
-interface AggregateMetric {
-    /** Aggregation function */
-    fn: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last';
-    /** Field to aggregate (optional for count) */
-    field?: string;
-}
+type AggregateMetric = `${string}.${'count' | 'sum' | 'avg' | 'min' | 'max'}`;
 /**
  * Search block for full-text/semantic search
  */
@@ -2265,10 +2416,15 @@ interface AdhocQueryResult<T = unknown> {
  */
 declare class AdhocQueryBuilder<T = unknown> {
     private readonly httpClient;
+    private readonly defaultLocale?;
     private queryDef;
     private parameters;
     private options;
-    constructor(httpClient: HttpClient);
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter
+     *   when `.param('locale', …)` binds none
+     */
+    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
     /**
      * Add a fetch block to retrieve content
      * @param config - Fetch configuration
@@ -2427,7 +2583,12 @@ declare class AdhocQueryBuilder<T = unknown> {
  */
 declare class AdhocQueryClient {
     private readonly httpClient;
-    constructor(httpClient: HttpClient);
+    private readonly defaultLocale?;
+    /**
+     * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter of
+     *   every query that binds none
+     */
+    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
     /**
      * Create a new query builder
      */
@@ -2437,8 +2598,13 @@ declare class AdhocQueryClient {
      * @param definition - Query definition
      * @param parameters - Parameter values
      * @param options - Execution options
+     * @param request - `headers` this one request adds to the client's own, e.g. `X-RelyIO-Dataset`
+     *   to query another dataset the key can see. A name the client already sends is replaced for
+     *   this request only.
      */
-    execute<T = unknown>(definition: AdhocQueryDefinition, parameters?: Record<string, unknown>, options?: AdhocQueryOptions): Promise<AdhocQueryResult<T>>;
+    execute<T = unknown>(definition: AdhocQueryDefinition, parameters?: Record<string, unknown>, options?: AdhocQueryOptions, request?: {
+        headers?: Record<string, string>;
+    }): Promise<AdhocQueryResult<T>>;
     /**
      * Quick fetch helper
      * @param contentType - Content type
@@ -2584,41 +2750,10 @@ interface ChangesOptions {
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
 }
-
-/**
- * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
- * types, components, singletons, queries and settings groups a customer declares.
- *
- * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
- * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
- * inferred against any wider alias would not be provably inside the client's bound.
- */
-type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
-/**
- * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
- *
- * Empty here on purpose. The generated `schema.ts` augments it —
- *
- * ```ts
- * declare module '@relyio/sdk' {
- *   interface Register {
- *     schema: typeof schema
- *   }
- * }
- * ```
- *
- * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
- * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
- */
-interface Register {
+interface ChangesHeadOptions {
+    /** Cancels the request; the promise then rejects. */
+    signal?: AbortSignal;
 }
-/**
- * The schema the project registered through `Register`, or `undefined` when nothing did — which is
- * the untyped client, exactly as before the generator ran.
- */
-type RegisteredSchema = Register extends {
-    schema: infer S extends AnySchemaDefinition;
-} ? S : undefined;
 
 /**
  * The key's project, as `GET /v1/project` describes it: organization, project, dataset and branch,
@@ -2707,7 +2842,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .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>;
+    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']], TSchema>> : ContentClient<BaseContent>;
     /**
      * Get an asset client for a specific asset type.
      *
@@ -2726,7 +2861,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * 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>;
+    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>], TSchema>> : AssetClient<BaseContent>;
     /**
      * Get a singleton client for a specific singleton key
      * Type-safe when schema is provided: autocompletes singleton names AND field names
@@ -2739,7 +2874,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .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>;
+    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']], TSchema>> : SingletonClient<unknown>;
     /**
      * Get a settings client for a specific settings group
      * Type-safe when schema is provided: autocompletes settings group names AND field names
@@ -2751,9 +2886,12 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .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>;
+    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>], TSchema>> : SettingsClient<unknown>;
     /**
-     * Start a search query with full-text, semantic, or hybrid search
+     * Start a search query with full-text, semantic, or hybrid search.
+     *
+     * Where a schema types the client, the results are its entries — every content type's until
+     * `in()` or `across()` narrows them (`INV-SS-TYPES-INFERRED`).
      *
      * @example
      * ```typescript
@@ -2765,7 +2903,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .execute()
      * ```
      */
-    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    search<T extends BaseContent = SearchEntry<TSchema>>(query: string): SearchBuilder<T, TSchema>;
     /**
      * Start an autocomplete query for search suggestions
      *
@@ -2835,6 +2973,23 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     changes(options?: ChangesOptions): AsyncIterable<Change>;
+    /**
+     * The dataset's current position in the changes feed, as a cursor to start
+     * `changes({ since })` or `followChanges(…, { since })` from. One
+     * `GET /v1/changes` without a cursor: answered at once, holding nothing.
+     *
+     * Take it **before** you read what you will follow. A write your read did not
+     * see is then after the position and replayed; opening the feed afterwards
+     * without a `since` starts after it and misses it.
+     *
+     * @example
+     * ```typescript
+     * const since = await relyio.changesHead()
+     * const post = await relyio.content('post').findById(id).execute()
+     * for await (const change of relyio.changes({ since, ids: [id] })) { … }
+     * ```
+     */
+    changesHead(options?: ChangesHeadOptions): Promise<string>;
     /**
      * Build and execute an ad-hoc query dynamically
      *
@@ -2927,7 +3082,10 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
     getHttpClient(): HttpClient;
     /**
      * Create a locale-scoped client
-     * All content operations on the returned client will use the specified locale
+     *
+     * Every read the returned client builds — `content()`, `asset()`, `singleton()`, `settings()`,
+     * `search()`, `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — is in this
+     * locale unless the call names one of its own, which wins.
      *
      * Type-safe when schema is provided: autocompletes valid locale codes!
      *
@@ -2935,9 +3093,10 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```typescript
      * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
      *
-     * // All operations use Spanish
+     * // Reads use Spanish
      * const products = await spanish.content('product').query().execute()
      * const homepage = await spanish.singleton('homepage').fetch()
+     * const results = await spanish.search('zapatos').execute()
      *
      * // Original client unchanged
      * const englishProducts = await relyio.content('product').query().execute()
@@ -3033,4 +3192,4 @@ declare function createClient<TSchema extends AnySchemaDefinition>(config: Typed
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { type SearchBlock as $, type ActiveSandbox as A, type AutocompleteSuggestion as B, type Change as C, type AutocompleteResponse as D, type ExtendedQueryResult as E, type SimilarResult as F, type SimilarResponse as G, HttpClient as H, type SearchFilter as I, type SearchFields as J, BatchClient as K, BatchBuilder as L, type BatchMethod as M, type BatchOperation as N, type BatchOptions as O, type Project as P, type BatchOperationResult as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type BatchSummary as U, type BatchResponse as V, AdhocQueryClient as W, AdhocQueryBuilder as X, type FetchBlock as Y, type AggregateBlock as Z, type AggregateMetric as _, type TypedClientConfig as a, type SimilarBlock as a0, type FilterValue as a1, type FullTextConfig as a2, type AdhocQueryDefinition as a3, type AdhocQueryOptions as a4, type QueryMetadata as a5, type AdhocQueryResult as a6, AssetClient as a7, AssetFileBuilder as a8, AssetUploadBuilder as a9, FileUploadError as aA, FileValidationError as aB, type FileValidationConstraints as aC, validateFile as aD, isAssetEntry as aa, type AssetVisibility as ab, type FileStatus as ac, type FileBackend as ad, type AssetFileBlock as ae, type AssetFileExtracted as af, type AssetUrls as ag, type AssetEntryResponse as ah, type PopulatedAssetReference as ai, type PresignInput as aj, type PresignResult as ak, type ConfirmInput as al, type ConfirmResult as am, type ResolveUrlInput as an, type ResolveUrlResult as ao, type CreateAssetOptions as ap, type WaitUntilReadyOptions as aq, type MultipartCreateResult as ar, type MultipartPart as as, type MultipartTarget as at, type UploadProgress as au, ResourceNotFoundError as av, ResourceConflictError as aw, ResourceExpiredError as ax, isResourceNotFound as ay, type FileErrorCode as az, type ClientSchema as b, createClient as c, type RegisteredSchema as d, type SendOptions as e, entityTagOf as f, type ConditionalWriteOptions as g, type RetryableWriteOptions as h, ChangesExpiredError as i, type ChangesOptions as j, type ChangesExpiredReason as k, ContentClient as l, SingletonClient as m, SettingsClient as n, ContentQueryBuilder as o, ContentByIdBuilder as p, type ChildrenOptions as q, type SingletonFetchOptions as r, type SettingsFetchOptions as s, SearchClient as t, SearchBuilder as u, AutocompleteBuilder as v, SimilarBuilder as w, type SearchMode as x, type SearchResultItem as y, type SearchResponse as z };
+export { AdhocQueryBuilder as $, type ActiveSandbox as A, type SearchResponse as B, ChangesExpiredError as C, type AutocompleteSuggestion as D, type ExtendedQueryResult as E, type AutocompleteResponse as F, type SimilarResult as G, HttpClient as H, type SimilarResponse as I, type SearchFilter as J, type SearchFields as K, type SearchSort as L, type SearchTypeName as M, type SearchEntry as N, BatchClient as O, type Project as P, BatchBuilder as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type BatchMethod as U, type BatchOperation as V, type BatchOptions as W, type BatchOperationResult as X, type BatchSummary as Y, type BatchResponse as Z, AdhocQueryClient as _, type Change as a, type FetchBlock as a0, type AggregateBlock as a1, type AggregateMetric as a2, type SearchBlock as a3, type SimilarBlock as a4, type FilterValue as a5, type FullTextConfig as a6, type AdhocQueryDefinition as a7, type AdhocQueryOptions as a8, type QueryMetadata as a9, ResourceConflictError as aA, ResourceExpiredError as aB, isResourceNotFound as aC, type FileErrorCode as aD, FileUploadError as aE, FileValidationError as aF, type FileValidationConstraints as aG, validateFile as aH, type AdhocQueryResult as aa, AssetClient as ab, AssetFileBuilder as ac, AssetUploadBuilder as ad, isAssetEntry as ae, type AssetVisibility as af, type FileStatus as ag, type FileBackend as ah, type AssetFileBlock as ai, type AssetFileExtracted as aj, type AssetUrls as ak, type AssetEntryResponse as al, type PopulatedAssetReference as am, type PresignInput as an, type PresignResult as ao, type ConfirmInput as ap, type ConfirmResult as aq, type ResolveUrlInput as ar, type ResolveUrlResult as as, type CreateAssetOptions as at, type WaitUntilReadyOptions as au, type MultipartCreateResult as av, type MultipartPart as aw, type MultipartTarget as ax, type UploadProgress as ay, ResourceNotFoundError as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, ContentClient as m, SingletonClient as n, SettingsClient as o, ContentQueryBuilder as p, ContentByIdBuilder as q, type ChildrenOptions as r, type SingletonFetchOptions as s, type SettingsFetchOptions as t, SearchClient as u, SearchBuilder as v, AutocompleteBuilder as w, SimilarBuilder as x, type SearchMode as y, type SearchResultItem as z };