@hauska-sdk/core 0.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,398 @@
+# Troubleshooting
+
+Common issues and solutions when using the CNS Protocol Core SDK.
+
+## Configuration Issues
+
+### "VDA configuration is required"
+
+**Problem:** SDK initialization fails with configuration error.
+
+**Solutions:**
+1. Ensure `vda` configuration is provided:
+   ```typescript
+   const sdk = new CNSSDK({
+     vda: {
+       storageAdapter: new PostgreSQLStorageAdapter({ /* ... */ }),
+     },
+     // ... other config
+   });
+   ```
+
+2. Check that `storageAdapter` is properly initialized.
+
+### "Pinata configuration is required"
+
+**Problem:** Retrieval SDK requires Pinata configuration.
+
+**Solutions:**
+1. Provide Pinata JWT token:
+   ```typescript
+   retrieval: {
+     pinata: {
+       pinataJwt: process.env.PINATA_JWT!,
+       pinataGateway: "https://gateway.pinata.cloud",
+     },
+   }
+   ```
+
+2. Verify your Pinata JWT token is valid.
+
+### "VDA storage adapter is required"
+
+**Problem:** Storage adapter not configured.
+
+**Solutions:**
+1. Install and configure a storage adapter:
+   ```bash
+   npm install @hauska-sdk/adapters-storage-postgres
+   ```
+
+2. Initialize the adapter:
+   ```typescript
+   import { PostgreSQLStorageAdapter } from "@hauska-sdk/adapters-storage-postgres";
+   
+   const storageAdapter = new PostgreSQLStorageAdapter({
+     connectionString: process.env.DATABASE_URL!,
+   });
+   ```
+
+## Wallet Issues
+
+### "Wallet not found" or "Wallet creation failed"
+
+**Problem:** Wallet operations fail.
+
+**Solutions:**
+1. Ensure `userId` is provided and not empty:
+   ```typescript
+   await sdk.getOrCreateWallet({
+     userId: "user-123", // Must not be empty
+     password: "secure-password",
+   });
+   ```
+
+2. Check password is correct for existing wallets.
+
+3. Verify wallet manager is properly initialized.
+
+### "Wallet decryption failed"
+
+**Problem:** Cannot decrypt wallet with provided password.
+
+**Solutions:**
+1. Verify the password is correct.
+
+2. Check if wallet was created with a different password.
+
+3. Ensure wallet data hasn't been corrupted.
+
+## VDA Issues
+
+### "VDA not found"
+
+**Problem:** Cannot find VDA by ID.
+
+**Solutions:**
+1. Verify the VDA ID is correct.
+
+2. Check that the VDA exists in storage:
+   ```typescript
+   const vda = await sdk.getVDASDK().getVDA(vdaId);
+   if (!vda) {
+     console.log("VDA not found");
+   }
+   ```
+
+3. Ensure storage adapter is properly connected.
+
+### "VDA access denied"
+
+**Problem:** Access denied when trying to access a VDA.
+
+**Solutions:**
+1. Verify wallet owns the VDA:
+   ```typescript
+   const verification = await sdk.getVDASDK().verifyOwnership(
+     vdaId,
+     wallet.address,
+     ["view"]
+   );
+   ```
+
+2. Check if access pass exists and hasn't expired:
+   ```typescript
+   const accessPasses = await sdk.getVDASDK().listAccessPassesByOwner(wallet.address);
+   ```
+
+3. Verify access pass hasn't been revoked.
+
+### "Invalid VDA metadata"
+
+**Problem:** VDA minting fails due to invalid metadata.
+
+**Solutions:**
+1. Ensure at least one universal metadata key is provided:
+   - `address` (real estate)
+   - `legalDesc` (real estate)
+   - `patientId` (healthcare)
+   - `api14` (oil & gas)
+
+2. Verify `spoke` is a valid spoke type.
+
+3. Check that `assetType` is valid.
+
+## Document Retrieval Issues
+
+### "Document not found"
+
+**Problem:** Cannot retrieve document from IPFS.
+
+**Solutions:**
+1. Verify the CID is correct.
+
+2. Check that the document exists in Pinata:
+   ```typescript
+   const metadata = await sdk.getRetrievalSDK().getPinataClient().getFileMetadata(cid);
+   ```
+
+3. Ensure Pinata gateway is accessible.
+
+### "Access denied" to document
+
+**Problem:** Cannot access document even though VDA exists.
+
+**Solutions:**
+1. Verify wallet has access to the VDA:
+   ```typescript
+   const verification = await sdk.getRetrievalSDK().verifyAccess(
+     cid,
+     wallet.address,
+     ["view"]
+   );
+   ```
+
+2. Check that VDA has `ipfsCid` metadata set:
+   ```typescript
+   const vda = await sdk.getVDASDK().getVDA(vdaId);
+   console.log("IPFS CID:", vda.metadata.ipfsCid);
+   ```
+
+3. Provide `getVDAIdFromCID` function if VDA lookup fails:
+   ```typescript
+   retrieval: {
+     // ... config
+     getVDAIdFromCID: async (cid: string) => {
+       const vda = await storageAdapter.getVDAByCID(cid);
+       return vda?.id || null;
+     },
+   }
+   ```
+
+### "Encryption key required for decryption"
+
+**Problem:** Document is encrypted but no encryption key provided.
+
+**Solutions:**
+1. Provide encryption key in config:
+   ```typescript
+   retrieval: {
+     // ... config
+     getEncryptionKey: async (cid: string) => {
+       // Retrieve encryption key from secure storage
+       return await getKeyFromDatabase(cid);
+     },
+   }
+   ```
+
+2. Store encryption key when uploading:
+   ```typescript
+   const result = await sdk.getRetrievalSDK().uploadDocument(content, {
+     encrypt: true,
+   });
+   
+   // Store encryption key securely
+   await storeEncryptionKey(result.cid, result.encryptionKey!);
+   ```
+
+### "VDA ID not found for CID"
+
+**Problem:** Cannot resolve VDA ID from document CID.
+
+**Solutions:**
+1. Ensure VDA has `ipfsCid` metadata:
+   ```typescript
+   const vda = await sdk.getVDASDK().mint({
+     // ... params
+     ipfsCid: documentCID, // Link VDA to document
+   });
+   ```
+
+2. Provide custom `getVDAIdFromCID` function:
+   ```typescript
+   retrieval: {
+     getVDAIdFromCID: async (cid: string) => {
+       // Query database or Pinata metadata
+       const vda = await db.query("SELECT id FROM vdas WHERE ipfs_cid = $1", [cid]);
+       return vda?.id || null;
+     },
+   }
+   ```
+
+## Payment Issues
+
+### "Payment verification failed"
+
+**Problem:** Crypto payment verification fails.
+
+**Solutions:**
+1. Verify transaction hash is correct.
+
+2. Check that transaction is confirmed on blockchain.
+
+3. Ensure facilitator wallet address is correct.
+
+4. Verify amount and currency match.
+
+### "Payment not found"
+
+**Problem:** Cannot find payment record.
+
+**Solutions:**
+1. Verify `resourceId` is correct.
+
+2. Check that payment was recorded:
+   ```typescript
+   const payment = await sdk.getPaymentSDK().getPayment(resourceId);
+   ```
+
+3. Ensure storage adapter is properly connected.
+
+## Network and Performance Issues
+
+### Slow document retrieval
+
+**Problem:** Document retrieval is slow.
+
+**Solutions:**
+1. Use Redis caching adapter:
+   ```typescript
+   import { RedisStorageAdapter } from "@hauska-sdk/adapters-storage-redis";
+   
+   const redisAdapter = new RedisStorageAdapter({
+     redis: process.env.REDIS_URL!,
+     primaryStorageAdapter: postgresAdapter,
+   });
+   ```
+
+2. Check Pinata gateway performance.
+
+3. Consider using a CDN for frequently accessed documents.
+
+### Connection timeouts
+
+**Problem:** Database or IPFS connection timeouts.
+
+**Solutions:**
+1. Check database connection string.
+
+2. Verify network connectivity to Pinata.
+
+3. Increase timeout settings if needed.
+
+4. Check firewall rules.
+
+## Error Handling
+
+### Understanding Error Types
+
+All SDK errors extend `SDKError` and include:
+- `code` - Error code for programmatic handling
+- `context` - Additional context about the error
+- `statusCode` - HTTP status code (if applicable)
+- `retryable` - Whether the error is retryable
+
+### 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 Best Practices
+
+```typescript
+import { 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 (isRetryableError(error)) {
+      // Implement retry logic
+      await retryOperation();
+    }
+  } else {
+    // Handle unexpected errors
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Debugging
+
+### Enable Logging
+
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  logHook: (level, message, data) => {
+    console.log(`[${level}] ${message}`, data);
+  },
+});
+```
+
+### Enable Metrics
+
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  metricsHook: (event, data) => {
+    console.log(`[METRICS] ${event}`, data);
+  },
+});
+```
+
+### Check SDK State
+
+```typescript
+// Verify SDK is initialized
+console.log("Payment SDK:", sdk.getPaymentSDK());
+console.log("VDA SDK:", sdk.getVDASDK());
+console.log("Retrieval SDK:", sdk.getRetrievalSDK());
+console.log("Wallet Manager:", sdk.getWalletManager());
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. Check the [API Reference](./api-reference.md) for detailed API documentation
+2. Review the [Examples](./examples.md) for usage patterns
+3. Open an issue on GitHub with:
+   - Error message and stack trace
+   - SDK configuration (without secrets)
+   - Steps to reproduce
+   - Expected vs actual behavior
+
+## Related Documentation
+
+- [Getting Started Guide](./getting-started.md)
+- [API Reference](./api-reference.md)
+- [Examples](./examples.md)

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@hauska-sdk/core",
+  "version": "0.1.0",
+  "description": "CNS Protocol Core SDK - Unified SDK for Payment, VDA, and Document Retrieval",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hauska-sdk/payment": "^0.1.0",
+    "@hauska-sdk/retrieval": "^0.1.0",
+    "@hauska-sdk/vda": "^0.1.0",
+    "@hauska-sdk/wallet": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hauska-sdk/adapters-storage-mock": "^0.1.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
+  },
+  "keywords": [
+    "cns-protocol",
+    "sdk",
+    "payment",
+    "vda",
+    "ipfs",
+    "blockchain",
+    "ethereum",
+    "base",
+    "verified-digital-assets",
+    "document-retrieval",
+    "access-control"
+  ],
+  "author": "Hauska SDK Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hauska-sdk/hauska-sdk.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/hauska-sdk/hauska-sdk/issues"
+  },
+  "homepage": "https://github.com/hauska-sdk/hauska-sdk#readme",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}