@relyio/sdk 0.4.0 → 0.5.0

package/dist/{chunk-43VPZT2G.js → chunk-5AZUUV5B.js}

@@ -768,6 +768,7 @@ var DECLARED_PATHS = {
   "/v1/meta/schema": true,
   "/v1/meta/schema/{contentType}": true,
   "/v1/meta/schema/{contentType}/fields": true,
+  "/v1/project": true,
   "/v1/query": true,
   "/v1/search": true,
   "/v1/search/autocomplete": true,
@@ -4176,6 +4177,10 @@ function aborted(signal) {
 __name(aborted, "aborted");
 
 // src/config/dev-detection.ts
+function sandboxStateOf(resolution) {
+  return resolution.state === "active" ? resolution.sandbox : resolution;
+}
+__name(sandboxStateOf, "sandboxStateOf");
 function getProcess() {
   return typeof process !== "undefined" ? process : void 0;
 }
@@ -4199,11 +4204,14 @@ function resolveFromEnv(proc, now) {
     case "active":
       return {
         state: "active",
-        override: {
-          dataset: verdict.credentials.dataset,
-          apiKey: verdict.credentials.apiKey,
+        sandbox: {
+          state: "active",
+          datasetId: verdict.credentials.dataset,
+          branchId: null,
+          expiresAt: verdict.expiresAt,
           source: "env"
-        }
+        },
+        apiKey: verdict.credentials.apiKey
       };
     case "expired":
       return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4234,11 +4242,14 @@ function resolveFromFile(proc, now) {
         case "active":
           return {
             state: "active",
-            override: {
-              dataset: verdict.context.datasetId,
-              apiKey: verdict.context.previewApiKey,
+            sandbox: {
+              state: "active",
+              datasetId: verdict.context.datasetId,
+              branchId: verdict.context.branchId,
+              expiresAt: verdict.context.expiresAt,
               source: "file"
-            }
+            },
+            apiKey: verdict.context.previewApiKey
           };
         case "expired":
           return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4319,7 +4330,7 @@ function validateConfig(config) {
 }
 __name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
-function mergeConfig(userConfig) {
+function resolveConfig(userConfig) {
   validateConfig(userConfig);
   const merged = {
     ...DEFAULT_CONFIG,
@@ -4347,12 +4358,12 @@ function mergeConfig(userConfig) {
   };
   const dev = resolveDevOverride(userConfig.dev);
   if (dev.state === "active") {
-    merged.apiKey = dev.override.apiKey;
-    merged.dataset = dev.override.dataset;
+    merged.apiKey = dev.apiKey;
+    merged.dataset = dev.sandbox.datasetId;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
-        `[RelyIO] Sandbox dev mode active (${dev.override.source}) \u2014 targeting dataset "${dev.override.dataset}" with a scoped preview key.`
+        `[RelyIO] Sandbox dev mode active (${dev.sandbox.source}) \u2014 targeting dataset "${dev.sandbox.datasetId}" with a scoped preview key.`
       );
     }
   } else if (dev.state === "expired" && !devOverrideNotified) {
@@ -4366,9 +4377,9 @@ function mergeConfig(userConfig) {
       `[RelyIO] Your .relyio/dev.json could not be read (${dev.reason}) \u2014 ignoring it and using the configured dataset "${merged.dataset}". Run \`relyio dev\` to rewrite it.`
     );
   }
-  return merged;
+  return { config: merged, sandbox: sandboxStateOf(dev) };
 }
-__name(mergeConfig, "mergeConfig");
+__name(resolveConfig, "resolveConfig");
 
 // src/client/create-client.ts
 var API_VERSION_SEGMENT = "v1";
@@ -4376,13 +4387,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   constructor(config) {
     __publicField(this, "httpClient");
     __publicField(this, "config");
+    __publicField(this, "_sandbox");
     __publicField(this, "_search");
     __publicField(this, "_batch");
     __publicField(this, "_adhocQuery");
     __publicField(this, "_schema");
     const { schema, ...clientConfig } = config;
     this._schema = schema;
-    this.config = mergeConfig(clientConfig);
+    const resolved = resolveConfig(clientConfig);
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
     this._search = new SearchClient(this.httpClient);
     this._batch = new BatchClient(this.httpClient);
@@ -4397,6 +4411,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   get schema() {
     return this._schema;
   }
+  /**
+   * 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() {
+    return this._sandbox;
+  }
   /**
    * Get the ad-hoc query client
    */
@@ -4620,6 +4651,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     const payload = readPayload(response.body);
     return Array.isArray(payload) ? payload : [payload];
   }
+  /**
+   * 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}`)
+   * ```
+   */
+  async project() {
+    return this.httpClient.fetchPayload("/v1/project", "get", {});
+  }
   /**
    * Get schema information from the API
    */
@@ -4666,7 +4714,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * Update the configuration and reinitialize all clients
    */
   updateConfig(newConfig) {
-    this.config = mergeConfig({ ...this.config, ...newConfig });
+    const resolved = resolveConfig({ ...this.config, ...newConfig });
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
     this._search = new SearchClient(this.httpClient);
     this._batch = new BatchClient(this.httpClient);
@@ -4764,5 +4814,5 @@ function createClient(config) {
 __name(createClient, "createClient");
 
 export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthenticationError, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, ChangesExpiredError, ConnectionError, ContentByIdBuilder, ContentClient, ContentQueryBuilder, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidFieldTypeError, InvalidPayloadError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, RequiredFieldError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, SchemaValidationError, SearchBuilder, SearchClient, ServerError, ServiceIndeterminateError, SettingsClient, SimilarBuilder, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, entityTagOf, isAssetEntry, isResourceNotFound, matchRoute, validateFile };
-//# sourceMappingURL=chunk-43VPZT2G.js.map
-//# sourceMappingURL=chunk-43VPZT2G.js.map
+//# sourceMappingURL=chunk-5AZUUV5B.js.map
+//# sourceMappingURL=chunk-5AZUUV5B.js.map

package/dist/{chunk-XS32U2UP.cjs → chunk-CIRT6TVT.cjs}

@@ -770,6 +770,7 @@ var DECLARED_PATHS = {
   "/v1/meta/schema": true,
   "/v1/meta/schema/{contentType}": true,
   "/v1/meta/schema/{contentType}/fields": true,
+  "/v1/project": true,
   "/v1/query": true,
   "/v1/search": true,
   "/v1/search/autocomplete": true,
@@ -4178,6 +4179,10 @@ function aborted(signal) {
 chunkMWMSFIWN_cjs.__name(aborted, "aborted");
 
 // src/config/dev-detection.ts
+function sandboxStateOf(resolution) {
+  return resolution.state === "active" ? resolution.sandbox : resolution;
+}
+chunkMWMSFIWN_cjs.__name(sandboxStateOf, "sandboxStateOf");
 function getProcess() {
   return typeof process !== "undefined" ? process : void 0;
 }
@@ -4201,11 +4206,14 @@ function resolveFromEnv(proc, now) {
     case "active":
       return {
         state: "active",
-        override: {
-          dataset: verdict.credentials.dataset,
-          apiKey: verdict.credentials.apiKey,
+        sandbox: {
+          state: "active",
+          datasetId: verdict.credentials.dataset,
+          branchId: null,
+          expiresAt: verdict.expiresAt,
           source: "env"
-        }
+        },
+        apiKey: verdict.credentials.apiKey
       };
     case "expired":
       return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4236,11 +4244,14 @@ function resolveFromFile(proc, now) {
         case "active":
           return {
             state: "active",
-            override: {
-              dataset: verdict.context.datasetId,
-              apiKey: verdict.context.previewApiKey,
+            sandbox: {
+              state: "active",
+              datasetId: verdict.context.datasetId,
+              branchId: verdict.context.branchId,
+              expiresAt: verdict.context.expiresAt,
               source: "file"
-            }
+            },
+            apiKey: verdict.context.previewApiKey
           };
         case "expired":
           return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4321,7 +4332,7 @@ function validateConfig(config) {
 }
 chunkMWMSFIWN_cjs.__name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
-function mergeConfig(userConfig) {
+function resolveConfig(userConfig) {
   validateConfig(userConfig);
   const merged = {
     ...DEFAULT_CONFIG,
@@ -4349,12 +4360,12 @@ function mergeConfig(userConfig) {
   };
   const dev = resolveDevOverride(userConfig.dev);
   if (dev.state === "active") {
-    merged.apiKey = dev.override.apiKey;
-    merged.dataset = dev.override.dataset;
+    merged.apiKey = dev.apiKey;
+    merged.dataset = dev.sandbox.datasetId;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
-        `[RelyIO] Sandbox dev mode active (${dev.override.source}) \u2014 targeting dataset "${dev.override.dataset}" with a scoped preview key.`
+        `[RelyIO] Sandbox dev mode active (${dev.sandbox.source}) \u2014 targeting dataset "${dev.sandbox.datasetId}" with a scoped preview key.`
       );
     }
   } else if (dev.state === "expired" && !devOverrideNotified) {
@@ -4368,9 +4379,9 @@ function mergeConfig(userConfig) {
       `[RelyIO] Your .relyio/dev.json could not be read (${dev.reason}) \u2014 ignoring it and using the configured dataset "${merged.dataset}". Run \`relyio dev\` to rewrite it.`
     );
   }
-  return merged;
+  return { config: merged, sandbox: sandboxStateOf(dev) };
 }
-chunkMWMSFIWN_cjs.__name(mergeConfig, "mergeConfig");
+chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
 
 // src/client/create-client.ts
 var API_VERSION_SEGMENT = "v1";
@@ -4378,13 +4389,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   constructor(config) {
     chunkMWMSFIWN_cjs.__publicField(this, "httpClient");
     chunkMWMSFIWN_cjs.__publicField(this, "config");
+    chunkMWMSFIWN_cjs.__publicField(this, "_sandbox");
     chunkMWMSFIWN_cjs.__publicField(this, "_search");
     chunkMWMSFIWN_cjs.__publicField(this, "_batch");
     chunkMWMSFIWN_cjs.__publicField(this, "_adhocQuery");
     chunkMWMSFIWN_cjs.__publicField(this, "_schema");
     const { schema, ...clientConfig } = config;
     this._schema = schema;
-    this.config = mergeConfig(clientConfig);
+    const resolved = resolveConfig(clientConfig);
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
     this._search = new SearchClient(this.httpClient);
     this._batch = new BatchClient(this.httpClient);
@@ -4399,6 +4413,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   get schema() {
     return this._schema;
   }
+  /**
+   * 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() {
+    return this._sandbox;
+  }
   /**
    * Get the ad-hoc query client
    */
@@ -4622,6 +4653,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     const payload = readPayload(response.body);
     return Array.isArray(payload) ? payload : [payload];
   }
+  /**
+   * 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}`)
+   * ```
+   */
+  async project() {
+    return this.httpClient.fetchPayload("/v1/project", "get", {});
+  }
   /**
    * Get schema information from the API
    */
@@ -4668,7 +4716,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * Update the configuration and reinitialize all clients
    */
   updateConfig(newConfig) {
-    this.config = mergeConfig({ ...this.config, ...newConfig });
+    const resolved = resolveConfig({ ...this.config, ...newConfig });
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
     this._search = new SearchClient(this.httpClient);
     this._batch = new BatchClient(this.httpClient);
@@ -4820,5 +4870,5 @@ exports.isAssetEntry = isAssetEntry;
 exports.isResourceNotFound = isResourceNotFound;
 exports.matchRoute = matchRoute;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-XS32U2UP.cjs.map
-//# sourceMappingURL=chunk-XS32U2UP.cjs.map
+//# sourceMappingURL=chunk-CIRT6TVT.cjs.map
+//# sourceMappingURL=chunk-CIRT6TVT.cjs.map

package/dist/client/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkXS32U2UP_cjs = require('../chunk-XS32U2UP.cjs');
+var chunkCIRT6TVT_cjs = require('../chunk-CIRT6TVT.cjs');
 require('../chunk-LSRPMNPT.cjs');
 require('../chunk-MWMSFIWN.cjs');
 
@@ -8,11 +8,11 @@ require('../chunk-MWMSFIWN.cjs');
 
 Object.defineProperty(exports, "TypedRelyIOClient", {
   enumerable: true,
-  get: function () { return chunkXS32U2UP_cjs.TypedRelyIOClient; }
+  get: function () { return chunkCIRT6TVT_cjs.TypedRelyIOClient; }
 });
 Object.defineProperty(exports, "createClient", {
   enumerable: true,
-  get: function () { return chunkXS32U2UP_cjs.createClient; }
+  get: function () { return chunkCIRT6TVT_cjs.createClient; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/client/index.d.cts

@@ -1,4 +1,5 @@
-export { C as ClientSchema, R as Register, b as RegisteredSchema, a as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-BvO6HDtY.cjs';
-import '../index-DFehx5sI.cjs';
+export { b as ClientSchema, R as Register, d as RegisteredSchema, a as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-BozPz4n1.cjs';
+import '../index-C5mRBb6t.cjs';
 import '../define-content-type-CBfnTWSS.cjs';
 import '../define-schema-2xbHgtK-.cjs';
+import '../dev-handshake/index.cjs';

package/dist/client/index.d.ts

@@ -1,4 +1,5 @@
-export { C as ClientSchema, R as Register, b as RegisteredSchema, a as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-BzOFJJKS.js';
-import '../index-FDak5ofk.js';
+export { b as ClientSchema, R as Register, d as RegisteredSchema, a as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-Dzo-upNS.js';
+import '../index-mXUx2H99.js';
 import '../define-content-type-CBfnTWSS.js';
 import '../define-schema-DzYXk4HL.js';
+import '../dev-handshake/index.js';

package/dist/client/index.js

@@ -1,4 +1,4 @@
-export { TypedRelyIOClient, createClient } from '../chunk-43VPZT2G.js';
+export { TypedRelyIOClient, createClient } from '../chunk-5AZUUV5B.js';
 import '../chunk-BBUB7C2Z.js';
 import '../chunk-XQ4QHWZE.js';
 //# sourceMappingURL=index.js.map

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

@@ -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 { 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 { DevUnreadableReason } from './dev-handshake/index.cjs';
+
+/**
+ * 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.
@@ -2557,6 +2620,15 @@ 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,
+ * 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.
+ *
+ * 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 Project = paths['/v1/project']['get']['responses'][200]['content']['application/json']['data'];
 /**
  * Client configuration with optional schema
  */
@@ -2592,6 +2664,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 +2674,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
      */
@@ -2779,6 +2867,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
      */
@@ -2930,4 +3033,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 { 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 };