optropic 2.2.0 → 2.4.0

package/dist/index.cjs

@@ -45,6 +45,7 @@ __export(index_exports, {
   NetworkError: () => NetworkError,
   OptropicClient: () => OptropicClient,
   OptropicError: () => OptropicError,
+  Permission: () => Permission,
   ProvenanceResource: () => ProvenanceResource,
   QuotaExceededError: () => QuotaExceededError,
   RateLimitedError: () => RateLimitedError,
@@ -512,6 +513,20 @@ var AssetsResource = class {
   async batchCreate(params) {
     return this.request({ method: "POST", path: "/v1/assets/batch", body: params });
   }
+  async batchVerify(assetIds) {
+    return this.request({
+      method: "POST",
+      path: "/v1/assets/batch-verify",
+      body: { asset_ids: assetIds }
+    });
+  }
+  async batchRevoke(assetIds, reason) {
+    return this.request({
+      method: "POST",
+      path: "/v1/assets/batch-revoke",
+      body: { asset_ids: assetIds, reason }
+    });
+  }
   buildQuery(params) {
     const entries = Object.entries(params).filter(([, v]) => v !== void 0);
     if (entries.length === 0) return "";
@@ -973,18 +988,21 @@ 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.4.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;
+  _rateLimit = null;
   assets;
   audit;
   compliance;
@@ -1003,6 +1021,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 {
@@ -1042,6 +1061,35 @@ var OptropicClient = class {
   get environment() {
     return this._sandbox ? "sandbox" : "live";
   }
+  /** Last known rate limit status, updated after every API call. Returns null until the first request. */
+  get rateLimit() {
+    return this._rateLimit;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // 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
   // ─────────────────────────────────────────────────────────────────────────
@@ -1051,20 +1099,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 +1128,10 @@ var OptropicClient = class {
           method,
           requestHeaders,
           body,
-          timeout
+          timeout,
+          requestId,
+          path,
+          attempt
         );
         return response;
       } catch (error) {
@@ -1092,8 +1149,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 +1162,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 +1174,18 @@ 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);
+      const rlLimit = response.headers.get("x-ratelimit-limit");
+      const rlRemaining = response.headers.get("x-ratelimit-remaining");
+      if (rlLimit !== null || rlRemaining !== null) {
+        this._rateLimit = {
+          limit: rlLimit ? parseInt(rlLimit, 10) : 0,
+          remaining: rlRemaining ? parseInt(rlRemaining, 10) : 0,
+          reset: response.headers.get("x-ratelimit-reset") ?? void 0
+        };
+      }
       if (!response.ok) {
         let errorBody;
         try {
@@ -1135,7 +1208,7 @@ var OptropicClient = class {
           code: errorBody.code,
           message: errorBody.message,
           details: errorBody.details,
-          requestId
+          requestId: serverRequestId || requestId
         });
       }
       if (response.status === 204) {
@@ -1161,8 +1234,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", {
@@ -1178,6 +1255,39 @@ function createClient(config) {
   return new OptropicClient(config);
 }
 
+// src/types.ts
+var Permission = {
+  ASSETS_READ: "assets:read",
+  ASSETS_WRITE: "assets:write",
+  ASSETS_VERIFY: "assets:verify",
+  AUDIT_READ: "audit:read",
+  COMPLIANCE_READ: "compliance:read",
+  KEYS_MANAGE: "keys:manage",
+  SCHEMAS_MANAGE: "schemas:manage",
+  DOCUMENTS_ENROLL: "documents:enroll",
+  DOCUMENTS_VERIFY: "documents:verify",
+  PROVENANCE_READ: "provenance:read",
+  PROVENANCE_WRITE: "provenance:write",
+  WEBHOOKS_MANAGE: "webhooks:manage",
+  /** All read permissions. */
+  ALL_READ: ["assets:read", "audit:read", "compliance:read", "provenance:read"],
+  /** All write permissions. */
+  ALL_WRITE: [
+    "assets:write",
+    "assets:verify",
+    "documents:enroll",
+    "documents:verify",
+    "provenance:write",
+    "webhooks:manage",
+    "keys:manage",
+    "schemas:manage"
+  ],
+  /** All permissions combined. */
+  all() {
+    return [...this.ALL_READ, ...this.ALL_WRITE];
+  }
+};
+
 // src/filter-verify.ts
 var HEADER_SIZE = 19;
 var SIGNATURE_SIZE = 64;
@@ -1421,7 +1531,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.2.0";
+var SDK_VERSION2 = "2.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetsResource,
@@ -1439,6 +1549,7 @@ var SDK_VERSION2 = "2.2.0";
   NetworkError,
   OptropicClient,
   OptropicError,
+  Permission,
   ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,

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.
@@ -71,6 +77,53 @@ interface RetryConfig {
  * Use these for programmatic error handling.
  */
 type ErrorCode = 'INVALID_API_KEY' | 'EXPIRED_API_KEY' | 'INSUFFICIENT_PERMISSIONS' | 'INVALID_GTIN' | 'INVALID_SERIAL' | 'INVALID_CODE_FORMAT' | 'INVALID_BATCH_CONFIG' | 'CODE_NOT_FOUND' | 'BATCH_NOT_FOUND' | 'PRODUCT_NOT_FOUND' | 'CODE_REVOKED' | 'CODE_EXPIRED' | 'BATCH_ALREADY_EXISTS' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVICE_UNAVAILABLE' | 'INTERNAL_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Type-safe permission constants for API key creation.
+ *
+ * @example
+ * ```typescript
+ * import { Permission } from 'optropic';
+ *
+ * const key = await client.keys.create({
+ *   environment: 'live',
+ *   label: 'Read-only integration',
+ *   permissions: [Permission.ASSETS_READ, Permission.ASSETS_VERIFY],
+ * });
+ * ```
+ */
+declare const Permission: {
+    readonly ASSETS_READ: "assets:read";
+    readonly ASSETS_WRITE: "assets:write";
+    readonly ASSETS_VERIFY: "assets:verify";
+    readonly AUDIT_READ: "audit:read";
+    readonly COMPLIANCE_READ: "compliance:read";
+    readonly KEYS_MANAGE: "keys:manage";
+    readonly SCHEMAS_MANAGE: "schemas:manage";
+    readonly DOCUMENTS_ENROLL: "documents:enroll";
+    readonly DOCUMENTS_VERIFY: "documents:verify";
+    readonly PROVENANCE_READ: "provenance:read";
+    readonly PROVENANCE_WRITE: "provenance:write";
+    readonly WEBHOOKS_MANAGE: "webhooks:manage";
+    /** All read permissions. */
+    readonly ALL_READ: readonly ["assets:read", "audit:read", "compliance:read", "provenance:read"];
+    /** All write permissions. */
+    readonly ALL_WRITE: readonly ["assets:write", "assets:verify", "documents:enroll", "documents:verify", "provenance:write", "webhooks:manage", "keys:manage", "schemas:manage"];
+    /** All permissions combined. */
+    readonly all: () => string[];
+};
+type PermissionValue = typeof Permission[keyof Omit<typeof Permission, 'ALL_READ' | 'ALL_WRITE' | 'all'>];
+/**
+ * Rate limit status parsed from response headers.
+ * Updated automatically after every API call.
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed per period. */
+    readonly limit: number;
+    /** Remaining requests in current period. */
+    readonly remaining: number;
+    /** ISO 8601 timestamp when the limit resets. */
+    readonly reset?: string;
+}
 
 /**
  * Assets Resource
@@ -146,6 +199,31 @@ interface BatchCreateResult {
     readonly requested: number;
     readonly assets: Asset[];
 }
+interface BatchVerifyResult {
+    readonly verified: number;
+    readonly requested: number;
+    readonly results: Array<{
+        readonly assetId: string;
+        readonly signatureValid: boolean;
+        readonly revocationStatus: string;
+    }>;
+    readonly errors?: Array<{
+        readonly assetId: string;
+        readonly error: string;
+    }>;
+}
+interface BatchRevokeResult {
+    readonly revoked: number;
+    readonly requested: number;
+    readonly results: Array<{
+        readonly assetId: string;
+        readonly status: string;
+    }>;
+    readonly errors?: Array<{
+        readonly assetId: string;
+        readonly error: string;
+    }>;
+}
 declare class AssetsResource {
     private readonly request;
     private readonly client;
@@ -175,6 +253,8 @@ declare class AssetsResource {
     verify(assetId: string): Promise<VerifyResult>;
     revoke(assetId: string, reason?: string): Promise<Asset>;
     batchCreate(params: BatchCreateParams): Promise<BatchCreateResult>;
+    batchVerify(assetIds: string[]): Promise<BatchVerifyResult>;
+    batchRevoke(assetIds: string[], reason: string): Promise<BatchRevokeResult>;
     private buildQuery;
 }
 
@@ -718,6 +798,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 +813,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 +822,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 +831,8 @@ declare class OptropicClient {
     private readonly baseUrl;
     private readonly retryConfig;
     private readonly _sandbox;
+    private readonly _debug;
+    private _rateLimit;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -764,6 +848,12 @@ declare class OptropicClient {
     get isLive(): boolean;
     /** Returns 'sandbox' or 'live'. */
     get environment(): 'sandbox' | 'live';
+    /** Last known rate limit status, updated after every API call. Returns null until the first request. */
+    get rateLimit(): RateLimitInfo | null;
+    private redact;
+    private logRequest;
+    private logResponse;
+    private logRetry;
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -781,6 +871,7 @@ declare class OptropicClient {
  *
  * const client = createClient({
  *   apiKey: process.env.OPTROPIC_API_KEY!,
+ *   debug: true,
  * });
  * ```
  */
@@ -1310,6 +1401,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.2.0";
+declare const SDK_VERSION = "2.4.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 };
+export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatchRevokeResult, type BatchVerifyResult, 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, Permission, type PermissionValue, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, type RateLimitInfo, 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.
@@ -71,6 +77,53 @@ interface RetryConfig {
  * Use these for programmatic error handling.
  */
 type ErrorCode = 'INVALID_API_KEY' | 'EXPIRED_API_KEY' | 'INSUFFICIENT_PERMISSIONS' | 'INVALID_GTIN' | 'INVALID_SERIAL' | 'INVALID_CODE_FORMAT' | 'INVALID_BATCH_CONFIG' | 'CODE_NOT_FOUND' | 'BATCH_NOT_FOUND' | 'PRODUCT_NOT_FOUND' | 'CODE_REVOKED' | 'CODE_EXPIRED' | 'BATCH_ALREADY_EXISTS' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVICE_UNAVAILABLE' | 'INTERNAL_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Type-safe permission constants for API key creation.
+ *
+ * @example
+ * ```typescript
+ * import { Permission } from 'optropic';
+ *
+ * const key = await client.keys.create({
+ *   environment: 'live',
+ *   label: 'Read-only integration',
+ *   permissions: [Permission.ASSETS_READ, Permission.ASSETS_VERIFY],
+ * });
+ * ```
+ */
+declare const Permission: {
+    readonly ASSETS_READ: "assets:read";
+    readonly ASSETS_WRITE: "assets:write";
+    readonly ASSETS_VERIFY: "assets:verify";
+    readonly AUDIT_READ: "audit:read";
+    readonly COMPLIANCE_READ: "compliance:read";
+    readonly KEYS_MANAGE: "keys:manage";
+    readonly SCHEMAS_MANAGE: "schemas:manage";
+    readonly DOCUMENTS_ENROLL: "documents:enroll";
+    readonly DOCUMENTS_VERIFY: "documents:verify";
+    readonly PROVENANCE_READ: "provenance:read";
+    readonly PROVENANCE_WRITE: "provenance:write";
+    readonly WEBHOOKS_MANAGE: "webhooks:manage";
+    /** All read permissions. */
+    readonly ALL_READ: readonly ["assets:read", "audit:read", "compliance:read", "provenance:read"];
+    /** All write permissions. */
+    readonly ALL_WRITE: readonly ["assets:write", "assets:verify", "documents:enroll", "documents:verify", "provenance:write", "webhooks:manage", "keys:manage", "schemas:manage"];
+    /** All permissions combined. */
+    readonly all: () => string[];
+};
+type PermissionValue = typeof Permission[keyof Omit<typeof Permission, 'ALL_READ' | 'ALL_WRITE' | 'all'>];
+/**
+ * Rate limit status parsed from response headers.
+ * Updated automatically after every API call.
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed per period. */
+    readonly limit: number;
+    /** Remaining requests in current period. */
+    readonly remaining: number;
+    /** ISO 8601 timestamp when the limit resets. */
+    readonly reset?: string;
+}
 
 /**
  * Assets Resource
@@ -146,6 +199,31 @@ interface BatchCreateResult {
     readonly requested: number;
     readonly assets: Asset[];
 }
+interface BatchVerifyResult {
+    readonly verified: number;
+    readonly requested: number;
+    readonly results: Array<{
+        readonly assetId: string;
+        readonly signatureValid: boolean;
+        readonly revocationStatus: string;
+    }>;
+    readonly errors?: Array<{
+        readonly assetId: string;
+        readonly error: string;
+    }>;
+}
+interface BatchRevokeResult {
+    readonly revoked: number;
+    readonly requested: number;
+    readonly results: Array<{
+        readonly assetId: string;
+        readonly status: string;
+    }>;
+    readonly errors?: Array<{
+        readonly assetId: string;
+        readonly error: string;
+    }>;
+}
 declare class AssetsResource {
     private readonly request;
     private readonly client;
@@ -175,6 +253,8 @@ declare class AssetsResource {
     verify(assetId: string): Promise<VerifyResult>;
     revoke(assetId: string, reason?: string): Promise<Asset>;
     batchCreate(params: BatchCreateParams): Promise<BatchCreateResult>;
+    batchVerify(assetIds: string[]): Promise<BatchVerifyResult>;
+    batchRevoke(assetIds: string[], reason: string): Promise<BatchRevokeResult>;
     private buildQuery;
 }
 
@@ -718,6 +798,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 +813,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 +822,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 +831,8 @@ declare class OptropicClient {
     private readonly baseUrl;
     private readonly retryConfig;
     private readonly _sandbox;
+    private readonly _debug;
+    private _rateLimit;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -764,6 +848,12 @@ declare class OptropicClient {
     get isLive(): boolean;
     /** Returns 'sandbox' or 'live'. */
     get environment(): 'sandbox' | 'live';
+    /** Last known rate limit status, updated after every API call. Returns null until the first request. */
+    get rateLimit(): RateLimitInfo | null;
+    private redact;
+    private logRequest;
+    private logResponse;
+    private logRetry;
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -781,6 +871,7 @@ declare class OptropicClient {
  *
  * const client = createClient({
  *   apiKey: process.env.OPTROPIC_API_KEY!,
+ *   debug: true,
  * });
  * ```
  */
@@ -1310,6 +1401,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.2.0";
+declare const SDK_VERSION = "2.4.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 };
+export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatchRevokeResult, type BatchVerifyResult, 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, Permission, type PermissionValue, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, type RateLimitInfo, 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

@@ -445,6 +445,20 @@ var AssetsResource = class {
   async batchCreate(params) {
     return this.request({ method: "POST", path: "/v1/assets/batch", body: params });
   }
+  async batchVerify(assetIds) {
+    return this.request({
+      method: "POST",
+      path: "/v1/assets/batch-verify",
+      body: { asset_ids: assetIds }
+    });
+  }
+  async batchRevoke(assetIds, reason) {
+    return this.request({
+      method: "POST",
+      path: "/v1/assets/batch-revoke",
+      body: { asset_ids: assetIds, reason }
+    });
+  }
   buildQuery(params) {
     const entries = Object.entries(params).filter(([, v]) => v !== void 0);
     if (entries.length === 0) return "";
@@ -906,18 +920,21 @@ 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.4.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;
+  _rateLimit = null;
   assets;
   audit;
   compliance;
@@ -936,6 +953,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 {
@@ -975,6 +993,35 @@ var OptropicClient = class {
   get environment() {
     return this._sandbox ? "sandbox" : "live";
   }
+  /** Last known rate limit status, updated after every API call. Returns null until the first request. */
+  get rateLimit() {
+    return this._rateLimit;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // 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
   // ─────────────────────────────────────────────────────────────────────────
@@ -984,20 +1031,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 +1060,10 @@ var OptropicClient = class {
           method,
           requestHeaders,
           body,
-          timeout
+          timeout,
+          requestId,
+          path,
+          attempt
         );
         return response;
       } catch (error) {
@@ -1025,8 +1081,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 +1094,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 +1106,18 @@ 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);
+      const rlLimit = response.headers.get("x-ratelimit-limit");
+      const rlRemaining = response.headers.get("x-ratelimit-remaining");
+      if (rlLimit !== null || rlRemaining !== null) {
+        this._rateLimit = {
+          limit: rlLimit ? parseInt(rlLimit, 10) : 0,
+          remaining: rlRemaining ? parseInt(rlRemaining, 10) : 0,
+          reset: response.headers.get("x-ratelimit-reset") ?? void 0
+        };
+      }
       if (!response.ok) {
         let errorBody;
         try {
@@ -1068,7 +1140,7 @@ var OptropicClient = class {
           code: errorBody.code,
           message: errorBody.message,
           details: errorBody.details,
-          requestId
+          requestId: serverRequestId || requestId
         });
       }
       if (response.status === 204) {
@@ -1094,8 +1166,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", {
@@ -1111,6 +1187,39 @@ function createClient(config) {
   return new OptropicClient(config);
 }
 
+// src/types.ts
+var Permission = {
+  ASSETS_READ: "assets:read",
+  ASSETS_WRITE: "assets:write",
+  ASSETS_VERIFY: "assets:verify",
+  AUDIT_READ: "audit:read",
+  COMPLIANCE_READ: "compliance:read",
+  KEYS_MANAGE: "keys:manage",
+  SCHEMAS_MANAGE: "schemas:manage",
+  DOCUMENTS_ENROLL: "documents:enroll",
+  DOCUMENTS_VERIFY: "documents:verify",
+  PROVENANCE_READ: "provenance:read",
+  PROVENANCE_WRITE: "provenance:write",
+  WEBHOOKS_MANAGE: "webhooks:manage",
+  /** All read permissions. */
+  ALL_READ: ["assets:read", "audit:read", "compliance:read", "provenance:read"],
+  /** All write permissions. */
+  ALL_WRITE: [
+    "assets:write",
+    "assets:verify",
+    "documents:enroll",
+    "documents:verify",
+    "provenance:write",
+    "webhooks:manage",
+    "keys:manage",
+    "schemas:manage"
+  ],
+  /** All permissions combined. */
+  all() {
+    return [...this.ALL_READ, ...this.ALL_WRITE];
+  }
+};
+
 // src/filter-verify.ts
 var HEADER_SIZE = 19;
 var SIGNATURE_SIZE = 64;
@@ -1354,7 +1463,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.2.0";
+var SDK_VERSION2 = "2.4.0";
 export {
   AssetsResource,
   AuditResource,
@@ -1371,6 +1480,7 @@ export {
   NetworkError,
   OptropicClient,
   OptropicError,
+  Permission,
   ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,

package/package.json

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