Skip to content

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.

23.4 KB
Raw Blame
// 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");
}