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 { round } from "@carbon/utils";
import { z } from "zod";
/**
* Zod schemas for the Ramp Developer API v1 objects Carbon consumes.
*
* Every schema is `.passthrough()` on purpose: Ramp evolves its payloads
* additively and Carbon parses-never-trusts — we validate only the fields we
* read and carry the rest through untouched. Field names follow the research
* file (§Answers Q1); anything not yet confirmed against a live sandbox is
* marked `TODO(task-1)`.
*/
// /********************************************************\
// * Monetary values *
// \********************************************************/
/**
* Ramp `CurrencyAmount` — an integer number of the currency's MINOR units
* (cents for USD, whole yen for JPY) plus the ISO currency code.
*/
export const RampCurrencyAmountSchema = z
.object({
amount: z.number().int(),
currency_code: z.string()
})
.passthrough();
export type RampCurrencyAmount = z.infer<typeof RampCurrencyAmountSchema>;
/**
* Convert a minor-unit integer amount to a major-unit decimal number, rounded
* at the currency's own decimal places. `decimals` is the authoritative
* `currency.decimalPlaces` value passed in by the caller — NEVER a literal, and
* the division goes through the shared precision `round()` (never a bare `/` at
* a call site). `fromMinorUnits(4000, "USD", 2) === 40`,
* `fromMinorUnits(63, "JPY", 0) === 63`.
*/
export function fromMinorUnits(
amount: number,
_currencyCode: string,
decimals: number
): number {
return round(amount / 10 ** decimals, decimals);
}
// /********************************************************\
// * Coding (accounting fields) *
// \********************************************************/
/**
* A coding selection on a transaction / line / bill — the customer's choice of
* a Carbon account, cost center, etc. `external_id` is the Carbon-side id we
* pushed (account.id, costCenter.id); `type` distinguishes GL_ACCOUNT from
* COST_CENTER and the rest.
*/
export const RampAccountingCategoryInfoSchema = z
.object({
external_id: z.string().nullish(),
id: z.string().nullish(),
name: z.string().nullish(),
// The accounting-field TYPE lives HERE per the Ramp OpenAPI spec
// (`ApiTransactionAccountingCategoryInfo.type`: GL_ACCOUNT / COST_CENTER /
// …), NOT on the selection itself. Verified against
// docs.ramp.com/openapi/developer-api.json (2026-08-28).
type: z.string().optional()
})
.passthrough();
export const RampAccountingFieldSelectionSchema = z
.object({
id: z.string().optional(),
// `external_id` is the Carbon-side id we pushed as the field OPTION
// (account.id / costCenter.id) — this part matches the spec.
external_id: z.string().nullish(),
// Legacy/top-level `type` — kept for resilience but the spec puts the type
// under `category_info.type` (see schema above). `codeSelections` reads
// `category_info.type` first, then falls back here.
type: z.string().optional(),
name: z.string().nullish(),
category_info: RampAccountingCategoryInfoSchema.optional()
})
.passthrough();
export type RampAccountingFieldSelection = z.infer<
typeof RampAccountingFieldSelectionSchema
>;
export const RampLineItemSchema = z
.object({
// TODO(task-1): confirm line_item amount is a CurrencyAmount (minor units)
// vs a bare decimal number.
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional(),
memo: z.string().nullish(),
accounting_field_selections: z
.array(RampAccountingFieldSelectionSchema)
.optional()
})
.passthrough();
export type RampLineItem = z.infer<typeof RampLineItemSchema>;
// /********************************************************\
// * Transactions *
// \********************************************************/
export const RampCardHolderSchema = z
.object({
first_name: z.string().nullish(),
last_name: z.string().nullish()
})
.passthrough();
/**
* `ApiSignedAmount` (Ramp OpenAPI): `{ currency, value }` where `value` is a
* SIGNED integer in the currency's smallest denomination (cents for USD).
* Distinct from `RampCurrencyAmount` (`{ amount, currency_code }`) — the newer
* transaction endpoints return `entity_amount` / `merchant_amount` as this
* shape. Verified against docs.ramp.com/openapi/developer-api.json (2026-08-28).
*/
export const RampSignedAmountSchema = z
.object({
value: z.number().int(),
currency: z.string().optional()
})
.passthrough();
export type RampSignedAmount = z.infer<typeof RampSignedAmountSchema>;
export const RampTransactionSchema = z
.object({
id: z.string(),
state: z.string().optional(),
sync_status: z.string().optional(),
// DEPRECATED per the Ramp spec ("Use `entity_amount`") and it is a bare
// `number` in MAJOR units (dollars), not minor units. Consumers must prefer
// `entity_amount.value` (signed integer cents) below; `amount` is kept only
// as a last-resort fallback. Verified 2026-08-28 against the OpenAPI spec.
amount: z.number().optional(),
// The settlement amount to the entity — signed integer in minor units
// (cents). This is the field ramp-sync should read for charges.
entity_amount: RampSignedAmountSchema.nullish(),
// The amount the merchant originally charged — signed integer minor units.
merchant_amount: RampSignedAmountSchema.nullish(),
currency_code: z.string().optional(),
currency: z.string().optional(),
merchant_name: z.string().nullish(),
merchant_id: z.string().nullish(),
card_holder: RampCardHolderSchema.nullish(),
card_id: z.string().nullish(),
memo: z.string().nullish(),
user_transaction_time: z.string().nullish(),
accounting_date: z.string().nullish(),
settlement_date: z.string().nullish(),
entity_id: z.string().nullish(),
original_transaction_id: z.string().nullish(),
statement_id: z.string().nullish(),
receipts: z.array(z.string()).optional(),
accounting_field_selections: z
.array(RampAccountingFieldSelectionSchema)
.optional(),
line_items: z.array(RampLineItemSchema).optional()
})
.passthrough();
export type RampTransaction = z.infer<typeof RampTransactionSchema>;
// /********************************************************\
// * Bills & payments *
// \********************************************************/
export const RampBillPaymentSchema = z
.object({
id: z.string().optional(),
status: z.string().optional(),
payment_method: z.string().nullish(),
effective_date: z.string().nullish(),
payment_date: z.string().nullish(),
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional()
})
.passthrough();
export type RampBillPayment = z.infer<typeof RampBillPaymentSchema>;
export const RampBillSchema = z
.object({
id: z.string(),
status: z.string().optional(),
approval_status: z.string().optional(),
sync_status: z.string().optional(),
remote_id: z.string().nullish(),
invoice_number: z.string().nullish(),
deep_link_url: z.string().nullish(),
issued_at: z.string().nullish(),
due_at: z.string().nullish(),
currency_code: z.string().optional(),
entity_id: z.string().nullish(),
purchase_order_ids: z.array(z.string()).optional(),
invoice_urls: z.array(z.string()).optional(),
payment: RampBillPaymentSchema.nullish(),
vendor: z.unknown().optional(),
line_items: z.array(RampLineItemSchema).optional()
})
.passthrough();
export type RampBill = z.infer<typeof RampBillSchema>;
// /********************************************************\
// * Transfers / cashbacks / repayments *
// \********************************************************/
export const RampTransferSchema = z
.object({
id: z.string(),
status: z.string().optional(),
sync_status: z.string().optional(),
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional(),
currency_code: z.string().optional(),
bank_account_id: z.string().nullish(),
statement_id: z.string().nullish(),
entity_id: z.string().nullish(),
created_at: z.string().nullish()
})
.passthrough();
export type RampTransfer = z.infer<typeof RampTransferSchema>;
export const RampCashbackSchema = z
.object({
id: z.string(),
sync_status: z.string().optional(),
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional(),
currency_code: z.string().optional(),
statement_id: z.string().nullish(),
entity_id: z.string().nullish(),
created_at: z.string().nullish()
})
.passthrough();
export type RampCashback = z.infer<typeof RampCashbackSchema>;
export const RampReimbursementSchema = z
.object({
id: z.string(),
state: z.string().optional(),
sync_status: z.string().optional(),
// DEPRECATED exactly as on a transaction: a live reimbursement sends a bare
// number in MAJOR units (dollars) here while the real amount sits in the
// verified minor-unit objects below. Readers must prefer those.
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional(),
// The settlement amount in the ENTITY's currency — signed integer minor
// units. This is the field the reimbursement header should read, matching
// the charge path's use of `entity_amount`.
entity_amount: RampSignedAmountSchema.nullish(),
// What the employee is actually paid, and what they originally submitted —
// integer minor units. Fallbacks when the entity amount is absent.
payee_amount: RampCurrencyAmountSchema.nullish(),
original_reimbursement_amount: RampCurrencyAmountSchema.nullish(),
currency_code: z.string().optional(),
currency: z.string().optional(),
transaction_date: z.string().nullish(),
approved_at: z.string().nullish(),
entity_id: z.string().nullish(),
user_id: z.string().nullish(),
// Ramp puts the employee's identity at the TOP LEVEL of a reimbursement
// (`user_email` / `user_full_name`); `user` is null on every record we have
// seen. Declared explicitly because the employee match keys on the email —
// `.passthrough()` keeps undeclared fields at runtime but hides them from
// the type, which is how the reader came to look only at `user.email`.
user_email: z.string().nullish(),
user_full_name: z.string().nullish(),
user: z.unknown().optional(),
line_items: z.array(RampLineItemSchema).optional()
})
.passthrough();
export type RampReimbursement = z.infer<typeof RampReimbursementSchema>;
export const RampRepaymentSchema = z
.object({
id: z.string(),
status: z.string().optional(),
repaid_at: z.string().nullish(),
original_transaction_id: z.string().nullish(),
funding_method: z.string().nullish(),
// TODO(task-1): confirm the repayment amount field name/shape.
repayment_amount: z
.union([RampCurrencyAmountSchema, z.number()])
.optional(),
amount: z.union([RampCurrencyAmountSchema, z.number()]).optional(),
currency_code: z.string().optional(),
entity_id: z.string().nullish()
})
.passthrough();
export type RampRepayment = z.infer<typeof RampRepaymentSchema>;
// /********************************************************\
// * Vendors / POs / entities *
// \********************************************************/
export const RampVendorSchema = z
.object({
id: z.string(),
name: z.string().nullish(),
accounting_vendor_remote_id: z.string().nullish(),
entity_id: z.string().nullish()
})
.passthrough();
export type RampVendor = z.infer<typeof RampVendorSchema>;
export const RampPurchaseOrderSchema = z
.object({
id: z.string(),
remote_id: z.string().nullish(),
creation_source: z.string().optional(),
billing_status: z.string().optional(),
receipt_status: z.string().optional(),
entity_id: z.string().nullish(),
line_items: z.array(z.unknown()).optional()
})
.passthrough();
export type RampPurchaseOrder = z.infer<typeof RampPurchaseOrderSchema>;
export const RampEntitySchema = z
.object({
id: z.string(),
entity_name: z.string().nullish(),
name: z.string().nullish()
})
.passthrough();
export type RampEntity = z.infer<typeof RampEntitySchema>;
export const RampAccountingConnectionSchema = z
.object({
id: z.string().optional(),
connection_id: z.string().optional(),
remote_provider_name: z.string().nullish(),
status: z.string().optional()
})
.passthrough();
export type RampAccountingConnection = z.infer<
typeof RampAccountingConnectionSchema
>;
// /********************************************************\
// * Webhooks / sync results *
// \********************************************************/
export const RampWebhookEventSchema = z
.object({
id: z.string(),
type: z.string(),
created_at: z.string().optional(),
business_id: z.string().optional(),
object: z.unknown().optional()
})
.passthrough();
export type RampWebhookEvent = z.infer<typeof RampWebhookEventSchema>;
export const RampSyncResultSchema = z
.object({
id: z.string().optional(),
sync_type: z.string().optional(),
// Ramp echoes back the per-object success/failure of a POST /accounting/syncs.
successful_syncs: z.array(z.unknown()).optional(),
failed_syncs: z.array(z.unknown()).optional()
})
.passthrough();
export type RampSyncResult = z.infer<typeof RampSyncResultSchema>;
// /********************************************************\
// * Credentials *
// \********************************************************/
export const RampCredentialsSchema = z.discriminatedUnion("type", [
z
.object({
type: z.literal("client_credentials"),
clientId: z.string(),
clientSecret: z.string()
})
.passthrough(),
z
.object({
type: z.literal("oauth2"),
accessToken: z.string(),
refreshToken: z.string().optional(),
expiresAt: z.string().optional()
})
.passthrough()
]);
export type RampCredentials = z.infer<typeof RampCredentialsSchema>;
// /********************************************************\
// * Integration metadata *
// \********************************************************/
export const RampSyncFlagsSchema = z
.object({
pullTransactions: z.boolean().default(true),
pullBills: z.boolean().default(true),
pullReimbursements: z.boolean().default(true),
pushPurchaseOrders: z.boolean().default(true),
pushInvoices: z.boolean().default(true)
})
.prefault({});
export type RampSyncFlags = z.infer<typeof RampSyncFlagsSchema>;
export const RampCursorsSchema = z
.object({
// Inbound only. The outbound push cursors
// (`purchaseOrderPushUpdatedAt` / `invoicePushUpdatedAt`) were dropped when
// purchase orders and bills moved onto the event engine — the ledger is the
// idempotency now, not a keyset. Values stored by earlier installs are
// simply ignored; no migration strips them.
repaymentsRepaidAt: z.string().optional()
})
.optional();
export type RampCursors = z.infer<typeof RampCursorsSchema>;
/**
* The settings form persists the five sync toggles as FLAT string flags at the
* metadata root (`pullTransactions: "true" | "false"`, …), but the runtime reads
* them as the nested boolean `sync` object above. This is the single place that
* bridges the two: an explicit `"false"`/`false` disables a family; anything else
* — including an absent flag on a fresh OAuth install — leaves it ON, matching
* the schema default. Applied on every read, so all runtime `metadata.sync.*`
* gates stay correct without the form and the sync engine agreeing on a shape.
*/
function flatSyncFlagEnabled(
raw: Record<string, unknown>,
key: string
): boolean {
const value = raw[key];
return value !== "false" && value !== false;
}
export const RampIntegrationMetadataSchema = z
.object({
credentials: RampCredentialsSchema,
cardLiabilityAccountId: z.string().optional(),
statementBankAccountId: z.string().optional(),
cashbackIncomeAccountId: z.string().optional(),
reimbursementBankAccountId: z.string().optional(),
entityId: z.string().optional(),
/**
* The install mode, stamped from the signed OAuth state at connect time.
* ABSENT on every install that predates modes, which resolves to
* `"provider"` — today's behaviour — via `resolveRampMode`.
*/
syncMode: z.enum(["provider", "push-only"]).optional(),
/**
* The scopes the token response ACTUALLY returned, not the set requested.
* RFC 6749 §3.3 permits an authorization server to issue narrower scope than
* asked for, and it must then say so in `scope`.
*/
grantedScopes: z.array(z.string()).optional(),
/**
* Which system holds Ramp's accounting connection (its
* `remote_provider_name`). In push-only this should NOT be Carbon; the
* healthcheck reports the mismatch rather than failing the connect, because
* the customer may connect the other provider afterwards.
*/
accountingConnectionProvider: z.string().optional(),
connectionId: z.string().optional(),
webhookId: z.string().optional(),
webhookSecret: z.string().optional(),
cursors: RampCursorsSchema,
sync: RampSyncFlagsSchema
})
.passthrough()
.transform((m) => {
const raw = m as Record<string, unknown>;
return {
...m,
sync: {
pullTransactions: flatSyncFlagEnabled(raw, "pullTransactions"),
pullBills: flatSyncFlagEnabled(raw, "pullBills"),
pullReimbursements: flatSyncFlagEnabled(raw, "pullReimbursements"),
pushPurchaseOrders: flatSyncFlagEnabled(raw, "pushPurchaseOrders"),
pushInvoices: flatSyncFlagEnabled(raw, "pushInvoices")
}
};
});
export type RampIntegrationMetadata = z.infer<
typeof RampIntegrationMetadataSchema
>;