skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
factorialco/factorial-code-skills444 installs

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-examples
view source ↗

Is 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 systemreferences/integration-acme.md
An import of external data into Factorial (payroll results, expenses, …) the customer can follow row by rowreferences/integration-inbound.md
A custom app with install/uninstall lifecycle: setup form, webhooks, schedulesreferences/custom-app-linear.md
A one-shot automation: export/report generation, file processingreferences/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 tablereferences/pairing-table.md

Pattern index

Where to find a specific pattern, regardless of which app you build:

PatternReference
An outbound sync: a vertical (CompensationsSync, …) composed with a delivery mode in modules/sync, run by the inherited sync processintegration-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 / processBatchintegration-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 codecustom-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 keycustom-app-linear
Dynamic form dropdowns via preRenderProcess + #/variablescustom-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 stateoauth-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 mappairing-table
Creating webhooks + schedules at install, recording them for uninstallcustom-app-linear
Polling with a datastore cursor + idempotency (dedup map, or vendor upsert when available)custom-app-linear
Best-effort uninstall / teardowncustom-app-linear
Storage upload + signed download URL + email with fcode.sendMailutility-processes
Reading a form-uploaded file from Storageutility-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:

ModuleFromProvides
factorial-sdkbase-appcreateFactorialClient() — authenticated @factorialco/api-client / factorial-api-client instance
factorial-utilsbase-appgetCompanyId(), setupWebhook(), listWebhookSubscriptions(), deleteWebhookSubscription()
fcode-formsbase-appForm-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-helperbase-appbrandedHtml() for styled email bodies
error-handlerbase-appShared error handling
record-sync + verticals (compensations-sync, expenses-sync, leaves-sync, …) + modes (api-sync, file-sync)base-integration-appThe outbound sync framework; the integration composes one vertical with one mode in its sync module, run by the inherited sync process
inbound-record-syncbase-integration-appInboundRecordSync base class for imports into Factorial tracked as a sync run
inbound-syncbase-integration-appInboundSyncClient: 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.

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>