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.

15.7 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 { getAppUrl } from "@carbon/auth";
import { getCarbonServiceRole } from "@carbon/auth/client.server";
import { trigger } from "@carbon/lib/trigger";
import { SpendProviderID } from "../accounting/core/models";
import { ensureProviderSubscriptions } from "../accounting/core/subscriptions";
import { resolveCapabilities } from "../sync/capabilities";
import { applyPartyContactRequirements } from "../sync/party-contact";
import {
  extractConnections,
  isCarbonConnection,
  isConnectionLinked,
  linkedConnections,
  resolveConnectedProviderName
} from "./lib/connection-status";
import { extractEntityIds, planRampConvergence } from "./lib/convergence";
import { rampOwnsCodingSurface, resolveRampModeProfile } from "./lib/modes";
import {
  clearRampConnectionMetadata,
  ensureRampConnection,
  ensureRampWebhook,
  getRampIntegration,
  pushChartOfAccounts,
  pushCostCenters,
  pushProjects
} from "./lib/service";
import { patchRampAccountingConnectionProvider } from "./lib/state";

/**
 * Ramp integration lifecycle hooks (server-only). Registered in
 * `packages/ee/src/hooks.server.ts` and exported via `@carbon/ee/ramp/hooks.server`.
 * Cloned from the Rillet hook shape.
 */

/**
 * Converge the company's Ramp integration: validate credentials, ensure the
 * accounting connection, push CoA + cost centers, and register the webhook
 * (idempotent — `ensureRampWebhook` skips when a webhookId is already set).
 */
