@relyio/sdk 0.4.0 → 0.6.0

package/dist/{index-BvO6HDtY.d.cts → index-XqoGUaAY.d.ts}

@@ -1,6 +1,69 @@
-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-DFehx5sI.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-yPbhZc6q.js';
+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-ChvAzY8H.js';
+import { Q as InferContentType, a6 as InferAssetType, a0 as InferSingleton } from './define-content-type-CDB3kyeA.js';
+import { DevUnreadableReason } from './dev-handshake/index.js';
+
+/**
+ * Dev-mode detection for `relyio dev` sandboxes — the SDK's I/O shell over `../dev-handshake`.
+ *
+ * Every rule about the handshake — the path, the env names, the required fields, the deadline —
+ * lives in `@relyio/sdk/dev-handshake`, which `relyio dev` imports too. What is left here is the
+ * part that is genuinely the SDK's: reading env and walking the filesystem from the cwd, both of
+ * which have to happen without a static `node:*` import so the module stays browser-safe.
+ *
+ * Node access goes through `process.getBuiltinModule` (Node ≥ 20.16 / 22, and the platform targets
+ * Node 24), which is absent in browsers and edge runtimes — so the resolver is inert everywhere it
+ * should be, and a bundler never has to shim `fs`.
+ *
+ * **Order: env, then file.** The wrapped-child env is the primary carrier and wins. Before REL-647
+ * it won *unconditionally*, because it had no deadline to lose on; it now goes through the same
+ * rule the file does.
+ */
+
+/**
+ * What the handshake says about the sandbox, as the preview toolbar displays it
+ * (`sdk-surfaces-spec.md` decision 22). `TypedRelyIOClient.sandbox` returns it.
+ *
+ * **Plain data, on purpose.** In Next the toolbar is rendered from a server layout, and a client
+ * cannot cross the RSC boundary — while the browser cannot read the handshake at all, because this
+ * module is inert without `process.getBuiltinModule`. So the server-created client's `sandbox` is the
+ * prop the toolbar is handed, and it has to survive `JSON` unchanged: strings and `null`, dates as
+ * the ISO strings the handshake carried, no class instances.
+ *
+ * **No key.** The handshake also carries the sandbox's preview key; that is the client's credential,
+ * held beside this value in {@link DevResolution} and never inside it, so handing the state around
+ * does not hand the key with it.
+ *
+ * - `active` — the client targets the sandbox. `branchId` is `null` from the env carrier, which names
+ *   no branch; only `.relyio/dev.json` does. `expiresAt` is `null` for an unbounded sandbox.
+ * - `expired` / `unreadable` — a handshake was found and refused; the client targets the configured
+ *   dataset and key, and `mergeConfig` has said so on the console.
+ * - `absent` — no handshake on either carrier. This is also what a browser or edge runtime reads,
+ *   since neither can see the env or the file.
+ * - `disabled` — detection did not run: `dev: false` was passed, or `NODE_ENV === 'production'`
+ *   and `dev: true` was not.
+ */
+type SandboxState = {
+    state: 'active';
+    datasetId: string;
+    branchId: string | null;
+    expiresAt: string | null;
+    source: 'env' | 'file';
+} | {
+    state: 'expired';
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+} | {
+    state: 'disabled';
+};
+/** The sandbox the client targets, once a carrier has been accepted. */
+type ActiveSandbox = Extract<SandboxState, {
+    state: 'active';
+}>;
 
 /**
  * What a call site supplies beside the route it named.
@@ -67,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>>;
     /**
@@ -133,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;
 }
 
@@ -189,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
      */
@@ -391,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
@@ -408,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
@@ -556,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**.
@@ -574,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;
@@ -591,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
@@ -1167,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')
@@ -1178,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
@@ -1265,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')
@@ -1276,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
@@ -1355,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
  */
@@ -1430,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
  *
@@ -1450,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?;
     /**
-     * Search within a single content type
+     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     */
+    constructor(httpClient: HttpClient, query: string, defaultLocale?: string | undefined);
+    /**
+     * 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
@@ -1480,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
@@ -1531,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
@@ -1586,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
@@ -1649,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
@@ -1773,6 +1974,7 @@ declare class BatchBuilder<TSchema = unknown> {
     private readonly httpClient;
     private operations;
     private defaultOptions;
+    private requestHeaders;
     constructor(httpClient: HttpClient);
     /**
      * Add a create operation
@@ -1910,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
      */
@@ -2030,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
  */
@@ -2202,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
@@ -2364,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
      */
@@ -2374,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
@@ -2521,42 +2750,20 @@ interface ChangesOptions {
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
 }
+interface ChangesHeadOptions {
+    /** Cancels the request; the promise then rejects. */
+    signal?: AbortSignal;
+}
 
 /**
- * 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
- *   }
- * }
- * ```
+ * The key's project, as `GET /v1/project` describes it: organization, project, dataset and branch,
+ * each by id and name, and `studioUrl` — the Studio root the preview toolbar deep-links from
+ * (`sdk-surfaces-spec.md` decision 24), or `null` when the service has no Dashboard address.
  *
- * — 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.
+ * Read from the committed document's `application/json` content by name, never written here
+ * (`INV-API-CLIENT-IS-DERIVED`); `derived-transport.types.ts` holds the two equal.
  */
