create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/routes/leads/index.ts

@@ -57,9 +57,10 @@
  * file leaves nothing to find, and its retry writes again. `subscribe` and
  * `callback` never read the header. The key is never logged or echoed.
  *
- * CONTACT TERMS ACCEPTANCE (#8730). A `submit` whose `source` is a contact
- * source (`isContactLeadSource` in @working-theory/validation:
- * `contact-form`, `conversational-intake`, `flow:contact`) must carry a
+ * CONTACT TERMS ACCEPTANCE (#8730). A `submit` whose `source` is a
+ * consent-bearing source (`isConsentLeadSource` in @working-theory/validation:
+ * the contact sources `contact-form`, `conversational-intake`, `flow:contact`,
+ * and since #9130 the Free apply page's `flow:job-application`) must carry a
  * top-level `consent: true` — the boolean, nothing else — or it is
  * `400 consent_required` before the tenant read or any write. An accepted one
  * gets `payload.consent = { statement, acceptedAt }` written HERE, replacing
@@ -110,7 +111,7 @@
 import { track } from "@working-theory/analytics/server";
 import {
   CONTACT_FORM_TERMS_STATEMENT,
-  isContactLeadSource,
+  isConsentLeadSource,
   type LeadSubmitNext,
 } from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
@@ -156,17 +157,18 @@ function liftString(
   return (typeof fromPayload === "string" ? fromPayload : topLevel) as string;
 }
 
-/** #8730 — the refusal a contact lead without terms acceptance gets. */
+/** #8730, #9130 — the refusal a consent-bearing lead without terms acceptance gets. */
 const CONSENT_REQUIRED_BODY = {
   error: "consent_required",
-  message: "Accept the terms to send a contact message.",
+  message: "Accept the terms to send this form.",
 } as const;
 
 /**
- * #8730 D3 — the accepted terms, recorded by the server on a contact lead's
- * payload, replacing any `consent` the client wrote there. Only a plain
- * object payload is stamped: anything else is left for `routeLead`'s schema
- * to refuse, never spread into an object that would then pass it.
+ * #8730 D3, #9130 — the accepted terms, recorded by the server on a
+ * consent-bearing lead's payload, replacing any `consent` the client wrote
+ * there. Only a plain object payload is stamped: anything else is left for
+ * `routeLead`'s schema to refuse, never spread into an object that would then
+ * pass it.
  */
 function withConsentRecord(payload: unknown, acceptedAt: string): unknown {
   if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
@@ -205,7 +207,7 @@ function buildInput(
       siteId: workspaceId,
       source: body["source"] as string,
       email: liftString(body, payload, "email"),
-      payload: isContactLeadSource(body["source"])
+      payload: isConsentLeadSource(body["source"])
         ? (withConsentRecord(payload, receivedAt) as Record<string, unknown>)
         : payload,
     };
@@ -246,11 +248,12 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
     fastify.post(`/v1/leads/${kind}`, async (request, reply) => {
       const body = request.body as Record<string, unknown>;
 
-      // #8730 D1 — a contact lead carries the visitor's terms acceptance, or
-      // it is refused before the tenant read and any write.
+      // #8730 D1, #9130 — a contact lead or a job application carries the
+      // visitor's terms acceptance, or it is refused before the tenant read
+      // and any write.
       if (
         kind === "submit" &&
-        isContactLeadSource(body?.["source"]) &&
+        isConsentLeadSource(body?.["source"]) &&
         body?.["consent"] !== true
       ) {
         return reply.status(400).send(CONSENT_REQUIRED_BODY);

package/templates/apps/api/src/routes/webhooks/README.md

@@ -199,6 +199,72 @@ through `metadata.site`.
   site, which silences the hub's dunning record for that subscription — the
   same key can already cancel or re-price it outright.
 
+## Per-Organization endpoint (#8932)
+
+`POST /v1/webhooks/stripe/:connectionToken` (`stripe-offerings.ts`) is the
+receiver for one Organization's own Stripe connection — the Offerings money
+path (spec `docs/specs/8932-the-per-organization-stripe-webhook-spec.md`,
+contract `docs/specs/8879-the-offerings-security-contract-key-spec.md` W1,
+W3–W11, G5, T8). The 43-character token selects one `StripeConnection` row
+(`findStripeConnectionByWebhookToken`, #8907); that row's decrypted secret
+verifies the signature through `verifyWebhookSignatureKeyless` (no env key),
+and its `organizationId` is the only Organization the event can act for.
+Registered beside the legacy route on every build, with its own 100/min
+per-IP bucket; the commerce claim is read at call time.
+
+**The ladder** — the first step that answers ends the request; every `200`
+body is `{ received: true }` and the outcome is the log line's only:
+
+| #    | Step                                                                                                                                                                                                                | Answer                                                                                     | Seen     |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------- |
+| 1    | the token resolves to no row (or is malformed)                                                                                                                                                                      | `404 not-found`, logs nothing                                                              | no       |
+| 1a   | the token lookup rejects                                                                                                                                                                                            | `503 webhook-unavailable`                                                                  | no       |
+| 2    | the row has no usable secret                                                                                                                                                                                        | `503 webhook-not-configured`                                                               | no       |
+| 3–6  | signature settled, then the claim (as the legacy route): `undetermined` → `503` + `Retry-After: 300`; `unclaimed` → signed `200 dropped_no_commerce_claim`, unsigned the module-disabled `404`; then the held `400` | as stated                                                                                  | no       |
+| 7    | `event.livemode` is not the row's mode                                                                                                                                                                              | `200 livemode_mismatch`                                                                    | no       |
+| 8    | not `checkout.session.completed` / `.async_payment_succeeded` on a session object                                                                                                                                   | `200 ignored_type`                                                                         | no       |
+| 9–11 | the hub's session record (#8930): rejects / unreadable / none                                                                                                                                                       | `503 record-unavailable` / `500 record-unreadable` / `200 unrecorded`                      | no       |
+| 12   | another Organization's record, or `metadata.site` is not the record's workspace                                                                                                                                     | `200 foreign_organization`                                                                 | no       |
+| 13   | the record's mode is not the row's                                                                                                                                                                                  | `200 livemode_mismatch`                                                                    | no       |
+| 14   | already seen for this Organization                                                                                                                                                                                  | `200 duplicate`                                                                            | —        |
+| 15   | a `completed` session neither `paid` nor `no_payment_required`                                                                                                                                                      | `200 unpaid`                                                                               | yes      |
+| 16   | the connection's client or its `listLineItems` call fails                                                                                                                                                           | `503 stripe-unavailable` (never the env key)                                               | no       |
+| 17   | not exactly one line item whose Price id is the record's                                                                                                                                                            | `200 offering_mismatch`                                                                    | yes      |
+| 18   | `routeLead` (below)                                                                                                                                                                                                 | `200 fulfilled` / `already_fulfilled` / `unfulfillable`, else `503 fulfilment-unavailable` | yes / no |
+
+**The lead.** One per session: `routeLead` with the idempotency key
+`"stripe-offerings " + sessionId` — a space, which no `Idempotency-Key`
+header can carry, so no anonymous lead can take the key first — and
+`offeringsCheckout: true`. Its offering is the record's FULL lookup key,
+never `metadata.ailk_offering`. A live session's lead is marked
+`spokeCheckout`, the hold #8793's `releaseHeldCheckoutPlan` releases at the
+buyer's verified first link; no path here writes `Person.planOffering`. A
+test-mode session's lead is written unmarked: no hold, purchase message,
+email or consent grant. A replay or a conflict on that key is
+`already_fulfilled`; a lead the database did not take is a `503`, so Stripe
+retries.
+
+**The legacy endpoint steps aside (W8).** `POST /v1/webhooks/stripe` acks
+any event carrying an `ailk_offering` key — in a session's metadata or any
+site-stamp source above — with `200 { received: true }` and
+`outcome: "offerings_path"`, **before** `markSeen`, and writes nothing.
+Every event without the key takes the legacy path unchanged.
+
+**Two dedup stores.** The legacy route keeps `hasSeen` / `markSeen`; the
+per-Organization route uses its own `hasSeenForOrganization` /
+`markSeenForOrganization`, keyed `<organizationId>:<eventId>`. Neither
+endpoint's store can swallow the other's event. Both are in-memory per
+instance; the per-Organization route's correctness rests on the lead's
+database key.
+
+**Logs.** Each line carries `organizationId`, `eventType`, an 8-character
+`eventIdPrefix` and `outcome` (fewer before an event is verified) — never
+the token, the secret, a full Stripe id, an email, a lookup key, a metadata
+value or Stripe product text. Request and error lines log the path with
+the token replaced whole by `:connectionToken` (`redactLogPath`).
+
+**W11.** No billing identity is bound from a connection's event.
+
 ## Dunning (#6034)
 
 Two arms record a per-subscriber lifecycle state so a failed renewal is no