services-integrations

Services & Integrations

Third-party service clients for the gateway app. See codebase-map for how these fit into the overall gateway request flow — this skill is the per-service detail.

The shared shape, once, so each service section below can just say "follows the pattern": every side-channel client (Brevo, Slack) is a never-throw HTTP wrapper —

async function callThing(...): Promise<boolean> {
  const key = getEnv().THING_API_KEY;
  if (!key) { console.warn("[thing] THING_API_KEY not set — skipping"); return false; }
  try {
    const res = await fetch(url, { ... , signal: AbortSignal.timeout(N) });
    if (!res.ok) { console.warn(`[thing] failed: ${res.status} ${(await res.text()).slice(0, 300)}`); return false; }
    return true;
  } catch (err) { console.warn("[thing] error", err); return false; }
}

No env var/token → warned no-op, not a throw. Non-2xx or a network error → warned false, not a throw. Error bodies are truncated to 300 chars in the warn log — don't expect full payloads there. New integrations should copy this shape rather than inventing a new failure contract.

Per-service patterns

Brevo (transactional email)

Entry file: apps/gateway/src/lib/brevo.ts. Single internal brevoPost() helper (follows the shape above) wraps all HTTP calls; two public functions call it: upsertBrevoContact() (POST /contacts) and sendBrevoTemplate() (POST /smtp/email).

• List/template IDs (BREVO_LIST_PRODUCT_USERS, BREVO_TEMPLATE_WELCOME, BREVO_TEMPLATE_NO_ACTIVATION, BREVO_TEMPLATE_FOLLOWUP_{CONNECT,PERMISSIONS,TRY_THIS}) are hardcoded constants, not env vars — they're managed in the Brevo console. Template params are flat strings; anything list-shaped is rendered to a string in code (listInProse) and the template owns every other word.
• isInternalEmail() checks the comma-separated INTERNAL_EXCLUDE_EMAILS env var (same env-side list the digest exclusion reads; values live in SSM/prod .env, never in source — this repo is public) plus the @datatorag.com domain, which is matched unconditionally in code; lifecycle emails must skip these.
• hasBrevoKey() lets callers check availability before doing other work (see Lifecycle below, which checks this before claiming a DB row).
• Env var: BREVO_API_KEY.