@tinycloud/sdk-services 3.1.0-beta.1 → 3.1.0-beta.10

package/dist/{BaseService-BhpVpA9b.d.cts → BaseService-B_UKhVht.d.ts}

@@ -1,4 +1,55 @@
-import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-qwMmB7qB.cjs';
+import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-CVwwxqXF.js';
+
+/**
+ * Base Service Types
+ *
+ * Types specific to the base service infrastructure.
+ */
+
+/**
+ * Service constructor type for registration.
+ * Used by the SDK to instantiate services.
+ */
+interface ServiceConstructor<TConfig = Record<string, unknown>, TService extends IService = IService> {
+    /** Service identifier used for registration */
+    readonly serviceName: string;
+    /** Create a new instance of the service */
+    new (config?: TConfig): TService;
+}
+/**
+ * Service registration entry.
+ */
+interface ServiceRegistration {
+    /** The service class constructor */
+    constructor: ServiceConstructor;
+    /** Configuration for this service instance */
+    config?: Record<string, unknown>;
+}
+/**
+ * Options for base service operations.
+ */
+interface BaseServiceOptions {
+    /** Override the default timeout for this operation */
+    timeout?: number;
+    /** Custom abort signal for this operation */
+    signal?: AbortSignal;
+}
+/**
+ * A per-request abort signal and the cleanup that releases it.
+ * Created by `BaseService.createRequestSignal()`.
+ */
+interface RequestSignal {
+    /**
+     * Aborts on service sign-out, context abort, the caller's signal, or when
+     * the request timeout elapses (reason: a `TimeoutError`).
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Clear the timeout and detach from the parent signals. Call once the
+     * response has been consumed. Idempotent.
+     */
+    dispose(): void;
+}
 
 /**
  * BaseService - Abstract base class for all TinyCloud services.
@@ -144,6 +195,27 @@ declare abstract class BaseService implements IService {
      * @returns A combined abort signal
      */
     protected combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal;
+    /**
+     * Create the abort signal for one request, bounded by the request timeout.
+     *
+     * The signal aborts when the service signs out, the context aborts, the
+     * caller's `signal` aborts, or the timeout elapses, whichever comes first.
+     * A timeout aborts with a {@link RequestTimeoutError} (`TimeoutError`), which
+     * `wrapError` maps to `ErrorCodes.TIMEOUT`; the other sources keep their own
+     * reason (normally `AbortError`, mapped to `ErrorCodes.ABORTED`).
+     *
+     * The timeout is `timeoutMs` when given, otherwise `config.timeout`. Only a
+     * positive, finite value (at most 2^31-1 ms) applies; `undefined`, `0`, and
+     * `Infinity` mean no timeout, so a per-call `0` opts out of a configured one.
+     *
+     * Callers must call `dispose()` once the response body has been consumed,
+     * which clears the timer and removes the listeners this adds to the
+     * long-lived service and context signals.
+     *
+     * @param signal - The caller's abort signal for this request
+     * @param timeoutMs - Per-request timeout override in milliseconds
+     */
+    protected createRequestSignal(signal?: AbortSignal, timeoutMs?: number): RequestSignal;
     /**
      * Wrap an operation with error handling and telemetry.
      *
@@ -155,4 +227,4 @@ declare abstract class BaseService implements IService {
     protected withTelemetry<T>(action: string, key: string | undefined, operation: () => Promise<Result<T>>): Promise<Result<T>>;
 }
 
-export { BaseService as B };
+export { BaseService as B, type RequestSignal as R, type ServiceConstructor as S, type BaseServiceOptions as a, type ServiceRegistration as b };

package/dist/{BaseService-CuV-ZVPs.d.ts → BaseService-DWbPbov7.d.cts}

@@ -1,4 +1,55 @@
-import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-qwMmB7qB.js';
+import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-CVwwxqXF.cjs';
+
+/**
+ * Base Service Types
+ *
+ * Types specific to the base service infrastructure.
+ */
+
+/**
+ * Service constructor type for registration.
+ * Used by the SDK to instantiate services.
+ */
+interface ServiceConstructor<TConfig = Record<string, unknown>, TService extends IService = IService> {
+    /** Service identifier used for registration */
+    readonly serviceName: string;
+    /** Create a new instance of the service */
+    new (config?: TConfig): TService;
+}
+/**
+ * Service registration entry.
+ */
+interface ServiceRegistration {
+    /** The service class constructor */
+    constructor: ServiceConstructor;
+    /** Configuration for this service instance */
+    config?: Record<string, unknown>;
+}
+/**
+ * Options for base service operations.
+ */
+interface BaseServiceOptions {
+    /** Override the default timeout for this operation */
+    timeout?: number;
+    /** Custom abort signal for this operation */
+    signal?: AbortSignal;
+}
+/**
+ * A per-request abort signal and the cleanup that releases it.
+ * Created by `BaseService.createRequestSignal()`.
+ */
+interface RequestSignal {
+    /**
+     * Aborts on service sign-out, context abort, the caller's signal, or when
+     * the request timeout elapses (reason: a `TimeoutError`).
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Clear the timeout and detach from the parent signals. Call once the
+     * response has been consumed. Idempotent.
+     */
+    dispose(): void;
+}
 
 /**
  * BaseService - Abstract base class for all TinyCloud services.
@@ -144,6 +195,27 @@ declare abstract class BaseService implements IService {
      * @returns A combined abort signal
      */
     protected combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal;