async function convergeRamp(
  companyId: string,
  opts: { syncReason: "install" | "settings-update" }
): Promise<void> {
  const serviceRole = getCarbonServiceRole();
  const integration = await getRampIntegration(serviceRole, companyId);
  if (!integration) return;

  const { client, metadata } = integration;

  // Validate credentials up front so a bad clientId/secret fails the install
  // with a clear message rather than deep inside a push.
  try {
    await client.getBusiness();
  } catch (err) {
    throw new Error(
      `Could not reach the Ramp API with the provided credentials — check the client id and secret. ${
        (err as Error).message
      }`
    );
  }

  const plan = planRampConvergence(metadata);

  // Connecting a platform that cannot create a vendor without a reachable
  // contact AND an identifiable location is what makes both mandatory, so
  // connecting it turns the requirement on. Driven by the mode profile's
  // declared capabilities, NOT by this being the Ramp hook — a second spend
  // provider declares the same capability and gets the same behaviour with no
  // edit here.
  //
  // Best-effort: a settings write must never fail an otherwise-good connection.
  try {
    const enabled = await applyPartyContactRequirements(
      serviceRole,
      companyId,
      resolveCapabilities(resolveRampModeProfile(metadata).capabilities)
    );
    if (enabled.length > 0) {
      console.log(
        `[ramp] enabled ${enabled.join(", ")} for company ${companyId} — Ramp cannot create a vendor without a contact email and a country`
      );
    }
  } catch (err) {
    console.error(
      `[ramp] could not enable party-contact requirements for company ${companyId}:`,
      (err as Error).message
    );
  }

  // Only the seat-holder may create the accounting connection. In push-only
  // another system holds it, and claiming it is precisely what this mode exists
  // to avoid.
  if (plan.claimConnection) {
    await ensureRampConnection(serviceRole, companyId);
  }

  // Refresh which system Ramp reports as holding the accounting seat.
  //
  // Only meaningful when Carbon is NOT the seat-holder — in provider mode Carbon
  // holds it and the field is noise. The value is otherwise written once at
  // connect and never revisited, so a peer that later disconnected left the
  // details drawer naming it indefinitely.
  //
  // A FAILED read leaves the previous value untouched: "Carbon could not ask" is
  // not "nobody is connected", and erasing on error would flap the drawer on any
  // transient Ramp outage. Confirmed 2026-09-26 that a push-only token (no
  // `accounting:write`) may call this endpoint, so a refusal here is unexpected
  // rather than routine.
  if (plan.refreshConnectionOwner) {
    try {
      await patchRampAccountingConnectionProvider(
        serviceRole,
        companyId,
        resolveConnectedProviderName(await client.getAccountingConnections())
      );
    } catch (err) {
      console.warn(
        `[ramp] could not refresh the accounting connection owner for company ${companyId}; leaving the stored value`,
        err
      );
    }
  }

  // Converge Ramp's SYNC event subscriptions, exactly as the accounting
  // providers' hooks do. Purchase orders and open payables push through the
  // shared event engine, so without these rows nothing is ever enqueued.
  await ensureProviderSubscriptions(
    serviceRole,
    companyId,
    SpendProviderID.RAMP
  );
  // The webhook is latency, not correctness — the hourly `ramp-sweep` is the
  // correctness guarantee. Ramp can't reach a non-public dev host
  // (erp.<branch>.dev), so webhook registration will fail locally; that must not
  // block the connect. Log and continue.
  try {
    await ensureRampWebhook(serviceRole, companyId, getAppUrl());
  } catch (err) {
    console.warn(
      `[ramp] webhook registration failed for company ${companyId}; continuing install (hourly sweep covers correctness)`,
      err
    );
  }

  // OAuth creates the credential-bearing integration row before the user maps
  // the card liability account that every card journal credits. Establish
  // connectivity, but do not push master data or launch finance until that one
  // required account exists. statementBankAccountId is NOT required here — it is
  // only the offset for statement payments and transfers, and each of those
  // families self-gates on it (skipping when unset). Coupling it here blocked
  // card-charge sync on an account card charges never touch.
  //
  // Scoped to the seat-holder: in push-only mode this account is not merely
  // unset, it is irrelevant — Carbon posts no card journal, and the settings form
  // does not even offer the field. Returning here would have skipped the sync
  // enqueue below, so push-only would have pushed nothing until the next hourly
  // sweep.
  if (!plan.launchSync) {
    return;
  }

  if (plan.validateEntityId) {
    let response: unknown;
    try {
      response = await client.getEntities();
    } catch (error) {
      throw new Error(
        `Could not validate Ramp entity ${plan.validateEntityId}`,
        {
          cause: error
        }
      );
    }

    if (!extractEntityIds(response).has(plan.validateEntityId)) {
      throw new Error(
        `Ramp entity ${plan.validateEntityId} is not available to this connection`
      );
    }
  }

  // Coding masters belong to whoever holds the connection: every one of these is
  // an `accounting:write` call, and in push-only the options Ramp offers are the
  // OTHER system's to publish. One gate covers all three — nothing can push a
  // coding master without the connection anyway.
  //
  // The sync still launches below: push-only has plenty to do (purchase orders,
  // receipts, provisional bills, and pulling bill payments back).
  if (plan.pushCodingMasters) {
    await pushChartOfAccounts(serviceRole, companyId);
    // Converge the cost-center ("project") field + its options. It re-runs on
    // every ramp-sync too, so a Ramp-side rejection here must not abort a valid
    // connection — log and continue so the hourly sweep can retry it.
    try {
      await pushCostCenters(serviceRole, companyId);
    } catch (err) {
      console.warn(
        `[ramp] cost-center push failed for company ${companyId}; continuing convergence`,
        err
      );
    }
    // Converge the Project field + its options — a second custom field, kept
    // independent of the cost-center one. Same fail-soft stance: the sweep retries.
    try {
      await pushProjects(serviceRole, companyId);
    } catch (err) {
      console.warn(
        `[ramp] project push failed for company ${companyId}; continuing convergence`,
        err
      );
    }
  }

  // Queued through @carbon/lib's trigger, as the Slack service does: ee cannot
  // depend on @carbon/jobs (jobs depends on ee), and importing jobs at runtime
  // fails in the built server, which runs its TypeScript source.
  // A failure to enqueue the initial sync must not fail the connect — the
  // hourly `ramp-sweep` fires `ramp-sync` for every active company regardless.
  try {
    await trigger("ramp-sync", {
      companyId,
      reason: opts.syncReason
    });
  } catch (err) {
    console.warn(
      `[ramp] initial sync enqueue failed for company ${companyId}; the hourly sweep will cover it`,
      err
    );
  }
}

export async function rampOnInstall(companyId: string): Promise<void> {
  await convergeRamp(companyId, { syncReason: "install" });
}

/**
 * Settings-save on an already-installed integration: re-converge and launch a
 * sync only after the required account and optional entity settings validate.
 */
export async function rampOnUpdate(companyId: string): Promise<void> {
  await convergeRamp(companyId, { syncReason: "settings-update" });
}

