@hauska-sdk/core 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,433 @@
+# API Reference
+
+Complete API documentation for the CNS Protocol Core SDK.
+
+## CNSSDK
+
+The main class for the unified CNS Protocol SDK.
+
+### Constructor
+
+```typescript
+new CNSSDK(config: CNSSDKConfig)
+```
+
+**Parameters:**
+- `config` - SDK configuration object
+
+**Example:**
+```typescript
+const sdk = new CNSSDK({
+  vda: {
+    storageAdapter: new PostgreSQLStorageAdapter({ /* ... */ }),
+  },
+  payment: {
+    storage: new PostgreSQLStorageAdapter({ /* ... */ }),
+  },
+  retrieval: {
+    pinata: {
+      pinataJwt: process.env.PINATA_JWT!,
+    },
+  },
+});
+```
+
+### Methods
+
+#### `getOrCreateWallet(options: WalletOptions): Promise<Wallet>`
+
+Gets or creates a wallet for a user.
+
+**Parameters:**
+- `options.userId` - User ID (required)
+- `options.password` - Password for wallet encryption (required)
+- `options.autoCreate` - Whether to create wallet if it doesn't exist (default: `true`)
+
+**Returns:** `Promise<Wallet>`
+
+**Throws:** `WalletError` if wallet creation fails
+
+**Example:**
+```typescript
+const wallet = await sdk.getOrCreateWallet({
+  userId: "user-123",
+  password: "secure-password",
+});
+```
+
+#### `purchaseAndMintVDA(options: PurchaseAndMintVDAOptions): Promise<{payment: PaymentRecord, vda: VDA, wallet: {address: string}}>`
+
+Purchases and mints a VDA in a single operation.
+
+**Parameters:**
+- `options.wallet` - Wallet options
+- `options.amount` - Payment amount (string)
+- `options.currency` - Payment currency (e.g., "USDC")
+- `options.method` - Payment method ("crypto" | "fiat")
+- `options.vdaParams` - VDA minting parameters
+- `options.paymentMetadata` - Optional payment metadata
+- `options.vdaMetadata` - Optional VDA metadata
+
+**Returns:** `Promise<{payment: PaymentRecord, vda: VDA, wallet: {address: string}}>`
+
+**Throws:** `PaymentError` or `VDAError` on failure
+
+**Example:**
+```typescript
+const result = await sdk.purchaseAndMintVDA({
+  wallet: { userId: "user", password: "pass" },
+  amount: "5000",
+  currency: "USDC",
+  method: "crypto",
+  vdaParams: {
+    assetType: "blueprint",
+    address: "123 Main St",
+    spoke: "architect",
+  },
+});
+```
+
+#### `createDataRoom(options: CreateDataRoomOptions): Promise<{vda: VDA, document?: UploadDocumentResult, accessPass?: VDA}>`
+
+Creates a data room (VDA + optional document + optional access pass).
+
+**Parameters:**
+- `options.ownerWallet` - Wallet options for the owner
+- `options.vdaParams` - VDA parameters
+- `options.document` - Optional document to upload
+- `options.accessPass` - Optional access pass configuration
+
+**Returns:** `Promise<{vda: VDA, document?: UploadDocumentResult, accessPass?: VDA}>`
+
+**Throws:** `VDAError` or `RetrievalError` on failure
+
+**Example:**
+```typescript
+const dataRoom = await sdk.createDataRoom({
+  ownerWallet: { userId: "owner", password: "pass" },
+  vdaParams: {
+    assetType: "deed",
+    address: "123 Main St",
+    spoke: "real-estate",
+  },
+  document: {
+    content: Buffer.from("..."),
+    encrypt: true,
+  },
+  accessPass: {
+    recipientWallet: { userId: "buyer", password: "pass" },
+    permissions: ["view", "download"],
+    expiry: Date.now() + 30 * 24 * 3600000,
+  },
+});
+```
+
+#### `retrieveDocument(options: RetrieveDocumentOptions): Promise<Buffer>`
+
+Retrieves a document with full access control, decryption, and watermarking.
+
+**Parameters:**
+- `options.wallet` - Wallet options for the requester
+- `options.cid` - IPFS Content Identifier
+- `options.requiredPermissions` - Required permissions (default: `["view"]`)
+- `options.decrypt` - Whether to decrypt (default: `false`)
+- `options.watermark` - Whether to watermark (default: `false`)
+
+**Returns:** `Promise<Buffer>`
+
+**Throws:** `RetrievalError` if access is denied or document not found
+
+**Example:**
+```typescript
+const document = await sdk.retrieveDocument({
+  wallet: { userId: "user", password: "pass" },
+  cid: "QmTest123...",
+  requiredPermissions: ["view"],
+  decrypt: true,
+  watermark: true,
+});
+```
+
+#### `getPaymentSDK(): PaymentSDK`
+
+Gets the underlying Payment SDK instance.
+
+**Returns:** `PaymentSDK`
+
+#### `getVDASDK(): VDASDK`
+
+Gets the underlying VDA SDK instance.
+
+**Returns:** `VDASDK`
+
+#### `getRetrievalSDK(): RetrievalSDK`
+
+Gets the underlying Retrieval SDK instance.
+
+**Returns:** `RetrievalSDK`
+
+#### `getWalletManager(): WalletManager`
+
+Gets the wallet manager instance.
+
+**Returns:** `WalletManager`
+
+## Types
+
+### CNSSDKConfig
+
+SDK configuration object.
+
+```typescript
+interface CNSSDKConfig {
+  walletManager?: WalletManager;
+  payment?: Omit<PaymentSDKConfig, "walletManager">;
+  vda: Omit<VDASDKConfig, "walletManager">;
+  retrieval: Omit<RetrievalSDKConfig, "vdaSdk">;
+  logHook?: LogHook;
+  metricsHook?: MetricsHook;
+}
+```
+
+### WalletOptions
+
+Wallet creation/retrieval options.
+
+```typescript
+interface WalletOptions {
+  userId: string;
+  password: string;
+  autoCreate?: boolean;
+}
+```
+
+### PurchaseAndMintVDAOptions
+
+Options for purchasing and minting a VDA.
+
+```typescript
+interface PurchaseAndMintVDAOptions {
+  wallet: WalletOptions;
+  amount: string;
+  currency: string;
+  method: "crypto" | "fiat";
+  vdaParams: {
+    assetType: AssetType;
+    ownerWallet?: string;
+    spoke: SpokeType;
+    address?: string;
+    legalDesc?: string;
+    patientId?: string;
+    api14?: string;
+    [key: string]: any;
+  };
+  paymentMetadata?: Record<string, any>;
+  vdaMetadata?: Record<string, any>;
+}
+```
+
+### CreateDataRoomOptions
+
+Options for creating a data room.
+
+```typescript
+interface CreateDataRoomOptions {
+  ownerWallet: WalletOptions;
+  vdaParams: {
+    assetType: AssetType;
+    spoke: SpokeType;
+    address?: string;
+    legalDesc?: string;
+    patientId?: string;
+    api14?: string;
+    [key: string]: any;
+  };
+  document?: {
+    content: Buffer;
+    name?: string;
+    encrypt?: boolean;
+  };
+  accessPass?: {
+    recipientWallet: WalletOptions;
+    permissions: string[];
+    expiry: number;
+  };
+}
+```
+
+### RetrieveDocumentOptions
+
+Options for retrieving a document.
+
+```typescript
+interface RetrieveDocumentOptions {
+  wallet: WalletOptions;
+  cid: string;
+  requiredPermissions?: string[];
+  decrypt?: boolean;
+  watermark?: boolean;
+}
+```
+
+## Error Handling
+
+The SDK uses structured error types for better error handling.
+
+### Error Types
+
+#### SDKError
+
+Base error class for all SDK errors.
+
+```typescript
+class SDKError extends Error {
+  code: string;
+  context?: Record<string, any>;
+  statusCode?: number;
+  retryable: boolean;
+}
+```
+
+#### PaymentError
+
+Payment-related errors.
+
+```typescript
+class PaymentError extends SDKError {
+  // HTTP 402 status code
+}
+```
+
+#### VDAError
+
+VDA-related errors.
+
+```typescript
+class VDAError extends SDKError {
+  // HTTP 400 status code
+}
+```
+
+#### RetrievalError
+
+Retrieval-related errors.
+
+```typescript
+class RetrievalError extends SDKError {
+  // HTTP 404 status code
+}
+```
+
+#### WalletError
+
+Wallet-related errors.
+
+```typescript
+class WalletError extends SDKError {
+  // HTTP 401 status code
+}
+```
+
+#### ConfigurationError
+
+Configuration-related errors.
+
+```typescript
+class ConfigurationError extends SDKError {
+  // HTTP 500 status code
+}
+```
+
+### Error Codes
+
+Common error codes:
+
+- `PAYMENT_VERIFICATION_FAILED` - Payment verification failed
+- `VDA_NOT_FOUND` - VDA not found
+- `VDA_ACCESS_DENIED` - Access denied to VDA
+- `RETRIEVAL_DOCUMENT_NOT_FOUND` - Document not found
+- `RETRIEVAL_ACCESS_DENIED` - Access denied to document
+- `WALLET_NOT_FOUND` - Wallet not found
+- `CONFIG_MISSING_REQUIRED` - Required configuration missing
+
+### Error Handling Example
+
+```typescript
+import {
+  SDKError,
+  PaymentError,
+  VDAError,
+  RetrievalError,
+  isSDKError,
+  isRetryableError,
+} from "@hauska-sdk/core";
+
+try {
+  await sdk.purchaseAndMintVDA({ /* ... */ });
+} catch (error) {
+  if (isSDKError(error)) {
+    console.error(`Error code: ${error.code}`);
+    console.error(`Context:`, error.context);
+    
+    if (error instanceof PaymentError) {
+      // Handle payment error
+    } else if (error instanceof VDAError) {
+      // Handle VDA error
+    }
+    
+    if (isRetryableError(error)) {
+      // Retry logic
+    }
+  } else {
+    // Handle unexpected error
+  }
+}
+```
+
+## Logging and Monitoring
+
+### Log Hook
+
+```typescript
+type LogHook = (level: "info" | "warn" | "error", message: string, data?: any) => void;
+```
+
+**Example:**
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  logHook: (level, message, data) => {
+    console.log(`[${level}] ${message}`, data);
+  },
+});
+```
+
+### Metrics Hook
+
+```typescript
+type MetricsHook = (event: string, data?: Record<string, any>) => void;
+```
+
+**Example:**
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  metricsHook: (event, data) => {
+    analytics.track(event, data);
+  },
+});
+```
+
+**Common Events:**
+- `cns_sdk_initialized` - SDK initialized
+- `payment_sdk_initialized` - Payment SDK initialized
+- `vda_sdk_initialized` - VDA SDK initialized
+- `retrieval_sdk_initialized` - Retrieval SDK initialized
+- `wallet_retrieved_or_created` - Wallet operation
+
+## Related Documentation
+
+- [Payment SDK API](../payment/README.md)
+- [VDA SDK API](../vda/README.md)
+- [Retrieval SDK API](../retrieval/README.md)
+- [Wallet Management API](../wallet/README.md)