@hauska-sdk/core 0.1.0

package/docs/examples.md

@@ -0,0 +1,362 @@
+# Examples
+
+Real-world usage examples for the CNS Protocol Core SDK.
+
+## Complete Flow Examples
+
+The SDK includes complete flow examples demonstrating end-to-end usage:
+
+### Architect Invoice Flow
+
+Complete flow for an architect invoicing scenario: invoice creation → payment → blueprint transfer.
+
+```typescript
+import { architectInvoiceFlow } from "@hauska-sdk/core/examples/architect-invoice-flow";
+
+const result = await architectInvoiceFlow();
+// Returns: { architectWallet, clientWallet, blueprintVDA, invoiceVDA, blueprintCID }
+```
+
+**Flow:**
+1. Architect creates invoice and uploads blueprint
+2. Client makes payment
+3. Payment is verified
+4. Blueprint VDA is transferred to client
+5. Client retrieves blueprint
+
+### Data Room Flow
+
+Complete flow for creating a data room with access control.
+
+```typescript
+import { dataRoomFlow } from "@hauska-sdk/core/examples/data-room-flow";
+
+const result = await dataRoomFlow();
+// Returns: { ownerWallet, buyerWallet, dataRoomVDA, accessPass, documentCID, titleReportCID }
+```
+
+**Flow:**
+1. Property owner creates data room VDA
+2. Uploads property documents to IPFS
+3. Creates access pass for potential buyer
+4. Buyer accesses documents with access pass
+5. Owner can revoke access pass
+
+### Healthcare Patient Flow
+
+Complete flow for healthcare patient record management.
+
+```typescript
+import { healthcarePatientFlow } from "@hauska-sdk/core/examples/healthcare-patient-flow";
+
+const result = await healthcarePatientFlow();
+// Returns: { patientWallet, doctorWallet, healthRecordVDA, accessPass, recordsCID, totalRecords }
+```
+
+**Flow:**
+1. Patient creates health record VDA
+2. Uploads encrypted medical records
+3. Grants doctor temporary access (24 hours)
+4. Doctor accesses records with access pass
+5. Search all records for patient
+
+### Real Estate Property Flow
+
+Complete flow for a real estate property transaction.
+
+```typescript
+import { realEstatePropertyFlow } from "@hauska-sdk/core/examples/real-estate-property-flow";
+
+const result = await realEstatePropertyFlow();
+// Returns: { ownerWallet, buyerWallet, propertyVDA, viewingAccessPass, purchasePayment, transferredProperty, documentCID, searchResults }
+```
+
+**Flow:**
+1. Property owner lists property
+2. Buyer views property (creates data room access)
+3. Buyer makes payment
+4. Property VDA is transferred to buyer
+5. Buyer now owns the property VDA
+6. Search property by address
+
+## Common Patterns
+
+### Pattern 1: Create and Share Document
+
+```typescript
+// 1. Create data room with document
+const dataRoom = await sdk.createDataRoom({
+  ownerWallet: { userId: "owner", password: "pass" },
+  vdaParams: {
+    assetType: "deed",
+    address: "123 Main St",
+    spoke: "real-estate",
+  },
+  document: {
+    content: Buffer.from("Property documents..."),
+    name: "property-deed.pdf",
+    encrypt: true,
+  },
+});
+
+// 2. Create access pass for recipient
+const accessPass = await sdk.getVDASDK().createAccessPass({
+  grantorWallet: ownerWallet.address,
+  recipientWallet: recipientWallet.address,
+  accessibleVDAs: [dataRoom.vda.id],
+  permissions: ["view", "download"],
+  expiry: Date.now() + 30 * 24 * 3600000, // 30 days
+  spoke: "real-estate",
+  address: "123 Main St",
+});
+
+// 3. Recipient retrieves document
+const document = await sdk.retrieveDocument({
+  wallet: { userId: "recipient", password: "pass" },
+  cid: dataRoom.document!.cid,
+  requiredPermissions: ["view"],
+  decrypt: true,
+  watermark: true, // Watermarked for access pass viewer
+});
+```
+
+### Pattern 2: Purchase and Transfer
+
+```typescript
+// 1. Purchase and mint VDA
+const purchase = await sdk.purchaseAndMintVDA({
+  wallet: { userId: "buyer", password: "pass" },
+  amount: "5000",
+  currency: "USDC",
+  method: "crypto",
+  vdaParams: {
+    assetType: "blueprint",
+    address: "123 Main St",
+    spoke: "architect",
+  },
+});
+
+// 2. Transfer VDA to buyer
+await sdk.getVDASDK().transferOwnership({
+  vdaId: originalVDA.id,
+  currentOwner: sellerWallet.address,
+  newOwner: buyerWallet.address,
+});
+```
+
+### Pattern 3: Search and Filter
+
+```typescript
+// Search by address
+const results = await sdk.getVDASDK().searchByAddress("Main St", {
+  limit: 10,
+  offset: 0,
+});
+
+// Search by patient ID
+const patientRecords = await sdk.getVDASDK().searchByPatientId("PATIENT-12345");
+
+// Search by API14
+const oilRecords = await sdk.getVDASDK().searchByAPI14("42-123-45678-00-00");
+```
+
+### Pattern 4: Access Control
+
+```typescript
+// Verify access before retrieving
+const accessVerification = await sdk.getRetrievalSDK().verifyAccess(
+  documentCID,
+  wallet.address,
+  ["view", "download"]
+);
+
+if (accessVerification.hasAccess) {
+  console.log(`Access granted via: ${accessVerification.accessType}`);
+  const document = await sdk.retrieveDocument({
+    wallet: { userId: "user", password: "pass" },
+    cid: documentCID,
+    requiredPermissions: ["view"],
+    decrypt: true,
+  });
+} else {
+  console.log(`Access denied: ${accessVerification.reason}`);
+}
+```
+
+### Pattern 5: Error Handling
+
+```typescript
+import {
+  SDKError,
+  PaymentError,
+  VDAError,
+  RetrievalError,
+  isSDKError,
+} from "@hauska-sdk/core";
+
+try {
+  await sdk.purchaseAndMintVDA({ /* ... */ });
+} catch (error) {
+  if (isSDKError(error)) {
+    switch (error.code) {
+      case "PAYMENT_VERIFICATION_FAILED":
+        // Handle payment verification failure
+        break;
+      case "VDA_NOT_FOUND":
+        // Handle VDA not found
+        break;
+      default:
+        console.error("SDK error:", error.message, error.context);
+    }
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+### Pattern 6: Logging and Monitoring
+
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  logHook: (level, message, data) => {
+    // Send to your logging service
+    logger[level](message, data);
+  },
+  metricsHook: (event, data) => {
+    // Send to your analytics service
+    analytics.track(event, {
+      ...data,
+      timestamp: Date.now(),
+    });
+  },
+});
+```
+
+## Integration Examples
+
+### Express.js Integration
+
+```typescript
+import express from "express";
+import { CNSSDK } from "@hauska-sdk/core";
+
+const app = express();
+const sdk = new CNSSDK({ /* ... config */ });
+
+// Create data room endpoint
+app.post("/api/data-rooms", async (req, res) => {
+  try {
+    const dataRoom = await sdk.createDataRoom({
+      ownerWallet: {
+        userId: req.user.id,
+        password: req.body.password,
+      },
+      vdaParams: {
+        assetType: "deed",
+        address: req.body.address,
+        spoke: "real-estate",
+      },
+      document: {
+        content: Buffer.from(req.body.document),
+        encrypt: true,
+      },
+    });
+    
+    res.json({ dataRoom });
+  } catch (error) {
+    if (isSDKError(error)) {
+      res.status(error.statusCode || 500).json({ error: error.message });
+    } else {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+});
+
+// Retrieve document endpoint
+app.get("/api/documents/:cid", async (req, res) => {
+  try {
+    const document = await sdk.retrieveDocument({
+      wallet: {
+        userId: req.user.id,
+        password: req.body.password,
+      },
+      cid: req.params.cid,
+      requiredPermissions: ["view"],
+      decrypt: true,
+    });
+    
+    res.setHeader("Content-Type", "application/pdf");
+    res.send(document);
+  } catch (error) {
+    if (error instanceof RetrievalError) {
+      res.status(error.statusCode || 404).json({ error: error.message });
+    } else {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+});
+```
+
+### Next.js API Route
+
+```typescript
+// pages/api/vdas/mint.ts
+import { CNSSDK } from "@hauska-sdk/core";
+import type { NextApiRequest, NextApiResponse } from "next";
+
+const sdk = new CNSSDK({ /* ... config */ });
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "Method not allowed" });
+  }
+
+  try {
+    const vda = await sdk.getVDASDK().mint({
+      assetType: req.body.assetType,
+      ownerWallet: req.body.ownerWallet,
+      spoke: req.body.spoke,
+      address: req.body.address,
+    });
+
+    res.status(200).json({ vda });
+  } catch (error) {
+    if (isSDKError(error)) {
+      res.status(error.statusCode || 500).json({ error: error.message });
+    } else {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+}
+```
+
+## Running Examples
+
+To run the complete flow examples:
+
+```bash
+# Install dependencies
+npm install
+
+# Run architect invoice flow
+npx ts-node packages/core/examples/architect-invoice-flow.ts
+
+# Run data room flow
+npx ts-node packages/core/examples/data-room-flow.ts
+
+# Run healthcare patient flow
+npx ts-node packages/core/examples/healthcare-patient-flow.ts
+
+# Run real estate property flow
+npx ts-node packages/core/examples/real-estate-property-flow.ts
+```
+
+## Next Steps
+
+- Read the [API Reference](./api-reference.md) for complete API documentation
+- Check the [Getting Started Guide](./getting-started.md) for setup instructions
+- See [Troubleshooting](./troubleshooting.md) for common issues

