@pplethai/cli 0.4.1 → 0.5.0

package/templates/golden-path/src/notify.ts

@@ -1,36 +1,82 @@
-// Audience-bound push notifications.
+// Push notifications: Broadcast and Direct.
 //
-// Your app sends *content* — a title and body, never phone numbers or user
-// ids — plus an optional path-only self-link. The platform resolves the
-// recipients server-side (this app's App Users ∩ its current publication-tier
-// audience), joins `linkPath` to this app's known entry, and enforces the
-// per-app rate limit. This is the whole privacy model: an app can reach the
-// people who use it, and no one else; and it can deep-link into itself, not
-// into another team's mini app.
+// Every send states its audience, and the two kinds follow from that:
 //
-// See docs/integration/today-sso-changes.md §6 for the contract.
+//   • Broadcast (การแจ้งเตือนทุกคน) — `{ kind: "all" }`, to everyone this app
+//     can reach: its App Users ∩ its current publication-tier audience.
+//   • Direct (การแจ้งเตือนรายบุคคล) — `{ kind: "direct", recipients }`, to the
+//     people this app names, by PPLE ID `sub` or mobile number.
+//
+// Naming narrows the audience and never widens it — the rule, and what
+// `not_reachable` may be read as, are in shared/api.ts. The privacy model in
+// one line: an app can reach the people who use it, say which of them it
+// means, and reach no one else; and it can deep-link into itself, not into
+// another team's mini app.
+//
+// See docs/integration/direct-notifications.md for the contract and
+// docs/adr/0017 for why naming recipients is safe but per-recipient *reasons*
+// are not.
 //
 // Wiring: the platform provisions NOTIFY_API_BASE and this app's own
 // NotificationApiKey as NOTIFY_API_KEY, so `POST {NOTIFY_API_BASE}/notifications`
-// lands on PPLE Today's audience-bound send route. The key is the whole
-// address — PPLE Today resolves it to this app and derives the audience from
-// that, so the request carries neither an app id nor any recipient.
+// lands on PPLE Today's send route. The key is the whole address — PPLE Today
+// resolves it to this app and derives the reachable set from that, so the
+// request carries no app id.
 //
 // The wire shape below is PPLE Today's, not this app's: your code passes the
-// friendlier `{ title, body, linkPath? }` and this is where it becomes
-// `{ content: { header, message }, linkPath? }`. Keeping that translation in
-// one place means the rest of the app never has to know the platform's
-// vocabulary.
-import type { Notification } from "../shared/api";
+// friendlier `{ audience, title, body, linkPath? }` and this is where it
+// becomes `{ audience, content: { header, message }, linkPath? }`. Keeping that
+// translation in one place means the rest of the app never has to know the
+// platform's vocabulary.
+import type { Notification, NotificationDelivery, NotificationRecipient } from "../shared/api";
 
 interface NotifyEnv {
   NOTIFY_API_BASE: string;
   NOTIFY_API_KEY?: string;
 }
 
+/**
+ * Every refusal this app can get back, named in terms a Builder can act on.
+ *
+ * - `notifications_not_configured` — no key bound (e.g. local dev).
+ * - `invalid_request` — the send itself was malformed: no audience, an
+ *   unknown `kind`, a `direct` send with no `recipients` array.
+ * - `invalid_recipients` — the list was: empty, over the 200 cap, or an entry
+ *   naming neither or both of `sub`/`phone`.
+ * - `idempotency_key_conflict` — that key was already used with a list of a
+ *   different length, so its stored outcome cannot be replayed onto this one.
+ * - `quota_exceeded` — **nothing was delivered.** Quota is checked up front
+ *   against the named count, so the call is rejected whole rather than
+ *   half-sent.
+ * - `not_permitted` — this key may not use this route.
+ * - `send_failed` — anything else.
+ */
+export type NotifyError =
+  | "notifications_not_configured"
+  | "invalid_request"
+  | "invalid_recipients"
+  | "idempotency_key_conflict"
+  | "quota_exceeded"
+  | "not_permitted"
+  | "send_failed";
+
+/**
+ * What the platform reports alongside a `quota_exceeded` refusal, so an app
+ * can back off rather than guess. Denominated in **deliveries**, not calls: a
+ * Direct send debits one unit per name it addressed (delivered or not), and a
+ * Broadcast debits its audience size.
+ */
+export interface NotifyQuota {
+  dailyQuota?: number;
+  remaining?: number;
+  /** When the budget resets (Asia/Bangkok midnight). */
+  resetAt?: string;
+}
+
 export type NotifyResult =
