Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import { createHash } from "node:crypto";
import { z } from "zod";
import { RAMP_SCOPES } from "../scopes";
import type { RampCredentials } from "./models";
import {
RampBillSchema,
RampCashbackSchema,
RampReimbursementSchema,
RampRepaymentSchema,
RampTransactionSchema,
RampTransferSchema,
RampVendorSchema
} from "./models";
export const RAMP_HOST = "https://api.ramp.com";
// The canonical scope lists live in the browser-safe `../scopes` module so the
// client-bundled `config.tsx` can share them without importing this file (which
// pulls `node:crypto`). Re-exported here to preserve the public contract.
export { RAMP_OAUTH_SCOPES, RAMP_SCOPES } from "../scopes";
/** Re-mint a client-credentials token when fewer than this many ms remain. */
const TOKEN_REFRESH_MARGIN_MS = 60_000;
/** Ramp's cursor-pagination page-size cap. */
const RAMP_PAGE_SIZE = 100;
// /********************************************************\
// * Errors *
// \********************************************************/
/** Non-2xx Ramp response (parsed from the `error_v2` envelope). */
export class RampApiError extends Error {
public readonly status: number;
public readonly code?: string;
constructor(status: number, code: string | undefined, message: string) {
super(`Ramp API error ${status}${code ? ` (${code})` : ""}: ${message}`);
this.name = "RampApiError";
this.status = status;
this.code = code;
}
}
/** A 429 from Ramp — carries the parsed `Retry-After` (seconds). */
export class RampRateLimitError extends Error {
public readonly retryAfterSeconds: number;
constructor(retryAfterSeconds: number) {
super(`Ramp rate limit exceeded — retry after ${retryAfterSeconds}s`);
this.name = "RampRateLimitError";
this.retryAfterSeconds = retryAfterSeconds;
}
}
type SearchParamsInit =
| URLSearchParams
| Record<string, string | number | boolean | undefined>;
type RequestOptions = {
body?: unknown;
searchParams?: SearchParamsInit;
idempotencyKey?: string;
};
function toSearchParams(init?: SearchParamsInit): URLSearchParams {
if (!init) return new URLSearchParams();
if (init instanceof URLSearchParams) return new URLSearchParams(init);
const params = new URLSearchParams();
for (const [key, value] of Object.entries(init)) {
if (value === undefined) continue;
params.set(key, String(value));
}
return params;
}
// /********************************************************\
// * RampClient *
// \********************************************************/
/**
* Server-only wiring for the OAuth2 (authorization-code) path. `oauthApp` is
* Carbon's single registered Ramp OAuth application (client id/secret from env,
* NOT the customer's) — required to exchange a code and to refresh. Refresh
* tokens are NOT rotated by Ramp (a refresh returns a new access token only), so
* `onTokensRefreshed` persists just the new access token + expiry; the refresh
* token is unchanged.
*/
export type RampClientOptions = {
oauthApp?: { clientId: string; clientSecret: string };
onTokensRefreshed?: (tokens: {
accessToken: string;
expiresAt: string;
}) => void | Promise<void>;
};
export class RampClient {
private readonly host: string;
private accessToken?: string;
/** Epoch ms at which the cached token expires. */
private tokenExpiresAt?: number;
/** Live oauth2 token state (mutated on refresh). */
private oauthAccessToken?: string;
private oauthExpiresAt?: number;
constructor(
private readonly credentials: RampCredentials,
private readonly options: RampClientOptions = {}
) {
this.host = RAMP_HOST;
if (credentials.type === "oauth2") {
this.oauthAccessToken = credentials.accessToken;
this.oauthExpiresAt = credentials.expiresAt
? Date.parse(credentials.expiresAt)
: undefined;
}
}
/**
* Exchange an OAuth authorization code for tokens (the Connect-flow callback).
* Uses Carbon's OAuth app credentials with HTTP Basic auth.
*/
async exchangeAuthorizationCode(
code: string,
redirectUri: string
): Promise<{
accessToken: string;
refreshToken?: string;
expiresAt?: string;
/** Present only when the server narrowed the grant (RFC 6749 §3.3). */
scope?: string;
}> {
const data = await this.oauthTokenRequest({
grant_type: "authorization_code",
code,
redirect_uri: redirectUri
});
return {
accessToken: data.access_token,
refreshToken: data.refresh_token,
expiresAt: data.expires_in
? new Date(Date.now() + data.expires_in * 1000).toISOString()
: undefined,
scope: data.scope
};
}
/** POST /token with Carbon's OAuth app credentials (Basic auth). */
private async oauthTokenRequest(body: Record<string, string>): Promise<{
access_token: string;
refresh_token?: string;
expires_in?: number;
scope?: string;
}> {
const app = this.options.oauthApp;
if (!app?.clientId || !app?.clientSecret) {
throw new Error(
"Ramp OAuth app credentials are not configured (RAMP_CLIENT_ID / RAMP_CLIENT_SECRET)"
);
}
const basic = Buffer.from(`${app.clientId}:${app.clientSecret}`).toString(
"base64"
);
const response = await fetch(`${this.host}/developer/v1/token`, {
method: "POST",
headers: {
Authorization: `Basic ${basic}`,
"Content-Type": "application/x-www-form-urlencoded",
Accept: "application/json"
},
body: new URLSearchParams(body)
});
if (response.status === 429) {
throw new RampRateLimitError(parseRetryAfter(response));
}
if (!response.ok) {
await throwRampApiError(response);
}
return (await response.json()) as {
access_token: string;
refresh_token?: string;
expires_in?: number;
scope?: string;
};
}
/**
* Return a valid bearer token. client_credentials mints/caches (re-minting
* under the refresh margin). oauth2 returns the stored access token, and when
* it is within the refresh margin runs the `refresh_token` grant, persisting
* the new access token via `onTokensRefreshed`.
*/
private async getAccessToken(): Promise<string> {
if (this.credentials.type === "oauth2") {
const now = Date.now();
if (
this.oauthAccessToken &&
(this.oauthExpiresAt === undefined ||
this.oauthExpiresAt - now > TOKEN_REFRESH_MARGIN_MS)
) {
return this.oauthAccessToken;
}
const { refreshToken } = this.credentials;
if (!refreshToken) {
throw new Error(
"Ramp OAuth access token expired and no refresh token is available — reconnect Ramp"
);
}
const data = await this.oauthTokenRequest({
grant_type: "refresh_token",
refresh_token: refreshToken
});
this.oauthAccessToken = data.access_token;
this.oauthExpiresAt = now + (data.expires_in ?? 0) * 1000;
// Ramp does not rotate refresh tokens — persist the new access token +
// expiry only; the stored refresh token stays valid.
await this.options.onTokensRefreshed?.({
accessToken: this.oauthAccessToken,
expiresAt: new Date(this.oauthExpiresAt).toISOString()
});
return this.oauthAccessToken;
}
const now = Date.now();
if (
this.accessToken &&
this.tokenExpiresAt &&
this.tokenExpiresAt - now > TOKEN_REFRESH_MARGIN_MS
) {
return this.accessToken;
}
const { clientId, clientSecret } = this.credentials;
const basic = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
const response = await fetch(`${this.host}/developer/v1/token`, {
method: "POST",
headers: {
Authorization: `Basic ${basic}`,
"Content-Type": "application/x-www-form-urlencoded",
Accept: "application/json"
},
body: new URLSearchParams({
grant_type: "client_credentials",
scope: RAMP_SCOPES.join(" ")
})
});
if (response.status === 429) {
throw new RampRateLimitError(parseRetryAfter(response));
}
if (!response.ok) {
await throwRampApiError(response);
}
const data = (await response.json()) as {
access_token: string;
expires_in?: number;
};
this.accessToken = data.access_token;
this.tokenExpiresAt = now + (data.expires_in ?? 0) * 1000;
return this.accessToken;
}
/**
* Authenticated JSON request. Throws `RampRateLimitError` on 429 (carrying
* `Retry-After`) and `RampApiError(status, code, message)` on any other
* non-2xx (parsed from `error_v2`). There are no in-client retries — retries
* live at the job layer.
*/
async request<T>(
method: string,
path: string,
opts: RequestOptions = {}
): Promise<T> {
const token = await this.getAccessToken();
const search = toSearchParams(opts.searchParams);
const query = search.toString();
const url = `${this.host}${path}${query ? `?${query}` : ""}`;
const headers: Record<string, string> = {
Authorization: `Bearer ${token}`,
Accept: "application/json"
};
if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
const init: RequestInit = { method, headers };
if (opts.body !== undefined) {
headers["Content-Type"] = "application/json";
init.body = JSON.stringify(opts.body);
}
const response = await fetch(url, init);
if (response.status === 429) {
throw new RampRateLimitError(parseRetryAfter(response));
}
if (!response.ok) {
await throwRampApiError(response);
}
if (response.status === 204) return undefined as T;
const text = await response.text();
if (!text) return undefined as T;
return JSON.parse(text) as T;
}
/**
* Drain a cursor-paginated Ramp list endpoint, following `page.next` until
* null and parsing each row with `schema`. `page_size=100` on the first page;
* subsequent pages reuse the query the `page.next` URL carries.
*/
async *listPaginated<TSchema extends z.ZodTypeAny>(
path: string,
params: SearchParamsInit | undefined,
schema: TSchema
): AsyncGenerator<Array<z.infer<TSchema>>> {
let search = toSearchParams(params);
if (!search.has("page_size")) {
search.set("page_size", String(RAMP_PAGE_SIZE));
}
while (true) {
const page = await this.request<{
data?: unknown[];
page?: { next?: string | null };
}>("GET", path, { searchParams: search });
// Parse PER ROW: one malformed row (a missing `id`, a non-integer minor
// amount) must not throw and abort the whole page — which would also skip
// every later page. Skip + log the reject and make progress on the rest.
const rows: Array<z.infer<TSchema>> = [];
for (const row of page.data ?? []) {
const parsed = schema.safeParse(row);
if (parsed.success) {
rows.push(parsed.data as z.infer<TSchema>);
} else {
const rowId =
row && typeof row === "object" && "id" in row
? (row as { id?: unknown }).id
: undefined;
console.warn(
`Ramp listPaginated: skipping malformed row from ${path}` +
(rowId !== undefined ? ` (id=${String(rowId)})` : ""),
parsed.error.issues
);
}
}
yield rows;
const next = page.page?.next;
if (!next) break;
search = new URLSearchParams(new URL(next).search);
}
}
// =================================================================
// Inbound listings (cursor-paginated)
// =================================================================
listTransactions(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/transactions",
params,
RampTransactionSchema
);
}
listBills(params?: SearchParamsInit) {
return this.listPaginated("/developer/v1/bills", params, RampBillSchema);
}
listTransfers(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/transfers",
params,
RampTransferSchema
);
}
listCashbacks(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/cashbacks",
params,
RampCashbackSchema
);
}
listReimbursements(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/reimbursements",
params,
RampReimbursementSchema
);
}
listRepayments(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/repayments",
params,
RampRepaymentSchema
);
}
listVendors(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/vendors",
params,
RampVendorSchema
);
}
// =================================================================
// Single reads / writes (thin, typed)
// =================================================================
getReceipt<T = unknown>(id: string): Promise<T> {
return this.request<T>("GET", `/developer/v1/receipts/${id}`);
}
getBusiness<T = unknown>(): Promise<T> {
return this.request<T>("GET", "/developer/v1/business");
}
// ---- Accounting connection ----
createAccountingConnection<T = unknown>(
body: unknown,
idempotencyKey?: string
): Promise<T> {
return this.request<T>("POST", "/developer/v1/accounting/connection", {
body,
idempotencyKey
});
}
// Path CONFIRMED live 2026-09-25 (provider-mode token): the healthcheck calls
// this and the integration reads HEALTHY, which requires a linked connection
// back. Whether a token WITHOUT `accounting:write` may call it is still open.
getAccountingConnections<T = unknown>(): Promise<T> {
return this.request<T>("GET", "/developer/v1/accounting/all-connections");
}
deleteAccountingConnection<T = unknown>(): Promise<T> {
return this.request<T>("DELETE", "/developer/v1/accounting/connection");
}
// ---- Accounting master data push ----
// TODO(task-1): confirm the accounts body key (`gl_accounts`) + path.
postAccountingAccounts<T = unknown>(batch: unknown): Promise<T> {
return this.request<T>("POST", "/developer/v1/accounting/accounts", {
body: batch
});
}
/**
* List the GL accounts already uploaded to Ramp (paginated). Each row carries
* `id` (the Carbon `account.id` we pushed, echoed back) and `ramp_id` (Ramp's
* internal UUID). The PATCH endpoint keys on `ramp_id`, so callers resolve it
* here before updating.
*/
listAccountingAccounts() {
return this.listPaginated(
"/developer/v1/accounting/accounts",
undefined,
z
.object({
id: z.string().nullish(),
ramp_id: z.string().nullish()
})
.passthrough()
);
}
patchAccountingAccount<T = unknown>(id: string, body: unknown): Promise<T> {
return this.request<T>("PATCH", `/developer/v1/accounting/accounts/${id}`, {
body
});
}
postAccountingFields<T = unknown>(body: unknown): Promise<T> {
return this.request<T>("POST", "/developer/v1/accounting/fields", { body });
}
postAccountingFieldOptions<T = unknown>(body: unknown): Promise<T> {
return this.request<T>("POST", "/developer/v1/accounting/field-options", {
body
});
}
patchAccountingFieldOption<T = unknown>(
id: string,
body: unknown
): Promise<T> {
return this.request<T>(
"PATCH",
`/developer/v1/accounting/field-options/${id}`,
{ body }
);
}
/**
* List the custom accounting fields uploaded to Ramp (paginated; filter with
* `remote_id`). `id` is the remote id Carbon created the field with;
* `ramp_id` is Ramp's UUID, which the field-options endpoints key on.
*/
listAccountingFields(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/accounting/fields",
params,
z
.object({
id: z.string().nullish(),
ramp_id: z.string().nullish(),
name: z.string().nullish(),
display_name: z.string().nullish(),
is_active: z.boolean().nullish()
})
.passthrough()
);
}
/**
* List a custom field's options (paginated; filter with `field_remote_id` or
* `field_id`). `id` is the Carbon id pushed as the option; `ramp_id` is what
* `PATCH /field-options/{id}` keys on.
*/
listAccountingFieldOptions(params?: SearchParamsInit) {
return this.listPaginated(
"/developer/v1/accounting/field-options",
params,
z
.object({
id: z.string().nullish(),
ramp_id: z.string().nullish(),
value: z.string().nullish(),
display_name: z.string().nullish(),
is_active: z.boolean().nullish(),
visibility: z.string().nullish()
})
.passthrough()
);
}
patchAccountingField<T = unknown>(id: string, body: unknown): Promise<T> {
return this.request<T>("PATCH", `/developer/v1/accounting/fields/${id}`, {
body
});
}
// ---- Sync confirmation ----
postAccountingSyncs<T = unknown>(body: unknown): Promise<T> {
return this.request<T>("POST", "/developer/v1/accounting/syncs", { body });
}
// ---- Vendors (spend vendors — the id a PO/bill `vendor_id` references) ----
/**
* Create a Ramp SPEND vendor (`POST /developer/v1/vendors`). This is the
* vendor a purchase order / bill `vendor_id` points at — NOT the accounting
* vendor (`/accounting/vendors`, for coding), whose id a PO/bill rejects.
* Requires `country` + `business_vendor_contacts: [{ email }]`.
*/
createSpendVendor<T = unknown>(
body: unknown,
idempotencyKey?: string
): Promise<T> {
return this.request<T>("POST", "/developer/v1/vendors", {
body,
idempotencyKey
});
}
/**
* Update a Ramp SPEND vendor (`PATCH /developer/v1/vendors/{id}`). Carbon uses
* it for one field: `accounting_vendor_remote_id`, the link to the accounting
* vendor the seat-holder published — Ramp's documented way to join a bill-pay
* vendor to its GL vendor ("Creating a bill-pay vendor does not auto-create an
* accounting vendor. Link them explicitly via PATCH /vendors/{id}").
*/
updateSpendVendor<T = unknown>(id: string, body: unknown): Promise<T> {
return this.request<T>("PATCH", `/developer/v1/vendors/${id}`, { body });
}
// ---- Business entities (for the required PO `entity_id`) ----
getEntities<T = unknown>(): Promise<T> {
return this.request<T>("GET", "/developer/v1/entities");
}
// ---- Purchase orders ----
createPurchaseOrder<T = unknown>(
body: unknown,
idempotencyKey?: string
): Promise<T> {
return this.request<T>("POST", "/developer/v1/purchase-orders", {
body,
idempotencyKey
});
}
/**
* Find the Ramp purchase order Carbon created for a local one, by the
* `external_id` it stamped at creation.
*
* `external_id` is the identity; `purchase_order_number` is NOT — Ramp
* normalizes it (`"PO000002"` is stored as `"2"`, verified live 2026-09-26) and
* appends a dedup suffix to others, so it can never be used to recognise
* Carbon's own row.
*
* The filter is real: an unsupported query parameter is IGNORED by this
* endpoint and returns the full first page, whereas a miss on `external_id`
* returns zero rows — which is how it was confirmed.
*/
async findPurchaseOrderByExternalId(
externalId: string
): Promise<{ id: string } | null> {
const response = (await this.request<{
data?: Array<{ id?: string; external_id?: string | null }>;
}>(
"GET",
`/developer/v1/purchase-orders?external_id=${encodeURIComponent(externalId)}`
)) ?? { data: [] };
// Re-check the value rather than trusting the filter: if a future API version
// stopped honouring it, an unfiltered page would otherwise hand back an
// unrelated purchase order to adopt.
const match = (response.data ?? []).find(
(row) => row.external_id === externalId && row.id
);
return match?.id ? { id: match.id } : null;
}
patchPurchaseOrder<T = unknown>(id: string, body: unknown): Promise<T> {
return this.request<T>("PATCH", `/developer/v1/purchase-orders/${id}`, {
body
});
}
/**
* Archive a Ramp purchase order.
*
* The empty object is REQUIRED, not decoration: Ramp answers a bodyless POST
* with `400 DEVELOPER_7011 "The request does not contain a JSON body"`
* (observed live 2026-09-25 against the sandbox). This call had no body until
* then — the archive path was unreachable from the old cursor sweep, so the
* failure had never surfaced.
*/
archivePurchaseOrder<T = unknown>(id: string): Promise<T> {
return this.request<T>(
"POST",
`/developer/v1/purchase-orders/${id}/archive`,
{ body: {} }
);
}
// ---- Bills (draft push) ----
createDraftBill<T = unknown>(
body: unknown,
idempotencyKey?: string
): Promise<T> {
return this.request<T>("POST", "/developer/v1/bills/drafts", {
body,
idempotencyKey
});
}
// ---- Webhooks ----
createWebhook<T = unknown>(
body: unknown,
idempotencyKey?: string
): Promise<T> {
return this.request<T>("POST", "/developer/v1/webhooks", {
body,
idempotencyKey
});
}
deleteWebhook<T = unknown>(id: string): Promise<T> {
return this.request<T>("DELETE", `/developer/v1/webhooks/${id}`);
}
// TODO(task-1): confirm the webhook challenge-verify path/shape.
verifyWebhook<T = unknown>(id: string, challenge: string): Promise<T> {
return this.request<T>("POST", `/developer/v1/webhooks/${id}/verify`, {
body: { challenge }
});
}
}
// /********************************************************\
// * Helpers *
// \********************************************************/
function parseRetryAfter(response: Response): number {
const header = response.headers.get("Retry-After");
const seconds = header ? Number.parseInt(header, 10) : NaN;
return Number.isFinite(seconds) && seconds > 0 ? seconds : 60;
}
async function throwRampApiError(response: Response): Promise<never> {
let code: string | undefined;
let message = response.statusText;
try {
const text = await response.text();
if (text) {
const parsed = JSON.parse(text) as {
error_v2?: { message?: string; error_code?: string; code?: string };
message?: string;
};
const errorV2 = parsed.error_v2;
if (errorV2) {
code = errorV2.error_code ?? errorV2.code;
message = errorV2.message ?? message;
} else if (parsed.message) {
message = parsed.message;
}
}
} catch {
// Non-JSON body — keep the status text.
}
throw new RampApiError(response.status, code, message);
}
/**
* Deterministic idempotency key for a Ramp write: sha256 of
* `companyId:operation:scope`. `scope` identifies the logical unit (e.g. a
* hash of the sorted ids being confirmed) so a retried confirm cannot
* double-apply. Clone of `buildRilletIdempotencyKey`.
*/
export function buildRampIdempotencyKey(args: {
companyId: string;
operation: string;
scope: string;
}): string {
return createHash("sha256")
.update(`${args.companyId}:${args.operation}:${args.scope}`)
.digest("hex");
}