@tinycloud/sdk-services 2.7.0-beta.3 → 2.7.0

package/dist/BaseService-BwBU5CQ4.d.cts

@@ -0,0 +1,158 @@
+import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-DAY1O1kW.cjs';
+
+/**
+ * BaseService - Abstract base class for all TinyCloud services.
+ *
+ * Provides common functionality:
+ * - Context management
+ * - Session lifecycle hooks
+ * - Abort signal handling
+ * - Telemetry emission
+ */
+
+/**
+ * Abstract base class for TinyCloud services.
+ *
+ * Services extend this class to get common functionality like
+ * context management, session lifecycle, and abort handling.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends BaseService implements IMyService {
+ *   static readonly serviceName = 'myservice';
+ *
+ *   constructor(config: MyServiceConfig = {}) {
+ *     super();
+ *     this._config = config;
+ *   }
+ *
+ *   async doSomething(): Promise<Result<Data>> {
+ *     if (!this.requireAuth()) {
+ *       return err(authRequiredError('myservice'));
+ *     }
+ *     // ... implementation
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService implements IService {
+    /**
+     * Service identifier used for registration.
+     * Must be overridden by subclasses.
+     */
+    static readonly serviceName: string;
+    /**
+     * Service context providing access to platform dependencies.
+     * Set during initialize().
+     */
+    protected context: IServiceContext;
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    protected abortController: AbortController;
+    /**
+     * Service-specific configuration.
+     */
+    protected _config: Record<string, unknown>;
+    /**
+     * Get the service configuration.
+     */
+    get config(): Record<string, unknown>;
+    /**
+     * Initialize the service with context.
+     * Called by the SDK after instantiation.
+     *
+     * @param context - The service context
+     */
+    initialize(context: IServiceContext): void;
+    /**
+     * Called when session changes (sign-in, sign-out, refresh).
+     * Override in subclasses to handle session changes.
+     *
+     * @param session - The new session, or null if signed out
+     */
+    onSessionChange(session: ServiceSession | null): void;
+    /**
+     * Called when SDK signs out.
+     * Aborts all pending operations.
+     */
+    onSignOut(): void;
+    /**
+     * Get the abort signal for this service.
+     * Combines the service-level abort with context-level abort.
+     */
+    protected get abortSignal(): AbortSignal;
+    /**
+     * Check if the service is authenticated.
+     */
+    protected get isAuthenticated(): boolean;
+    /**
+     * Get the current session.
+     * Throws if not authenticated.
+     */
+    protected get session(): ServiceSession;
+    /**
+     * Check authentication and return error result if not authenticated.
+     * Use this at the start of methods that require authentication.
+     *
+     * @returns true if authenticated, false otherwise
+     */
+    protected requireAuth(): boolean;
+    /**
+     * Emit a telemetry event.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    protected emit(event: string, data: unknown): void;
+    /**
+     * Emit a service request event.
+     *
+     * @param action - The action being performed
+     * @param key - Optional key/path being accessed
+     */
+    protected emitRequest(action: string, key?: string): void;
+    /**
+     * Emit a service response event.
+     *
+     * @param action - The action that was performed
+     * @param ok - Whether the request was successful
+     * @param startTime - Start time for duration calculation
+     * @param status - Optional HTTP status code
+     */
+    protected emitResponse(action: string, ok: boolean, startTime: number, status?: number): void;
+    /**
+     * Emit a service error event.
+     *
+     * @param error - The service error
+     */
+    protected emitError(error: ServiceError, action?: string): void;
+    /**
+     * Get the service name from the static property.
+     * Subclasses must define static serviceName.
+     */
+    protected getServiceName(): string;
+    /**
+     * Stable span name used by SDK telemetry sinks.
+     */
+    protected spanName(action: string): string;
+    /**
+     * Create a combined abort signal from multiple sources.
+     *
+     * @param signals - Additional abort signals to combine
+     * @returns A combined abort signal
+     */
+    protected combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal;
+    /**
+     * Wrap an operation with error handling and telemetry.
+     *
+     * @param action - The action name for telemetry
+     * @param key - Optional key for telemetry
+     * @param operation - The operation to execute
+     * @returns Result of the operation
+     */
+    protected withTelemetry<T>(action: string, key: string | undefined, operation: () => Promise<Result<T>>): Promise<Result<T>>;
+}
+
+export { BaseService as B };

package/dist/BaseService-CnPTKR5G.d.ts

