# Integration Hub

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 149  
**Tier:** All tiers (view); per integration varies  
**Depends on:** `settings-module`, `invoices-adapters`, `calendar-module`, `payment-gateway-adapters`, `custom-smtp-email-whitelabel`, `contractor-payouts`, `foundation-auth-rbac`  
**Referenced by:** `settings-module`

---

## Overview

Spec 25 (`settings-module`) mentions "integrations hub (app-store layout)" but provides no detail. Individual integration specs (calendar OAuth, invoice adapters, payment gateways, SMTP) each define their own settings routes but do not provide a unified discovery surface. This spec defines the `/settings/integrations` hub — the central page where users can discover, connect, and manage all integrations.

### OS route titles

OS and mobile frames MUST title `/settings/integrations` "Integrations"; invoicing, accounting, Make, Zapier, and webhook routes use concise integration titles. A webhook detail route MUST title as "Webhook {id}".

Rationale: preserve deep-link wayfinding inside the settings app frame.

---

## Route

`/settings/integrations` — accessible from the settings navigation.

---

## Page Layout

```
┌──────────────────────────────────────────────────────────────┐
│  Settings > Integrations                                     │
│                                                              │
│  [Search integrations...]                                    │
│                                                              │
│  Connected (3)                                               │
│  ─────────────────────────────────────────────────────────  │
│  🟢 Google Calendar          Connected · Syncing             │
│     2-way calendar sync for meetings and scheduling          │
│     [Manage →]                                               │
│                                                              │
│  🟢 iCount                   Connected · Last sync: 2h ago   │
│     Invoice automation and accounting                        │
│     [Manage →]                                               │
│                                                              │
│  🟢 Payplus                  Connected                       │
│     Customer payment collection                              │
│     [Manage →]                                               │
│                                                              │
│  ─────────────────────────────────────────────────────────  │
│  Available integrations                                      │
│                                                              │
│  Accounting & Invoicing                                      │
│  Morning ·iCount · Rivhit · Invoice4u · Easycount            │
│  [Connect]                                                   │
│                                                              │
│  Calendar                                                    │
│  Google Calendar · Outlook / Office 365                      │
│  [Connect]                                                   │
│                                                              │
│  Scheduling                                                  │
│  Calendly · Acuity · moCal                                   │
│  [Connect]                                                   │
│                                                              │
│  Payment Collection                                          │
│  Payplus · Cardcom · Stripe                                  │
│  [Connect]                                                   │
│                                                              │
│  Email                                                       │
│  Custom SMTP · Custom From (via Resend DKIM)   Business+     │
│  [Configure →]                                               │
│                                                              │
│  Messaging                                                   │
│  Telegram Bot · WhatsApp Business                 Enterprise │
│  [Connect]                                                   │
│                                                              │
│  Automation                                       Business+ │
│  Zapier · Make                                               │
│  [Connect]                                                   │
│                                                              │
│  Custom                                                      │
│  Webhooks · API Keys                                         │
│  [Manage →]                                                  │
└──────────────────────────────────────────────────────────────┘
```

---

## Integration Card States

Each integration card can be:

| State | Icon | Description |
|-------|------|-------------|
| Not connected | grey circle | Available to connect |
| Connecting | spinner | OAuth in progress |
| Connected | 🟢 green | Active, healthy |
| Connected with warning | 🟡 amber | e.g., token expiring, sync errors |
| Error | 🔴 red | Auth failed, webhook unreachable |
| Tier-gated | lock icon | Requires higher tier |

---

## [Connect] Flow

Clicking `[Connect]` for an integration:
- **OAuth-based** (Google Calendar, Outlook): Opens OAuth flow inline (popup or redirect)
- **Credential-based** (iCount, Morning, Rivhit): Opens setup wizard sheet (see spec 127 for invoice adapters, spec 49 for payment gateways)
- **API key** (Calendly, Acuity): Opens credential entry sheet
- **Configuration-only** (SMTP, Telegram): Opens `/settings/integrations/{name}` detail page
- **Automation** (Zapier, Make): Opens the OAuth 2.0 connect/consent flow (spec 177) so the user authorizes the Zync app; managed thereafter at `/settings/integrations/zapier` · `/make` (spec 176)

---

## [Manage →] Deep Links

Each connected integration's `[Manage →]` links to its dedicated settings route:

| Integration | Route |
|-------------|-------|
| Google Calendar | `/settings/integrations/calendar` |
| Outlook | `/settings/integrations/calendar` |
| iCount / Morning / Rivhit / Invoice4u / Easycount | `/settings/integrations/invoicing` (spec 127) |
| Accountant export (Hashavshevet / Form 6111) | `/settings/integrations/accounting` (spec 181) |
| Payplus / Cardcom / Stripe | `/settings/integrations/payments` (spec 49 UI) |
| Custom SMTP / Resend DKIM | `/settings/integrations/smtp` (spec 51) |
| Telegram | `/settings/integrations/telegram` (spec 43) |
| Webhooks | `/settings/integrations/webhooks` (spec 27) |
| API Keys | `/settings/api-keys` (spec 60) |
| Zapier | `/settings/integrations/zapier` (spec 176) |
| Make | `/settings/integrations/make` (spec 176) |

---

## Integration Status Summary

At top of page, a status bar if any integration has issues:

```
⚠ 1 integration needs attention — Google Calendar token expired [Reconnect]
```

---

## API

```
GET /api/settings/integrations
    → list all integrations with their connection status
      Returns: [{
        id: 'google-calendar',
        name: 'Google Calendar',
        category: 'calendar',
        status: 'connected' | 'error' | 'not_connected',
        tier_required: 'all' | 'business' | 'enterprise',
        manage_url: '/settings/integrations/calendar',
        details: { last_sync_at?, error_message? }
      }]
      Requires: authenticated (admin sees all; member sees non-billing integrations)
```

Status is derived from:
- `calendar_connections` table → Google Calendar / Outlook
- `adapter_credentials` table → accounting adapters
- `payment_gateway_configs` table → payment gateways
- `tenant_email_config` table → SMTP / Resend DKIM

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Read-only hub | Not manage from hub | Each integration has complex setup state; the hub is discovery + status surface, not the setup UI |
| Single `/api/settings/integrations` endpoint | Not per-integration status checks | Frontend needs one round-trip for the hub render; individual status comes from existing table queries |
| Category grouping | Not alphabetical | Users think by use case (accounting, calendar, payments), not integration name |