@relyio/sdk 0.3.0 → 0.5.0

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

@@ -734,6 +734,111 @@ function fillPath(template, params) {
   return filled;
 }
 __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/project": 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 };
+}
+__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;
+}
+__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;
+}
+__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;
+}
+__name(readQuery, "readQuery");
 
 // src/http/retry-policy.ts
 var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
@@ -881,6 +986,7 @@ var _HttpClient = class _HttpClient {
         return response;
       } catch (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,
@@ -889,7 +995,7 @@ var _HttpClient = class _HttpClient {
         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;
         }
         const sdkError = ErrorMapper.mapGenericError(failure, {
@@ -988,20 +1094,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__ */ __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) {
@@ -1032,6 +1159,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
@@ -1063,6 +1191,8 @@ var _HttpClient = class _HttpClient {
         throw corsError;
       }
       throw error;
+    } finally {
+      caller?.removeEventListener("abort", onCallerAbort);
     }
   }
   /**
@@ -1151,8 +1281,21 @@ var _HttpClient = class _HttpClient {
     });
     return obj;
   }
-  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__ */ __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;
@@ -1165,6 +1308,10 @@ var _HttpClient = class _HttpClient {
 };
 __name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+__name(isAborted, "isAborted");
 
 // src/content/query-builder.ts
 var _ContentQueryBuilder = class _ContentQueryBuilder {
@@ -3932,7 +4079,108 @@ var _AdhocQueryClient = class _AdhocQueryClient {
 __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);
+    __publicField(this, "reason");
+    this.name = "ChangesExpiredError";
+    this.reason = expiredReasonOf(message);
+  }
+  static of(expired) {
+    return new _ChangesExpiredError(expired.message, expired.statusCode, expired, expired.context);
+  }
+};
+__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";
+}
+__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);
+    }
+  }
+}
+__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 }
+  });
+}
+__name(pollOnce, "pollOnce");
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (aborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = /* @__PURE__ */ __name(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, "done");
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+__name(sleep, "sleep");
+function aborted(signal) {
+  return signal?.aborted === true;
+}
+__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;
 }
@@ -3956,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 };
@@ -3991,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 };
@@ -4076,7 +4330,7 @@ function validateConfig(config) {
 }
 __name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
-function mergeConfig(userConfig) {
+function resolveConfig(userConfig) {
   validateConfig(userConfig);
   const merged = {
     ...DEFAULT_CONFIG,
@@ -4104,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) {
@@ -4123,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";
@@ -4133,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);
@@ -4154,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
    */
@@ -4302,6 +4576,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
   // ============================================================================
   /**
@@ -4346,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
    */
@@ -4392,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);
@@ -4489,6 +4813,6 @@ function createClient(config) {
 }
 __name(createClient, "createClient");
 
-export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthenticationError, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, 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, validateFile };
-//# sourceMappingURL=chunk-QIZOBT5F.js.map
-//# sourceMappingURL=chunk-QIZOBT5F.js.map
+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-5AZUUV5B.js.map
+//# sourceMappingURL=chunk-5AZUUV5B.js.map