optropic 2.2.0 → 2.3.0

package/dist/index.cjs

@@ -973,18 +973,20 @@ var SchemasResource = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "2.2.0";
+var SDK_VERSION = "2.3.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelay: 1e3,
   maxDelay: 1e4
 };
+var KEY_REDACT_RE = /(optr_(?:live|test)_)[a-zA-Z0-9_-]+/g;
 var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
   _sandbox;
+  _debug;
   assets;
   audit;
   compliance;
@@ -1003,6 +1005,7 @@ var OptropicClient = class {
       ...config,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
+    this._debug = config.debug ?? false;
     if (config.sandbox !== void 0) {
       this._sandbox = config.sandbox;
     } else {
@@ -1043,6 +1046,31 @@ var OptropicClient = class {
     return this._sandbox ? "sandbox" : "live";
   }
   // ─────────────────────────────────────────────────────────────────────────
+  // DEBUG LOGGING
+  // ─────────────────────────────────────────────────────────────────────────
+  redact(text) {
+    return text.replace(KEY_REDACT_RE, "$1****");
+  }
+  logRequest(method, url, requestId, idempotencyKey) {
+    if (!this._debug) return;
+    const parts = [`${method} ${this.redact(url)}`, `req=${requestId}`];
+    if (idempotencyKey) parts.push(`idempotency=${idempotencyKey}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logResponse(method, path, status, durationMs, requestId, serverRequestId, attempt) {
+    if (!this._debug) return;
+    const parts = [`${method} ${path} \u2192 ${status} (${Math.round(durationMs)}ms)`, `req=${requestId}`];
+    if (serverRequestId) parts.push(`server_req=${serverRequestId}`);
+    if (attempt > 0) parts.push(`attempt=${attempt + 1}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logRetry(method, path, attempt, delay, reason) {
+    if (!this._debug) return;
+    console.log(
+      `[optropic] ${method} ${path} retry #${attempt + 1} in ${(delay / 1e3).toFixed(1)}s (${reason})`
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────────
   // PRIVATE METHODS
   // ─────────────────────────────────────────────────────────────────────────
   isValidApiKey(apiKey) {
@@ -1051,20 +1079,26 @@ var OptropicClient = class {
   async request(options) {
     const { method, path, body, headers = {}, timeout = this.config.timeout, idempotencyKey } = options;
     const url = `${this.baseUrl}${path}`;
+    const requestId = crypto.randomUUID();
     const requestHeaders = {
       "Content-Type": "application/json",
       "Accept": "application/json",
       "x-api-key": this.config.apiKey,
       "X-SDK-Version": SDK_VERSION,
       "X-SDK-Language": "typescript",
+      "X-Request-ID": requestId,
       ...this.config.headers,
       ...headers
     };
+    let effectiveIdempotencyKey;
     if (idempotencyKey) {
       requestHeaders["Idempotency-Key"] = idempotencyKey;
+      effectiveIdempotencyKey = idempotencyKey;
     } else if (["POST", "PUT", "PATCH"].includes(method)) {
-      requestHeaders["Idempotency-Key"] = crypto.randomUUID();
+      effectiveIdempotencyKey = crypto.randomUUID();
+      requestHeaders["Idempotency-Key"] = effectiveIdempotencyKey;
     }
+    this.logRequest(method, url, requestId, effectiveIdempotencyKey);
     let lastError = null;
     let attempt = 0;
     while (attempt <= this.retryConfig.maxRetries) {
@@ -1074,7 +1108,10 @@ var OptropicClient = class {
           method,
           requestHeaders,
           body,
-          timeout
+          timeout,
+          requestId,
+          path,
+          attempt
         );
         return response;
       } catch (error) {
@@ -1092,8 +1129,12 @@ var OptropicClient = class {
         const jitter = baseDelay * 0.5 * Math.random();
         const delay = baseDelay + jitter;
         if (error instanceof RateLimitedError) {
-          await this.sleep(error.retryAfter * 1e3);
+          const retryDelay = error.retryAfter * 1e3;
+          this.logRetry(method, path, attempt, retryDelay, "rate_limited");
+          await this.sleep(retryDelay);
         } else {
+          const statusCode = error instanceof OptropicError ? error.statusCode : 0;
+          this.logRetry(method, path, attempt, delay, `status=${statusCode}`);
           await this.sleep(delay);
         }
         attempt++;
@@ -1101,9 +1142,10 @@ var OptropicClient = class {
     }
     throw lastError ?? new OptropicError("UNKNOWN_ERROR", "Request failed");
   }
-  async executeRequest(url, method, headers, body, timeout) {
+  async executeRequest(url, method, headers, body, timeout, requestId, path, attempt) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const t0 = performance.now();
     try {
       const response = await fetch(url, {
         method,
@@ -1112,7 +1154,9 @@ var OptropicClient = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      const requestId = response.headers.get("x-request-id") ?? "";
+      const durationMs = performance.now() - t0;
+      const serverRequestId = response.headers.get("x-request-id") ?? "";
+      this.logResponse(method, path, response.status, durationMs, requestId, serverRequestId, attempt);
       if (!response.ok) {
         let errorBody;
         try {
@@ -1135,7 +1179,7 @@ var OptropicClient = class {
           code: errorBody.code,
           message: errorBody.message,
           details: errorBody.details,
-          requestId
+          requestId: serverRequestId || requestId
         });
       }
       if (response.status === 204) {
@@ -1161,8 +1205,12 @@ var OptropicClient = class {
       }
       if (error instanceof Error) {
         if (error.name === "AbortError") {
+          const durationMs2 = performance.now() - t0;
+          this.logResponse(method, path, 408, durationMs2, requestId, "", attempt);
           throw new TimeoutError(timeout);
         }
+        const durationMs = performance.now() - t0;
+        this.logResponse(method, path, 0, durationMs, requestId, "", attempt);
         throw new NetworkError(error.message, { cause: error });
       }
       throw new OptropicError("UNKNOWN_ERROR", "An unexpected error occurred", {
@@ -1421,7 +1469,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.2.0";
+var SDK_VERSION2 = "2.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetsResource,

package/dist/index.d.cts

@@ -44,6 +44,12 @@ interface OptropicConfig {
      * Retry configuration for failed requests.
      */
     readonly retry?: RetryConfig;
+    /**
+     * Enable debug logging.  When ``true``, every request and response
+     * is logged to the console with secrets redacted.
+     * @default false
+     */
+    readonly debug?: boolean;
 }
 /**
  * Retry configuration for network requests.
@@ -718,6 +724,7 @@ interface RequestOptions {
     path: string;
     body?: unknown;
     headers?: Record<string, string>;
+    /** Per-operation timeout in ms.  Overrides the client-level default. */
     timeout?: number;
     /** Idempotency key for safe mutation retries. Auto-generated for POST/PUT/PATCH if omitted. */
     idempotencyKey?: string;
@@ -732,6 +739,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *
  * const client = new OptropicClient({
  *   apiKey: 'optr_live_xxxxxxxxxxxx',
+ *   debug: true,  // logs every request/response
  * });
  *
  * // Create an asset
@@ -740,7 +748,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *   serial: 'SN001',
  * });
  *
- * // Verify an asset
+ * // Verify an asset (with per-operation timeout)
  * const result = await client.assets.verify(asset.id);
  * ```
  */
@@ -749,6 +757,7 @@ declare class OptropicClient {
     private readonly baseUrl;
     private readonly retryConfig;
     private readonly _sandbox;
+    private readonly _debug;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -764,6 +773,10 @@ declare class OptropicClient {
     get isLive(): boolean;
     /** Returns 'sandbox' or 'live'. */
     get environment(): 'sandbox' | 'live';
+    private redact;
+    private logRequest;
+    private logResponse;
+    private logRetry;
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -781,6 +794,7 @@ declare class OptropicClient {
  *
  * const client = createClient({
  *   apiKey: process.env.OPTROPIC_API_KEY!,
+ *   debug: true,
  * });
  * ```
  */
@@ -1310,6 +1324,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.2.0";
+declare const SDK_VERSION = "2.3.0";
 
 export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatteryPassportData, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type ConformityDeclaration, type CreateAssetParams, type CreateAuditEventParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateSchemaParams, type DPPCategory, type DPPMetadata, type Document, type DocumentVerifyResult, DocumentsResource, type EnrollDocumentParams, type ErrorCode, type ExportParams, type ExportResult, type FiberEntry, type FilterHeader, type FilterSyncResult, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListDocumentsParams, type ListDocumentsResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListProvenanceParams, type ListProvenanceResponse, type ListSchemasParams, type ListSchemasResponse, type MerkleProof, type MerkleRoot, NetworkError, type OfflineVerifyOptions, type OfflineVerifyResult, OptropicClient, type OptropicConfig, OptropicError, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, RateLimitedError, type RecordProvenanceParams, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, StaleFilterError, type SubstanceEntry, type TextilePassportData, TimeoutError, type UpdateSchemaParams, type VerifyDocumentParams, type VerifyProvenanceResult, type VerifyResult, type VerticalSchema, type WebhookVerifyOptions, type WebhookVerifyResult, buildDPPConfig, createClient, createErrorFromResponse, parseFilterHeader, parseSaltsHeader, validateDPPMetadata, verifyOffline, verifyWebhookSignature };

package/dist/index.d.ts

@@ -44,6 +44,12 @@ interface OptropicConfig {
      * Retry configuration for failed requests.
      */
     readonly retry?: RetryConfig;
+    /**
+     * Enable debug logging.  When ``true``, every request and response
+     * is logged to the console with secrets redacted.
+     * @default false
+     */
+    readonly debug?: boolean;
 }
 /**
  * Retry configuration for network requests.
@@ -718,6 +724,7 @@ interface RequestOptions {
     path: string;
     body?: unknown;
     headers?: Record<string, string>;
+    /** Per-operation timeout in ms.  Overrides the client-level default. */
     timeout?: number;
     /** Idempotency key for safe mutation retries. Auto-generated for POST/PUT/PATCH if omitted. */
     idempotencyKey?: string;
@@ -732,6 +739,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *
  * const client = new OptropicClient({
  *   apiKey: 'optr_live_xxxxxxxxxxxx',
+ *   debug: true,  // logs every request/response
  * });
  *
  * // Create an asset
@@ -740,7 +748,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *   serial: 'SN001',
  * });
  *
- * // Verify an asset
+ * // Verify an asset (with per-operation timeout)
  * const result = await client.assets.verify(asset.id);
  * ```
  */
@@ -749,6 +757,7 @@ declare class OptropicClient {
     private readonly baseUrl;
     private readonly retryConfig;
     private readonly _sandbox;
+    private readonly _debug;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -764,6 +773,10 @@ declare class OptropicClient {
     get isLive(): boolean;
     /** Returns 'sandbox' or 'live'. */
     get environment(): 'sandbox' | 'live';
+    private redact;
+    private logRequest;
+    private logResponse;
+    private logRetry;
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -781,6 +794,7 @@ declare class OptropicClient {
  *
  * const client = createClient({
  *   apiKey: process.env.OPTROPIC_API_KEY!,
+ *   debug: true,
  * });
  * ```
  */
@@ -1310,6 +1324,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.2.0";
+declare const SDK_VERSION = "2.3.0";
 
 export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatteryPassportData, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type ConformityDeclaration, type CreateAssetParams, type CreateAuditEventParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateSchemaParams, type DPPCategory, type DPPMetadata, type Document, type DocumentVerifyResult, DocumentsResource, type EnrollDocumentParams, type ErrorCode, type ExportParams, type ExportResult, type FiberEntry, type FilterHeader, type FilterSyncResult, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListDocumentsParams, type ListDocumentsResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListProvenanceParams, type ListProvenanceResponse, type ListSchemasParams, type ListSchemasResponse, type MerkleProof, type MerkleRoot, NetworkError, type OfflineVerifyOptions, type OfflineVerifyResult, OptropicClient, type OptropicConfig, OptropicError, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, RateLimitedError, type RecordProvenanceParams, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, StaleFilterError, type SubstanceEntry, type TextilePassportData, TimeoutError, type UpdateSchemaParams, type VerifyDocumentParams, type VerifyProvenanceResult, type VerifyResult, type VerticalSchema, type WebhookVerifyOptions, type WebhookVerifyResult, buildDPPConfig, createClient, createErrorFromResponse, parseFilterHeader, parseSaltsHeader, validateDPPMetadata, verifyOffline, verifyWebhookSignature };

package/dist/index.js

@@ -906,18 +906,20 @@ var SchemasResource = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "2.2.0";
+var SDK_VERSION = "2.3.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelay: 1e3,
   maxDelay: 1e4
 };
+var KEY_REDACT_RE = /(optr_(?:live|test)_)[a-zA-Z0-9_-]+/g;
 var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
   _sandbox;
+  _debug;
   assets;
   audit;
   compliance;
@@ -936,6 +938,7 @@ var OptropicClient = class {
       ...config,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
+    this._debug = config.debug ?? false;
     if (config.sandbox !== void 0) {
       this._sandbox = config.sandbox;
     } else {
@@ -976,6 +979,31 @@ var OptropicClient = class {
     return this._sandbox ? "sandbox" : "live";
   }
   // ─────────────────────────────────────────────────────────────────────────
+  // DEBUG LOGGING
+  // ─────────────────────────────────────────────────────────────────────────
+  redact(text) {
+    return text.replace(KEY_REDACT_RE, "$1****");
+  }
+  logRequest(method, url, requestId, idempotencyKey) {
+    if (!this._debug) return;
+    const parts = [`${method} ${this.redact(url)}`, `req=${requestId}`];
+    if (idempotencyKey) parts.push(`idempotency=${idempotencyKey}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logResponse(method, path, status, durationMs, requestId, serverRequestId, attempt) {
+    if (!this._debug) return;
+    const parts = [`${method} ${path} \u2192 ${status} (${Math.round(durationMs)}ms)`, `req=${requestId}`];
+    if (serverRequestId) parts.push(`server_req=${serverRequestId}`);
+    if (attempt > 0) parts.push(`attempt=${attempt + 1}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logRetry(method, path, attempt, delay, reason) {
+    if (!this._debug) return;
+    console.log(
+      `[optropic] ${method} ${path} retry #${attempt + 1} in ${(delay / 1e3).toFixed(1)}s (${reason})`
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────────
   // PRIVATE METHODS
   // ─────────────────────────────────────────────────────────────────────────
   isValidApiKey(apiKey) {
@@ -984,20 +1012,26 @@ var OptropicClient = class {
   async request(options) {
     const { method, path, body, headers = {}, timeout = this.config.timeout, idempotencyKey } = options;
     const url = `${this.baseUrl}${path}`;
+    const requestId = crypto.randomUUID();
     const requestHeaders = {
       "Content-Type": "application/json",
       "Accept": "application/json",
       "x-api-key": this.config.apiKey,
       "X-SDK-Version": SDK_VERSION,
       "X-SDK-Language": "typescript",
+      "X-Request-ID": requestId,
       ...this.config.headers,
       ...headers
     };
+    let effectiveIdempotencyKey;
     if (idempotencyKey) {
       requestHeaders["Idempotency-Key"] = idempotencyKey;
+      effectiveIdempotencyKey = idempotencyKey;
     } else if (["POST", "PUT", "PATCH"].includes(method)) {
-      requestHeaders["Idempotency-Key"] = crypto.randomUUID();
+      effectiveIdempotencyKey = crypto.randomUUID();
+      requestHeaders["Idempotency-Key"] = effectiveIdempotencyKey;
     }
+    this.logRequest(method, url, requestId, effectiveIdempotencyKey);
     let lastError = null;
     let attempt = 0;
     while (attempt <= this.retryConfig.maxRetries) {
@@ -1007,7 +1041,10 @@ var OptropicClient = class {
           method,
           requestHeaders,
           body,
-          timeout
+          timeout,
+          requestId,
+          path,
+          attempt
         );
         return response;
       } catch (error) {
@@ -1025,8 +1062,12 @@ var OptropicClient = class {
         const jitter = baseDelay * 0.5 * Math.random();
         const delay = baseDelay + jitter;
         if (error instanceof RateLimitedError) {
-          await this.sleep(error.retryAfter * 1e3);
+          const retryDelay = error.retryAfter * 1e3;
+          this.logRetry(method, path, attempt, retryDelay, "rate_limited");
+          await this.sleep(retryDelay);
         } else {
+          const statusCode = error instanceof OptropicError ? error.statusCode : 0;
+          this.logRetry(method, path, attempt, delay, `status=${statusCode}`);
           await this.sleep(delay);
         }
         attempt++;
@@ -1034,9 +1075,10 @@ var OptropicClient = class {
     }
     throw lastError ?? new OptropicError("UNKNOWN_ERROR", "Request failed");
   }
-  async executeRequest(url, method, headers, body, timeout) {
+  async executeRequest(url, method, headers, body, timeout, requestId, path, attempt) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const t0 = performance.now();
     try {
       const response = await fetch(url, {
         method,
@@ -1045,7 +1087,9 @@ var OptropicClient = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      const requestId = response.headers.get("x-request-id") ?? "";
+      const durationMs = performance.now() - t0;
+      const serverRequestId = response.headers.get("x-request-id") ?? "";
+      this.logResponse(method, path, response.status, durationMs, requestId, serverRequestId, attempt);
       if (!response.ok) {
         let errorBody;
         try {
@@ -1068,7 +1112,7 @@ var OptropicClient = class {
           code: errorBody.code,
           message: errorBody.message,
           details: errorBody.details,
-          requestId
+          requestId: serverRequestId || requestId
         });
       }
       if (response.status === 204) {
@@ -1094,8 +1138,12 @@ var OptropicClient = class {
       }
       if (error instanceof Error) {
         if (error.name === "AbortError") {
+          const durationMs2 = performance.now() - t0;
+          this.logResponse(method, path, 408, durationMs2, requestId, "", attempt);
           throw new TimeoutError(timeout);
         }
+        const durationMs = performance.now() - t0;
+        this.logResponse(method, path, 0, durationMs, requestId, "", attempt);
         throw new NetworkError(error.message, { cause: error });
       }
       throw new OptropicError("UNKNOWN_ERROR", "An unexpected error occurred", {
@@ -1354,7 +1402,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.2.0";
+var SDK_VERSION2 = "2.3.0";
 export {
   AssetsResource,
   AuditResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optropic",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Official Optropic SDK for TypeScript and JavaScript",
   "type": "module",
   "main": "./dist/index.js",