optropic 2.3.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,7 +988,7 @@ var SchemasResource = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "2.3.0";
+var SDK_VERSION = "2.4.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
@@ -987,6 +1002,7 @@ var OptropicClient = class {
   retryConfig;
   _sandbox;
   _debug;
+  _rateLimit = null;
   assets;
   audit;
   compliance;
@@ -1045,6 +1061,10 @@ 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
   // ─────────────────────────────────────────────────────────────────────────
@@ -1157,6 +1177,15 @@ var OptropicClient = class {
       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 {
@@ -1226,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;
@@ -1469,7 +1531,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.3.0";
+var SDK_VERSION2 = "2.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetsResource,
@@ -1487,6 +1549,7 @@ var SDK_VERSION2 = "2.3.0";
   NetworkError,
   OptropicClient,
   OptropicError,
+  Permission,
   ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,

package/dist/index.d.cts

@@ -77,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
@@ -152,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;
@@ -181,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;
 }
 
@@ -758,6 +832,7 @@ declare class OptropicClient {
     private readonly retryConfig;
     private readonly _sandbox;
     private readonly _debug;
+    private _rateLimit;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -773,6 +848,8 @@ 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;
@@ -1324,6 +1401,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.3.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

@@ -77,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
@@ -152,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;
@@ -181,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;
 }
 
@@ -758,6 +832,7 @@ declare class OptropicClient {
     private readonly retryConfig;
     private readonly _sandbox;
     private readonly _debug;
+    private _rateLimit;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
@@ -773,6 +848,8 @@ 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;
@@ -1324,6 +1401,6 @@ declare function createErrorFromResponse(statusCode: number, body: {
     requestId?: string;
 }): OptropicError;
 
-declare const SDK_VERSION = "2.3.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,7 +920,7 @@ var SchemasResource = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "2.3.0";
+var SDK_VERSION = "2.4.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
@@ -920,6 +934,7 @@ var OptropicClient = class {
   retryConfig;
   _sandbox;
   _debug;
+  _rateLimit = null;
   assets;
   audit;
   compliance;
@@ -978,6 +993,10 @@ 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
   // ─────────────────────────────────────────────────────────────────────────
@@ -1090,6 +1109,15 @@ var OptropicClient = class {
       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 {
@@ -1159,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;
@@ -1402,7 +1463,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.3.0";
+var SDK_VERSION2 = "2.4.0";
 export {
   AssetsResource,
   AuditResource,
@@ -1419,6 +1480,7 @@ export {
   NetworkError,
   OptropicClient,
   OptropicError,
+  Permission,
   ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,

package/package.json

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