@fianto/sdk

@fianto/sdk is the server side of every integration: a typed client for the v1 API, webhook verification under @fianto/sdk/webhooks, and route handlers that work with any Request / Response framework under @fianto/sdk/handlers. The framework packages wrap those handlers.

pnpm add @fianto/sdk

Create the clientCopy Anchor Link

import { Fianto } from '@fianto/sdk';

// Reads FIANTO_APP_ID and FIANTO_APP_SECRET, and FIANTO_BASE_URL when it is set.
const fianto = new Fianto();

// Or pass everything yourself, for example where there is no process.env.
export function clientFor(env: { FIANTO_APP_ID: string; FIANTO_APP_SECRET: string }) {
  return new Fianto({ appId: env.FIANTO_APP_ID, appSecret: env.FIANTO_APP_SECRET, maxRetries: 3 });
}

console.log(await fianto.application.retrieve());

A missing appId or appSecret throws at construction, naming the option and the variable to set. Keys belong to the deployment that issued them: for a self-hosted or local backend, set FIANTO_BASE_URL, or calls go to https://api.fianto.xyz and answer 401 invalid_api_credentials.

ResourcesCopy Anchor Link

Ids that go into the path (every retrieve, cancel and reissueLink) are checked against ^[A-Za-z0-9_]{1,64}$ before any request is sent. The orderId of retrieveByOrderId is your own id, sent as a query parameter, and is not checked. Request and response fields are the API's own, in snake_case: see Checkout sessions and Subscriptions.

list() returns a PagePromise: await it for one page ({ items, next_cursor }), or for await it to walk every item. See Pagination.

Per-call optionsCopy Anchor Link

Every method takes a last options argument:

Every retrieve(id, …), checkoutSessions.cancel, reissueLink, application.retrieve and sendTestEvent also take a params object that is empty today and sits before options, so pass {} to reach it. subscriptions.cancel is different: its params is the required { at }.

import { Fianto } from '@fianto/sdk';

const fianto = new Fianto();

export async function cancelCheckout(sessionId: string) {
  // params is {} today; options comes after it.
  return fianto.checkoutSessions.cancel(sessionId, {}, { idempotencyKey: `cancel:${sessionId}` });
}

For crash-safe keys, see Idempotency.

AmountsCopy Anchor Link

The API takes amounts as decimal strings ('12.50') and returns them as strings of USDC base units with 6 decimals ('12500000'). usdc converts between the two without floating point:

import { usdc } from '@fianto/sdk';

usdc.toBaseUnits('12.5'); // '12500000'
usdc.fromBaseUnits('12500000'); // '12.5'
usdc.format('12500000'); // '12.50 USDC'
usdc.format('12500000', { symbol: false }); // '12.50'

toBaseUnits throws a UsdcError for more than 6 decimals, a sign, or anything that is not a number.

Errors and retriesCopy Anchor Link

Every error the SDK throws extends FiantoError. An error response becomes an APIError with status, code, message, field, details, requestId and headers, in one subclass per status:

Next to them: ConnectionError (no response arrived, or the API answered with a redirect, which the SDK never follows), TimeoutError (over timeoutMs), AbortError (your signal aborted) and UsdcError. After a network failure on a POST, ConnectionError and TimeoutError carry the idempotencyKey to retry with.

The SDK retries network errors, timeouts, 408, 429, every 5xx, and a 409 only for idempotency_request_in_progress or checkout_unavailable. It waits for Retry-After, or backs off from 500 ms, doubling up to 8 s, with ±25 % jitter. A Retry-After over 10 seconds is not waited on: the error is thrown at once.

Check errors with isFiantoError(err, ErrorCode.X) or isAPIError(err) rather than instanceof. An app that loads the SDK both as ESM and as CommonJS has two copies of every class, and instanceof a subclass fails across them. See Errors for the codes.

@fianto/sdk/webhooksCopy Anchor Link

Verifies and builds webhook requests without a framework.

The tolerance is 300 seconds by default, from 1 to 3,600, and cannot be switched off. The reasons and the route code per framework are on Verify webhooks. In a test, sign a sample and post it to your own handler:

import { sampleEvent, signWebhook } from '@fianto/sdk/webhooks';

const { body, headers } = await signWebhook({ event: sampleEvent('order.paid'), secret: process.env.FIANTO_WEBHOOK_SECRET! });
await fetch('http://localhost:3000/api/webhooks/fianto', { method: 'POST', headers, body });

@fianto/sdk/handlersCopy Anchor Link

createWebhookHandler(options) and createCheckoutHandler(options) return a function that takes a Request and resolves to a Response. Webhooks() / Checkout() in Next.js and webhooks() / checkout() in Express and Hono are these two handlers, adapted to the framework.

Webhook handler optionsCopy Anchor Link

The handler answers endpoint.verification itself, 200 {"received": true} for a handled event, 400 {"error": "invalid_webhook"} for a failed check, 500 {"error": "handler_failed"} when a callback throws, and 405 for anything but POST.

Checkout handler optionsCopy Anchor Link

The handler accepts only POST (else 405 method_not_allowed), and only a same-origin request: Sec-Fetch-Site: same-origin, or an Origin in allowedOrigins (else 403 forbidden_origin). It answers 200 { id, url }. When the order already has an open session with the same terms, it reissues that session's link; with different terms it answers 409 order_session_mismatch and leaves the open session alone.

Errors reach the browser as { error: { code, message } } only for an allowlist of codes, each with the SDK's own message: payment_in_progress, order_already_paid, checkout_unavailable, rate_limited, session_not_reissuable, subscription_preparing, plan_limit_reached, order_session_mismatch, and the validation codes for your own params (validation_failed, url_insecure, amount_or_price_required, amount_out_of_range, amount_not_allowed, expires_at_out_of_range, mode_not_supported, price_id_required, price_not_found, price_archived, product_archived, price_not_recurring, price_type_mismatch). Everything else, including a 401 or 403 from Fianto and every 5xx, answers 500 internal_error.

See alsoCopy Anchor Link