export async function rampOnUninstall(companyId: string): Promise<void> {
  const serviceRole = getCarbonServiceRole();
  // `includeInactive`: the uninstall route deactivates the row BEFORE calling
  // this hook, so the default read returns null here and every remote teardown
  // below silently never ran.
  const integration = await getRampIntegration(serviceRole, companyId, {
    includeInactive: true
  });

  if (integration) {
    const { client, metadata } = integration;

    if (metadata.webhookId) {
      try {
        await client.deleteWebhook(metadata.webhookId);
      } catch (err) {
        // Tolerate a missing webhook (already deleted).
        console.error(
          `[ramp] failed to delete webhook on uninstall (company ${companyId}): ${
            (err as Error).message
          }`
        );
      }
    }

    try {
      // Only when Carbon owns it — and "owns" means the connection at Ramp is
      // actually Carbon's, NOT merely that this install is in provider mode.
      //
      // The mode alone was not enough, and the gap was destructive rather than
      // theoretical: a provider-mode install that had ADOPTED another system's
      // connection (see `ensureRampConnection`) deleted that system's connection
      // on uninstall. It happened here on 2026-09-26 and unlinked a live peer.
      // `ensureRampConnection` now refuses to adopt, but an install created
      // before that fix still carries the adopted id, so the delete re-checks
      // whose connection it is against Ramp rather than trusting metadata.
      //
      // Note this does NOT revoke Carbon's OAuth grant: Ramp exposes no
      // revocation endpoint (confirmed 2026-09-25 against `llms-api.txt` and the
      // OpenAPI spec). A reinstall may therefore still hold `accounting:write`.
      // The accepted position is that Carbon never USES it outside provider mode
      // — see `rampOwnsCodingSurface`, which gates every write-scope call.
      if (rampOwnsCodingSurface(metadata)) {
        const live = linkedConnections(await client.getAccountingConnections());
        // Nothing linked: nothing to tear down. A connection that is Carbon's is
        // deleted; one belonging to anyone else is left alone and said so.
        const foreign = live.find((c) => !isCarbonConnection(c));
        if (live.some(isCarbonConnection)) {
          await client.deleteAccountingConnection();
        } else if (foreign) {
          console.warn(
            `[ramp] leaving the accounting connection in place for company ${companyId}: it is held by ${
              foreign.remote_provider_name ?? "another system"
            }, not Carbon`
          );
        }
      }
    } catch (err) {
      // Tolerate — the connection may already be gone.
      console.error(
        `[ramp] failed to delete accounting connection on uninstall (company ${companyId}): ${
          (err as Error).message
        }`
      );
    }
  }

  // Clear the stored `webhookId`/`connectionId` so a later reinstall re-creates
  // both at Ramp instead of trusting ids that were torn down here. Runs even
  // when the integration row is already deactivated (the read above returns null
  // then, since it gates on `active`) — `clearRampConnectionMetadata` reads the
  // row directly, so a deactivated-but-present row is still cleared.
  try {
    await clearRampConnectionMetadata(serviceRole, companyId);
  } catch (err) {
    console.error(
      `[ramp] failed to clear stored webhook/connection metadata on uninstall (company ${companyId}): ${
        (err as Error).message
      }`
    );
  }
}

export async function rampHealthcheck(
  companyId: string,
  _metadata: Record<string, unknown>
): Promise<boolean> {
  // Build the client via getRampIntegration so it carries the OAuth app creds
  // and token-refresh. The health framework's passed metadata builds a client
  // with no `oauthApp`, which cannot refresh an expired oauth2 access token and
  // would report a healthy connection as unhealthy after ~1h.
  const integration = await getRampIntegration(
    getCarbonServiceRole(),
    companyId
  );
  if (!integration) return false;

  // A connected Ramp with no card liability account is not functional:
  // convergeRamp returns early (no chart-of-accounts push, no sync) and the
  // charge sync gate skips every family without it. Report it as
  // unhealthy rather than showing a green badge over a sync that silently does
  // nothing — the required-field gap was invisible in the UI otherwise.
  // statementBankAccountId is intentionally NOT checked: it is optional (only
  // statement-payment/transfer sync needs it), so its absence is a healthy
  // "that family is off", not a broken connection.
  // Required only where card charges actually post. A push-only install never
  // pulls a card charge, so demanding the account it credits would report an
  // integration unhealthy for a family it does not run.
  const ownsCodingSurface = rampOwnsCodingSurface(integration.metadata);
  if (ownsCodingSurface && !integration.metadata.cardLiabilityAccountId) {
    return false;
  }

  try {
    await integration.client.getBusiness();
    const connections = extractConnections(
      await integration.client.getAccountingConnections()
    );
    const linked = connections.filter((connection) =>
      isConnectionLinked(connection.status)
    );

    // What "healthy" means differs by mode, because what Carbon OWNS differs.
    //
    // Provider mode: Carbon holds the seat, so its own connection must be live.
    // Checking `linked.length > 0` was too weak — it passed while another
    // system held the seat and Carbon held nothing.
    //
    // Push-only: Carbon owns no connection, by design. Requiring one reported a
    // perfectly functional install as broken whenever the customer had not yet
    // connected their accounting system — a legitimate, ordinary state during
    // onboarding, and one Carbon cannot act on. Carbon's own side is reachable
    // and it can still push purchase orders and bills, so that is healthy.
    //
    // The cost is deliberate: an install whose peer never appears hands Ramp
    // bills nobody will post, and this no longer surfaces that. The badge is a
    // boolean with no room to say why, and "broken" is the more misleading of
    // the two answers. See `.ai/runs/2026-09-26-ramp-push-only-verification.md`.
    return ownsCodingSurface ? linked.some(isCarbonConnection) : true;
  } catch {
    return false;
  }
}