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.

4.6 KB
Raw Blame

@carbon/lib

Shared server utilities — event system, Inngest client, trigger dispatch, SMTP email, Slack messaging, and Twenty CRM.

Always

  • Use trigger(taskId, payload) for dispatching background jobs — typed helper that maps task IDs to Inngest event names; drop-in replacement for old tasks.trigger()
  • Add new events to the Events type in events.ts — every Inngest event needs a typed payload here
  • Add new task mappings to taskToEvent in trigger.ts — maps human-readable task IDs to carbon/* event names
  • carbon/send-push has no task on purpose — only the notify job sends it (step.sendEvent), because browser push mirrors the in-app row; app code never pushes directly
  • Guard external calls — email.server.ts no-ops when no SMTP config is set (SMTP_*, with a legacy RESEND_API_KEY fallback via smtp.resend.com); slack.server.ts skips sends on localhost
  • Add new work events to src/telemetry/events.ts — the WorkEvents type map is the contract; captureWorkEvent is typed off it, so an unlisted name will not compile

Ask First

  • Adding new Inngest event types (coordinate with packages/jobs/ function registration)
  • Changing the Inngest client ID ("carbon")

Never

  • Send emails or Slack messages directly from app routes — dispatch via trigger("send-email", ...) or trigger("send-slack", ...)
  • Import this package on the client — all exports are server-only (.server.ts convention)

Validation Commands

pnpm --filter @carbon/lib typecheck   # tsc --noEmit
pnpm --filter @carbon/lib test        # vitest run

Key Patterns

  • Inngest client: src/inngest/client.ts — singleton new Inngest({ id: "carbon", logger: createInngestLogger() }). The logger (from @carbon/logger/inngest) routes every job's ctx.logger into LogTape under the ["carbon","jobs"] category.
  • Trigger helper: trigger(taskId, payload) / batchTrigger(taskId, items) — typed dispatch
  • Events: src/events.ts — full Events type map (carbon/notify, carbon/send-email, carbon/send-slack, etc.)
  • Exports: ./events, ./inngest, ./trigger, ./telemetry, ./email.server (SMTP sendEmail, DEFAULT_FROM, EMAIL_DOMAIN), ./resend.server (marketing contacts only), ./slack.server, ./twenty.server, ./party-contact + ./party-contact.server (checkPartyContactRequirement — the require-a-contact-and-location rule, shared by the ERP's post routes and the invoice automation job; the ERP's settings/party-contact*.ts re-export it), ./sales-invoice-document.server (loadSalesInvoiceDocument + renderSalesInvoicePdf — one read of a sales invoice for its PDF and email, shared by the ERP PDF route, the manual post route and the invoice automation job; a pure function of a SupabaseClient, no request)
  • Work-event telemetry: src/telemetry/ — trackWorkEvent() records work done on the platform (jobs released, quotes sent, POs issued) as a PostHog event, over a bare fetch with no SDK. Three rules it must keep: it never throws into the caller (same contract as raiseMoment — a lost measurement beats a failed action), the event uuid is deterministic from (companyId, event, recordId, discriminator) so a retry collapses instead of double-counting, and it emits only when POSTHOG_PROJECT_PUBLIC_KEY is set and CONTROLLED_ENVIRONMENT is off — the same gate apps/erp/app/entry.client.tsx:31 puts on the browser SDK. Deliberately not named .server: MES service files are in the client graph (React components import their types), so a .server specifier fails the React Router build — which is also why the hash is plain TypeScript rather than node:crypto. See src/telemetry/README.md for the coverage gaps and VERIFICATION.md for the post-deploy runbook
  • Workflow moments: src/workflows/raise-moment.ts — raiseMoment() announces a business moment (as opposed to a row change) to the workflow matcher. Two rules it must keep: it never throws into the caller (a failed announcement must not fail the business operation that raised it — it logs instead), and the momentId it mints is used twice, as the Inngest event id and as the matcher's sourceEventId, which is what makes a redelivery idempotent. See .claude/rules/workflow-matcher.md

Cross-References

  • packages/notifications/ — NotificationEvent / NotificationDestination enums used in event payloads
  • packages/jobs/ — Inngest function implementations that consume these events
  • packages/env/ — SLACK_BOT_TOKEN, SMTP_*, and other env vars
  • packages/logger/ — createInngestLogger() wired as the Inngest client's logger