@b2binpay/defi-sdk 1.0.0

package/docs/api-client.md

@@ -0,0 +1,74 @@
+# API Client
+
+The API layer is implemented in `src/api/defi-client.ts` and wraps the generated contracts to present a developer-friendly interface for authentication and API calls.
+
+## Configuration
+
+```ts
+const client = new DefiClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: process.env.API_KEY!,
+  defaultHeaders: { 'x-app-version': '1.0.0' },
+});
+```
+
+Supported options:
+- `baseUrl` (required): REST endpoint (without trailing slash).
+- `apiKey` (required): value sent as the `x-api-key` header on every request.
+- `fetchApi`: Custom fetch implementation (useful for SSR or testing).
+- `middleware`: OpenAPI middleware applied to every request.
+- `defaultHeaders`, `credentials`, `queryParamsStringify`: Fine-grained HTTP control.
+
+## Authentication
+
+`DefiClient` authenticates purely via API key. Provide the key at construction time and every request will include `x-api-key: <value>`. There is no nonce/signature exchange or access/refresh token management in the SDK anymore.
+
+## Account Management
+- `getAccounts()` retrieves all accounts linked to the authenticated user (the first entry is cached automatically).
+- `getAccount()` fetches account details as an `AccountDetailsDto`, exposing the primary `account` metadata plus network `deployments`.
+- `getDeployments(accountDetails?)` returns the list of deployments for the account; pass cached account details to avoid re-fetching if you already have them.
+- `selectChain(chainId)` resolves and stores the deployment for a chain so downstream calls (invoices, payouts, claims, etc.) can omit chain/deployment identifiers.
+- `getSelectedDeployment()` returns the cached deployment (or `undefined` if none was selected yet).
+- `getAccountBalanceSummary({ chainId, baseCurrency })` retrieves balances; `baseCurrency` must be a value from `FiatCurrency`.
+- `getAssetBalances({ chainId?, baseCurrency, ...filters })` returns paginated asset balances with optional sorting/filtering by asset id or balance.
+- `getDeploymentByChain(chainId, accountDetails?)` resolves the `AccountDeploymentDto` for the requested chain without affecting the cached selection (pass cached account details to avoid re-fetching).
+
+Each API key is scoped to a single account, so the SDK auto-selects it internally and never requires an `accountId`.
+
+## Currencies & Payouts
+- `getCurrencies()` returns the list of supported currencies (native coins have `address === null`).
+- `getNativeCurrency(chainId)` returns the native coin entry for a chain (i.e., the currency with `address === null`).
+- `findCurrencyBySymbol({ symbol, chainId? })` searches currencies by ticker symbol (optionally constrained by chain, or falling back to the selected chain if one is cached); throws if zero or multiple matches exist.
+- `createPayout({ currencyId, amount, recipient, ... })` creates a payout request and enqueues a multisig operation for the selected chain (optionally override via `chainId`; amount is passed through as-is to the REST API).
+- `getPayouts({ ...filters, chainId? })` lists payouts with rich filtering (status, creator, address, etc.).
+- `getPayout({ payoutId, chainId? })` retrieves on-chain and API metadata for a specific payout.
+- `updatePayout({ payoutId, ...patch, chainId? })` patches tracking or callback metadata without re-creating the payout.
+- `getDeploymentQueue({ chainId?, ... })` fetches pending operations for signature/execution.
+- `submitOperationSignature({ operationId, signature, chainId? })` uploads an off-chain signature for an operation.
+
+## Invoice Management
+- `getInvoices({ ...filters, chainId? })` paginates invoices by status, date range, currency, or tracking ID.
+- `getInvoice({ invoiceId, chainId? })` returns the full invoice details payload.
+- `createInvoice({ requestedAmount, currencyIds, ... , chainId? })` creates an invoice for a chain/currency pair with optional callbacks.
+- `updateInvoice({ invoiceId, ...patch, chainId? })` updates request amount, callback URLs, currency selections, or status (e.g., to cancel an invoice, set `status: InvoiceStatus.Cancelled`).
+
+## Transactions & Claims
+- `getTransactions({ ...filters, chainId? })` exposes the transaction ledger with filters for operation type, status, currency, block hash, etc.
+- `getTransaction({ transactionId, chainId? })` hydrates a specific transaction with decoded metadata.
+- `getClaims({ ...filters, chainId? })` lists claimable deposits grouped by invoice and currency.
+- `getClaimableCurrencies(chainId?)` surfaces currencies that currently have claimable balances.
+- On-chain claim broadcasting is app-controlled; use `MultisigBlockchainClient.buildClaimCalldata` (see `examples/claim-deposits.ts`) to assemble calldata for `MultiSigWallet.claim`/`claimTo`, then broadcast the transaction yourself.
+
+## Blockchain Client & Builders
+- `MultisigBlockchainClient` (in `src/blockchain`) encapsulates RPC access for multisig operations.
+- `createExecuteTypedData({ contractAddress, operation, domainOverride? })` returns the EIP-712 payload ready for `signTypedData`.
+- `buildExecuteTransaction({ contractAddress, operations })` builds a `MultiSigWallet.execute` transaction (single or batch) using queue operations.
+- `buildClaimCalldata({ erc20, depositAccountIds, to? })` generates calldata for `claim`/`claimTo` functions.
+
+The lower-level builders in `src/utils/transactions` are also exported if you want to construct transactions without instantiating a client. This separation keeps API usage decoupled from blockchain access so the blockchain client can be used independently of how requests are authenticated.
+
+## Error Handling
+All generated API methods throw `ResponseError` when the server responds with non-2xx status codes. Catch these errors to read the JSON body for additional context, as demonstrated in `examples/get-account-info.ts`.
+
+## Validation Helpers
+Use `validateAddress({ address, networkChainId, currency, assets })` from `src/utils/validation` (re-exported via `@b2binpay/defi-sdk`) before submitting payouts or invoices. The helper enforces checksum address formatting, verifies currency/network combinations, and ensures the currency is part of the provided asset list, returning `{ isValid, errors, normalizedAddress }`.

