Sample apps & shared foundation

You never start from a blank file. Every App inherits a shared foundation through workspace inheritance, and the AI skills your agent works with carry examples and references drawn from complete reference samples.

JavaScript or Python

You pick a language — JavaScript (Node.js v22) or Python (3.13) — when you request your App. Each workspace below exists in both languages; your App inherits the matching variant and uses the matching SDK. The split is an implementation detail — these docs refer to workspaces by their base name.

The shared foundation (base-*)

These workspaces are inherited as read-only — their modules and processes are available via fcode.import(...) without copying any code.

base-app

The foundation inherited by every App. It provides:

• FactorialClient — the production-grade Factorial API client (pagination, OAuth, and error handling built in).
• fc-utils and factorial-utils — helpers including checkWebhookChallenge and setupWebhook.
• A shared error handler and a mail-helper for email delivery.
• Utility processes such as datastore-inspector and workspace-error-handler.

base-integration-app

The base integrations workspace. It inherits base-app and adds the generic OutboundSync orchestrator module and the sync process scaffold that concrete integrations extend — so each integration only implements its own mapping logic. It is the foundation for the integrations framework.

The samples

Two complete reference Apps — one per App type — inform the patterns the skills teach your agent. They reach your agent through the fcode-examples skill, whose references walk through each sample’s architecture, processes, and the patterns worth adapting.

Custom app sample

A reference custom automation that inherits base-app. It includes a multi-step Linear integration (linear-setup, linear-setup-mapping, linear-projects-poll, linear-users-push, linear-uninstall) plus standalone utilities that show the breadth of what an App can do:

• timeoffs-csv-export — generate a CSV from data fetched through the Factorial API.
• xml-employee-documents — parse and produce XML documents.
• Multi-step forms, scheduled polling, webhook-triggered pushes, and email notification patterns.

This is the reference for a bespoke automation — form-driven workflows, Factorial API jobs, report generation, email — rather than a marketplace integration. Walkthroughs: custom app lifecycle and utility processes.

Integration app sample

A vendor-neutral marketplace integration for an invented “Acme Payroll”, built on base-integration-app. It handles compensations and leaves and ships two delivery flavors, selected by a one-line import in processes/sync/:

• sync-file — aggregate items into a CSV and upload a single file (uploadOutput / upload_output).
• sync-api — push each item to the external system’s HTTP API (via the acme-client module).

This is the reference when building on the integrations framework — an integration replaces the Acme specifics with the target system’s data model. Walkthrough: marketplace integration.

Built on the SDKs

The samples — and your App — rely on the published Factorial API SDKs for all Factorial API access, rather than hand-rolled HTTP calls: @factorialco/api-client for JavaScript and factorial-api-client for Python. See factorialco/factorial-api-sdks.