optropic 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,478 @@
+/**
+ * optropic - Public Types
+ *
+ * Configuration and error types for the Optropic SDK.
+ *
+ * @module optropic
+ */
+/**
+ * Configuration for the Optropic SDK client.
+ *
+ * @example
+ * ```typescript
+ * const config: OptropicConfig = {
+ *   apiKey: 'optr_live_xxxxxxxxxxxx',
+ * };
+ * ```
+ */
+interface OptropicConfig {
+    /**
+     * API key for authentication.
+     * Format: optr_live_xxx (production) or optr_test_xxx (test)
+     */
+    readonly apiKey: string;
+    /**
+     * Base URL override (for self-hosted deployments).
+     * If not provided, uses Optropic's managed infrastructure.
+     */
+    readonly baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    readonly timeout?: number;
+    /**
+     * Custom headers to include in all requests.
+     */
+    readonly headers?: Record<string, string>;
+    /**
+     * Retry configuration for failed requests.
+     */
+    readonly retry?: RetryConfig;
+}
+/**
+ * Retry configuration for network requests.
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    readonly maxRetries?: number;
+    /**
+     * Base delay between retries in milliseconds.
+     * Uses exponential backoff: delay * 2^attempt
+     * @default 1000
+     */
+    readonly baseDelay?: number;
+    /**
+     * Maximum delay between retries in milliseconds.
+     * @default 10000
+     */
+    readonly maxDelay?: number;
+}
+/**
+ * Error codes returned by the SDK.
+ * Use these for programmatic error handling.
+ */
+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';
+
+interface Asset {
+    readonly id: string;
+    readonly short_id: string;
+    readonly gtin: string;
+    readonly serial: string;
+    readonly status: 'active' | 'revoked';
+    readonly security_level: 'signed' | 'provenance';
+    readonly metadata?: Record<string, string>;
+    readonly created_at: string;
+    readonly revoked_at?: string;
+}
+interface CreateAssetParams {
+    readonly gtin: string;
+    readonly serial: string;
+    readonly metadata?: Record<string, string>;
+}
+interface ListAssetsParams {
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly status?: 'active' | 'revoked';
+    readonly gtin?: string;
+}
+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;
+}
+interface BatchCreateParams {
+    readonly assets: CreateAssetParams[];
+}
+interface BatchCreateResult {
+    readonly created: number;
+    readonly asset_ids: string[];
+}
+declare class AssetsResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(params: CreateAssetParams): Promise<Asset>;
+    list(params?: ListAssetsParams): Promise<Asset[]>;
+    get(assetId: string): Promise<Asset>;
+    verify(assetId: string): Promise<VerifyResult>;
+    revoke(assetId: string, reason?: string): Promise<Asset>;
+    batchCreate(params: BatchCreateParams): Promise<BatchCreateResult>;
+    private buildQuery;
+}
+
+interface ApiKey {
+    readonly id: string;
+    readonly name: string;
+    readonly key_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';
+}
+interface CreateKeyResult extends ApiKey {
+    readonly key: string;
+}
+declare class KeysResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(params?: CreateKeyParams): Promise<CreateKeyResult>;
+    list(): Promise<ApiKey[]>;
+    revoke(keyId: string): Promise<void>;
+}
+
+/**
+ * optropic - OptropicClient
+ *
+ * The SDK interface for integrations with the Optropic API.
+ *
+ * @module optropic
+ */
+
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+type RequestFn = <T>(options: RequestOptions) => Promise<T>;
+/**
+ * OptropicClient - The SDK interface for Optropic API integrations.
+ *
+ * @example
+ * ```typescript
+ * import { OptropicClient } from 'optropic';
+ *
+ * const client = new OptropicClient({
+ *   apiKey: 'optr_live_xxxxxxxxxxxx',
+ * });
+ *
+ * // Create an asset
+ * const asset = await client.assets.create({
+ *   gtin: '01234567890123',
+ *   serial: 'SN001',
+ * });
+ *
+ * // Verify an asset
+ * const result = await client.assets.verify(asset.id);
+ * ```
+ */
+declare class OptropicClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly retryConfig;
+    readonly assets: AssetsResource;
+    readonly keys: KeysResource;
+    constructor(config: OptropicConfig);
+    private isValidApiKey;
+    private request;
+    private executeRequest;
+    private sleep;
+}
+/**
+ * Create an OptropicClient instance.
+ *
+ * @param config - Client configuration
+ * @returns Configured OptropicClient
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'optropic';
+ *
+ * const client = createClient({
+ *   apiKey: process.env.OPTROPIC_API_KEY!,
+ * });
+ * ```
+ */
+declare function createClient(config: OptropicConfig): OptropicClient;
+
+/**
+ * optropic - Error Classes
+ *
+ * Clear, actionable errors for API integrations.
+ * Each error includes a code for programmatic handling
+ * and a human-readable message.
+ *
+ * @module optropic
+ */
+
+/**
+ * Base error class for all Optropic SDK errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.verify(scanData);
+ * } catch (error) {
+ *   if (error instanceof OptropicError) {
+ *     console.log('Error code:', error.code);
+ *     console.log('Message:', error.message);
+ *     if (error.retryable) {
+ *       // Implement retry logic
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class OptropicError extends Error {
+    /**
+     * Error code for programmatic handling.
+     */
+    readonly code: ErrorCode;
+    /**
+     * HTTP status code (if applicable).
+     */
+    readonly statusCode?: number;
+    /**
+     * Whether this error can be retried.
+     */
+    readonly retryable: boolean;
+    /**
+     * Additional details about the error.
+     */
+    readonly details?: Record<string, unknown>;
+    /**
+     * Request ID for support reference.
+     */
+    readonly requestId?: string;
+    constructor(code: ErrorCode, message: string, options?: {
+        statusCode?: number;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        requestId?: string;
+        cause?: Error;
+    });
+    /**
+     * Create a JSON-serializable representation.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when API key authentication fails.
+ *
+ * Common causes:
+ * - Invalid API key format
+ * - Expired API key
+ * - Revoked API key
+ * - Wrong environment (using test key in production)
+ */
+declare class AuthenticationError extends OptropicError {
+    constructor(message?: string, options?: {
+        code?: ErrorCode;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a serial number is invalid.
+ *
+ * Serial numbers must:
+ * - Be non-empty
+ * - Not exceed 20 characters (GS1 limit)
+ * - Contain only allowed characters
+ */
+declare class InvalidSerialError extends OptropicError {
+    /**
+     * The invalid serial that was provided.
+     */
+    readonly serial: string;
+    constructor(serial: string, message?: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a GTIN is invalid.
+ */
+declare class InvalidGTINError extends OptropicError {
+    /**
+     * The invalid GTIN that was provided.
+     */
+    readonly gtin: string;
+    constructor(gtin: string, message?: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a code format is invalid.
+ */
+declare class InvalidCodeError extends OptropicError {
+    /**
+     * The invalid code that was provided.
+     */
+    readonly invalidCode: string;
+    constructor(invalidCode: string, message?: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a code has been revoked.
+ *
+ * Revocation reasons include:
+ * - Confirmed counterfeit
+ * - Product recall
+ * - Duplicate detection
+ * - Manual revocation by brand
+ */
+declare class RevokedCodeError extends OptropicError {
+    /**
+     * The revoked code.
+     */
+    readonly revokedCode: string;
+    /**
+     * Reason for revocation.
+     */
+    readonly reason: string;
+    /**
+     * When the code was revoked.
+     */
+    readonly revokedAt: string;
+    constructor(code: string, reason: string, revokedAt: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a code is not found.
+ */
+declare class CodeNotFoundError extends OptropicError {
+    /**
+     * The code that was not found.
+     */
+    readonly searchedCode: string;
+    constructor(code: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a batch is not found.
+ */
+declare class BatchNotFoundError extends OptropicError {
+    /**
+     * The batch ID that was not found.
+     */
+    readonly batchId: string;
+    constructor(batchId: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when rate limit is exceeded.
+ *
+ * Rate limits are per-client and may vary by vertical policy.
+ * Check `retryAfter` for when to retry.
+ */
+declare class RateLimitedError extends OptropicError {
+    /**
+     * Seconds until rate limit resets.
+     */
+    readonly retryAfter: number;
+    /**
+     * Current rate limit (requests per period).
+     */
+    readonly limit: number;
+    /**
+     * Remaining requests in current period.
+     */
+    readonly remaining: number;
+    constructor(retryAfter: number, options?: {
+        limit?: number;
+        remaining?: number;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when quota is exceeded.
+ */
+declare class QuotaExceededError extends OptropicError {
+    /**
+     * Current quota limit.
+     */
+    readonly quotaLimit: number;
+    /**
+     * Quota used.
+     */
+    readonly quotaUsed: number;
+    /**
+     * When quota resets (ISO 8601).
+     */
+    readonly resetsAt: string;
+    constructor(quotaLimit: number, quotaUsed: number, resetsAt: string, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a network error occurs.
+ */
+declare class NetworkError extends OptropicError {
+    constructor(message?: string, options?: {
+        cause?: Error;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when a request times out.
+ */
+declare class TimeoutError extends OptropicError {
+    /**
+     * Timeout duration in milliseconds.
+     */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, options?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+/**
+ * Error thrown when service is unavailable.
+ */
+declare class ServiceUnavailableError extends OptropicError {
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    });
+}
+
+declare const SDK_VERSION = "1.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 };