Skip to content
5 changes: 5 additions & 0 deletions .changeset/admin-crm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@freeticket/cli": minor
---

New `ft admin crm` commands for the master CRM (admin contract 1.8.0): list and inspect campaigns, search shows and dates, read options and the WhatsApp quota, preview an audience, launch a campaign (`--ignore-window` to send WhatsApp now outside 9:00-20:00), send or stop WhatsApp batches and cancel a scheduled campaign. SUPER_ADMIN only. Every write previews its target and asks for confirmation (`--yes` in scripts; no TTY and no `--yes` refuses), each prompt names the API host it writes to, and `launch --yes` requires `--expect-count <N>` (the reach the preview must match - WhatsApp-reachable for WHATSAPP, the total for EMAIL - or nothing is sent; optional but checked without `--yes`). None is retried: a 5xx or a dropped connection on a write reports the outcome as unknown and points at `campaigns list` instead of suggesting a retry, and a 2xx with an unexpected body warns that the write probably went through (exit 0) instead of crashing. Audience filters must be v2 (`"version": 2`) and are checked before anything is sent. `PAYLOAD_TOO_LARGE` (413) and `RATE_LIMITED` (429) are explained. The bundled admin contract moves to 1.8.0 (adds the `MERCH_MANAGER` staff role).
5 changes: 5 additions & 0 deletions .changeset/admin-service-token.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@freeticket/cli": minor
---

`ft admin` authenticates with a platform service token: set `FT_ADMIN_TOKEN` and it is sent as `Authorization: Bearer`, ahead of the session cookie.
122 changes: 122 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ ft sales list --status CONFIRMED --json
| `ft waitlist list [--city <name>]` · `waitlist create --data` | Per-city waitlist of an enterprise landing (export with personal data); `create` needs an enterprise service key | ADMIN |
| `ft api-keys create <name>` · `list` · `revoke <id>` | Self-service API keys (the secret is shown once, never stored) | ADMIN |
| `ft admin login` · `me` · `workspaces` · `users` · `plans` · `feature-flags` · `tokens` · `audit-log` | Superadmin, cross-tenant — needs a SUPER_ADMIN session, not an API key. Includes `admin workspaces plan <id>` (assisted plan assignment), `plan-show <id>` (current plan) and `delete <id>` (soft delete; suspend first) and `webTemplate` / `customDomain` on `update` | SUPER_ADMIN |
| `ft admin crm campaigns` · `batches` · `events` · `options` · `quota` · `preview` · `launch` | Master CRM: email / WhatsApp campaigns to buyers across workspaces. See [`ft admin crm`](#ft-admin-crm) | SUPER_ADMIN |

> **Write operations** (`create`/`update`/`delete` and actions like `publish`,
> `cancel`, `refund`) send a JSON body via `--data <inline-json>` or
Expand All @@ -143,6 +144,125 @@ ft sales list --status CONFIRMED --json
| `--csv` | list commands | CSV output for spreadsheets/accounting |
| `--data <json>` `--yes` | write commands | JSON body (inline or `@file`) · skip delete confirmation |

## `ft admin crm`

The master CRM for the internal team: email and WhatsApp campaigns to buyers,
across every workspace, against `/api/admin/crm`. It needs a SUPER_ADMIN
credential — `FT_ADMIN_TOKEN` (a service token from `ft admin tokens create`)
or `ft admin login --session`.

```bash
ft admin crm campaigns list [--channel EMAIL|WHATSAPP] [--status S] [--limit N]
ft admin crm campaigns get <id>
ft admin crm campaigns cancel <id> [--yes]
ft admin crm batches next <id> [--ignore-window] [--yes]
ft admin crm batches stop <id> [--yes]
ft admin crm events search <query> [--purpose scope|promote|except] [--sender <workspaceId>]
ft admin crm events dates <eventId...>
ft admin crm options
ft admin crm quota
ft admin crm preview --filter @filter.json [--sender freeticket|<workspaceId>]
ft admin crm launch --data @campaign.json [--ignore-window] [--expect-count N] [--yes]
```

**Writes send real messages.** `launch`, `campaigns cancel`, `batches next` and
`batches stop` first show what they are about to touch — `launch` runs the
audience preview with the same filter and sender (total, how many have email
or reachable WhatsApp, the estimated days at the daily quota); the others show
the campaign — and then ask for confirmation, naming the API host the write
goes to (`… against admin.appfreeticket.com?`) so a staging token pointed at
production stands out. Without a TTY they refuse unless you pass `--yes`
(being in CI is not consent).

`launch --yes` also requires `--expect-count <N>`: the number of people you
expect to reach — reachable by WhatsApp for a `WHATSAPP` campaign, the total
for `EMAIL`, the same `N` the prompt shows in `Launch to N people`. Take it from
`ft admin crm preview`. If the launch's own preview gives a different number it
stops before sending anything. Without `--yes` the flag is optional (the prompt
is the gate) but still checked when given. A script or an agent cannot launch
a campaign without declaring how many people it reaches. The CLI never retries a write
on its own: a 5xx or a dropped connection on a write is reported as "outcome
unknown" — check `campaigns list` before running it again (the backend rejects
the same channel + sender + subject within 10 minutes with
`DUPLICATE_CAMPAIGN` and prints the existing id). If a write answers 2xx but
with an unexpected body, the CLI exits 0 with a warning that it probably went
through — again, check `campaigns list` instead of running it again. A filter without
`"version": 2` is refused before anything is sent.