@@ -0,0 +1,158 @@
+import { I as IService, a as IServiceContext, S as ServiceSession, b as ServiceError, R as Result } from './types-DAY1O1kW.js';
+
+/**
+ * BaseService - Abstract base class for all TinyCloud services.
+ *
+ * Provides common functionality:
+ * - Context management
+ * - Session lifecycle hooks
+ * - Abort signal handling
+ * - Telemetry emission
+ */
+
+/**
+ * Abstract base class for TinyCloud services.
+ *
+ * Services extend this class to get common functionality like
+ * context management, session lifecycle, and abort handling.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends BaseService implements IMyService {
+ *   static readonly serviceName = 'myservice';
+ *
+ *   constructor(config: MyServiceConfig = {}) {
+ *     super();
+ *     this._config = config;
+ *   }
+ *
+ *   async doSomething(): Promise<Result<Data>> {
+ *     if (!this.requireAuth()) {
+ *       return err(authRequiredError('myservice'));
+ *     }
+ *     // ... implementation
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService implements IService {
+    /**
+     * Service identifier used for registration.
+     * Must be overridden by subclasses.
+     */
+    static readonly serviceName: string;
+    /**
+     * Service context providing access to platform dependencies.
+     * Set during initialize().
+     */
+    protected context: IServiceContext;
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    protected abortController: AbortController;
+    /**
+     * Service-specific configuration.
+     */
+    protected _config: Record<string, unknown>;
+    /**
+     * Get the service configuration.
+     */
+    get config(): Record<string, unknown>;
+    /**
+     * Initialize the service with context.
+     * Called by the SDK after instantiation.
+     *
+     * @param context - The service context
+     */
+    initialize(context: IServiceContext): void;
+    /**
+     * Called when session changes (sign-in, sign-out, refresh).
+     * Override in subclasses to handle session changes.
+     *
+     * @param session - The new session, or null if signed out
+     */
+    onSessionChange(session: ServiceSession | null): void;
+    /**
+     * Called when SDK signs out.
+     * Aborts all pending operations.
+     */
+    onSignOut(): void;
+    /**
+     * Get the abort signal for this service.
+     * Combines the service-level abort with context-level abort.
+     */
+    protected get abortSignal(): AbortSignal;
+    /**
+     * Check if the service is authenticated.
+     */
+    protected get isAuthenticated(): boolean;
+    /**
+     * Get the current session.
+     * Throws if not authenticated.
+     */
+    protected get session(): ServiceSession;
+    /**
+     * Check authentication and return error result if not authenticated.
+     * Use this at the start of methods that require authentication.
+     *
+     * @returns true if authenticated, false otherwise
+     */
+    protected requireAuth(): boolean;
+    /**
+     * Emit a telemetry event.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    protected emit(event: string, data: unknown): void;
+    /**
+     * Emit a service request event.
+     *
+     * @param action - The action being performed
+     * @param key - Optional key/path being accessed
+     */
+    protected emitRequest(action: string, key?: string): void;
+    /**
+     * Emit a service response event.
+     *
+     * @param action - The action that was performed
+     * @param ok - Whether the request was successful
+     * @param startTime - Start time for duration calculation
+     * @param status - Optional HTTP status code
+     */
+    protected emitResponse(action: string, ok: boolean, startTime: number, status?: number): void;
+    /**
+     * Emit a service error event.
+     *
+     * @param error - The service error
+     */
+    protected emitError(error: ServiceError, action?: string): void;
+    /**
+     * Get the service name from the static property.
+     * Subclasses must define static serviceName.
+     */
+    protected getServiceName(): string;
+    /**
+     * Stable span name used by SDK telemetry sinks.
+     */
+    protected spanName(action: string): string;
+    /**
+     * Create a combined abort signal from multiple sources.
+     *
+     * @param signals - Additional abort signals to combine
+     * @returns A combined abort signal
+     */
+    protected combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal;
+    /**
+     * Wrap an operation with error handling and telemetry.
+     *
+     * @param action - The action name for telemetry
+     * @param key - Optional key for telemetry
+     * @param operation - The operation to execute
+     * @returns Result of the operation
+     */
+    protected withTelemetry<T>(action: string, key: string | undefined, operation: () => Promise<Result<T>>): Promise<Result<T>>;
+}
+
+export { BaseService as B };

package/dist/encryption/index.cjs

