@trusset/sdk 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# @trusset/sdk
+
+TypeScript SDK for the Trusset tokenization infrastructure API. Built for financial institutions, banks, and fintechs integrating MiCA/eWpG-compliant tokenized asset management.
+
+Zero dependencies. Works in Node.js 18+ and modern runtimes with native `fetch`.
+
+## Setup
+
+```bash
+npm install @trusset/sdk
+```
+
+Requires an API key from your Trusset instance dashboard. Each API key is scoped to a single instance (isolated environment with its own data, contracts, and network config).
+
+```ts
+import { TrussetClient } from '@trusset/sdk'
+
+const trusset = new TrussetClient({
+  apiKey: 'tsk_live_...',
+  // baseUrl defaults to https://api.trusset.org
+})
+```
+
+## Modules
+
+The SDK currently ships the `customers` module. Tokenization, trading, and lending modules will follow.
+
+### customers.manage - CRUD and search
+
+```ts
+// Create a customer (with or without a wallet)
+const customer = await trusset.customers.manage.create({
+  name: 'Acme GmbH',
+  country: 'DE',
+  investorType: 'PROFESSIONAL',
+  externalId: 'your-internal-id-123',
+})
+
+// The customer gets a referenceKey if no wallet was provided.
+// Link a wallet later:
+await trusset.customers.manage.linkWallet({
+  referenceKey: customer.referenceKey!,
+  walletAddress: '0x...',
+})
+
+// Search
+const byName = await trusset.customers.manage.searchByName('Acme')
+const byWallet = await trusset.customers.manage.searchByWallet('0x...')
+const byExtId = await trusset.customers.manage.searchByExternalId('your-internal-id-123')
+
+// List with pagination
+const page = await trusset.customers.manage.list({ limit: 50, offset: 0, search: 'bank' })
+
+// Update
+await trusset.customers.manage.update(customer.id, { country: 'AT' })
+
+// Archive
+await trusset.customers.manage.archive(customer.id)
+```
+
+### customers.identity - On-chain KYC
+
+All write operations require a configured relayer wallet on the instance. The relayer signs transactions against the IdentityRegistry contract (UUPS upgradeable, MiCA/eWpG compliant).
+
+```ts
+// Verify a single identity on-chain
+const result = await trusset.customers.identity.verify({
+  walletAddress: '0x...',
+  country: 'DE',
+  investorType: 'RETAIL',
+  softExpiryDays: 365,
+  hardExpiryDays: 730,
+})
+// result.txHash, result.gasUsed
+
+// Batch verify up to 500 identities in one transaction
+await trusset.customers.identity.batchVerify([
+  { walletAddress: '0xaaa...', country: 'DE' },
+  { walletAddress: '0xbbb...', country: 'FR', investorType: 'PROFESSIONAL' },
+])
+
+// Revoke
+await trusset.customers.identity.revoke('0x...')
+
+// Get combined on-chain + off-chain status
+const status = await trusset.customers.identity.getStatus('0x...')
+// status.onChain.isVerified, status.offChain.status
+
+// Compliance check before a token transfer
+const check = await trusset.customers.identity.canTransfer({
+  from: '0xaaa...',
+  to: '0xbbb...',
+  amount: '1000000000000000000',
+  fromBalance: '5000000000000000000',
+  toBalance: '0',
+})
+// check.allowed, check.reason, check.senderStatus, check.receiverStatus
+```
+
+### customers.idLinks - KYC verification links
+
+Send Sumsub-powered KYC verification links to investors via email or SMS.
+
+```ts
+const link = await trusset.customers.idLinks.create({
+  recipientEmail: 'investor@example.com',
+  investorType: 'RETAIL',
+  country: 'DE',
+  expiryDays: 30,
+  sendVia: ['email'],
+})
+// link.verificationUrl, link.token
+
+const links = await trusset.customers.idLinks.list({ status: 'PENDING' })
+await trusset.customers.idLinks.revoke(link.id)
+await trusset.customers.idLinks.resend(link.id, ['email'])
+```
+
+### customers.sync - Database synchronization
+
+The sync module is built for institutions migrating existing customer databases into Trusset. It handles batched upserts, conflict resolution, and optional on-chain verification in a single call.
+
+```ts
+import { SyncRecord } from '@trusset/sdk'
+
+// Map your existing database rows to SyncRecord
+const records: SyncRecord[] = existingCustomers.map(row => ({
+  externalId: row.id,              // Your system's unique ID
+  name: row.fullName,
+  walletAddress: row.ethAddress,   // Optional
+  country: row.countryCode,
+  investorType: 'RETAIL',
+  metadata: { source: 'legacy-crm' },
+}))
+
+const result = await trusset.customers.sync.importRecords(records, {
+  batchSize: 50,
+  onConflict: 'update',           // 'skip' or 'update'
+  verifyOnChain: true,            // Also verify wallets on IdentityRegistry
+  verificationDefaults: {
+    softExpiryDays: 365,
+    hardExpiryDays: 730,
+  },
+  onProgress: (done, total) => {
+    console.log(`Synced ${done}/${total}`)
+  },
+})
+
+// result.created, result.updated, result.skipped, result.errors
+
+// Export back to your system
+const exported = await trusset.customers.sync.exportRecords()
+```
+
+## Error handling
+
+All errors extend `TrussetError` and carry machine-readable codes.
+
+```ts
+import { TrussetError, AuthError, ValidationError, NetworkError } from '@trusset/sdk'
+
+try {
+  await trusset.customers.manage.get('0xinvalid')
+} catch (err) {
+  if (err instanceof AuthError) {
+    // API key invalid or expired
+  }
+  if (err instanceof ValidationError) {
+    // Bad input, check err.message
+  }
+  if (err instanceof TrussetError) {
+    // err.code, err.statusCode, err.requestId
+  }
+}
+```
+
+The HTTP layer retries transient errors (408, 429, 5xx, network failures) with exponential backoff. Default: 3 retries, 30s timeout. Override via config:
+
+```ts
+new TrussetClient({
+  apiKey: '...',
+  timeoutMs: 60_000,
+  maxRetries: 5,
+})
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | required | Instance API key from dashboard |
+| `baseUrl` | `string` | `https://api.trusset.org` | API base URL |
+| `timeoutMs` | `number` | `30000` | Request timeout in ms |
+| `maxRetries` | `number` | `3` | Retries on transient failures |
+| `logger` | `Logger` | silent | Custom logger implementing `debug/info/warn/error` |
+
+## Architecture
+
+```
+src/
+  index.ts              Public exports
+  client.ts             TrussetClient entry point
+  types/
+    common.ts           Shared types (config, API envelope, pagination)
+    customers.ts        All customer-related types and interfaces
+  modules/
+    customers/
+      index.ts          Customers facade (combines sub-modules)
+      management.ts     CRUD, search, wallet linking
+      identity.ts       On-chain verification, compliance checks
+      id-links.ts       KYC verification link management
+      sync.ts           Bulk database import/export
+  utils/
+    http.ts             HTTP client with retries and error mapping
+    errors.ts           Error class hierarchy
+    validation.ts       Input validation helpers
+```
+
+The SDK is structured so additional product modules (tokenization, trading, lending) slot in as sibling directories under `modules/`. Each module receives the shared `HttpClient` instance and exposes a clean public API.
+
+## Compatibility
+
+- **TypeScript / ESM** - primary target, full type safety
+- **Node.js / CommonJS** - dual CJS/ESM build via tsup
+- **Java / Python** - the SDK calls a standard REST API with JSON over HTTPS. Any HTTP client in any language works. Typed wrappers for Java and Python are planned.
+
+## Build
+
+```bash
+npm install
+npm run build        # outputs to dist/
+npm run typecheck    # type validation
+npm run test         # vitest
+```
+
+## License
+
+MIT - Trusset UG
+
+
+For future modules (tokenization, trading, lending) we*ll go as siblings:
+└── modules/
+        ├── customers/
+        ├── tokenization/                 # next
+        ├── trading/                      # next
+        └── lending/                      # next