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 calls fcode.oauth.start(), the platform runs both redirect legs and invokes the completion process, which exchanges the code and 302s to the SDK callback page; onComplete: "reload" renders the connected state |
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.