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
perf(onshape): spend fewer Onshape API calls per export
Sidwebworks374b98c7bb5e
diff --git a/.claude/rules/onshape-panel.md b/.claude/rules/onshape-panel.mdindex 85d85a7cca..5d20a59bf1 100644--- a/.claude/rules/onshape-panel.md+++ b/.claude/rules/onshape-panel.md@@ -54,6 +54,7 @@ The `carbon` cookie is `SameSite=Lax` and never reaches a cross-site iframe, so| Release revision item | `release:<releaseId>:<partNumber>` || Onshape-written BOM line | entityType `methodMaterial`; `metadata.makeMethodId` names the method || Draft the panel made | entityType `makeMethod` (`DRAFT_MARKER_ENTITY_TYPE`); `externalId` is the Draft id, `metadata.sourceMethodId` the Active method it copied |+| Source of an item's last assembly export | entityType `modelSource`, `entityId` the item, integration the connection's id; `externalId` hashes the document, element, configuration and the version or workspace microversion; `metadata.modelUploadId` the model it produced |A non-default configuration is appended to the key (`normalizeConfiguration`, `externalIdFor*` in `panel/status.ts`).@@ -121,7 +122,9 @@ The gateway rejects a request line over 4,096 bytes, and a PostgREST `.in()` lis## Onshape API facts- Root identity comes from element metadata ("Part number", "Name", "Description"); the BOM's top-level row (`includeTopLevelAssemblyRow=true`) is the fallback.-- A Part Studio model export needs exactly one `partId`. The thumbnail endpoint cannot select a part or configuration, so only unconfigured assemblies take Onshape's thumbnail; others come from Carbon's model optimizer.+- A Part Studio model export needs exactly one `partId`. Thumbnails come from Carbon's model optimizer, never Onshape's thumbnail endpoint (it cannot select a part or configuration, and the optimizer renders one anyway).+- `GET /documents/d/{did}/w/{wid}/currentmicroversion` changes on any edit to the document. An assembly's own element microversion does not change when a Part Studio it uses does, so the export skip keys on the document's.+- `onshape.model.translation.complete` can be registered per document (`documentId`, `isTransient: true`); its payload carries `translationId`. A webhook that answers errors is dropped by Onshape.- Unresolved action-URL placeholders arrive literally (`{$partNumber}`) and are read as null (`parsePanelContext`).- Extensions render only for users subscribed to the app; an OAuth grant alone shows nothing.- A linked document's BOM can report a different revision for a part than the source document's BOM at the same version.@@ -129,11 +132,12 @@ The gateway rejects a request line over 4,096 bytes, and a PostgREST `.in()` lis## Background job and dev workflow-- An element's export is `runOnshapeElementSync` (`onshape-sync-element.ts`), resumable steps namespaced by a prefix: `existing` (a released part's model id is known before any export; when its row exists the export is skipped and the item linked to it), `translate` (the model and every drawing translation start at once), `poll-n` / `sleep-n` (all translations polled together, `step.sleep` between, so no function is held), `fetch` (a `step.invoke` of `onshape-fetch`, `onshape-fetch.ts`: the assembler's `fetch` action copies the STEP from Onshape into temp-staging at `{companyId}/models/onshape-fetch-{translationId}.step`, with a bearer from `OnshapeClient.externalDataDownload` minted inside the submit step; with no assembler configured, one `download` step stages it), `drawings`, `attach` (moves the staged object to `{companyId}/models/{id}.step`, inserts the row) and `thumbnail`. A retry resumes at the failed step, so a late failure never re-runs a translation. A fetch refused with `LIMIT_EXCEEDED` returns `tooLarge` (a permanent skip), never throws. Every Onshape-calling step is wrapped in `withRateLimitRetry` (`onshape-rate-limit.ts`). A staged object a failed attach leaves behind is an unreferenced temp-staging object, which the 7-day staged-raw sweep (`scheduled/cleanup.ts`) removes.-- A released drawing alone (no model element) is `runOnshapeDrawingSync`, the same steps without the model: `translate`, `poll-n` / `sleep-n`, `attach` (downloads the PDF and attaches it; a PDF past the document limit returns `tooLarge`).+- An element's export is `runOnshapeElementSync` (`onshape-sync-element.ts`), resumable steps namespaced by a prefix: `existing` (a released part's model id is known before any export; when its row exists the export is skipped and the item linked to it. An assembly is compared with its `modelSource` mapping: the version, or the workspace's current microversion (one call), unchanged and the item still on the model it produced skips the export too), `translate` (the model and every drawing translation start at once), the wait (`waitForTranslations`: all translations polled together, six quick polls with `step.sleep` between; one still running registers a transient translation.complete webhook (`webhook`) and waits on `carbon/onshape-translation-complete` (`wait-n`, 5 min) with a poll after each wait, deleted (`unwebhook`) when done; with no webhook it polls every 30 s; an hour without finishing fails the sync. The webhook only wakes the run, the poll reads the result), `fetch` (a `step.invoke` of `onshape-fetch`, `onshape-fetch.ts`: the assembler's `fetch` action copies the STEP from Onshape into temp-staging at `{companyId}/models/onshape-fetch-{translationId}.step`, with a bearer from `OnshapeClient.externalDataDownload` minted inside the submit step; with no assembler configured, one `download` step stages it), `drawings` and `attach` (moves the staged object to `{companyId}/models/{id}.step`, inserts the row, records an assembly's `modelSource`). A retry resumes at the failed step, so a late failure never re-runs a translation. A fetch refused with `LIMIT_EXCEEDED` returns `tooLarge` (a permanent skip), never throws. Every Onshape-calling step is wrapped in `withRateLimitRetry` (`onshape-rate-limit.ts`). A staged object a failed attach leaves behind is an unreferenced temp-staging object, which the 7-day staged-raw sweep (`scheduled/cleanup.ts`) removes.+- A released drawing alone (no model element) is `runOnshapeDrawingSync`, the same steps without the model: `translate`, the wait, `attach` (downloads the PDF and attaches it; a PDF past the document limit returns `tooLarge`).- Callers: `onshape-panel-sync` and `onshape-revision-sync` (after its `resolve-revision` step, which returns either an element or a drawing to sync) run the pipeline in their own run; the backfill `step.invoke`s `onshape-element-sync` per model item and `onshape-drawing-sync` per released drawing, so a long backfill stays under the per-run step limit. None of them carries `ASSEMBLER_CONCURRENCY`: Inngest counts every executing step of a function against its keys, so the Onshape polls would take the five env-wide assembler slots from optimize, convert and plan. Only `onshape-fetch` carries it. The three run checkpointing (`ONSHAPE_CHECKPOINTING`, `maxRuntime: "60s"`): consecutive steps share one request. Keep `maxRuntime` far below Vercel's 300 s, since a step that starts late in the window gets only the rest of the request; checkpointing is not on client-wide because other functions have single steps that run for minutes.- `onshape-panel-sync` (Inngest) is the panel's job: the element pipeline above, or a released drawing as PDF. `elementKind` is `partstudio`, `assembly` or `drawing`; retries 1; concurrency 1 per item. Applies queue it with event id `<planId>:<itemId>:<elementId>`, so a retried apply exports once. A queue failure is reported and the writes stay; a part push then deletes the new link so the next push retries.-- `ONSHAPE_DEV_CACHE=1` serves repeated GETs from a 10-minute Redis cache, only for `DEV_CACHEABLE_PATHS` in `lib/client.ts`; the key is the path alone, so every company shares entries. Never add a polling endpoint. Live calls are counted in Redis `onshape:api-calls:<year>`.+- `ONSHAPE_DEV_CACHE=1` serves repeated GETs from a 10-minute Redis cache, only for `DEV_CACHEABLE_PATHS` in `lib/client.ts`; the key is the path alone, so every company shares entries. Never add a polling endpoint (`currentmicroversion` is excluded for that reason). Live calls are counted in Redis `onshape:api-calls:<year>`, and per endpoint in the hash `onshape:api-calls:<year>:paths` (ids replaced by `{id}`, `apiCallPathKey`).+- `webhook.onshape.$companyId.ts` answers `onshape.model.translation.complete` and Onshape's `webhook.*` events for any active Onshape connection, the panel's included, before the sync connection's checks; a translation event becomes `carbon/onshape-translation-complete`.## Panel UIdiff --git a/apps/erp/app/routes/api+/webhook.onshape.$companyId.ts b/apps/erp/app/routes/api+/webhook.onshape.$companyId.tsindex a174cf5c60..cccd9e4ae0 100644--- a/apps/erp/app/routes/api+/webhook.onshape.$companyId.ts+++ b/apps/erp/app/routes/api+/webhook.onshape.$companyId.ts@@ -3,8 +3,13 @@// including ports, remain AGPLv3; serving them over a network requires releasing their source.import { getCarbonServiceRole } from "@carbon/auth/client.server";-import { getOnshapeIntegration } from "@carbon/ee/onshape";+import {+ getOnshapeIntegration,+ ONSHAPE_INTEGRATION_IDS+} from "@carbon/ee/onshape";+import { ONSHAPE_V2_INTEGRATION_ID } from "@carbon/ee/onshape/integration-id";import { trigger } from "@carbon/jobs";+import { inngest } from "@carbon/lib/inngest";import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";import { data } from "react-router";import { z } from "zod";@@ -18,8 +23,16 @@ import { z } from "zod";// │ validate minimal envelope, log the event// ▼// onshape.revision.created ──▶ trigger("onshape-revision-sync")+// onshape.model.translation.complete+// ──▶ carbon/onshape-translation-complete (wakes+// the element sync waiting on it)// everything else ──▶ ack 200 (logged, no dispatch)//+// The translation webhook is registered by the element sync for any Onshape+// connection, the panel's included, so it and Onshape's own webhook.* events+// are answered before the sync connection's checks: a webhook answered with an+// error is dropped by Onshape.+//// AUTH: like the jira/linear receivers, no signature verification — the endpoint// relies on the callback URL + the active-integration check. A forged event can't// inject content: the sync job re-resolves the released revision against the@@ -62,7 +75,65 @@ export async function action({ request, params }: ActionFunctionArgs) {return data({ success: false }, { status: 400 });}+ let body: unknown;+ try {+ body = await request.json();+ } catch (parseError) {+ console.error("Onshape webhook: body is not valid JSON", parseError);+ return data(+ { success: false, error: "Invalid JSON body" },+ { status: 400 }+ );+ }++ const parsed = onshapeWebhookEnvelope.safeParse(body);++ if (!parsed.success) {+ return data(+ { success: false, error: parsed.error.format() },+ { status: 400 }+ );+ }+const serviceRole = getCarbonServiceRole();++ if (+ parsed.data.event === "onshape.model.translation.complete" ||+ parsed.data.event.startsWith("webhook.")+ ) {+ const connection = await serviceRole+ .from("companyIntegration")+ .select("id")+ .in("id", [...ONSHAPE_INTEGRATION_IDS, ONSHAPE_V2_INTEGRATION_ID])+ .eq("companyId", companyId)+ .eq("active", true)+ .limit(1);+ if (connection.error) {+ console.error(+ "Onshape webhook: integration query failed",+ connection.error+ );+ return data(+ { success: false, error: "Integration query failed" },+ { status: 400 }+ );+ }+ if (connection.data.length === 0) {+ return data(+ { success: false, error: "Integration not active" },+ { status: 400 }+ );+ }+ // Only a wake-up: the sync reads the translation from Onshape itself.+ if (parsed.data.translationId) {+ await inngest.send({+ name: "carbon/onshape-translation-complete",+ data: { companyId, translationId: parsed.data.translationId }+ });+ }+ return { success: true };+ }+const integration = await getOnshapeIntegration(serviceRole, companyId);if (integration.error) {@@ -104,26 +175,6 @@ export async function action({ request, params }: ActionFunctionArgs) {return { success: true };}- let body: unknown;- try {- body = await request.json();- } catch (parseError) {- console.error("Onshape webhook: body is not valid JSON", parseError);- return data(- { success: false, error: "Invalid JSON body" },- { status: 400 }- );- }-- const parsed = onshapeWebhookEnvelope.safeParse(body);-- if (!parsed.success) {- return data(- { success: false, error: parsed.error.format() },- { status: 400 }- );- }-const {event,messageId,@@ -189,8 +240,8 @@ export async function action({ request, params }: ActionFunctionArgs) {// that follow a release instead, so there is nothing to dispatch here.break;default:- // System events (webhook.register / ping) and anything we don't handle:- // ack so Onshape doesn't retry-storm; the log above captures them.+ // Anything we don't handle: ack so Onshape doesn't retry-storm; the log+ // above captures it.break;}diff --git a/packages/ee/src/onshape/hooks.server.ts b/packages/ee/src/onshape/hooks.server.tsindex f3cca74880..16acc7d1e5 100644--- a/packages/ee/src/onshape/hooks.server.ts+++ b/packages/ee/src/onshape/hooks.server.ts@@ -120,8 +120,13 @@ export async function registerOnshapeWebhook(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)+ (webhook) =>+ typeof webhook.url === "string" &&+ webhook.url.includes(path) &&+ Array.isArray(webhook.events) &&+ webhook.events.includes("onshape.revision.created"));if (alreadyRegistered) return { ok: true };diff --git a/packages/ee/src/onshape/lib/api-call-key.test.ts b/packages/ee/src/onshape/lib/api-call-key.test.tsnew file mode 100644index 0000000000..6d6a3bf1a9--- /dev/null+++ b/packages/ee/src/onshape/lib/api-call-key.test.ts@@ -0,0 +1,25 @@+// 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 { describe, expect, it } from "vitest";+import { apiCallPathKey } from "./api-call-key";++describe("apiCallPathKey", () => {+ it("counts every call to one endpoint under one key", () => {+ expect(+ apiCallPathKey("/api/v10/translations/5f1e2d3c4b5a69788796a5b4")+ ).toBe("/api/v10/translations/{id}");+ expect(+ apiCallPathKey(+ "/api/v10/assemblies/d/5f1e2d3c4b5a69788796a5b4/w/0a1b2c3d4e5f60718293a4b5/e/aaaabbbbccccddddeeeeffff/bom?indented=true"+ )+ ).toBe("/api/v10/assemblies/d/{id}/w/{id}/e/{id}/bom");+ });++ it("replaces part ids and other non-word segments", () => {+ expect(+ apiCallPathKey("/api/v10/metadata/d/abc123/v/def456/e/ghi789/p/JHD")+ ).toBe("/api/v10/metadata/d/{id}/v/{id}/e/{id}/p/{id}");+ });+});diff --git a/packages/ee/src/onshape/lib/api-call-key.ts b/packages/ee/src/onshape/lib/api-call-key.tsnew file mode 100644index 0000000000..604b0519e1--- /dev/null+++ b/packages/ee/src/onshape/lib/api-call-key.ts@@ -0,0 +1,18 @@+// 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.++/** An API path as one counter key per endpoint: the query dropped and every+ * id (any segment that is not a lowercase word or the API version) replaced,+ * so `/api/v10/translations/<id>` counts as `/api/v10/translations/{id}`. */+export function apiCallPathKey(path: string): string {+ return (path.split("?")[0] ?? "")+ .split("/")+ .map((segment) =>+ segment === "" ||+ (/^(v\d+|[a-z]+)$/.test(segment) && !/^[0-9a-f]{24}$/.test(segment))+ ? segment+ : "{id}"+ )+ .join("/");+}diff --git a/packages/ee/src/onshape/lib/client.ts b/packages/ee/src/onshape/lib/client.tsindex 778c1f138c..30b05f4162 100644--- a/packages/ee/src/onshape/lib/client.ts+++ b/packages/ee/src/onshape/lib/client.ts@@ -16,6 +16,7 @@ import {resolveIntegrationSecrets} from "../../integrations/secrets";import { normalizeConfiguration } from "../panel/status";+import { apiCallPathKey } from "./api-call-key";import {getOnshapeIntegration,isOnshapeIntegrationId,@@ -84,7 +85,9 @@ export interface OnshapeElementRow {const DEV_CACHEABLE_PATHS = [/^\/api\/v\d+\/parts\//,/^\/api\/v\d+\/partstudios\/.*\/massproperties/,- /^\/api\/v\d+\/documents\//,+ // Not currentmicroversion: the element sync compares it to skip unchanged+ // exports, and a cached value would skip a changed one.+ /^\/api\/v\d+\/documents\/(?!.*\/currentmicroversion)/,/^\/api\/v\d+\/assemblies\/.*\/bom/,/^\/api\/v\d+\/metadata\//,// A new release shows after the TTL; flush onshape-dev-cache:* for sooner.@@ -310,11 +313,16 @@ export class OnshapeClient {};}- /** Counts in Redis `onshape:api-calls:<year>`; never awaited. */+ /** Counts in Redis `onshape:api-calls:<year>`, and per endpoint in the hash+ * `onshape:api-calls:<year>:paths`; never awaited. */private async countLiveCall(path: string) {try {const year = new Date().getUTCFullYear();- await redis.incr(`onshape:api-calls:${year}`);+ await redis+ .multi()+ .incr(`onshape:api-calls:${year}`)+ .hincrby(`onshape:api-calls:${year}:paths`, apiCallPathKey(path), 1)+ .exec();} catch {// Never let accounting break a real request.}@@ -361,30 +369,55 @@ export class OnshapeClient {return Array.isArray(response) ? response : (response.items ?? []);}- // Register a webhook subscription so Onshape POSTs lifecycle events to Carbon.- // Used to subscribe to onshape.revision.created (go-forward asset sync) on- // connect. Requires a publicly reachable callback URL and an OAuth app that+ // Register a webhook subscription so Onshape POSTs events to Carbon: the+ // release webhook (onshape.revision.created, company scope) and the element+ // sync's translation webhook (onshape.model.translation.complete, document+ // scope). Requires a publicly reachable callback URL and an OAuth app that// permits webhook management. The API also REQUIRES `options` and a scope// (`companyId` or `documentId`) — omitting either is a 400 ("options field is- // required" / "company id or document id required").- async createWebhook(params: {- url: string;- events: string[];- companyId: string; // Onshape company id — scopes the subscription- collapseEvents?: boolean;- }): Promise<{ id: string } & Record<string, unknown>> {+ // required" / "company id or document id required"). A transient webhook is+ // cleaned up by Onshape after a period of inactivity.+ async createWebhook(+ params: {+ url: string;+ events: string[];+ collapseEvents?: boolean;+ isTransient?: boolean;+ } & ({ companyId: string } | { documentId: string })+ ): Promise<{ id: string } & Record<string, unknown>> {return this.request<{ id: string } & Record<string, unknown>>("POST","/api/v10/webhooks",{url: params.url,events: params.events,- companyId: params.companyId,+ ...("companyId" in params+ ? { companyId: params.companyId }+ : { documentId: params.documentId }),+ ...(params.isTransient === undefined+ ? {}+ : { isTransient: params.isTransient }),options: { collapseEvents: params.collapseEvents ?? false }});}+ /** The workspace's current microversion: it changes on every edit to the+ * document, so it names the workspace's exact state. */+ async getCurrentMicroversion(+ documentId: string,+ workspaceId: string+ ): Promise<string> {+ const response = await this.request<{ microversion?: string }>(+ "GET",+ `/api/v10/documents/d/${documentId}/w/${workspaceId}/currentmicroversion`+ );+ if (!response.microversion) {+ throw new Error("Onshape returned no current microversion");+ }+ return response.microversion;+ }+// List the webhook subscriptions visible to the authenticated principal. Used// on disconnect to find (and delete) the ones Carbon registered.async getWebhooks(): Promise<{@@ -802,30 +835,6 @@ export class OnshapeClient {}}- // Onshape-rendered element thumbnail at a version (shaded view PNG). Lets the- // sync set an item thumbnail with one small API call instead of screenshotting- // the viewer against the full decoded mesh (the model-thumbnail pipeline).- // `size` is a WxH string from Onshape's fixed set (e.g. "300x300").- async getElementThumbnail(- documentId: string,- versionId: string,- elementId: string,- size: string = "300x300",- wvm: "w" | "v" = "v"- ): Promise<ArrayBuffer> {- try {- const response = await this.axiosInstance.request<ArrayBuffer>({- method: "GET",- url: `/api/v10/thumbnails/d/${documentId}/${wvm}/${versionId}/e/${elementId}/s/${size}`,- responseType: "arraybuffer",- headers: { Accept: "image/png" }- });- return response.data;- } catch (error) {- throw this.toApiError(error);- }- }-// Stream external data to a file on disk — for results too large to buffer// in memory (e.g. a multi-GB STEP export destined for compression, not// attachment). Aborts with OnshapeAssetTooLargeError as soon as thediff --git a/packages/jobs/AGENTS.md b/packages/jobs/AGENTS.mdindex 6761c51f52..7db610adae 100644--- a/packages/jobs/AGENTS.md+++ b/packages/jobs/AGENTS.md@@ -59,8 +59,8 @@ pnpm --filter @carbon/jobs plan:company -- --company <id> --user <id> # MRP +| `ramp-sweep` | `0 * * * *` | Dispatch Ramp sync for every active install || `oee-sweep` | `*/2 * * * *` | Sends one `carbon/oee-sync` per (company, OEE integration) that is active and has at least 1 `workCenterDevice`. OEE providers have no webhooks, so this poll is the only input || `oee-sync` | `carbon/oee-sync` (concurrency 1 per company; `singleton` with `mode: "skip"` per company and integration, so an event that arrives while a run is live is dropped) | Syncs every mapped device of one OEE integration in ONE `step.run` (`syncOeeDevice`, `oee-sync-device.ts`): reads the provider's state changes from `lastEventAt − 10 minutes` (24 hours before the mapping on a first sync), stores them in `machineStateChange`, then under `lockWorkCenterDevice` reads the loads (`workCenterLoad`), maintenance block periods and recorded machine time in a bounded window, runs `planMachineTime` and writes Machine `productionEvent` / `unattributedMachineTime` rows; it clears `workCenterDevice.unplannedPressAt` and deletes closed unattributed rows shorter than `minimumStateSeconds`. A failed device gets `lastSyncError` and keeps its cursor; the others continue, except on `OeeProviderUnavailableError` (network failure, timeout, 5xx), which stops the run. Skipped (no error) when the company is not entitled, the integration is inactive or the key is empty. After each device commits, posts the Machine events its sync ended (`endedEventIds` → `postEndedMachineEvents`, `post-production-event` as `userId "system"`); a posting failure is logged, never fails the device. See `.claude/rules/oee-provider.md` |-| `onshape-element-sync` | `carbon/onshape-element-sync` (`step.invoke`d by `onshape-backfill`, one per model item) | One Onshape element's export onto an item, as `runOnshapeElementSync`'s resumable steps: skip when the source's model exists, start the model and drawing translations together, poll with `step.sleep`, `step.invoke` `onshape-fetch`, attach. Concurrency 1 per item. See `.claude/rules/onshape-panel.md` |-| `onshape-drawing-sync` | `carbon/onshape-drawing-sync` (`step.invoke`d by `onshape-backfill`, one per released drawing) | One released Onshape drawing as a PDF on its model item, as `runOnshapeDrawingSync`'s resumable steps: translate, poll with `step.sleep`, attach. Concurrency 1 per item |+| `onshape-element-sync` | `carbon/onshape-element-sync` (`step.invoke`d by `onshape-backfill`, one per model item) | One Onshape element's export onto an item, as `runOnshapeElementSync`'s resumable steps: skip when the source's model exists (an assembly: when its version or workspace microversion is unchanged), start the model and drawing translations together, poll with `step.sleep` and then wait on the translation.complete webhook, `step.invoke` `onshape-fetch`, attach. Concurrency 1 per item. See `.claude/rules/onshape-panel.md` |+| `onshape-drawing-sync` | `carbon/onshape-drawing-sync` (`step.invoke`d by `onshape-backfill`, one per released drawing) | One released Onshape drawing as a PDF on its model item, as `runOnshapeDrawingSync`'s resumable steps: translate, wait as the element sync does, attach. Concurrency 1 per item || `onshape-fetch` | `carbon/onshape-fetch` (`step.invoke`d by the element sync) | The assembler's `fetch` copies one finished Onshape translation into temp-staging. Its own function so that only it holds `ASSEMBLER_CONCURRENCY` (Inngest counts every executing step of a function against its keys); an export past the upload limit returns `{ tooLarge: true }` || `mount-publish` | `carbon/mount-publish` | One company's push to Mount: a step per batch of 200 until nothing is stale, a batch publishes nothing, or 50 batches; progress and outcome in `companyIntegration.metadata.lastPublish.{entityType}`, which the integration page reads || `mount-sweep` | `30 2 * * *` | Dispatch a scheduled `mount-publish` for every active Mount install |diff --git a/packages/jobs/src/inngest/functions/integrations/onshape-attach.ts b/packages/jobs/src/inngest/functions/integrations/onshape-attach.tsindex bdd996fdd1..3599a7df28 100644--- a/packages/jobs/src/inngest/functions/integrations/onshape-attach.ts+++ b/packages/jobs/src/inngest/functions/integrations/onshape-attach.ts@@ -263,38 +263,6 @@ async function upsertSyncedDocument(return inserted.data.id;}-// Store an Onshape-rendered thumbnail for a modelUpload, matching the-// model-thumbnail pipeline's path convention-// ({companyId}/thumbnails/{modelId}/{modelId}.png) so both producers are-// interchangeable to consumers of modelUpload.thumbnailPath.-export async function attachModelThumbnail(- carbon: CarbonClient,- input: { companyId: string; modelUploadId: string; pngBytes: Uint8Array }-): Promise<void> {- const thumbnailPath = `${input.companyId}/thumbnails/${input.modelUploadId}/${input.modelUploadId}.png`;- const uploaded = await storage(carbon)- .company(input.companyId)- .upload(thumbnailPath, input.pngBytes, {- upsert: true,- contentType: "image/png"- });- if (uploaded.error) {- throw new Error(- `attachModelThumbnail: upload failed (${thumbnailPath}): ${uploaded.error.message}`- );- }- const updated = await carbon- .from("modelUpload")- .update({ thumbnailPath })- .eq("id", input.modelUploadId)- .eq("companyId", input.companyId);- if (updated.error) {- throw new Error(- `attachModelThumbnail: modelUpload update failed: ${updated.error.message}`- );- }-}-export async function attachOnshapeAssetsToItem(carbon: CarbonClient,input: AttachOnshapeAssetsInputdiff --git a/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.test.ts b/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.test.tsindex bac64859dd..fe4e7fafdb 100644--- a/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.test.ts+++ b/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.test.ts@@ -95,10 +95,7 @@ beforeEach(() => {vi.clearAllMocks();mocks.getRevisions.mockResolvedValue({ items: [released] });mocks.getCompanyRevisions.mockResolvedValue({ items: [released] });- mocks.sync.mockResolvedValue({- modelUploadId: "selected-model",- thumbnailAttached: false- });+ mocks.sync.mockResolvedValue({ modelUploadId: "selected-model" });});describe("release identity", () => {diff --git a/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.ts b/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.tsindex b14213cb0a..9dbb96d17e 100644--- a/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.ts+++ b/packages/jobs/src/inngest/functions/integrations/onshape-revision-sync.ts@@ -62,7 +62,6 @@ export interface OnshapeRevisionSyncResult {| "asset-too-large"; // export exceeds Carbon's upload limits — permanent skipitemId?: string;modelUploadId?: string | null;- thumbnailAttached?: boolean; // Onshape-rendered thumbnail stored — no fallback event neededreleaseKey?: string;}@@ -338,7 +337,6 @@ export const onshapeRevisionSyncFunction = inngest.createFunction(synced: true,itemId: resolved.itemId,modelUploadId: attached.modelUploadId,- thumbnailAttached: attached.thumbnailAttached,releaseKey: resolved.releaseKey};}diff --git a/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.test.ts b/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.test.tsindex 5808677806..8b13394d80 100644--- a/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.test.ts+++ b/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.test.ts@@ -7,7 +7,8 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import type { SyncOnshapeElementInput } from "./onshape-sync-element";import {runOnshapeDrawingSync,- runOnshapeElementSync+ runOnshapeElementSync,+ translationEventCondition} from "./onshape-sync-element";const mocks = vi.hoisted(() => ({@@ -19,24 +20,32 @@ const mocks = vi.hoisted(() => ({downloadExternalData: vi.fn(),downloadExternalDataToFile: vi.fn(),externalDataDownload: vi.fn(),- getElementThumbnail: vi.fn()+ getCurrentMicroversion: vi.fn(),+ createWebhook: vi.fn(),+ deleteWebhook: vi.fn()},attach: vi.fn(),- thumbnail: vi.fn(),assemblerEnabled: vi.fn(),invoke: vi.fn(),- existingModel: null as { id: string; name: string } | null+ existingModel: null as { id: string; name: string } | null,+ modelSource: null as {+ externalId: string;+ metadata: { modelUploadId: string };+ } | null,+ itemModelUploadId: null as string | null,+ upserts: [] as Record<string, unknown>[]}));vi.mock("@carbon/ee/onshape", () => ({getOnshapeClient: vi.fn(async () => ({ client: mocks.client })),OnshapeAssetTooLargeError: class extends Error {}}));vi.mock("@carbon/utils", () => ({- getFileSizeLimit: () => ({ bytes: 100000 })+ getFileSizeLimit: () => ({ bytes: 100000 }),+ datetime: { timestamp: () => "2026-10-20T00:00:00Z" }}));+vi.mock("@carbon/env", () => ({ getAppUrl: () => "https://app.carbon.test" }));vi.mock("./onshape-attach", () => ({- attachOnshapeAssetsToItem: mocks.attach,- attachModelThumbnail: mocks.thumbnail+ attachOnshapeAssetsToItem: mocks.attach}));vi.mock("../tasks/assembler-client", () => ({assemblerEnabled: mocks.assemblerEnabled@@ -50,15 +59,26 @@ vi.mock("./onshape-fetch", () => ({const step = {run: async (_id: string, fn: () => unknown) => fn(),sleep: vi.fn(async () => undefined),+ waitForEvent: vi.fn(async () => null),invoke: mocks.invoke};const carbon = {- from: () => {+ from: (table: string) => {+ const row = () =>+ table === "externalIntegrationMapping"+ ? mocks.modelSource+ : table === "item"+ ? { modelUploadId: mocks.itemModelUploadId }+ : mocks.existingModel;const query = {select: () => query,eq: () => query,- maybeSingle: async () => ({ data: mocks.existingModel, error: null })+ maybeSingle: async () => ({ data: row(), error: null }),+ upsert: async (values: Record<string, unknown>) => {+ mocks.upserts.push(values);+ return { error: null };+ }};return query;},@@ -87,6 +107,11 @@ const sync = (args: SyncOnshapeElementInput = input) =>beforeEach(() => {vi.clearAllMocks();mocks.existingModel = null;+ mocks.modelSource = null;+ mocks.itemModelUploadId = null;+ mocks.upserts = [];+ mocks.client.getCurrentMicroversion.mockResolvedValue("microversion-1");+ mocks.client.createWebhook.mockResolvedValue({ id: "webhook-1" });mocks.assemblerEnabled.mockReturnValue(false);mocks.client.createPartStudioTranslation.mockResolvedValue({ id: "model-t" });mocks.client.createAssemblyTranslation.mockResolvedValue({ id: "model-t" });@@ -110,7 +135,6 @@ beforeEach(() => {url: "https://cad.onshape.test/api/v10/documents/d/export-document/externaldata/file",authorization: "Bearer onshape-token"});- mocks.client.getElementThumbnail.mockResolvedValue(new ArrayBuffer(1));mocks.attach.mockResolvedValue({modelUploadId: "new-model",documentIds: [],@@ -142,13 +166,6 @@ describe("released model exports", () => {});});- it("never attaches a whole-studio thumbnail to a part", async () => {- const result = await sync();- expect(mocks.client.getElementThumbnail).not.toHaveBeenCalled();- expect(mocks.thumbnail).not.toHaveBeenCalled();- expect(result.thumbnailAttached).toBe(false);- });-it.each([undefined, null, "", " ", "part-one,part-two"])("refuses unsafe individual-part selection %s before any export or attach",async (partId) => {@@ -163,7 +180,7 @@ describe("released model exports", () => {);it("keeps whole-assembly exports and forwards their configuration", async () => {- const result = await sync({+ await sync({...input,modelElementKind: "assembly",partId: undefined@@ -175,20 +192,6 @@ describe("released model exports", () => {expect.objectContaining({ configuration: input.configuration }));expect(mocks.client.createPartStudioTranslation).not.toHaveBeenCalled();- // The element thumbnail cannot select a non-default assembly configuration.- expect(mocks.client.getElementThumbnail).not.toHaveBeenCalled();- expect(result.thumbnailAttached).toBe(false);- });-- it("retains the inexpensive element thumbnail for an unconfigured assembly", async () => {- const result = await sync({- ...input,- modelElementKind: "assembly",- partId: undefined,- configuration: undefined- });- expect(mocks.client.getElementThumbnail).toHaveBeenCalledOnce();- expect(result.thumbnailAttached).toBe(true);});it("gives exact-source replays a stable generation, distinct from another part/configuration", async () => {@@ -261,6 +264,140 @@ describe("export economy", () => {});});+describe("unchanged assemblies", () => {+ const workspaceAssembly = {+ ...input,+ modelElementKind: "assembly",+ partId: undefined,+ sourceWvm: "w",+ versionId: "workspace"+ } as const;++ // Pushes once, then points the item at the model that push recorded.+ async function pushOnce() {+ await sync(workspaceAssembly);+ const recorded = mocks.upserts.at(-1)!;+ mocks.modelSource = {+ externalId: recorded.externalId as string,+ metadata: recorded.metadata as { modelUploadId: string }+ };+ mocks.itemModelUploadId = "new-model";+ mocks.existingModel = { id: "new-model", name: "SADDLE.A.step" };+ vi.clearAllMocks();+ }++ it("records the source an assembly's model was exported from", async () => {+ await sync(workspaceAssembly);+ expect(mocks.upserts).toEqual([+ expect.objectContaining({+ entityType: "modelSource",+ entityId: "saddle-item",+ integration: "onshape",+ metadata: { modelUploadId: "new-model" }+ })+ ]);+ });++ it("skips the export when the workspace has not changed", async () => {+ await pushOnce();+ await sync(workspaceAssembly);+ expect(mocks.client.getCurrentMicroversion).toHaveBeenCalledWith(+ "released-document",+ "workspace"+ );+ expect(mocks.client.createAssemblyTranslation).not.toHaveBeenCalled();+ expect(mocks.client.getTranslation).not.toHaveBeenCalled();+ expect(mocks.attach.mock.calls[0]![1]).toMatchObject({+ existingModelId: "new-model"+ });+ });++ it("exports again after any edit to the document", async () => {+ await pushOnce();+ mocks.client.getCurrentMicroversion.mockResolvedValue("microversion-2");+ await sync(workspaceAssembly);+ expect(mocks.client.createAssemblyTranslation).toHaveBeenCalledOnce();+ });++ it("exports again when the item's model was replaced since", async () => {+ await pushOnce();+ mocks.itemModelUploadId = "uploaded-by-hand";+ await sync(workspaceAssembly);+ expect(mocks.client.createAssemblyTranslation).toHaveBeenCalledOnce();+ });++ it("exports when the microversion cannot be read", async () => {+ await pushOnce();+ mocks.client.getCurrentMicroversion.mockRejectedValue(new Error("down"));+ await sync(workspaceAssembly);+ expect(mocks.client.createAssemblyTranslation).toHaveBeenCalledOnce();+ });+});++describe("waiting on a long translation", () => {+ const running = { id: "model-t", requestState: "ACTIVE" };++ it("waits for the translation webhook once the quick polls are spent", async () => {+ for (let i = 0; i < 7; i++) {+ mocks.client.getTranslation.mockResolvedValueOnce(running);+ }+ await sync();+ expect(step.sleep).toHaveBeenCalledTimes(5);+ expect(mocks.client.createWebhook).toHaveBeenCalledWith({+ url: "https://app.carbon.test/api/webhook/onshape/company",+ events: ["onshape.model.translation.complete"],+ documentId: "released-document",+ isTransient: true+ });+ expect(step.waitForEvent).toHaveBeenCalledOnce();+ expect(step.waitForEvent).toHaveBeenCalledWith(+ "element-wait-6",+ expect.objectContaining({+ event: "carbon/onshape-translation-complete",+ timeout: 5 * 60 * 1000+ })+ );+ expect(mocks.client.deleteWebhook).toHaveBeenCalledWith("webhook-1");+ expect(mocks.attach).toHaveBeenCalledOnce();+ });++ it("keeps polling when no webhook can be registered", async () => {+ mocks.client.createWebhook.mockRejectedValue(new Error("unreachable"));+ for (let i = 0; i < 8; i++) {+ mocks.client.getTranslation.mockResolvedValueOnce(running);+ }+ await sync();+ expect(step.waitForEvent).not.toHaveBeenCalled();+ expect(step.sleep).toHaveBeenCalledTimes(8);+ expect(mocks.client.deleteWebhook).not.toHaveBeenCalled();+ });++ it("gives up after an hour, and removes its webhook", async () => {+ mocks.client.getTranslation.mockResolvedValue(running);+ let now = 0;+ const clock = vi.spyOn(Date, "now").mockImplementation(() => {+ now += 10 * 60 * 1000;+ return now;+ });+ try {+ await expect(sync()).rejects.toThrow(/within an hour/);+ } finally {+ clock.mockRestore();+ }+ expect(mocks.client.deleteWebhook).toHaveBeenCalledWith("webhook-1");+ expect(mocks.attach).not.toHaveBeenCalled();+ });++ it("matches only this company's translations", () => {+ expect(translationEventCondition({ companyId: "co" }, ["t1", "t2"])).toBe(+ 'async.data.companyId == "co" && (async.data.translationId == "t1" || async.data.translationId == "t2")'+ );+ expect(translationEventCondition({ companyId: "co" }, ['t" || true'])).toBe(+ null+ );+ });+});+describe("with the assembler", () => {beforeEach(() => {mocks.assemblerEnabled.mockReturnValue(true);diff --git a/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.ts b/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.tsindex 9dd97beb12..acd8f7f02b 100644--- a/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.ts+++ b/packages/jobs/src/inngest/functions/integrations/onshape-sync-element.ts@@ -14,14 +14,14 @@ import {OnshapeAssetTooLargeError} from "@carbon/ee/onshape";import type { OnshapeOAuthIntegrationId } from "@carbon/ee/onshape/integration-id";+import { getAppUrl } from "@carbon/env";import { TEMP_STAGING_BUCKET } from "@carbon/files";-import { getFileSizeLimit } from "@carbon/utils";+import { datetime, getFileSizeLimit } from "@carbon/utils";import type { SupabaseClient } from "@supabase/supabase-js";import { NonRetriableError } from "inngest";import { assemblerEnabled } from "../tasks/assembler-client";import {type AttachOnshapeAssetsResult,- attachModelThumbnail,attachOnshapeAssetsToItem} from "./onshape-attach";import {@@ -34,14 +34,14 @@ import { withRateLimitRetry } from "./onshape-rate-limit";// Export→stage→attach for ONE Onshape element, released or in a workspace// (`runOnshapeElementSync`), and the PDF export of one released drawing.-// Poll-with-backoff (real completions take seconds); no translation.complete-// webhook needed.+// Translations are polled with backoff (most finish in seconds); one still+// running after the quick polls waits on Onshape's translation.complete+// webhook instead (see waitForTranslations).//// Callers (the release-sync and backfill jobs, and onshape-panel-sync) resolve// itemId and the documentId/version-or-workspace/elementId of the geometry,-// including its partId and configuration. Individual-part-// thumbnails come from that selected model after optimization; an element-// thumbnail represents the entire Part Studio and must never be attached to it.+// including its partId and configuration. Thumbnails come from the model+// optimizer, which renders one from the exported model.type CarbonClient = SupabaseClient<Database>;type DocumentSourceType = Database["public"]["Enums"]["documentSourceType"];@@ -66,12 +66,23 @@ export interface SyncOnshapeElementInput {assetBaseName?: string; // filename base (e.g. item part number); falls back to Onshape name}-// About an hour: a large assembly's STEP export can take Onshape far longer-// than a few minutes. Each wait is a step.sleep, so a long budget holds-// nothing; the 30 s cap keeps a slow export's polls off the yearly API quota.-const POLL_MAX_ATTEMPTS = 125;+// Waiting for a translation. Six quick polls (about 40 s of backoff) cover+// most exports at the cost they always had. One still running then registers a+// transient translation.complete webhook and waits for it, polling only every+// WEBHOOK_WAIT_MS as a fallback; without a webhook (a callback Onshape cannot+// reach) it keeps polling every POLL_MAX_DELAY_MS. A large assembly's export+// can take far longer than a few minutes, so the budget is an hour. Every wait+// is a step.sleep or step.waitForEvent, so a long wait holds nothing.+const QUICK_POLLS = 6;const POLL_INITIAL_DELAY_MS = 2000;const POLL_MAX_DELAY_MS = 30000;+const WEBHOOK_WAIT_MS = 5 * 60 * 1000;+const WAIT_BUDGET_MS = 60 * 60 * 1000;+const TRANSLATION_COMPLETE_EVENT = "carbon/onshape-translation-complete";++// An assembly's last export is recorded per item as a mapping row, so a push of+// an unchanged assembly reuses its model instead of exporting it again.+const MODEL_SOURCE_ENTITY_TYPE = "modelSource";// Size caps — the SAME limits Carbon enforces on manual uploads (CadModel.tsx /// document upload), since synced assets land in the same buckets. The raw model@@ -82,7 +93,7 @@ const DOCUMENT_MAX_BYTES = getFileSizeLimit("DOCUMENT_UPLOAD").bytes;/*** Checkpointing for the functions that run this pipeline: consecutive steps- * (existing → translate → first poll; drawings → attach → thumbnail) run in+ * (existing → translate → first poll; drawings → attach) run in* one request instead of a round trip each. Every step here is a short Onshape* call or storage move. `maxRuntime` is far below the ERP's 300 s Vercel limit* because a step that starts at the end of the window gets only the rest of@@ -95,6 +106,10 @@ export const ONSHAPE_CHECKPOINTING = { maxRuntime: "60s" } as const;export type ElementSyncStep = {run: (id: string, fn: () => unknown) => Promise<any>;sleep: (id: string, duration: number) => Promise<unknown>;+ waitForEvent: (+ id: string,+ opts: { event: string; timeout: number; if: string }+ ) => Promise<unknown>;invoke: (id: string,opts: { function: typeof onshapeFetchFunction; data: OnshapeFetchInput }@@ -102,7 +117,6 @@ export type ElementSyncStep = {};export type ElementSyncResult = AttachOnshapeAssetsResult & {- thumbnailAttached: boolean;/** The export is past Carbon's upload limit: a permanent skip, not a fault. */tooLarge?: boolean;};@@ -119,18 +133,20 @@ type FinishedTranslation = {* Export one element's model (and any drawings) from Onshape onto an item, as* resumable steps:*- * 1. `existing` — a released part's model id is known before any export; when- * that model already exists the export is skipped entirely.+ * 1. `existing` — a released part's model id is known before any export, and+ * an assembly's source (version, or workspace microversion) is compared with+ * the one its item's current model came from; when the model already exists+ * the export is skipped entirely.* 2. `translate` — start the model and every drawing translation at once.- * 3. `poll-n` / `sleep-n` — wait for all of them; nothing holds a function- * between polls.+ * 3. `poll-n` / `sleep-n` / `webhook` / `wait-n` — wait for all of them;+ * nothing holds a function between polls.* 4. `fetch` — the assembler copies the STEP straight from Onshape into* temp-staging (`fetch` action), so the export never passes through this* process. With no assembler configured, one step downloads and stages it.* 5. `drawings` — download and attach the PDFs.* 6. `attach` — move the staged STEP to its model key, insert the- * `modelUpload` row (which starts the optimise) and link the item.- * 7. `thumbnail` — Onshape's own thumbnail, for an unconfigured assembly.+ * `modelUpload` row (which starts the optimise, and its thumbnail) and link+ * the item.** A retry resumes at the step that failed, so a late failure never re-runs a* translation (Onshape's API quota is yearly). Step ids are namespaced by@@ -148,11 +164,21 @@ export async function runOnshapeElementSync(const planned: {sourceId: string | null;+ assemblySource?: string | null;existing: { id: string; name: string | null } | null;} = await step.run(`${prefix}-existing`, async () => {assertSelection(input);const sourceId = partSourceId(input);- if (!sourceId) return { sourceId: null, existing: null };+ if (!sourceId) {+ const assemblySource = await assemblySourceKey(carbon, input, label);+ return {+ sourceId: null,+ assemblySource,+ existing: assemblySource+ ? await currentModelFromSource(carbon, input, assemblySource)+ : null+ };+ }const row = await carbon.from("modelUpload").select("id, name")@@ -247,7 +273,6 @@ export async function runOnshapeElementSync(modelUploadId: null,documentIds: [],preservedPriorModelAsDocument: false,- thumbnailAttached: false,tooLarge: true};}@@ -284,8 +309,8 @@ export async function runOnshapeElementSync(const attached: AttachOnshapeAssetsResult = await step.run(`${prefix}-attach`,- () =>- attachOnshapeAssetsToItem(carbon, {+ async () => {+ const result = await attachOnshapeAssetsToItem(carbon, {companyId: input.companyId,createdBy: input.userId,itemId: input.itemId,@@ -299,26 +324,22 @@ export async function runOnshapeElementSync(}}: { existingModelId: planned.existing!.id })- })+ });+ if (staged && planned.assemblySource && result.modelUploadId) {+ await recordModelSource(+ carbon,+ input,+ planned.assemblySource,+ result.modelUploadId+ );+ }+ return result;+ });- // The element-thumbnail endpoint cannot select a part or configuration.- // Keep it only for a new model of an unconfigured assembly. All other- // thumbnails are rendered from the selected model by the optimise itself.- const thumbnailAttached: boolean =- attached.modelUploadId !== null &&- staged !== null &&- input.modelElementKind === "assembly" &&- (!input.configuration || input.configuration.toLowerCase() === "default")- ? await step.run(`${prefix}-thumbnail`, () =>- attachOnshapeThumbnail(carbon, input, attached.modelUploadId!, label)- )- : false;-return {...attached,- documentIds: [...drawingDocumentIds, ...attached.documentIds],- thumbnailAttached+ documentIds: [...drawingDocumentIds, ...attached.documentIds]};}@@ -394,6 +415,132 @@ export function partSourceId(input: SyncOnshapeElementInput): string | null {.slice(0, 40)}`;}+/**+ * What an assembly export is made from: the released version, or the+ * workspace's current microversion, which changes on any edit to the document+ * (an assembly's own microversion would miss an edit to a part it uses). Null+ * for a part (named by partSourceId), or when the microversion cannot be read:+ * the sync then exports as before.+ */+async function assemblySourceKey(+ carbon: CarbonClient,+ input: SyncOnshapeElementInput,+ label: string+): Promise<string | null> {+ if (input.modelElementKind !== "assembly") return null;+ let state = input.versionId;+ if (input.sourceWvm === "w") {+ try {+ const client = await onshapeClient(carbon, input);+ state = await client.getCurrentMicroversion(+ input.documentId,+ input.versionId+ );+ } catch (error) {+ console.warn(+ `onshape sync: could not read the microversion of ${label}; exporting`,+ error+ );+ return null;+ }+ }+ return createHash("sha256")+ .update(+ JSON.stringify([+ "assembly-source-v1",+ input.documentId,+ input.sourceWvm ?? "v",+ state,+ input.modelElementId,+ input.configuration ?? ""+ ])+ )+ .digest("hex");+}++/** The item's current model, when it was exported from `source`. */+async function currentModelFromSource(+ carbon: CarbonClient,+ input: SyncOnshapeElementInput,+ source: string+): Promise<{ id: string; name: string | null } | null> {+ const [mapping, item] = await Promise.all([+ carbon+ .from("externalIntegrationMapping")+ .select("externalId, metadata")+ .eq("entityType", MODEL_SOURCE_ENTITY_TYPE)+ .eq("entityId", input.itemId)+ .eq("integration", modelSourceIntegration(input))+ .eq("companyId", input.companyId)+ .maybeSingle(),+ carbon+ .from("item")+ .select("modelUploadId")+ .eq("id", input.itemId)+ .eq("companyId", input.companyId)+ .maybeSingle()+ ]);+ if (mapping.error || item.error) {+ throw new Error(+ `model source lookup failed: ${(mapping.error ?? item.error)!.message}`+ );+ }+ const modelUploadId = (+ mapping.data?.metadata as { modelUploadId?: unknown } | null+ )?.modelUploadId;+ if (+ mapping.data?.externalId !== source ||+ typeof modelUploadId !== "string" ||+ item.data?.modelUploadId !== modelUploadId+ ) {+ return null;+ }+ const model = await carbon+ .from("modelUpload")+ .select("id, name")+ .eq("id", modelUploadId)+ .eq("companyId", input.companyId)+ .maybeSingle();+ if (model.error) {+ throw new Error(`existing model lookup failed: ${model.error.message}`);+ }+ return model.data ? { id: model.data.id, name: model.data.name } : null;+}++/** Remember which source the item's new model came from. Only an+ * optimization: a failed write means the next push exports again. */+async function recordModelSource(+ carbon: CarbonClient,+ input: SyncOnshapeElementInput,+ source: string,+ modelUploadId: string+): Promise<void> {+ const written = await carbon.from("externalIntegrationMapping").upsert(+ {+ entityType: MODEL_SOURCE_ENTITY_TYPE,+ entityId: input.itemId,+ integration: modelSourceIntegration(input),+ externalId: source,+ allowDuplicateExternalId: true,+ metadata: { modelUploadId },+ companyId: input.companyId,+ createdBy: input.userId,+ updatedAt: datetime.timestamp()+ },+ { onConflict: "entityType,entityId,integration,companyId" }+ );+ if (written.error) {+ console.warn(+ `onshape sync: could not record the model source of ${input.itemId}`,+ written.error+ );+ }+}++function modelSourceIntegration(input: OnshapeCredentials): string {+ return input.integrationId ?? "onshape";+}+function startModelTranslation(client: OnshapeClient,input: SyncOnshapeElementInput@@ -419,47 +566,146 @@ function startModelTranslation();}-/** Poll every translation together until all are done, sleeping (as a step,- * holding nothing) between polls. A failed translation fails the sync. */+/**+ * Wait for every translation together until all are done. The first+ * QUICK_POLLS polls back off from 2 s. A translation still running after them+ * registers a transient, document-scoped translation.complete webhook, polls+ * once more (one may have finished before the webhook existed), then waits for+ * the webhook with a poll every WEBHOOK_WAIT_MS. The webhook only wakes the run:+ * a poll reads the result, so a forged event can do no more than cause a poll.+ * A failed translation, or an hour without finishing, fails the sync.+ */async function waitForTranslations(- step: Pick<ElementSyncStep, "run" | "sleep">,+ step: Pick<ElementSyncStep, "run" | "sleep" | "waitForEvent">,carbon: CarbonClient,- input: OnshapeCredentials,+ input: OnshapeCredentials & { documentId: string },label: string,prefix: string,ids: string[]): Promise<Record<string, FinishedTranslation>> {const finished: Record<string, FinishedTranslation> = {};let delay = POLL_INITIAL_DELAY_MS;- for (let attempt = 0; ; attempt++) {- const waiting = ids.filter((id) => !finished[id]);- if (waiting.length === 0) return finished;- if (attempt >= POLL_MAX_ATTEMPTS) {- throw new NonRetriableError(- `Onshape translations ${waiting.join(", ")} did not finish after ${POLL_MAX_ATTEMPTS} polls`+ let startedAt: number | null = null;+ // undefined: not tried yet; null: tried, and none could be registered.+ let webhookId: string | null | undefined;+ try {+ for (let attempt = 0; ; attempt++) {+ const waiting = ids.filter((id) => !finished[id]);+ if (waiting.length === 0) return finished;+ const poll: { at: number; translations: (FinishedTranslation | null)[] } =+ await step.run(`${prefix}-poll-${attempt}`, () =>+ withRateLimitRetry(async () => {+ const client = await onshapeClient(carbon, input);+ const translations = await Promise.all(+ waiting.map(async (id) =>+ finishedTranslation(await client.getTranslation(id))+ )+ );+ return { at: Date.now(), translations };+ }, `poll ${label}`)+ );+ for (const translation of poll.translations) {+ if (translation) finished[translation.id] = translation;+ }+ if (ids.every((id) => finished[id])) return finished;++ startedAt ??= poll.at;+ if (poll.at - startedAt >= WAIT_BUDGET_MS) {+ throw new NonRetriableError(+ `Onshape translations ${ids.filter((id) => !finished[id]).join(", ")} did not finish within an hour`+ );+ }++ if (attempt + 1 >= QUICK_POLLS && webhookId === undefined) {+ webhookId = await step.run(`${prefix}-webhook`, () =>+ registerTranslationWebhook(carbon, input, label)+ );+ if (webhookId) continue;+ }++ const condition = webhookId+ ? translationEventCondition(input, ids)+ : null;+ if (condition) {+ await step.waitForEvent(`${prefix}-wait-${attempt}`, {+ event: TRANSLATION_COMPLETE_EVENT,+ timeout: WEBHOOK_WAIT_MS,+ if: condition+ });+ } else {+ await step.sleep(`${prefix}-sleep-${attempt}`, delay);+ delay = Math.min(delay * 1.5, POLL_MAX_DELAY_MS);+ }+ }+ } finally {+ if (webhookId) {+ const id = webhookId;+ await step.run(`${prefix}-unwebhook`, () =>+ deleteTranslationWebhook(carbon, input, id, label));}- const polled: (FinishedTranslation | null)[] = await step.run(- `${prefix}-poll-${attempt}`,- () =>- withRateLimitRetry(async () => {- const client = await onshapeClient(carbon, input);- return Promise.all(- waiting.map(async (id) =>- finishedTranslation(await client.getTranslation(id))- )- );- }, `poll ${label}`)+ }+}++/** Register a webhook for this document's translation.complete events.+ * Never throws: without one the sync keeps polling. */+async function registerTranslationWebhook(+ carbon: CarbonClient,+ input: OnshapeCredentials & { documentId: string },+ label: string+): Promise<string | null> {+ try {+ const client = await onshapeClient(carbon, input);+ const webhook = await client.createWebhook({+ url: `${getAppUrl()}/api/webhook/onshape/${input.companyId}`,+ events: ["onshape.model.translation.complete"],+ documentId: input.documentId,+ isTransient: true+ });+ return webhook.id;+ } catch (error) {+ console.warn(+ `onshape sync: no translation webhook for ${label}; polling`,+ error);- for (const translation of polled) {- if (translation) finished[translation.id] = translation;- }- if (ids.every((id) => finished[id])) return finished;- await step.sleep(`${prefix}-sleep-${attempt}`, delay);- delay = Math.min(delay * 1.5, POLL_MAX_DELAY_MS);+ return null;}}+/** Best-effort: Onshape removes a transient webhook on its own when idle. */+async function deleteTranslationWebhook(+ carbon: CarbonClient,+ input: OnshapeCredentials,+ webhookId: string,+ label: string+): Promise<void> {+ try {+ const client = await onshapeClient(carbon, input);+ await client.deleteWebhook(webhookId);+ } catch (error) {+ console.warn(+ `onshape sync: could not delete the translation webhook for ${label}`,+ error+ );+ }+}++/** The `if` expression matching this company's translations. Null (poll+ * instead) for an id that is not plain alphanumeric, since it is interpolated. */+export function translationEventCondition(+ input: Pick<OnshapeCredentials, "companyId">,+ ids: string[]+): string | null {+ const safe = /^[A-Za-z0-9_-]+$/;+ if (!safe.test(input.companyId) || !ids.every((id) => safe.test(id))) {+ return null;+ }+ const translations = ids+ .map((id) => `async.data.translationId == "${id}"`)+ .join(" || ");+ return `async.data.companyId == "${input.companyId}" && (${translations})`;+}+function finishedTranslation(translation: OnshapeTranslation): FinishedTranslation | null {@@ -556,36 +802,6 @@ async function downloadPdf(}}-async function attachOnshapeThumbnail(- carbon: CarbonClient,- input: SyncOnshapeElementInput,- modelUploadId: string,- label: string-): Promise<boolean> {- try {- const client = await onshapeClient(carbon, input);- const thumbnail = await client.getElementThumbnail(- input.documentId,- input.versionId,- input.modelElementId,- "300x300",- input.sourceWvm ?? "v"- );- await attachModelThumbnail(carbon, {- companyId: input.companyId,- modelUploadId,- pngBytes: new Uint8Array(thumbnail)- });- return true;- } catch (thumbnailError) {- console.warn(- `onshape sync: Onshape thumbnail fetch failed for ${label}; the optimise renders one`,- thumbnailError- );- return false;- }-}-export interface SyncOnshapeDrawingInput {companyId: string;userId: string; // Onshape integration installer (auth + audit)@@ -606,14 +822,14 @@ export type DrawingSyncResult = AttachOnshapeAssetsResult & {// Export ONE released Onshape DRAWING element as a PDF and attach it as a document// on the given Carbon item, as resumable steps like the element sync's:-// `translate`, `poll-n` / `sleep-n` (holding no function between polls), then+// `translate`, the translation wait (holding no function in between), then// `attach` (download the PDF and record it). Drawings are released as their own// elements (DRW-xxxx, elementType 2) separate from the model, so the caller// resolves which item the drawing belongs to (by shared part number) and passes// it here. No model is touched — only a PDF document is added/updated// (idempotent via the attach helper's replace-not-append rule).export async function runOnshapeDrawingSync(- step: Pick<ElementSyncStep, "run" | "sleep">,+ step: Pick<ElementSyncStep, "run" | "sleep" | "waitForEvent">,carbon: CarbonClient,input: SyncOnshapeDrawingInput,prefix: stringdiff --git a/packages/jobs/src/inngest/functions/tasks/model-optimize.ts b/packages/jobs/src/inngest/functions/tasks/model-optimize.tsindex f124676b04..cc5f58e1b5 100644--- a/packages/jobs/src/inngest/functions/tasks/model-optimize.ts+++ b/packages/jobs/src/inngest/functions/tasks/model-optimize.ts@@ -213,8 +213,8 @@ export const modelOptimizeFunction = inngest.createFunction(const stats: Json = optimize.stats;await step.run("persist", async () => {- // Read the thumbnail now, not at queue time: an Onshape sync can attach- // its own while the job runs, and that one is superseded too.+ // Read the thumbnail now, not at queue time: an earlier run's thumbnail+ // is superseded too.const superseded = outputs.thumbnail? (await getModelUpload(companyId, modelUploadId))?.thumbnailPath: null;diff --git a/packages/lib/src/events.ts b/packages/lib/src/events.tsindex 80cece16e6..7f40f161a5 100644--- a/packages/lib/src/events.ts+++ b/packages/lib/src/events.ts@@ -739,6 +739,15 @@ export type Events = {};};+ // Onshape's translation.complete webhook, forwarded: wakes an element sync+ // waiting on the translation (matched on companyId + translationId)+ "carbon/onshape-translation-complete": {+ data: {+ companyId: string;+ translationId: string;+ };+ };+// Onshape released-asset backfill / reconcile"carbon/onshape-backfill": {data: {