@lumeo/sdk

Official TypeScript SDK for Lumeo, a programmable financial infrastructure platform for India's developer ecosystem.

Lumeo's Vault API helps freelancers, agencies, and B2B exporters programmatically manage inbound payments, contract-engine rules, settlement sweeps, beneficiaries, and compliance workflows.

Complete documentation set

• README.md (this file): quickstart + core usage
• docs/END_TO_END.md: full integration walkthrough from setup to production
• docs/API_REFERENCE.md: method-level API surface and behavior
• docs/RELEASE.md: build, test, package, and publish runbook

Package artifact metadata (from npm pack --dry-run)

| Field | Value | |---|---| | Package | @lumeo/[email protected] | | Unpacked size | 328.5 kB | | Shasum | 6fc5a72d86a4e8c47275fa697bd36beaf5056291 | | Integrity | sha512-oqWmQugxIdUqk[...]Bpcymsbp/XtLQ== | | Total files | 8 |

Installation

npm install @lumeo/sdk

Quickstart

import LumeoClient, { RuleDSL } from '@lumeo/sdk';

const client = new LumeoClient({
	apiKey: process.env.LUMEO_API_KEY!,
	baseUrl: 'https://api.lumeo.in/v1',
	timeout: 30_000,
	retries: 3,
	idempotencyPrefix: 'myapp',
});

// 1) Create vault
const vault = await client.vaults.create({
	ownerId: 'org_123',
	label: 'Export Receivables - USD',
	currency: 'USD',
	metadata: { segment: 'b2b-export' },
});

// 2) Create rule (split + notify)
const dsl: RuleDSL = {
	version: '1.0',
	trigger: {
		event: 'inbound_payment',
		conditions: [{ field: 'amountRaw', operator: 'gt', value: 5_000_000 }],
	},
	actions: [
		{
			type: 'split',
			splits: [
				{ beneficiaryId: 'bene_ops', percentage: 70 },
				{ beneficiaryId: 'bene_gst', percentage: 30 },
			],
		},
		{
			type: 'notify',
			channel: 'webhook',
			payload: { topic: 'payment.large' },
		},
	],
};

const rule = await client.rules.create({
	ownerId: 'org_123',
	name: 'Large Invoice Split Rule',
	dsl,
});

// 3) Attach rule to vault
await client.vaults.attachRule(vault.id, rule.id);

// 4) Query received payments (transactions)
const txPage = await client.transactions.list({ vaultId: vault.id, limit: 10 });
console.log('Recent tx count:', txPage.data.length);

Client configuration

type LumeoClientConfig = {
	apiKey: string;
	baseUrl?: string;
	timeout?: number;          // default: 30000 ms
	retries?: number;          // default: 3
	idempotencyPrefix?: string;
	defaultHeaders?: HeadersInit;
	onRequest?: (ctx) => void | Promise<void>;
	onResponse?: (ctx) => void | Promise<void>;
	onError?: (ctx) => void | Promise<void>;
};

Advanced client hooks (observability)

const client = new LumeoClient({
	apiKey: process.env.LUMEO_API_KEY!,
	defaultHeaders: { 'x-app-version': '1.2.0' },
	onRequest: ({ method, url, attempt }) => {
		console.log('[SDK request]', method, url, attempt);
	},
	onResponse: ({ status, durationMs, requestId }) => {
		console.log('[SDK response]', status, durationMs, requestId);
	},
	onError: ({ error, durationMs }) => {
		console.error('[SDK error]', durationMs, error);
	},
});

Auth and idempotency behavior

• Every request adds Authorization: Bearer {apiKey}.
• POST, PUT, PATCH requests auto-add Idempotency-Key (UUID v4).
• Override per request via options:

await client.vaults.create(
	{ ownerId: 'org_123', label: 'Main INR', currency: 'INR' },
	{ idempotencyKey: 'invoice-3491-create-vault' },
);

API reference

vaults

| Method | Description | |---|---| | create(params, opts?) | Create a programmable inbound payment vault | | get(vaultId, opts?) | Get vault by ID | | list(params?, opts?) | List vaults with cursor pagination | | listAutoPaginate(params?) | Async iterator over all vault pages | | update(vaultId, params, opts?) | Update vault metadata / settlement rule ref | | deactivate(vaultId, opts?) | Soft-deactivate vault | | getBalance(vaultId, opts?) | Get real-time vault balance snapshot | | attachRule(vaultId, ruleId, opts?) | Attach rule to vault | | detachRule(vaultId, ruleId, opts?) | Detach rule from vault | | sweep(vaultId, params, opts?) | Trigger manual settlement sweep |

rules

