@bufinance/ramps

Composable on/off-ramp + FX provider abstraction for the BU.FI ecosystem.

Ships a canonical four-interface contract (RampCustomerProvider, RampDestinationPreparer, RampPayoutProvider, RampWebhookProvider) and a ProviderRegistry dispatcher that picks providers by corridor + country + fiat. Designed to be consumed from both Node.js services (desk-v1's apps/shiva) and Cloudflare Workers (fx-pasillo).

What's in v0.2.0

| Subpath | Status | Notes | | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @bufinance/ramps/core | ✅ | Interfaces, registry, in-memory stores, errors, intent-hash | | @bufinance/ramps/alfred | ✅ | Real provider: LATAM send-money (USD↔MXN/BRL/COP/ARS), on/off-ramp (MX/BR/CO/AR/US/HK), KYC/KYB scaffolds. Web Crypto webhook verification. Dependency-injection factory — host provides AlfredApiClient, AlfredKycClient, AlfredKybClient, AlfredQuoteClient, AlfredSendMoneyClient, CircleTransferClient. | | @bufinance/ramps/bridge | ✅ | Real provider: USD/EUR/GBP/MXN/BRL off-ramp (ACH, Wire, SEPA, Faster Payments, SPEI, PIX). Web Crypto HMAC-SHA256 webhook verification. DI factory — host provides BridgeApiClient, BridgeExternalAccountClient, BridgeCustomerClient. On-ramp arrives in v0.3.0. | | @bufinance/ramps/stablefx | ⏳ stub | Mock + real-mode lands once Circle StableFX integration extracts from fx-pasillo. | | @bufinance/ramps/kyc | ⏳ stub | PersonaKycBridge skeleton. | | @bufinance/ramps/compliance | ⏳ stub | OFAC / sanctions / travel-rule helpers — out of v1 scope. |

Install

npm install @bufinance/ramps
# or
bun add @bufinance/ramps

Quick start — register the Alfred provider

import { ProviderRegistry } from '@bufinance/ramps/core';
import { createAlfredProvider } from '@bufinance/ramps/alfred';

const registry = new ProviderRegistry({
  priority: ['stablefx', 'alfred', 'bridge'],
});

registry.register(
  createAlfredProvider({
    api, // your AlfredApiClient implementation
    kyc, // your AlfredKycClient implementation
    kyb, // your AlfredKybClient implementation
    quote, // your AlfredQuoteClient implementation
    sendMoney, // your AlfredSendMoneyClient implementation
    circle, // your CircleTransferClient implementation
    promoterId: process.env.ALFRED_PROMOTER_ID!,
    webhookSecret: process.env.ALFRED_WEBHOOK_SECRET,
  })
);

const provider = registry.getPayoutProvider('alfred');
const quote = await provider.getQuote({
  kind: 'send',
  source: { currency: 'USD', country: 'US' },
  destination: { currency: 'MXN', country: 'MX' },
  amount: 100_000_00n, // bigint, minor units
});

Design

• Money is always BigInt minor units. Decimal strings are converted at the provider boundary. See currencyMinorMultiplier / minorToDecimalString / decimalStringToMinor in alfred/.
• Errors are typed. Every provider boundary throws a RampError subclass — RampValidationError, RampRetryableError, RampPermanentError, RampUnsupportedError, RampQuoteExpiredError, RampComplianceError, RampKycIntentMismatchError, RampDuplicateIntentError, RampFailoverError, RampInfraError. Use isRampError() to guard.
• Webhooks are content-addressed. RampWebhookProvider.verifyAndParseWebhook returns a canonical RampWebhookEvent or null. Never throw on bad signatures — fail closed and 200 the request.
• Dependency injection at boot. Adapters never import service classes directly. Hosts (apps/shiva for desk-v1, fx-pasillo for the Worker side) build clients and pass them as structural dep bags. Keeps the module graph one-way: apps depend on packages, never the reverse.

Versioning

0.x — pre-1.0, every minor bump is potentially breaking. Pin to "@bufinance/ramps": "0.1.x" until 1.0.

Tag prefix is ramps-v (set in .npmrc) so future npm version bumps inside this package don't collide with desk-v1's app-level tags.

Workspace consumers

desk-v1 consumes this package via workspace:*. The dist/ build runs on prepublishOnly and is the published artifact, but local dev still points at compiled output — run bun run build in packages/ramps/ after edits, or rely on turbo run build --filter=@bufinance/ramps from the repo root.

License

MIT — see LICENSE.