-  | { ok: true }
-  | { ok: false; status: number; error: string };
+  | { ok: true; audience: "all" }
+  | { ok: true; audience: "direct"; results: NotificationDelivery[] }
+  | { ok: false; status: number; error: NotifyError; quota?: NotifyQuota };
 
 export async function sendNotification(
   env: NotifyEnv,
@@ -48,17 +94,99 @@ export async function sendNotification(
       authorization: `Bearer ${env.NOTIFY_API_KEY}`,
       "content-type": "application/json",
     },
-    // Content (+ optional self-link). The audience is resolved by the platform.
     body: JSON.stringify({
+      // Stated on every send, including a broadcast. There is no shape of this
+      // request that leaves the audience to be guessed.
+      audience: input.audience,
       content: { header: input.title, message: input.body },
       ...(input.linkPath !== undefined ? { linkPath: input.linkPath } : {}),
+      ...(input.idempotencyKey !== undefined
+        ? { idempotencyKey: input.idempotencyKey }
+        : {}),
     }),
   });
 
-  if (res.ok) return { ok: true };
+  if (!res.ok) {
+    const error = errorFor(res.status);
+    const quota = error === "quota_exceeded" ? quotaOf(await readJson(res)) : undefined;
+    return { ok: false, status: res.status, error, ...(quota ? { quota } : {}) };
+  }
+
+  if (input.audience.kind === "all") return { ok: true, audience: "all" };
   return {
-    ok: false,
-    status: res.status,
-    error: res.status === 429 ? "rate_limited" : "send_failed",
+    ok: true,
+    audience: "direct",
+    results: zipResults(input.audience.recipients, await readJson(res)),
   };
 }
+
+/**
+ * The platform splits its refusals: schema-level ones answer 422 (its whole
+ * API validates uniformly, and this route does not get to be the exception),
+ * recipient-level ones answer 400. Both are refusals — none is a broadcast,
+ * none is a silent no-op — but a client that branches on 400 alone is wrong.
+ * The status table lives in docs/integration/direct-notifications.md.
+ */
+function errorFor(status: number): NotifyError {
+  switch (status) {
+    case 422:
+      return "invalid_request";
+    case 400:
+      return "invalid_recipients";
+    case 403:
+      return "not_permitted";
+    case 409:
+      return "idempotency_key_conflict";
+    case 429:
+      return "quota_exceeded";
+    default:
+      return "send_failed";
+  }
+}
+
+async function readJson(res: Response): Promise<unknown> {
+  return res.json().catch(() => null);
+}
+
+/**
+ * The three figures the contract says a 429 carries, read from the top level
+ * of the refusal body. If the platform ever nests them under an envelope, this
+ * is the one place to adjust — the refusal itself is reported either way.
+ */
+function quotaOf(body: unknown): NotifyQuota | undefined {
+  if (typeof body !== "object" || body === null) return undefined;
+  const { dailyQuota, remaining, resetAt } = body as Record<string, unknown>;
+  const quota: NotifyQuota = {
+    ...(typeof dailyQuota === "number" ? { dailyQuota } : {}),
+    ...(typeof remaining === "number" ? { remaining } : {}),
+    ...(typeof resetAt === "string" ? { resetAt } : {}),
+  };
+  return Object.keys(quota).length > 0 ? quota : undefined;
+}
+
+/**
+ * Pair each recipient this app named with what the platform said about it.
+ * The results come back in the order they were named, one per entry, so this
+ * pairs them by position and hands back the caller's *own* entry — ready to
+ * match onto the list the app holds.
+ *
+ * Two rules, both in the direction of not lying: a list of a different length
+ * is not the answer to this send, so none of it is trusted; and anything not
+ * affirmatively reported `delivered` is reported `not_reachable`. See
+ * shared/api.ts for what that status may and may not be read as.
+ */
+function zipResults(
+  recipients: readonly NotificationRecipient[],
+  body: unknown,
+): NotificationDelivery[] {
+  const reported = (body as { results?: unknown } | null)?.results;
+  const results =
+    Array.isArray(reported) && reported.length === recipients.length ? reported : [];
+  return recipients.map((recipient, i) => ({
+    recipient,
+    status:
+      (results[i] as { status?: unknown } | undefined)?.status === "delivered"
+        ? "delivered"
+        : "not_reachable",
+  }));
+}

