From 8b20195001032386f164a307c9363e2294ae1cf1 Mon Sep 17 00:00:00 2001 From: Neal Date: Thu, 24 Oct 2024 12:29:40 -0700 Subject: [PATCH 1/3] add README --- bound/typescript/README.md | 106 +++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 bound/typescript/README.md diff --git a/bound/typescript/README.md b/bound/typescript/README.md new file mode 100644 index 0000000..44bfdd9 --- /dev/null +++ b/bound/typescript/README.md @@ -0,0 +1,106 @@ +# tbDEX SDK + +[![npm version](https://badge.fury.io/js/tbdex.svg)](https://badge.fury.io/js/tbdex) + +A TypeScript SDK for interacting with the tbDEX protocol. This SDK is built on a Rust core with WebAssembly bindings, offering high performance, type safety, and interoperability. This library that can be used to create, parse, verify, and validate the tbDEX Messages and Resources defined in the [protocol specification](https://github.com/TBD54566975/tbdex/blob/main/README.md). This library also includes an HTTP client that can be used to send tbdex messages to PFIs. + + +## Features + +- **Complete tbDEX Protocol Support**: Implements all tbDEX message types and resources +- **Type-Safe**: Full TypeScript support with comprehensive type definitions +- **Cross-Platform**: Works in Node.js and modern browsers + +## Installation + +```bash +npm install @tbdex/sdk +``` + +## Basic Usage + +### Creating and Managing Exchanges + +```typescript +import { + BearerDid, + Rfq, + CreateRfqData, + getOfferings, + createExchange, + getExchange +} from 'tbdex'; + +// Create a new Bearer DID +const bearerDid = await BearerDid.create(); + +// Fetch available offerings +const offerings = await getOfferings('did:example:pfi123'); +const offeringId = offerings[0].metadata.id; + +// Create an RFQ (Request for Quote) +const rfqData: CreateRfqData = { + offeringId, + claims: ['credentialJwt'], + payin: { + amount: '100', + kind: 'USD_LEDGER', + paymentDetails: null + }, + payout: { + kind: 'PAYOUT_KIND', + paymentDetails: { + phoneNumber: '555-0123', + reason: 'payment' + } + } +}; + +// Create and sign the RFQ +const rfq = Rfq.create('did:example:pfi123', bearerDid.did.uri, rfqData); +await rfq.sign(bearerDid); +await rfq.verify(); + +// Submit the RFQ to create an exchange +await createExchange(rfq); + +// Get exchange details +const exchange = await getExchange( + 'did:example:pfi123', + bearerDid, + rfq.metadata.exchangeId +); +``` + +## Message Types + +The SDK supports all tbDEX message types: + +- **RFQ (Request for Quote)**: Initial request for exchange +- **Quote**: Response with exchange terms +- **Order**: Acceptance of quote terms +- **OrderInstructions**: Payment process details +- **OrderStatus**: Transaction status updates +- **Close**: Exchange completion notification +- **Cancel**: Exchange cancellation + +## Resources + +Supported tbDEX resources: + +- **Offering**: Defines exchange terms and requirements +- **Balance**: Shows available currency amounts + +## Error Handling + +The SDK provides detailed error information for common scenarios: + +```typescript +try { + await rfq.verify(); +} catch (error) { + if (error instanceof TbdexError) { + console.error('Verification failed:', error.message); + } +} +``` \ No newline at end of file From 4f5bc621929a7bc5620f5cb0463e5151860a2be0 Mon Sep 17 00:00:00 2001 From: Neal Date: Thu, 24 Oct 2024 12:31:06 -0700 Subject: [PATCH 2/3] badge --- bound/typescript/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bound/typescript/README.md b/bound/typescript/README.md index 44bfdd9..2af8a02 100644 --- a/bound/typescript/README.md +++ b/bound/typescript/README.md @@ -1,6 +1,6 @@ # tbDEX SDK -[![npm version](https://badge.fury.io/js/tbdex.svg)](https://badge.fury.io/js/tbdex) +[![npm version](https://badge.fury.io/js/%40tbdex%2Fsdk.svg)](https://badge.fury.io/js/%40tbdex%2Fsdk) A TypeScript SDK for interacting with the tbDEX protocol. This SDK is built on a Rust core with WebAssembly bindings, offering high performance, type safety, and interoperability. This library that can be used to create, parse, verify, and validate the tbDEX Messages and Resources defined in the [protocol specification](https://github.com/TBD54566975/tbdex/blob/main/README.md). This library also includes an HTTP client that can be used to send tbdex messages to PFIs. From ea22640d3c92e53f603dd89d4a44183b3a2bbbb9 Mon Sep 17 00:00:00 2001 From: Neal Date: Thu, 24 Oct 2024 12:57:53 -0700 Subject: [PATCH 3/3] update readme --- bound/typescript/README.md | 106 +++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 33 deletions(-) diff --git a/bound/typescript/README.md b/bound/typescript/README.md index 2af8a02..84fc6b5 100644 --- a/bound/typescript/README.md +++ b/bound/typescript/README.md @@ -19,59 +19,99 @@ npm install @tbdex/sdk ## Basic Usage -### Creating and Managing Exchanges +### Message Creation ```typescript import { - BearerDid, Rfq, CreateRfqData, +} from '@tbdex/sdk'; + +const createRfqData: CreateRfqData = { + claims: [verifiableCredential], + offeringId, + payin: { + amount: '101', + kind: 'USD_LEDGER', + paymentDetails: null, + }, + payout: { + kind: 'MOMO_MPESA', + paymentDetails: { + phoneNumber: '867-5309', + reason: 'cause', + }, + }, +}; + +const rfq = Rfq.create(pfiDidUri, bearerDid.did.uri, createRfqData); + +await rfq.sign(bearerDid); +await rfq.verify(); +``` + +### Message Parsing +```typescript + +import { + Rfq, +} from '@tbdex/sdk'; + +const jsonMessage = "" +const rfq = Rfq.fromJSONString(jsonMessage); +``` + +### Http Client Create Exchange Flow +```typescript +import { + Rfq, + CreateRfqData, + BearerDid, getOfferings, createExchange, - getExchange -} from 'tbdex'; - -// Create a new Bearer DID -const bearerDid = await BearerDid.create(); + getExchange, + Exchange, +} from '@tbdex/sdk'; + +// Step 1: Fetch offerings +console.log('1. Fetching offerings...'); +const offerings = await getOfferings(pfiDidUri); +if (!offerings || offerings.length === 0) { + throw new Error('No offerings available.'); +} -// Fetch available offerings -const offerings = await getOfferings('did:example:pfi123'); const offeringId = offerings[0].metadata.id; - -// Create an RFQ (Request for Quote) -const rfqData: CreateRfqData = { - offeringId, - claims: ['credentialJwt'], - payin: { - amount: '100', +console.log(`Successfully fetched offering ID: ${offeringId}\n`); + +// Step 2: Create exchange (RFQ) +console.log('2. Creating exchange...'); +const createRfqData: CreateRfqData = { + claims: [verifiableCredential], + offeringId, + payin: { + amount: '101', kind: 'USD_LEDGER', - paymentDetails: null - }, - payout: { + paymentDetails: null, + }, + payout: { kind: 'PAYOUT_KIND', paymentDetails: { - phoneNumber: '555-0123', - reason: 'payment' - } - } + phoneNumber: '867-5309', + reason: 'cause', + }, + }, }; -// Create and sign the RFQ -const rfq = Rfq.create('did:example:pfi123', bearerDid.did.uri, rfqData); +const rfq = Rfq.create(pfiDidUri, bearerDid.did.uri, createRfqData); await rfq.sign(bearerDid); await rfq.verify(); - -// Submit the RFQ to create an exchange await createExchange(rfq); -// Get exchange details -const exchange = await getExchange( - 'did:example:pfi123', - bearerDid, - rfq.metadata.exchangeId -); +const exchangeId = rfq.metadata.exchangeId; +console.log(`Created exchange with ID: ${exchangeId}\n`); ``` + ## Message Types The SDK supports all tbDEX message types: