warmbly/docs/integrations-oauth-setup.md

# Integrations — OAuth provider setup

Warmbly's integrations connect via **real OAuth 2.0** wherever the provider
supports it (HubSpot, Slack, Google Sheets, Pipedrive, Salesforce). The connect
flow, CSRF/PKCE handling, token exchange, encrypted-at-rest token storage, and
automatic refresh are all built in. The only thing the platform operator must
supply is **one developer app per provider**, registered in that provider's
console, plus its client ID/secret as environment variables.

Until a provider's credentials are present, it renders in the dashboard catalog
as **"Coming soon"** (the Connect button is disabled) — no code change is needed
to light it up; just add the env vars and restart the backend.

## How it works (no code changes required to enable a provider)

1. User clicks **Connect with X** in the dashboard.
2. SPA calls `POST /integrations/oauth/start` → backend mints a CSRF `state`
   (+ PKCE verifier where supported), stores it in `integration_oauth_states`,
   and returns the provider authorization URL.
3. SPA opens that URL in a popup. The user authorizes in the provider's UI.
4. The provider redirects to `GET /integrations/oauth/callback` (a public
   bouncer page) which `postMessage`s `{code, state}` back to the SPA opener.
5. SPA calls `POST /integrations/oauth/finish` → backend validates+consumes the
   `state`, exchanges the code for tokens, resolves the connected account, and
   stores the access/refresh tokens **sealed with the connecting user's
   envelope-encryption DEK** (KMS → per-user DEK → AES-GCM, the same path used
   for mailbox OAuth tokens). Plaintext tokens never touch a database column.

Access tokens are refreshed automatically (60s before expiry) using the stored
refresh token; if a refresh fails the connection flips to `reauth_required` and
the user is prompted to reconnect from the connection drawer.

## Required environment variables

Set these on the **backend** service. The redirect/callback URL must be allow-
listed in each provider's app config.

```
# Shared callback URL the providers redirect to. Defaults to
# $BACKEND_PUBLIC_URL/integrations/oauth/callback, else http://localhost:8080/...
INTEGRATIONS_OAUTH_REDIRECT_URL=https://api.yourdomain.com/integrations/oauth/callback

# HubSpot — https://developers.hubspot.com/  (create a public app)
HUBSPOT_OAUTH_CLIENT_ID=
HUBSPOT_OAUTH_CLIENT_SECRET=

# Slack — https://api.slack.com/apps  (OAuth & Permissions → bot scopes:
#   chat:write, channels:read, groups:read)
SLACK_OAUTH_CLIENT_ID=
SLACK_OAUTH_CLIENT_SECRET=

# Google Sheets — https://console.cloud.google.com/  (OAuth client, enable the
#   Google Sheets API; scopes: spreadsheets, userinfo.email)
GOOGLE_SHEETS_OAUTH_CLIENT_ID=
GOOGLE_SHEETS_OAUTH_CLIENT_SECRET=

# Pipedrive — https://developers.pipedrive.com/  (Marketplace Manager app;
#   scopes: contacts:full, deals:full)
PIPEDRIVE_OAUTH_CLIENT_ID=
PIPEDRIVE_OAUTH_CLIENT_SECRET=

# Salesforce — https://developer.salesforce.com/  (Connected App;
#   scopes: api, refresh_token)
SALESFORCE_OAUTH_CLIENT_ID=
SALESFORCE_OAUTH_CLIENT_SECRET=
```

The env var prefix is `<PROVIDER>_OAUTH_CLIENT_ID` / `_CLIENT_SECRET` — wiring a
new OAuth provider is just registering it in `internal/app/integration/oauth.go`
(`NewOAuthManager`) and adding the matching env vars.

## Redirect URL to register with each provider

```
<INTEGRATIONS_OAUTH_REDIRECT_URL>
# e.g. https://api.yourdomain.com/integrations/oauth/callback
```

For local development the default is `http://localhost:8080/integrations/oauth/callback`.

## Providers that do NOT use OAuth

- **Close** — no public OAuth app; the user pastes a Close API key.
- **Zapier / Make / n8n** — authenticate *into Warmbly* using a scoped Warmbly
  API key the user generates under Settings → API keys.
- **Discord** — the user pastes a channel webhook URL (outbound only).
- **Calendly / Cal.com** — inbound only; Warmbly mints a signed inbound URL the
  user pastes into the provider's webhook config.

All pasted secrets are sealed with the same envelope encryption as OAuth tokens
before they are stored — nothing sensitive is ever persisted in plaintext.

## How a user actually uses an integration

Connecting is step one; the value is the **automations** a user builds on a
connection. After connecting, the user opens the connection's management drawer
(click any connected card on the Integrations page) and adds rules:

> **When** a prospect replies — **only** positive replies, **≥60%** confidence —
> **notify** `#sales` with “🔥 {{contact_email}} is interested — {{subject}}”.

Each rule is fully customizable in the UI (no code, no API keys to paste):

- **Trigger** — which Warmbly event fires the rule (reply, bounce, unsubscribe,
  warmup-health, complaint, meeting booked).
- **Filters** (reply triggers) — restrict to specific reply intents
  (`positive`, `question`, `negative`, …) and a minimum classifier confidence.
- **Destination** — Slack channel, Google Sheet ID, or an outbound URL,
  depending on the provider.
- **Message template** — a custom string with `{{placeholder}}` substitution
  over the event payload (`{{contact_email}}`, `{{subject}}`, `{{intent}}`,
  `{{campaign_id}}`, `{{reason}}`, …).

Rules are stored in `integration_event_subscriptions.config` (JSONB) and applied
at dispatch time by `internal/app/integration/dispatch.go`
(`subscriptionMatchesFilter`, `renderTemplate`).

## Event-driven actions — the wiring

Examples of trigger → action pairs:

- `campaign.reply_received` → `slack.notify` (ping #sales)
- `campaign.reply_received` → `hubspot.upsert_contact` (create/update + log note)
- `campaign.email_bounced` → `discord.notify`
- meeting booked (Calendly/Cal.com) → Slack / CRM

Events reach integration actions through the webhook dispatch sink
(`webhook.Service.WireDispatchSink`), so any event already delivered to customer
webhooks also drives integration actions. The sink is wired in **both** binaries:

- **`cmd/backend`** — deliverability ingest (bounce/complaint/unsubscribe),
  meeting-booked, email-account lifecycle, warmup health.
- **`cmd/consumer`** — inbound campaign replies. The consumer is where replies
  are detected (`advanced.ProcessIncomingReply`), which now emits
  `campaign.reply_received` with `intent`/`confidence` in the payload. This is
  what makes "notify me when a prospect replies → Slack/CRM" fire for real.

`advanced.Service` exposes `WireDispatcher(EventDispatcher)` (see
`internal/app/advanced/events.go`); `ProcessIncomingReply` and
`IngestDeliverabilityEvent` call `emit(...)` to fan their events out.

Each executed action is recorded as an `integration_sync_runs` row for
observability and surfaced in the connection drawer's "Recent activity".

## Access / gating

Integrations are a **paid-plan** feature (enforced in the integration handlers
via `FeatureGateService.IsPaidOrganization`). Browsing the catalog is open so
non-paid orgs see what's available; connecting requires an active paid plan.