optropic 1.0.0 → 2.0.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -28,6 +38,7 @@ __export(index_exports, {
   InvalidGTINError: () => InvalidGTINError,
   InvalidSerialError: () => InvalidSerialError,
   KeysResource: () => KeysResource,
+  KeysetsResource: () => KeysetsResource,
   NetworkError: () => NetworkError,
   OptropicClient: () => OptropicClient,
   OptropicError: () => OptropicError,
@@ -37,7 +48,8 @@ __export(index_exports, {
   SDK_VERSION: () => SDK_VERSION2,
   ServiceUnavailableError: () => ServiceUnavailableError,
   TimeoutError: () => TimeoutError,
-  createClient: () => createClient
+  createClient: () => createClient,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -425,14 +437,26 @@ function createErrorFromResponse(statusCode, body) {
 
 // src/resources/assets.ts
 var AssetsResource = class {
-  constructor(request) {
+  constructor(request, client) {
     this.request = request;
+    this.client = client;
   }
   async create(params) {
     return this.request({ method: "POST", path: "/v1/assets", body: params });
   }
+  /**
+   * List assets with optional filtering and pagination.
+   *
+   * When the client uses a sandbox/test API key, `is_sandbox` is
+   * automatically set to `true` so sandbox clients only see sandbox
+   * assets. Pass an explicit `is_sandbox` value to override.
+   */
   async list(params) {
-    const query = params ? this.buildQuery(params) : "";
+    let effectiveParams = params;
+    if (this.client.isSandbox && (!params || params.is_sandbox === void 0)) {
+      effectiveParams = { ...params, is_sandbox: true };
+    }
+    const query = effectiveParams ? this.buildQuery(effectiveParams) : "";
     return this.request({ method: "GET", path: `/v1/assets${query}` });
   }
   async get(assetId) {
@@ -467,17 +491,38 @@ var KeysResource = class {
     return this.request({ method: "POST", path: "/v1/keys", body: params });
   }
   async list() {
-    return this.request({ method: "GET", path: "/v1/keys" });
+    const result = await this.request({ method: "GET", path: "/v1/keys" });
+    return result.data;
   }
   async revoke(keyId) {
     await this.request({ method: "DELETE", path: `/v1/keys/${encodeURIComponent(keyId)}` });
   }
 };
 
+// src/resources/keysets.ts
+var KeysetsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  async create(params) {
+    return this.request({ method: "POST", path: "/v1/keysets", body: params });
+  }
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({ method: "GET", path: `/v1/keysets${query}` });
+  }
+  buildQuery(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+    if (entries.length === 0) return "";
+    return "?" + entries.map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`).join("&");
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "2.0.0";
+var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelay: 1e3,
@@ -487,8 +532,10 @@ var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
+  _sandbox;
   assets;
   keys;
+  keysets;
   constructor(config) {
     if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
       throw new AuthenticationError(
@@ -499,6 +546,11 @@ var OptropicClient = class {
       ...config,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
+    if (config.sandbox !== void 0) {
+      this._sandbox = config.sandbox;
+    } else {
+      this._sandbox = SANDBOX_PREFIXES.some((p) => config.apiKey.startsWith(p));
+    }
     if (config.baseUrl) {
       this.baseUrl = config.baseUrl.replace(/\/$/, "");
     } else {
@@ -509,8 +561,24 @@ var OptropicClient = class {
       ...config.retry
     };
     const boundRequest = this.request.bind(this);
-    this.assets = new AssetsResource(boundRequest);
+    this.assets = new AssetsResource(boundRequest, this);
     this.keys = new KeysResource(boundRequest);
+    this.keysets = new KeysetsResource(boundRequest);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // ENVIRONMENT DETECTION
+  // ─────────────────────────────────────────────────────────────────────────
+  /** True when the client is in sandbox mode (test API key or explicit override). */
+  get isSandbox() {
+    return this._sandbox;
+  }
+  /** True when the client is in live/production mode. */
+  get isLive() {
+    return !this._sandbox;
+  }
+  /** Returns 'sandbox' or 'live'. */
+  get environment() {
+    return this._sandbox ? "sandbox" : "live";
   }
   // ─────────────────────────────────────────────────────────────────────────
   // PRIVATE METHODS
@@ -601,18 +669,22 @@ var OptropicClient = class {
           requestId
         });
       }
+      if (response.status === 204) {
+        return void 0;
+      }
       const json = await response.json();
-      if (json.error) {
+      if (json && typeof json === "object" && "error" in json && json.error) {
+        const err = json.error;
         throw createErrorFromResponse(response.status, {
           // Justified: Error code string from API may not match SDK's ErrorCode enum exactly
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          code: json.error.code,
-          message: json.error.message,
-          details: json.error.details,
+          code: err.code ?? "UNKNOWN_ERROR",
+          message: err.message ?? "Unknown error",
+          details: err.details,
           requestId: json.requestId
         });
       }
-      return json.data;
+      return json;
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof OptropicError) {
@@ -637,8 +709,53 @@ function createClient(config) {
   return new OptropicClient(config);
 }
 
+// src/webhooks.ts
+async function computeHmacSha256(secret, message) {
+  const encoder = new TextEncoder();
+  if (typeof globalThis.crypto?.subtle !== "undefined") {
+    const key = await globalThis.crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      // OPSEC: Web Crypto API requires this exact algorithm identifier
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(message));
+    return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const { createHmac } = await import("crypto");
+  return createHmac("sha256", secret).update(message).digest("hex");
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+async function verifyWebhookSignature(options) {
+  const { payload, signature, timestamp, secret, tolerance = 300 } = options;
+  const ts = parseInt(timestamp, 10);
+  if (isNaN(ts)) {
+    return { valid: false, reason: "Invalid timestamp" };
+  }
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - ts);
+  if (age > tolerance) {
+    return { valid: false, reason: `Timestamp too old (${age}s > ${tolerance}s tolerance)` };
+  }
+  const signedPayload = `${timestamp}.${payload}`;
+  const expectedHex = await computeHmacSha256(secret, signedPayload);
+  const expected = `sha256=${expectedHex}`;
+  if (!timingSafeEqual(expected, signature)) {
+    return { valid: false, reason: "Signature mismatch" };
+  }
+  return { valid: true };
+}
+
 // src/index.ts
-var SDK_VERSION2 = "1.0.0";
+var SDK_VERSION2 = "2.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetsResource,
@@ -649,6 +766,7 @@ var SDK_VERSION2 = "1.0.0";
   InvalidGTINError,
   InvalidSerialError,
   KeysResource,
+  KeysetsResource,
   NetworkError,
   OptropicClient,
   OptropicError,
@@ -658,5 +776,6 @@ var SDK_VERSION2 = "1.0.0";
   SDK_VERSION,
   ServiceUnavailableError,
   TimeoutError,
-  createClient
+  createClient,
+  verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -21,6 +21,11 @@ interface OptropicConfig {
      * Format: optr_live_xxx (production) or optr_test_xxx (test)
      */
     readonly apiKey: string;
+    /**
+     * Explicitly set sandbox mode. When omitted, auto-detected from
+     * the API key prefix: `optr_test_*` → sandbox, `optr_live_*` → live.
+     */
+    readonly sandbox?: boolean;
     /**
      * Base URL override (for self-hosted deployments).
      * If not provided, uses Optropic's managed infrastructure.
@@ -67,60 +72,93 @@ interface RetryConfig {
  */
 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';
 
+/**
+ * Assets Resource
+ *
+ * CRUD operations for digitally signed assets.
+ */
+
 interface Asset {
     readonly id: string;
-    readonly short_id: string;
-    readonly gtin: string;
-    readonly serial: string;
+    readonly shortId: string;
+    readonly tenantId: string;
+    readonly keysetId: string;
+    readonly externalId: string | null;
+    readonly vertical: string;
+    readonly securityLevel: 'signed' | 'provenance';
+    readonly assetConfig: Record<string, unknown>;
+    readonly signatureHex: string;
     readonly status: 'active' | 'revoked';
-    readonly security_level: 'signed' | 'provenance';
-    readonly metadata?: Record<string, string>;
-    readonly created_at: string;
-    readonly revoked_at?: string;
+    readonly isSandbox: boolean;
+    readonly verificationCount: number;
+    readonly metadata: Record<string, unknown> | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
 }
 interface CreateAssetParams {
-    readonly gtin: string;
-    readonly serial: string;
-    readonly metadata?: Record<string, string>;
+    readonly keysetId: string;
+    readonly externalId?: string;
+    readonly vertical?: string;
+    readonly securityLevel?: 'signed' | 'provenance';
+    readonly assetConfig?: Record<string, unknown>;
+    readonly metadata?: Record<string, unknown>;
 }
 interface ListAssetsParams {
-    readonly limit?: number;
-    readonly offset?: number;
+    readonly page?: number;
+    readonly per_page?: number;
     readonly status?: 'active' | 'revoked';
-    readonly gtin?: string;
+    readonly vertical?: string;
+    /** Filter by sandbox status. Auto-set when using a test API key. */
+    readonly is_sandbox?: boolean;
+}
+interface ListAssetsResponse {
+    readonly data: Asset[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
 }
 interface VerifyResult {
     readonly id: string;
     readonly status: string;
-    readonly security_level: string;
-    readonly signature_valid: boolean;
-    readonly verification_count: number;
-    readonly last_verified_at: string;
-    readonly revocation_status: 'active' | 'revoked';
-    readonly verification_mode: 'online' | 'offline';
-    readonly provenance_valid?: boolean;
-    readonly evidence?: VerificationEvidence;
-}
-interface VerificationEvidence {
-    readonly signature_valid: boolean;
-    readonly revocation_status: string;
-    readonly verification_mode: string;
-    readonly provenance_valid?: boolean;
-    readonly security_level?: string;
-    readonly verification_count?: number;
+    readonly securityLevel: string;
+    readonly signatureValid: boolean;
+    readonly provenanceValid?: boolean;
+    readonly revocationStatus: 'active' | 'revoked';
+    readonly verificationMode: 'online' | 'offline';
+    readonly verificationCount: number;
+    readonly lastVerifiedAt: string;
 }
 interface BatchCreateParams {
-    readonly assets: CreateAssetParams[];
+    readonly keysetId: string;
+    readonly assets: Array<{
+        readonly externalId?: string;
+        readonly vertical?: string;
+        readonly securityLevel?: 'signed' | 'provenance';
+        readonly assetConfig?: Record<string, unknown>;
+        readonly metadata?: Record<string, unknown>;
+    }>;
 }
 interface BatchCreateResult {
     readonly created: number;
-    readonly asset_ids: string[];
+    readonly requested: number;
+    readonly assets: Asset[];
 }
 declare class AssetsResource {
     private readonly request;
-    constructor(request: RequestFn);
+    private readonly client;
+    constructor(request: RequestFn, client: OptropicClient);
     create(params: CreateAssetParams): Promise<Asset>;
-    list(params?: ListAssetsParams): Promise<Asset[]>;
+    /**
+     * List assets with optional filtering and pagination.
+     *
+     * When the client uses a sandbox/test API key, `is_sandbox` is
+     * automatically set to `true` so sandbox clients only see sandbox
+     * assets. Pass an explicit `is_sandbox` value to override.
+     */
+    list(params?: ListAssetsParams): Promise<ListAssetsResponse>;
     get(assetId: string): Promise<Asset>;
     verify(assetId: string): Promise<VerifyResult>;
     revoke(assetId: string, reason?: string): Promise<Asset>;
@@ -128,21 +166,31 @@ declare class AssetsResource {
     private buildQuery;
 }
 
+/**
+ * Keys Resource
+ *
+ * API key management operations.
+ */
+
 interface ApiKey {
     readonly id: string;
-    readonly name: string;
-    readonly key_prefix: string;
+    readonly label: string;
+    readonly prefix: string;
     readonly environment: string;
-    readonly permissions: string[];
     readonly created_at: string;
     readonly last_used_at?: string;
 }
 interface CreateKeyParams {
-    readonly name?: string;
-    readonly environment?: 'production' | 'test';
+    readonly label?: string;
+    readonly environment?: 'live' | 'test';
 }
-interface CreateKeyResult extends ApiKey {
+interface CreateKeyResult {
     readonly key: string;
+    readonly prefix: string;
+    readonly id: string;
+    readonly label: string;
+    readonly environment: string;
+    readonly created_at: string;
 }
 declare class KeysResource {
     private readonly request;
@@ -152,6 +200,44 @@ declare class KeysResource {
     revoke(keyId: string): Promise<void>;
 }
 
+/**
+ * Keysets Resource
+ *
+ * Signing keyset management operations.
+ */
+
+interface Keyset {
+    readonly id: string;
+    readonly name: string;
+    readonly publicKey: string;
+    readonly tenantId: string;
+    readonly isActive: boolean;
+    readonly createdAt: string;
+}
+interface CreateKeysetParams {
+    readonly name?: string;
+}
+interface ListKeysetsParams {
+    readonly page?: number;
+    readonly per_page?: number;
+}
+interface ListKeysetsResponse {
+    readonly data: Keyset[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+declare class KeysetsResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(params?: CreateKeysetParams): Promise<Keyset>;
+    list(params?: ListKeysetsParams): Promise<ListKeysetsResponse>;
+    private buildQuery;
+}
+
 /**
  * optropic - OptropicClient
  *
@@ -193,9 +279,17 @@ declare class OptropicClient {
     private readonly config;
     private readonly baseUrl;
     private readonly retryConfig;
+    private readonly _sandbox;
     readonly assets: AssetsResource;
     readonly keys: KeysResource;
+    readonly keysets: KeysetsResource;
     constructor(config: OptropicConfig);
+    /** True when the client is in sandbox mode (test API key or explicit override). */
+    get isSandbox(): boolean;
+    /** True when the client is in live/production mode. */
+    get isLive(): boolean;
+    /** Returns 'sandbox' or 'live'. */
+    get environment(): 'sandbox' | 'live';
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -218,6 +312,51 @@ declare class OptropicClient {
  */
 declare function createClient(config: OptropicConfig): OptropicClient;
 
+/**
+ * Webhook Signature Verification
+ *
+ * Verifies that incoming webhook payloads were signed by Optropic.
+ * Uses the endpoint secret provided when the webhook was registered.
+ *
+ * @module optropic/webhooks
+ */
+interface WebhookVerifyOptions {
+    /** Raw request body (string). Must not be parsed JSON. */
+    readonly payload: string;
+    /** Value of the `X-Optropic-Signature` header. Format: `sha256=<hex>` */
+    readonly signature: string;
+    /** Value of the `X-Optropic-Timestamp` header (unix seconds). */
+    readonly timestamp: string;
+    /** The endpoint secret from webhook registration. */
+    readonly secret: string;
+    /** Maximum allowed age of the timestamp in seconds. @default 300 (5 minutes) */
+    readonly tolerance?: number;
+}
+interface WebhookVerifyResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Verify a webhook payload signature.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'optropic';
+ *
+ * const result = await verifyWebhookSignature({
+ *   payload: req.body,          // raw string body
+ *   signature: req.headers['x-optropic-signature'],
+ *   timestamp: req.headers['x-optropic-timestamp'],
+ *   secret: process.env.WEBHOOK_SECRET!,
+ * });
+ *
+ * if (!result.valid) {
+ *   return res.status(401).json({ error: result.reason });
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(options: WebhookVerifyOptions): Promise<WebhookVerifyResult>;
+
 /**
  * optropic - Error Classes
  *
@@ -473,6 +612,6 @@ declare class ServiceUnavailableError extends OptropicError {
     });
 }
 
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "2.0.0";
 
-export { type ApiKey, type Asset, AssetsResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, CodeNotFoundError, type CreateAssetParams, type CreateKeyParams, type CreateKeyResult, type ErrorCode, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type ListAssetsParams, NetworkError, OptropicClient, type OptropicConfig, OptropicError, QuotaExceededError, RateLimitedError, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, ServiceUnavailableError, TimeoutError, type VerificationEvidence, type VerifyResult, createClient };
+export { type ApiKey, type Asset, AssetsResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, CodeNotFoundError, type CreateAssetParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type ErrorCode, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListKeysetsParams, type ListKeysetsResponse, NetworkError, OptropicClient, type OptropicConfig, OptropicError, QuotaExceededError, RateLimitedError, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, ServiceUnavailableError, TimeoutError, type VerifyResult, type WebhookVerifyOptions, type WebhookVerifyResult, createClient, verifyWebhookSignature };

package/dist/index.d.ts

@@ -21,6 +21,11 @@ interface OptropicConfig {
      * Format: optr_live_xxx (production) or optr_test_xxx (test)
      */
     readonly apiKey: string;
+    /**
+     * Explicitly set sandbox mode. When omitted, auto-detected from
+     * the API key prefix: `optr_test_*` → sandbox, `optr_live_*` → live.
+     */
+    readonly sandbox?: boolean;
     /**
      * Base URL override (for self-hosted deployments).
      * If not provided, uses Optropic's managed infrastructure.
@@ -67,60 +72,93 @@ interface RetryConfig {
  */
 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';
 
+/**
+ * Assets Resource
+ *
+ * CRUD operations for digitally signed assets.
+ */
+
 interface Asset {
     readonly id: string;
-    readonly short_id: string;
-    readonly gtin: string;
-    readonly serial: string;
+    readonly shortId: string;
+    readonly tenantId: string;
+    readonly keysetId: string;
+    readonly externalId: string | null;
+    readonly vertical: string;
+    readonly securityLevel: 'signed' | 'provenance';
+    readonly assetConfig: Record<string, unknown>;
+    readonly signatureHex: string;
     readonly status: 'active' | 'revoked';
-    readonly security_level: 'signed' | 'provenance';
-    readonly metadata?: Record<string, string>;
-    readonly created_at: string;
-    readonly revoked_at?: string;
+    readonly isSandbox: boolean;
+    readonly verificationCount: number;
+    readonly metadata: Record<string, unknown> | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
 }
 interface CreateAssetParams {
-    readonly gtin: string;
-    readonly serial: string;
-    readonly metadata?: Record<string, string>;
+    readonly keysetId: string;
+    readonly externalId?: string;
+    readonly vertical?: string;
+    readonly securityLevel?: 'signed' | 'provenance';
+    readonly assetConfig?: Record<string, unknown>;
+    readonly metadata?: Record<string, unknown>;
 }
 interface ListAssetsParams {
-    readonly limit?: number;
-    readonly offset?: number;
+    readonly page?: number;
+    readonly per_page?: number;
     readonly status?: 'active' | 'revoked';
-    readonly gtin?: string;
+    readonly vertical?: string;
+    /** Filter by sandbox status. Auto-set when using a test API key. */
+    readonly is_sandbox?: boolean;
+}
+interface ListAssetsResponse {
+    readonly data: Asset[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
 }
 interface VerifyResult {
     readonly id: string;
     readonly status: string;
-    readonly security_level: string;
-    readonly signature_valid: boolean;
-    readonly verification_count: number;
-    readonly last_verified_at: string;
-    readonly revocation_status: 'active' | 'revoked';
-    readonly verification_mode: 'online' | 'offline';
-    readonly provenance_valid?: boolean;
-    readonly evidence?: VerificationEvidence;
-}
-interface VerificationEvidence {
-    readonly signature_valid: boolean;
-    readonly revocation_status: string;
-    readonly verification_mode: string;
-    readonly provenance_valid?: boolean;
-    readonly security_level?: string;
-    readonly verification_count?: number;
+    readonly securityLevel: string;
+    readonly signatureValid: boolean;
+    readonly provenanceValid?: boolean;
+    readonly revocationStatus: 'active' | 'revoked';
+    readonly verificationMode: 'online' | 'offline';
+    readonly verificationCount: number;
+    readonly lastVerifiedAt: string;
 }
 interface BatchCreateParams {
-    readonly assets: CreateAssetParams[];
+    readonly keysetId: string;
+    readonly assets: Array<{
+        readonly externalId?: string;
+        readonly vertical?: string;
+        readonly securityLevel?: 'signed' | 'provenance';
+        readonly assetConfig?: Record<string, unknown>;
+        readonly metadata?: Record<string, unknown>;
+    }>;
 }
 interface BatchCreateResult {
     readonly created: number;
-    readonly asset_ids: string[];
+    readonly requested: number;
+    readonly assets: Asset[];
 }
 declare class AssetsResource {
     private readonly request;
-    constructor(request: RequestFn);
+    private readonly client;
+    constructor(request: RequestFn, client: OptropicClient);
     create(params: CreateAssetParams): Promise<Asset>;
-    list(params?: ListAssetsParams): Promise<Asset[]>;
+    /**
+     * List assets with optional filtering and pagination.
+     *
+     * When the client uses a sandbox/test API key, `is_sandbox` is
+     * automatically set to `true` so sandbox clients only see sandbox
+     * assets. Pass an explicit `is_sandbox` value to override.
+     */
+    list(params?: ListAssetsParams): Promise<ListAssetsResponse>;
     get(assetId: string): Promise<Asset>;
     verify(assetId: string): Promise<VerifyResult>;
     revoke(assetId: string, reason?: string): Promise<Asset>;
@@ -128,21 +166,31 @@ declare class AssetsResource {
     private buildQuery;
 }
 
+/**
+ * Keys Resource
+ *
+ * API key management operations.
+ */
+
 interface ApiKey {
     readonly id: string;
-    readonly name: string;
-    readonly key_prefix: string;
+    readonly label: string;
+    readonly prefix: string;
     readonly environment: string;
-    readonly permissions: string[];
     readonly created_at: string;
     readonly last_used_at?: string;
 }
 interface CreateKeyParams {
-    readonly name?: string;
-    readonly environment?: 'production' | 'test';
+    readonly label?: string;
+    readonly environment?: 'live' | 'test';
 }
-interface CreateKeyResult extends ApiKey {
+interface CreateKeyResult {
     readonly key: string;
+    readonly prefix: string;
+    readonly id: string;
+    readonly label: string;
+    readonly environment: string;
+    readonly created_at: string;
 }
 declare class KeysResource {
     private readonly request;
@@ -152,6 +200,44 @@ declare class KeysResource {
     revoke(keyId: string): Promise<void>;
 }
 
+/**
+ * Keysets Resource
+ *
+ * Signing keyset management operations.
+ */
+
+interface Keyset {
+    readonly id: string;
+    readonly name: string;
+    readonly publicKey: string;
+    readonly tenantId: string;
+    readonly isActive: boolean;
+    readonly createdAt: string;
+}
+interface CreateKeysetParams {
+    readonly name?: string;
+}
+interface ListKeysetsParams {
+    readonly page?: number;
+    readonly per_page?: number;
+}
+interface ListKeysetsResponse {
+    readonly data: Keyset[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+declare class KeysetsResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(params?: CreateKeysetParams): Promise<Keyset>;
+    list(params?: ListKeysetsParams): Promise<ListKeysetsResponse>;
+    private buildQuery;
+}
+
 /**
  * optropic - OptropicClient
  *
@@ -193,9 +279,17 @@ declare class OptropicClient {
     private readonly config;
     private readonly baseUrl;
     private readonly retryConfig;
+    private readonly _sandbox;
     readonly assets: AssetsResource;
     readonly keys: KeysResource;
+    readonly keysets: KeysetsResource;
     constructor(config: OptropicConfig);
+    /** True when the client is in sandbox mode (test API key or explicit override). */
+    get isSandbox(): boolean;
+    /** True when the client is in live/production mode. */
+    get isLive(): boolean;
+    /** Returns 'sandbox' or 'live'. */
+    get environment(): 'sandbox' | 'live';
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -218,6 +312,51 @@ declare class OptropicClient {
  */
 declare function createClient(config: OptropicConfig): OptropicClient;
 
+/**
+ * Webhook Signature Verification
+ *
+ * Verifies that incoming webhook payloads were signed by Optropic.
+ * Uses the endpoint secret provided when the webhook was registered.
+ *
+ * @module optropic/webhooks
+ */
+interface WebhookVerifyOptions {
+    /** Raw request body (string). Must not be parsed JSON. */
+    readonly payload: string;
+    /** Value of the `X-Optropic-Signature` header. Format: `sha256=<hex>` */
+    readonly signature: string;
+    /** Value of the `X-Optropic-Timestamp` header (unix seconds). */
+    readonly timestamp: string;
+    /** The endpoint secret from webhook registration. */
+    readonly secret: string;
+    /** Maximum allowed age of the timestamp in seconds. @default 300 (5 minutes) */
+    readonly tolerance?: number;
+}
+interface WebhookVerifyResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Verify a webhook payload signature.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'optropic';
+ *
+ * const result = await verifyWebhookSignature({
+ *   payload: req.body,          // raw string body
+ *   signature: req.headers['x-optropic-signature'],
+ *   timestamp: req.headers['x-optropic-timestamp'],
+ *   secret: process.env.WEBHOOK_SECRET!,
+ * });
+ *
+ * if (!result.valid) {
+ *   return res.status(401).json({ error: result.reason });
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(options: WebhookVerifyOptions): Promise<WebhookVerifyResult>;
+
 /**
  * optropic - Error Classes
  *
@@ -473,6 +612,6 @@ declare class ServiceUnavailableError extends OptropicError {
     });
 }
 
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "2.0.0";
 
-export { type ApiKey, type Asset, AssetsResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, CodeNotFoundError, type CreateAssetParams, type CreateKeyParams, type CreateKeyResult, type ErrorCode, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type ListAssetsParams, NetworkError, OptropicClient, type OptropicConfig, OptropicError, QuotaExceededError, RateLimitedError, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, ServiceUnavailableError, TimeoutError, type VerificationEvidence, type VerifyResult, createClient };
+export { type ApiKey, type Asset, AssetsResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, CodeNotFoundError, type CreateAssetParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type ErrorCode, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListKeysetsParams, type ListKeysetsResponse, NetworkError, OptropicClient, type OptropicConfig, OptropicError, QuotaExceededError, RateLimitedError, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, ServiceUnavailableError, TimeoutError, type VerifyResult, type WebhookVerifyOptions, type WebhookVerifyResult, createClient, verifyWebhookSignature };

package/dist/index.js

@@ -382,14 +382,26 @@ function createErrorFromResponse(statusCode, body) {
 
 // src/resources/assets.ts
 var AssetsResource = class {
-  constructor(request) {
+  constructor(request, client) {
     this.request = request;
+    this.client = client;
   }
   async create(params) {
     return this.request({ method: "POST", path: "/v1/assets", body: params });
   }
+  /**
+   * List assets with optional filtering and pagination.
+   *
+   * When the client uses a sandbox/test API key, `is_sandbox` is
+   * automatically set to `true` so sandbox clients only see sandbox
+   * assets. Pass an explicit `is_sandbox` value to override.
+   */
   async list(params) {
-    const query = params ? this.buildQuery(params) : "";
+    let effectiveParams = params;
+    if (this.client.isSandbox && (!params || params.is_sandbox === void 0)) {
+      effectiveParams = { ...params, is_sandbox: true };
+    }
+    const query = effectiveParams ? this.buildQuery(effectiveParams) : "";
     return this.request({ method: "GET", path: `/v1/assets${query}` });
   }
   async get(assetId) {
@@ -424,17 +436,38 @@ var KeysResource = class {
     return this.request({ method: "POST", path: "/v1/keys", body: params });
   }
   async list() {
-    return this.request({ method: "GET", path: "/v1/keys" });
+    const result = await this.request({ method: "GET", path: "/v1/keys" });
+    return result.data;
   }
   async revoke(keyId) {
     await this.request({ method: "DELETE", path: `/v1/keys/${encodeURIComponent(keyId)}` });
   }
 };
 
+// src/resources/keysets.ts
+var KeysetsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  async create(params) {
+    return this.request({ method: "POST", path: "/v1/keysets", body: params });
+  }
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({ method: "GET", path: `/v1/keysets${query}` });
+  }
+  buildQuery(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+    if (entries.length === 0) return "";
+    return "?" + entries.map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`).join("&");
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "2.0.0";
+var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelay: 1e3,
@@ -444,8 +477,10 @@ var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
+  _sandbox;
   assets;
   keys;
+  keysets;
   constructor(config) {
     if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
       throw new AuthenticationError(
@@ -456,6 +491,11 @@ var OptropicClient = class {
       ...config,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
+    if (config.sandbox !== void 0) {
+      this._sandbox = config.sandbox;
+    } else {
+      this._sandbox = SANDBOX_PREFIXES.some((p) => config.apiKey.startsWith(p));
+    }
     if (config.baseUrl) {
       this.baseUrl = config.baseUrl.replace(/\/$/, "");
     } else {
@@ -466,8 +506,24 @@ var OptropicClient = class {
       ...config.retry
     };
     const boundRequest = this.request.bind(this);
-    this.assets = new AssetsResource(boundRequest);
+    this.assets = new AssetsResource(boundRequest, this);
     this.keys = new KeysResource(boundRequest);
+    this.keysets = new KeysetsResource(boundRequest);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // ENVIRONMENT DETECTION
+  // ─────────────────────────────────────────────────────────────────────────
+  /** True when the client is in sandbox mode (test API key or explicit override). */
+  get isSandbox() {
+    return this._sandbox;
+  }
+  /** True when the client is in live/production mode. */
+  get isLive() {
+    return !this._sandbox;
+  }
+  /** Returns 'sandbox' or 'live'. */
+  get environment() {
+    return this._sandbox ? "sandbox" : "live";
   }
   // ─────────────────────────────────────────────────────────────────────────
   // PRIVATE METHODS
@@ -558,18 +614,22 @@ var OptropicClient = class {
           requestId
         });
       }
+      if (response.status === 204) {
+        return void 0;
+      }
       const json = await response.json();
-      if (json.error) {
+      if (json && typeof json === "object" && "error" in json && json.error) {
+        const err = json.error;
         throw createErrorFromResponse(response.status, {
           // Justified: Error code string from API may not match SDK's ErrorCode enum exactly
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          code: json.error.code,
-          message: json.error.message,
-          details: json.error.details,
+          code: err.code ?? "UNKNOWN_ERROR",
+          message: err.message ?? "Unknown error",
+          details: err.details,
           requestId: json.requestId
         });
       }
-      return json.data;
+      return json;
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof OptropicError) {
@@ -594,8 +654,53 @@ function createClient(config) {
   return new OptropicClient(config);
 }
 
+// src/webhooks.ts
+async function computeHmacSha256(secret, message) {
+  const encoder = new TextEncoder();
+  if (typeof globalThis.crypto?.subtle !== "undefined") {
+    const key = await globalThis.crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      // OPSEC: Web Crypto API requires this exact algorithm identifier
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(message));
+    return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const { createHmac } = await import("crypto");
+  return createHmac("sha256", secret).update(message).digest("hex");
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+async function verifyWebhookSignature(options) {
+  const { payload, signature, timestamp, secret, tolerance = 300 } = options;
+  const ts = parseInt(timestamp, 10);
+  if (isNaN(ts)) {
+    return { valid: false, reason: "Invalid timestamp" };
+  }
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - ts);
+  if (age > tolerance) {
+    return { valid: false, reason: `Timestamp too old (${age}s > ${tolerance}s tolerance)` };
+  }
+  const signedPayload = `${timestamp}.${payload}`;
+  const expectedHex = await computeHmacSha256(secret, signedPayload);
+  const expected = `sha256=${expectedHex}`;
+  if (!timingSafeEqual(expected, signature)) {
+    return { valid: false, reason: "Signature mismatch" };
+  }
+  return { valid: true };
+}
+
 // src/index.ts
-var SDK_VERSION2 = "1.0.0";
+var SDK_VERSION2 = "2.0.0";
 export {
   AssetsResource,
   AuthenticationError,
@@ -605,6 +710,7 @@ export {
   InvalidGTINError,
   InvalidSerialError,
   KeysResource,
+  KeysetsResource,
   NetworkError,
   OptropicClient,
   OptropicError,
@@ -614,5 +720,6 @@ export {
   SDK_VERSION2 as SDK_VERSION,
   ServiceUnavailableError,
   TimeoutError,
-  createClient
+  createClient,
+  verifyWebhookSignature
 };

package/package.json

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