@devly-cl/flow-client

Flow wire protocol for Node 24 or newer. Zero runtime npm dependencies; emits CommonJS and TypeScript declarations and supports require and named ESM imports. Published releases are installed from npm; local npm pack only creates a candidate tarball.

Install

npm install @devly-cl/flow-client

import { FlowHttpClient, FlowClientError, type FlowCustomer } from '@devly-cl/flow-client';

const client = new FlowHttpClient({
  environment: 'test',
  getCredentials: () => secretStore.readFlowCredentials(),
  // Optional: transport with the native fetch signature, for interception/testing.
});
client.assertConfigured(); // Validates without network I/O or returning credentials.
const customer = await client.request<FlowCustomer>('GET', '/customer/get', { customerId });

getCredentials supplies { apiKey, secretKey } synchronously and is called for every request. The client never reads environment variables. Credentials stay bound to the chosen test or live host. Signatures use raw sorted UTF-8 values before form encoding. Requests reject redirects, time out after 15 seconds and cap response bodies at 1 MiB. Each call makes exactly one transport attempt; there is no automatic retry or provider idempotency key.

FlowClientError exposes only code, uncertain and optional httpStatus; transport messages, causes and provider rejection bodies are discarded. An uncertain mutation requires reconciliation before retrying. The non-mutating changePlanPreview POST follows read semantics. Successful request<T> results still require caller validation of identity, ownership and financial state: the generic type is a wire description, not a runtime guarantee. Host policy must handle uncertainty raised by validation after a successful POST.

Public exports: FlowHttpClient, FlowClientError, flowObject, flowString, flowInteger, flowClpAmount, flowCalendarDate, flowLocalDateTime; types for environment/options/credentials/transport/error codes and Flow wire DTOs. Calendar parsers preserve dates and wall-clock strings without inferring a timezone. Fetch transport declarations reference TypeScript's standard DOM library; consumers need no Nest, TypeORM or Node type package to resolve this API.

Sales gates, tenant authorization, checkout, callbacks, journals, retries, billing rules and environment-variable selection belong to the application. The integrating application preserves those responsibilities and translates SDK errors into its existing billing contract.

From this repository root, run npm run build:packages, npm run test:packages, npm run test:package-boundaries and npm run test:package-artifacts. The artifact test installs the SDK alone offline outside the repository and signs an intercepted request without framework dependencies or .env. It does not contact Flow. Rebuild packages and restart Nest after changing package sources; automatic package hot reload is not provided.