Jak używać
- Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
- W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
- Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-examplesPrzed rozpoczęciem
- Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
- Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.
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 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.
