Weekly Sales Report: Code Does the Maths, AI Writes the Summary

# .env.example — names only, never values
GHL_API_BASE=https://services.leadconnectorhq.com
GHL_LOCATION_ID=
GHL_TOKEN=
ANTHROPIC_API_KEY=
SLACK_WEBHOOK_URL=

// src/ghl.ts
export interface Opp {
  status: "open" | "won" | "lost" | "abandoned";
  monetaryValue?: number;
  createdAt: string;
  lastStatusChangeAt?: string;
}

export function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable ${name}`);
  return value;
}

export async function fetchOpportunities(): Promise<Opp[]> {
  const all: Opp[] = [];
  for (let page = 1; page <= 50; page++) {
    const url = new URL("/opportunities/search", requireEnv("GHL_API_BASE"));
    url.searchParams.set("location_id", requireEnv("GHL_LOCATION_ID"));
    url.searchParams.set("status", "all");
    url.searchParams.set("limit", "100");
    url.searchParams.set("page", String(page));

    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${requireEnv("GHL_TOKEN")}`,
        Version: "v3", // the only value the current endpoint reference lists
        Accept: "application/json",
      },
    });
    if (!res.ok) throw new Error(`HighLevel returned ${res.status} on page ${page}`);

    const body = (await res.json()) as { opportunities: Opp[]; meta: { nextPage?: number | null } };
    all.push(...body.opportunities);
    if (!body.meta.nextPage) return all;
  }
  throw new Error("Stopped after 50 pages. Filter by pipeline or raise the cap on purpose.");
}

// src/metrics.ts
import type { Opp } from "./ghl";

export interface WeekMetrics {
  newDeals: number;
  won: number;
  lost: number;
  wonValue: number;
  winRatePct: number | null;
}

function inRange(iso: string | undefined, start: Date, end: Date): boolean {
  if (!iso) return false;
  const time = Date.parse(iso);
  return time >= start.getTime() && time < end.getTime();
}

export function weekMetrics(opps: Opp[], start: Date, end: Date): WeekMetrics {
  const closed = opps.filter((opp) => inRange(opp.lastStatusChangeAt, start, end));
  const won = closed.filter((opp) => opp.status === "won");
  const lost = closed.filter((opp) => opp.status === "lost");
  const decided = won.length + lost.length;
  return {
    newDeals: opps.filter((opp) => inRange(opp.createdAt, start, end)).length,
    won: won.length,
    lost: lost.length,
    wonValue: Math.round(won.reduce((sum, opp) => sum + (opp.monetaryValue ?? 0), 0)),
    winRatePct: decided === 0 ? null : Math.round((won.length / decided) * 100),
  };
}

// src/narrative.ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

export async function writeNarrative(metrics: Record<string, number | null>): Promise<string> {
  const response = await client.messages.create({
    model: "claude-haiku-5-5",
    max_tokens: 400,
    system:
      "You write a weekly sales summary for a team chat. Use only the numbers in the JSON. " +
      "Do not calculate, estimate or round any number, and do not mention dates. " +
      "Do not guess at causes. Write 2 short paragraphs of plain text.",
    messages: [{ role: "user", content: JSON.stringify(metrics) }],
  });
  return response.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("")
    .trim();
}

// src/guard.ts
export function numbersAreGrounded(text: string, metrics: Record<string, number | null>): boolean {
  const allowed = new Set(
    Object.values(metrics)
      .filter((value): value is number => value !== null)
      .map((value) => String(Math.abs(value))),
  );
  const found = text.match(/[0-9][0-9,]*(?:[.][0-9]+)?/g) ?? [];
  return found.every((raw) => allowed.has(raw.replace(/,/g, "")));
}

// src/slack.ts
import { requireEnv } from "./ghl";

export async function postToSlack(text: string, dryRun: boolean): Promise<void> {
  if (dryRun) {
    console.log(text);
    return;
  }
  const res = await fetch(requireEnv("SLACK_WEBHOOK_URL"), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  if (!res.ok) throw new Error(`Slack returned ${res.status}: ${await res.text()}`);
}

# .github/workflows/weekly-report.yml
name: weekly-sales-report
on:
  schedule:
    - cron: "7 8 * * 1"
      timezone: "America/New_York"
  workflow_dispatch:
concurrency: weekly-sales-report
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npx tsx src/report.ts
        env:
          GHL_API_BASE: ${{ secrets.GHL_API_BASE }}
          GHL_LOCATION_ID: ${{ secrets.GHL_LOCATION_ID }}
          GHL_TOKEN: ${{ secrets.GHL_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}