Factorial Code — reference implementations
Worked, production-shaped examples of complete Factorial Code apps. Each
reference in references/ walks through one real sample: its architecture,
the key code, and how to adapt it. They complement the rule-focused skills
(fcode-core-concepts, fcode-javascript/fcode-python, fcode-json-schema,
fcode-forms, fcode-cli): those tell you how to write fcode code, this one
shows what a finished app looks like.
Adapt, don't paste. These are patterns to rebuild for the user's actual
vendor/requirements — rename slugs, variables, and mappings; drop what the use
case doesn't need.
Which reference to read
| You are building… |
Read |
| A marketplace integration that delivers Factorial data (payroll, leaves, …) to an external system |
references/integration-acme.md |
| A custom app with install/uninstall lifecycle: setup form, webhooks, schedules |
references/custom-app-linear.md |
| A one-shot automation: export/report generation, file processing |
references/utility-processes.md |
| An app that connects a third-party account through OAuth from a form (no pasted API tokens) |
references/oauth-connect.md |
Pattern index
Where to find a specific pattern, regardless of which app you build:
| Pattern |
Reference |
Extending the outbound-sync base class (OutboundSync) |
integration-acme |
| Per-item API push vs aggregate-to-file delivery |
integration-acme |
Reporting per-item sync status (success / invalid / failed) |
integration-acme |
| Webhook entry point authenticated by the platform, not in process code |
integration-acme, custom-app-linear |
Activating webhook / form triggers in metadata.json, and protecting the webhook (webhook.authMode + the workspace webhookAuth, marketplace appRole) |
integration-acme, custom-app-linear |
Multi-step setup form (nextProcessId chaining) |
custom-app-linear |
Dynamic form dropdowns via preRenderProcess + #/variables |
custom-app-linear |
OAuth connect button in a form (ui:widget: "oauth"): pre-render mints the state + authorize URL, public callback webhook exchanges the code and 302s to the SDK callback page, onComplete: "reload" renders the connected state |
oauth-connect |
Verifying a signed, single-use state on a public (authMode: NONE) webhook |
oauth-connect |
| Creating webhooks + schedules at install, recording them for uninstall |
custom-app-linear |
| Polling with a datastore cursor + idempotency (dedup map, or vendor upsert when available) |
custom-app-linear |
| Best-effort uninstall / teardown |
custom-app-linear |
Storage upload + signed download URL + email with fcode.sendMail |
utility-processes |
| Reading a form-uploaded file from Storage |
utility-processes |
Calling the Factorial API SDK (factorial-sdk module) |
all three |
The base workspaces (always present — never recreate)
Every fcode App workspace inherits shared modules from the base apps. Import
them with fcode.import(...) / fcode.import_module(...); do not
reimplement them:
| Module |
From |
Provides |
factorial-sdk |
base-app |
createFactorialClient() — authenticated @factorialco/api-client / factorial-api-client instance |
factorial-utils |
base-app |
getCompanyId(), setupWebhook(), listWebhookSubscriptions(), deleteWebhookSubscription() |
fcode-forms |
base-app |
Form-schema builders: selectField(), toOptions(), … |
mail-helper |
base-app |
brandedHtml() for styled email bodies |
error-handler |
base-app |
Shared error handling |
outbound-sync |
base-integration-app |
OutboundSync base class for marketplace syncs |
Integration apps inherit base-integration-app (which inherits base-app);
custom apps inherit base-app directly.
Note: the fcode-forms module above (form-schema builders you
fcode.import) is unrelated to the fcode-forms skill, which documents
embedding forms on webpages.
The references keep code compact and omit routine logging; real
implementations should log verbosely through the shared fcode-logs module
(see fcode-javascript / fcode-python).
Language variants
Every sample exists in JavaScript (Node.js v22) and Python (3.13) with
identical structure and behavior. References show JavaScript; the Python
variant differs only in idiom (main.py, fcode.import_module,
fcode.send_mail, snake_case) — see fcode-python.
1---2name: fcode-examples3description: Reference implementations for Factorial Code — a complete marketplace payroll integration, a custom app with full install/uninstall lifecycle, an OAuth account connection from a form, and utility processes. Use when building a Factorial Code (fcode) integration, custom app, or automation end to end and you want a proven, working pattern to adapt — read the matching reference before writing code.4license: MIT5---67# Factorial Code — reference implementations89Worked, production-shaped examples of complete Factorial Code apps. Each10reference in `references/` walks through one real sample: its architecture,11the key code, and how to adapt it. They complement the rule-focused skills12(`fcode-core-concepts`, `fcode-javascript`/`fcode-python`, `fcode-json-schema`,13`fcode-forms`, `fcode-cli`): those tell you *how to write fcode code*, this one14shows *what a finished app looks like*.1516**Adapt, don't paste.** These are patterns to rebuild for the user's actual17vendor/requirements — rename slugs, variables, and mappings; drop what the use18case doesn't need.1920## Which reference to read2122| You are building… | Read |23|---|---|24| A marketplace integration that delivers Factorial data (payroll, leaves, …) to an external system | [`references/integration-acme.md`](references/integration-acme.md) |25| A custom app with install/uninstall lifecycle: setup form, webhooks, schedules | [`references/custom-app-linear.md`](references/custom-app-linear.md) |26| A one-shot automation: export/report generation, file processing | [`references/utility-processes.md`](references/utility-processes.md) |27| An app that connects a third-party account through OAuth from a form (no pasted API tokens) | [`references/oauth-connect.md`](references/oauth-connect.md) |2829## Pattern index3031Where to find a specific pattern, regardless of which app you build:3233| Pattern | Reference |34|---|---|35| Extending the `outbound-sync` base class (`OutboundSync`) | integration-acme |36| Per-item API push vs aggregate-to-file delivery | integration-acme |37| Reporting per-item sync status (`success` / `invalid` / `failed`) | integration-acme |38| Webhook entry point authenticated by the platform, not in process code | integration-acme, custom-app-linear |39| Activating webhook / form triggers in `metadata.json`, and protecting the webhook (`webhook.authMode` + the workspace `webhookAuth`, marketplace `appRole`) | integration-acme, custom-app-linear |40| Multi-step setup form (`nextProcessId` chaining) | custom-app-linear |41| Dynamic form dropdowns via `preRenderProcess` + `#/variables` | custom-app-linear |42| OAuth connect button in a form (`ui:widget: "oauth"`): pre-render mints the `state` + authorize URL, public callback webhook exchanges the code and 302s to the SDK callback page, `onComplete: "reload"` renders the connected state | oauth-connect |43| Verifying a signed, single-use `state` on a public (`authMode: NONE`) webhook | oauth-connect |44| Creating webhooks + schedules at install, recording them for uninstall | custom-app-linear |45| Polling with a datastore cursor + idempotency (dedup map, or vendor upsert when available) | custom-app-linear |46| Best-effort uninstall / teardown | custom-app-linear |47| Storage upload + signed download URL + email with `fcode.sendMail` | utility-processes |48| Reading a form-uploaded file from Storage | utility-processes |49| Calling the Factorial API SDK (`factorial-sdk` module) | all three |5051## The base workspaces (always present — never recreate)5253Every fcode App workspace inherits shared modules from the base apps. Import54them with `fcode.import(...)` / `fcode.import_module(...)`; do **not**55reimplement them:5657| Module | From | Provides |58|---|---|---|59| `factorial-sdk` | base-app | `createFactorialClient()` — authenticated `@factorialco/api-client` / `factorial-api-client` instance |60| `factorial-utils` | base-app | `getCompanyId()`, `setupWebhook()`, `listWebhookSubscriptions()`, `deleteWebhookSubscription()` |61| `fcode-forms` | base-app | Form-schema builders: `selectField()`, `toOptions()`, … |62| `mail-helper` | base-app | `brandedHtml()` for styled email bodies |63| `error-handler` | base-app | Shared error handling |64| `outbound-sync` | base-integration-app | `OutboundSync` base class for marketplace syncs |6566Integration apps inherit base-integration-app (which inherits base-app);67custom apps inherit base-app directly.6869Note: the `fcode-forms` **module** above (form-schema builders you70`fcode.import`) is unrelated to the `fcode-forms` **skill**, which documents71embedding forms on webpages.7273The references keep code compact and omit routine logging; real74implementations should log verbosely through the shared `fcode-logs` module75(see `fcode-javascript` / `fcode-python`).7677## Language variants7879Every sample exists in JavaScript (Node.js v22) and Python (3.13) with80identical structure and behavior. References show JavaScript; the Python81variant differs only in idiom (`main.py`, `fcode.import_module`,82`fcode.send_mail`, snake_case) — see `fcode-python`.83
factorialco