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

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   ServiceRetryEventSchema: () => ServiceRetryEventSchema,
   ServiceSessionSchema: () => ServiceSessionSchema,
   TelemetryEvents: () => TelemetryEvents,
+  TelemetrySpanEventSchema: () => TelemetrySpanEventSchema,
   TinyCloudQuota: () => TinyCloudQuota,
   VaultHeaders: () => VaultHeaders,
   VaultPublicSpaceKVActions: () => VaultPublicSpaceKVActions,
@@ -121,6 +122,7 @@ __export(index_exports, {
   validateServiceRequestEvent: () => validateServiceRequestEvent,
   validateServiceResponseEvent: () => validateServiceResponseEvent,
   validateServiceSession: () => validateServiceSession,
+  validateTelemetrySpanEvent: () => validateTelemetrySpanEvent,
   verifyDecryptResponse: () => verifyDecryptResponse,
   wrapError: () => wrapError
 });
@@ -171,6 +173,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,18 +251,22 @@ var KVListResultSchema = createResultSchema(KVListResponseSchema);
 var ServiceRequestEventSchema = import_zod.z.object({
   service: import_zod.z.string(),
   action: import_zod.z.string(),
+  span: import_zod.z.string().optional(),
   key: import_zod.z.string().optional(),
   timestamp: import_zod.z.number()
 });
 var ServiceResponseEventSchema = import_zod.z.object({
   service: import_zod.z.string(),
   action: import_zod.z.string(),
+  span: import_zod.z.string().optional(),
   ok: import_zod.z.boolean(),
   duration: import_zod.z.number(),
+  durationMs: import_zod.z.number().optional(),
   status: import_zod.z.number().optional()
 });
 var ServiceErrorEventSchema = import_zod.z.object({
   service: import_zod.z.string(),
+  span: import_zod.z.string().optional(),
   error: ServiceErrorSchema
 });
 var ServiceRetryEventSchema = import_zod.z.object({
@@ -268,6 +275,15 @@ var ServiceRetryEventSchema = import_zod.z.object({
   maxAttempts: import_zod.z.number().int().positive(),
   error: ServiceErrorSchema
 });
+var TelemetrySpanEventSchema = import_zod.z.object({
+  span: import_zod.z.string(),
+  ok: import_zod.z.boolean(),
+  durationMs: import_zod.z.number(),
+  service: import_zod.z.string().optional(),
+  action: import_zod.z.string().optional(),
+  status: import_zod.z.number().optional(),
+  error: ServiceErrorSchema.optional()
+});
 var RetryPolicySchema = import_zod.z.object({
   /** Maximum number of attempts (including initial) */
   maxAttempts: import_zod.z.number().int().positive(),
@@ -399,6 +415,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 {
@@ -416,6 +447,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
@@ -510,6 +543,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) {
@@ -788,9 +828,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()
     });
@@ -804,11 +846,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
     });
   }
@@ -817,9 +872,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
     });
   }
@@ -830,6 +887,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.
    *
@@ -867,13 +930,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);
     }
   }
@@ -1798,7 +1861,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
         );
@@ -1828,7 +1891,7 @@ var SQLService = class extends BaseService {
         }
         const response = await this.invokeSQL(
           dbName,
-          SQLAction.WRITE,
+          this.actionForSql(sql, SQLAction.WRITE),
           body,
           options?.signal
         );
@@ -1850,7 +1913,7 @@ var SQLService = class extends BaseService {
       try {
         const response = await this.invokeSQL(
           dbName,
-          SQLAction.WRITE,
+          this.actionForSqlBatch(statements),
           { action: "batch", statements },
           options?.signal
         );
@@ -1927,6 +1990,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 = {};
@@ -1972,6 +2043,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 {
@@ -5650,6 +5748,7 @@ EncryptionService.serviceName = "encryption";
   ServiceRetryEventSchema,
   ServiceSessionSchema,
   TelemetryEvents,
+  TelemetrySpanEventSchema,
   TinyCloudQuota,
   VaultHeaders,
   VaultPublicSpaceKVActions,
@@ -5709,6 +5808,7 @@ EncryptionService.serviceName = "encryption";
   validateServiceRequestEvent,
   validateServiceResponseEvent,
   validateServiceSession,
+  validateTelemetrySpanEvent,
   verifyDecryptResponse,
   wrapError
 });