fcode-examples
Reference implementations for Factorial Code — a complete marketplace payroll integration, an inbound import tracked as a sync run, a custom app with full install/uninstall lifecycle, an OAuth account connection from a form, a pairing table mapping Factorial records to another system's, 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.
How do I install this agent skill?
npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-examplesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a comprehensive library of reference implementations and best-practice patterns for building integrations and automations on the Factorial Code platform. It covers common architectural patterns such as OAuth flows, record pairing, and data synchronization while emphasizing secure credential management and input validation.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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 |
| An import of external data into Factorial (payroll results, expenses, …) the customer can follow row by row | references/integration-inbound.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 |
| A settings form that maps many Factorial records to another system's (accounts, departments, codes) as one reviewable table | references/pairing-table.md |
Pattern index
Where to find a specific pattern, regardless of which app you build:
| Pattern | Reference |
|---|---|
An outbound sync: a vertical (CompensationsSync, …) composed with a delivery mode in modules/sync, run by the inherited sync process | integration-acme |
Per-item API push (ApiSync) vs aggregate-to-file delivery (FileSync) | integration-acme |
Validating records before an export (validate(item)) | integration-acme |
Reporting per-item sync status (success / invalid / failed) | integration-acme, integration-inbound |
Extending the inbound-record-sync base class (InboundRecordSync): fetchItems + process / processBatch | integration-inbound |
Opening a sync run in a form and importing it in an async worker (sync_run hand-off) | integration-inbound |
Aborting open sync runs on uninstall (abortOpenRunsForIntegration) | integration-inbound |
| Webhook entry point authenticated by the platform, not in process code | custom-app-linear |
Activating webhook / form triggers in metadata.json, and protecting the webhook (webhook.authMode + the workspace webhookAuth, the reserved install / settings slugs) | custom-app-linear |
Multi-step setup flow across processes (process steps in ui:steps), with a second form built from data fetched with the first step's key | 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 |
Pairing table (ui:field: "pairing"): pre-render builds one row per Factorial record with the vendor's records as choices, the stored pair as default, a name match as x-fcode-suggestion and x-fcode-in-use; the settings process validates and stores the flat map | pairing-table |
| 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(), … — never fed a directory that grows with the company (employees, projects, cost centers); small lists such as teams or legal entities are fine (see fcode-json-schema §Gotchas) |
mail-helper | base-app | brandedHtml() for styled email bodies |
error-handler | base-app | Shared error handling |
record-sync + verticals (compensations-sync, expenses-sync, leaves-sync, …) + modes (api-sync, file-sync) | base-integration-app | The outbound sync framework; the integration composes one vertical with one mode in its sync module, run by the inherited sync process |
inbound-record-sync | base-integration-app | InboundRecordSync base class for imports into Factorial tracked as a sync run |
inbound-sync | base-integration-app | InboundSyncClient: open, declare, report, finish and abort sync runs, list an integration's runs |
Integration apps inherit base-integration-app (which inherits base-app);
custom apps inherit base-app directly. An App that only imports into Factorial
adds base-integration-app-<lang> to its parentTeams to get the inbound
modules (see integration-inbound).
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/factorialco/factorial-code-skills/fcode-examples">View fcode-examples on skillZs</a>