@tinycloud/sdk-services 3.1.0-beta.6 → 3.1.0-beta.7

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

@@ -1,5 +1,56 @@
 import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-qwMmB7qB.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/{BaseService-CuV-ZVPs.d.ts → BaseService-DU-lE-Qx.d.ts}

@@ -1,5 +1,56 @@
 import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-qwMmB7qB.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/encryption/index.cjs

@@ -225,11 +225,31 @@ var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
 var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
 
 // src/errors.ts
-function timeoutError(service) {
+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) {
@@ -247,6 +267,9 @@ var capabilityServices = new Set(
 );
 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);
     }
@@ -268,6 +291,7 @@ function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
 }
 
 // src/base/BaseService.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
 var BaseService = class {
   constructor() {
     /**
@@ -448,6 +472,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.
    *