package/docs/contributing.md

@@ -0,0 +1,33 @@
+# Contributing Guide
+
+## Prerequisites
+- Node `^22.16.0` and npm `^10.9.2`.
+- Access to the OpenAPI specification for regenerating `generated-contracts/`.
+- Wallet tooling capable of signing messages for integration testing.
+
+## Project Commands
+- `npm install`: Install dependencies.
+- `npm run generate:api`: Regenerate REST client from the remote OpenAPI spec.
+- `npm run lint`: Check and format code with Biome.
+- `npm run example:get-account-info`: Run the reference example (requires `.env`).
+- `npx tsc --noEmit`: Type-check the project.
+
+## Workflow
+1. Update or regenerate API contracts as needed.
+2. Implement changes inside `src/` (API layer or utilities).
+3. Add or update documentation under `docs/`.
+4. Update examples/tests to reflect new behaviour.
+5. Run `npx tsc --noEmit` before opening a PR.
+
+## Coding Guidelines
+- Prefer TypeScript modules in `src/` with explicit named exports.
+- Keep shared interfaces/types in dedicated files when used by multiple modules.
+- Favour composition over inheritance; expose helper functions over classes unless stateful behaviour is required.
+- Limit comments to non-obvious logic and architectural decisions.
+
+## Release Preparation
+- Ensure `generated-contracts/` is up to date and committed.
+- Bump the version in `package.json` (to be configured once publishing is in place).
+- Attach release notes referencing relevant documentation updates.
+
+For architectural orientation review `docs/overview.md` first, then reference module-specific guides.

package/docs/overview.md

@@ -0,0 +1,33 @@
+# SDK Overview
+
+This SDK provides a single TypeScript entry point that combines REST API access with smart-contract helpers tailored to the B2BinPay DeFi stack.
+
+- The **API layer** lives under `src/api` and wraps the generated `AccountsApi` (and related REST modules) so consumers interact with concise methods like `getAccountBalanceSummary`.
+- The **transaction utilities** under `src/utils/transactions` encapsulate `viem` logic for composing, signing, and (soon) decoding contract payloads.
+- Shared contract interfaces live under `src/abi`, ensuring builders/decoders stay consistent with the deployed contracts.
+- Documentation is collated in the `docs/` folder and is shipped with the npm package for discoverability.
+
+## High-Level Workflow
+1. Authenticate requests by instantiating `DefiClient` with your API key (sent automatically via `x-api-key`).
+2. Interact with REST endpoints using the client’s convenience methods.
+3. Build and sign contract transactions through the utility layer.
+4. Decode on-chain data returned from contract calls with the same helper set (decoders WIP).
+
+## Supported Workflows
+- **Authentication management** – every client instance binds to a sandbox or production base URL and injects the API key automatically.
+- **Account & ledger data** – fetch account details, balances, deployment queues, invoices, payouts, and transactions with a single method call.
+- **Chain selection** – use `selectChain(chainId)` to cache the deployment for a target network so subsequent invoice/payout/claim calls don’t need explicit deployment IDs.
+- **Invoice lifecycle** – create, update, and cancel invoices with tracking IDs, callback URLs, and custom currency selections.
+- **Payout lifecycle** – list payouts with filters, fetch payout details, patch metadata, and submit multisig signatures.
+- **Claims management** – enumerate claimable deposits and trigger single/batch claim executions tied to signed transaction hashes.
+- **Validation helpers** – `validateAddress` enforces address + network correctness before hitting write endpoints, reducing API errors.
+
+## Published Package
+The publishable module exports:
+- `DefiClient` and supporting types for API-key-based account flows.
+- Transaction helper utilities (`transactions.buildExecuteOperationsTransaction`, `transactions.createExecuteTypedData`, `transactions.signExecuteTypedData`, etc.) under a dedicated namespace.
+- Shared ABI exports (`abi.MULTI_SIG_WALLET_ABI`) for contract-aware integrations.
+
+See `examples/queue-sign.ts` for a combined flow that authenticates, fetches the linked account, builds a payout execute payload, and signs it, `examples/queue-execute.ts` for broadcasting the execute transaction, and `examples/claim-deposits.ts` for on-chain claim calldata and broadcasting.
+
+Refer to `docs/api-client.md` and `docs/transactions.md` for deep dives into each layer.

