@relyio/sdk 0.2.1 → 0.4.0

package/dist/{chunk-7W4MJXQ4.cjs → chunk-XS32U2UP.cjs}

@@ -1,5 +1,6 @@
 'use strict';
 
+var chunkLSRPMNPT_cjs = require('./chunk-LSRPMNPT.cjs');
 var chunkMWMSFIWN_cjs = require('./chunk-MWMSFIWN.cjs');
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -167,14 +168,17 @@ var _UsageQuotaExceededError = class _UsageQuotaExceededError extends SDKError {
 chunkMWMSFIWN_cjs.__name(_UsageQuotaExceededError, "UsageQuotaExceededError");
 var UsageQuotaExceededError = _UsageQuotaExceededError;
 var _RateLimitError = class _RateLimitError extends SDKError {
-  constructor(message = "Rate limit exceeded", limit, resetAt, context) {
+  constructor(message = "Rate limit exceeded", limit, resetAt, context, retryAfterMs) {
     super(message, 429, void 0, context);
     chunkMWMSFIWN_cjs.__publicField(this, "code", "RATE_LIMIT_EXCEEDED");
     chunkMWMSFIWN_cjs.__publicField(this, "retryable", true);
     chunkMWMSFIWN_cjs.__publicField(this, "limit");
     chunkMWMSFIWN_cjs.__publicField(this, "resetAt");
+    /** `Retry-After`, in milliseconds, where the response carried a readable one. */
+    chunkMWMSFIWN_cjs.__publicField(this, "retryAfterMs");
     this.limit = limit;
     this.resetAt = resetAt;
+    this.retryAfterMs = retryAfterMs;
   }
   getUserMessage() {
     return this.resetAt === void 0 ? "Too many requests. Please retry shortly." : `Too many requests. The window resets at ${this.resetAt}.`;
@@ -223,12 +227,15 @@ var _TransactionRolledBackError = class _TransactionRolledBackError extends SDKE
 chunkMWMSFIWN_cjs.__name(_TransactionRolledBackError, "TransactionRolledBackError");
 var TransactionRolledBackError = _TransactionRolledBackError;
 var _ServiceIndeterminateError = class _ServiceIndeterminateError extends SDKError {
-  constructor(message = "The service could not decide this request", missing, context) {
+  constructor(message = "The service could not decide this request", missing, context, retryAfterMs) {
     super(message, 503, void 0, context);
     chunkMWMSFIWN_cjs.__publicField(this, "code", "SERVICE_INDETERMINATE");
     chunkMWMSFIWN_cjs.__publicField(this, "retryable", true);
     chunkMWMSFIWN_cjs.__publicField(this, "missing");
+    /** `Retry-After`, in milliseconds. The contract requires the header on this code. */
+    chunkMWMSFIWN_cjs.__publicField(this, "retryAfterMs");
     this.missing = missing;
+    this.retryAfterMs = retryAfterMs;
   }
   getUserMessage() {
     return "The service is temporarily unable to answer. Please retry.";
@@ -459,6 +466,14 @@ var _InvalidFieldTypeError = class _InvalidFieldTypeError extends BaseValidation
 chunkMWMSFIWN_cjs.__name(_InvalidFieldTypeError, "InvalidFieldTypeError");
 var InvalidFieldTypeError = _InvalidFieldTypeError;
 
+// ../../platform/api-contract/dist/index.js
+var HEADER_RETRY_AFTER = { name: "Retry-After" };
+var HEADER_ENTITY_TAG = { name: "X-Entity-Tag" };
+var HEADER_IF_MATCH = {
+  name: "If-Match"};
+var HEADER_IDEMPOTENCY_KEY = {
+  name: "Idempotency-Key"};
+
 // ../../platform/api-contract/dist/client/index.js
 var _a;
 var ContractBodyError = (_a = class extends Error {
@@ -502,19 +517,47 @@ function readError(body) {
 }
 chunkMWMSFIWN_cjs.__name(readError, "readError");
 
+// src/http/retry-after.ts
+function headerValue(headers, name) {
+  if (headers === void 0) return void 0;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === wanted) return value;
+  }
+  return void 0;
+}
+chunkMWMSFIWN_cjs.__name(headerValue, "headerValue");
+function parseRetryAfterMs(value, nowMs) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "") return void 0;
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  if (!/[A-Za-z]/.test(trimmed)) return void 0;
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return void 0;
+  return Math.max(0, at - nowMs);
+}
+chunkMWMSFIWN_cjs.__name(parseRetryAfterMs, "parseRetryAfterMs");
+
 // src/errors/error-mapper.ts
 var _ErrorMapper = class _ErrorMapper {
   /** Map a non-2xx response to an SDK error. */
   static mapHttpError(response, requestContext) {
-    const { status, statusText, body } = response;
+    const { status, statusText, body, headers } = response;
     const refusal = readError(body);
     const context = { ...requestContext, response: body };
     if (refusal === void 0) {
       return new NetworkError(`HTTP ${status}: ${statusText}`.trim(), status, void 0, context);
     }
-    return this.fromContractCode(refusal, status, context);
+    const retryAfterMs = parseRetryAfterMs(
+      headerValue(headers, HEADER_RETRY_AFTER.name),
+      Date.now()
+    );
+    return this.fromContractCode(refusal, status, context, retryAfterMs);
   }
-  static fromContractCode(refusal, status, context) {
+  static fromContractCode(refusal, status, context, retryAfterMs) {
     const message = refusal.messages[0] ?? `RelyIO refused with ${refusal.code}`;
     switch (refusal.code) {
       case "MISSING_API_KEY": {
@@ -545,7 +588,8 @@ var _ErrorMapper = class _ErrorMapper {
           message,
           detailNumber(refusal, "limit"),
           detailString(refusal, "resetAt"),
-          context
+          context,
+          retryAfterMs
         );
       }
       case "REQUEST_INVALID": {
@@ -588,7 +632,12 @@ var _ErrorMapper = class _ErrorMapper {
         );
       }
       case "SERVICE_INDETERMINATE": {
-        return new ServiceIndeterminateError(message, detailString(refusal, "missing"), context);
+        return new ServiceIndeterminateError(
+          message,
+          detailString(refusal, "missing"),
+          context,
+          retryAfterMs
+        );
       }
       case "INTERNAL_ERROR": {
         return new ServerError(message, status, context);
@@ -630,12 +679,6 @@ var _ErrorMapper = class _ErrorMapper {
     }
     return error.name === "TypeError" && error.message.includes("fetch") || error.message.includes("timeout") || error.message.includes("Network Error") || error.message.includes("ECONNREFUSED");
   }
-  /**
-   * Extract retry delay from error
-   */
-  static getRetryDelay(_error) {
-    return 0;
-  }
 };
 chunkMWMSFIWN_cjs.__name(_ErrorMapper, "ErrorMapper");
 var ErrorMapper = _ErrorMapper;
@@ -693,6 +736,158 @@ function fillPath(template, params) {
   return filled;
 }
 chunkMWMSFIWN_cjs.__name(fillPath, "fillPath");
+var DECLARED_PATHS = {
+  "/health": true,
+  "/health/cache": true,
+  "/health/live": true,
+  "/health/ready": true,
+  "/internal/media/claim": true,
+  "/internal/media/file-complete": true,
+  "/internal/media/progress": true,
+  "/internal/media/resolve": true,
+  "/internal/usage/cycle": true,
+  "/internal/usage/ingest": true,
+  "/v1/{contentType}": true,
+  "/v1/{contentType}/{id}": true,
+  "/v1/{contentType}/{id}/children": true,
+  "/v1/{contentType}/{id}/file": true,
+  "/v1/{contentType}/{id}/file/confirm": true,
+  "/v1/{contentType}/{id}/file/multipart/abort": true,
+  "/v1/{contentType}/{id}/file/multipart/complete": true,
+  "/v1/{contentType}/{id}/file/multipart/create": true,
+  "/v1/{contentType}/{id}/file/multipart/list-parts": true,
+  "/v1/{contentType}/{id}/file/multipart/sign-part": true,
+  "/v1/{contentType}/{id}/file/presign": true,
+  "/v1/{contentType}/{id}/file/url": true,
+  "/v1/{contentType}/{id}/versions": true,
+  "/v1/{contentType}/{id}/versions/{versionNumber}": true,
+  "/v1/{contentType}/{id}/versions/{versionNumber}/restore": true,
+  "/v1/batch": true,
+  "/v1/changes": true,
+  "/v1/meta/content-types": true,
+  "/v1/meta/info": true,
+  "/v1/meta/locales": true,
+  "/v1/meta/schema": true,
+  "/v1/meta/schema/{contentType}": true,
+  "/v1/meta/schema/{contentType}/fields": true,
+  "/v1/query": true,
+  "/v1/search": true,
+  "/v1/search/autocomplete": true,
+  "/v1/search/similar": true,
+  "/v1/settings": true,
+  "/v1/settings/{groupId}": true,
+  "/v1/settings/{groupId}/defaults": true,
+  "/v1/settings/{groupId}/reset": true,
+  "/v1/settings/{groupId}/versions": true,
+  "/v1/settings/{groupId}/versions/{versionNumber}": true,
+  "/v1/singletons/{key}": true,
+  "/v1/singletons/{key}/exists": true,
+  "/v1/singletons/{key}/versions": true,
+  "/v1/singletons/{key}/versions/{versionNumber}": true
+};
+function compile(path) {
+  const segments = path.split("/").slice(1).map((part) => {
+    const param = /^\{(\w+)\}$/.exec(part);
+    return param?.[1] === void 0 ? { kind: "static", value: part } : { kind: "param", name: param[1] };
+  });
+  return { path, segments };
+}
+chunkMWMSFIWN_cjs.__name(compile, "compile");
+function byRouterPrecedence(a, b) {
+  const shared = Math.min(a.segments.length, b.segments.length);
+  for (let index = 0; index < shared; index += 1) {
+    const left = a.segments[index]?.kind;
+    const right = b.segments[index]?.kind;
+    if (left !== right) return left === "static" ? -1 : 1;
+  }
+  return 0;
+}
+chunkMWMSFIWN_cjs.__name(byRouterPrecedence, "byRouterPrecedence");
+var COMPILED_ROUTES = Object.keys(DECLARED_PATHS).map(compile).sort(byRouterPrecedence);
+function matchRoute(url, options = {}) {
+  const parsed = new URL(url, "http://relative.invalid");
+  let pathname = parsed.pathname;
+  if (options.baseUrl !== void 0) {
+    const prefix = new URL(options.baseUrl, "http://relative.invalid").pathname.replace(/\/+$/, "");
+    if (prefix !== "") {
+      if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) return null;
+      pathname = pathname.slice(prefix.length);
+    }
+  }
+  const parts = pathname.split("/").slice(1);
+  for (const route of COMPILED_ROUTES) {
+    if (route.segments.length !== parts.length) continue;
+    const params = {};
+    const matched = route.segments.every((segment, index) => {
+      const part = parts[index];
+      if (part === void 0) return false;
+      if (segment.kind === "static") return segment.value === part;
+      if (part === "") return false;
+      params[segment.name] = decodeURIComponent(part);
+      return true;
+    });
+    if (matched) return { path: route.path, params, query: readQuery(parsed.searchParams) };
+  }
+  return null;
+}
+chunkMWMSFIWN_cjs.__name(matchRoute, "matchRoute");
+function readQuery(searchParams) {
+  const query = {};
+  for (const key of new Set(searchParams.keys())) {
+    const values = searchParams.getAll(key);
+    query[key] = values.length === 1 && values[0] !== void 0 ? values[0] : values;
+  }
+  return query;
+}
+chunkMWMSFIWN_cjs.__name(readQuery, "readQuery");
+
+// src/http/retry-policy.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "OPTIONS",
+  "PUT",
+  "DELETE",
+  "TRACE"
+]);
+function isReplaySafe(request) {
+  if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
+  return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+}
+chunkMWMSFIWN_cjs.__name(isReplaySafe, "isReplaySafe");
+function serviceInstructedDelayMs(error, nowMs) {
+  if (error instanceof ServiceIndeterminateError) {
+    return error.retryAfterMs;
+  }
+  if (!(error instanceof RateLimitError)) return void 0;
+  if (error.retryAfterMs !== void 0) return error.retryAfterMs;
+  if (error.resetAt === void 0) return void 0;
+  const resetAtMs = Date.parse(error.resetAt);
+  if (Number.isNaN(resetAtMs)) return void 0;
+  const wait = resetAtMs - nowMs;
+  return wait > 0 ? wait : void 0;
+}
+chunkMWMSFIWN_cjs.__name(serviceInstructedDelayMs, "serviceInstructedDelayMs");
+var _DefaultRetryPolicy = class _DefaultRetryPolicy {
+  constructor(config) {
+    chunkMWMSFIWN_cjs.__publicField(this, "config");
+    this.config = config;
+  }
+  shouldRetry(attempt, error, request) {
+    if (attempt >= this.config.maxAttempts) return false;
+    if (!ErrorMapper.isRetryable(error)) return false;
+    return isReplaySafe(request);
+  }
+  delayFor(attempt, error) {
+    const instructed = serviceInstructedDelayMs(error, Date.now());
+    if (instructed !== void 0) return instructed;
+    const exponential = this.config.baseDelay * Math.pow(this.config.backoffFactor, attempt - 1);
+    const delay = Math.min(exponential, this.config.maxDelay);
+    return this.config.jitter ? delay * (0.5 + Math.random() * 0.5) : delay;
+  }
+};
+chunkMWMSFIWN_cjs.__name(_DefaultRetryPolicy, "DefaultRetryPolicy");
+var DefaultRetryPolicy = _DefaultRetryPolicy;
 
 // src/http/http-client.ts
 var _HttpClient = class _HttpClient {
@@ -700,7 +895,7 @@ var _HttpClient = class _HttpClient {
     chunkMWMSFIWN_cjs.__publicField(this, "baseUrl");
     chunkMWMSFIWN_cjs.__publicField(this, "defaultHeaders");
     chunkMWMSFIWN_cjs.__publicField(this, "timeout");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryConfig");
+    chunkMWMSFIWN_cjs.__publicField(this, "retryPolicy");
     chunkMWMSFIWN_cjs.__publicField(this, "debug");
     chunkMWMSFIWN_cjs.__publicField(this, "logger");
     chunkMWMSFIWN_cjs.__publicField(this, "config");
@@ -721,16 +916,13 @@ var _HttpClient = class _HttpClient {
       const globalWithVersion = globalThis;
       this.defaultHeaders["User-Agent"] = `RelyIO-SDK/${globalWithVersion.__VERSION__ ?? "0.0.0"}`;
     }
-    this.retryConfig = {
+    this.retryPolicy = new DefaultRetryPolicy({
       maxAttempts: config.retryAttempts,
       baseDelay: 1e3,
       maxDelay: 1e4,
       backoffFactor: 2,
-      jitter: true,
-      retryCondition: /* @__PURE__ */ chunkMWMSFIWN_cjs.__name((error, attempt) => {
-        return ErrorMapper.isRetryable(error) && attempt < config.retryAttempts;
-      }, "retryCondition")
-    };
+      jitter: true
+    });
     this.log("debug", "HttpClient initialized", {
       baseUrl: this.baseUrl,
       timeout: this.timeout,
@@ -763,7 +955,16 @@ var _HttpClient = class _HttpClient {
     return readPayload(response.body);
   }
   /**
-   * 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`.
    */
   async request(config) {
     const mergedConfig = this.mergeRequestConfig(config);
@@ -772,14 +973,11 @@ var _HttpClient = class _HttpClient {
       url: mergedConfig.url
       // Show the final URL with query params
     });
-    let lastError;
-    let attempt = 0;
-    while (attempt < this.retryConfig.maxAttempts) {
-      attempt++;
+    if (config.method === "DELETE" && mergedConfig.headers) {
+      delete mergedConfig.headers["Content-Type"];
+    }
+    for (let attempt = 1; ; attempt++) {
       try {
-        if (config.method === "DELETE" && mergedConfig.headers) {
-          delete mergedConfig.headers["Content-Type"];
-        }
         const response = await this.makeRequest(mergedConfig.url, mergedConfig);
         this.log("debug", "Request successful", {
           status: response.status,
@@ -788,31 +986,31 @@ var _HttpClient = class _HttpClient {
         });
         return response;
       } catch (error) {
-        lastError = error;
+        const failure = error;
+        if (config.signal?.aborted === true) throw failure;
         this.log("warn", "Request failed", {
           error: error instanceof Error ? error.message : "Unknown error",
           attempt,
           url: mergedConfig.url
         });
-        if (attempt < this.retryConfig.maxAttempts && this.retryConfig.retryCondition?.(lastError, attempt) === true) {
-          const delay = this.calculateRetryDelay(attempt);
+        if (this.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
+          const delay = this.retryPolicy.delayFor(attempt, failure);
           this.log("debug", "Retrying request", { attempt, delay });
-          await this.sleep(delay);
+          await this.sleep(delay, config.signal);
           continue;
         }
-        break;
+        const sdkError = ErrorMapper.mapGenericError(failure, {
+          url: mergedConfig.url,
+          method: mergedConfig.method,
+          attempt
+        });
+        this.log("error", "Request failed after all retries", {
+          error: sdkError.toJSON(),
+          url: mergedConfig.url
+        });
+        throw sdkError;
       }
     }
-    const sdkError = ErrorMapper.mapGenericError(lastError, {
-      url: mergedConfig.url,
-      method: mergedConfig.method,
-      attempt
-    });
-    this.log("error", "Request failed after all retries", {
-      error: sdkError.toJSON(),
-      url: mergedConfig.url
-    });
-    throw sdkError;
   }
   /**
    * Make a GET request
@@ -897,20 +1095,41 @@ var _HttpClient = class _HttpClient {
   getBaseUrl() {
     return this.baseUrl;
   }
+  /**
+   * 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.
+   */
   async makeRequest(url, config) {
+    const caller = config.signal;
+    if (caller?.aborted === true) {
+      throw new DOMException("The request was aborted before it was sent", "AbortError");
+    }
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), config.timeout ?? this.timeout);
+    let timedOut = false;
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, config.timeout ?? this.timeout);
+    const onCallerAbort = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => controller.abort(), "onCallerAbort");
+    caller?.addEventListener("abort", onCallerAbort, { once: true });
     try {
       const filteredHeaders = this.filterHeadersForBrowser(config.headers ?? {});
       const requestInit = {
         method: config.method,
         headers: filteredHeaders,
         body: this.prepareRequestBody(config),
-        signal: config.signal ?? controller.signal,
+        signal: controller.signal,
         // Include credentials for CORS requests if in browser and configured
         ...typeof window !== "undefined" && this.config.browser.includeCredentials != null && { credentials: "include" }
       };
-      const response = await fetch(url, requestInit);
+      const send = this.config.fetch ?? globalThis.fetch;
+      const response = await send(url, requestInit);
       clearTimeout(timeoutId);
       const responseBody = await this.parseResponse(response);
       if (!response.ok) {
@@ -941,6 +1160,7 @@ var _HttpClient = class _HttpClient {
         throw error;
       }
       if (error instanceof DOMException && error.name === "AbortError") {
+        if (!timedOut && isAborted(caller)) throw error;
         throw new TimeoutError(
           `Request timed out after ${config.timeout ?? this.timeout}ms`,
           config.timeout ?? this.timeout
@@ -972,6 +1192,8 @@ var _HttpClient = class _HttpClient {
         throw corsError;
       }
       throw error;
+    } finally {
+      caller?.removeEventListener("abort", onCallerAbort);
     }
   }
   /**
@@ -1060,16 +1282,21 @@ var _HttpClient = class _HttpClient {
     });
     return obj;
   }
-  calculateRetryDelay(attempt) {
-    const exponentialDelay = this.retryConfig.baseDelay * Math.pow(this.retryConfig.backoffFactor, attempt - 1);
-    const delay = Math.min(exponentialDelay, this.retryConfig.maxDelay);
-    if (this.retryConfig.jitter) {
-      return delay * (0.5 + Math.random() * 0.5);
-    }
-    return delay;
-  }
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+  /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
+  sleep(ms, signal) {
+    return new Promise((resolve) => {
+      if (isAborted(signal)) {
+        resolve();
+        return;
+      }
+      const done = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+      }, "done");
+      const timer = setTimeout(done, ms);
+      signal?.addEventListener("abort", done, { once: true });
+    });
   }
   log(level, message, data) {
     if (!this.debug) return;
@@ -1082,6 +1309,10 @@ var _HttpClient = class _HttpClient {
 };
 chunkMWMSFIWN_cjs.__name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+chunkMWMSFIWN_cjs.__name(isAborted, "isAborted");
 
 // src/content/query-builder.ts
 var _ContentQueryBuilder = class _ContentQueryBuilder {
@@ -1563,32 +1794,27 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
 chunkMWMSFIWN_cjs.__name(_ContentByIdBuilder, "ContentByIdBuilder");
 var ContentByIdBuilder = _ContentByIdBuilder;
 
-// ../../platform/api-contract/dist/index.js
-var HEADER_ENTITY_TAG = { name: "X-Entity-Tag" };
-var HEADER_IF_MATCH = {
-  name: "If-Match"};
-var HEADER_IDEMPOTENCY_KEY = {
-  name: "Idempotency-Key"};
-
 // src/http/write-options.ts
+function mintIdempotencyKey() {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID !== "function") return void 0;
+  return webCrypto.randomUUID();
+}
+chunkMWMSFIWN_cjs.__name(mintIdempotencyKey, "mintIdempotencyKey");
 function writeHeaders(options) {
-  if (options === void 0) return void 0;
   const headers = {};
-  if ("ifMatch" in options && options.ifMatch !== void 0) {
+  if (options !== void 0 && "ifMatch" in options && options.ifMatch !== void 0) {
     headers[HEADER_IF_MATCH.name] = options.ifMatch;
   }
-  if (options.idempotencyKey !== void 0) {
-    headers[HEADER_IDEMPOTENCY_KEY.name] = options.idempotencyKey;
+  const idempotencyKey = options?.idempotencyKey ?? mintIdempotencyKey();
+  if (idempotencyKey !== void 0) {
+    headers[HEADER_IDEMPOTENCY_KEY.name] = idempotencyKey;
   }
   return Object.keys(headers).length > 0 ? headers : void 0;
 }
 chunkMWMSFIWN_cjs.__name(writeHeaders, "writeHeaders");
 function entityTagOf(response) {
-  const wanted = HEADER_ENTITY_TAG.name.toLowerCase();
-  for (const [name, value] of Object.entries(response.headers)) {
-    if (name.toLowerCase() === wanted) return value;
-  }
-  return void 0;
+  return headerValue(response.headers, HEADER_ENTITY_TAG.name);
 }
 chunkMWMSFIWN_cjs.__name(entityTagOf, "entityTagOf");
 
@@ -3854,6 +4080,103 @@ var _AdhocQueryClient = class _AdhocQueryClient {
 chunkMWMSFIWN_cjs.__name(_AdhocQueryClient, "AdhocQueryClient");
 var AdhocQueryClient = _AdhocQueryClient;
 
+// src/changes/changes.ts
+var CHANGES_POLL_TIMEOUT_MS = 25e3 + 5e3;
+var _ChangesExpiredError = class _ChangesExpiredError extends ResourceExpiredError {
+  /** The base class's signature, so `withContext` can rebuild one. */
+  constructor(message, statusCode = 410, cause, context) {
+    super(message, statusCode, cause, context);
+    chunkMWMSFIWN_cjs.__publicField(this, "reason");
+    this.name = "ChangesExpiredError";
+    this.reason = expiredReasonOf(message);
+  }
+  static of(expired) {
+    return new _ChangesExpiredError(expired.message, expired.statusCode, expired, expired.context);
+  }
+};
+chunkMWMSFIWN_cjs.__name(_ChangesExpiredError, "ChangesExpiredError");
+var ChangesExpiredError = _ChangesExpiredError;
+function expiredReasonOf(message) {
+  if (message.includes("(retention)")) return "retention";
+  if (message.includes("(dataset-replaced)")) return "dataset-replaced";
+  return "unknown";
+}
+chunkMWMSFIWN_cjs.__name(expiredReasonOf, "expiredReasonOf");
+async function* pollChanges(http, options = {}) {
+  const { signal } = options;
+  let since = options.since;
+  let resynced;
+  for (; ; ) {
+    if (aborted(signal)) return;
+    let response;
+    try {
+      response = await pollOnce(http, since, options);
+    } catch (error) {
+      if (aborted(signal)) return;
+      if (!(error instanceof ResourceExpiredError) || since === void 0) throw error;
+      const expired = ChangesExpiredError.of(error);
+      const onExpired = options.onExpired ?? "throw";
+      if (onExpired === "throw") throw expired;
+      since = void 0;
+      resynced = typeof onExpired === "function" ? expired : void 0;
+      continue;
+    }
+    const { data, page } = response.body;
+    if (page.nextCursor === null) {
+      throw new Error("GET /v1/changes answered without page.nextCursor");
+    }
+    since = page.nextCursor;
+    if (resynced !== void 0 && typeof options.onExpired === "function") {
+      const expired = resynced;
+      resynced = void 0;
+      await options.onExpired(expired);
+      if (aborted(signal)) return;
+    }
+    for (const change of data) {
+      yield change;
+      if (aborted(signal)) return;
+    }
+    if (data.length === 0) {
+      const wait = parseRetryAfterMs(headerValue(response.headers, "Retry-After"), Date.now());
+      if (wait !== void 0 && wait > 0) await sleep(wait, signal);
+    }
+  }
+}
+chunkMWMSFIWN_cjs.__name(pollChanges, "pollChanges");
+async function pollOnce(http, since, options) {
+  const query = {};
+  if (since !== void 0) query.since = since;
+  if (options.types !== void 0) query.types = options.types.join(",");
+  if (options.ids !== void 0) query.ids = options.ids.join(",");
+  if (options.limit !== void 0) query.limit = options.limit;
+  return http.send("/v1/changes", "get", {
+    query,
+    timeout: CHANGES_POLL_TIMEOUT_MS,
+    ...options.signal === void 0 ? {} : { signal: options.signal }
+  });
+}
+chunkMWMSFIWN_cjs.__name(pollOnce, "pollOnce");
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (aborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, "done");
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+chunkMWMSFIWN_cjs.__name(sleep, "sleep");
+function aborted(signal) {
+  return signal?.aborted === true;
+}
+chunkMWMSFIWN_cjs.__name(aborted, "aborted");
+
 // src/config/dev-detection.ts
 function getProcess() {
   return typeof process !== "undefined" ? process : void 0;
@@ -3872,47 +4195,76 @@ function isProduction(proc) {
   return proc?.env?.NODE_ENV === "production";
 }
 chunkMWMSFIWN_cjs.__name(isProduction, "isProduction");
-function resolveFromEnv(proc) {
-  const dataset = proc?.env?.RELYIO_DEV_DATASET;
-  const apiKey = proc?.env?.RELYIO_DEV_API_KEY;
-  if (dataset != null && dataset !== "" && apiKey != null && apiKey !== "") {
-    return { dataset, apiKey, source: "env" };
+function resolveFromEnv(proc, now) {
+  const verdict = chunkLSRPMNPT_cjs.parseDevEnv(proc?.env, now);
+  switch (verdict.state) {
+    case "active":
+      return {
+        state: "active",
+        override: {
+          dataset: verdict.credentials.dataset,
+          apiKey: verdict.credentials.apiKey,
+          source: "env"
+        }
+      };
+    case "expired":
+      return { state: "expired", expiredAt: verdict.expiredAt };
+    case "unreadable":
+      return { state: "unreadable", reason: verdict.reason };
+    case "absent":
+      return { state: "absent" };
   }
-  return null;
 }
 chunkMWMSFIWN_cjs.__name(resolveFromEnv, "resolveFromEnv");
-function resolveFromFile(proc) {
-  if (proc == null || typeof proc.cwd !== "function") return null;
+function resolveFromFile(proc, now) {
+  if (proc == null || typeof proc.cwd !== "function") return { state: "absent" };
   const fs = getBuiltin(proc, "node:fs");
   const path = getBuiltin(proc, "node:path");
-  if (fs == null || path == null) return null;
+  if (fs == null || path == null) return { state: "absent" };
   let dir = proc.cwd();
   for (; ; ) {
-    const candidate = path.join(dir, ".relyio", "dev.json");
+    const candidate = path.join(dir, chunkLSRPMNPT_cjs.DEV_CONTEXT_DIR, chunkLSRPMNPT_cjs.DEV_CONTEXT_FILENAME);
+    let raw = null;
     try {
-      if (fs.existsSync(candidate)) {
-        const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
-        if (parsed.datasetId != null && parsed.datasetId !== "" && parsed.previewApiKey != null && parsed.previewApiKey !== "") {
-          if (parsed.expiresAt != null && Number.isFinite(new Date(parsed.expiresAt).getTime()) && new Date(parsed.expiresAt).getTime() < Date.now()) {
-            return null;
-          }
-          return { dataset: parsed.datasetId, apiKey: parsed.previewApiKey, source: "file" };
-        }
-      }
+      if (fs.existsSync(candidate)) raw = fs.readFileSync(candidate, "utf8");
     } catch {
+      return { state: "absent" };
+    }
+    if (raw !== null) {
+      const verdict = chunkLSRPMNPT_cjs.parseDevContextFile(raw, now);
+      switch (verdict.state) {
+        case "active":
+          return {
+            state: "active",
+            override: {
+              dataset: verdict.context.datasetId,
+              apiKey: verdict.context.previewApiKey,
+              source: "file"
+            }
+          };
+        case "expired":
+          return { state: "expired", expiredAt: verdict.expiredAt };
+        case "unreadable":
+          return { state: "unreadable", reason: verdict.reason };
+        case "absent":
+          return { state: "absent" };
+      }
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return null;
+  return { state: "absent" };
 }
 chunkMWMSFIWN_cjs.__name(resolveFromFile, "resolveFromFile");
 function resolveDevOverride(dev) {
-  if (dev === false) return null;
+  if (dev === false) return { state: "disabled" };
   const proc = getProcess();
-  if (dev !== true && isProduction(proc)) return null;
-  return resolveFromEnv(proc) ?? resolveFromFile(proc);
+  if (dev !== true && isProduction(proc)) return { state: "disabled" };
+  const now = Date.now();
+  const fromEnv = resolveFromEnv(proc, now);
+  if (fromEnv.state !== "absent") return fromEnv;
+  return resolveFromFile(proc, now);
 }
 chunkMWMSFIWN_cjs.__name(resolveDevOverride, "resolveDevOverride");
 
@@ -3995,16 +4347,26 @@ function mergeConfig(userConfig) {
       ...userConfig.debug
     }
   };
-  const devOverride = resolveDevOverride(userConfig.dev);
-  if (devOverride != null) {
-    merged.apiKey = devOverride.apiKey;
-    merged.dataset = devOverride.dataset;
+  const dev = resolveDevOverride(userConfig.dev);
+  if (dev.state === "active") {
+    merged.apiKey = dev.override.apiKey;
+    merged.dataset = dev.override.dataset;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
-        `[RelyIO] Sandbox dev mode active (${devOverride.source}) \u2014 targeting dataset "${devOverride.dataset}" with a scoped preview key.`
+        `[RelyIO] Sandbox dev mode active (${dev.override.source}) \u2014 targeting dataset "${dev.override.dataset}" with a scoped preview key.`
       );
     }
+  } else if (dev.state === "expired" && !devOverrideNotified) {
+    devOverrideNotified = true;
+    console.warn(
+      `[RelyIO] Your sandbox's .relyio/dev.json expired at ${dev.expiredAt} \u2014 ignoring it and using the configured dataset "${merged.dataset}". Run \`relyio dev\` to refresh it.`
+    );
+  } else if (dev.state === "unreadable" && !devOverrideNotified) {
+    devOverrideNotified = true;
+    console.warn(
+      `[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;
 }
@@ -4185,6 +4547,37 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     return this._batch.create();
   }
   // ============================================================================
+  // CHANGES FEED
+  // ============================================================================
+  /**
+   * 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 = {}) {
+    return pollChanges(this.httpClient, options);
+  }
+  // ============================================================================
   // QUERY OPERATIONS
   // ============================================================================
   /**
@@ -4383,6 +4776,7 @@ exports.AutocompleteBuilder = AutocompleteBuilder;
 exports.BaseValidationError = BaseValidationError;
 exports.BatchBuilder = BatchBuilder;
 exports.BatchClient = BatchClient;
+exports.ChangesExpiredError = ChangesExpiredError;
 exports.ConnectionError = ConnectionError;
 exports.ContentByIdBuilder = ContentByIdBuilder;
 exports.ContentClient = ContentClient;
@@ -4424,6 +4818,7 @@ exports.createClient = createClient;
 exports.entityTagOf = entityTagOf;
 exports.isAssetEntry = isAssetEntry;
 exports.isResourceNotFound = isResourceNotFound;
+exports.matchRoute = matchRoute;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-7W4MJXQ4.cjs.map
-//# sourceMappingURL=chunk-7W4MJXQ4.cjs.map
+//# sourceMappingURL=chunk-XS32U2UP.cjs.map
+//# sourceMappingURL=chunk-XS32U2UP.cjs.map