Named errors get a next step: `OUTSIDE_SEND_WINDOW` (WhatsApp sends only
9:00-20:00 Bogotá) prints when the window opens and suggests `--ignore-window` (on `batches next`, and on a
`launch` by WhatsApp with `timing.mode` `now`);
`QUOTA_EXHAUSTED` prints when the quota frees up; `RATE_LIMITED` (429) says
when to run it again by hand; `INVALID_STATE` means the
campaign no longer allows that action; a 422 lists each `details[].path`; a 413 `PAYLOAD_TOO_LARGE` means the body is over
256 KB.

Find the ids for a filter with `events search` and `events dates`, and the
cities, genre/format codes, plans and WhatsApp templates with `options`.

### `filter.json` (audience filter v2)

```json
{
"version": 2,
"scope": { "level": "platform" },
"include": [
{ "type": "purchased", "eventIds": ["evt_123"], "window": { "kind": "last_days", "days": 90 } }
],
"except": [
{ "type": "received_campaign", "days": 7, "channel": "any" }
]
}
```

- `scope` (default `platform`): `{ "level": "orgs", "workspaceIds": [...] }` or
`{ "level": "events", "eventIds": [...] }`.
- `include` conditions combine with AND; `except` with OR, evaluated across the
whole platform. Up to 12 per block, 50 ids per list.
- Condition types: `purchased`, `abandoned`, `checked_in` (with optional
`eventIds`, `dateIds` + `dateEventIds`, `window`), `city` (`cities`),
`facet` (`dimension`: `genre` | `format`, `codes`), `membership` (`state`:
`active` | `expiring` | `cancelled`, `withinDays` for `expiring`, `planIds`),
`spend` (`minCop`, `maxCop`), `received_campaign` (`except` only: `days`,
`channel`), `people` (`include` only: `emails`).
- `window`: `{ "kind": "any" }` (default), `{ "kind": "last_days", "days": 7|30|90 }`
or `{ "kind": "range", "from": "2026-09-01", "to": "2026-09-30" }` (Bogotá dates).
- Without a state condition (`purchased`, `abandoned`, `checked_in`,
`membership`, `people`) in `include`, the audience defaults to confirmed
buyers plus active members.

### `campaign.json`

```json
{
"channel": "WHATSAPP",
"sender": { "kind": "freeticket" },
"templateName": "promo_show",
"subject": "New date in Medellín",
"body": "We just opened a second show. Get your tickets before they are gone.",
"promotedEventId": "evt_123",
"filter": {
"version": 2,
"include": [{ "type": "purchased", "eventIds": ["evt_123"] }],
"except": []
},
"timing": { "mode": "batches", "firstAt": "2026-11-03T10:00:00-05:00", "batchSize": 50, "perDay": 3, "intervalMinutes": 120 }
}
```

- `sender`: `{ "kind": "freeticket" }` or `{ "kind": "organization", "workspaceId": "..." }`.
FreeTicket is mandatory when the scope spans the platform, several
organizations or events of more than one owner (`preview` tells you).
- WhatsApp needs an approved `templateName` (see `options`); email rejects one.
`imageUrl` for WhatsApp must come from the media library.
- `ignoreSendWindow` (or `--ignore-window`): WhatsApp with `timing.mode` `now`
only; sends even outside 9:00-20:00 Bogotá instead of failing with
`OUTSIDE_SEND_WINDOW`.
- `timing`: `{ "mode": "now" }` (sends on response), `{ "mode": "scheduled", "at": "<ISO with offset>" }`
or `batches` (WhatsApp only, daily cap 150 when FreeTicket signs, 200 for an
organization). WhatsApp times are moved into the 9:00-20:00 Bogotá window;
the response's `scheduledAt` is the real one.

## Configuration

`ft` resolves configuration in this precedence order:
Expand All @@ -156,6 +276,8 @@ flags > environment variables > ~/.freeticket/config.json > defaults
| `FT_API_URL` | `https://admin.appfreeticket.com` | API base URL (without `/api/v1`) |
| `FT_API_KEY` | — | CI/headless only — a backend-issued `ft_live_...` token. Browser login (`ft login`) needs no key. When set it is the **only** account: stored logins are ignored, nothing fans out across them, and `--account` is rejected. A workspace pinned with `ft workspace use` still applies |
| `FT_WORKSPACE_ID` | *home* | Default active workspace |
| `FT_ADMIN_TOKEN` | — | `ft admin` only — a platform service token (`ft admin tokens create`), sent as `Authorization: Bearer`. Takes precedence over the session cookie |
| `FT_ADMIN_SESSION` | — | `ft admin` only — a SUPER_ADMIN `better-auth.session_token` cookie (same as `ft admin login --session`) |
| `FT_NO_UPDATE_CHECK` | — | Set to disable the "update available" notice (checked at most once a day; also off in CI, without a TTY, and with `--json`/`--raw`/`--csv`) |

Logins are stored per account under `accounts` in `~/.freeticket/config.json`
Expand Down
Loading
Loading