@tinycloud/sdk-services 2.3.0-beta.7 → 2.3.0-beta.8

package/dist/{BaseService-DZ2hBJeD.d.cts → BaseService-BdRvNm2s.d.cts}

@@ -205,6 +205,17 @@ declare const defaultRetryPolicy: RetryPolicy;
  * Event handler function type.
  */
 type EventHandler = (data: unknown) => void;
+/**
+ * SDK telemetry event handler.
+ */
+type TelemetryEventHandler = (event: string, data: unknown) => void;
+/**
+ * Default-off telemetry configuration.
+ */
+type TelemetryConfig = boolean | {
+    enabled?: boolean;
+    onEvent?: TelemetryEventHandler;
+};
 /**
  * Service interface - base contract for all services.
  */
@@ -252,6 +263,7 @@ interface IServiceContext {
 interface ServiceRequestEvent {
     service: string;
     action: string;
+    span?: string;
     key?: string;
     timestamp: number;
 }
@@ -261,8 +273,10 @@ interface ServiceRequestEvent {
 interface ServiceResponseEvent {
     service: string;
     action: string;
+    span?: string;
     ok: boolean;
     duration: number;
+    durationMs?: number;
     status?: number;
 }
 /**
@@ -270,6 +284,7 @@ interface ServiceResponseEvent {
  */
 interface ServiceErrorEvent {
     service: string;
+    span?: string;
     error: ServiceError;
 }
 /**
@@ -281,10 +296,23 @@ interface ServiceRetryEvent {
     maxAttempts: number;
     error: ServiceError;
 }
+/**
+ * Generic named span event for aggregating operation timings.
+ */
+interface TelemetrySpanEvent {
+    span: string;
+    ok: boolean;
+    durationMs: number;
+    service?: string;
+    action?: string;
+    status?: number;
+    error?: ServiceError;
+}
 /**
  * Telemetry event names.
  */
 declare const TelemetryEvents: {
+    readonly SPAN: "telemetry.span";
     readonly SERVICE_REQUEST: "service.request";
     readonly SERVICE_RESPONSE: "service.response";
     readonly SERVICE_ERROR: "service.error";
@@ -435,12 +463,16 @@ declare abstract class BaseService implements IService {
      *
      * @param error - The service error
      */
-    protected emitError(error: ServiceError): void;
+    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.
      *
@@ -459,4 +491,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, type ErrorCode as E, type FetchFunction as F, type IServiceContext as I, type RetryPolicy as R, type ServiceSession as S, TelemetryEvents as T, type InvokeFunction as a, type InvokeAnyFunction as b, type IService as c, type ServiceError as d, type Result as e, type StorageQuotaInfo as f, ErrorCodes as g, type EventHandler as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, defaultRetryPolicy as s, err as t, ok as u, serviceError as v };
+export { BaseService as B, type EventHandler as E, type FetchFunction as F, type IServiceContext as I, type RetryPolicy as R, type ServiceSession as S, type TelemetryConfig as T, type InvokeFunction as a, type InvokeAnyFunction as b, type IService as c, type ServiceError as d, type Result as e, type StorageQuotaInfo as f, type ErrorCode as g, ErrorCodes as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, type TelemetryEventHandler as s, TelemetryEvents as t, type TelemetrySpanEvent as u, defaultRetryPolicy as v, err as w, ok as x, serviceError as y };

package/dist/{BaseService-DZ2hBJeD.d.ts → BaseService-BdRvNm2s.d.ts}

@@ -205,6 +205,17 @@ declare const defaultRetryPolicy: RetryPolicy;
  * Event handler function type.
  */
 type EventHandler = (data: unknown) => void;
+/**
+ * SDK telemetry event handler.
+ */
+type TelemetryEventHandler = (event: string, data: unknown) => void;
+/**
+ * Default-off telemetry configuration.
+ */
+type TelemetryConfig = boolean | {
+    enabled?: boolean;
+    onEvent?: TelemetryEventHandler;
+};
 /**
  * Service interface - base contract for all services.
  */
@@ -252,6 +263,7 @@ interface IServiceContext {
 interface ServiceRequestEvent {
     service: string;
     action: string;
+    span?: string;
     key?: string;
     timestamp: number;
 }
@@ -261,8 +273,10 @@ interface ServiceRequestEvent {
 interface ServiceResponseEvent {
     service: string;
     action: string;
+    span?: string;
     ok: boolean;
     duration: number;
+    durationMs?: number;
     status?: number;
 }
 /**
@@ -270,6 +284,7 @@ interface ServiceResponseEvent {
  */
 interface ServiceErrorEvent {
     service: string;
+    span?: string;
     error: ServiceError;
 }
 /**
@@ -281,10 +296,23 @@ interface ServiceRetryEvent {
     maxAttempts: number;
     error: ServiceError;
 }
+/**
+ * Generic named span event for aggregating operation timings.
+ */
+interface TelemetrySpanEvent {
+    span: string;
+    ok: boolean;
+    durationMs: number;
+    service?: string;
+    action?: string;
+    status?: number;
+    error?: ServiceError;
+}
 /**
  * Telemetry event names.
  */
 declare const TelemetryEvents: {
+    readonly SPAN: "telemetry.span";
     readonly SERVICE_REQUEST: "service.request";
     readonly SERVICE_RESPONSE: "service.response";
     readonly SERVICE_ERROR: "service.error";
@@ -435,12 +463,16 @@ declare abstract class BaseService implements IService {
      *
      * @param error - The service error
      */
-    protected emitError(error: ServiceError): void;
+    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.
      *
@@ -459,4 +491,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, type ErrorCode as E, type FetchFunction as F, type IServiceContext as I, type RetryPolicy as R, type ServiceSession as S, TelemetryEvents as T, type InvokeFunction as a, type InvokeAnyFunction as b, type IService as c, type ServiceError as d, type Result as e, type StorageQuotaInfo as f, ErrorCodes as g, type EventHandler as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, defaultRetryPolicy as s, err as t, ok as u, serviceError as v };
+export { BaseService as B, type EventHandler as E, type FetchFunction as F, type IServiceContext as I, type RetryPolicy as R, type ServiceSession as S, type TelemetryConfig as T, type InvokeFunction as a, type InvokeAnyFunction as b, type IService as c, type ServiceError as d, type Result as e, type StorageQuotaInfo as f, type ErrorCode as g, ErrorCodes as h, type FetchRequestInit as i, type FetchResponse as j, type InvocationFact as k, type InvocationFacts as l, type InvokeAnyEntry as m, type ServiceErrorEvent as n, type ServiceHeaders as o, type ServiceRequestEvent as p, type ServiceResponseEvent as q, type ServiceRetryEvent as r, type TelemetryEventHandler as s, TelemetryEvents as t, type TelemetrySpanEvent as u, defaultRetryPolicy as v, err as w, ok as x, serviceError as y };

package/dist/encryption/index.cjs

@@ -108,6 +108,7 @@ var defaultRetryPolicy = {
   retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
 };
 var TelemetryEvents = {
+  SPAN: "telemetry.span",
   SERVICE_REQUEST: "service.request",
   SERVICE_RESPONSE: "service.response",
   SERVICE_ERROR: "service.error",
@@ -248,9 +249,11 @@ var BaseService = class {
    * @param key - Optional key/path being accessed
    */
   emitRequest(action, key) {
+    const service = this.getServiceName();
     this.emit(TelemetryEvents.SERVICE_REQUEST, {
-      service: this.getServiceName(),
+      service,
       action,
+      span: this.spanName(action),
       key,
       timestamp: Date.now()
     });
@@ -264,11 +267,24 @@ var BaseService = class {
    * @param status - Optional HTTP status code
    */
   emitResponse(action, ok, startTime, status) {
+    const service = this.getServiceName();
+    const durationMs = Date.now() - startTime;
+    const span = this.spanName(action);
     this.emit(TelemetryEvents.SERVICE_RESPONSE, {
-      service: this.getServiceName(),
+      service,
+      action,
+      span,
+      ok,
+      duration: durationMs,
+      durationMs,
+      status
+    });
+    this.emit(TelemetryEvents.SPAN, {
+      span,
+      service,
       action,
       ok,
-      duration: Date.now() - startTime,
+      durationMs,
       status
     });
   }
@@ -277,9 +293,11 @@ var BaseService = class {
    *
    * @param error - The service error
    */
-  emitError(error) {
+  emitError(error, action) {
+    const span = action ? this.spanName(action) : void 0;
     this.emit(TelemetryEvents.SERVICE_ERROR, {
       service: this.getServiceName(),
+      ...span ? { span } : {},
       error
     });
   }
@@ -290,6 +308,12 @@ var BaseService = class {
   getServiceName() {
     return this.constructor.serviceName;
   }
+  /**
+   * Stable span name used by SDK telemetry sinks.
+   */
+  spanName(action) {
+    return `sdk.${this.getServiceName()}.${action}`;
+  }
   /**
    * Create a combined abort signal from multiple sources.
    *
@@ -327,13 +351,13 @@ var BaseService = class {
         this.emitResponse(action, true, startTime);
       } else {
         this.emitResponse(action, false, startTime);
-        this.emitError(result.error);
+        this.emitError(result.error, action);
       }
       return result;
     } catch (error) {
       const serviceError2 = wrapError(this.getServiceName(), error);
       this.emitResponse(action, false, startTime);
-      this.emitError(serviceError2);
+      this.emitError(serviceError2, action);
       return err(serviceError2);
     }
   }