App Store

Purpose

The App Store is Cal.diy's pluggable integration system. Users browse the in-product gallery, click "Install", complete an OAuth flow, and the integration's adapter starts being called for every booking. There are 111 integrations covering calendars, conferencing, payments, CRMs, analytics, automation, AI receptionists, and messaging.

This page is a feature view of the App Store flow. For the directory layout and authoring CLI, see packages/app-store.

Install flow

sequenceDiagram
    participant User
    participant AppsPage as apps/web/app/.../apps
    participant InstallBtn as InstallAppButton
    participant OAuthRoute as <app>/api/add (OAuth start)
    participant Vendor
    participant Callback as <app>/api/callback
    participant Cred as features/credentials
    participant DB

    User->>AppsPage: browse
    AppsPage-->>User: list (apps.metadata.generated.ts)
    User->>InstallBtn: click "Install"
    InstallBtn->>OAuthRoute: GET /apps/<slug>/setup
    OAuthRoute->>Vendor: redirect to OAuth consent
    Vendor-->>Callback: redirect with code
    Callback->>Vendor: exchange code for tokens
    Callback->>Cred: encrypt + save in Credential table
    Cred->>DB: INSERT Credential (key encrypted with CALENDSO_ENCRYPTION_KEY)
    Callback-->>User: redirect to /apps/installed/<category>

Each integration follows the same <app>/api/ pattern. The OAuth start route (/apps/<slug>/setup or similar) and callback (/api/integrations/<slug>/callback) are wired through the generated registries.

Per-event-type configuration

Many apps expose per-event-type configuration cards (e.g., "Charge $30 deposit when booked", "Add a tracking pixel"). The card components live in each app's components/EventTypeAppCard.tsx and are aggregated by the App Store CLI into apps.browser.generated.tsx. The Zod schema for each card lives in apps.schemas.generated.ts.

To enable an app for a specific event type, the user toggles it in the Apps tab of the event-type editor. The setting is stored in the EventTypeAppMetadata JSON column on EventType.

Credential lifecycle

• Install — Credential row created with encrypted key JSON.
• Refresh — adapters call BaseCalendarService.getRefreshedAccessToken() (or equivalent for video / payment / CRM) which re-encrypts and writes back.
• Revocation — uninstall flow deletes the Credential row. Some apps also revoke the third-party token; others rely on TTL.
• Delegation — system-wide credentials (e.g., Google Workspace domain-wide delegation) live in a separate flow handled by packages/lib/delegationCredential.ts and packages/features/credentials.

AGENTS.md is explicit: never select credential.key into anything that flows to a client.

App categories and adapter shapes

Category	Interface	Where the interface lives
Calendar	Calendar	packages/types/Calendar.d.ts
Video / conferencing	VideoApiAdapter	packages/types/VideoApiAdapter.d.ts
Payment	PaymentService	packages/types/payment.d.ts
CRM	CrmService	packages/features/crmManager
Analytics	AnalyticsService	per-app under packages/app-store/<analytics-app>/lib/
Automation / messaging / other	App-specific handlers	per-app api/

Categories are declared in each app's config.json (categories: ["calendar"], ["payment"], ...). The App Store CLI uses the categories to generate per-category registries (calendar.services.generated.ts, etc.).

Integration points

• Bookings — calendar / video / payment / CRM adapters are pulled into the booking pipeline by EventManager and the post-booking dispatchers.
• Webhooks — apps can register listeners for booking events through the standard Webhook model.
• Admin UI — apps/web/app/(use-page-wrapper)/(main-nav)/apps/ shows the gallery and installed-apps list.

Entry points for modification

• See packages/app-store for authoring instructions.
• For credential or install-flow changes, edit packages/features/credentials and the per-app api/ directory.
• For the admin UI, edit apps/web/modules/apps/.

Related pages

• packages/app-store
• Calendars
• Bookings
• Primitives → Credential