@getbrevo/cli 2.0.1 → 2.1.0

package/agent-context/SKILL.md

@@ -7,6 +7,18 @@ description: Use when working in a project that uses the Brevo Developer CLI (th
 
 This project uses the Brevo Developer CLI to create and manage Brevo OAuth applications. Treat the `brevo` binary as the canonical entry point — don't shell out to `curl https://api.brevo.com/...` for things the CLI already covers.
 
+## `brevo --help` is the source of truth
+
+Brevo features that haven't been released are **not built into the published CLI at all** — not as hidden commands, not behind a flag or an env var. `brevo --help` and `brevo app --help` list everything the binary can do. Treat that as the complete surface and build from it.
+
+What this means in practice:
+
+- **If a command isn't in `--help`, it doesn't exist here.** Invoking it gives Commander's `unknown command` and exit `1`. That is a final answer, not a transient failure and not a permissions problem — there is no flag, config edit, account setting, or environment variable that reveals it. Don't retry, don't hunt for an alternative route, and don't tell the user to get access. Say the feature isn't available in this CLI and offer the nearest thing that works.
+- **Don't act on a command you remember rather than one you can see.** Your recollection of the Brevo CLI may include commands from a newer or unreleased build. `--help` in the current session is the only reliable source.
+- **A flag can be rejected even when its command exists.** `--distribution` is a real flag, but a value tied to an unreleased feature is refused with *"That command is not available yet. It is part of a Brevo feature that has not been released."* Same rule: it's final. Use `--distribution private`.
+
+The Brevo API enforces the same boundaries independently, so nothing is gained by trying to route around the CLI — a hand-rolled `curl` hits the platform's own refusal.
+
 > **Reading this from the repo rather than `~/.claude/skills/brevo-cli/`?**
 >
 > - **If you're Claude Code** (CLI or desktop app — any agent that reads `~/.claude/skills/`): install it as a skill with `brevo skill:cli install` so your tooling loads it natively and keeps it auto-refreshed. The repo copy is bundled with the npm package; the installed copy is what Claude actually consumes. Note: the Claude Desktop **chat** app does not read `~/.claude/skills/`, so the installed skill won't load there — only Claude Code surfaces pick it up.
@@ -40,54 +52,98 @@ Don't fall back to raw HTTP against `api.brevo.com` — the `brevo` binary is th
 - "Authenticate" → `brevo login` (or `BREVO_API_KEY=xkeysib-... brevo login` for CI)
 - "Who am I logged in as?" → `brevo whoami --json`
 - "Show / pick an app" → `brevo app list --json`
-- "Create an app" → `brevo app create --name "<name>" --distribution private --redirect-uri <url> --json` (add `--logo-uri <https://…>` to set the app logo at creation time; new apps default to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`). Only `private` distribution is available today — the CLI rejects `--distribution public` with a "coming soon" error, so never suggest it.
-- "Update app metadata" → `brevo app update --app-id <id> --name "<name>"` and/or `--redirect-uri <url>` (repeatable) and/or `--scope <scope>` (repeatable, appends) and/or `--logo-uri <https://…>`
-- "Get client credentials" → `brevo app credentials --app-id <id> --json` (add `--reveal-secret` to print the secret)
-- "Generate starter OAuth code" → `brevo app scaffold --app-id <id>`
+- "Create an app" → `brevo app create --name "<name>" --distribution private --redirect-uri <url> --json` (add `--logo-uri <https://…>` to set the app logo at creation time; new apps default to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`). **Use `--distribution private`** — check `brevo app create --help` for the values your account accepts, and don't pass one it doesn't list. **Fails immediately if run from a directory that already has `app-config.json`** — `cd` elsewhere first, or use `brevo app scaffold` in that directory instead. Otherwise resolves (creates/`cd`s into) its target directory, creates the app, and writes the **basic project structure** (`app-config.json` + `.gitignore`/`AGENTS.md`/`CLAUDE.md`/`README.md`). It scaffolds a feature (the OAuth test server) **only** when the interactive confirm (*"Scaffold the Test OAuth App?"*, default yes) is answered yes — there is no separate "which feature?" question while the CLI ships one; **non-interactive runs (`--json` or piped) stay base-only** — run `brevo app scaffold` afterward to add the OAuth code. Under `--json`, the response's `directory` field is where it landed and `scaffolded` is the base file count; check for `scaffoldSkipped` instead of `scaffolded` if that directory already existed (both directory setup and scaffolding are skipped together in that case, but the app is still created).
+- "Update app metadata" → edit the relevant field(s) in `app-config.json` (`appName`, `auth.redirectUris`, `auth.scopes`, `logoUri`, `version`) (older projects may still say `auth.redirectUrls` — the CLI reads it and migrates the file to `redirectUris` on its next write), then run `brevo app upload --json` (no `--app-id`/`--name`/`--redirect-uri`/`--scope`/`--logo-uri` flags exist — `upload` always pushes the whole file, resolved only from cwd's `app-config.json`). **`distribution_type` is immutable** — it's set at `app create` time and cannot be changed via `upload`; if the local value differs from the server, `upload` errors and tells you to restore it (create a new app to get a different distribution). **There is no `brevo app update`** — it was removed, with no shim and no flag-for-flag equivalent; if you find it in a user's script, CI job, README, or your own recollection, replace it with the edit-then-`upload` flow above. Invoking it — with any of the old flags, with `--help`, or as `brevo app help update` — prints a message naming `brevo app upload` and exits `1` **without uploading anything**, so a `1` from `brevo app update` means the command is gone, not that an upload failed.
+- "Get client credentials" → `brevo app credentials --app-id <id> --json` (add `--reveal-secret` to print the secret). **`--app-id` is not optional here** — without it the command wants an interactive app picker, and under `--json`/off a TTY it refuses with exit `1` rather than prompting.
+- "Set up a project for an app that already exists" → `brevo app scaffold --app-id <id>` (`brevo app list` gives the IDs). Fetches the app and writes `app-config.json` + the base files, then adds a feature as below. Interactively it asks which directory to write into first (default `./<slugified app name>`); under `--json`/off a TTY it uses the current one. **This is the only way to get an `app-config.json` for an existing app** — `brevo app create` makes a *new* app, and `brevo app upload` only ever reads the project in the current directory. It refuses if the directory is already linked to a *different* app; pointing it at the app the directory is already linked to is a no-op. **Interactively you can omit `--app-id`**: plain `brevo app scaffold` in a directory with no `app-config.json` says so, asks *"Set up a project for an app you already have?"* (default yes), and on yes lists the account's apps so you can pick one — no need to look the ID up first. **Every interactive bootstrap (picker or `--app-id`) then asks `Output directory:`, defaulted to `./<the app's name slugified>`** — the same question `brevo app create` asks — creates that directory and `cd`s into it, so the files don't land in whatever folder you happened to be standing in; answer `.` to use the current directory instead. It then writes the project (`app-config.json` + the base files), shows what it wrote, and asks *"Scaffold the Test OAuth App?"* (default yes) — declining is normal and leaves the project in place, exit `0`. The *Next steps* box opens with `cd <dir>`, because the CLI can only move its own process, never your shell. **Under `--json` or off a TTY there is no directory question and the files go into the current directory**, so scripted `brevo app scaffold --app-id <id>` runs are unchanged — `mkdir` and `cd` yourself first if you want them somewhere specific. Answering **no** is a normal outcome, not an error: it exits `0` after printing the remaining routes (`brevo app create` here, or `cd` into an existing project). **Always pass `--app-id` when scripting** — the offer needs a terminal, so under `--json` or off a TTY the command errors instead of prompting. **If the directory you point it at already holds a project, the bootstrap is a refresh, not a fresh write**: the config found there is diffed against the server and rewritten only on consent (*"…will update app-config.json to match the server. Continue?"*, default yes) — answering **Merge** at the directory question does not suppress that, because merging keeps the file that exists and so would skip the very file a bootstrap is for. No drift means `app-config.json` is left alone with a one-line notice, and the feature still gets added. A directory holding a project for a **different** app is refused outright, naming both apps. Two refusals apply to both forms, before any write: that different-app case, and the directory must not be **inside** an existing project (a nested second `app-config.json` would make a later `brevo app upload` push the wrong app).
+- "Add a feature (e.g. the OAuth test server) to an existing project" → `brevo app scaffold` (run **inside** the project directory; it reads the linked app from `app-config.json`, so `--app-id` is only needed to bootstrap a directory that has none). Not needed right after `app create` if you already accepted the feature prompt there. If feature files already exist it prompts Overwrite / Merge / Cancel (default Merge); pass `--overwrite` to force a full overwrite without prompting. **The scaffolded OAuth flow is the confidential-client flow:** `/auth/callback` authenticates the token exchange with the `CLIENT_SECRET` written into the scaffolded `.env.local`.
 - "Run the OAuth test server" → `brevo app start oauth --port 3009` (must be inside the scaffolded directory)
-- "Delete an app" → `brevo app delete --app-id <id> --force`
+- "Delete an app" → `brevo app delete --app-id <id> --force`. **`--app-id` is not optional here either** — omitting it means an interactive picker, which under `--json`/off a TTY is refused with exit `1`. Never script a delete without naming the app.
 - "List supported OAuth scopes" → `brevo app available-scopes --json`
 - "Sign out" → `brevo logout --force`
 
 ## Hard rules
 
-1. **Always pass `--json`** when you intend to parse output. Every command supports it.
+1. **Always pass `--json`** when you intend to parse output. Every command supports it, **on success and on failure alike** — a failing `--json` run writes a single `{"error": {...}}` document to stdout (see *JSON errors* below), so you can read the reason instead of only seeing a non-zero exit.
 2. **Never print, log, or commit** API keys (`xkeysib-…`), client secrets, refresh tokens, or contents of `~/.brevo/credentials.json` / `.env.local`. Redact before sharing diagnostics.
 3. **Don't use `--api-key`** — the flag was removed. Use the `BREVO_API_KEY` env var.
-4. **Don't run `brevo app scaffold` inside an existing scaffolded project** — it refuses if `app-config.json` exists in cwd. Use `brevo app update` to push config changes.
+4. **`brevo app create` refuses to run inside an already-linked directory** (`app-config.json` present) — `cd` elsewhere or use `brevo app scaffold` there instead. **`brevo app scaffold` requires an `app-config.json` in the current directory unless you pass `--app-id` or answer its bootstrap offer** (it adds a feature to an already-created project); with none present and no `--app-id` it offers to set the directory up for an existing app when interactive, and otherwise errors, listing the three ways out (`cd` into a project, `--app-id` to set this directory up for an app you already have, or `brevo app create` for a new one). With `--app-id <id>` in a directory that has no config it fetches that app, asks (interactively only) which directory to write into — default `./<slugified app name>`, `.` to stay put — writes `app-config.json` + the base files there, and continues; that is the migration path off the removed `brevo app update --app-id`, and off a TTY or under `--json` it writes into the current directory with no prompt. If the directory it is told to write into already holds a project for the **same** app, it diffs that config against the server and rewrites it only on consent — the directory prompt's **Merge** answer does not silently skip the refresh, and no drift leaves `app-config.json` untouched with a notice. It refuses (before any network call) if the directory is already linked to a *different* app — whether that is the directory the command ran in or the one it was pointed at — or if the directory is **inside** an existing app project (a nested second `app-config.json` would make a later `brevo app upload` from there push the wrong app — `cd` to the project root or outside it). It reads the linked app from that config, diffs the config against the server, and if fields drifted it tells you and (on consent) rewrites `app-config.json` to match before writing the feature files. When any feature file already exists it prompts **Overwrite / Merge / Cancel** (default **Merge** — existing, e.g. hand-edited, files are kept; Cancel aborts). Pass `--overwrite` to force a full overwrite and skip that prompt (works interactively and under `--json`). **Under `--json` it never prompts**: a config diff comes back as `{ "cancelled": true, "reason": "...", "diffs": [...] }`; otherwise it scaffolds the feature (merging existing files unless `--overwrite` is passed) and returns `{ "scaffolded": <n>, "directory": "..." }`.
 5. **Prefer flag-driven over interactive** in agent contexts: `--name`, `--app-id`, `--force`, `--yes` so the command doesn't block on prompts.
+6. **Write only the `app-config.json` keys this file documents.** `brevo app upload` validates the whole file and rejects keys it doesn't recognise, so an invented block fails at upload rather than doing anything useful.
 
 ## Locating the linked app
 
-If `app-config.json` exists in the working directory, it pins the app — `brevo app update` and `brevo app start` use it automatically. To target a different app, pass `--app-id`.
+If `app-config.json` exists in the working directory, it pins the app — `brevo app upload` and `brevo app start` use it automatically. `brevo app start` accepts an `--app-id` override to target a different app; `upload` does **not** — it only ever reads cwd's `app-config.json`, hard-erroring if that file is missing, invalid, or lacks `appId`.
+
+`app-config.json` carries an optional top-level `logoUri` string. When set, `brevo app upload` pushes it as `logo_uri`; when empty / absent, the field is left untouched on the API.
+
+`app-config.json` also carries a top-level `version` string, shown by `brevo app create`/`brevo app list`. `brevo app upload` sends it on the wire as `version` (falling back to the server's current value if locally absent) and writes back whatever version the server confirms after a successful upload.
 
-`app-config.json` carries an optional top-level `logoUri` string. When set, a flagless `brevo app update` pushes it as `logo_uri` in the PUT body; when empty / absent, the field is left untouched on the API.
+`brevo app credentials` also backfills a legacy `app-config.json` toward the current shape: when the file exists in cwd and its `appId` matches the app being inspected, any missing top-level `version` / `distribution_type` is filled in from the server (fill-only-when-missing — an existing local value is never overwritten). This runs silently in all modes; human output prints a one-line note when something was written. It's how projects that are never `upload`ed still converge.
 
 ## Scopes
 
-- New apps created via `brevo app create` default to `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. The CLI prints the default set on success and points to `brevo app update --scope` for changes.
-- `brevo app update --scope <scope>` is **repeatable and appends** — passing `--scope X --scope Y` adds both to the app's existing scope set, de-duped, order-preserving. A single flag value may also contain multiple comma- or whitespace-separated tokens (`--scope "crm:read, crm:write"` ≡ `--scope crm:read --scope crm:write`); the same normalization is applied to `auth.scopes` when read from `app-config.json`, so a malformed entry like `"crm:write, campaigns:read"` is split into two scopes on read. To see what's currently set, run `brevo app credentials --app-id <id> --json`. To remove a scope, edit `app-config.json` and run `brevo app update` without `--scope`.
+- New apps created via `brevo app create` default to `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. The CLI prints the default set on success and points to editing `app-config.json` + `brevo app upload` for changes.
+- To add, remove, or change scopes: edit `auth.scopes` in `app-config.json` directly, then run `brevo app upload`. Comma- or whitespace-separated values are normalized on read, whether they sit in a single array entry (`["crm:read", "crm:write, campaigns:read"]`) or replace the array entirely (`"crm:write, campaigns:read"`) — either becomes two scopes. To see what's currently set, run `brevo app credentials --app-id <id> --json`.
 - `brevo app available-scopes [--json] [--web]` lists the OAuth scopes the IdP currently supports. It reads a **public** catalog and works **without `brevo login`** (no API key needed). Text output groups names by category (e.g. `account`, `data_crm`, `messaging`); `--json` returns a flat `{ scopes: string[] }` of names. OIDC-reserved scopes (`openid`, `profile`, `email`, `offline_access`) and magic wildcards are excluded. The CLI validates scope **format** locally (must match `[A-Za-z0-9][A-Za-z0-9:_.-]*`) but does **not** validate that a scope is recognized by the IdP — use `app available-scopes` to confirm spelling before passing an unfamiliar scope.
 - Passing `--web` to `brevo app available-scopes` **also opens a browser** to a styled local page (loopback `http://127.0.0.1:<port>/`) and stays running until Ctrl+C. Without `--web` the command exits after printing the list — TTY detection no longer triggers the browser. `--json` always suppresses the browser, so agent invocations using `--json` behave the same regardless of `--web`.
 
 ### Legacy `'all'` scope deprecation
 
-The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app update` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is an explicit `--scope` migration. To handle a legacy app:
+The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app upload` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is editing `auth.scopes` in `app-config.json` and running `upload`. To handle a legacy app:
 
 1. **Detect** `'all'` in `auth.scopes` of a local `app-config.json`, or on a remote app via `brevo app list --json` — affected apps carry `"legacy_all_scope": true` (text output appends `(legacy 'all' — deprecated)` to the scopes line).
 2. **Prompt the user to pick granular scopes** — use `brevo app available-scopes --json` for the catalog, or fall back to the four defaults (`contacts:read`, `contacts:write`, `crm:read`, `crm:write`).
-3. **Migrate** with `brevo app update --scope <scope> --scope <scope> ...` — passing `--scope` drops `'all'` from the outgoing scope set and applies the new granular scopes (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
+3. **Migrate** by editing `auth.scopes` in `app-config.json` to replace `'all'` with the granular scopes your integration uses, then run `brevo app upload` (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
 
-`brevo app scaffold` against an app whose remote scopes contain `'all'` never propagates it: the new `app-config.json` keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). Note the substitution is local-only — the remote app still needs the `--scope` migration above.
+Writing `app-config.json` for an app whose remote scopes contain `'all'` never propagates it: the file keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). This applies when `brevo app create` writes the base config, and when `brevo app scaffold` rewrites it after a detected server drift. Note the substitution is local-only — the remote app still needs the `app-config.json` edit + `brevo app upload` migration above.
 
 ## Exit codes
 
 `0` success · `1` general error · `2` aborted · `3` auth failure · `4` network · `5` not found.
 
+## JSON errors
+
+Under `--json`, a command that fails writes **one** JSON document to stdout describing the failure, and the human-readable message still goes to stderr. The `error` key is the discriminator — no success payload has one:
+
+```json
+{ "error": { "name": "CliError", "message": "Not authenticated. Run: brevo login", "exitCode": 1 } }
+```
+
+`name` is the error class (`CliError`, `ApiError`, `AuthExpiredError`, `AbortError`), `message` is the same text printed to stderr, and `exitCode` matches the process exit code. An `ApiError` adds `statusCode` (the HTTP status) and, when the API classified the failure, `code` — one of `AUTH_INVALID`, `AUTH_EXPIRED`, `ACCESS_DENIED`, `APP_NOT_FOUND`, `REDIRECT_INVALID`, `PORT_IN_USE`, `NETWORK_ERROR`, `RATE_LIMITED`, `APP_LIMIT_REACHED`, `REGISTRY_ERROR`, `AUTH_GATEWAY`:
+
+```json
+{ "error": { "name": "ApiError", "message": "App not found", "exitCode": 5, "code": "APP_NOT_FOUND", "statusCode": 404 } }
+```
+
+Two things to rely on: stdout is always **exactly one** parseable document, and commands that describe their own failure keep doing so instead of emitting this envelope — `brevo whoami --json` still returns `{"authenticated": false, "reason": "no_key"}` (exit `1`). Check for `error` first, then fall back to the command's own shape.
+
+## Command help
+
+`brevo --help` prints the grouped overview of every command. `brevo <command> --help` prints that command's own usage line, arguments, flags, and examples — e.g. `brevo app scaffold --help` documents `--app-id` / `--overwrite` / `--json`. When you need to confirm a flag exists on the version actually installed, read it from there rather than assuming from this file.
+
 ## Forced update
 
 When the installed CLI is a full **major** version behind the latest npm release, every command except `--help` / `--version` prints a blocking update banner to stderr and exits `1` **without running** — so a `brevo` call that suddenly exits `1` with an update banner means the CLI must be upgraded (`npm install -g @getbrevo/cli` or `yarn global add @getbrevo/cli`) before it will work. The gate honors the same opt-outs as the soft update notice (`BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, non-TTY), so it never fires in those contexts.
 
+## Update notice wording
+
+The update banner's first line comes from the app-store service (`GET /cli/info`). It is called directly rather than through the v3 API gateway and requires no API key, so it works while logged out or with expired credentials. It runs once per invocation, **before** the command, and the response is cached at `~/.brevo/cli-info-cache.json` for **15 minutes**, keyed to the installed `cliVersion` — so reworded text or a new block reaches the CLI within minutes rather than after the old 12h npm-style TTL, without a network call on every single command. Whether an update banner appears is still decided from the npm registry, exactly as before, and a failed call just means the banner uses local wording (a failed call never overwrites a good cache entry). `BREVO_APP_STORE_URL` overrides that service's base URL for non-production testing.
+
+## Server-side block
+
+The same response may carry `"is_blocked": true`. When it does, every command except `--help` / `--version` prints a banner to stderr and exits `1` **without running** — a separate mechanism from the major-version gate above, and one the server can turn on without shipping a new CLI.
+
+Those two are exempt from the **block**, not from the lookup: they still call `/cli/info` and still render the server's wording on their update banner. They simply never exit non-zero because of it, so a blocked CLI can always still report what version it is.
+
+Two things to know when you hit this:
+
+- **The notice opt-outs do not apply.** `BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, and a non-TTY all suppress the *notice*; none of them suppress a block. Don't suggest them as a workaround — the only fix is upgrading the CLI.
+- **It fails open.** A timeout, a non-2xx, or an unparseable body lets the command run normally; only a literal `true` blocks. So a network problem never manifests as a block.
+- **A block can persist up to 15 minutes after the server lifts it, and vice versa**, because the whole response is cached. If you need a verdict that reflects the server's *current* state, delete `~/.brevo/cli-info-cache.json` (or bump the version) before checking.
+
+The soft (non-blocking) notice also prints after a command **fails**, not just after it succeeds — so stderr can hold the error message followed by the update box. This does not change exit codes: a failing command still exits with its own code, and the box is never printed twice in one run. A Ctrl-C abort skips it. If you parse stderr strictly, suppress the notice with `BREVO_NO_UPDATE_NOTIFIER=1` or `--no-update-notifier`.
+
 ## Before sharing or committing output
 
 * [ ] No `xkeysib-…` API keys, client secrets, refresh tokens, or contents of `~/.brevo/credentials.json` / `.env.local` in messages, logs, or diffs.

package/dist/{templates → bin}/files/AGENTS.md.tmpl

@@ -33,11 +33,21 @@ Implements the authorization code flow to obtain access tokens for the Brevo API
 - Other grant types supported by the Brevo OAuth server but not wired into this scaffold: `client_credentials`
 
 ## OAuth flow
+{{#if private}}
 1. `/auth/login` — generates CSRF state, redirects user to `{OAUTH_BASE}/realms/{realm}/oauth/authorize`
 2. User authorizes -> OAuth server redirects to `/auth/callback` with an auth code
-3. Server validates state, exchanges code for access + refresh tokens via `POST /realms/{realm}/oauth/token`
+3. Server validates state, exchanges code for access + refresh tokens via `POST /realms/{realm}/oauth/token` (authenticated with `client_secret`)
 4. Verifies connection via `GET /realms/{realm}/oauth/userinfo`
 5. `/auth/refresh` — refreshes tokens using `refresh_token` grant
+{{/if}}
+{{#if public}}
+This is a **public app** — the flow uses **PKCE (RFC 7636)** and sends **no `client_secret`**:
+1. `/auth/login` — generates CSRF state + a PKCE `code_verifier`, then redirects user to `{OAUTH_BASE}/realms/{realm}/oauth/authorize` with `code_challenge` (S256) + `code_challenge_method=S256`
+2. User authorizes -> OAuth server redirects to `/auth/callback` with an auth code
+3. Server validates state, exchanges code + `code_verifier` (no `client_secret`) for access + refresh tokens via `POST /realms/{realm}/oauth/token`
+4. Verifies connection via `GET /realms/{realm}/oauth/userinfo`
+5. `/auth/refresh` — refreshes tokens using `refresh_token` grant (no `client_secret`)
+{{/if}}
 
 ## Development
 ```bash

package/dist/{templates → bin}/files/CLAUDE.md.tmpl

@@ -47,9 +47,17 @@ brevo app start oauth        # port is read from app-config.json; override with
 | `GET /realms/{realm}/.well-known/openid-configuration` | OIDC discovery |
 
 ## Key flows
+{{#if private}}
 - `/auth/login` — generates random CSRF state, redirects to OAuth authorize endpoint
 - `/auth/callback` — validates state, POSTs code to `/realms/{realm}/oauth/token`, stores tokens
 - `/auth/refresh` — refreshes tokens using `refresh_token` grant
+{{/if}}
+{{#if public}}
+This is a **public app**, so the flow uses **PKCE (RFC 7636)** and no client secret:
+- `/auth/login` — generates random CSRF state **and a PKCE `code_verifier`**, then redirects to the OAuth authorize endpoint sending `code_challenge` (S256 hash of the verifier) + `code_challenge_method=S256`. The verifier is stored server-side and never sent to the browser.
+- `/auth/callback` — validates state, POSTs code **plus the `code_verifier`** (no `client_secret`) to `/realms/{realm}/oauth/token`, stores tokens
+- `/auth/refresh` — refreshes tokens using the `refresh_token` grant (no `client_secret`)
+{{/if}}
 
 ## Next steps
 - Replace the in-memory token store in `src/oauth/token-store.js` with a real database (the global singleton is process-local so data is lost on restart, and it is not session-isolated, so multiple users/sessions/tabs can read or overwrite the same in-memory tokens)

package/dist/{templates → bin}/files/README.md.tmpl

@@ -55,28 +55,25 @@ Brevo OAuth integration for testing and implementing app authorization flows, sc
 
 ## Updating your app
 
-Push changes to Brevo directly from the CLI:
+`brevo app upload` has no edit flags — it always pushes the full contents of `app-config.json`. To change something, edit the file, then run:
 
 ```bash
-brevo app update --name "New Name"
-brevo app update --redirect-url https://myapp.com/callback
-brevo app update --name "New Name" --redirect-url https://myapp.com/callback
-brevo app update --logo-uri https://example.com/logo.png
+brevo app upload
 ```
 
-`--redirect-url` is repeatable and **appends** to existing URLs.
+For example, to rename the app or add a redirect URL, edit `appName` or `auth.redirectUris` in `app-config.json`:
 
-To avoid unintentionally accumulating stale redirect URLs over time:
+```bash
+# 1. Edit app-config.json (e.g. change "appName", or append to "auth.redirectUris")
+# 2. Push the change
+brevo app upload
+```
 
-- Periodically review your redirect list and remove obsolete entries in `app-config.json`.
-- Run `brevo app update` **without flags** to replace the remote configuration with the local file.
-- When flags are provided, the local `app-config.json` is updated automatically after a successful API call.
+`brevo app upload` always fetches the current server state first and shows a diff before pushing — review it before confirming (or pass `--yes` to skip the prompt).
 
-Outside this project directory, target an app by ID:
+To avoid unintentionally accumulating stale redirect URLs over time, periodically review `auth.redirectUris` in `app-config.json` and remove obsolete entries before running `brevo app upload`.
 
-```bash
-brevo app update --app-id {{APP_ID}} --name "New Name"
-```
+`brevo app upload` has no `--app-id` flag — it always resolves the app from this directory's `app-config.json`. To manage a different app, `cd` into that app's project directory (or use `brevo app credentials --app-id <id>` to inspect it without editing).
 
 ## Docs
 

package/dist/bin/files/app-config.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "appId": "{{APP_ID}}",
+  "appName": "{{APP_NAME}}",
+  "version": "{{APP_VERSION}}",
+  "logoUri": "{{LOGO_URI}}",
+  "distribution_type": "{{DISTRIBUTION}}",
+{{#if ui_app}}
+  "ui_app": {{UI_APP_JSON}},
+{{/if}}
+  "auth": {
+{{#if oauth}}
+    "scopes": {{SCOPES_JSON}},
+    "redirectUris": {{REDIRECT_URLS_JSON}}
+{{/if}}
+  }
+}

package/dist/{templates → bin}/files/src/oauth/.env.example.tmpl

@@ -1,8 +1,16 @@
 # Brevo OAuth Credentials — copy this file to .env.local and fill in your values
+{{#if private}}
 # Get CLIENT_ID and CLIENT_SECRET: brevo app credentials --reveal-secret
+{{/if}}
+{{#if public}}
+# Get CLIENT_ID: brevo app credentials
+# This is a public app — it uses PKCE (RFC 7636) and no client secret.
+{{/if}}
 
 CLIENT_ID=your_client_id_here
+{{#if private}}
 CLIENT_SECRET=your_client_secret_here
+{{/if}}
 REDIRECT_URI={{REDIRECT_URI}}
 
 # OAuth server

package/dist/{templates → bin}/files/src/oauth/.env.local.tmpl

@@ -2,7 +2,9 @@
 # Generated by: brevo app scaffold
 
 CLIENT_ID={{CLIENT_ID}}
+{{#if private}}
 CLIENT_SECRET={{CLIENT_SECRET}}
+{{/if}}
 REDIRECT_URI={{REDIRECT_URI}}
 
 # OAuth server

package/dist/{templates → bin}/files/src/oauth/handler.js.tmpl

@@ -38,7 +38,9 @@ const REVEAL_SCRIPT =
   '<script>document.querySelectorAll(".reveal-btn").forEach(function(btn){btn.addEventListener("click",function(){btn.parentElement.querySelector(".token-value").classList.add("revealed");btn.classList.add("hidden")})});</script>';
 
 const CLIENT_ID = process.env.CLIENT_ID;
+{{#if private}}
 const CLIENT_SECRET = process.env.CLIENT_SECRET;
+{{/if}}
 const REDIRECT_URI = process.env.REDIRECT_URI || '{{REDIRECT_URI}}';
 const OAUTH_BASE = process.env.OAUTH_BASE || '{{OAUTH_BASE}}';
 const OAUTH_REALM = process.env.OAUTH_REALM || '{{OAUTH_REALM}}';
@@ -55,19 +57,48 @@ try {
   console.warn('Warning: Could not read app-config.json — defaulting scopes to "all".');
 }
 
-// Step 1: Redirect user to authorization page
-router.get('/login', (req, res) => {
-  const state = require('crypto').randomBytes(16).toString('hex');
-  tokenStore.setState(state);
-
-  const authUrl = `${realmPath}/authorize?` +
+// Build the OAuth authorization URL. Extracted so /auth/login and the
+// server.js landing page render the exact same URL — no drift between the two.
+{{#if public}}
+// `codeChallenge` is the PKCE (RFC 7636) S256 challenge. Base64url output is
+// already URL-safe, so it is not re-encoded (matching the `state` treatment).
+function buildAuthorizeUrl({ state, codeChallenge }) {
+{{/if}}
+{{#if private}}
+function buildAuthorizeUrl({ state }) {
+{{/if}}
+  let authUrl = `${realmPath}/authorize?` +
     `response_type=code` +
     `&client_id=${encodeURIComponent(CLIENT_ID)}` +
     `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
     `&state=${state}` +
     `&scope=${encodeURIComponent(SCOPES)}`;
+{{#if public}}
+  authUrl += `&code_challenge=${codeChallenge}&code_challenge_method=S256`;
+{{/if}}
+  return authUrl;
+}
+
+// Step 1: Redirect user to authorization page
+router.get('/login', (req, res) => {
+  const crypto = require('crypto');
+  const state = crypto.randomBytes(16).toString('hex');
+  tokenStore.setState(state);
+{{#if public}}
+
+  // PKCE (RFC 7636): create a high-entropy verifier, keep it server-side, and
+  // send only its SHA-256 (S256) hash on the authorize request. The verifier
+  // itself is presented only later, on the token exchange in /auth/callback.
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+  tokenStore.setVerifier(codeVerifier);
+
+  res.redirect(buildAuthorizeUrl({ state, codeChallenge }));
+{{/if}}
+{{#if private}}
 
-  res.redirect(authUrl);
+  res.redirect(buildAuthorizeUrl({ state }));
+{{/if}}
 });
 
 // Step 2: Handle the OAuth callback
@@ -94,7 +125,14 @@ router.get('/callback', async (req, res) => {
       new URLSearchParams({
         grant_type: 'authorization_code',
         client_id: CLIENT_ID,
+{{#if private}}
         client_secret: CLIENT_SECRET,
+{{/if}}
+{{#if public}}
+        // PKCE (RFC 7636): prove possession of the verifier generated in /login.
+        // Public clients hold no secret, so this replaces client_secret entirely.
+        code_verifier: tokenStore.getVerifier(),
+{{/if}}
         code,
         redirect_uri: REDIRECT_URI,
       }),
@@ -165,7 +203,9 @@ router.get('/refresh', async (req, res) => {
       new URLSearchParams({
         grant_type: 'refresh_token',
         client_id: CLIENT_ID,
+{{#if private}}
         client_secret: CLIENT_SECRET,
+{{/if}}
         refresh_token: refreshToken,
       }),
       { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
@@ -204,3 +244,5 @@ router.get('/refresh', async (req, res) => {
 });
 
 module.exports = router;
+// Exposed so server.js renders the same authorize URL the /login redirect uses.
+module.exports.buildAuthorizeUrl = buildAuthorizeUrl;

package/dist/{templates → bin}/files/src/oauth/server.js.tmpl

@@ -14,11 +14,21 @@ if (!fs.existsSync(envPath)) {
 
 require('dotenv').config({ path: envPath });
 
+{{#if private}}
 if (!process.env.CLIENT_ID || !process.env.CLIENT_SECRET) {
   console.error('\nError: CLIENT_ID and CLIENT_SECRET must be set in .env.local');
   console.error('Get your credentials with: brevo app credentials --reveal-secret\n');
   process.exit(1);
 }
+{{/if}}
+{{#if public}}
+// Public apps use PKCE (RFC 7636) — no client secret is involved.
+if (!process.env.CLIENT_ID) {
+  console.error('\nError: CLIENT_ID must be set in .env.local');
+  console.error('Get your credentials with: brevo app credentials\n');
+  process.exit(1);
+}
+{{/if}}
 
 if (!process.env.OAUTH_BASE || process.env.OAUTH_BASE.startsWith('{{')) {
   console.error('\nError: OAUTH_BASE is not set or contains a placeholder.');
@@ -33,24 +43,20 @@ if (!process.env.OAUTH_REALM || process.env.OAUTH_REALM.startsWith('{{')) {
 
 const express = require('express');
 const authRouter = require('./handler');
+const { buildAuthorizeUrl } = authRouter;
 
 const app = express();
 const PORT = process.env.PORT || 3009;
 
-const REDIRECT_URI = process.env.REDIRECT_URI || '{{REDIRECT_URI}}';
-let SCOPES = 'all';
-try {
-  const appConfig = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'app-config.json'), 'utf-8'));
-  if (appConfig.auth && appConfig.auth.scopes) SCOPES = appConfig.auth.scopes.join(' ');
-} catch {
-  console.warn('Warning: Could not read app-config.json — defaulting scopes to "all".');
-}
-const AUTH_URL = `${process.env.OAUTH_BASE}/realms/${process.env.OAUTH_REALM}/oauth/authorize`
-  + `?response_type=code`
-  + `&client_id=${encodeURIComponent(process.env.CLIENT_ID)}`
-  + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`
-  + `&state=[random]`
-  + `&scope=${encodeURIComponent(SCOPES)}`;
+// Build the displayed authorization URL with the same helper /auth/login uses,
+// so what the landing page shows always matches what the redirect actually
+// sends. Placeholders (`[random]` state) stand in for the per-request values.
+{{#if private}}
+const AUTH_URL = buildAuthorizeUrl({ state: '[random]' });
+{{/if}}
+{{#if public}}
+const AUTH_URL = buildAuthorizeUrl({ state: '[random]', codeChallenge: '[generated-per-login]' });
+{{/if}}
 
 app.use('/auth', authRouter);
 

package/dist/{templates → bin}/files/src/oauth/token-store.js.tmpl

@@ -2,6 +2,9 @@
 
 let tokens = {};
 let csrfState = null;
+{{#if public}}
+let codeVerifier = null;
+{{/if}}
 
 module.exports = {
   saveTokens({ access_token, refresh_token, expires_in }) {
@@ -31,9 +34,25 @@ module.exports = {
   getState() {
     return csrfState;
   },
+{{#if public}}
+
+  // PKCE (RFC 7636): stash the code_verifier between /auth/login and
+  // /auth/callback. Same process-local, non-session-isolated limitation as the
+  // token store above — replace with your database in production.
+  setVerifier(verifier) {
+    codeVerifier = verifier;
+  },
+
+  getVerifier() {
+    return codeVerifier;
+  },
+{{/if}}
 
   clear() {
     tokens = {};
     csrfState = null;
+{{#if public}}
+    codeVerifier = null;
+{{/if}}
   },
 };