package/docs/getting-started.md

@@ -0,0 +1,265 @@
+# Getting Started with CNS Protocol Core SDK
+
+This guide will help you get started with the CNS Protocol Core SDK in minutes.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- TypeScript 5.3+ (recommended)
+- A Pinata account (for IPFS storage)
+- PostgreSQL database (or use Mock adapter for testing)
+- Base L2 RPC endpoint (for blockchain operations)
+
+## Installation
+
+```bash
+npm install @hauska-sdk/core
+```
+
+## Basic Setup
+
+### 1. Install Required Adapters
+
+```bash
+# For production (PostgreSQL)
+npm install @hauska-sdk/adapters-storage-postgres
+
+# For testing (Mock)
+npm install @hauska-sdk/adapters-storage-mock
+
+# For blockchain operations
+npm install @hauska-sdk/adapters-blockchain-ethers
+```
+
+### 2. Initialize the SDK
+
+```typescript
+import { CNSSDK } from "@hauska-sdk/core";
+import { PostgreSQLStorageAdapter } from "@hauska-sdk/adapters-storage-postgres";
+
+const sdk = new CNSSDK({
+  vda: {
+    storageAdapter: new PostgreSQLStorageAdapter({
+      connectionString: process.env.DATABASE_URL!,
+    }),
+  },
+  payment: {
+    storage: new PostgreSQLStorageAdapter({
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    blockchain: {
+      chain: "base",
+      token: "USDC",
+      facilitatorWallet: process.env.FACILITATOR_WALLET!,
+      baseRpcUrl: process.env.BASE_RPC_URL!,
+    },
+  },
+  retrieval: {
+    pinata: {
+      pinataJwt: process.env.PINATA_JWT!,
+      pinataGateway: "https://gateway.pinata.cloud",
+    },
+  },
+});
+```
+
+### 3. Environment Variables
+
+Create a `.env` file:
+
+```env
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/cns_protocol
+
+# Pinata (IPFS)
+PINATA_JWT=your_pinata_jwt_token
+
+# Blockchain
+FACILITATOR_WALLET=0xYourFacilitatorWalletAddress
+BASE_RPC_URL=https://mainnet.base.org
+
+# Optional: Logging
+LOG_LEVEL=info
+```
+
+## Your First VDA
+
+Let's create your first Verified Digital Asset:
+
+```typescript
+// Get or create a wallet for the user
+const wallet = await sdk.getOrCreateWallet({
+  userId: "user-123",
+  password: "secure-password",
+});
+
+// Mint a VDA
+const vda = await sdk.getVDASDK().mint({
+  assetType: "deed",
+  ownerWallet: wallet.address,
+  address: "123 Main St, Schertz, TX 78154",
+  legalDesc: "Lot 5, Block 3",
+  spoke: "real-estate",
+});
+
+console.log(`VDA created: ${vda.id}`);
+console.log(`Owner: ${vda.metadata.ownerWallet}`);
+```
+
+## Your First Data Room
+
+Create a data room with an encrypted document:
+
+```typescript
+const dataRoom = await sdk.createDataRoom({
+  ownerWallet: {
+    userId: "owner-123",
+    password: "owner-password",
+  },
+  vdaParams: {
+    assetType: "deed",
+    address: "123 Main St, Schertz, TX 78154",
+    legalDesc: "Lot 5, Block 3",
+    spoke: "real-estate",
+  },
+  document: {
+    content: Buffer.from("Property deed content..."),
+    name: "property-deed.pdf",
+    encrypt: true, // Encrypt before uploading to IPFS
+  },
+});
+
+console.log(`Data room VDA: ${dataRoom.vda.id}`);
+console.log(`Document CID: ${dataRoom.document?.cid}`);
+```
+
+## Grant Access with Access Pass
+
+Create an access pass to grant temporary access:
+
+```typescript
+const accessPass = await sdk.getVDASDK().createAccessPass({
+  grantorWallet: ownerWallet.address,
+  recipientWallet: buyerWallet.address,
+  accessibleVDAs: [dataRoom.vda.id],
+  permissions: ["view", "download"],
+  expiry: Date.now() + 30 * 24 * 3600000, // 30 days
+  spoke: "real-estate",
+  address: "123 Main St, Schertz, TX 78154",
+});
+
+console.log(`Access pass created: ${accessPass.id}`);
+console.log(`Expires: ${new Date(accessPass.metadata.expiry!)}`);
+```
+
+## Retrieve a Document
+
+Retrieve a document with access control:
+
+```typescript
+const document = await sdk.retrieveDocument({
+  wallet: {
+    userId: "buyer-456",
+    password: "buyer-password",
+  },
+  cid: dataRoom.document!.cid,
+  requiredPermissions: ["view"],
+  decrypt: true,
+  watermark: true, // Watermark for access pass viewers
+});
+
+console.log(`Document retrieved: ${document.length} bytes`);
+```
+
+## Complete Example: Real Estate Flow
+
+Here's a complete example of a real estate property flow:
+
+```typescript
+import { CNSSDK } from "@hauska-sdk/core";
+import { PostgreSQLStorageAdapter } from "@hauska-sdk/adapters-storage-postgres";
+
+const sdk = new CNSSDK({
+  // ... config
+});
+
+// 1. Property owner creates data room
+const dataRoom = await sdk.createDataRoom({
+  ownerWallet: { userId: "owner", password: "pass" },
+  vdaParams: {
+    assetType: "deed",
+    address: "123 Main St",
+    spoke: "real-estate",
+  },
+  document: {
+    content: Buffer.from("Property documents..."),
+    encrypt: true,
+  },
+});
+
+// 2. Create access pass for buyer
+await sdk.getVDASDK().createAccessPass({
+  grantorWallet: ownerWallet.address,
+  recipientWallet: buyerWallet.address,
+  accessibleVDAs: [dataRoom.vda.id],
+  permissions: ["view"],
+  expiry: Date.now() + 7 * 24 * 3600000, // 7 days
+  spoke: "real-estate",
+  address: "123 Main St",
+});
+
+// 3. Buyer makes payment
+const purchase = await sdk.purchaseAndMintVDA({
+  wallet: { userId: "buyer", password: "pass" },
+  amount: "250000",
+  currency: "USDC",
+  method: "crypto",
+  vdaParams: {
+    assetType: "invoice",
+    address: "123 Main St",
+    spoke: "real-estate",
+  },
+});
+
+// 4. Transfer property to buyer
+await sdk.getVDASDK().transferOwnership({
+  vdaId: dataRoom.vda.id,
+  currentOwner: ownerWallet.address,
+  newOwner: buyerWallet.address,
+});
+```
+
+## Next Steps
+
+- Read the [API Reference](./api-reference.md) for complete API documentation
+- Check out [Examples](./examples.md) for more use cases
+- See [Troubleshooting](./troubleshooting.md) for common issues
+
+## Testing
+
+For testing, use the Mock storage adapter:
+
+```typescript
+import { MockStorageAdapter } from "@hauska-sdk/adapters-storage-mock";
+
+const sdk = new CNSSDK({
+  vda: {
+    storageAdapter: new MockStorageAdapter(),
+  },
+  payment: {
+    storage: new MockStorageAdapter(),
+  },
+  retrieval: {
+    pinata: {
+      pinataJwt: "test-jwt",
+      pinataGateway: "https://gateway.pinata.cloud",
+    },
+  },
+});
+```
+
+## Need Help?
+
+- Check the [Troubleshooting Guide](./troubleshooting.md)
+- Review the [API Reference](./api-reference.md)
+- Open an issue on GitHub