-type RegisteredSchema = Register extends {
-    schema: infer S extends AnySchemaDefinition;
-} ? S : undefined;
-
+type Project = paths['/v1/project']['get']['responses'][200]['content']['application/json']['data'];
 /**
  * Client configuration with optional schema
  */
@@ -2592,6 +2799,7 @@ interface TypedClientConfig<TSchema extends AnySchemaDefinition | undefined = un
 declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined = undefined> {
     private httpClient;
     private config;
+    private _sandbox;
     private _search;
     private _batch;
     private _adhocQuery;
@@ -2601,6 +2809,21 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * Get the schema definition
      */
     get schema(): TSchema;
+    /**
+     * The `relyio dev` sandbox this client resolved at construction, as the preview toolbar displays
+     * it (`sdk-surfaces-spec.md` decision 22).
+     *
+     * Plain, JSON-serializable data and no key, so a server component can hand it to a client
+     * component as a prop — the browser cannot read the handshake itself, so a client created there
+     * reports `absent`. See {@link SandboxState} for what each state means.
+     *
+     * @example
+     * ```tsx
+     * // app/layout.tsx — a server component handing the state to a client component
+     * <SandboxBadge sandbox={relyio.sandbox} />
+     * ```
+     */
+    get sandbox(): SandboxState;
     /**
      * Get the ad-hoc query client
      */
@@ -2619,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.
      *
@@ -2638,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
@@ -2651,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
@@ -2663,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
@@ -2677,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
      *
@@ -2747,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
      *
@@ -2779,6 +3022,21 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     executeQuery<K extends TSchema extends AnySchemaDefinition ? SchemaQueryNames<TSchema> : string>(queryName: K, params?: Record<string, unknown>): Promise<unknown[]>;
+    /**
+     * Describe the project this key resolves to — `GET /v1/project`.
+     *
+     * `dataset` is the one this client's requests select (`dataset`, a sandbox from the `relyio dev`
+     * handshake, or the key's default), which is not always the project's default, so a Studio link
+     * built from `studioUrl` should carry it as `?dataset=`. `studioUrl` is `null` — a value, not an
+     * error — when the service has no Dashboard address configured.
+     *
+     * @example
+     * ```typescript
+     * const { studioUrl, dataset } = await relyio.project()
+     * if (studioUrl !== null) window.open(`${studioUrl}?dataset=${dataset.id}`)
+     * ```
+     */
+    project(): Promise<Project>;
     /**
      * Get schema information from the API
      */
@@ -2824,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!
      *
@@ -2832,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()
@@ -2930,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 FullTextConfig as $, AutocompleteBuilder as A, type SimilarResult as B, type ClientSchema as C, type SimilarResponse as D, type ExtendedQueryResult as E, type SearchFilter as F, type SearchFields as G, HttpClient as H, BatchClient as I, BatchBuilder as J, type BatchMethod as K, type BatchOperation as L, type BatchOptions as M, type BatchOperationResult as N, type BatchSummary as O, type BatchResponse as P, AdhocQueryClient as Q, type Register as R, type SendOptions as S, TypedRelyIOClient as T, AdhocQueryBuilder as U, type FetchBlock as V, type AggregateBlock as W, type AggregateMetric as X, type SearchBlock as Y, type SimilarBlock as Z, type FilterValue as _, type TypedClientConfig as a, type AdhocQueryDefinition as a0, type AdhocQueryOptions as a1, type QueryMetadata as a2, type AdhocQueryResult as a3, AssetClient as a4, AssetFileBuilder as a5, AssetUploadBuilder as a6, isAssetEntry as a7, type AssetVisibility as a8, type FileStatus as a9, validateFile as aA, type FileBackend as aa, type AssetFileBlock as ab, type AssetFileExtracted as ac, type AssetUrls as ad, type AssetEntryResponse as ae, type PopulatedAssetReference as af, type PresignInput as ag, type PresignResult as ah, type ConfirmInput as ai, type ConfirmResult as aj, type ResolveUrlInput as ak, type ResolveUrlResult as al, type CreateAssetOptions as am, type WaitUntilReadyOptions as an, type MultipartCreateResult as ao, type MultipartPart as ap, type MultipartTarget as aq, type UploadProgress as ar, ResourceNotFoundError as as, ResourceConflictError as at, ResourceExpiredError as au, isResourceNotFound as av, type FileErrorCode as aw, FileUploadError as ax, FileValidationError as ay, type FileValidationConstraints as az, type RegisteredSchema as b, createClient as c, type ConditionalWriteOptions as d, entityTagOf as e, type RetryableWriteOptions as f, ChangesExpiredError as g, type Change as h, type ChangesOptions as i, type ChangesExpiredReason as j, ContentClient as k, SingletonClient as l, SettingsClient as m, ContentQueryBuilder as n, ContentByIdBuilder as o, type ChildrenOptions as p, type SingletonFetchOptions as q, type SettingsFetchOptions as r, SearchClient as s, SearchBuilder as t, SimilarBuilder as u, type SearchMode as v, type SearchResultItem as w, type SearchResponse as x, type AutocompleteSuggestion as y, type AutocompleteResponse 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 };