optropic 1.0.0 → 2.1.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,19 +17,30 @@ 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
 var index_exports = {};
 __export(index_exports, {
   AssetsResource: () => AssetsResource,
+  AuditResource: () => AuditResource,
   AuthenticationError: () => AuthenticationError,
   BatchNotFoundError: () => BatchNotFoundError,
   CodeNotFoundError: () => CodeNotFoundError,
+  ComplianceResource: () => ComplianceResource,
   InvalidCodeError: () => InvalidCodeError,
   InvalidGTINError: () => InvalidGTINError,
   InvalidSerialError: () => InvalidSerialError,
   KeysResource: () => KeysResource,
+  KeysetsResource: () => KeysetsResource,
   NetworkError: () => NetworkError,
   OptropicClient: () => OptropicClient,
   OptropicError: () => OptropicError,
@@ -35,9 +48,11 @@ __export(index_exports, {
   RateLimitedError: () => RateLimitedError,
   RevokedCodeError: () => RevokedCodeError,
   SDK_VERSION: () => SDK_VERSION2,
+  SchemasResource: () => SchemasResource,
   ServiceUnavailableError: () => ServiceUnavailableError,
   TimeoutError: () => TimeoutError,
-  createClient: () => createClient
+  createClient: () => createClient,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -425,14 +440,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) {
@@ -458,6 +485,117 @@ var AssetsResource = class {
   }
 };
 
+// src/resources/audit.ts
+var AuditResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * List audit events with optional filtering and pagination.
+   */
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({ method: "GET", path: `/v1/audit${query}` });
+  }
+  /**
+   * Retrieve a single audit event by ID.
+   */
+  async get(eventId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/audit/${encodeURIComponent(eventId)}`
+    });
+  }
+  /**
+   * Record a custom audit event.
+   */
+  async create(params) {
+    return this.request({
+      method: "POST",
+      path: "/v1/audit",
+      body: {
+        event_type: params.eventType,
+        ...params.resourceId !== void 0 && { resource_id: params.resourceId },
+        ...params.resourceType !== void 0 && { resource_type: params.resourceType },
+        ...params.details !== void 0 && { details: params.details }
+      }
+    });
+  }
+  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/resources/compliance.ts
+var ComplianceResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Verify the integrity of the full audit chain.
+   */
+  async verifyChain() {
+    return this.request({
+      method: "POST",
+      path: "/v1/compliance/verify-chain"
+    });
+  }
+  /**
+   * Return all Merkle roots.
+   */
+  async listMerkleRoots() {
+    return this.request({
+      method: "GET",
+      path: "/v1/compliance/merkle-roots"
+    });
+  }
+  /**
+   * Return a Merkle inclusion proof for a specific audit event.
+   */
+  async getMerkleProof(eventId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/compliance/merkle-proof/${encodeURIComponent(eventId)}`
+    });
+  }
+  /**
+   * Export audit data as a signed CSV.
+   */
+  async exportAudit(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({
+      method: "GET",
+      path: `/v1/compliance/export${query}`
+    });
+  }
+  /**
+   * Retrieve the current compliance configuration.
+   */
+  async getConfig() {
+    return this.request({
+      method: "GET",
+      path: "/v1/compliance/config"
+    });
+  }
+  /**
+   * Update the compliance mode.
+   */
+  async updateConfig(mode) {
+    return this.request({
+      method: "POST",
+      path: "/v1/compliance/config",
+      body: { compliance_mode: mode }
+    });
+  }
+  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/resources/keys.ts
 var KeysResource = class {
   constructor(request) {
@@ -467,17 +605,162 @@ 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/resources/schemas.ts
+function checkType(value, expected) {
+  switch (expected) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && !Number.isNaN(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "date":
+      return typeof value === "string";
+    // ISO 8601 string
+    case "array":
+      return Array.isArray(value);
+    default:
+      return true;
+  }
+}
+var SchemasResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Register or update a vertical config schema.
+   * If a schema already exists for the verticalId, it will be updated.
+   */
+  async create(params) {
+    const body = this.stripUndefined({
+      vertical_id: params.verticalId,
+      metadata_schema: params.metadataSchema,
+      version: params.version,
+      export_formats: params.exportFormats,
+      description: params.description
+    });
+    return this.request({ method: "POST", path: "/v1/schemas", body });
+  }
+  /**
+   * List registered vertical schemas with pagination.
+   */
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({ method: "GET", path: `/v1/schemas${query}` });
+  }
+  /**
+   * Get the active schema for a specific vertical.
+   */
+  async get(verticalId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/schemas/${encodeURIComponent(verticalId)}`
+    });
+  }
+  /**
+   * Update an existing vertical schema.
+   */
+  async update(verticalId, params) {
+    const body = this.stripUndefined({
+      version: params.version,
+      metadata_schema: params.metadataSchema,
+      export_formats: params.exportFormats,
+      description: params.description,
+      is_active: params.isActive
+    });
+    return this.request({
+      method: "PUT",
+      path: `/v1/schemas/${encodeURIComponent(verticalId)}`,
+      body
+    });
+  }
+  /**
+   * Deactivate a vertical schema (soft delete).
+   */
+  async delete(verticalId) {
+    await this.request({
+      method: "DELETE",
+      path: `/v1/schemas/${encodeURIComponent(verticalId)}`
+    });
+  }
+  /**
+   * Pre-flight validation: check if assetConfig matches the registered schema.
+   *
+   * This is a client-side convenience that fetches the schema and validates locally.
+   * The server also validates on asset creation.
+   */
+  async validate(verticalId, assetConfig) {
+    let schema;
+    try {
+      schema = await this.get(verticalId);
+    } catch {
+      return { valid: true, errors: [] };
+    }
+    const errors = [];
+    const metadataSchema = schema.metadataSchema ?? {};
+    for (const [fieldName, fieldDef] of Object.entries(metadataSchema)) {
+      if (typeof fieldDef !== "object" || fieldDef === null) continue;
+      const def = fieldDef;
+      const value = assetConfig[fieldName];
+      if (def.required && (value === void 0 || value === null || value === "")) {
+        const label = def.label ?? fieldName;
+        errors.push({ field: fieldName, message: `Required field "${label}" is missing` });
+        continue;
+      }
+      if (value === void 0 || value === null) continue;
+      const expectedType = def.type ?? "string";
+      if (!checkType(value, expectedType)) {
+        errors.push({
+          field: fieldName,
+          message: `"${def.label ?? fieldName}" must be a ${expectedType}`,
+          received: typeof value
+        });
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  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("&");
+  }
+  stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+  }
+};
+
 // 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 +770,13 @@ var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
+  _sandbox;
   assets;
+  audit;
+  compliance;
   keys;
+  keysets;
+  schemas;
   constructor(config) {
     if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
       throw new AuthenticationError(
@@ -499,6 +787,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 +802,27 @@ var OptropicClient = class {
       ...config.retry
     };
     const boundRequest = this.request.bind(this);
-    this.assets = new AssetsResource(boundRequest);
+    this.assets = new AssetsResource(boundRequest, this);
+    this.audit = new AuditResource(boundRequest);
+    this.compliance = new ComplianceResource(boundRequest);
     this.keys = new KeysResource(boundRequest);
+    this.keysets = new KeysetsResource(boundRequest);
+    this.schemas = new SchemasResource(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 +913,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,18 +953,66 @@ 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,
+  AuditResource,
   AuthenticationError,
   BatchNotFoundError,
   CodeNotFoundError,
+  ComplianceResource,
   InvalidCodeError,
   InvalidGTINError,
   InvalidSerialError,
   KeysResource,
+  KeysetsResource,
   NetworkError,
   OptropicClient,
   OptropicError,
@@ -656,7 +1020,9 @@ var SDK_VERSION2 = "1.0.0";
   RateLimitedError,
   RevokedCodeError,
   SDK_VERSION,
+  SchemasResource,
   ServiceUnavailableError,
   TimeoutError,
-  createClient
+  createClient,
+  verifyWebhookSignature
 });