+    /**
+     * Create the abort signal for one request, bounded by the request timeout.
+     *
+     * The signal aborts when the service signs out, the context aborts, the
+     * caller's `signal` aborts, or the timeout elapses, whichever comes first.
+     * A timeout aborts with a {@link RequestTimeoutError} (`TimeoutError`), which
+     * `wrapError` maps to `ErrorCodes.TIMEOUT`; the other sources keep their own
+     * reason (normally `AbortError`, mapped to `ErrorCodes.ABORTED`).
+     *
+     * The timeout is `timeoutMs` when given, otherwise `config.timeout`. Only a
+     * positive, finite value (at most 2^31-1 ms) applies; `undefined`, `0`, and
+     * `Infinity` mean no timeout, so a per-call `0` opts out of a configured one.
+     *
+     * Callers must call `dispose()` once the response body has been consumed,
+     * which clears the timer and removes the listeners this adds to the
+     * long-lived service and context signals.
+     *
+     * @param signal - The caller's abort signal for this request
+     * @param timeoutMs - Per-request timeout override in milliseconds
+     */
+    protected createRequestSignal(signal?: AbortSignal, timeoutMs?: number): RequestSignal;
     /**
      * Wrap an operation with error handling and telemetry.
      *
@@ -155,4 +227,4 @@ declare abstract class BaseService implements IService {
     protected withTelemetry<T>(action: string, key: string | undefined, operation: () => Promise<Result<T>>): Promise<Result<T>>;
 }
 
-export { BaseService as B };
+export { BaseService as B, type RequestSignal as R, type ServiceConstructor as S, type BaseServiceOptions as a, type ServiceRegistration as b };

package/dist/encryption/index.cjs

@@ -71,6 +71,10 @@ var ErrorCodes = {
   AUTH_EXPIRED: "AUTH_EXPIRED",
   AUTH_REQUIRED: "AUTH_REQUIRED",
   AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
   NETWORK_ERROR: "NETWORK_ERROR",
   TIMEOUT: "TIMEOUT",
   ABORTED: "ABORTED",
@@ -82,6 +86,10 @@ var ErrorCodes = {
   KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
   KV_CONFLICT: "KV_CONFLICT",
   KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
   // SQL-specific errors
   SQL_ERROR: "SQL_ERROR",
   SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -125,11 +133,131 @@ function err(error) {
 }
 
 // src/errors.ts
-function timeoutError(service) {
+var import_bootstrap = require("@tinycloud/bootstrap");
+
+// src/encryption/networkId.ts
+var URN_PREFIX = "urn:tinycloud:encryption:";
+var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
+var NetworkIdError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NetworkIdError";
+  }
+};
+function parseNetworkId(networkId) {
+  if (typeof networkId !== "string" || networkId.length === 0) {
+    throw new NetworkIdError("networkId must be a non-empty string");
+  }
+  if (!networkId.startsWith(URN_PREFIX)) {
+    throw new NetworkIdError(
+      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const body = networkId.slice(URN_PREFIX.length);
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon <= 0 || lastColon === body.length - 1) {
+    throw new NetworkIdError(
+      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const ownerDid = body.slice(0, lastColon);
+  const name = body.slice(lastColon + 1);
+  if (!ownerDid.startsWith("did:")) {
+    throw new NetworkIdError(
+      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  const didParts = ownerDid.split(":");
+  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
+    throw new NetworkIdError(
+      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return { networkId, ownerDid, name };
+}
+function buildNetworkId(ownerDid, name) {
+  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
+    throw new NetworkIdError("ownerDid must be a DID");
+  }
+  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
+  parseNetworkId(networkId);
+  return networkId;
+}
+function isNetworkId(networkId) {
+  if (typeof networkId !== "string") {
+    return false;
+  }
+  try {
+    parseNetworkId(networkId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parsePkhOwnerDid(ownerDid) {
+  const match = ownerDid.match(PKH_EIP155_DID_RE);
+  if (!match) return null;
+  return {
+    chainId: match[1],
+    address: match[2].toLowerCase()
+  };
+}
+function ownerDidMatches(a, b) {
+  const aPkh = parsePkhOwnerDid(a);
+  const bPkh = parsePkhOwnerDid(b);
+  if (aPkh && bPkh) {
+    return aPkh.chainId === bPkh.chainId && aPkh.address === bPkh.address;
+  }
+  return a === b;
+}
+function networkDiscoveryKey(name) {
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return `.well-known/encryption/network/${name}`;
+}
+var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
+var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
+
+// src/errors.ts
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function isRequestTimeoutError(error) {
+  return error instanceof RequestTimeoutError || error instanceof Error && error.name === "TimeoutError" && typeof error.timeoutMs === "number";
+}
+function timeoutError(service, timeoutMs, cause) {
+  if (timeoutMs === void 0) {
+    return {
+      code: ErrorCodes.TIMEOUT,
+      message: "Request timed out.",
+      service,
+      ...cause === void 0 ? {} : { cause }
+    };
+  }
   return {
     code: ErrorCodes.TIMEOUT,
-    message: "Request timed out.",
-    service
+    message: `Request timed out after ${timeoutMs}ms.`,
+    service,
+    ...cause === void 0 ? {} : { cause },
+    meta: { timeoutMs }
   };
 }
 function abortedError(service) {
@@ -139,8 +267,17 @@ function abortedError(service) {
     service
   };
 }
+var grantableActions = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
+);
+var capabilityServices = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
+);
 function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
   if (error instanceof Error) {
+    if (isRequestTimeoutError(error)) {
+      return timeoutError(service, error.timeoutMs, error);
+    }
     if (error.name === "AbortError") {
       return abortedError(service);
     }
@@ -162,6 +299,7 @@ function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
 }
 
 // src/base/BaseService.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
 var BaseService = class {
   constructor() {
     /**
@@ -342,6 +480,64 @@ var BaseService = class {
     }
     return controller.signal;
   }
+  /**
+   * Create the abort signal for one request, bounded by the request timeout.
+   *
+   * The signal aborts when the service signs out, the context aborts, the
+   * caller's `signal` aborts, or the timeout elapses, whichever comes first.
+   * A timeout aborts with a {@link RequestTimeoutError} (`TimeoutError`), which
+   * `wrapError` maps to `ErrorCodes.TIMEOUT`; the other sources keep their own
+   * reason (normally `AbortError`, mapped to `ErrorCodes.ABORTED`).
+   *
+   * The timeout is `timeoutMs` when given, otherwise `config.timeout`. Only a
+   * positive, finite value (at most 2^31-1 ms) applies; `undefined`, `0`, and
+   * `Infinity` mean no timeout, so a per-call `0` opts out of a configured one.
+   *
+   * Callers must call `dispose()` once the response body has been consumed,
+   * which clears the timer and removes the listeners this adds to the
+   * long-lived service and context signals.
+   *
+   * @param signal - The caller's abort signal for this request
+   * @param timeoutMs - Per-request timeout override in milliseconds
+   */
+  createRequestSignal(signal, timeoutMs) {
+    const controller = new AbortController();
+    const detachers = [];
+    let timer;
+    const dispose = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      for (const detach of detachers.splice(0)) {
+        detach();
+      }
+    };
+    const abort = (reason) => {
+      dispose();
+      controller.abort(reason);
+    };
+    const requestSignal = { signal: controller.signal, dispose };
+    const parents = [
+      this.abortController.signal,
+      this.context?.abortSignal,
+      signal
+    ].filter((parent) => parent !== void 0);
+    for (const parent of parents) {
+      if (parent.aborted) {
+        abort(parent.reason);
+        return requestSignal;
+      }
+      const onAbort = () => abort(parent.reason);
+      parent.addEventListener("abort", onAbort, { once: true });
+      detachers.push(() => parent.removeEventListener("abort", onAbort));
+    }
+    const timeout = timeoutMs ?? this._config.timeout;
+    if (typeof timeout === "number" && timeout > 0 && timeout <= MAX_TIMER_DELAY_MS) {
+      timer = setTimeout(() => abort(new RequestTimeoutError(timeout)), timeout);
+    }
+    return requestSignal;
+  }
   /**
    * Wrap an operation with error handling and telemetry.
    *
@@ -481,103 +677,6 @@ function canonicalHashHex(sha256, value) {
   return hexEncode(sha256(utf8Encode(canonical)));
 }
 
-// src/encryption/networkId.ts
-var URN_PREFIX = "urn:tinycloud:encryption:";
-var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
-var NetworkIdError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NetworkIdError";
-  }
-};
-function parseNetworkId(networkId) {
-  if (typeof networkId !== "string" || networkId.length === 0) {
-    throw new NetworkIdError("networkId must be a non-empty string");
-  }
-  if (!networkId.startsWith(URN_PREFIX)) {
-    throw new NetworkIdError(
-      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const body = networkId.slice(URN_PREFIX.length);
-  const lastColon = body.lastIndexOf(":");
-  if (lastColon <= 0 || lastColon === body.length - 1) {
-    throw new NetworkIdError(
-      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const ownerDid = body.slice(0, lastColon);
-  const name = body.slice(lastColon + 1);
-  if (!ownerDid.startsWith("did:")) {
-    throw new NetworkIdError(
-      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  const didParts = ownerDid.split(":");
-  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
-    throw new NetworkIdError(
-      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  if (!NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  return { networkId, ownerDid, name };
-}
-function buildNetworkId(ownerDid, name) {
-  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
-    throw new NetworkIdError("ownerDid must be a DID");
-  }
-  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
-  parseNetworkId(networkId);
-  return networkId;
-}
-function isNetworkId(networkId) {
-  if (typeof networkId !== "string") {
-    return false;
-  }
-  try {
-    parseNetworkId(networkId);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function parsePkhOwnerDid(ownerDid) {
-  const match = ownerDid.match(PKH_EIP155_DID_RE);
-  if (!match) return null;
-  return {
-    chainId: match[1],
-    address: match[2].toLowerCase()
-  };
-}
-function ownerDidMatches(a, b) {
-  const aPkh = parsePkhOwnerDid(a);
-  const bPkh = parsePkhOwnerDid(b);
-  if (aPkh && bPkh) {
-    return aPkh.chainId === bPkh.chainId && aPkh.address === bPkh.address;
-  }
-  return a === b;
-}
-function networkDiscoveryKey(name) {
-  if (!NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  return `.well-known/encryption/network/${name}`;
-}
-var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
-var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
-
 // src/encryption/types.ts
 var DEFAULT_ENCRYPTION_ALG = "x25519-aes256gcm/v1";
 var ENVELOPE_VERSION = 1;