@relyio/sdk 0.2.1 → 0.3.0

package/dist/dev-handshake/index.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var chunkLSRPMNPT_cjs = require('../chunk-LSRPMNPT.cjs');
+require('../chunk-MWMSFIWN.cjs');
+
+
+
+Object.defineProperty(exports, "DEV_CONTEXT_DIR", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_DIR; }
+});
+Object.defineProperty(exports, "DEV_CONTEXT_FILE", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_FILE; }
+});
+Object.defineProperty(exports, "DEV_CONTEXT_FILENAME", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_FILENAME; }
+});
+Object.defineProperty(exports, "DEV_ENV", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_ENV; }
+});
+Object.defineProperty(exports, "buildDevEnv", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.buildDevEnv; }
+});
+Object.defineProperty(exports, "parseDevContextFile", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.parseDevContextFile; }
+});
+Object.defineProperty(exports, "parseDevEnv", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.parseDevEnv; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/dev-handshake/index.d.cts

@@ -0,0 +1,144 @@
+/**
+ * The `relyio dev` handshake: the one declaration of how a sandbox reaches a running app.
+ *
+ * `relyio dev` provisions an ephemeral sandbox and hands its connection details to the developer's
+ * app by two carriers, which `sandboxes-spec.md` presents as interchangeable:
+ *
+ *  1. **Env** — `relyio dev -- pnpm dev` injects `RELYIO_DEV_*` into the wrapped child process.
+ *  2. **File** — `.relyio/dev.json`, for an app started standalone beside the cockpit.
+ *
+ * Three consumers read this: the SDK (both carriers), and `relyio promote` (the file, to work out
+ * which sandbox this repo is developing against). Before REL-647 each had its own copy of the
+ * answer and the three disagreed — the file required `branchId` in the CLI and not in the SDK, an
+ * unparseable deadline read as *unbounded*, and **the env carrier had no expiry at all**, so
+ * `relyio dev` and `relyio dev -- pnpm dev` were not in fact interchangeable: the same lapsed
+ * sandbox stopped working under one and kept working for the life of the process under the other.
+ *
+ * So this module is the declaration, and it is deliberately **pure** — no `node:*`, no I/O, no
+ * clock of its own. Each consumer keeps the I/O shell it needs (the SDK cannot statically import
+ * `node:fs`; the CLI is async and knows the project root) and none of them keeps a rule.
+ *
+ * **On the direction of the dependency.** The CLI *writes* this file and the SDK *reads* it, so
+ * publishing the declaration from the reader inverts writer→reader, which is worth knowing when
+ * you change it. It is the right trade anyway: the SDK is already dependency-free and browser-safe
+ * by construction, so the declaration costs it nothing, while the CLI bundles every `@relyio/*`
+ * into its published artifact and can absorb the import. The alternative — a third package — buys
+ * a version stream for four constants and a parser.
+ */
+/** Directory, relative to the project root, that holds the dev artifact. Hidden, git-ignored. */
+declare const DEV_CONTEXT_DIR = ".relyio";
+/** Filename of the dev artifact inside {@link DEV_CONTEXT_DIR}. */
+declare const DEV_CONTEXT_FILENAME = "dev.json";
+/**
+ * Path of the dev artifact relative to the project root, POSIX-separated.
+ *
+ * The one place this path is spelled. It is also exactly the `.gitignore` entry, which must use a
+ * forward slash on every platform — so the constant is a literal rather than a `path.join`, and
+ * callers that need a filesystem path join it onto their own root.
+ */
+declare const DEV_CONTEXT_FILE = ".relyio/dev.json";
+/**
+ * The environment variables `relyio dev` injects into a wrapped child process.
+ *
+ * `expiresAt` is the REL-647 addition. Without it the env carrier could not express a deadline, so
+ * it was exempt from the expiry the file carrier enforced — which is the whole of Gap 3.
+ */
+declare const DEV_ENV: {
+    readonly dataset: "RELYIO_DEV_DATASET";
+    readonly apiKey: "RELYIO_DEV_API_KEY";
+    readonly expiresAt: "RELYIO_DEV_EXPIRES_AT";
+};
+/** The `.relyio/dev.json` shape, as `relyio dev` writes it. All four keys; `expiresAt` nullable. */
+interface DevContext {
+    /** Ephemeral sandbox dataset the app should read (`X-RelyIO-Dataset`). */
+    datasetId: string;
+    /** Scoped read-only preview key for the sandbox dataset (`X-API-Key`). */
+    previewApiKey: string;
+    /** Sandbox branch id — informational to the SDK; `relyio promote` identifies the sandbox by it. */
+    branchId: string;
+    /**
+     * ISO deadline of the sandbox's current lifecycle state, or null when unbounded.
+     *
+     * This is `sandbox.expiresAt` from the provisioning bundle — when the sandbox is due to be
+     * suspended or archived — not the preview key's own `expiresAt`. Past it, the dataset may be
+     * archived and the key deactivated, so the handshake names a sandbox that no longer answers.
+     */
+    expiresAt: string | null;
+}
+/** The credentials a carrier yields once it has been accepted. */
+interface DevCredentials {
+    dataset: string;
+    apiKey: string;
+}
+/** Why a carrier's payload could not be understood. */
+type DevUnreadableReason = 'not-json' | 'missing-fields' | 'bad-expiry';
+/**
+ * What a carrier says, as a closed set of named states.
+ *
+ * There is deliberately no `null` or falsy arm, on any path. "Expired", "absent" and "corrupt" lead
+ * to different advice — refresh the key, start a sandbox, delete the file — and collapsing them to
+ * one falsy value is what let an app with a lapsed sandbox read **production** in silence and let
+ * `relyio promote` act on a stale identity. An absent input is a declared state, not a default.
+ */
+type DevContextVerdict = {
+    state: 'active';
+    context: DevContext;
+} | {
+    state: 'expired';
+    context: DevContext;
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/** What the env carrier says. It carries no `branchId`; only the file identifies a branch. */
+type DevEnvVerdict = {
+    state: 'active';
+    credentials: DevCredentials;
+    expiresAt: string | null;
+} | {
+    state: 'expired';
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/**
+ * Decide what the text of `.relyio/dev.json` says, against a caller-supplied clock.
+ *
+ * All three of `datasetId`, `previewApiKey` and `branchId` are **required**. `relyio dev` has
+ * always written all four keys and the spec documents all four, so a file missing one is corrupt
+ * rather than a narrower dialect — before REL-647 the CLI required `branchId` and the SDK did not,
+ * so one file read as absent to one binary and usable to the other.
+ *
+ * The clock is a parameter rather than a `Date.now()` inside, so the boundary is testable without
+ * faking time, and so this module stays pure.
+ */
+declare function parseDevContextFile(raw: string, now: number): DevContextVerdict;
+/**
+ * Build the `RELYIO_DEV_*` environment `relyio dev` injects into a wrapped child.
+ *
+ * The counterpart of {@link parseDevEnv}, and the reason the env names are single-sourced: the
+ * binary that writes them and the library that reads them now use one object. `expiresAt` is
+ * omitted rather than emitted empty when the sandbox is unbounded, so the variable's presence
+ * means "there is a deadline".
+ */
+declare function buildDevEnv(context: Pick<DevContext, 'datasetId' | 'previewApiKey' | 'expiresAt'>): Record<string, string>;
+/**
+ * Decide what the `RELYIO_DEV_*` environment says, against a caller-supplied clock.
+ *
+ * The env carrier names no branch, so it yields credentials rather than a {@link DevContext}. It
+ * applies the same deadline rule the file does — that equivalence is Gap 3, and the reason
+ * {@link DEV_ENV}`.expiresAt` exists at all.
+ *
+ * A deadline present but unreadable refuses the credentials. That is deliberate and is the same
+ * choice the file path makes: a wrapped process whose deadline we cannot read is not a process we
+ * can say is inside its window.
+ */
+declare function parseDevEnv(env: Record<string, string | undefined> | undefined, now: number): DevEnvVerdict;
+
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, type DevContext, type DevContextVerdict, type DevCredentials, type DevEnvVerdict, type DevUnreadableReason, buildDevEnv, parseDevContextFile, parseDevEnv };

package/dist/dev-handshake/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The `relyio dev` handshake: the one declaration of how a sandbox reaches a running app.
+ *
+ * `relyio dev` provisions an ephemeral sandbox and hands its connection details to the developer's
+ * app by two carriers, which `sandboxes-spec.md` presents as interchangeable:
+ *
+ *  1. **Env** — `relyio dev -- pnpm dev` injects `RELYIO_DEV_*` into the wrapped child process.
+ *  2. **File** — `.relyio/dev.json`, for an app started standalone beside the cockpit.
+ *
+ * Three consumers read this: the SDK (both carriers), and `relyio promote` (the file, to work out
+ * which sandbox this repo is developing against). Before REL-647 each had its own copy of the
+ * answer and the three disagreed — the file required `branchId` in the CLI and not in the SDK, an
+ * unparseable deadline read as *unbounded*, and **the env carrier had no expiry at all**, so
+ * `relyio dev` and `relyio dev -- pnpm dev` were not in fact interchangeable: the same lapsed
+ * sandbox stopped working under one and kept working for the life of the process under the other.
+ *
+ * So this module is the declaration, and it is deliberately **pure** — no `node:*`, no I/O, no
+ * clock of its own. Each consumer keeps the I/O shell it needs (the SDK cannot statically import
+ * `node:fs`; the CLI is async and knows the project root) and none of them keeps a rule.
+ *
+ * **On the direction of the dependency.** The CLI *writes* this file and the SDK *reads* it, so
+ * publishing the declaration from the reader inverts writer→reader, which is worth knowing when
+ * you change it. It is the right trade anyway: the SDK is already dependency-free and browser-safe
+ * by construction, so the declaration costs it nothing, while the CLI bundles every `@relyio/*`
+ * into its published artifact and can absorb the import. The alternative — a third package — buys
+ * a version stream for four constants and a parser.
+ */
+/** Directory, relative to the project root, that holds the dev artifact. Hidden, git-ignored. */
+declare const DEV_CONTEXT_DIR = ".relyio";
+/** Filename of the dev artifact inside {@link DEV_CONTEXT_DIR}. */
+declare const DEV_CONTEXT_FILENAME = "dev.json";
+/**
+ * Path of the dev artifact relative to the project root, POSIX-separated.
+ *
+ * The one place this path is spelled. It is also exactly the `.gitignore` entry, which must use a
+ * forward slash on every platform — so the constant is a literal rather than a `path.join`, and
+ * callers that need a filesystem path join it onto their own root.
+ */
+declare const DEV_CONTEXT_FILE = ".relyio/dev.json";
+/**
+ * The environment variables `relyio dev` injects into a wrapped child process.
+ *
+ * `expiresAt` is the REL-647 addition. Without it the env carrier could not express a deadline, so
+ * it was exempt from the expiry the file carrier enforced — which is the whole of Gap 3.
+ */
+declare const DEV_ENV: {
+    readonly dataset: "RELYIO_DEV_DATASET";
+    readonly apiKey: "RELYIO_DEV_API_KEY";
+    readonly expiresAt: "RELYIO_DEV_EXPIRES_AT";
+};
+/** The `.relyio/dev.json` shape, as `relyio dev` writes it. All four keys; `expiresAt` nullable. */
+interface DevContext {
+    /** Ephemeral sandbox dataset the app should read (`X-RelyIO-Dataset`). */
+    datasetId: string;
+    /** Scoped read-only preview key for the sandbox dataset (`X-API-Key`). */
+    previewApiKey: string;
+    /** Sandbox branch id — informational to the SDK; `relyio promote` identifies the sandbox by it. */
+    branchId: string;
+    /**
+     * ISO deadline of the sandbox's current lifecycle state, or null when unbounded.
+     *
+     * This is `sandbox.expiresAt` from the provisioning bundle — when the sandbox is due to be
+     * suspended or archived — not the preview key's own `expiresAt`. Past it, the dataset may be
+     * archived and the key deactivated, so the handshake names a sandbox that no longer answers.
+     */
+    expiresAt: string | null;
+}
+/** The credentials a carrier yields once it has been accepted. */
+interface DevCredentials {
+    dataset: string;
+    apiKey: string;
+}
+/** Why a carrier's payload could not be understood. */
+type DevUnreadableReason = 'not-json' | 'missing-fields' | 'bad-expiry';
+/**
+ * What a carrier says, as a closed set of named states.
+ *
+ * There is deliberately no `null` or falsy arm, on any path. "Expired", "absent" and "corrupt" lead
+ * to different advice — refresh the key, start a sandbox, delete the file — and collapsing them to
+ * one falsy value is what let an app with a lapsed sandbox read **production** in silence and let
+ * `relyio promote` act on a stale identity. An absent input is a declared state, not a default.
+ */
+type DevContextVerdict = {
+    state: 'active';
+    context: DevContext;
+} | {
+    state: 'expired';
+    context: DevContext;
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/** What the env carrier says. It carries no `branchId`; only the file identifies a branch. */
+type DevEnvVerdict = {
+    state: 'active';
+    credentials: DevCredentials;
+    expiresAt: string | null;
+} | {
+    state: 'expired';
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/**
+ * Decide what the text of `.relyio/dev.json` says, against a caller-supplied clock.
+ *
+ * All three of `datasetId`, `previewApiKey` and `branchId` are **required**. `relyio dev` has
+ * always written all four keys and the spec documents all four, so a file missing one is corrupt
+ * rather than a narrower dialect — before REL-647 the CLI required `branchId` and the SDK did not,
+ * so one file read as absent to one binary and usable to the other.
+ *
+ * The clock is a parameter rather than a `Date.now()` inside, so the boundary is testable without
+ * faking time, and so this module stays pure.
+ */
+declare function parseDevContextFile(raw: string, now: number): DevContextVerdict;
+/**
+ * Build the `RELYIO_DEV_*` environment `relyio dev` injects into a wrapped child.
+ *
+ * The counterpart of {@link parseDevEnv}, and the reason the env names are single-sourced: the
+ * binary that writes them and the library that reads them now use one object. `expiresAt` is
+ * omitted rather than emitted empty when the sandbox is unbounded, so the variable's presence
+ * means "there is a deadline".
+ */
+declare function buildDevEnv(context: Pick<DevContext, 'datasetId' | 'previewApiKey' | 'expiresAt'>): Record<string, string>;
+/**
+ * Decide what the `RELYIO_DEV_*` environment says, against a caller-supplied clock.
+ *
+ * The env carrier names no branch, so it yields credentials rather than a {@link DevContext}. It
+ * applies the same deadline rule the file does — that equivalence is Gap 3, and the reason
+ * {@link DEV_ENV}`.expiresAt` exists at all.
+ *
+ * A deadline present but unreadable refuses the credentials. That is deliberate and is the same
+ * choice the file path makes: a wrapped process whose deadline we cannot read is not a process we
+ * can say is inside its window.
+ */
+declare function parseDevEnv(env: Record<string, string | undefined> | undefined, now: number): DevEnvVerdict;
+
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, type DevContext, type DevContextVerdict, type DevCredentials, type DevEnvVerdict, type DevUnreadableReason, buildDevEnv, parseDevContextFile, parseDevEnv };

package/dist/dev-handshake/index.js

@@ -0,0 +1,4 @@
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, buildDevEnv, parseDevContextFile, parseDevEnv } from '../chunk-BBUB7C2Z.js';
+import '../chunk-XQ4QHWZE.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

@@ -1,5 +1,6 @@
-import { M as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, G as PathParamsOf, r as ApiResponse, W as Wire, q as RequestConfig, B as BaseContent, c as WhereClause, e as SortOptions, f as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, v as BaseValidationError, u as ValidationViolation, H as components, R as RelyIOConfig } from './index-BsUqCAu8.cjs';
-import { x as SchemaDefinition, y as SchemaContentTypeNames, a6 as InferContentType, K as SchemaAssetTypeNames, at as InferAssetType, z as SchemaSingletonNames, ac as InferSingleton, J as SchemaSettingsGroupNames, an as InferSettingsGroup, G as SchemaQueryNames, H as SchemaLocaleCodes } from './define-schema-DHvUCKwj.cjs';
+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 InferContentType } from './define-content-type-CBfnTWSS.cjs';
 
 /**
  * What a call site supplies beside the route it named.
@@ -38,7 +39,7 @@ declare class HttpClient {
     private baseUrl;
     private defaultHeaders;
     private timeout;
-    private retryConfig;
+    private retryPolicy;
     private debug;
     private logger?;
     private config;
@@ -56,7 +57,16 @@ declare class HttpClient {
         data: unknown;
     } ? Wire<P, M, T>['data'] : never>;
     /**
-     * Make an HTTP request with retry logic
+     * Make an HTTP request, retrying only where a retry is safe.
+     *
+     * The headers are merged **once**, before the first attempt, and every attempt
+     * sends that same object. That is what makes a minted `Idempotency-Key` stable
+     * across the retries of one logical write: the service sees one key and
+     * answers the replay from the original outcome instead of applying it twice.
+     *
+     * 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`.
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -113,7 +123,6 @@ declare class HttpClient {
     private mergeRequestConfig;
     private buildQueryString;
     private headersToObject;
-    private calculateRetryDelay;
     private sleep;
     private log;
 }
@@ -427,13 +436,20 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
  */
 interface RetryableWriteOptions {
     /**
-     * A caller-chosen key that makes a retry of **this** write safe.
+     * A key that makes a retry of **this** write safe.
      *
      * A replay inside the service's window returns the original outcome rather
      * than applying twice. The service derives that response from committed state
      * pinned to the recorded version — it does not store bytes — so a replay after
      * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
      * answered from a stale copy.
+     *
+     * **The SDK mints one when you do not.** It used to be caller-supplied and
+     * nothing else, which meant the default write carried no key while the retry
+     * loop replayed it anyway — the one mechanism that makes a replay safe was
+     * optional on the one path that needed it. Supply your own to make a key
+     * outlive the process: a job that may be restarted wants a key derived from
+     * the work, not one minted per call.
      */
     idempotencyKey?: string;
 }