@getbrevo/cli 2.0.2 → 2.2.0

package/dist/bin/files/README.md.tmpl

@@ -0,0 +1,184 @@
+# {{APP_NAME}}
+{{#if oauth}}
+
+Brevo OAuth integration for testing and implementing app authorization flows, scaffolded with the Brevo CLI.
+
+> **This is a starter / test app** to help you exercise the OAuth flow locally. Treat it as a reference — it is not intended for production use.
+
+## Setup
+
+1. Install dependencies for the oauth feature:
+
+   ```bash
+   yarn --cwd src/oauth install
+   # or: npm --prefix src/oauth install
+   ```
+
+2. Start the local OAuth test server (the CLI reads `app-config.json` for port and redirect URLs):
+
+   ```bash
+   brevo app start oauth
+   # or choose a port: brevo app start oauth --port 3000
+   ```
+
+3. Open the login URL printed by the CLI (typically `http://localhost:<port>/auth/login`). The OAuth server redirects back to `http://localhost:<port>/auth/callback` — make sure that URL is registered on your app's redirect list.
+
+## Project structure
+
+```
+.
+├── app-config.json           App config — ID, scopes, redirect URLs, logo URL
+├── .gitignore                Ignores .env.local and build artifacts
+├── AGENTS.md                 AI agent guidance
+├── CLAUDE.md                 Claude Code guidance
+├── README.md                 (this file)
+└── src/
+    └── oauth/                Self-contained OAuth test feature
+        ├── package.json      Dependencies & `yarn start` script
+        ├── server.js         Test server entry point
+        ├── handler.js        OAuth routes (/auth/login, /auth/callback, /auth/refresh)
+        ├── token-store.js    In-memory token management
+        ├── .env.example      Credential template (committed)
+        └── .env.local        Local credentials (gitignored, chmod 600)
+```
+
+## Credentials
+
+- Client ID and secret are written to `src/oauth/.env.local` during scaffold (file permissions `600`).
+- Re-fetch them any time with `brevo app credentials --app-id {{APP_ID}} --reveal-secret`.
+- `.env.local` is in `.gitignore` — **never commit it**.
+
+## Security
+
+- Never commit `src/oauth/.env.local` — it contains your client secret.
+- The test server uses a random `state` parameter for CSRF protection and binds to localhost only.
+- Access tokens are kept in process memory; restarting the server clears them.
+
+## Updating your app
+
+`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 upload
+```
+
+For example, to rename the app or add a redirect URL, edit `appName` or `auth.redirectUris` in `app-config.json`:
+
+```bash
+# 1. Edit app-config.json (e.g. change "appName", or append to "auth.redirectUris")
+# 2. Push the change
+brevo app upload
+```
+
+`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).
+
+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`.
+
+`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
+
+- [Brevo API Documentation](https://developers.brevo.com)
+- [Brevo CLI reference](https://developers.brevo.com/docs/cli-reference)
+- [Brevo CLI](https://github.com/getbrevo/brevo-cli)
+{{/if}}
+{{#if ui_app}}
+
+Brevo **UI app** — an action link that renders inside Brevo CRM records, scaffolded with the Brevo CLI.
+
+> **There is no local server to run and no code to install.** A UI app has no OAuth callback. Brevo opens a URL you already host, and this project is the app's configuration.
+
+## Setup
+
+1. Open `app-config.json` and check the `ui_app` block — the placement, its label, and the URL Brevo will open.
+
+2. Push it to Brevo (the CLI shows a diff of local vs. server first):
+
+   ```bash
+   brevo app upload
+   # or skip the confirmation: brevo app upload --yes
+   ```
+
+3. Make it available in an account, then open a CRM record to see it:
+
+   ```bash
+   brevo app install
+   # or target a specific sub-account: brevo app install <account-id>
+   ```
+
+   Remove it again with `brevo app uninstall` (same optional `<account-id>`).
+
+## Project structure
+
+```
+.
+├── app-config.json           App metadata + the `ui_app` block (the whole app)
+├── .gitignore                Ignores .env.local and build artifacts
+├── AGENTS.md                 AI agent guidance
+├── CLAUDE.md                 Claude Code guidance
+└── README.md                 (this file)
+```
+
+## The `ui_app` block
+
+`ui_app` is what makes this a UI app rather than an OAuth one, which is why `auth` is `{}` — leave it empty.
+
+`extension_type` sits at the root and picks how the app opens:
+
+| Value | What it does | Destination field |
+|-------|--------------|-------------------|
+| `actionLink` | Opens your URL in a new tab | `redirect_link` |
+| `iframeExtension` | Embeds your URL in a modal | `modal_iframe_url` |
+
+Each entry in `surface_point_list` is one placement, with its own text and destination:
+
+| Key | Required | Notes |
+|-----|----------|-------|
+| `surface_point_name` | yes | Where it appears, as a dotted slug — e.g. `contactDetails.header.menu` |
+| `label` | yes | Max 48 chars — the menu entry's text, or a card's button |
+| `more_info` | no | Max 255 chars — the menu entry's second line, or a card's description |
+| `redirect_link` | for `actionLink` | `https://` (or `http://localhost`) |
+| `modal_iframe_url` | for `iframeExtension` | `https://` (or `http://localhost`) |
+| `context` | no | Narrows the record context Brevo sends |
+| `size` | no | `{ "width": "280px", "height": "160px" }` — `px`, or `%` up to 100 |
+
+A card's title is the app name — there is no field for it. Don't add `link_target`: the CLI sets it on upload, and a copy in this file shows up as drift you can't clear.
+
+## Record context
+
+Brevo appends the record context to your URL as **query parameters** — the path is never templated. For example:
+
+```
+https://example.com/open?recordId=123&recordType=contact&accountId=456
+```
+
+These values reach you through the browser, so validate them like any other user input.
+
+## Adding a placement
+
+`brevo app create` sets up one. To add another, append a `surface_point_list` entry with its own `label` and destination, then:
+
+```bash
+brevo app upload
+```
+
+Slot names are checked by Brevo, not locally — `brevo app upload` fails and names any slot that isn't registered.
+
+## Updating your app
+
+`brevo app upload` has no edit flags — it always pushes the full contents of `app-config.json`. To change the app's name, label, destination or placement, edit the file and run:
+
+```bash
+brevo app upload
+```
+
+It fetches the current server state first and shows a diff before pushing — review it before confirming (or pass `--yes` to skip the prompt).
+
+`brevo app upload` has no `--app-id` flag either: it always resolves the app from this directory's `app-config.json`. To manage a different app, `cd` into that app's project directory.
+
+## Docs
+
+- [Brevo API Documentation](https://developers.brevo.com)
+- [Brevo CLI reference](https://developers.brevo.com/docs/cli-reference)
+- [Brevo CLI](https://github.com/getbrevo/brevo-cli)
+{{/if}}

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}}
   },
 };