@luxfi/bank 1.0.0

package/README.md

@@ -0,0 +1,33 @@
+# @luxfi/bank
+
+Typed client for the Lux banking API (`/v1/bank`) — accounts, transfers,
+payments, beneficiaries, cards, crypto, exchange, FX, and membership plans.
+Sandbox and production serve the identical contract (LP-3040); point the
+client at either.
+
+```ts
+import { Bank } from '@luxfi/bank'
+
+const bank = new Bank({
+  baseUrl: 'https://api.sandbox.lux.financial',
+  token: () => sessionStorage.getItem('token'),
+})
+
+const plans = await bank.plans()
+const { holdings } = await bank.wallet()
+await bank.sendCrypto('ETH', 400_000, '0x1234…5678') // minor units, 6 dp
+
+// Card issuance — branch only on the issuer's status/nextAction pair:
+const { data } = await bank.cardAccount()
+if (data.virtualAccount?.nextAction === 'complete_kyc') {
+  const { url } = await bank.cardKYCURL() // sensitive — straight to the browser
+  window.open(url)
+}
+```
+
+Amounts are integers in minor units; every balance carries `decimals`
+(2 for most fiat, 0 for JPY, 6 for crypto). Errors throw `BankError`
+with `status` and the parsed body.
+
+Docs: [docs.lux.financial](https://docs.lux.financial/docs/banking) ·
+Spec: LP-3040.

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+export interface BankConfig {
+    /** API origin, e.g. "https://api.lux.financial" or "https://api.sandbox.lux.financial". */
+    baseUrl: string;
+    /** IAM bearer token, or a getter so rotation is picked up per request. */
+    token?: string | (() => string | null | undefined);
+    fetch?: typeof fetch;
+}
+export declare class BankError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export interface Config {
+    sandbox: boolean;
+    demoLogin?: boolean;
+    demoEmail?: string;
+    fiat: string[];
+    crypto: string[];
+    network: string;
+    disclaimer: string;
+    partner?: {
+        name: string;
+        terms: string;
+        privacy: string;
+    };
+}
+export interface Plan {
+    id: string;
+    name: string;
+    monthly: number;
+    card: 'virtual' | 'plastic' | 'metal';
+    iban: boolean;
+    freeACH: number;
+    freeWires: number;
+    achFee: number;
+    wireFee: number;
+    fxPct: number;
+    depositPct: number;
+    dailyLimit: number;
+    monthlyLimit: number;
+    holders: number;
+    invite?: boolean;
+    perks: string[];
+}
+export interface Balance {
+    currency: string;
+    available: number;
+    held: number;
+    decimals: number;
+    kind: 'fiat' | 'crypto';
+    valueUsd: number;
+}
+export interface Account {
+    id: string;
+    entityName: string;
+    entityType: 'individual' | 'business';
+    country: string;
+    currency: string;
+    status: string;
+    kycStatus: string;
+    iban: string;
+}
+export interface Wallet {
+    id: string;
+    currency: string;
+    address: string;
+    network: string;
+    status: string;
+}
+export interface Card {
+    id: string;
+    holderName: string;
+    brand: string;
+    type: string;
+    last4: string;
+    display: string;
+    expMonth: number;
+    expYear: number;
+    currency: string;
+    status: string;
+    design: string;
+}
+export interface Transaction {
+    id: string;
+    type: string;
+    direction: 'credit' | 'debit';
+    amount: number;
+    currency: string;
+    decimals: number;
+    status: string;
+    reference: string;
+    created: string;
+}
+export interface Beneficiary {
+    id: string;
+    name: string;
+    currency: string;
+    country: string;
+    [k: string]: unknown;
+}
+export interface CryptoPrice {
+    asset: string;
+    usd: number;
+    decimals: number;
+}
+export interface CryptoMove {
+    txHash: string;
+    network: string;
+    asset: string;
+    amount: number;
+    toAddress?: string;
+    balances: Balance[];
+}
+export interface ExchangeQuote {
+    fromCurrency: string;
+    toCurrency: string;
+    fromAmount: number;
+    toAmount: number;
+    fromDecimals: number;
+    toDecimals: number;
+    rate: number;
+    expiresAt: string;
+}
+export interface ExchangeResult {
+    fromCurrency: string;
+    toCurrency: string;
+    fromAmount: number;
+    toAmount: number;
+    rate: number;
+    balances: Balance[];
+}
+export interface FXQuote {
+    sellCurrency: string;
+    buyCurrency: string;
+    sellAmount: number;
+    buyAmount: number;
+    rate: number;
+    quoteId: string;
+    expiresAt: string;
+}
+/** The issuer's normalized card-lifecycle state; branch on this pair only. */
+export interface IssuerState {
+    status: 'not_started' | 'pending' | 'approved' | 'rejected' | 'error' | string;
+    nextAction: 'register' | 'complete_kyc' | 'accept_agreement' | 'retry_kyc' | 'order_card' | 'none' | string;
+}
+export interface CardholderProfile {
+    firstName: string;
+    middleName?: string;
+    lastName: string;
+    cardHolderFirstName: string;
+    cardHolderLastName: string;
+    gender: 0 | 1 | 2;
+    dateOfBirth: string;
+    placeOfBirth: string;
+    occupation: number;
+    phoneNumber: string;
+    phoneNumberCountryCode: string;
+    address: {
+        addressLine1: string;
+        addressLine2?: string;
+        subdivision: string;
+        city: string;
+        postalCode: string;
+        country: string;
+    };
+}
+export interface Overview {
+    account: Account;
+    balances: Balance[];
+    wallet: Wallet | null;
+    cards: Card[];
+    transactions: Transaction[];
+    [k: string]: unknown;
+}
+export declare class Bank {
+    private baseUrl;
+    private token?;
+    private fetchFn;
+    constructor(config: BankConfig);
+    private request;
+    health(): Promise<{
+        status: string;
+        sandbox: boolean;
+    }>;
+    config(): Promise<Config>;
+    plans(): Promise<Plan[]>;
+    onboard(profile: Record<string, unknown>): Promise<{
+        account: Account;
+    }>;
+    overview(): Promise<Overview>;
+    transactions(): Promise<Transaction[]>;
+    accounts(): Promise<Account[]>;
+    transfer(fromAccountId: string, toAccountId: string, amount: number, currency: string, reference?: string): Promise<{
+        debitId: string;
+        creditId: string;
+        status: string;
+    }>;
+    pay(accountId: string, beneficiaryId: string, amount: number, currency: string, reference?: string): Promise<{
+        transactionId: string;
+        status: string;
+    }>;
+    balances(accountId: string): Promise<Balance[]>;
+    wallets(accountId: string): Promise<Wallet[]>;
+    accountTransactions(accountId: string): Promise<Transaction[]>;
+    beneficiaries(): Promise<Beneficiary[]>;
+    createBeneficiary(beneficiary: Record<string, unknown>): Promise<Beneficiary>;
+    deleteBeneficiary(id: string): Promise<void>;
+    cards(): Promise<Card[]>;
+    issueCard(card: Record<string, unknown>): Promise<Card>;
+    freezeCard(id: string): Promise<Card>;
+    unfreezeCard(id: string): Promise<Card>;
+    createCardAccount(profile: CardholderProfile): Promise<{
+        status: string;
+        message?: string;
+    }>;
+    cardAccount(): Promise<{
+        status: string;
+        data: Record<string, unknown>;
+    }>;
+    cardKYC(): Promise<{
+        status: string;
+        data: Record<string, unknown>;
+    }>;
+    createVirtualCard(): Promise<{
+        status: string;
+        data?: IssuerState;
+    }>;
+    /** Sensitive: hand the URL straight to the user's browser; never log or persist it. */
+    cardKYCURL(): Promise<{
+        url: string;
+    }>;
+    /** Sensitive: hand the URL straight to the user's browser; never log or persist it. */
+    cardConsentURL(): Promise<{
+        url: string;
+    }>;
+    orderVirtualCard(): Promise<{
+        status: string;
+        message?: string;
+    }>;
+    wallet(): Promise<{
+        wallet: Wallet;
+        holdings: Balance[];
+        network: string;
+        sandbox: boolean;
+    }>;
+    cryptoPrices(): Promise<{
+        prices: CryptoPrice[];
+        sandbox: boolean;
+    }>;
+    sendCrypto(asset: string, amount: number, toAddress: string): Promise<CryptoMove>;
+    /** Sandbox-only testnet faucet. */
+    depositCrypto(asset: string, amount: number): Promise<CryptoMove>;
+    exchangeQuote(fromCurrency: string, toCurrency: string, amount: number): Promise<ExchangeQuote>;
+    exchange(fromCurrency: string, toCurrency: string, amount: number): Promise<ExchangeResult>;
+    fxQuote(sellCurrency: string, buyCurrency: string, amount: number): Promise<FXQuote>;
+    fxExecute(accountId: string, quoteId: string): Promise<Record<string, unknown>>;
+    sandboxLogin(email: string, password: string): Promise<{
+        token: string;
+        user: {
+            id: string;
+            email: string;
+        };
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,175 @@
+// @luxfi/bank — typed client for the Lux banking API (/v1/bank).
+// One surface: accounts, transfers, payments, beneficiaries, cards (with the
+// provider-neutral issuer lifecycle), crypto, exchange, FX, membership plans.
+// Sandbox and production serve the identical contract (LP-3040).
+export class BankError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'BankError';
+    }
+}
+// -- Client --
+export class Bank {
+    baseUrl;
+    token;
+    fetchFn;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.token = config.token;
+        this.fetchFn = config.fetch ?? fetch;
+    }
+    async request(method, path, body) {
+        const headers = { 'Content-Type': 'application/json' };
+        const token = typeof this.token === 'function' ? this.token() : this.token;
+        if (token)
+            headers['Authorization'] = `Bearer ${token}`;
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            throw new BankError(data.message || data.error || `Request failed: ${res.status}`, res.status, data);
+        }
+        return data;
+    }
+    // Public
+    health() {
+        return this.request('GET', '/v1/bank/health');
+    }
+    config() {
+        return this.request('GET', '/v1/bank/config');
+    }
+    plans() {
+        return this.request('GET', '/v1/bank/plans');
+    }
+    // Onboarding + dashboard
+    onboard(profile) {
+        return this.request('POST', '/v1/bank/onboard', profile);
+    }
+    overview() {
+        return this.request('GET', '/v1/bank/overview');
+    }
+    transactions() {
+        return this.request('GET', '/v1/bank/transactions');
+    }
+    accounts() {
+        return this.request('GET', '/v1/bank/account/summary');
+    }
+    // Money movement
+    transfer(fromAccountId, toAccountId, amount, currency, reference) {
+        return this.request('POST', '/v1/bank/transfers', {
+            fromAccountId,
+            toAccountId,
+            amount,
+            currency,
+            reference,
+        });
+    }
+    pay(accountId, beneficiaryId, amount, currency, reference) {
+        return this.request('POST', '/v1/bank/payments/outbound', {
+            accountId,
+            beneficiaryId,
+            amount,
+            currency,
+            reference,
+        });
+    }
+    // Per-account reads
+    balances(accountId) {
+        return this.request('GET', `/v1/bank/accounts/${accountId}/balances`);
+    }
+    wallets(accountId) {
+        return this.request('GET', `/v1/bank/accounts/${accountId}/wallets`);
+    }
+    accountTransactions(accountId) {
+        return this.request('GET', `/v1/bank/accounts/${accountId}/transactions`);
+    }
+    // Beneficiaries
+    beneficiaries() {
+        return this.request('GET', '/v1/bank/beneficiaries');
+    }
+    createBeneficiary(beneficiary) {
+        return this.request('POST', '/v1/bank/beneficiaries', beneficiary);
+    }
+    deleteBeneficiary(id) {
+        return this.request('DELETE', `/v1/bank/beneficiaries/${id}`);
+    }
+    // Cards — ledger
+    cards() {
+        return this.request('GET', '/v1/bank/cards');
+    }
+    issueCard(card) {
+        return this.request('POST', '/v1/bank/cards', card);
+    }
+    freezeCard(id) {
+        return this.request('POST', `/v1/bank/cards/${id}/freeze`);
+    }
+    unfreezeCard(id) {
+        return this.request('POST', `/v1/bank/cards/${id}/unfreeze`);
+    }
+    // Cards — issuer lifecycle (provider-neutral; branch on status/nextAction)
+    createCardAccount(profile) {
+        return this.request('POST', '/v1/bank/cards/account', profile);
+    }
+    cardAccount() {
+        return this.request('GET', '/v1/bank/cards/account');
+    }
+    cardKYC() {
+        return this.request('GET', '/v1/bank/cards/kyc');
+    }
+    createVirtualCard() {
+        return this.request('POST', '/v1/bank/cards/virtual');
+    }
+    /** Sensitive: hand the URL straight to the user's browser; never log or persist it. */
+    cardKYCURL() {
+        return this.request('GET', '/v1/bank/cards/virtual/kyc-url');
+    }
+    /** Sensitive: hand the URL straight to the user's browser; never log or persist it. */
+    cardConsentURL() {
+        return this.request('GET', '/v1/bank/cards/virtual/consent-url');
+    }
+    orderVirtualCard() {
+        return this.request('POST', '/v1/bank/cards/virtual/order');
+    }
+    // Crypto
+    wallet() {
+        return this.request('GET', '/v1/bank/wallet');
+    }
+    cryptoPrices() {
+        return this.request('GET', '/v1/bank/crypto/prices');
+    }
+    sendCrypto(asset, amount, toAddress) {
+        return this.request('POST', '/v1/bank/crypto/send', { asset, amount, toAddress });
+    }
+    /** Sandbox-only testnet faucet. */
+    depositCrypto(asset, amount) {
+        return this.request('POST', '/v1/bank/crypto/deposit', { asset, amount });
+    }
+    // Exchange (fiat FX + crypto buy/sell/convert)
+    exchangeQuote(fromCurrency, toCurrency, amount) {
+        return this.request('POST', '/v1/bank/exchange/quote', { fromCurrency, toCurrency, amount });
+    }
+    exchange(fromCurrency, toCurrency, amount) {
+        return this.request('POST', '/v1/bank/exchange/execute', { fromCurrency, toCurrency, amount });
+    }
+    // Dealt FX
+    fxQuote(sellCurrency, buyCurrency, amount) {
+        return this.request('POST', '/v1/bank/fx/quote', { sellCurrency, buyCurrency, amount });
+    }
+    fxExecute(accountId, quoteId) {
+        return this.request('POST', '/v1/bank/fx/execute', { accountId, quoteId });
+    }
+    // Sandbox demo login (sandbox deployments only)
+    sandboxLogin(email, password) {
+        return this.request('POST', '/v1/bank/login', {
+            email,
+            password,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@luxfi/bank",
+  "version": "1.0.0",
+  "description": "Typed client for the Lux banking API (/v1/bank) — accounts, payments, cards, crypto, FX, and membership plans.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luxfi/bank.git",
+    "directory": "sdk"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}