@hauska-sdk/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog - @hauska-sdk/core
+
+All notable changes to the Core SDK will be documented in this file.
+
+## [0.1.0] - 2025-02-03
+
+### Added
+- Initial release of unified CNS Protocol Core SDK
+- `CNSSDK` class combining Payment, VDA, Retrieval, and Wallet modules
+- Automatic wallet creation and management
+- `purchaseAndMintVDA()` method for combined payment and VDA minting
+- `createDataRoom()` method for creating VDAs with documents and access passes
+- `retrieveDocument()` method with full access control
+- Comprehensive error handling with custom error types (`SDKError`, `PaymentError`, `VDAError`, `RetrievalError`, `WalletError`, `ConfigurationError`)
+- Logging hooks (`LogHook`) for monitoring and debugging
+- Metrics hooks (`MetricsHook`) for analytics
+- Complete flow examples (architect invoice, data room, healthcare, real estate)
+- Full documentation (README, getting started, API reference, examples, troubleshooting)
+
+### Documentation
+- Comprehensive README with installation and quick start
+- Getting started guide with step-by-step setup
+- Complete API reference
+- Real-world usage examples
+- Troubleshooting guide
+
+---
+
+[0.1.0]: https://github.com/hauska-sdk/hauska-sdk/releases/tag/@hauska-sdk/core@0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @hauska-sdk/core
+
+**CNS Protocol Core SDK** - Unified SDK for Payment, VDA, and Document Retrieval
+
+The CNS Protocol Core SDK provides a single, unified interface for all CNS Protocol functionality, combining Payment, VDA (Verified Digital Assets), Document Retrieval, and Wallet Management into one easy-to-use package.
+
+## Installation
+
+```bash
+npm install @hauska-sdk/core
+```
+
+## Quick Start
+
+```typescript
+import { CNSSDK } from "@hauska-sdk/core";
+import { PostgreSQLStorageAdapter } from "@hauska-sdk/adapters-storage-postgres";
+
+// Initialize SDK
+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: "0xYourFacilitatorWallet",
+      baseRpcUrl: "https://mainnet.base.org",
+    },
+  },
+  retrieval: {
+    pinata: {
+      pinataJwt: process.env.PINATA_JWT!,
+      pinataGateway: "https://gateway.pinata.cloud",
+    },
+  },
+});
+
+// Create a data room with document
+const dataRoom = await sdk.createDataRoom({
+  ownerWallet: {
+    userId: "owner-123",
+    password: "secure-password",
+  },
+  vdaParams: {
+    assetType: "deed",
+    address: "123 Main St, Schertz, TX 78154",
+    spoke: "real-estate",
+  },
+  document: {
+    content: Buffer.from("Property documents..."),
+    name: "property-deed.pdf",
+    encrypt: true,
+  },
+  accessPass: {
+    recipientWallet: {
+      userId: "buyer-456",
+      password: "buyer-password",
+    },
+    permissions: ["view", "download"],
+    expiry: Date.now() + 30 * 24 * 3600000, // 30 days
+  },
+});
+
+console.log(`Data room created: ${dataRoom.vda.id}`);
+console.log(`Document uploaded: ${dataRoom.document?.cid}`);
+```
+
+## Features
+
+### 🎯 Unified API
+- Single entry point for all CNS Protocol functionality
+- Automatic wallet management
+- Seamless integration between Payment, VDA, and Retrieval modules
+
+### 💰 Payment Processing
+- HTTP 402 Payment Required protocol (x402)
+- Crypto payment verification (USDC on Base L2)
+- Fiat payment support (via Circle API)
+- Automatic payment recording and audit trails
+
+### 🏷️ VDA Management
+- Mint Verified Digital Assets (metadata-only ownership proofs)
+- Create and manage access passes
+- Transfer ownership
+- Cross-spoke search (real-estate, healthcare, architect, etc.)
+
+### 📄 Document Retrieval
+- IPFS document upload/download via Pinata
+- AES-256-GCM encryption
+- Gated access control (VDA ownership or access passes)
+- PDF watermarking for access pass viewers
+- Access logging and analytics
+
+### 🔐 Wallet Management
+- Automatic wallet creation per user
+- Secure wallet encryption
+- EIP-712 signing support
+
+## Core Concepts
+
+### Verified Digital Assets (VDAs)
+VDAs are metadata-only ownership proofs, not tokens or NFTs. They represent ownership of real-world assets (properties, medical records, blueprints, etc.) without tokenization.
+
+### Access Passes
+Time-bound VDAs that grant temporary, permissioned access to other VDAs. Perfect for data rooms, medical record sharing, and document collaboration.
+
+### Spokes
+Industry verticals (e.g., `real-estate`, `healthcare`, `architect`). Each spoke can have its own metadata schema while sharing universal metadata keys (`address`, `legalDesc`, `patientId`, `api14`).
+
+### Universal Metadata
+Standardized metadata keys that enable cross-spoke search:
+- `address` - Physical address (real estate)
+- `legalDesc` - Legal description (real estate)
+- `patientId` - Patient identifier (healthcare)
+- `api14` - API 14 identifier (oil & gas)
+
+## Documentation
+
+- [Getting Started Guide](./docs/getting-started.md) - Step-by-step setup and first steps
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+- [Examples](./docs/examples.md) - Real-world usage examples
+- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+
+## Examples
+
+### Architect Invoice Flow
+```typescript
+import { architectInvoiceFlow } from "@hauska-sdk/core/examples/architect-invoice-flow";
+
+// Complete flow: Create invoice → Payment → Transfer blueprint
+const result = await architectInvoiceFlow();
+```
+
+### Data Room Creation
+```typescript
+// Create a data room with encrypted documents
+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,
+  },
+});
+```
+
+### Purchase and Mint VDA
+```typescript
+// Purchase and mint a VDA in a single operation
+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",
+  },
+});
+```
+
+See [Examples Guide](./docs/examples.md) for more complete examples.
+
+## Error Handling
+
+The SDK uses structured error types for better error handling:
+
+```typescript
+import {
+  SDKError,
+  PaymentError,
+  VDAError,
+  RetrievalError,
+  WalletError,
+  ConfigurationError,
+  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)) {
+      // Retry logic
+    }
+  }
+}
+```
+
+See [Error Handling](./docs/api-reference.md#error-handling) for more details.
+
+## Logging and Monitoring
+
+The SDK supports logging and metrics hooks for monitoring:
+
+```typescript
+const sdk = new CNSSDK({
+  // ... config
+  logHook: (level, message, data) => {
+    console.log(`[${level}] ${message}`, data);
+  },
+  metricsHook: (event, data) => {
+    // Send to your analytics service
+    analytics.track(event, data);
+  },
+});
+```
+
+## Adapters
+
+The SDK uses adapters for storage, blockchain, and IPFS:
+
+### Storage Adapters
+- `@hauska-sdk/adapters-storage-postgres` - PostgreSQL (production)
+- `@hauska-sdk/adapters-storage-redis` - Redis caching layer
+- `@hauska-sdk/adapters-storage-mock` - In-memory (testing)
+
+### Blockchain Adapters
+- `@hauska-sdk/adapters-blockchain-ethers` - Ethers.js (Base L2)
+
+### IPFS Adapters
+- Pinata (via `@hauska-sdk/retrieval`)
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.3+
+- PostgreSQL (for production storage)
+- Pinata account (for IPFS storage)
+- Base L2 RPC endpoint (for blockchain operations)
+
+## License
+
+MIT
+
+## Related Packages
+
+- [`@hauska-sdk/payment`](../payment/README.md) - Payment SDK
+- [`@hauska-sdk/vda`](../vda/README.md) - VDA SDK
+- [`@hauska-sdk/retrieval`](../retrieval/README.md) - Retrieval SDK
+- [`@hauska-sdk/wallet`](../wallet/README.md) - Wallet Management
+
+## Support
+
+- [GitHub Issues](https://github.com/hauska-sdk/issues)
+- [Documentation](https://docs.hauska-sdk.com)
+- [Discord](https://discord.gg/hauska-sdk)

package/dist/CNSSDK.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @hauska-sdk/core
+ * Unified CNS SDK - Main entry point
+ */
+import { WalletManager } from "@hauska-sdk/wallet";
+import { PaymentSDK } from "@hauska-sdk/payment";
+import { VDASDK } from "@hauska-sdk/vda";
+import { RetrievalSDK } from "@hauska-sdk/retrieval";
+import type { CNSSDKConfig, WalletOptions, PurchaseAndMintVDAOptions, CreateDataRoomOptions, RetrieveDocumentOptions } from "./types";
+import type { PaymentRecord } from "@hauska-sdk/payment";
+import type { VDA } from "@hauska-sdk/vda";
+import type { UploadDocumentResult } from "@hauska-sdk/retrieval";
+/**
+ * Unified CNS SDK
+ *
+ * Main entry point for all CNS Protocol functionality:
+ * - Payment processing (x402 protocol)
+ * - VDA management (Verified Digital Assets)
+ * - Document retrieval (IPFS with gated access)
+ * - Wallet management (automatic wallet creation)
+ */
+export declare class CNSSDK {
+    private config;
+    private walletManager;
+    private paymentSDK;
+    private vdaSDK;
+    private retrievalSDK;
+    private anchoring?;
+    constructor(config: CNSSDKConfig);
+    /**
+     * Initialize all SDK modules
+     */
+    private initialize;
+    /**
+     * Get or create a wallet for a user
+     *
+     * @param options - Wallet options
+     * @returns Wallet instance
+     */
+    getOrCreateWallet(options: WalletOptions): Promise<import("@hauska-sdk/wallet").Wallet>;
+    /**
+     * Purchase and mint a VDA in a single operation
+     *
+     * This method:
+     * 1. Gets or creates a wallet for the user
+     * 2. Processes the payment
+     * 3. Records the payment
+     * 4. Mints the VDA
+     *
+     * @param options - Purchase and mint options
+     * @returns Object containing payment record and VDA
+     */
+    purchaseAndMintVDA(options: PurchaseAndMintVDAOptions): Promise<{
+        payment: PaymentRecord;
+        vda: VDA;
+        wallet: {
+            address: string;
+        };
+    }>;
+    /**
+     * Create a data room (VDA + optional document + optional access pass)
+     *
+     * This method:
+     * 1. Gets or creates a wallet for the owner
+     * 2. Mints a VDA for the data room
+     * 3. Optionally uploads a document to IPFS
+     * 4. Optionally creates an access pass
+     *
+     * @param options - Data room creation options
+     * @returns Object containing VDA, document (if uploaded), and access pass (if created)
+     */
+    createDataRoom(options: CreateDataRoomOptions): Promise<{
+        vda: VDA;
+        document?: UploadDocumentResult;
+        accessPass?: VDA;
+    }>;
+    /**
+     * Retrieve a document with access verification
+     *
+     * This method:
+     * 1. Gets or creates a wallet for the requester
+     * 2. Verifies access to the document (VDA ownership or access pass)
+     * 3. Retrieves the document from IPFS
+     * 4. Optionally decrypts and watermarks the document
+     *
+     * @param options - Document retrieval options
+     * @returns Document content as Buffer
+     */
+    retrieveDocument(options: RetrieveDocumentOptions): Promise<Buffer>;
+    /**
+     * Get the underlying Payment SDK instance
+     */
+    getPaymentSDK(): PaymentSDK;
+    /**
+     * Get the underlying VDA SDK instance
+     */
+    getVDASDK(): VDASDK;
+    /**
+     * Get the underlying Retrieval SDK instance
+     */
+    getRetrievalSDK(): RetrievalSDK;
+    /**
+     * Get the wallet manager instance
+     */
+    getWalletManager(): WalletManager;
+    /**
+     * Log a message using the configured log hook
+     */
+    private log;
+    /**
+     * Emit a metrics event using the configured metrics hook
+     */
+    private metrics;
+}
+//# sourceMappingURL=CNSSDK.d.ts.map

package/dist/CNSSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CNSSDK.d.ts","sourceRoot":"","sources":["../src/CNSSDK.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAIlE;;;;;;;;GAQG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,SAAS,CAAC,CAAwB;gBAE9B,MAAM,EAAE,YAAY;IAKhC;;OAEG;IACH,OAAO,CAAC,UAAU;IA0FlB;;;;;OAKG;IACG,iBAAiB,CAAC,OAAO,EAAE,aAAa;IAyC9C;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC;QACpE,OAAO,EAAE,aAAa,CAAC;QACvB,GAAG,EAAE,GAAG,CAAC;QACT,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7B,CAAC;IAiFF;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC;QAC5D,GAAG,EAAE,GAAG,CAAC;QACT,QAAQ,CAAC,EAAE,oBAAoB,CAAC;QAChC,UAAU,CAAC,EAAE,GAAG,CAAC;KAClB,CAAC;IAgGF;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BzE;;OAEG;IACH,aAAa,IAAI,UAAU;IAI3B;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,eAAe,IAAI,YAAY;IAI/B;;OAEG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,OAAO;CAKhB"}