@proofchain/sdk 1.2.0 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 ProofChain / MegaWatts Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,144 +1,284 @@
-# @attestation/sdk
+# ProofChain JavaScript/TypeScript SDK
 
-TypeScript SDK for the Attestation Service API.
+Official JavaScript/TypeScript SDK for [ProofChain](https://proofchain.co.za) - blockchain-anchored document attestation.
+
+Works in Node.js and browsers.
 
 ## Installation
 
 ```bash
-npm install @attestation/sdk ethers
+npm install @proofchain/sdk
+# or
+yarn add @proofchain/sdk
+# or
+pnpm add @proofchain/sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { AttestationClient, AttestationRegistryContract } from '@attestation/sdk';
-import { ethers } from 'ethers';
+import { ProofChain } from '@proofchain/sdk';
+
+// Create client
+const client = new ProofChain({ apiKey: 'your-api-key' });
 
-// Create API client
-const client = new AttestationClient({
-  baseUrl: 'http://localhost:8000',
+// Attest a document
+const result = await client.documents.attest({
+  file: myFile, // File, Blob, or Buffer
+  userId: 'user@example.com',
+  eventType: 'contract_signed',
 });
 
-// Health check
-const health = await client.health();
-console.log(health.status); // 'healthy'
+console.log('IPFS Hash:', result.ipfsHash);
+console.log('Verify URL:', result.verifyUrl);
+
+// Verify
+const verification = await client.verify(result.ipfsHash);
+console.log('Valid:', verification.valid);
+```
+
+## High-Performance Ingestion
 
-// Web3 Authentication
-const challenge = await client.requestChallenge('0x742d35...');
-// Sign the challenge.message with your wallet
-const auth = await client.verifySignature(
-  '0x742d35...',
-  signature,
-  challenge.message
-);
-// Token is automatically set on the client
+For maximum throughput, use the dedicated `IngestionClient` which connects directly to the Rust ingestion API:
+
+```typescript
+import { IngestionClient } from '@proofchain/sdk';
+
+const ingestion = new IngestionClient({ apiKey: 'your-api-key' });
+
+// Single event (immediate attestation)
+const result = await ingestion.ingest({
+  userId: 'user-123',
+  eventType: 'purchase',
+  data: { amount: 99.99, product: 'widget' },
+});
+
+console.log('Event ID:', result.eventId);
+console.log('Certificate:', result.certificateId);
+
+// Batch events (up to 1000 per request)
+const batchResult = await ingestion.ingestBatch({
+  events: [
+    { userId: 'user-1', eventType: 'click', data: { page: '/home' } },
+    { userId: 'user-2', eventType: 'click', data: { page: '/products' } },
+    // ... up to 1000 events
+  ],
+});
+
+console.log('Queued:', batchResult.queued);
+console.log('Failed:', batchResult.failed);
+```
+
+## State Channels (High-Volume Streaming)
+
+For high-throughput scenarios (100K+ events/sec):
+
+```typescript
+import { ProofChain } from '@proofchain/sdk';
 
+const client = new ProofChain({ apiKey: 'your-api-key' });
+
+// Create a state channel
+const channel = await client.channels.create({ name: 'iot-sensors' });
+
+// Stream events
+for (const reading of sensorReadings) {
+  await client.channels.stream(channel.channelId, {
+    eventType: 'sensor_reading',
+    userId: reading.deviceId,
+    data: { temperature: reading.temp, humidity: reading.humidity },
+  });
+}
+
+// Settle on-chain
+const settlement = await client.channels.settle(channel.channelId);
+console.log('TX Hash:', settlement.txHash);
+```
+
+## Features
+
+### Documents
+
+```typescript
+// Attest a file (Node.js)
+import { readFileSync } from 'fs';
+
+const result = await client.documents.attest({
+  file: readFileSync('contract.pdf'),
+  filename: 'contract.pdf',
+  userId: 'user@example.com',
+  eventType: 'document_uploaded',
+  metadata: { department: 'legal' },
+});
+
+// Attest a file (Browser)
+const fileInput = document.querySelector('input[type="file"]');
+const result = await client.documents.attest({
+  file: fileInput.files[0],
+  userId: 'user@example.com',
+});
+
+// Get document by hash
+const doc = await client.documents.get('Qm...');
+```
+
+### Events
+
+```typescript
 // Create an event
-const event = await client.createEvent({
-  user_id: 'user123',
-  event_type: 'document_signed',
-  data: { documentId: 'doc-456', hash: '0xabc...' },
+const event = await client.events.create({
+  eventType: 'user_action',
+  userId: 'user123',
+  data: { action: 'login', ip: '192.168.1.1' },
+});
+
+// List events
+const events = await client.events.list({
+  userId: 'user123',
+  eventType: 'user_action',
+  limit: 100,
+});
+
+// Search events
+const results = await client.events.search({
+  query: 'login',
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
 });
-console.log(event.ipfs_hash);
-
-// Get Merkle proof
-await client.rebuildMerkleTree('user123');
-const proof = await client.getMerkleProof('user123', event.ipfs_hash);
-console.log(proof.root, proof.proof);
-
-// Verify proof off-chain
-const isValid = await client.verifyMerkleProof(
-  proof.leaf,
-  proof.proof,
-  proof.root
-);
-console.log(isValid.valid); // true
 ```
 
-## On-Chain Verification
+### Verification
 
 ```typescript
-import { AttestationRegistryContract } from '@attestation/sdk';
-import { ethers } from 'ethers';
-
-// Connect to contract
-const provider = new ethers.JsonRpcProvider('https://rpc.example.com');
-const signer = new ethers.Wallet(privateKey, provider);
-const contract = new AttestationRegistryContract(
-  '0xContractAddress...',
-  signer
-);
-
-// Get on-chain root
-const root = await contract.getRoot('0xWalletAddress...');
-console.log(root.merkleRoot, root.eventCount);
-
-// Verify attestation on-chain
-const isValid = await contract.verifyAttestation(
-  '0xWalletAddress...',
-  proof.leaf,
-  proof.proof
-);
-
-// Update root (requires authorization)
-const tx = await contract.updateRoot(
-  '0xWalletAddress...',
-  proof.root,
-  3201,
-  'QmLatestIpfsHash...'
-);
-await tx.wait();
-
-// Off-chain verification (no RPC needed)
-const validOffchain = AttestationRegistryContract.verifyProofOffchain(
-  proof.leaf,
-  proof.proof,
-  proof.root
-);
+// Verify by IPFS hash
+const result = await client.verify('Qm...');
+
+if (result.valid) {
+  console.log('Timestamp:', result.timestamp);
+  console.log('Blockchain TX:', result.blockchainTx);
+  console.log('Certificate ID:', result.certificateId);
+}
 ```
 
-## API Reference
-
-### AttestationClient
-
-| Method | Description |
-|--------|-------------|
-| `health()` | Check API health |
-| `requestChallenge(wallet)` | Get auth challenge |
-| `verifySignature(wallet, sig, msg)` | Verify and get JWT |
-| `createEvent(event)` | Create new event |
-| `getEvents(userId, options)` | List user events |
-| `queryEvents(userId, query)` | Query with filters |
-| `rebuildMerkleTree(userId)` | Rebuild Merkle tree |
-| `getMerkleRoot(userId)` | Get current root |
-| `getMerkleProof(userId, ipfsHash)` | Get proof for event |
-| `verifyMerkleProof(leaf, proof, root)` | Verify proof |
-| `linkWallet(request)` | Link wallet to user |
-| `getWalletStatus(userId)` | Get wallet status |
-
-### AttestationRegistryContract
-
-| Method | Description |
-|--------|-------------|
-| `getRoot(wallet)` | Get on-chain root |
-| `getHistoryCount(wallet)` | Get history count |
-| `getHistoricalRoot(wallet, index)` | Get historical root |
-| `verifyAttestation(wallet, leaf, proof)` | Verify on-chain |
-| `computeLeaf(ipfs, type, timestamp)` | Compute leaf hash |
-| `updateRoot(wallet, root, count, ipfs)` | Update root |
-| `batchUpdateRoots(...)` | Batch update |
-| `setAuthorizedUpdater(addr, auth)` | Manage updaters |
-
-### Static Methods
+### Certificates
 
 ```typescript
-// Compute leaf without RPC
-AttestationRegistryContract.computeLeafOffchain(ipfsHash, eventType, timestamp);
+// Issue a certificate
+const cert = await client.certificates.issue({
+  recipientName: 'John Doe',
+  recipientEmail: 'john@example.com',
+  title: 'Course Completion',
+  description: 'Completed JavaScript Fundamentals',
+  metadata: { courseId: 'JS101', score: 95 },
+});
 
-// Verify proof without RPC
-AttestationRegistryContract.verifyProofOffchain(leaf, proof, root);
+console.log('Certificate ID:', cert.certificateId);
+console.log('QR Code:', cert.qrCodeUrl);
+
+// Revoke
+await client.certificates.revoke(cert.certificateId, 'Issued in error');
+```
+
+### Webhooks
+
+```typescript
+// Register a webhook
+const webhook = await client.webhooks.create({
+  url: 'https://your-app.com/webhook',
+  events: ['document.attested', 'channel.settled'],
+  secret: 'your-secret',
+});
+
+// List webhooks
+const webhooks = await client.webhooks.list();
+
+// Delete
+await client.webhooks.delete(webhook.id);
+```
+
+## Error Handling
+
+```typescript
+import { ProofChain, ProofChainError, AuthenticationError, RateLimitError } from '@proofchain/sdk';
+
+try {
+  const result = await client.documents.attest(req);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ProofChainError) {
+    console.error(`API error: ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+import { ProofChain } from '@proofchain/sdk';
+
+// Full configuration
+const client = new ProofChain({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://ingest.proofchain.co.za', // Ingestion API (Rust)
+  mgmtUrl: 'https://api.proofchain.co.za',    // Management API (Python)
+  timeout: 30000, // 30 seconds
+  maxRetries: 3,
+});
+
+// From environment variable (Node.js)
+// Set PROOFCHAIN_API_KEY
+const client = ProofChain.fromEnv();
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  AttestationResult,
+  Event,
+  Channel,
+  ChannelStatus,
+  Settlement,
+  Certificate,
+  Webhook,
+  VerificationResult,
+  SearchResult,
+} from '@proofchain/sdk';
+```
+
+## Browser Usage
+
+The SDK works in browsers with no additional configuration:
+
+```html
+<script type="module">
+  import { ProofChain } from 'https://esm.sh/@proofchain/sdk';
+
+  const client = new ProofChain({ apiKey: 'your-api-key' });
+  
+  // Use with file input
+  document.querySelector('#upload').addEventListener('change', async (e) => {
+    const file = e.target.files[0];
+    const result = await client.documents.attest({
+      file,
+      userId: 'user@example.com',
+    });
+    console.log('Attested:', result.ipfsHash);
+  });
+</script>
 ```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- Documentation: https://proofchain.co.za/docs
+- Email: support@proofchain.co.za
+- GitHub Issues: https://github.com/proofchain/proofchain-js/issues