package/docs/transactions.md

@@ -0,0 +1,36 @@
+# Transaction Utilities
+
+This SDK exposes a cohesive set of helpers under `src/utils/transactions` to standardise interactions with the B2BinPay smart contract ecosystem.
+
+## Modules
+- `builders/`: Functions that create transaction payloads for contract methods. Currently includes `buildExecuteOperationsTransaction`, which encodes a `MultiSigWallet.execute` call for one or more queued operations.
+- `eip712/`: Helpers for building EIP-712 typed data (`createExecuteTypedData`, `buildExecuteTypedMessage`) and optional sign helpers.
+- `blockchain/MultisigBlockchainClient`: RPC-aware helper that wraps `eip712` utilities, producing execute-typed data while keeping API interactions optional; also exposes `buildClaimCalldata` for claim transactions.
+- ABI definitions required by these helpers are stored under `src/abi` to keep contract interfaces versioned alongside the SDK.
+
+## Design Goals
+- **Type safety**: Reuse the same DTOs/ABI typings across builders, signers, and decoders.
+- **Deterministic encoding**: Ensure every canonical contract call has a single builder that validates inputs before encoding.
+- **Composable flows**: Allow apps to compose API data + transaction payload generation without duplicating logic.
+- **Test coverage**: Each helper will include contract-level test vectors and integration fixtures.
+
+
+- Use `buildExecuteOperationsTransaction` (via `transactions.builders` or `MultisigBlockchainClient.buildExecuteTransaction`) to encode on-chain `MultiSigWallet.execute` calls for one or many queue operations.
+- Use `MultisigBlockchainClient.buildClaimCalldata` to assemble calldata for `claim`/`claimTo` when broadcasting claim transactions.
+- See `examples/queue-sign.ts` for signing, `examples/queue-execute.ts` / `examples/queue-execute-batch.ts` for broadcasting execute transactions, and `examples/claim-deposits.ts` for claim calldata + broadcasting.
+
+### Signing Queue Operations
+When a payout is created, the backend enqueues a multisig operation. The `executeOperationId` exposed by the queue can be signed locally using:
+
+```ts
+const typedData = await transactions.createExecuteTypedData({
+  contractAddress,
+  operation,
+  publicClient,
+});
+
+const signature = await account.signTypedData(typedData);
+```
+
+Submit the resulting signature with `submitOperationSignature` on the `DefiClient` to record approval. If you prefer a
+higher-level abstraction, instantiate `MultisigBlockchainClient` and call `createExecuteTypedData` directly.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@b2binpay/defi-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for the B2BinPay DeFi API with blockchain transaction utilities built on viem",
+  "private": false,
+  "license": "MIT",
+  "author": "B2BinPay (https://b2binpay.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/b2binpay/defi-sdk-nodejs.git"
+  },
+  "homepage": "https://github.com/b2binpay/defi-sdk-nodejs#readme",
+  "bugs": {
+    "url": "https://github.com/b2binpay/defi-sdk-nodejs/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check",
+    "lint:fix": "biome check --fix",
+    "prepublishOnly": "npm run build",
+    "generate:api": "rm -rf ./generated-contracts && openapi-generator-cli generate --openapitools ./openapitools.json",
+    "example:get-account-info": "tsx examples/get-account-info.ts",
+    "example:create-invoice": "tsx examples/create-invoice.ts",
+    "example:get-invoice-details": "tsx examples/get-invoice-details.ts",
+    "example:create-payout": "tsx examples/create-payout.ts",
+    "example:claim-deposits": "tsx examples/claim-deposits.ts",
+    "example:queue-sign": "tsx examples/queue-sign.ts",
+    "example:queue-execute": "tsx examples/queue-execute.ts",
+    "example:queue-execute-batch": "tsx examples/queue-execute-batch.ts"
+  },
+  "dependencies": {
+    "viem": "^2.40.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.2",
+    "@openapitools/openapi-generator-cli": "^2.25.2",
+    "@types/node": "^24.10.1",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.16.0",
+    "npm": "^10.9.2"
+  }
+}