@relyio/sdk 0.3.0 → 0.5.0

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

@@ -1,6 +1,69 @@
-import { M as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, G as PathParamsOf, r as ApiResponse, W as Wire, q as RequestConfig, B as BaseContent, c as WhereClause, e as SortOptions, f as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, v as BaseValidationError, u as ValidationViolation, H as components, R as RelyIOConfig } from './index-ulOrcfPa.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-BfXeR6K8.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.
@@ -109,6 +172,16 @@ declare class HttpClient {
      * Get current base URL
      */
     getBaseUrl(): string;
+    /**
+     * One attempt.
+     *
+     * The caller's `signal` and the timeout both end it, through one controller.
+     * The incumbent handed `fetch` the caller's signal **instead of** its own, so a
+     * request that passed a signal had no timeout at all — and a caller abort then
+     * surfaced as `Request timed out`. `timedOut` is what tells the two apart: a
+     * timeout is a `TimeoutError`, a caller abort is the platform's `AbortError`,
+     * rethrown as it came.
+     */
     private makeRequest;
     /**
      * Filter headers that browsers don't allow to be set manually
@@ -123,6 +196,7 @@ 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;
 }
@@ -2386,11 +2460,175 @@ declare class AdhocQueryClient {
 }
 
 /**
- * Type alias for any schema definition.
- * Uses `any` intentionally to accept schemas with any content types, components, etc.
- * This is necessary for the SDK to be flexible with user-defined schemas.
+ * Content and resource errors.
+ *
+ * `ContentTypeNotFoundError` and `ContentNotFoundError` were deleted at API5.
+ * The mapper reached them by sniffing `CONTENT_TYPE_NOT_FOUND` and
+ * `CONTENT_NOT_FOUND`, neither of which is in the closed vocabulary, so neither
+ * class was reachable. Both cases are `RESOURCE_NOT_FOUND`, whose declared
+ * `details` are `{ kind, id? }` — the same two facts, from the one code a route
+ * can actually declare.
+ */
+declare class ResourceNotFoundError extends SDKError {
+    readonly code = "RESOURCE_NOT_FOUND";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceConflictError extends SDKError {
+    readonly code = "RESOURCE_CONFLICT";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceExpiredError extends SDKError {
+    readonly code = "RESOURCE_EXPIRED";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+/**
+ * "Did the service say this resource does not exist?"
+ *
+ * Reads the **code**, not the status. Four contract codes are 4xx on a read and
+ * only one of them means "not there"; the incumbent checked `statusCode === 404`
+ * on the thrown value, and a second arm duck-typed a plain object for the same
+ * number so a hand-written test double would pass. Both are the branch
+ * `INV-API-CLIENT-IS-DERIVED` forbids where a code exists — and the second one
+ * only existed because the tests faked the boundary (rule 20). They now stub
+ * `fetch`, so the double is gone with the branch.
+ */
+declare function isResourceNotFound(error: unknown): boolean;
+
+/**
+ * `relyio.changes()` — the changes feed as a typed long-poll iterator
+ * (`sdk-surfaces-spec.md` decisions 16–18).
+ *
+ * Long-poll only, on purpose. `GET /v1/changes` is an ordinary cursor-paged
+ * collection the committed document declares, so each poll is one `send` over
+ * the one HTTP client (`INV-SS-ONE-CORE`, `INV-API-CLIENT-IS-DERIVED`). The SSE
+ * branch the route also serves would be a second transport path inside that
+ * client, and `parseResponse` buffers a whole body; it stays for `EventSource`
+ * and curl consumers.
+ */
+
+type PollChanges = paths['/v1/changes']['get'];
+/**
+ * The 200 body the document declares, read from its `application/json` content
+ * **by name**. The route also negotiates `text/event-stream`; naming the JSON
+ * content is what keeps that alternate from changing this type when the
+ * document gains it.
+ */
+type ChangesPageBody = PollChanges['responses'][200]['content']['application/json'];
+/**
+ * One change, as the committed document describes an item of the feed's `data`
+ * (`INV-SS-CHANGE-IS-IDS`: ids, content type, locale, kind and cursor — never a
+ * document).
+ *
+ * Read from the document, never written here: the api's route row names the
+ * `Change` component schema, and a change to it reaches this type when the
+ * document is regenerated. `changes.types.ts` holds it equal to the document's
+ * item, and fails if it is ever `unknown` again.
+ */
+type Change = ChangesPageBody['data'][number];
+/** Why a cursor could no longer be replayed. `unknown` when the message named neither. */
+type ChangesExpiredReason = 'retention' | 'dataset-replaced' | 'unknown';
+/**
+ * `RESOURCE_EXPIRED` from the changes feed: the cursor names a position the
+ * ledger can no longer replay from (`INV-SS-CURSOR-REPLAYS`). The consumer
+ * resyncs from the read path and starts again without a cursor.
+ *
+ * A `ResourceExpiredError`, so code that already catches that still does. The
+ * refusal declares no details, so `reason` is read from the message the api
+ * writes (`apps/services/api/src/changes/changes-request.ts` `refusalOf`).
+ */
+declare class ChangesExpiredError extends ResourceExpiredError {
+    readonly reason: ChangesExpiredReason;
+    /** The base class's signature, so `withContext` can rebuild one. */
+    constructor(message: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    static of(expired: ResourceExpiredError): ChangesExpiredError;
+}
+interface ChangesOptions {
+    /**
+     * A `page.nextCursor` — or a change's `cursor` — from an earlier poll. Omitted,
+     * the first poll answers the dataset's current position and no changes, at
+     * once, and the feed starts from there.
+     */
+    since?: string;
+    /** Content types to keep. Omitted keeps every type; an empty list is refused (400). */
+    types?: readonly string[];
+    /**
+     * Entry ids to keep. Omitted keeps every entry. The api refuses more than it
+     * allows (100 today) as `REQUEST_INVALID`, thrown from the iterator as an
+     * `InvalidPayloadError` on the first poll; the SDK does not restate the
+     * cap, so it cannot drift from the service's.
+     */
+    ids?: readonly string[];
+    /** Ledger rows one poll scans, 1 to 500; the api defaults to 100. */
+    limit?: number;
+    /**
+     * Ends the iteration. An abort — in flight, between polls, or while waiting
+     * out a `Retry-After` — makes the `for await` **complete**, with no further
+     * request and no `AbortError` thrown into the loop.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when the cursor has expired.
+     *
+     * - `'throw'` (default) — the iterator throws {@link ChangesExpiredError}.
+     * - `'resync'` — restart from the dataset's current position and keep going.
+     * - a function — resync, and call it with the error once the new position is
+     *   taken and before any change after it is yielded. This is the observable
+     *   form: whatever the consumer derived from the feed may be stale, so the
+     *   function is where it invalidates everything. The iterator waits for it.
+     */
+    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 {
+}
+/**
+ * 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,
+ * 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
  */
@@ -2426,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;
@@ -2435,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
      */
@@ -2555,6 +2809,32 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     batch(): BatchBuilder<NonNullable<TSchema>>;
+    /**
+     * Follow the dataset's changes feed: each write this key can see, as ids, in
+     * order, long-polled from `GET /v1/changes`.
+     *
+     * Lazy — nothing is requested until the first `next()`. It runs until
+     * `signal` aborts, which ends the `for await` cleanly rather than throwing.
+     * A change names what changed; refetch it through the ordinary read path
+     * (`INV-SS-CHANGE-IS-IDS`).
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController()
+     * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
+     *   // { entryId, contentType, locale, kind, cursor }
+     * }
+     * ```
+     *
+     * @example Resync when the cursor has expired
+     * ```typescript
+     * for await (const change of relyio.changes({
+     *   since: cursor,
+     *   onExpired: async () => invalidateEverything(),
+     * })) { … }
+     * ```
+     */
+    changes(options?: ChangesOptions): AsyncIterable<Change>;
     /**
      * Build and execute an ad-hoc query dynamically
      *
@@ -2587,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
      */
@@ -2713,12 +3008,29 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
  * // Content type names autocomplete!
  * const products = await relyio.content('product').fetchAll()
  * ```
- */
+ *
+ * @example After `relyio generate-types` (inferred, `INV-SS-TYPES-INFERRED`)
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ *
+ * // The generated `schema.ts` augments `Register`, so no generic and no `schema:` are needed
+ * const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+ * ```
+ *
+ * The overload without a schema comes first on purpose. Behind the generic one it was never
+ * chosen: with no `schema` to infer from, `TSchema` fell back to its constraint and the call
+ * resolved to `TypedRelyIOClient<AnySchemaDefinition>`. First, it takes every call that passes no
+ * schema, and returns the registered schema's client — or the untyped one when nothing registered.
+ * A `schema:` value fails its `schema?: undefined`, and an explicit generic skips it because it has
+ * no type parameter, so both reach the generic overload unchanged.
+ */
+declare function createClient(config: RelyIOConfig & {
+    schema?: undefined;
+}): TypedRelyIOClient<RegisteredSchema>;
 declare function createClient<TSchema extends AnySchemaDefinition>(config: TypedClientConfig<TSchema>): TypedRelyIOClient<TSchema>;
-declare function createClient(config: RelyIOConfig): TypedRelyIOClient<undefined>;
 /**
  * Helper type to extract schema from client
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { AssetFileBuilder as $, AutocompleteBuilder as A, BatchClient as B, type ClientSchema as C, type BatchOperation as D, type ExtendedQueryResult as E, type BatchOptions as F, type BatchOperationResult as G, HttpClient as H, type BatchSummary as I, type BatchResponse as J, AdhocQueryClient as K, AdhocQueryBuilder as L, type FetchBlock as M, type AggregateBlock as N, type AggregateMetric as O, type SearchBlock as P, type SimilarBlock as Q, type RetryableWriteOptions as R, type SendOptions as S, TypedRelyIOClient as T, type FilterValue as U, type FullTextConfig as V, type AdhocQueryDefinition as W, type AdhocQueryOptions as X, type QueryMetadata as Y, type AdhocQueryResult as Z, AssetClient as _, type TypedClientConfig as a, AssetUploadBuilder as a0, isAssetEntry as a1, type AssetVisibility as a2, type FileStatus as a3, type FileBackend as a4, type AssetFileBlock as a5, type AssetFileExtracted as a6, type AssetUrls as a7, type AssetEntryResponse as a8, type PopulatedAssetReference as a9, type PresignInput as aa, type PresignResult as ab, type ConfirmInput as ac, type ConfirmResult as ad, type ResolveUrlInput as ae, type ResolveUrlResult as af, type CreateAssetOptions as ag, type WaitUntilReadyOptions as ah, type MultipartCreateResult as ai, type MultipartPart as aj, type MultipartTarget as ak, type UploadProgress as al, type FileErrorCode as am, FileUploadError as an, FileValidationError as ao, type FileValidationConstraints as ap, validateFile as aq, type ConditionalWriteOptions as b, createClient as c, ContentClient as d, entityTagOf as e, SingletonClient as f, SettingsClient as g, ContentQueryBuilder as h, ContentByIdBuilder as i, type ChildrenOptions as j, type SingletonFetchOptions as k, type SettingsFetchOptions as l, SearchClient as m, SearchBuilder as n, SimilarBuilder as o, type SearchMode as p, type SearchResultItem as q, type SearchResponse as r, type AutocompleteSuggestion as s, type AutocompleteResponse as t, type SimilarResult as u, type SimilarResponse as v, type SearchFilter as w, type SearchFields as x, BatchBuilder as y, type BatchMethod as z };
+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 };