package/templates/golden-path/test/harness.ts

@@ -17,8 +17,8 @@ export interface Fakes {
 /**
  * A copy of the Worker wired to fake PPLE ID / notification services (via an
  * injected fetch) and the real local D1 + R2 from the test runtime. Records
- * the requests sent to the notification endpoint so tests can assert the
- * content-only contract.
+ * the requests sent to the notification endpoint so tests can assert the wire
+ * shape — above all that every send states its audience.
  */
 export function makeHarness(fakes: Fakes = {}, envOverrides: Partial<Env> = {}) {
   const calls = { notify: [] as Request[] };

package/templates/golden-path/test/smoke.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import type { Note, UploadedFile } from "../shared/api";
+import type { Note, Notification, UploadedFile } from "../shared/api";
 import { makeHarness } from "./harness";
 
 describe("health", () => {
@@ -174,32 +174,123 @@ describe("R2 upload (files)", () => {
   });
 });
 
-describe("audience-bound notifications", () => {
+// Shaped like what the platform actually binds, so these tests exercise the
+// real `${base}/notifications` the Worker will call in production.
+const NOTIFY_ENV = {
+  NOTIFY_API_BASE: "https://today.test/external",
+  NOTIFY_API_KEY: "app-key",
+};
+
+/** A platform that accepts everything and reports every named entry delivered. */
+const accepts = (body: unknown = null) => ({
+  notify: () => (body === null ? new Response(null, { status: 202 }) : Response.json(body)),
+});
+
+describe("notifications: the audience is required", () => {
+  it("is a compile error to omit it, not a runtime one", () => {
+    // @ts-expect-error — `audience` is required. The dangerous bug in this
+    // feature is omission: a dropped field turning a message meant for one
+    // person into a message to every App User. The discriminated union kills
+    // it at the compiler, which is where it is cheapest.
+    const missingAudience: Notification = { title: "Hi", body: "there" };
+    expect(missingAudience).toBeTruthy();
+  });
+
+  it("refuses a send with no audience before it reaches the platform", async () => {
+    const h = makeHarness(accepts(), NOTIFY_ENV);
+    const res = await h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ title: "Hi", body: "there" }),
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: "invalid_body" });
+    // Never a broadcast, never a silent no-op.
+    expect(h.calls.notify).toHaveLength(0);
+  });
+
+  it("refuses an empty recipient list before it reaches the platform", async () => {
+    const h = makeHarness(accepts(), NOTIFY_ENV);
+    const res = await h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        audience: { kind: "direct", recipients: [] },
+        title: "Hi",
+        body: "there",
+      }),
+    });
+    expect(res.status).toBe(400);
+    expect(h.calls.notify).toHaveLength(0);
+  });
+
+  it("refuses more than 200 recipients rather than truncating them", async () => {
+    const h = makeHarness(accepts(), NOTIFY_ENV);
+    const res = await h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        audience: {
+          kind: "direct",
+          recipients: Array.from({ length: 201 }, (_, i) => ({ sub: `u-${i}` })),
+        },
+        title: "Hi",
+        body: "there",
+      }),
+    });
+    expect(res.status).toBe(400);
+    expect(h.calls.notify).toHaveLength(0);
+  });
+
+  it("refuses an entry naming both a sub and a phone", async () => {
+    const h = makeHarness(accepts(), NOTIFY_ENV);
+    const res = await h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        audience: {
+          kind: "direct",
+          recipients: [{ sub: "u-1", phone: "0812345678" }],
+        },
+        title: "Hi",
+        body: "there",
+      }),
+    });
+    expect(res.status).toBe(400);
+    expect(h.calls.notify).toHaveLength(0);
+  });
+});
+
+describe("Broadcast Notification (การแจ้งเตือนทุกคน)", () => {
   it("reports not-configured when no key is set", async () => {
     const h = makeHarness();
     const res = await h.request("/api/notify", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ title: "Hi", body: "there" }),
+      body: JSON.stringify({
+        audience: { kind: "all" },
+        title: "Hi",
+        body: "there",
+      }),
     });
     expect(res.status).toBe(503);
     expect(await res.json()).toMatchObject({ error: "notifications_not_configured" });
   });
 
