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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, c as IService, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-DZ2hBJeD.cjs';
-export { E as ErrorCode, g as ErrorCodes, h as EventHandler, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, T as TelemetryEvents, s as defaultRetryPolicy, t as err, u as ok, v as serviceError } from './BaseService-DZ2hBJeD.cjs';
+import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-BdRvNm2s.cjs';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './BaseService-BdRvNm2s.cjs';
 import { z } from 'zod';
 import { IKVService } from './kv/index.cjs';
 export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
@@ -416,17 +416,20 @@ type KVListResultType = z.infer<typeof KVListResultSchema>;
 declare const ServiceRequestEventSchema: z.ZodObject<{
     service: z.ZodString;
     action: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     key: z.ZodOptional<z.ZodString>;
     timestamp: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     service: string;
     action: string;
     timestamp: number;
+    span?: string | undefined;
     key?: string | undefined;
 }, {
     service: string;
     action: string;
     timestamp: number;
+    span?: string | undefined;
     key?: string | undefined;
 }>;
 type ServiceRequestEventType = z.infer<typeof ServiceRequestEventSchema>;
@@ -436,8 +439,10 @@ type ServiceRequestEventType = z.infer<typeof ServiceRequestEventSchema>;
 declare const ServiceResponseEventSchema: z.ZodObject<{
     service: z.ZodString;
     action: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     ok: z.ZodBoolean;
     duration: z.ZodNumber;
+    durationMs: z.ZodOptional<z.ZodNumber>;
     status: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     service: string;
@@ -445,12 +450,16 @@ declare const ServiceResponseEventSchema: z.ZodObject<{
     action: string;
     duration: number;
     status?: number | undefined;
+    span?: string | undefined;
+    durationMs?: number | undefined;
 }, {
     service: string;
     ok: boolean;
     action: string;
     duration: number;
     status?: number | undefined;
+    span?: string | undefined;
+    durationMs?: number | undefined;
 }>;
 type ServiceResponseEventType = z.infer<typeof ServiceResponseEventSchema>;
 /**
@@ -458,6 +467,7 @@ type ServiceResponseEventType = z.infer<typeof ServiceResponseEventSchema>;
  */
 declare const ServiceErrorEventSchema: z.ZodObject<{
     service: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     error: z.ZodObject<{
         /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
         code: z.ZodString;
@@ -491,6 +501,7 @@ declare const ServiceErrorEventSchema: z.ZodObject<{
         meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     };
     service: string;
+    span?: string | undefined;
 }, {
     error: {
         code: string;
@@ -500,6 +511,7 @@ declare const ServiceErrorEventSchema: z.ZodObject<{
         meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     };
     service: string;
+    span?: string | undefined;
 }>;
 type ServiceErrorEventType = z.infer<typeof ServiceErrorEventSchema>;
 /**
@@ -557,6 +569,70 @@ declare const ServiceRetryEventSchema: z.ZodObject<{
     maxAttempts: number;
 }>;
 type ServiceRetryEventType = z.infer<typeof ServiceRetryEventSchema>;
+/**
+ * Schema for generic named span event.
+ */
+declare const TelemetrySpanEventSchema: z.ZodObject<{
+    span: z.ZodString;
+    ok: z.ZodBoolean;
+    durationMs: z.ZodNumber;
+    service: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodObject<{
+        /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+        code: z.ZodString;
+        /** Human-readable error message */
+        message: z.ZodString;
+        /** Service that produced the error (e.g., 'kv', 'sql') */
+        service: z.ZodString;
+        /** Original error if this wraps another error - not validated since Error is a class */
+        cause: z.ZodOptional<z.ZodUnknown>;
+        /** Additional metadata about the error - passthrough allows any object properties */
+        meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    ok: boolean;
+    span: string;
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    service?: string | undefined;
+    status?: number | undefined;
+    action?: string | undefined;
+}, {
+    ok: boolean;
+    span: string;
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    service?: string | undefined;
+    status?: number | undefined;
+    action?: string | undefined;
+}>;
+type TelemetrySpanEventType = z.infer<typeof TelemetrySpanEventSchema>;
 /**
  * Schema for retry policy configuration.
  */
@@ -718,16 +794,25 @@ declare function validateServiceResponseEvent(data: unknown): {
     ok: false;
     error: ValidationError;
 };
+/**
+ * Validate named telemetry span event against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateTelemetrySpanEvent(data: unknown): {
+    ok: true;
+    data: TelemetrySpanEventType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
 
 /**
  * ServiceContext implementation for TinyCloud SDK Services
  * @module @tinycloud/sdk-services
  */
 
-/**
- * Event handler type for telemetry events.
- */
-type EventHandler = (data: unknown) => void;
 /**
  * Configuration options for ServiceContext.
  */
@@ -744,6 +829,8 @@ interface ServiceContextConfig {
     session?: ServiceSession | null;
     /** Retry policy configuration */
     retryPolicy?: Partial<RetryPolicy>;
+    /** Default-off telemetry event delivery. */
+    telemetry?: TelemetryConfig;
 }
 /**
  * ServiceContext provides platform dependencies and cross-service access to services.
@@ -776,6 +863,8 @@ declare class ServiceContext implements IServiceContext {
     private readonly _fetch;
     private readonly _hosts;
     private readonly _retryPolicy;
+    private readonly _telemetryEnabled;
+    private readonly _telemetryHandler?;
     constructor(config: ServiceContextConfig);
     /**
      * Get the current session.
@@ -2010,4 +2099,4 @@ declare class SecretsService implements ISecretsService {
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, createKVResponseSchema, createResultSchema, createVaultCrypto, errorResult, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, wrapError };
+export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, createKVResponseSchema, createResultSchema, createVaultCrypto, errorResult, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, c as IService, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-DZ2hBJeD.js';
-export { E as ErrorCode, g as ErrorCodes, h as EventHandler, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, T as TelemetryEvents, s as defaultRetryPolicy, t as err, u as ok, v as serviceError } from './BaseService-DZ2hBJeD.js';
+import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-BdRvNm2s.js';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './BaseService-BdRvNm2s.js';
 import { z } from 'zod';
 import { IKVService } from './kv/index.js';
 export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
@@ -416,17 +416,20 @@ type KVListResultType = z.infer<typeof KVListResultSchema>;
 declare const ServiceRequestEventSchema: z.ZodObject<{
     service: z.ZodString;
     action: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     key: z.ZodOptional<z.ZodString>;
     timestamp: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     service: string;
     action: string;
     timestamp: number;
+    span?: string | undefined;
     key?: string | undefined;
 }, {
     service: string;
     action: string;
     timestamp: number;
+    span?: string | undefined;
     key?: string | undefined;
 }>;
 type ServiceRequestEventType = z.infer<typeof ServiceRequestEventSchema>;
@@ -436,8 +439,10 @@ type ServiceRequestEventType = z.infer<typeof ServiceRequestEventSchema>;
 declare const ServiceResponseEventSchema: z.ZodObject<{
     service: z.ZodString;
     action: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     ok: z.ZodBoolean;
     duration: z.ZodNumber;
+    durationMs: z.ZodOptional<z.ZodNumber>;
     status: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     service: string;
@@ -445,12 +450,16 @@ declare const ServiceResponseEventSchema: z.ZodObject<{
     action: string;
     duration: number;
     status?: number | undefined;
+    span?: string | undefined;
+    durationMs?: number | undefined;
 }, {
     service: string;
     ok: boolean;
     action: string;
     duration: number;
     status?: number | undefined;
+    span?: string | undefined;
+    durationMs?: number | undefined;
 }>;
 type ServiceResponseEventType = z.infer<typeof ServiceResponseEventSchema>;
 /**
@@ -458,6 +467,7 @@ type ServiceResponseEventType = z.infer<typeof ServiceResponseEventSchema>;
  */
 declare const ServiceErrorEventSchema: z.ZodObject<{
     service: z.ZodString;
+    span: z.ZodOptional<z.ZodString>;
     error: z.ZodObject<{
         /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
         code: z.ZodString;
@@ -491,6 +501,7 @@ declare const ServiceErrorEventSchema: z.ZodObject<{
         meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     };
     service: string;
+    span?: string | undefined;
 }, {
     error: {
         code: string;
@@ -500,6 +511,7 @@ declare const ServiceErrorEventSchema: z.ZodObject<{
         meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     };
     service: string;
+    span?: string | undefined;
 }>;
 type ServiceErrorEventType = z.infer<typeof ServiceErrorEventSchema>;
 /**
@@ -557,6 +569,70 @@ declare const ServiceRetryEventSchema: z.ZodObject<{
     maxAttempts: number;
 }>;
 type ServiceRetryEventType = z.infer<typeof ServiceRetryEventSchema>;
+/**
+ * Schema for generic named span event.
+ */
+declare const TelemetrySpanEventSchema: z.ZodObject<{
+    span: z.ZodString;
+    ok: z.ZodBoolean;
+    durationMs: z.ZodNumber;
+    service: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodObject<{
+        /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+        code: z.ZodString;
+        /** Human-readable error message */
+        message: z.ZodString;
+        /** Service that produced the error (e.g., 'kv', 'sql') */
+        service: z.ZodString;
+        /** Original error if this wraps another error - not validated since Error is a class */
+        cause: z.ZodOptional<z.ZodUnknown>;
+        /** Additional metadata about the error - passthrough allows any object properties */
+        meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    ok: boolean;
+    span: string;
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    service?: string | undefined;
+    status?: number | undefined;
+    action?: string | undefined;
+}, {
+    ok: boolean;
+    span: string;
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    service?: string | undefined;
+    status?: number | undefined;
+    action?: string | undefined;
+}>;
+type TelemetrySpanEventType = z.infer<typeof TelemetrySpanEventSchema>;
 /**
  * Schema for retry policy configuration.
  */
@@ -718,16 +794,25 @@ declare function validateServiceResponseEvent(data: unknown): {
     ok: false;
     error: ValidationError;
 };
+/**
+ * Validate named telemetry span event against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateTelemetrySpanEvent(data: unknown): {
+    ok: true;
+    data: TelemetrySpanEventType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
 
 /**
  * ServiceContext implementation for TinyCloud SDK Services
  * @module @tinycloud/sdk-services
  */
 
-/**
- * Event handler type for telemetry events.
- */
-type EventHandler = (data: unknown) => void;
 /**
  * Configuration options for ServiceContext.
  */
@@ -744,6 +829,8 @@ interface ServiceContextConfig {
     session?: ServiceSession | null;
     /** Retry policy configuration */
     retryPolicy?: Partial<RetryPolicy>;
+    /** Default-off telemetry event delivery. */
+    telemetry?: TelemetryConfig;
 }
 /**
  * ServiceContext provides platform dependencies and cross-service access to services.
@@ -776,6 +863,8 @@ declare class ServiceContext implements IServiceContext {
     private readonly _fetch;
     private readonly _hosts;
     private readonly _retryPolicy;
+    private readonly _telemetryEnabled;
+    private readonly _telemetryHandler?;
     constructor(config: ServiceContextConfig);
     /**
      * Get the current session.
@@ -2010,4 +2099,4 @@ declare class SecretsService implements ISecretsService {
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, createKVResponseSchema, createResultSchema, createVaultCrypto, errorResult, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, wrapError };
+export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, createKVResponseSchema, createResultSchema, createVaultCrypto, errorResult, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };

package/dist/index.js

@@ -43,6 +43,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",
@@ -120,18 +121,22 @@ var KVListResultSchema = createResultSchema(KVListResponseSchema);
 var ServiceRequestEventSchema = z.object({
   service: z.string(),
   action: z.string(),
+  span: z.string().optional(),
   key: z.string().optional(),
   timestamp: z.number()
 });
 var ServiceResponseEventSchema = z.object({
   service: z.string(),
   action: z.string(),
+  span: z.string().optional(),
   ok: z.boolean(),
   duration: z.number(),
+  durationMs: z.number().optional(),
   status: z.number().optional()
 });
 var ServiceErrorEventSchema = z.object({
   service: z.string(),
+  span: z.string().optional(),
   error: ServiceErrorSchema
 });
 var ServiceRetryEventSchema = z.object({
@@ -140,6 +145,15 @@ var ServiceRetryEventSchema = z.object({
   maxAttempts: z.number().int().positive(),
   error: ServiceErrorSchema
 });
+var TelemetrySpanEventSchema = z.object({
+  span: z.string(),
+  ok: z.boolean(),
+  durationMs: z.number(),
+  service: z.string().optional(),
+  action: z.string().optional(),
+  status: z.number().optional(),
+  error: ServiceErrorSchema.optional()
+});
 var RetryPolicySchema = z.object({
   /** Maximum number of attempts (including initial) */
   maxAttempts: z.number().int().positive(),
@@ -271,6 +285,21 @@ function validateServiceResponseEvent(data) {
   }
   return { ok: true, data: result.data };
 }
+function validateTelemetrySpanEvent(data) {
+  const result = TelemetrySpanEventSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "telemetry",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
 
 // src/context.ts
 var ServiceContext = class {
@@ -288,6 +317,8 @@ var ServiceContext = class {
       ...defaultRetryPolicy,
       ...config.retryPolicy
     };
+    this._telemetryEnabled = typeof config.telemetry === "boolean" ? config.telemetry : config.telemetry?.enabled === true;
+    this._telemetryHandler = typeof config.telemetry === "object" ? config.telemetry.onEvent : void 0;
   }
   // ============================================================
   // Session Management
@@ -382,6 +413,13 @@ var ServiceContext = class {
    * @param data - Event data
    */
   emit(event, data) {
+    if (this._telemetryEnabled && this._telemetryHandler) {
+      try {
+        this._telemetryHandler(event, data);
+      } catch (error) {
+        console.error(`Error in telemetry handler for "${event}":`, error);
+      }
+    }
     const handlers = this._eventHandlers.get(event);
     if (handlers) {
       for (const handler of handlers) {
@@ -660,9 +698,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()
     });
@@ -676,11 +716,24 @@ var BaseService = class {
    * @param status - Optional HTTP status code
    */
   emitResponse(action, ok2, 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: ok2,
-      duration: Date.now() - startTime,
+      duration: durationMs,
+      durationMs,
+      status
+    });
+    this.emit(TelemetryEvents.SPAN, {
+      span,
+      service,
+      action,
+      ok: ok2,
+      durationMs,
       status
     });
   }
@@ -689,9 +742,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
     });
   }
@@ -702,6 +757,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.
    *
@@ -739,13 +800,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 serviceError3 = wrapError(this.getServiceName(), error);
       this.emitResponse(action, false, startTime);
-      this.emitError(serviceError3);
+      this.emitError(serviceError3, action);
       return err(serviceError3);
     }
   }
@@ -1670,7 +1731,7 @@ var SQLService = class extends BaseService {
       try {
         const response = await this.invokeSQL(
           dbName,
-          SQLAction.READ,
+          this.actionForSql(sql, SQLAction.READ),
           { action: "query", sql, params: params ?? [] },
           options?.signal
         );
@@ -1700,7 +1761,7 @@ var SQLService = class extends BaseService {
         }
         const response = await this.invokeSQL(
           dbName,
-          SQLAction.WRITE,
+          this.actionForSql(sql, SQLAction.WRITE),
           body,
           options?.signal
         );
@@ -1722,7 +1783,7 @@ var SQLService = class extends BaseService {
       try {
         const response = await this.invokeSQL(
           dbName,
-          SQLAction.WRITE,
+          this.actionForSqlBatch(statements),
           { action: "batch", statements },
           options?.signal
         );
@@ -1799,6 +1860,14 @@ var SQLService = class extends BaseService {
       signal: this.combineSignals(signal)
     });
   }
+  actionForSql(sql, fallback) {
+    return firstSqlToken(sql) === "pragma" ? SQLAction.ADMIN : fallback;
+  }
+  actionForSqlBatch(statements) {
+    return statements.some(
+      (statement) => this.actionForSql(statement.sql, SQLAction.WRITE) === SQLAction.ADMIN
+    ) ? SQLAction.ADMIN : SQLAction.WRITE;
+  }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
     let errorBody = {};
@@ -1844,6 +1913,33 @@ var SQLService = class extends BaseService {
   }
 };
 SQLService.serviceName = "sql";
+function firstSqlToken(sql) {
+  let index = 0;
+  while (index < sql.length) {
+    while (index < sql.length && /\s/.test(sql[index])) {
+      index++;
+    }
+    if (sql.startsWith("--", index)) {
+      const newline = sql.indexOf("\n", index + 2);
+      if (newline === -1) {
+        return void 0;
+      }
+      index = newline + 1;
+      continue;
+    }
+    if (sql.startsWith("/*", index)) {
+      const end = sql.indexOf("*/", index + 2);
+      if (end === -1) {
+        return void 0;
+      }
+      index = end + 2;
+      continue;
+    }
+    break;
+  }
+  const match = /^[A-Za-z_]+/.exec(sql.slice(index));
+  return match?.[0].toLowerCase();
+}
 
 // src/duckdb/DuckDbDatabaseHandle.ts
 var DuckDbDatabaseHandle = class {
@@ -5521,6 +5617,7 @@ export {
   ServiceRetryEventSchema,
   ServiceSessionSchema,
   TelemetryEvents,
+  TelemetrySpanEventSchema,
   TinyCloudQuota,
   VaultHeaders,
   VaultPublicSpaceKVActions,
@@ -5580,6 +5677,7 @@ export {
   validateServiceRequestEvent,
   validateServiceResponseEvent,
   validateServiceSession,
+  validateTelemetrySpanEvent,
   verifyDecryptResponse,
   wrapError
 };