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.

9.0 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 { getLogger } from "@carbon/logger";
import { getOnshapeClient } from "./lib/client";
import {
  getOnshapeIntegration,
  type OnshapeIntegrationId
} from "./lib/connection";
import type { OnshapeOAuthIntegrationId } from "./lib/integration-id";
import { patchOnshapeCompanyId } from "./lib/state";

const logger = getLogger("ee", "onshape");

// The release webhook's callback path for a company. We match/deregister by this
// PATH (not the full URL) so a host change — localhost, a tunnel, or the prod
// domain — still resolves this company's webhook(s).
function callbackPath(companyId: string): string {
  return `/api/webhook/onshape/${companyId}`;
}

// Build an Onshape client for background webhook management — against whichever
// Onshape connection the company has (public app or Government private app).
// Reads the installer (updatedBy) for token refresh/audit; falls back to "system".
async function onshapeClientForCompany(companyId: string) {
  const client = getCarbonServiceRole();
  const integration = await getOnshapeIntegration(client, companyId);
  const userId = integration.data?.updatedBy ?? "system";
  return getOnshapeClient(client, companyId, userId);
}

// Resolve the Onshape company id to register the webhook under. Prefer the id
// stored on the integration (written here at first resolve) so every path — this
// webhook registration and the sync/backfill jobs (resolveOnshapeCompanyId in
// @carbon/jobs) — targets the SAME Onshape tenant. Fall back to the first company
// the token can see, persisting it for consistency. Returns null if none.
async function resolveAndStoreOnshapeCompanyId(
  companyId: string,
  client: Awaited<ReturnType<typeof getOnshapeClient>>["client"]
): Promise<string | null> {
  const carbon = getCarbonServiceRole();
  const integration = await getOnshapeIntegration(carbon, companyId);
  if (!integration.data) return null;
  const integrationId = integration.data.id;
  const metadata = (integration.data?.metadata ?? {}) as Record<
    string,
    unknown
  >;
  const stored = metadata.onshapeCompanyId;
  if (typeof stored === "string" && stored.length > 0) return stored;

  const companies = (await client?.getCompanies()) ?? [];
  const resolved = companies[0]?.id;
  if (!resolved) return null;

  try {
    await patchOnshapeCompanyId(
      carbon,
      companyId,
      integrationId as OnshapeIntegrationId,
      resolved
    );
  } catch (error) {
    // Non-fatal: we can still register with the resolved id; the jobs just fall
    // back to their own getCompanies() resolve if the store didn't stick.
    console.error(
      "onshape: failed to persist resolved Onshape company id",
      error
    );
  }
  return resolved;
}

// Onshape's write scope — needed to create translation (export) jobs and manage
// the release webhook. A connection authorized before this scope was requested
// holds a read-only token, and a refresh can't widen it (the refresh grant sends
// no scope), so the only remedy is a reconnect.
const ONSHAPE_WRITE_SCOPE = "OAuth2Write";

// Does the stored connection have write access? Read from the scope captured at
// the OAuth callback. Legacy installs predate that field (no `scope`) — treat
// them as read-only so we prompt for a reconnect rather than silently failing.
export function onshapeConnectionHasWriteScope(
  metadata: Record<string, unknown> | null | undefined
): boolean {
  const scope = metadata?.scope;
  if (typeof scope !== "string") return false;
  return scope.split(/\s+/).includes(ONSHAPE_WRITE_SCOPE);
}

export type OnshapeWebhookResult = { ok: true } | { ok: false; error: string };

function webhookFailure(error: unknown): OnshapeWebhookResult {
  return {
    ok: false,
    error: error instanceof Error ? error.message : String(error)
  };
}

