optropic 2.1.0 → 2.3.0

package/dist/index.js

@@ -404,6 +404,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)}` });
   }
@@ -538,6 +563,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) {
@@ -574,6 +691,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) {
@@ -701,23 +906,27 @@ 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.3.0";
 var SANDBOX_PREFIXES = ["optr_test_"];
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelay: 1e3,
   maxDelay: 1e4
 };
+var KEY_REDACT_RE = /(optr_(?:live|test)_)[a-zA-Z0-9_-]+/g;
 var OptropicClient = class {
   config;
   baseUrl;
   retryConfig;
   _sandbox;
+  _debug;
   assets;
   audit;
   compliance;
+  documents;
   keys;
   keysets;
+  provenance;
   schemas;
   constructor(config) {
     if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
@@ -729,6 +938,7 @@ var OptropicClient = class {
       ...config,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
+    this._debug = config.debug ?? false;
     if (config.sandbox !== void 0) {
       this._sandbox = config.sandbox;
     } else {
@@ -747,8 +957,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);
   }
   // ─────────────────────────────────────────────────────────────────────────
@@ -767,23 +979,59 @@ var OptropicClient = class {
     return this._sandbox ? "sandbox" : "live";
   }
   // ─────────────────────────────────────────────────────────────────────────
+  // DEBUG LOGGING
+  // ─────────────────────────────────────────────────────────────────────────
+  redact(text) {
+    return text.replace(KEY_REDACT_RE, "$1****");
+  }
+  logRequest(method, url, requestId, idempotencyKey) {
+    if (!this._debug) return;
+    const parts = [`${method} ${this.redact(url)}`, `req=${requestId}`];
+    if (idempotencyKey) parts.push(`idempotency=${idempotencyKey}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logResponse(method, path, status, durationMs, requestId, serverRequestId, attempt) {
+    if (!this._debug) return;
+    const parts = [`${method} ${path} \u2192 ${status} (${Math.round(durationMs)}ms)`, `req=${requestId}`];
+    if (serverRequestId) parts.push(`server_req=${serverRequestId}`);
+    if (attempt > 0) parts.push(`attempt=${attempt + 1}`);
+    console.log(`[optropic] ${parts.join(" ")}`);
+  }
+  logRetry(method, path, attempt, delay, reason) {
+    if (!this._debug) return;
+    console.log(
+      `[optropic] ${method} ${path} retry #${attempt + 1} in ${(delay / 1e3).toFixed(1)}s (${reason})`
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────────
   // PRIVATE METHODS
   // ─────────────────────────────────────────────────────────────────────────
   isValidApiKey(apiKey) {
     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 requestId = crypto.randomUUID();
     const requestHeaders = {
       "Content-Type": "application/json",
       "Accept": "application/json",
       "x-api-key": this.config.apiKey,
       "X-SDK-Version": SDK_VERSION,
       "X-SDK-Language": "typescript",
+      "X-Request-ID": requestId,
       ...this.config.headers,
       ...headers
     };
+    let effectiveIdempotencyKey;
+    if (idempotencyKey) {
+      requestHeaders["Idempotency-Key"] = idempotencyKey;
+      effectiveIdempotencyKey = idempotencyKey;
+    } else if (["POST", "PUT", "PATCH"].includes(method)) {
+      effectiveIdempotencyKey = crypto.randomUUID();
+      requestHeaders["Idempotency-Key"] = effectiveIdempotencyKey;
+    }
+    this.logRequest(method, url, requestId, effectiveIdempotencyKey);
     let lastError = null;
     let attempt = 0;
     while (attempt <= this.retryConfig.maxRetries) {
@@ -793,7 +1041,10 @@ var OptropicClient = class {
           method,
           requestHeaders,
           body,
-          timeout
+          timeout,
+          requestId,
+          path,
+          attempt
         );
         return response;
       } catch (error) {
@@ -804,13 +1055,19 @@ 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);
+          const retryDelay = error.retryAfter * 1e3;
+          this.logRetry(method, path, attempt, retryDelay, "rate_limited");
+          await this.sleep(retryDelay);
         } else {
+          const statusCode = error instanceof OptropicError ? error.statusCode : 0;
+          this.logRetry(method, path, attempt, delay, `status=${statusCode}`);
           await this.sleep(delay);
         }
         attempt++;
@@ -818,9 +1075,10 @@ var OptropicClient = class {
     }
     throw lastError ?? new OptropicError("UNKNOWN_ERROR", "Request failed");
   }
-  async executeRequest(url, method, headers, body, timeout) {
+  async executeRequest(url, method, headers, body, timeout, requestId, path, attempt) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const t0 = performance.now();
     try {
       const response = await fetch(url, {
         method,
@@ -829,7 +1087,9 @@ var OptropicClient = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      const requestId = response.headers.get("x-request-id") ?? "";
+      const durationMs = performance.now() - t0;
+      const serverRequestId = response.headers.get("x-request-id") ?? "";
+      this.logResponse(method, path, response.status, durationMs, requestId, serverRequestId, attempt);
       if (!response.ok) {
         let errorBody;
         try {
@@ -852,7 +1112,7 @@ var OptropicClient = class {
           code: errorBody.code,
           message: errorBody.message,
           details: errorBody.details,
-          requestId
+          requestId: serverRequestId || requestId
         });
       }
       if (response.status === 204) {
@@ -878,8 +1138,12 @@ var OptropicClient = class {
       }
       if (error instanceof Error) {
         if (error.name === "AbortError") {
+          const durationMs2 = performance.now() - t0;
+          this.logResponse(method, path, 408, durationMs2, requestId, "", attempt);
           throw new TimeoutError(timeout);
         }
+        const durationMs = performance.now() - t0;
+        this.logResponse(method, path, 0, durationMs, requestId, "", attempt);
         throw new NetworkError(error.message, { cause: error });
       }
       throw new OptropicError("UNKNOWN_ERROR", "An unexpected error occurred", {
@@ -895,6 +1159,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();
@@ -941,7 +1402,7 @@ async function verifyWebhookSignature(options) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "2.0.0";
+var SDK_VERSION2 = "2.3.0";
 export {
   AssetsResource,
   AuditResource,
@@ -949,6 +1410,7 @@ export {
   BatchNotFoundError,
   CodeNotFoundError,
   ComplianceResource,
+  DocumentsResource,
   InvalidCodeError,
   InvalidGTINError,
   InvalidSerialError,
@@ -957,13 +1419,21 @@ export {
   NetworkError,
   OptropicClient,
   OptropicError,
+  ProvenanceResource,
   QuotaExceededError,
   RateLimitedError,
   RevokedCodeError,
   SDK_VERSION2 as SDK_VERSION,
   SchemasResource,
   ServiceUnavailableError,
+  StaleFilterError,
   TimeoutError,
+  buildDPPConfig,
   createClient,
+  createErrorFromResponse,
+  parseFilterHeader,
+  parseSaltsHeader,
+  validateDPPMetadata,
+  verifyOffline,
   verifyWebhookSignature
 };

package/package.json

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