@proofrails/sdk 1.1.0 → 1.2.0

package/README.md

@@ -1 +1,244 @@
-# ProofRails SDK> **Beginner-friendly SDK for creating blockchain-verifiable ISO 20022 payment receipts**Create compliant, auditable payment receipts with just a few lines of code. No blockchain expertise required!## Features-  **Zero coding knowledge required** - Use simple templates-  **ISO 20022 compliant** - Generates standard banking messages-  **Blockchain-verified** - Receipts anchored on Flare blockchain-  **Tamper-proof** - Cryptographic evidence bundles-  **Real-time updates** - Live receipt status via SSE-  **Works everywhere** - TypeScript, JavaScript, Node.js, browsers##  Installation```bashnpm install @proofrails/sdk# oryarn add @proofrails/sdk```##  Quick Start### Option 1: Create New Project (Easiest)```javascriptimport ProofRails from '@proofrails/sdk';// Create a new project automaticallyconst { client, apiKey, projectId } = await ProofRails.createProject({  label: 'My App'});console.log('Your API Key:', apiKey); // Save this!console.log('Your Project ID:', projectId);```### Option 2: Use Existing API Key```javascriptimport ProofRails from '@proofrails/sdk';const proofrails = new ProofRails({  apiKey: 'your-api-key-here'});```##  Templates (Beginner-Friendly)### Payment Receipt```javascriptconst receipt = await proofrails.templates.payment({  amount: 100,  from: 'Alice',  to: 'Bob',  purpose: 'Freelance web development',  transactionHash: '0x123...'});console.log('Receipt ID:', receipt.id);console.log('Status:', receipt.status);```### Donation Receipt```javascriptconst receipt = await proofrails.templates.donation({  amount: 50,  donor: 'John Doe',  organization: 'Red Cross',  campaign: 'Disaster Relief 2024',  transactionHash: '0x456...'});```### Escrow Release```javascriptconst receipt = await proofrails.templates.escrow({  amount: 1000,  buyer: 'Alice',  seller: 'Bob',  escrowId: 'ESC-2024-001',  releaseReason: 'Milestone 1 completed',  transactionHash: '0x789...'});```### Grant Disbursement```javascriptconst receipt = await proofrails.templates.grant({  amount: 5000,  grantee: 'Research Lab',  grantor: 'Science Foundation',  grantId: 'GR-2024-001',  purpose: 'Climate change research',  transactionHash: '0xabc...'});```### Refund```javascriptconst receipt = await proofrails.templates.refund({  amount: 25,  originalPayment: 'receipt-id-123',  reason: 'Product returned',  customer: 'Jane Smith',  transactionHash: '0xdef...'});```##  Core Operations### Get Receipt```javascriptconst receipt = await proofrails.receipts.get('receipt-id');console.log(receipt.status); // 'pending' or 'anchored'console.log(receipt.amount);console.log(receipt.anchorTx); // Blockchain transaction (if anchored)```### List Receipts```javascriptconst { items, total } = await proofrails.receipts.list({  limit: 10,  status: 'anchored'});items.forEach(receipt => {  console.log(receipt.id, receipt.amount);});```### Download Artifacts```javascriptconst artifacts = await proofrails.receipts.getArtifacts('receipt-id');console.log('ISO XML:', artifacts.pain001Url);console.log('Bundle:', artifacts.bundleUrl);console.log('Manifest:', artifacts.manifestUrl);```##  Verification### Verify Receipt```javascriptconst verification = await proofrails.verify.byReceiptId('receipt-id');if (verification.valid && verification.onChain) {  console.log(' Receipt is valid and on-chain!');  console.log('Anchor TX:', verification.anchorTx);}```### Verify by Bundle Hash```javascriptconst verification = await proofrails.verify.byHash('0x123...');```### Get Verification Proof```javascriptconst proof = await proofrails.verify.getProof('receipt-id');console.log('Bundle Hash:', proof.bundleHash);console.log('Block Number:', proof.blockNumber);console.log('Timestamp:', proof.timestamp);```##  Live Updates```javascript// Listen to receipt status changes in real-timeconst listener = proofrails.events.listen('receipt-id', (update) => {  console.log('Status:', update.status);    if (update.status === 'anchored') {    console.log('Receipt is now on-chain!');    console.log('Anchor TX:', update.anchorTx);    listener.stop(); // Stop listening  }});```##  Embeddable Widgets### Generate Widget```javascriptconst widget = proofrails.embed.widget('receipt-id', {  theme: 'light',  width: '100%',  height: '400px'});// Use in HTMLdocument.getElementById('receipt').innerHTML = widget.iframeHtml;```### Full Page URL```javascriptconst pageUrl = proofrails.embed.fullPage('receipt-id');// https://middleware.com/receipt/receipt-id```##  Statements### Generate Intraday Statement```javascriptconst statement = await proofrails.statements.intraday({  dateFrom: '2024-01-01',  dateTo: '2024-01-31',  accountId: 'my-account'});console.log('Download:', statement.downloadUrl);```### Generate End-of-Day Statement```javascriptconst statement = await proofrails.statements.endOfDay({  dateTo: '2024-01-31',  accountId: 'my-account'});```##  Project Management### Get Project Info```javascriptconst info = await proofrails.project.getInfo();console.log('Project ID:', info.projectId);```### Rotate API Key```javascriptconst newKey = await proofrails.project.rotateKey();console.log('New API Key:', newKey.apiKey); // Save this!// Update client with new keyproofrails.setApiKey(newKey.apiKey);```##  Admin Operations```javascriptconst admin = new ProofRails({ adminToken: 'your-admin-token' });// Create API key for specific projectconst key = await admin.admin.createKey({  projectId: 'proj-123',  label: 'Production Key'});  label: 'Production Key'});// Delete API keyawait admin.admin.deleteKey('key-id');```##  Networks```javascript// Testnet (default)const proofrails = new ProofRails({  apiKey: 'your-key',  network: 'coston2'});// Mainnetconst proofrails = new ProofRails({  apiKey: 'your-key',  network: 'flare'});```##  Advanced Configuration```javascriptconst proofrails = new ProofRails({  apiKey: 'your-key',  network: 'coston2',  baseUrl: 'https://custom-middleware.com', // Optional  timeout: 60000 // Request timeout in ms (default: 30000)});```##  React Hooks (New!)The SDK exports dedicated React hooks for the easiest integration experience.### Setup```typescriptimport { useProofRails } from '@proofrails/sdk/react';// Initialize the hookconst sdk = useProofRails({   apiKey: 'your-api-key' });```### Sending Payments (Zero Boilerplate)```typescriptimport { useProofRailsPayment } from '@proofrails/sdk/react';const { send, loading, receipt, status } = useProofRailsPayment(sdk);const handleMyButton = async () => {    await send({        amount: "10.0",        to: "0xReceiverAddress...",        purpose: "Payment for Services"    });};```### Self-Serve Project Creation```typescriptimport { useCreateProject } from '@proofrails/sdk/react';const { create, loading } = useCreateProject();const setup = async () => {    const { apiKey, projectId } = await create("My New dApp");    console.log("My new key:", apiKey);};```##  TypeScript SupportFull TypeScript support with type definitions included:```typescriptimport ProofRails, { Receipt, VerificationResult } from '@proofrails/sdk';const proofrails = new ProofRails({ apiKey: 'your-key' });const receipt: Receipt = await proofrails.templates.payment({  amount: 100,  from: 'Alice',  to: 'Bob',  purpose: 'Payment',  transactionHash: '0x123...'});const verification: VerificationResult = await proofrails.verify.byReceiptId(receipt.id);```##  JavaScript (No TypeScript)Works perfectly in plain JavaScript too:```javascriptconst ProofRails = require('@proofrails/sdk');const proofrails = new ProofRails({ apiKey: 'your-key' });// Same API, no types needed!```##  Error Handling```javascriptimport { ProofRailsError } from '@proofrails/sdk';try {  const receipt = await proofrails.receipts.get('invalid-id');} catch (error) {  if (error instanceof ProofRailsError) {    console.error('Error:', error.message);    console.error('Code:', error.code);    console.error('Status:', error.statusCode);  }}```##  LicenseMIT##  Support- Documentation: [docs.proofrails.com](https://docs.proofrails.com)- Issues: [GitHub Issues](https://github.com/proofrails/proofrails-sdk/issues)- Email: support@proofrails.com---**Made with ❤️ by ProofRails**# Proofrails-sdk
+
+````md
+# ProofRails SDK
+
+**Beginner friendly SDK for creating blockchain verifiable ISO 20022 payment receipts**
+
+Create compliant, auditable payment receipts with just a few lines of code. No blockchain expertise required.
+
+## Features
+
+- **Zero coding knowledge required**, use simple templates  
+- **ISO 20022 compliant**, generates standard banking messages  
+- **Blockchain verified**, receipts anchored on Flare blockchain  
+- **Tamper proof**, cryptographic evidence bundles  
+- **Real time updates**, live receipt status via SSE  
+- **Works everywhere**, TypeScript, JavaScript, Node.js, browsers  
+
+## Installation
+
+```bash
+npm i @proofrails-sdk/sdk
+# or
+yarn add @proofrails/sdk
+````
+
+## Quick Start
+
+### Option 1, Create New Project (Easiest)
+
+```javascript
+import ProofRails from '@proofrails/sdk';
+
+// Create a new project automatically
+const { client, apiKey, projectId } = await ProofRails.createProject({
+  label: 'My App'
+});
+
+console.log('Your API Key:', apiKey); // Save this
+console.log('Your Project ID:', projectId);
+```
+
+### Option 2, Use Existing API Key
+
+```javascript
+import ProofRails from '@proofrails/sdk';
+
+const proofrails = new ProofRails({
+  apiKey: 'your-api-key-here'
+});
+```
+
+## Templates (Beginner Friendly)
+
+### Payment Receipt
+
+```javascript
+const receipt = await proofrails.templates.payment({
+  amount: 100,
+  from: 'Alice',
+  to: 'Bob',
+  purpose: 'Freelance web development',
+  transactionHash: '0x123...'
+});
+
+console.log('Receipt ID:', receipt.id);
+console.log('Status:', receipt.status);
+```
+
+### Donation Receipt
+
+```javascript
+const receipt = await proofrails.templates.donation({
+  amount: 50,
+  donor: 'John Doe',
+  organization: 'Red Cross',
+  campaign: 'Disaster Relief 2024',
+  transactionHash: '0x456...'
+});
+```
+
+### Escrow Release
+
+```javascript
+const receipt = await proofrails.templates.escrow({
+  amount: 1000,
+  buyer: 'Alice',
+  seller: 'Bob',
+  escrowId: 'ESC-2024-001',
+  releaseReason: 'Milestone 1 completed',
+  transactionHash: '0x789...'
+});
+```
+
+### Grant Disbursement
+
+```javascript
+const receipt = await proofrails.templates.grant({
+  amount: 5000,
+  grantee: 'Research Lab',
+  grantor: 'Science Foundation',
+  grantId: 'GR-2024-001',
+  purpose: 'Climate change research',
+  transactionHash: '0xabc...'
+});
+```
+
+### Refund
+
+```javascript
+const receipt = await proofrails.templates.refund({
+  amount: 25,
+  originalPayment: 'receipt-id-123',
+  reason: 'Product returned',
+  customer: 'Jane Smith',
+  transactionHash: '0xdef...'
+});
+```
+
+## Core Operations
+
+### Get Receipt
+
+```javascript
+const receipt = await proofrails.receipts.get('receipt-id');
+
+console.log(receipt.status);
+console.log(receipt.amount);
+console.log(receipt.anchorTx);
+```
+
+### List Receipts
+
+```javascript
+const { items, total } = await proofrails.receipts.list({
+  limit: 10,
+  status: 'anchored'
+});
+
+items.forEach(r => {
+  console.log(r.id, r.amount);
+});
+```
+
+### Download Artifacts
+
+```javascript
+const artifacts = await proofrails.receipts.getArtifacts('receipt-id');
+
+console.log('ISO XML:', artifacts.pain001Url);
+console.log('Bundle:', artifacts.bundleUrl);
+console.log('Manifest:', artifacts.manifestUrl);
+```
+
+## Verification
+
+### Verify Receipt
+
+```javascript
+const verification = await proofrails.verify.byReceiptId('receipt-id');
+
+if (verification.valid && verification.onChain) {
+  console.log('Receipt is valid and on chain');
+  console.log('Anchor TX:', verification.anchorTx);
+}
+```
+
+### Verify by Bundle Hash
+
+```javascript
+const verification = await proofrails.verify.byHash('0x123...');
+```
+
+### Get Verification Proof
+
+```javascript
+const proof = await proofrails.verify.getProof('receipt-id');
+
+console.log('Bundle Hash:', proof.bundleHash);
+console.log('Block Number:', proof.blockNumber);
+console.log('Timestamp:', proof.timestamp);
+```
+
+## Live Updates
+
+```javascript
+const listener = proofrails.events.listen('receipt-id', update => {
+  console.log('Status:', update.status);
+
+  if (update.status === 'anchored') {
+    console.log('Receipt is now on chain');
+    listener.stop();
+  }
+});
+```
+
+## Embeddable Widgets
+
+### Generate Widget
+
+```javascript
+const widget = proofrails.embed.widget('receipt-id', {
+  theme: 'light',
+  width: '100%',
+  height: '400px'
+});
+
+document.getElementById('receipt').innerHTML = widget.iframeHtml;
+```
+
+### Full Page URL
+
+```javascript
+const pageUrl = proofrails.embed.fullPage('receipt-id');
+```
+
+## Networks
+
+```javascript
+const proofrails = new ProofRails({
+  apiKey: 'your-key',
+  network: 'coston2'
+});
+```
+
+```javascript
+const proofrails = new ProofRails({
+  apiKey: 'your-key',
+  network: 'flare'
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+* Documentation, [https://www.flarestudio.xyz/sdk/proofrails-sdk/overview](https://www.flarestudio.xyz/sdk/proofrails-sdk/overview)
+* Repository, [https://github.com/Elite-tch/Proofrails-sdk.git](https://github.com/Elite-tch/Proofrails-sdk.git)
+* Email, [izuchukwujohnbosco95@gmail.com](mailto:izuchukwujohnbosco95@gmail.com)
+
+**Made with ❤️ by ProofRails**
+
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@proofrails/sdk",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Beginner-friendly SDK for ProofRails ISO 20022 Middleware - Create blockchain-verifiable payment receipts with zero coding knowledge",
     "main": "dist/index.js",
     "module": "dist/index.mjs",