// Register the go-forward release webhook (onshape.revision.created). Idempotent:
// no-op if a subscription for this company's callback already exists. Never
// throws — failures are logged and returned so the caller can surface them (the
// common causes: a callback that isn't publicly reachable, or an OAuth token
// granted before OAuth2Write was requested, which can't manage webhooks until
// the user reconnects Onshape).
export async function registerOnshapeWebhook(
  companyId: string
): Promise<OnshapeWebhookResult> {
  const onshape = await onshapeClientForCompany(companyId);
  if (onshape.error || !onshape.client) {
    console.error(
      "onshape: could not build client; skipping webhook registration",
      onshape.error
    );
    return { ok: false, error: onshape.error ?? "no client" };
  }
  const path = callbackPath(companyId);
  try {
    const existing = await onshape.client.getWebhooks();
    // The element sync's transient translation webhooks share the path.
    const alreadyRegistered = (existing.items ?? []).some(
      (webhook) =>
        typeof webhook.url === "string" &&
        webhook.url.includes(path) &&
        Array.isArray(webhook.events) &&
        webhook.events.includes("onshape.revision.created")
    );
    if (alreadyRegistered) return { ok: true };

    const onshapeCompanyId = await resolveAndStoreOnshapeCompanyId(
      companyId,
      onshape.client
    );
    if (!onshapeCompanyId) {
      console.error(
        "onshape: could not resolve Onshape company id; skipping webhook registration"
      );
      return { ok: false, error: "could not resolve Onshape company id" };
    }
    await onshape.client.createWebhook({
      url: `${getAppUrl()}${path}`,
      events: ["onshape.revision.created"],
      companyId: onshapeCompanyId
    });
    console.log(`onshape: registered release webhook for company ${companyId}`);
    return { ok: true };
  } catch (error) {
    console.error("onshape: webhook registration failed", error);
    return webhookFailure(error);
  }
}

// Delete Carbon's release webhook(s) for this company. Idempotent; never throws.
export async function deregisterOnshapeWebhooks(
  companyId: string
): Promise<OnshapeWebhookResult> {
  const onshape = await onshapeClientForCompany(companyId);
  if (onshape.error || !onshape.client) {
    console.error(
      "onshape: could not build client; skipping webhook cleanup",
      onshape.error
    );
    return { ok: false, error: onshape.error ?? "no client" };
  }
  const path = callbackPath(companyId);
  try {
    const webhooks = await onshape.client.getWebhooks();
    const ours = (webhooks.items ?? []).filter(
      (webhook) => typeof webhook.url === "string" && webhook.url.includes(path)
    );
    for (const webhook of ours) {
      await onshape.client.deleteWebhook(webhook.id);
    }
    console.log(
      `onshape: deregistered ${ours.length} webhook(s) for company ${companyId}`
    );
    return { ok: true };
  } catch (error) {
    console.error("onshape: webhook deregistration failed", error);
    return webhookFailure(error);
  }
}

// Keep the subscription in lockstep with the asset-sync toggle: it should exist
// iff asset sync is enabled. Called from the integration settings save — the
// universal hook point, since asset sync is off by default and every company
// (new or already-connected) must enable it there. NOTE: connections authorized
// before the OAuth2Write scope was requested hold Read-only tokens and will fail
// here until the user reconnects Onshape — the settings save surfaces that
// failure rather than swallowing it.
export async function ensureOnshapeReleaseWebhook(
  companyId: string,
  assetSyncEnabled: boolean
): Promise<OnshapeWebhookResult> {
  if (assetSyncEnabled) {
    return registerOnshapeWebhook(companyId);
  }
  return deregisterOnshapeWebhooks(companyId);
}

// Disconnect: remove the subscription so it doesn't keep firing at a dead callback.
export async function onshapeOnUninstall(companyId: string): Promise<void> {
  await deregisterOnshapeWebhooks(companyId);
}

/**
 * Building the client refreshes an expired token and one read proves it is
 * accepted, so a revoked grant reads unhealthy. `getIntegrationHealth` caches a
 * healthy answer for five hours, which bounds the quota this spends.
 */
export function onshapeHealthcheck(integrationId: OnshapeOAuthIntegrationId) {
  return async (companyId: string): Promise<boolean> => {
    try {
      const onshape = await getOnshapeClient(
        getCarbonServiceRole(),
        companyId,
        "system",
        integrationId
      );
      if (!onshape.client) {
        logger.warn("Onshape healthcheck: no client", {
          companyId,
          integrationId,
          error: onshape.error
        });
        return false;
      }
      await onshape.client.getCompanies();
      return true;
    } catch (error) {
      logger.warn("Onshape healthcheck: request failed", {
        companyId,
        integrationId,
        error
      });
      return false;
    }
  };
}