optropic 1.0.0 → 2.1.0

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,169 @@ declare class AssetsResource {
     private buildQuery;
 }
 
+/**
+ * Audit Resource
+ *
+ * Immutable audit log operations — list, get, and create custom audit events.
+ * Mirrors the Python SDK's `optropic.resources.audit` module.
+ */
+
+interface AuditEvent {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly eventType: string;
+    readonly actor: string;
+    readonly createdAt: string;
+    readonly resourceId?: string;
+    readonly resourceType?: string;
+    readonly details?: Record<string, unknown>;
+    readonly eventHash?: string;
+    readonly chainSequence?: number;
+}
+interface ListAuditParams {
+    readonly page?: number;
+    readonly limit?: number;
+    readonly event_type?: string;
+    readonly resource_id?: string;
+    readonly from_date?: string;
+    readonly to_date?: string;
+}
+interface ListAuditResponse {
+    readonly data: AuditEvent[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+interface CreateAuditEventParams {
+    readonly eventType: string;
+    readonly resourceId?: string;
+    readonly resourceType?: string;
+    readonly details?: Record<string, unknown>;
+}
+declare class AuditResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * List audit events with optional filtering and pagination.
+     */
+    list(params?: ListAuditParams): Promise<ListAuditResponse>;
+    /**
+     * Retrieve a single audit event by ID.
+     */
+    get(eventId: string): Promise<AuditEvent>;
+    /**
+     * Record a custom audit event.
+     */
+    create(params: CreateAuditEventParams): Promise<AuditEvent>;
+    private buildQuery;
+}
+
+/**
+ * Compliance Resource
+ *
+ * Chain verification, Merkle proofs, audit export, and compliance configuration.
+ * Mirrors the Python SDK's `optropic.resources.compliance` module.
+ */
+
+interface ChainVerifyResult {
+    readonly tenantId: string;
+    readonly chainValid: boolean;
+    readonly eventsChecked: number;
+    readonly verifiedAt: string;
+    readonly brokenAtSequence?: number;
+}
+interface MerkleRoot {
+    readonly id: string;
+    readonly rootHash: string;
+    readonly eventCount: number;
+    readonly periodStart: string;
+    readonly periodEnd: string;
+    readonly createdAt: string;
+}
+interface MerkleProof {
+    readonly eventId: string;
+    readonly eventHash: string;
+    readonly merkleRoot: string;
+    readonly proof: string[];
+    readonly verified: boolean;
+    readonly period: string;
+}
+interface ExportParams {
+    readonly from_date?: string;
+    readonly to_date?: string;
+    readonly limit?: number;
+}
+interface ExportResult {
+    readonly filename: string;
+    readonly eventCount: number;
+    readonly csv: string;
+    readonly signature?: string;
+    readonly publicKeyHex?: string;
+    readonly keyId?: string;
+    readonly algorithm?: string;
+}
+interface ComplianceConfig {
+    readonly complianceMode: string;
+    readonly retentionPolicy: Record<string, unknown>;
+}
+declare class ComplianceResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * Verify the integrity of the full audit chain.
+     */
+    verifyChain(): Promise<ChainVerifyResult>;
+    /**
+     * Return all Merkle roots.
+     */
+    listMerkleRoots(): Promise<MerkleRoot[]>;
+    /**
+     * Return a Merkle inclusion proof for a specific audit event.
+     */
+    getMerkleProof(eventId: string): Promise<MerkleProof>;
+    /**
+     * Export audit data as a signed CSV.
+     */
+    exportAudit(params?: ExportParams): Promise<ExportResult>;
+    /**
+     * Retrieve the current compliance configuration.
+     */
+    getConfig(): Promise<ComplianceConfig>;
+    /**
+     * Update the compliance mode.
+     */
+    updateConfig(mode: string): Promise<ComplianceConfig>;
+    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 +338,134 @@ 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;
+}
+
+/**
+ * Schemas Resource
+ *
+ * Schema Registry operations — register and manage vertical config schemas.
+ * Mirrors the Python SDK's `optropic.resources.schemas` module.
+ */
+
+interface VerticalSchema {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly verticalId: string;
+    readonly version: string;
+    readonly metadataSchema: Record<string, unknown>;
+    readonly exportFormats: string[];
+    readonly isActive: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly description?: string;
+}
+interface CreateSchemaParams {
+    readonly verticalId: string;
+    readonly metadataSchema: Record<string, unknown>;
+    readonly version?: string;
+    readonly exportFormats?: string[];
+    readonly description?: string;
+}
+interface UpdateSchemaParams {
+    readonly version?: string;
+    readonly metadataSchema?: Record<string, unknown>;
+    readonly exportFormats?: string[];
+    readonly description?: string;
+    readonly isActive?: boolean;
+}
+interface ListSchemasParams {
+    readonly page?: number;
+    readonly per_page?: number;
+    readonly include_inactive?: boolean;
+}
+interface ListSchemasResponse {
+    readonly data: VerticalSchema[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+        readonly totalPages: number;
+    };
+}
+interface SchemaValidationResult {
+    readonly valid: boolean;
+    readonly errors: Array<{
+        field: string;
+        message: string;
+        received?: string;
+    }>;
+}
+declare class SchemasResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * Register or update a vertical config schema.
+     * If a schema already exists for the verticalId, it will be updated.
+     */
+    create(params: CreateSchemaParams): Promise<VerticalSchema>;
+    /**
+     * List registered vertical schemas with pagination.
+     */
+    list(params?: ListSchemasParams): Promise<ListSchemasResponse>;
+    /**
+     * Get the active schema for a specific vertical.
+     */
+    get(verticalId: string): Promise<VerticalSchema>;
+    /**
+     * Update an existing vertical schema.
+     */
+    update(verticalId: string, params: UpdateSchemaParams): Promise<VerticalSchema>;
+    /**
+     * Deactivate a vertical schema (soft delete).
+     */
+    delete(verticalId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    validate(verticalId: string, assetConfig: Record<string, unknown>): Promise<SchemaValidationResult>;
+    private buildQuery;
+    private stripUndefined;
+}
+
 /**
  * optropic - OptropicClient
  *
@@ -193,9 +507,20 @@ declare class OptropicClient {
     private readonly config;
     private readonly baseUrl;
     private readonly retryConfig;
+    private readonly _sandbox;
     readonly assets: AssetsResource;
+    readonly audit: AuditResource;
+    readonly compliance: ComplianceResource;
     readonly keys: KeysResource;
+    readonly keysets: KeysetsResource;
+    readonly schemas: SchemasResource;
     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 +543,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 +843,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, 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 };