-  it("sends content only (never phone numbers) to the platform endpoint", async () => {
-    const h = makeHarness(
-      { notify: () => new Response(null, { status: 202 }) },
-      // Shaped like what the platform actually binds, so the test exercises
-      // the real `${base}/notifications` the Worker will call in production.
-      { NOTIFY_API_BASE: "https://today.test/external", NOTIFY_API_KEY: "app-key" },
-    );
+  it("states its audience explicitly and names no one", async () => {
+    const h = makeHarness(accepts(), NOTIFY_ENV);
 
     const res = await h.request("/api/notify", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ title: "Event tonight", body: "Doors at 7" }),
+      body: JSON.stringify({
+        audience: { kind: "all" },
+        title: "Event tonight",
+        body: "Doors at 7",
+      }),
     });
     expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
 
     expect(h.calls.notify).toHaveLength(1);
     const sent = h.calls.notify[0]!;
@@ -207,21 +298,20 @@ describe("audience-bound notifications", () => {
     // PPLE Today's wire shape, which src/notify.ts translates into.
     const payload = await sent.json<Record<string, unknown>>();
     expect(payload).toEqual({
+      audience: { kind: "all" },
       content: { header: "Event tonight", message: "Doors at 7" },
     });
-    expect(JSON.stringify(payload)).not.toMatch(/phone|recipient|number/i);
+    expect(JSON.stringify(payload)).not.toMatch(/phone|recipient/i);
   });
 
   it("forwards optional linkPath on the platform wire shape", async () => {
-    const h = makeHarness(
-      { notify: () => new Response(null, { status: 202 }) },
-      { NOTIFY_API_BASE: "https://today.test/external", NOTIFY_API_KEY: "app-key" },
-    );
+    const h = makeHarness(accepts(), NOTIFY_ENV);
 
     const res = await h.request("/api/notify", {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({
+        audience: { kind: "all" },
         title: "Check-in open",
         body: "Tap to open the form",
         linkPath: "/check-in",
@@ -231,8 +321,144 @@ describe("audience-bound notifications", () => {
 
     const payload = await h.calls.notify[0]!.json<Record<string, unknown>>();
     expect(payload).toEqual({
+      audience: { kind: "all" },
       content: { header: "Check-in open", message: "Tap to open the form" },
       linkPath: "/check-in",
     });
   });
 });
+
+describe("Direct Notification (การแจ้งเตือนรายบุคคล)", () => {
+  const recipients = [{ sub: "u-42" }, { phone: "+66812345678" }];
+
+  const sendDirect = (h: ReturnType<typeof makeHarness>, extra: object = {}) =>
+    h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        audience: { kind: "direct", recipients },
+        title: "Reimbursement approved",
+        body: "Your claim was approved",
+        ...extra,
+      }),
+    });
+
+  it("names recipients by sub or phone and reports each one's outcome", async () => {
+    const h = makeHarness(
+      accepts({
+        results: [
+          { recipient: { sub: "u-42" }, status: "delivered" },
+          { recipient: { phone: "+66812345678" }, status: "not_reachable" },
+        ],
+      }),
+      NOTIFY_ENV,
+    );
+
+    const res = await sendDirect(h);
+    expect(res.status).toBe(200);
+    // Every named entry comes back, echoed as the caller named it, so a
+    // Builder can match a result straight onto the list it holds.
+    expect(await res.json()).toEqual({
+      ok: true,
+      results: [
+        { recipient: { sub: "u-42" }, status: "delivered" },
+        { recipient: { phone: "+66812345678" }, status: "not_reachable" },
+      ],
+    });
+
+    const payload = await h.calls.notify[0]!.json<Record<string, unknown>>();
+    expect(payload).toEqual({
+      audience: { kind: "direct", recipients },
+      content: {
+        header: "Reimbursement approved",
+        message: "Your claim was approved",
+      },
+    });
+  });
+
+  it("forwards an idempotencyKey so a retry after a timeout is safe", async () => {
+    const h = makeHarness(accepts({ results: [] }), NOTIFY_ENV);
+    await sendDirect(h, { idempotencyKey: "claim-123" });
+    const payload = await h.calls.notify[0]!.json<Record<string, unknown>>();
+    expect(payload).toMatchObject({ idempotencyKey: "claim-123" });
+  });
+
+  const unconfirmed = {
+    ok: true,
+    results: [
+      { recipient: { sub: "u-42" }, status: "not_reachable" },
+      { recipient: { phone: "+66812345678" }, status: "not_reachable" },
+    ],
+  };
+
+  it("never claims a delivery the platform did not confirm", async () => {
+    // A body this helper cannot read is not evidence of delivery.
+    const h = makeHarness(accepts({ unexpected: true }), NOTIFY_ENV);
+    expect(await (await sendDirect(h)).json()).toEqual(unconfirmed);
+  });
+
+  it("trusts none of a result list that is not one-per-named-entry", async () => {
+    // Results are paired by position, so a list of a different length is not
+    // the answer to this send — reading it would attribute someone's delivery
+    // to the wrong person.
+    const h = makeHarness(
+      accepts({ results: [{ recipient: { sub: "u-42" }, status: "delivered" }] }),
+      NOTIFY_ENV,
+    );
+    expect(await (await sendDirect(h)).json()).toEqual(unconfirmed);
+  });
+});
+
+describe("notification refusals map to legible errors", () => {
+  const refuses = (status: number, body: unknown = null) => ({
+    notify: () =>
+      body === null
+        ? new Response(null, { status })
+        : Response.json(body, { status }),
+  });
+
+  const send = (h: ReturnType<typeof makeHarness>) =>
+    h.request("/api/notify", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        audience: { kind: "direct", recipients: [{ sub: "u-42" }] },
+        title: "Hi",
+        body: "there",
+      }),
+    });
+
+  // The platform splits schema-level refusals (422) from recipient-level ones
+  // (400); a client that branches on 400 alone is wrong. See the status table
+  // in docs/integration/direct-notifications.md.
+  it.each([
+    [422, "invalid_request"],
+    [400, "invalid_recipients"],
+    [403, "not_permitted"],
+    [409, "idempotency_key_conflict"],
+    [429, "quota_exceeded"],
+    [500, "send_failed"],
+  ])("maps %i to %s", async (status, error) => {
+    const h = makeHarness(refuses(status), NOTIFY_ENV);
+    const res = await send(h);
+    expect(res.status).toBe(status);
+    expect(await res.json()).toMatchObject({ error });
+  });
+
+  it("passes the quota figures through on a 429 so an app can back off", async () => {
+    const h = makeHarness(
+      refuses(429, {
+        // Deliveries, not calls — the budget's denomination changed with
+        // Direct Notifications, and nothing was delivered by this call.
+        dailyQuota: 1000,
+        remaining: 3,
+        resetAt: "2026-08-15T00:00:00+07:00",
+      }),
+      NOTIFY_ENV,
+    );
+    expect(await (await send(h)).json()).toMatchObject({
+      error: "quota_exceeded",
+      quota: { dailyQuota: 1000, remaining: 3, resetAt: "2026-08-15T00:00:00+07:00" },
+    });
+  });
+});