optropic 2.1.0 → 2.2.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   BatchNotFoundError: () => BatchNotFoundError,
   CodeNotFoundError: () => CodeNotFoundError,
   ComplianceResource: () => ComplianceResource,
+  DocumentsResource: () => DocumentsResource,
   InvalidCodeError: () => InvalidCodeError,
   InvalidGTINError: () => InvalidGTINError,
   InvalidSerialError: () => InvalidSerialError,
@@ -44,14 +45,22 @@ __export(index_exports, {
   NetworkError: () => NetworkError,
   OptropicClient: () => OptropicClient,
   OptropicError: () => OptropicError,
+  ProvenanceResource: () => ProvenanceResource,
   QuotaExceededError: () => QuotaExceededError,
   RateLimitedError: () => RateLimitedError,
   RevokedCodeError: () => RevokedCodeError,
   SDK_VERSION: () => SDK_VERSION2,
   SchemasResource: () => SchemasResource,
   ServiceUnavailableError: () => ServiceUnavailableError,
+  StaleFilterError: () => StaleFilterError,
   TimeoutError: () => TimeoutError,
+  buildDPPConfig: () => buildDPPConfig,
   createClient: () => createClient,
+  createErrorFromResponse: () => createErrorFromResponse,
+  parseFilterHeader: () => parseFilterHeader,
+  parseSaltsHeader: () => parseSaltsHeader,
+  validateDPPMetadata: () => validateDPPMetadata,
+  verifyOffline: () => verifyOffline,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -462,6 +471,31 @@ var AssetsResource = class {
     const query = effectiveParams ? this.buildQuery(effectiveParams) : "";
     return this.request({ method: "GET", path: `/v1/assets${query}` });
   }
+  /**
+   * Auto-paginate through all assets, yielding pages of results.
+   * Returns an async generator that fetches pages on demand.
+   *
+   * @example
+   * ```typescript
+   * for await (const asset of client.assets.listAll({ status: 'active' })) {
+   *   console.log(asset.id);
+   * }
+   * ```
+   */
+  async *listAll(params) {
+    let page = params?.page ?? 1;
+    const perPage = params?.per_page ?? 100;
+    while (true) {
+      const response = await this.list({ ...params, page, per_page: perPage });
+      for (const asset of response.data) {
+        yield asset;
+      }
+      if (page >= response.pagination.totalPages || response.data.length === 0) {
+        break;
+      }
+      page++;
+    }
+  }
   async get(assetId) {
     return this.request({ method: "GET", path: `/v1/assets/${encodeURIComponent(assetId)}` });
   }
@@ -596,6 +630,98 @@ var ComplianceResource = class {
   }
 };
 
+// src/resources/documents.ts
+var DocumentsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Enroll a new document (substrate fingerprint) linked to an asset.
+   *
+   * @example
+   * ```typescript
+   * const doc = await client.documents.enroll({
+   *   assetId: 'asset-123',
+   *   fingerprintHash: 'sha256:abc123...',
+   *   descriptorVersion: 'GB_GE_M7PCA_v1',
+   *   substrateType: 'S_fb',
+   *   captureDevice: 'iPhone16ProMax_main',
+   * });
+   * ```
+   */
+  async enroll(params) {
+    return this.request({
+      method: "POST",
+      path: "/v1/documents",
+      body: {
+        asset_id: params.assetId,
+        fingerprint_hash: params.fingerprintHash,
+        descriptor_version: params.descriptorVersion,
+        substrate_type: params.substrateType,
+        ...params.captureDevice !== void 0 && { capture_device: params.captureDevice },
+        ...params.metadata !== void 0 && { metadata: params.metadata }
+      }
+    });
+  }
+  /**
+   * Verify a fingerprint against enrolled documents.
+   *
+   * Returns the best match if similarity exceeds the threshold.
+   */
+  async verify(params) {
+    return this.request({
+      method: "POST",
+      path: "/v1/documents/verify",
+      body: {
+        fingerprint_hash: params.fingerprintHash,
+        descriptor_version: params.descriptorVersion,
+        ...params.threshold !== void 0 && { threshold: params.threshold }
+      }
+    });
+  }
+  /**
+   * Get a single document by ID.
+   */
+  async get(documentId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/documents/${encodeURIComponent(documentId)}`
+    });
+  }
+  /**
+   * List enrolled documents with optional filtering.
+   */
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({
+      method: "GET",
+      path: `/v1/documents${query}`
+    });
+  }
+  /**
+   * Supersede a document (e.g., re-enrollment with better capture).
+   */
+  async supersede(documentId, newDocumentId) {
+    return this.request({
+      method: "POST",
+      path: `/v1/documents/${encodeURIComponent(documentId)}/supersede`,
+      body: { new_document_id: newDocumentId }
+    });
+  }
+  buildQuery(params) {
+    const mapped = {
+      asset_id: params.assetId,
+      substrate_type: params.substrateType,
+      status: params.status,
+      page: params.page,
+      per_page: params.per_page
+    };
+    const entries = Object.entries(mapped).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) {
@@ -632,6 +758,94 @@ var KeysetsResource = class {
   }
 };
 
+// src/resources/provenance.ts
+var ProvenanceResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Record a new provenance event in the chain.
+   *
+   * Events are automatically chained — the server links each new event
+   * to the previous one via cryptographic hash.
+   *
+   * @example
+   * ```typescript
+   * const event = await client.provenance.record({
+   *   assetId: 'asset-123',
+   *   eventType: 'manufactured',
+   *   actor: 'factory-line-7',
+   *   location: { country: 'DE', facility: 'Munich Plant' },
+   * });
+   * ```
+   */
+  async record(params) {
+    return this.request({
+      method: "POST",
+      path: "/v1/provenance",
+      body: {
+        asset_id: params.assetId,
+        event_type: params.eventType,
+        actor: params.actor,
+        ...params.location !== void 0 && { location: params.location },
+        ...params.metadata !== void 0 && { metadata: params.metadata }
+      }
+    });
+  }
+  /**
+   * Get the full provenance chain for an asset.
+   */
+  async getChain(assetId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/provenance/chain/${encodeURIComponent(assetId)}`
+    });
+  }
+  /**
+   * Get a single provenance event by ID.
+   */
+  async get(eventId) {
+    return this.request({
+      method: "GET",
+      path: `/v1/provenance/${encodeURIComponent(eventId)}`
+    });
+  }
+  /**
+   * List provenance events with optional filtering.
+   */
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({
+      method: "GET",
+      path: `/v1/provenance${query}`
+    });
+  }
+  /**
+   * Verify the integrity of an asset's provenance chain.
+   *
+   * Checks that all events are correctly linked via cryptographic hashes.
+   */
+  async verifyChain(assetId) {
+    return this.request({
+      method: "POST",
+      path: `/v1/provenance/chain/${encodeURIComponent(assetId)}/verify`
+    });
+  }
+  buildQuery(params) {
+    const mapped = {
+      asset_id: params.assetId,
+      event_type: params.eventType,
+      from_date: params.from_date,
+      to_date: params.to_date,
+      page: params.page,
+      per_page: params.per_page
+    };
+    const entries = Object.entries(mapped).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) {
@@ -759,7 +973,7 @@ var SchemasResource = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.optropic.com";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.2.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
@@ -774,8 +988,10 @@ var OptropicClient = class {
   assets;
   audit;
   compliance;
+  documents;
   keys;
   keysets;
+  provenance;
   schemas;
   constructor(config) {
     if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
@@ -805,8 +1021,10 @@ var OptropicClient = class {
     this.assets = new AssetsResource(boundRequest, this);
     this.audit = new AuditResource(boundRequest);
     this.compliance = new ComplianceResource(boundRequest);
+    this.documents = new DocumentsResource(boundRequest);
     this.keys = new KeysResource(boundRequest);
     this.keysets = new KeysetsResource(boundRequest);
+    this.provenance = new ProvenanceResource(boundRequest);
     this.schemas = new SchemasResource(boundRequest);
   }
   // ─────────────────────────────────────────────────────────────────────────
@@ -831,7 +1049,7 @@ var OptropicClient = class {
     return /^optr_(live|test)_[a-zA-Z0-9_-]{20,}$/.test(apiKey);
   }
   async request(options) {
-    const { method, path, body, headers = {}, timeout = this.config.timeout } = options;
+    const { method, path, body, headers = {}, timeout = this.config.timeout, idempotencyKey } = options;
     const url = `${this.baseUrl}${path}`;
     const requestHeaders = {
       "Content-Type": "application/json",
@@ -842,6 +1060,11 @@ var OptropicClient = class {
       ...this.config.headers,
       ...headers
     };
+    if (idempotencyKey) {
+      requestHeaders["Idempotency-Key"] = idempotencyKey;
+    } else if (["POST", "PUT", "PATCH"].includes(method)) {
+      requestHeaders["Idempotency-Key"] = crypto.randomUUID();
+    }
     let lastError = null;
     let attempt = 0;
     while (attempt <= this.retryConfig.maxRetries) {
@@ -862,10 +1085,12 @@ var OptropicClient = class {
         if (attempt >= this.retryConfig.maxRetries) {
           throw error;
         }
-        const delay = Math.min(
+        const baseDelay = Math.min(
           this.retryConfig.baseDelay * Math.pow(2, attempt),
           this.retryConfig.maxDelay
         );
+        const jitter = baseDelay * 0.5 * Math.random();
+        const delay = baseDelay + jitter;
         if (error instanceof RateLimitedError) {
           await this.sleep(error.retryAfter * 1e3);
         } else {
@@ -953,6 +1178,203 @@ function createClient(config) {
   return new OptropicClient(config);
 }
 
+// src/filter-verify.ts
+var HEADER_SIZE = 19;
+var SIGNATURE_SIZE = 64;
+var SLOTS_PER_BUCKET = 4;
+var StaleFilterError = class extends Error {
+  code = "FILTER_STALE_CRITICAL";
+  ageSeconds;
+  trustWindowSeconds;
+  constructor(ageSeconds, trustWindowSeconds) {
+    super(`Filter age ${ageSeconds}s exceeds trust window ${trustWindowSeconds}s`);
+    this.name = "StaleFilterError";
+    this.ageSeconds = ageSeconds;
+    this.trustWindowSeconds = trustWindowSeconds;
+  }
+};
+async function sha256(data) {
+  const buf = new Uint8Array(data).buffer;
+  const hash = await globalThis.crypto.subtle.digest("SHA-256", buf);
+  return new Uint8Array(hash);
+}
+async function sha256Hex(input) {
+  const encoded = new TextEncoder().encode(input);
+  const hash = await sha256(encoded);
+  return Array.from(hash).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function uint32BE(buf, offset) {
+  return (buf[offset] << 24 | buf[offset + 1] << 16 | buf[offset + 2] << 8 | buf[offset + 3]) >>> 0;
+}
+function uint16BE(buf, offset) {
+  return buf[offset] << 8 | buf[offset + 1];
+}
+function int64BE(buf, offset) {
+  const high = (buf[offset] << 24 | buf[offset + 1] << 16 | buf[offset + 2] << 8 | buf[offset + 3]) >>> 0;
+  const low = (buf[offset + 4] << 24 | buf[offset + 5] << 16 | buf[offset + 6] << 8 | buf[offset + 7]) >>> 0;
+  return high * 4294967296 + low;
+}
+async function fingerprint(item) {
+  const encoded = new TextEncoder().encode(item);
+  let digest = await sha256(encoded);
+  let fp = uint16BE(digest, 4);
+  while (fp === 0) {
+    digest = await sha256(digest);
+    fp = uint16BE(digest, 4);
+  }
+  return fp;
+}
+async function h1(item, capacity) {
+  const encoded = new TextEncoder().encode(item);
+  const digest = await sha256(encoded);
+  return uint32BE(digest, 0) % capacity;
+}
+async function altIndex(index, fp, capacity) {
+  const fpBuf = new Uint8Array(2);
+  fpBuf[0] = fp >> 8 & 255;
+  fpBuf[1] = fp & 255;
+  const fpDigest = await sha256(fpBuf);
+  return ((index ^ uint32BE(fpDigest, 0) % capacity) & 4294967295) >>> 0;
+}
+async function filterLookup(filterData, capacity, item) {
+  const fp = await fingerprint(item);
+  const i1 = await h1(item, capacity);
+  const i2 = await altIndex(i1, fp, capacity);
+  const b1Offset = i1 * SLOTS_PER_BUCKET * 2;
+  for (let s = 0; s < SLOTS_PER_BUCKET; s++) {
+    const slotVal = uint16BE(filterData, b1Offset + s * 2);
+    if (slotVal === fp) return true;
+  }
+  const b2Offset = i2 * SLOTS_PER_BUCKET * 2;
+  for (let s = 0; s < SLOTS_PER_BUCKET; s++) {
+    const slotVal = uint16BE(filterData, b2Offset + s * 2);
+    if (slotVal === fp) return true;
+  }
+  return false;
+}
+function parseFilterHeader(buf) {
+  if (buf.length < HEADER_SIZE) {
+    throw new Error("Buffer too small for filter header");
+  }
+  return {
+    version: buf[0],
+    issuedAt: int64BE(buf, 1),
+    itemCount: uint32BE(buf, 9),
+    keyId: uint16BE(buf, 13),
+    capacity: uint32BE(buf, 15)
+  };
+}
+function parseSaltsHeader(header) {
+  const salts = /* @__PURE__ */ new Map();
+  if (!header) return salts;
+  for (const pair of header.split(",")) {
+    const colonIdx = pair.indexOf(":");
+    if (colonIdx === -1) continue;
+    const tenantId = pair.slice(0, colonIdx).trim();
+    const saltHex = pair.slice(colonIdx + 1).trim();
+    if (tenantId && saltHex) {
+      const bytes = new Uint8Array(saltHex.length / 2);
+      for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(saltHex.slice(i * 2, i * 2 + 2), 16);
+      }
+      salts.set(tenantId, bytes);
+    }
+  }
+  return salts;
+}
+function toHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function verifyOffline(options) {
+  const {
+    assetId,
+    filterBytes,
+    salts,
+    filterPolicy = "permissive",
+    trustWindowSeconds = 259200
+    // 72 hours
+  } = options;
+  const header = parseFilterHeader(filterBytes);
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  const ageSeconds = nowSeconds - header.issuedAt;
+  if (ageSeconds > trustWindowSeconds) {
+    if (filterPolicy === "strict") {
+      throw new StaleFilterError(ageSeconds, trustWindowSeconds);
+    }
+  }
+  const filterDataEnd = filterBytes.length - SIGNATURE_SIZE;
+  const filterData = filterBytes.slice(HEADER_SIZE, filterDataEnd);
+  const capacity = header.capacity;
+  let revoked = false;
+  for (const salt of salts.values()) {
+    const saltHex = toHex(salt);
+    const saltedInput = assetId + saltHex;
+    const saltedHash = await sha256Hex(saltedInput);
+    if (await filterLookup(filterData, capacity, saltedHash)) {
+      revoked = true;
+      break;
+    }
+  }
+  const freshness = ageSeconds > trustWindowSeconds ? "stale" : "current";
+  return {
+    signatureValid: true,
+    revocationStatus: revoked ? "revoked" : "clear",
+    filterAgeSeconds: ageSeconds,
+    verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    verificationMode: "offline",
+    freshness
+  };
+}
+
+// src/dpp.ts
+function buildDPPConfig(metadata) {
+  const config = {
+    product_id: metadata.productId,
+    product_name: metadata.productName,
+    manufacturer: metadata.manufacturer,
+    country_of_origin: metadata.countryOfOrigin,
+    dpp_category: metadata.category
+  };
+  if (metadata.carbonFootprint !== void 0) config.carbon_footprint_kg_co2e = metadata.carbonFootprint;
+  if (metadata.recycledContent !== void 0) config.recycled_content_percent = metadata.recycledContent;
+  if (metadata.durabilityYears !== void 0) config.durability_years = metadata.durabilityYears;
+  if (metadata.repairabilityScore !== void 0) config.repairability_score = metadata.repairabilityScore;
+  if (metadata.substancesOfConcern) config.substances_of_concern = metadata.substancesOfConcern;
+  if (metadata.dppRegistryId) config.dpp_registry_id = metadata.dppRegistryId;
+  if (metadata.conformityDeclarations) config.conformity_declarations = metadata.conformityDeclarations;
+  if (metadata.sectorData) config.sector_data = metadata.sectorData;
+  return config;
+}
+function validateDPPMetadata(metadata) {
+  const errors = [];
+  if (!metadata.productId) errors.push("productId is required");
+  if (!metadata.productName) errors.push("productName is required");
+  if (!metadata.manufacturer) errors.push("manufacturer is required");
+  if (!metadata.countryOfOrigin) errors.push("countryOfOrigin is required");
+  if (metadata.countryOfOrigin && !/^[A-Z]{2}$/.test(metadata.countryOfOrigin)) {
+    errors.push('countryOfOrigin must be ISO 3166-1 alpha-2 (e.g., "DE")');
+  }
+  if (metadata.recycledContent !== void 0 && (metadata.recycledContent < 0 || metadata.recycledContent > 100)) {
+    errors.push("recycledContent must be between 0 and 100");
+  }
+  if (metadata.category === "battery" && metadata.sectorData) {
+    const battery = metadata.sectorData;
+    if (battery.type === "battery") {
+      if (!battery.chemistry) errors.push("battery.chemistry is required for battery passports");
+      if (!battery.capacityKwh) errors.push("battery.capacityKwh is required for battery passports");
+    }
+  }
+  if (metadata.category === "textile" && metadata.sectorData) {
+    const textile = metadata.sectorData;
+    if (textile.type === "textile") {
+      if (!textile.fiberComposition || textile.fiberComposition.length === 0) {
+        errors.push("textile.fiberComposition is required for textile passports");
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
 // src/webhooks.ts
 async function computeHmacSha256(secret, message) {
   const encoder = new TextEncoder();
@@ -999,7 +1421,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.0.0";
+var SDK_VERSION2 = "2.2.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetsResource,
@@ -1008,6 +1430,7 @@ var SDK_VERSION2 = "2.0.0";
   BatchNotFoundError,
   CodeNotFoundError,
   ComplianceResource,
+  DocumentsResource,
   InvalidCodeError,
   InvalidGTINError,
   InvalidSerialError,
@@ -1016,13 +1439,21 @@ var SDK_VERSION2 = "2.0.0";
   NetworkError,
   OptropicClient,
   OptropicError,
+  ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,
   RevokedCodeError,
   SDK_VERSION,
   SchemasResource,
   ServiceUnavailableError,
+  StaleFilterError,
   TimeoutError,
+  buildDPPConfig,
   createClient,
+  createErrorFromResponse,
+  parseFilterHeader,
+  parseSaltsHeader,
+  validateDPPMetadata,
+  verifyOffline,
   verifyWebhookSignature
 });