@@ -25,6 +25,7 @@ __export(encryption_exports, {
   DECRYPT_RESULT_TYPE: () => DECRYPT_RESULT_TYPE,
   DEFAULT_ENCRYPTION_ALG: () => DEFAULT_ENCRYPTION_ALG,
   DEFAULT_KEY_VERSION: () => DEFAULT_KEY_VERSION,
+  DecryptTransportResponseError: () => import_decrypt_transport_response_error3.DecryptTransportResponseError,
   ENCRYPTION_NETWORK_URN_PREFIX: () => ENCRYPTION_NETWORK_URN_PREFIX,
   ENCRYPTION_SERVICE: () => ENCRYPTION_SERVICE,
   ENCRYPTION_SERVICE_SHORT: () => ENCRYPTION_SERVICE_SHORT,
@@ -206,7 +207,7 @@ var BaseService = class {
    * Combines the service-level abort with context-level abort.
    */
   get abortSignal() {
-    return this.abortController.signal;
+    return this.combineSignals();
   }
   /**
    * Check if the service is authenticated.
@@ -322,7 +323,11 @@ var BaseService = class {
    */
   combineSignals(...signals) {
     const controller = new AbortController();
-    const allSignals = [this.abortSignal, ...signals.filter(Boolean)];
+    const allSignals = [
+      this.abortController.signal,
+      this.context?.abortSignal,
+      ...signals.filter(Boolean)
+    ].filter(Boolean);
     for (const signal of allSignals) {
       if (signal.aborted) {
         controller.abort(signal.reason);
@@ -1209,6 +1214,8 @@ function openWrappedKey(crypto, receiverPrivateKey, response) {
 }
 
 // src/encryption/EncryptionService.ts
+var import_decrypt_transport_response_error = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
+var import_decrypt_transport_response_error2 = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
 function encOk(data) {
   return { ok: true, data };
 }
@@ -1227,17 +1234,20 @@ var EncryptionService = class extends BaseService {
     return this._config.crypto;
   }
   async discoverNetwork(identifier, ownerDid) {
+    this.assertActive();
     const result = await discoverNetwork({
       identifier,
       ...ownerDid !== void 0 ? { ownerDid } : {},
       ...this._config.node !== void 0 ? { node: this._config.node } : {},
       ...this._config.wellKnown !== void 0 ? { wellKnown: this._config.wellKnown } : {}
     });
+    this.assertActive();
     if (!result.ok) return result;
     return encOk(result.data.descriptor);
   }
   async encryptToNetwork(networkId, plaintext, options) {
     try {
+      this.assertActive();
       const discovered = await this.discoverNetwork(networkId);
       if (!discovered.ok) return discovered;
       const usable = ensureNetworkUsableForDecrypt(discovered.data);
@@ -1265,6 +1275,7 @@ var EncryptionService = class extends BaseService {
   }
   async decryptEnvelope(envelope, capabilityProof, options) {
     try {
+      this.assertActive();
       const validated = validateEnvelope(this.crypto, envelope);
       if (!validated.ok) return validated;
       if (options?.aad !== void 0 && validated.data.aad !== base64Encode(options.aad)) {
@@ -1330,16 +1341,38 @@ var EncryptionService = class extends BaseService {
         facts,
         proof: capabilityProof
       });
-      if (!built.ok) return built;
+      this.assertActive();
+      if (!built.ok) {
+        if (built.error.code !== "TRANSPORT_ERROR") return built;
+        return encErr(
+          encryptionError({
+            code: "INVALID_INPUT",
+            message: "Unable to build decrypt request"
+          })
+        );
+      }
       let response;
       try {
         response = await this._config.transport.postDecrypt({
           targetNode,
           networkId: envelope.networkId,
           authorization: built.data.authorization,
-          canonicalBody: built.data.canonicalBody
+          canonicalBody: built.data.canonicalBody,
+          signal: this.abortSignal
         });
+        this.assertActive();
       } catch (error) {
+        if (error instanceof import_decrypt_transport_response_error.DecryptTransportResponseError) {
+          return encErr(
+            encryptionError(
+              error.status === 401 || error.status === 403 ? {
+                code: "DECRYPT_DENIED",
+                message: "Node denied decrypt request",
+                ...error.permissionHint === void 0 ? {} : { permissionHint: error.permissionHint }
+              } : { code: "INVALID_RESPONSE", message: "Node decrypt request failed" }
+            )
+          );
+        }
         return encErr(
           encryptionError({
             code: "TRANSPORT_ERROR",
@@ -1370,14 +1403,20 @@ var EncryptionService = class extends BaseService {
     } catch (error) {
       return encErr(
         encryptionError({
-          code: "TRANSPORT_ERROR",
-          cause: toError(error)
+          code: "INVALID_RESPONSE",
+          message: "Local decryption failed"
         })
       );
     }
   }
+  assertActive() {
+    this._config.assertActive?.();
+  }
 };
 EncryptionService.serviceName = "encryption";
+
+// src/encryption/index.ts
+var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DECRYPT_ACTION,
@@ -1385,6 +1424,7 @@ EncryptionService.serviceName = "encryption";
   DECRYPT_RESULT_TYPE,
   DEFAULT_ENCRYPTION_ALG,
   DEFAULT_KEY_VERSION,
+  DecryptTransportResponseError,
   ENCRYPTION_NETWORK_URN_PREFIX,
   ENCRYPTION_SERVICE,
   ENCRYPTION_SERVICE_SHORT,