| Method | Description | |---|---| | create(params, opts?) | Create a new Contract Engine rule | | get(ruleId, opts?) | Get rule by ID | | list(params?, opts?) | List rules with cursor pagination | | listAutoPaginate(params?) | Async iterator over all rules | | update(ruleId, params, opts?) | Update rule | | delete(ruleId, opts?) | Delete rule | | validate(dsl, opts?) | Validate DSL (local + API validator) | | simulate(ruleId, params, opts?) | Simulate rule execution with sample payload |

transactions

| Method | Description | |---|---| | list(params?, opts?) | List transactions | | listAutoPaginate(params?) | Async iterator over all transaction pages | | get(transactionId, opts?) | Get transaction by ID | | refund(transactionId, params, opts?) | Initiate refund | | getTimeline(transactionId, opts?) | Get transaction audit timeline |

beneficiaries

| Method | Description | |---|---| | create(params, opts?) | Create beneficiary | | get(beneficiaryId, opts?) | Get beneficiary | | list(params?, opts?) | List beneficiaries | | listAutoPaginate(params?) | Async iterator over all beneficiary pages | | update(beneficiaryId, params, opts?) | Update beneficiary | | delete(beneficiaryId, opts?) | Delete beneficiary | | verify(beneficiaryId, params?, opts?) | Trigger bank account verification |

compliance

| Method | Description | |---|---| | upload(params, opts?) | Upload compliance document (multipart) | | get(documentId, opts?) | Get compliance document | | list(params?, opts?) | List compliance documents | | listAutoPaginate(params?) | Async iterator over all compliance doc pages | | getStatus(documentId, opts?) | Get document status | | requestResubmission(documentId, params, opts?) | Request resubmission |

Rule DSL guide

1) Split 30% to GST account on inbound > ₹50,000

const dsl: RuleDSL = {
	version: '1.0',
	trigger: {
		event: 'inbound_payment',
		conditions: [{ field: 'amountRaw', operator: 'gt', value: 5_000_000 }],
	},
	actions: [
		{
			type: 'split',
			splits: [
				{ beneficiaryId: 'bene_ops', percentage: 70 },
				{ beneficiaryId: 'bene_gst', percentage: 30 },
			],
		},
	],
};

2) Escrow release after 7 days

const dsl: RuleDSL = {
	version: '1.0',
	trigger: { event: 'inbound_payment' },
	actions: [
		{
			type: 'escrow',
			releaseCondition: { field: 'ageDays', operator: 'gte', value: 7 },
		},
	],
};

3) Scheduled sweep to treasury wallet

const dsl: RuleDSL = {
	version: '1.0',
	trigger: { event: 'schedule' },
	actions: [
		{
			type: 'sweep',
			destination: 'wallet:treasury_main',
			currency: 'INR',
		},
	],
};

Webhook guide

Use webhook helpers to verify HMAC signatures and parse typed events.

import { constructWebhookEvent } from '@lumeo/sdk';

const rawBody = requestRawBody; // string | Uint8Array | ArrayBuffer
const signature = req.headers['x-lumeo-signature'] as string;
const secret = process.env.LUMEO_WEBHOOK_SECRET!;

const event = await constructWebhookEvent(rawBody, signature, secret);

switch (event.type) {
	case 'payment.received':
		console.log(event.payload.transactionId, event.payload.amountRaw);
		break;
	case 'compliance.status_changed':
		console.log(event.payload.currentStatus);
		break;
}

Supported event types:

• vault.created
• payment.received
• rule.triggered
• settlement.completed
• compliance.status_changed
• sweep.initiated
• sweep.completed

Error handling

All SDK errors inherit from LumeoError.

| Error class | Typical status | |---|---| | LumeoAuthError | 401, 403 | | LumeoRateLimitError | 429 | | LumeoValidationError | 400, 409, 422 | | LumeoAPIError | Other non-2xx API errors |

import {
	LumeoAuthError,
	LumeoRateLimitError,
	LumeoValidationError,
} from '@lumeo/sdk';

try {
	await client.vaults.get('vault_123');
} catch (error) {
	if (error instanceof LumeoAuthError) {
		// refresh or rotate API key
	} else if (error instanceof LumeoRateLimitError) {
		// use retryAfterSeconds for backoff
	} else if (error instanceof LumeoValidationError) {
		// fix payload
	}
}

TypeScript usage notes

• SDK is fully typed and built with strict TypeScript settings.
• ESM and CJS builds are both published.
• No runtime dependencies are required.
• LumeoClient is available as both default and named export.

Local development

npm run typecheck
npm run test
npm run build

Release and publish

npm run prepublishOnly
npm pack --dry-run

Publish manually (PowerShell):

$env:NODE_AUTH_TOKEN="YOUR_NPM_TOKEN"; npm publish --access public

See docs/RELEASE.md for the full end-to-end release checklist, CI tag flow, and troubleshooting.