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 type { ExternalIntegrationMappingService } from "../../accounting/core/external-mapping";
import type { SpendVendorParty } from "../../spend/parties";
import { buildRampIdempotencyKey, type RampClient } from "./client";
import { RAMP } from "./connection";
import type { RampVendor } from "./models";
// /********************************************************\
// * Ramp spend-vendor resolution (outbound) *
// \********************************************************/
/**
* Alias of the shared `SpendVendorParty` — one definition of "the Carbon
* supplier identity a spend platform needs", loaded by `spend/parties.ts`. Kept
* under the Ramp name because it is this module's public contract.
*/
export type RampVendorSupplier = SpendVendorParty;
/**
* Where the Ramp vendor mapping keeps the accounting vendor Carbon last linked
* that Ramp vendor to. Recorded so a linked supplier resolves from the mapping
* alone, with no Ramp call, on every push after the first.
*/
const LINKED_ACCOUNTING_VENDOR_KEY = "accountingVendorRemoteId";
/**
* Everything one push needs to resolve its suppliers' Ramp spend vendors,
* loaded up front so a page of documents costs a fixed number of reads.
*/
export type RampVendorResolution = {
/** supplier id → Ramp spend vendor id, from Carbon's `ramp` vendor mappings. */
vendorIds: Map<string, string>;
/**
* supplier id → the accounting vendor Carbon last linked that Ramp vendor to
* (the mapping's metadata). Compared against `accountingVendorIds` to decide
* whether a mapped vendor still needs linking.
*/
linkedAccountingVendorIds: Map<string, string>;
/**
* supplier id → the SEAT-HOLDER's vendor id for it (e.g. the Rillet vendor
* Carbon pushed). Empty when Carbon holds Ramp's accounting seat — Carbon
* publishes no accounting vendors, so there is nothing to link to.
*/
accountingVendorIds: Map<string, string>;
vendorsById: Map<string, RampVendor>;
vendorsByExternalId: Map<string, RampVendor>;
vendorsByName: Map<string, RampVendor | null>;
vendorsByAccountingVendorId: Map<string, RampVendor>;
vendorLookup: { ok: true } | { ok: false; error: unknown };
};
export type RampPurchaseOrderBatch = RampVendorResolution & {
purchaseOrderIds: Map<string, string>;
};
function indexSpendVendor(
resolution: RampVendorResolution,
vendor: RampVendor
) {
resolution.vendorsById.set(vendor.id, vendor);
if (
typeof vendor.external_vendor_id === "string" &&
!resolution.vendorsByExternalId.has(vendor.external_vendor_id)
) {
resolution.vendorsByExternalId.set(vendor.external_vendor_id, vendor);
}
// Ramp allows an accounting vendor to be linked to ONE Ramp vendor, so this
// key is unique by construction.
if (vendor.accounting_vendor_remote_id) {
resolution.vendorsByAccountingVendorId.set(
vendor.accounting_vendor_remote_id,
vendor
);
}
const name = (vendor.name ?? "").trim().toLowerCase();
if (name)
resolution.vendorsByName.set(
name,
resolution.vendorsByName.has(name) ? null : vendor
);
}
function linkedAccountingVendorId(
metadata: Record<string, unknown> | null | undefined
): string | undefined {
const value = metadata?.[LINKED_ACCOUNTING_VENDOR_KEY];
return typeof value === "string" && value ? value : undefined;
}
type VendorMappingRow = {
entityId: string;
externalId: string | null;
metadata?: Record<string, unknown> | null;
};
/**
* The resolution state from already-loaded rows. Pure —
* `prepareRampVendorResolution` is this plus the reads.
*/
export function buildRampVendorResolution(args: {
/** Carbon's `ramp` vendor mappings. */
vendorMappings: VendorMappingRow[];
/** The seat-holder's vendor mappings; empty when Carbon holds the seat. */
accountingVendorMappings?: VendorMappingRow[];
/** The Ramp vendor snapshot, when one was read. */
vendors?: RampVendor[];
}): RampVendorResolution {
const resolution: RampVendorResolution = {
vendorIds: new Map(
args.vendorMappings.flatMap((row) =>
row.externalId ? [[row.entityId, row.externalId] as const] : []
)
),
linkedAccountingVendorIds: new Map(
args.vendorMappings.flatMap((row) => {
const linked = linkedAccountingVendorId(row.metadata);
return linked ? [[row.entityId, linked] as const] : [];
})
),
accountingVendorIds: new Map(
(args.accountingVendorMappings ?? []).flatMap((row) =>
row.externalId ? [[row.entityId, row.externalId] as const] : []
)
),
vendorsById: new Map(),
vendorsByExternalId: new Map(),
vendorsByName: new Map(),
vendorsByAccountingVendorId: new Map(),
vendorLookup: { ok: true }
};
for (const vendor of args.vendors ?? []) indexSpendVendor(resolution, vendor);
return resolution;
}
/**
* One mapping read per integration and, only when some supplier still needs
* resolving or linking, one paginated Ramp vendor snapshot.
*
* `accountingIntegration` is the integration that holds Ramp's accounting seat
* when it is not Carbon (`RampProvider.codingIdentityIntegrationId`). Its
* vendor mappings name the accounting vendor each supplier's Ramp vendor must
* be linked to.
*/
export async function prepareRampVendorResolution(
mapping: ExternalIntegrationMappingService,
client: RampClient,
suppliers: RampVendorSupplier[],
options: { accountingIntegration?: string } = {}
): Promise<RampVendorResolution> {
const uniqueSuppliers = [
...new Map(suppliers.map((supplier) => [supplier.id, supplier])).values()
];
const supplierIds = uniqueSuppliers.map((supplier) => supplier.id);
const [vendorMappings, accountingVendorMappings] = await Promise.all([
mapping.getByEntities("vendor", supplierIds, RAMP),
options.accountingIntegration
? mapping.getByEntities(
"vendor",
supplierIds,
options.accountingIntegration
)
: Promise.resolve(new Map())
]);
const resolution = buildRampVendorResolution({
vendorMappings: [...vendorMappings.values()],
accountingVendorMappings: [...accountingVendorMappings.values()]
});
if (uniqueSuppliers.some((supplier) => needsLookup(resolution, supplier))) {
try {
for await (const page of client.listVendors()) {
for (const vendor of page) indexSpendVendor(resolution, vendor);
}
} catch (error) {
// Mapped vendors and archive-only orders can still proceed. Only a
// supplier needing this provider lookup inherits the error.
resolution.vendorLookup = { ok: false, error };
}
}
return resolution;
}
/** One mapping read per entity kind and one paginated provider snapshot per PO page. */
export async function prepareRampPurchaseOrderBatch(
mapping: ExternalIntegrationMappingService,
client: RampClient,
purchaseOrderIds: string[],
suppliers: RampVendorSupplier[],
options: { accountingIntegration?: string } = {}
): Promise<RampPurchaseOrderBatch> {
const [poMappings, resolution] = await Promise.all([
mapping.getByEntities("purchaseOrder", purchaseOrderIds, RAMP),
prepareRampVendorResolution(mapping, client, suppliers, options)
]);
return {
...resolution,
purchaseOrderIds: new Map(
[...poMappings].map(([id, row]) => [id, row.externalId])
)
};
}
/** Whether resolving this supplier needs the Ramp vendor snapshot. */
function needsLookup(
resolution: RampVendorResolution,
supplier: Pick<RampVendorSupplier, "id" | "name">
): boolean {
const mapped = resolution.vendorIds.get(supplier.id);
if (!mapped) return Boolean(supplier.name?.trim());
const accountingVendorId = resolution.accountingVendorIds.get(supplier.id);
return (
accountingVendorId !== undefined &&
resolution.linkedAccountingVendorIds.get(supplier.id) !== accountingVendorId
);
}
/**
* What resolving one supplier's Ramp spend vendor must DO — pure, so the
* choice is tested with real values and the executor only performs it.
*
* - `use` — the mapped vendor, already linked (or nothing to link): no writes.
* - `match` — record the mapping to `vendorId`; when `linkTo` is set, link the
* vendor to that accounting vendor first. `linkedTo` is a link that already
* exists in Ramp; `conflict` is one a human made to a DIFFERENT accounting
* vendor, which is left alone.
* - `create` — no vendor to use; create one, then link it when `linkTo` is set.
* - `none` — nothing to match and no name to create with.
* - `fail` — the vendor snapshot could not be read and there is no mapping.
*/
export type RampSpendVendorDecision =
| { action: "use"; vendorId: string }
| {
action: "match";
vendorId: string;
linkTo?: string;
linkedTo?: string;
conflict?: string;
}
| { action: "create"; linkTo?: string }
| { action: "none" }
| { action: "fail"; error: unknown };
/**
* The resolution ladder for one supplier:
*
* 1. an existing `("vendor", supplier.id, "ramp")` mapping — used as-is unless
* it still needs linking to the seat-holder's accounting vendor,
* 2. the Ramp vendor the seat-holder's accounting vendor is ALREADY linked to
* (Ramp allows one, so it is the vendor this supplier's bills belong on —
* typically one Ramp created from the accounting provider's own sync),
* 3. a Ramp vendor already carrying our `external_vendor_id`,
* 4. a Ramp vendor whose name matches exactly (case-insensitive) and uniquely
* — a shared name is not an identity key, so an ambiguous one creates,
* 5. otherwise create.
*/
export function decideRampSpendVendor(
resolution: RampVendorResolution,
supplier: Pick<RampVendorSupplier, "id" | "name">
): RampSpendVendorDecision {
const mapped = resolution.vendorIds.get(supplier.id);
const accountingVendorId = resolution.accountingVendorIds.get(supplier.id);
if (mapped && !needsLookup(resolution, supplier)) {
return { action: "use", vendorId: mapped };
}
const name = (supplier.name ?? "").trim();
if (!mapped && !name) return { action: "none" };
if (!resolution.vendorLookup.ok) {
// A mapped vendor is still a valid `vendor_id`; the link is retried on the
// next push rather than holding this one on a failed list read.
return mapped
? { action: "use", vendorId: mapped }
: { action: "fail", error: resolution.vendorLookup.error };
}
const alreadyLinked = accountingVendorId
? resolution.vendorsByAccountingVendorId.get(accountingVendorId)
: undefined;
if (alreadyLinked) {
return {
action: "match",
vendorId: alreadyLinked.id,
linkedTo: accountingVendorId
};
}
const matched: Pick<RampVendor, "id" | "accounting_vendor_remote_id"> | null =
mapped
? (resolution.vendorsById.get(mapped) ?? { id: mapped })
: (resolution.vendorsByExternalId.get(supplier.id) ??
resolution.vendorsByName.get(name.toLowerCase()) ??
null);
if (!matched) return { action: "create", linkTo: accountingVendorId };
if (!accountingVendorId) return { action: "match", vendorId: matched.id };
const current = matched.accounting_vendor_remote_id;
if (current === accountingVendorId) {
return { action: "match", vendorId: matched.id, linkedTo: current };
}
if (current) {
// Someone linked this vendor to a DIFFERENT GL vendor on purpose. Carbon's
// mapping is weaker evidence than a human's choice, so leave it alone
// rather than silently re-pointing their bills.
return { action: "match", vendorId: matched.id, conflict: current };
}
return { action: "match", vendorId: matched.id, linkTo: accountingVendorId };
}
/**
* Link a Ramp SPEND vendor to the seat-holder's ACCOUNTING vendor.
*
* Three counterparty objects, three id spaces — Ramp's guide calls confusing
* them "the most common integration error":
*
* - **Merchant** — the card-network counterparty on a transaction. Read-only.
* - **Vendor** (`/developer/v1/vendors`) — the bill-pay payee. What a PO/bill
* `vendor_id` names, and what Carbon creates.
* - **Accounting vendor** (`/developer/v1/accounting/vendors`) — the GL vendor,
* published by whoever holds the accounting connection. Ramp shows it on a
* bill as "Accounting Merchant", and it is what the bill posts against.
*
* A vendor Carbon creates carries no accounting vendor, so without this link a
* bill reaches Ramp with "Accounting Merchant" empty and someone has to pick it
* before the seat-holder can post the bill.
*
* Best-effort: the bill still pushes when the link fails, exactly as it did
* before linking existed, so a refusal here can never block a payable. Returns
* the accounting vendor the Ramp vendor is now linked to, or undefined when it
* is not (so the next push tries again).
*/
async function linkAccountingVendor(
client: RampClient,
rampVendorId: string,
accountingVendorId: string
): Promise<string | undefined> {
try {
await client.updateSpendVendor(rampVendorId, {
accounting_vendor_remote_id: accountingVendorId
});
return accountingVendorId;
} catch (error) {
console.error(
`[RAMP] failed to link vendor ${rampVendorId} to accounting vendor ${accountingVendorId}`,
error
);
return undefined;
}
}
async function recordSpendVendor(
mapping: ExternalIntegrationMappingService,
resolution: RampVendorResolution,
supplierId: string,
rampVendorId: string,
linkedTo: string | undefined
) {
await mapping.link("vendor", supplierId, RAMP, rampVendorId, {
createdBy: "system",
...(linkedTo
? { metadata: { [LINKED_ACCOUNTING_VENDOR_KEY]: linkedTo } }
: {})
});
resolution.vendorIds.set(supplierId, rampVendorId);
if (linkedTo) resolution.linkedAccountingVendorIds.set(supplierId, linkedTo);
else resolution.linkedAccountingVendorIds.delete(supplierId);
}
/**
* Resolve the Ramp SPEND-vendor id a PO/bill `vendor_id` needs for a Carbon
* supplier — matching first, creating only as a last resort. The ladder is
* `decideRampSpendVendor`; this performs what it decides. A create sends the
* supplier's synced contact email + country (+ address when present) and
* `external_vendor_id`.
*
* Returns `null` (never throws) when the supplier has no name, or has no
* matching vendor AND lacks the email/country a create requires — the caller
* decides (a PO omits the optional `vendor_id`; a bill, which requires one, is
* skipped). Accounting vendors (`/accounting/vendors`) are a DIFFERENT id space
* a PO/bill `vendor_id` rejects — see `linkAccountingVendor`.
*/
export async function resolveOrCreateRampSpendVendor(
mapping: ExternalIntegrationMappingService,
client: RampClient,
supplier: RampVendorSupplier,
companyId: string,
resolution: RampVendorResolution,
opts?: {
/**
* Rethrow Ramp's rejection instead of returning null.
*
* A PO's `vendor_id` is OPTIONAL, so swallowing is right there — the PO
* still pushes. A BILL requires one, so swallowing turns Ramp's actual
* complaint ("state is required", "invalid email", …) into a generic
* "supplier has no Ramp spend vendor" that nobody can act on, with the real
* cause reaching only a server console.
*/
surfaceCreateError?: boolean;
}
): Promise<string | null> {
const decision = decideRampSpendVendor(resolution, supplier);
if (decision.action === "use") return decision.vendorId;
if (decision.action === "none") return null;
if (decision.action === "fail") throw decision.error;
if (decision.action === "match") {
if (decision.conflict) {
console.warn(
`[RAMP] vendor ${decision.vendorId} is linked to accounting vendor ${decision.conflict}, not the one mapped for supplier ${supplier.id}; leaving it`
);
}
const linkedTo = decision.linkTo
? await linkAccountingVendor(client, decision.vendorId, decision.linkTo)
: decision.linkedTo;
await recordSpendVendor(
mapping,
resolution,
supplier.id,
decision.vendorId,
linkedTo
);
return decision.vendorId;
}
const name = (supplier.name ?? "").trim();
// Create — Ramp requires a country and at least one contact email (and, for
// US, a two-letter state). Best-effort: a create that Ramp rejects (missing
// state, bad data) returns null rather than throwing, so a PO still pushes
// without a vendor and a bill is skipped rather than crashing the family.
const email = supplier.contact?.email?.trim();
const country = supplier.country?.trim();
if (!email || !country) return null;
const { contact, address } = supplier;
// `business_vendor_contacts` is a SINGLE object despite the plural name
// (OpenAPI `allOf` of one contact schema — an array is rejected "Invalid input
// type"). `state` is required for US and lives at the vendor top level.
//
// The accounting-vendor link is deliberately NOT part of the create body: a
// link Ramp refuses would then fail the create, and with it the bill. It is
// made by a separate best-effort PATCH below.
let created: { id?: string } | null;
try {
created = (await client.createSpendVendor(
{
name,
country,
...(address?.stateProvince ? { state: address.stateProvince } : {}),
external_vendor_id: supplier.id,
business_vendor_contacts: {
email,
...(contact?.firstName ? { first_name: contact.firstName } : {}),
...(contact?.lastName ? { last_name: contact.lastName } : {}),
...(contact?.phone ? { phone: contact.phone } : {})
},
...(address?.line1 && address.city && address.postalCode
? {
address: {
address_line_1: address.line1,
...(address.line2 ? { address_line_2: address.line2 } : {}),
city: address.city,
postal_code: address.postalCode,
...(address.stateProvince
? { state: address.stateProvince }
: {}),
country
}
}
: {})
},
// Entity-scoped idempotency key (keyed on the Carbon supplier id) so a
// retried push cannot create a duplicate Ramp spend vendor.
buildRampIdempotencyKey({
companyId,
operation: "createSpendVendor",
scope: supplier.id
})
)) as { id?: string } | null;
} catch (createError) {
console.error(
`[RAMP] failed to create Ramp spend vendor for supplier "${name}" (${supplier.id})`,
createError
);
if (opts?.surfaceCreateError) throw createError;
return null;
}
const rampVendorId = created?.id ?? null;
if (!rampVendorId) return null;
const linkedTo = decision.linkTo
? await linkAccountingVendor(client, rampVendorId, decision.linkTo)
: undefined;
await recordSpendVendor(
mapping,
resolution,
supplier.id,
rampVendorId,
linkedTo
);
indexSpendVendor(resolution, {
id: rampVendorId,
name,
external_vendor_id: supplier.id,
accounting_vendor_remote_id: linkedTo
});
return rampVendorId;
}