optropic 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -44,6 +44,12 @@ interface OptropicConfig {
      * Retry configuration for failed requests.
      */
     readonly retry?: RetryConfig;
+    /**
+     * Enable debug logging.  When ``true``, every request and response
+     * is logged to the console with secrets redacted.
+     * @default false
+     */
+    readonly debug?: boolean;
 }
 /**
  * Retry configuration for network requests.
@@ -159,6 +165,18 @@ declare class AssetsResource {
      * assets. Pass an explicit `is_sandbox` value to override.
      */
     list(params?: ListAssetsParams): Promise<ListAssetsResponse>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    listAll(params?: ListAssetsParams): AsyncGenerator<Asset>;
     get(assetId: string): Promise<Asset>;
     verify(assetId: string): Promise<VerifyResult>;
     revoke(assetId: string, reason?: string): Promise<Asset>;
@@ -304,6 +322,115 @@ declare class ComplianceResource {
     private buildQuery;
 }
 
+/**
+ * Documents Resource
+ *
+ * Document enrollment operations — register physical objects with substrate
+ * fingerprints and manage their lifecycle.
+ *
+ * This module is central to Optropic's Material Entropy technology:
+ * a physical object is photographed, its micro-surface features are extracted
+ * as a 3D descriptor [GB, GE, M7-PCA], and the resulting fingerprint is
+ * enrolled as a document linked to an asset.
+ */
+
+interface Document {
+    readonly id: string;
+    readonly assetId: string;
+    readonly tenantId: string;
+    readonly fingerprintHash: string;
+    readonly descriptorVersion: string;
+    readonly substrateType: string;
+    readonly captureDevice?: string;
+    readonly enrolledAt: string;
+    readonly status: 'active' | 'superseded' | 'revoked';
+    readonly metadata?: Record<string, unknown>;
+}
+interface EnrollDocumentParams {
+    /** The asset ID to link this document to. */
+    readonly assetId: string;
+    /** SHA-256 hash of the 3D descriptor fingerprint. */
+    readonly fingerprintHash: string;
+    /** Descriptor version, e.g. "GB_GE_M7PCA_v1". */
+    readonly descriptorVersion: string;
+    /** Substrate type, e.g. "S_fb", "S_pvc", "S_kp". */
+    readonly substrateType: string;
+    /** Capture device identifier, e.g. "iPhone16ProMax_main". */
+    readonly captureDevice?: string;
+    /** Additional metadata (ROI info, sharpness scores, etc). */
+    readonly metadata?: Record<string, unknown>;
+}
+interface VerifyDocumentParams {
+    /** The fingerprint hash to verify against enrolled documents. */
+    readonly fingerprintHash: string;
+    /** Descriptor version used for the verification capture. */
+    readonly descriptorVersion: string;
+    /** Minimum similarity threshold (0.0 - 1.0). @default 0.85 */
+    readonly threshold?: number;
+}
+interface DocumentVerifyResult {
+    readonly matched: boolean;
+    readonly documentId?: string;
+    readonly assetId?: string;
+    readonly similarity: number;
+    readonly descriptorVersion: string;
+    readonly verifiedAt: string;
+}
+interface ListDocumentsParams {
+    readonly assetId?: string;
+    readonly substrateType?: string;
+    readonly status?: 'active' | 'superseded' | 'revoked';
+    readonly page?: number;
+    readonly per_page?: number;
+}
+interface ListDocumentsResponse {
+    readonly data: Document[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+declare class DocumentsResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    enroll(params: EnrollDocumentParams): Promise<Document>;
+    /**
+     * Verify a fingerprint against enrolled documents.
+     *
+     * Returns the best match if similarity exceeds the threshold.
+     */
+    verify(params: VerifyDocumentParams): Promise<DocumentVerifyResult>;
+    /**
+     * Get a single document by ID.
+     */
+    get(documentId: string): Promise<Document>;
+    /**
+     * List enrolled documents with optional filtering.
+     */
+    list(params?: ListDocumentsParams): Promise<ListDocumentsResponse>;
+    /**
+     * Supersede a document (e.g., re-enrollment with better capture).
+     */
+    supersede(documentId: string, newDocumentId: string): Promise<Document>;
+    private buildQuery;
+}
+
 /**
  * Keys Resource
  *
@@ -376,6 +503,124 @@ declare class KeysetsResource {
     private buildQuery;
 }
 
+/**
+ * Provenance Resource
+ *
+ * OID (Origin ID) Provenance chain operations — track the full lifecycle
+ * of a physical object from manufacturing through distribution to verification.
+ *
+ * Each provenance event is cryptographically linked to the previous one,
+ * forming a tamper-evident chain. Combined with Document Enrollment
+ * (substrate fingerprints), this enables end-to-end physical-digital trust.
+ */
+
+interface ProvenanceEvent {
+    readonly id: string;
+    readonly assetId: string;
+    readonly tenantId: string;
+    readonly eventType: ProvenanceEventType;
+    readonly actor: string;
+    readonly location?: ProvenanceLocation;
+    readonly previousEventId?: string;
+    readonly eventHash: string;
+    readonly chainSequence: number;
+    readonly timestamp: string;
+    readonly metadata?: Record<string, unknown>;
+}
+type ProvenanceEventType = 'manufactured' | 'labeled' | 'enrolled' | 'shipped' | 'received' | 'transferred' | 'verified' | 'recalled' | 'destroyed' | 'custom';
+interface ProvenanceLocation {
+    readonly country?: string;
+    readonly region?: string;
+    readonly facility?: string;
+    readonly coordinates?: {
+        readonly lat: number;
+        readonly lng: number;
+    };
+}
+interface RecordProvenanceParams {
+    /** The asset ID this event belongs to. */
+    readonly assetId: string;
+    /** Type of provenance event. */
+    readonly eventType: ProvenanceEventType;
+    /** Actor identifier (user, system, device). */
+    readonly actor: string;
+    /** Location where the event occurred. */
+    readonly location?: ProvenanceLocation;
+    /** Additional event metadata. */
+    readonly metadata?: Record<string, unknown>;
+}
+interface ProvenanceChain {
+    readonly assetId: string;
+    readonly events: ProvenanceEvent[];
+    readonly chainValid: boolean;
+    readonly eventCount: number;
+    readonly firstEvent: string;
+    readonly lastEvent: string;
+}
+interface VerifyProvenanceResult {
+    readonly chainValid: boolean;
+    readonly eventsChecked: number;
+    readonly brokenAtSequence?: number;
+    readonly verifiedAt: string;
+}
+interface ListProvenanceParams {
+    readonly assetId?: string;
+    readonly eventType?: ProvenanceEventType;
+    readonly from_date?: string;
+    readonly to_date?: string;
+    readonly page?: number;
+    readonly per_page?: number;
+}
+interface ListProvenanceResponse {
+    readonly data: ProvenanceEvent[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+declare class ProvenanceResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * 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' },
+     * });
+     * ```
+     */
+    record(params: RecordProvenanceParams): Promise<ProvenanceEvent>;
+    /**
+     * Get the full provenance chain for an asset.
+     */
+    getChain(assetId: string): Promise<ProvenanceChain>;
+    /**
+     * Get a single provenance event by ID.
+     */
+    get(eventId: string): Promise<ProvenanceEvent>;
+    /**
+     * List provenance events with optional filtering.
+     */
+    list(params?: ListProvenanceParams): Promise<ListProvenanceResponse>;
+    /**
+     * Verify the integrity of an asset's provenance chain.
+     *
+     * Checks that all events are correctly linked via cryptographic hashes.
+     */
+    verifyChain(assetId: string): Promise<VerifyProvenanceResult>;
+    private buildQuery;
+}
+
 /**
  * Schemas Resource
  *
@@ -475,11 +720,14 @@ declare class SchemasResource {
  */
 
 interface RequestOptions {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     path: string;
     body?: unknown;
     headers?: Record<string, string>;
+    /** Per-operation timeout in ms.  Overrides the client-level default. */
     timeout?: number;
+    /** Idempotency key for safe mutation retries. Auto-generated for POST/PUT/PATCH if omitted. */
+    idempotencyKey?: string;
 }
 type RequestFn = <T>(options: RequestOptions) => Promise<T>;
 /**
@@ -491,6 +739,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *
  * const client = new OptropicClient({
  *   apiKey: 'optr_live_xxxxxxxxxxxx',
+ *   debug: true,  // logs every request/response
  * });
  *
  * // Create an asset
@@ -499,7 +748,7 @@ type RequestFn = <T>(options: RequestOptions) => Promise<T>;
  *   serial: 'SN001',
  * });
  *
- * // Verify an asset
+ * // Verify an asset (with per-operation timeout)
  * const result = await client.assets.verify(asset.id);
  * ```
  */
@@ -508,11 +757,14 @@ declare class OptropicClient {
     private readonly baseUrl;
     private readonly retryConfig;
     private readonly _sandbox;
+    private readonly _debug;
     readonly assets: AssetsResource;
     readonly audit: AuditResource;
     readonly compliance: ComplianceResource;
+    readonly documents: DocumentsResource;
     readonly keys: KeysResource;
     readonly keysets: KeysetsResource;
+    readonly provenance: ProvenanceResource;
     readonly schemas: SchemasResource;
     constructor(config: OptropicConfig);
     /** True when the client is in sandbox mode (test API key or explicit override). */
@@ -521,6 +773,10 @@ declare class OptropicClient {
     get isLive(): boolean;
     /** Returns 'sandbox' or 'live'. */
     get environment(): 'sandbox' | 'live';
+    private redact;
+    private logRequest;
+    private logResponse;
+    private logRetry;
     private isValidApiKey;
     private request;
     private executeRequest;
@@ -538,11 +794,224 @@ declare class OptropicClient {
  *
  * const client = createClient({
  *   apiKey: process.env.OPTROPIC_API_KEY!,
+ *   debug: true,
  * });
  * ```
  */
 declare function createClient(config: OptropicConfig): OptropicClient;
 
+/**
+ * Offline Filter Verification — Cuckoo Filter + Salted Lookup
+ *
+ * Validates the filter signature, checks freshness, then performs
+ * salted lookup for revocation status without network access.
+ *
+ * Port of Python SDK's `filter_verify.py` to TypeScript.
+ *
+ * @module optropic/filter-verify
+ */
+interface FilterHeader {
+    readonly version: number;
+    readonly issuedAt: number;
+    readonly itemCount: number;
+    readonly keyId: number;
+    readonly capacity: number;
+}
+interface OfflineVerifyResult {
+    readonly signatureValid: boolean;
+    readonly revocationStatus: 'clear' | 'revoked' | 'unknown';
+    readonly filterAgeSeconds: number | null;
+    readonly verifiedAt: string;
+    readonly verificationMode: 'offline';
+    readonly freshness?: 'current' | 'stale';
+}
+interface FilterSyncResult {
+    readonly filter: Uint8Array;
+    readonly salts: Map<string, Uint8Array>;
+    readonly issuedAt: Date;
+    readonly itemCount: number;
+}
+interface OfflineVerifyOptions {
+    /** The asset ID to check. */
+    readonly assetId: string;
+    /** The full filter binary (header + buckets + signature). */
+    readonly filterBytes: Uint8Array;
+    /** Per-tenant salts (tenant_id → salt bytes). */
+    readonly salts: Map<string, Uint8Array>;
+    /** Ed25519 public key for signature verification. Optional. */
+    readonly publicKey?: Uint8Array;
+    /** 'strict' throws on stale filter, 'permissive' continues. @default 'permissive' */
+    readonly filterPolicy?: 'strict' | 'permissive';
+    /** Maximum filter age in seconds before considered stale. @default 259200 (72 hours) */
+    readonly trustWindowSeconds?: number;
+}
+declare class StaleFilterError extends Error {
+    readonly code = "FILTER_STALE_CRITICAL";
+    readonly ageSeconds: number;
+    readonly trustWindowSeconds: number;
+    constructor(ageSeconds: number, trustWindowSeconds: number);
+}
+/**
+ * Parse the 19-byte Cuckoo filter header.
+ */
+declare function parseFilterHeader(buf: Uint8Array): FilterHeader;
+/**
+ * Parse the X-Optropic-Filter-Salts header.
+ *
+ * Format: "tenant_id_1:salt_hex_1,tenant_id_2:salt_hex_2"
+ */
+declare function parseSaltsHeader(header: string): Map<string, Uint8Array>;
+/**
+ * Perform offline verification using a local Cuckoo filter.
+ *
+ * Checks the revocation status of an asset without any network access.
+ * Requires a previously downloaded filter (via `assets.syncFilter()`).
+ *
+ * @example
+ * ```typescript
+ * import { verifyOffline } from 'optropic';
+ *
+ * const result = await verifyOffline({
+ *   assetId: 'asset-123',
+ *   filterBytes: cachedFilter,
+ *   salts: cachedSalts,
+ * });
+ *
+ * if (result.revocationStatus === 'revoked') {
+ *   console.warn('Asset has been revoked!');
+ * }
+ * ```
+ */
+declare function verifyOffline(options: OfflineVerifyOptions): Promise<OfflineVerifyResult>;
+
+/**
+ * EU Digital Product Passport (DPP) — Types & Helpers
+ *
+ * Supports the ESPR/DPP regulation (EU DPP Registry goes live 19 July 2026).
+ * Provides typed metadata structures for Battery Passport (Feb 2027),
+ * Textiles (Q2 2027), and general product passports.
+ *
+ * @module optropic/dpp
+ */
+/**
+ * Base Digital Product Passport metadata.
+ * Aligns with the EU DPP data model (ESPR Art. 8-12).
+ */
+interface DPPMetadata {
+    /** Unique product identifier (GS1 GTIN, SGTIN, or custom). */
+    readonly productId: string;
+    /** Product name / trade name. */
+    readonly productName: string;
+    /** Manufacturer / economic operator name. */
+    readonly manufacturer: string;
+    /** Country of manufacture (ISO 3166-1 alpha-2). */
+    readonly countryOfOrigin: string;
+    /** Product category for DPP regulation scope. */
+    readonly category: DPPCategory;
+    /** Carbon footprint in kg CO2e (if applicable). */
+    readonly carbonFootprint?: number;
+    /** Recycled content percentage (0-100). */
+    readonly recycledContent?: number;
+    /** Durability / expected lifetime in years. */
+    readonly durabilityYears?: number;
+    /** Repairability score (EU scale, if applicable). */
+    readonly repairabilityScore?: number;
+    /** List of substances of concern (SCIP database). */
+    readonly substancesOfConcern?: SubstanceEntry[];
+    /** EU DPP Registry reference (assigned after July 2026). */
+    readonly dppRegistryId?: string;
+    /** Conformity declarations / certifications. */
+    readonly conformityDeclarations?: ConformityDeclaration[];
+    /** Additional sector-specific metadata. */
+    readonly sectorData?: BatteryPassportData | TextilePassportData | Record<string, unknown>;
+}
+type DPPCategory = 'battery' | 'textile' | 'electronics' | 'construction' | 'steel' | 'furniture' | 'chemical' | 'general';
+interface SubstanceEntry {
+    readonly name: string;
+    readonly casNumber?: string;
+    readonly concentration?: number;
+    readonly unit?: string;
+}
+interface ConformityDeclaration {
+    readonly standard: string;
+    readonly certificateId?: string;
+    readonly issuedBy?: string;
+    readonly validUntil?: string;
+}
+interface BatteryPassportData {
+    readonly type: 'battery';
+    /** Battery chemistry (e.g., "NMC", "LFP", "NCA"). */
+    readonly chemistry: string;
+    /** Nominal capacity in kWh. */
+    readonly capacityKwh: number;
+    /** State of Health percentage (0-100). */
+    readonly stateOfHealth?: number;
+    /** Number of charge cycles completed. */
+    readonly cycleCount?: number;
+    /** Cobalt content percentage. */
+    readonly cobaltContent?: number;
+    /** Lithium content percentage. */
+    readonly lithiumContent?: number;
+    /** Recycled cobalt percentage. */
+    readonly recycledCobaltPercent?: number;
+    /** Carbon footprint class (A-G). */
+    readonly carbonClass?: string;
+    /** Expected lifetime in charge cycles. */
+    readonly expectedLifetimeCycles?: number;
+}
+interface TextilePassportData {
+    readonly type: 'textile';
+    /** Fiber composition (e.g., [{ fiber: "cotton", percent: 95 }]). */
+    readonly fiberComposition: FiberEntry[];
+    /** Dyeing / finishing processes used. */
+    readonly processes?: string[];
+    /** Water usage in liters per unit. */
+    readonly waterUsageLiters?: number;
+    /** Microfiber release rating. */
+    readonly microfiberRelease?: 'low' | 'medium' | 'high';
+    /** Care instructions (ISO 3758 symbols). */
+    readonly careInstructions?: string[];
+}
+interface FiberEntry {
+    readonly fiber: string;
+    readonly percent: number;
+    readonly recycled?: boolean;
+    readonly origin?: string;
+}
+/**
+ * Build a DPP-compliant asset config from metadata.
+ *
+ * Converts a typed DPPMetadata object into the flat config format
+ * expected by the Optropic API's asset creation endpoint.
+ *
+ * @example
+ * ```typescript
+ * const config = buildDPPConfig({
+ *   productId: '04012345000010',
+ *   productName: 'EcoWidget Pro',
+ *   manufacturer: 'GreenTech GmbH',
+ *   countryOfOrigin: 'DE',
+ *   category: 'electronics',
+ *   carbonFootprint: 12.5,
+ *   recycledContent: 35,
+ * });
+ *
+ * await client.assets.create({
+ *   keysetId: 'ks-1',
+ *   vertical: 'dpp',
+ *   assetConfig: config,
+ * });
+ * ```
+ */
+declare function buildDPPConfig(metadata: DPPMetadata): Record<string, unknown>;
+/**
+ * Validate that DPP metadata meets minimum requirements for the given category.
+ */
+declare function validateDPPMetadata(metadata: DPPMetadata): {
+    valid: boolean;
+    errors: string[];
+};
+
 /**
  * Webhook Signature Verification
  *
@@ -842,7 +1311,19 @@ declare class ServiceUnavailableError extends OptropicError {
         requestId?: string;
     });
 }
+/**
+ * Create an appropriate error from an API response.
+ * Used internally by the client to map responses to typed errors.
+ *
+ * @internal
+ */
+declare function createErrorFromResponse(statusCode: number, body: {
+    code?: ErrorCode;
+    message?: string;
+    details?: Record<string, unknown>;
+    requestId?: string;
+}): OptropicError;
 
-declare const SDK_VERSION = "2.0.0";
+declare const SDK_VERSION = "2.3.0";
 
-export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type CreateAssetParams, type CreateAuditEventParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateSchemaParams, type ErrorCode, type ExportParams, type ExportResult, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListSchemasParams, type ListSchemasResponse, type MerkleProof, type MerkleRoot, NetworkError, OptropicClient, type OptropicConfig, OptropicError, QuotaExceededError, RateLimitedError, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, TimeoutError, type UpdateSchemaParams, type VerifyResult, type VerticalSchema, type WebhookVerifyOptions, type WebhookVerifyResult, createClient, verifyWebhookSignature };
+export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatteryPassportData, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type ConformityDeclaration, type CreateAssetParams, type CreateAuditEventParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateSchemaParams, type DPPCategory, type DPPMetadata, type Document, type DocumentVerifyResult, DocumentsResource, type EnrollDocumentParams, type ErrorCode, type ExportParams, type ExportResult, type FiberEntry, type FilterHeader, type FilterSyncResult, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListDocumentsParams, type ListDocumentsResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListProvenanceParams, type ListProvenanceResponse, type ListSchemasParams, type ListSchemasResponse, type MerkleProof, type MerkleRoot, NetworkError, type OfflineVerifyOptions, type OfflineVerifyResult, OptropicClient, type OptropicConfig, OptropicError, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, RateLimitedError, type RecordProvenanceParams, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, StaleFilterError, type SubstanceEntry, type TextilePassportData, TimeoutError, type UpdateSchemaParams, type VerifyDocumentParams, type VerifyProvenanceResult, type VerifyResult, type VerticalSchema, type WebhookVerifyOptions, type WebhookVerifyResult, buildDPPConfig, createClient, createErrorFromResponse, parseFilterHeader, parseSaltsHeader, validateDPPMetadata, verifyOffline, verifyWebhookSignature };