create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/deliverable-fulfillment.ts

@@ -387,7 +387,7 @@ export async function sendCompletionEmail(
 
 export async function fulfillDeliverable(
   input: FulfillDeliverableInput,
-): Promise<void> {
+): Promise<{ grantId: string } | undefined> {
   const {
     siteId,
     flowSlug,
@@ -403,7 +403,7 @@ export async function fulfillDeliverable(
   // the call on this being present; re-checking here is defense in depth,
   // never load-bearing for the "no block → no call" AC4 regression floor.
   const block = configSnapshot.deliverables;
-  if (!block) return;
+  if (!block) return undefined;
 
   const logCtx = { siteId, flowSlug, sessionId };
 
@@ -412,7 +412,7 @@ export async function fulfillDeliverable(
   const entry = resolveEntry(block.assets, segment);
   if (!entry) {
     logOutcome(logCtx, "no_entry");
-    return;
+    return undefined;
   }
 
   // FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset: a per-lead
@@ -439,7 +439,7 @@ export async function fulfillDeliverable(
     });
     if (!instance) {
       logOutcome(logCtx, "playbook_missing");
-      return;
+      return undefined;
     }
     assetId = entry.assetKey;
   } else {
@@ -464,6 +464,13 @@ export async function fulfillDeliverable(
       assetId = resolvedAssetId;
       grantWorkspaceId = workspaceId;
     } else {
+      // #8848 D3 (SEC-8848-B) — a `deliverable` flow resolves against the
+      // Asset store only: it is new, so it has no legacy key to keep, and the
+      // legacy store also holds the founders' signup CSVs.
+      if (configSnapshot.deliverable !== undefined) {
+        logOutcome(logCtx, "asset_missing");
+        return undefined;
+      }
       // #6310 D2/D3 — legacy fallback. A missing row (config references an
       // un-uploaded key) → same skip-and-log posture as before.
       // #6257 — the LEGACY store's read, scoped by the same resolved
@@ -476,7 +483,7 @@ export async function fulfillDeliverable(
 
       if (!asset) {
         logOutcome(logCtx, "asset_missing");
-        return;
+        return undefined;
       }
       assetId = asset.id;
     }
@@ -527,6 +534,7 @@ export async function fulfillDeliverable(
     defaultLocale: configSnapshot.defaultLocale,
     copy: block.copy,
   });
+  return { grantId: grant.id };
 }
 
 // ─── #3998 D3 — resend: reuses the existing grant id, never mints ───────────────

package/templates/apps/api/src/services/entitlements.ts

@@ -15,15 +15,24 @@
  * foundation fills `features` + `limits.static` (tier + seat count) and returns
  * `limits.metered` as the reserved empty shape FEAT-047 (#3679) fills — this
  * spec builds NO metering engine (spec D5).
+ *
+ * #9067 D5 — the Billing tab's plan card also reads here: the licence expiry,
+ * the Organization's one open plan Checkout, and the customer's billing
+ * summary. That summary is the one Stripe read this resolver makes, through
+ * `lib/stripe.ts`.
  */
-import type { Entitlements } from "@working-theory/license";
+import { checkLicense, type Entitlements } from "@working-theory/license";
+import { logger } from "@working-theory/observability";
 import {
   MAGNET_KIND_MIN_RANK,
+  orgBillingDetailsSchema,
   planRank,
   type FlowConfig,
+  type OrgBillingDetails,
 } from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
+import { readCustomerBillingSummary } from "../lib/stripe.js";
 
 /**
  * Feature flags unlocked per tier. Free unlocks none; every paid tier unlocks
@@ -180,3 +189,150 @@ export async function isBillingCustomerAnOrganization(
   });
   return org !== null;
 }
+
+/**
+ * #9067 D5 — the deployment licence's expiry, as an ISO string, or `null`
+ * for a keyless, expired or invalid licence. The trial state's date
+ * (C2). Never throws: a failed read is `null`.
+ */
+export async function resolveLicenseExpiresAt(): Promise<string | null> {
+  try {
+    const license = await checkLicense();
+    return license.expiresAt?.toISOString() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #9067 D13 — the one plan Checkout this Organization has open, or `null`.
+ * Server-side only: the session id is never served. An unknown
+ * Organization reads `null`.
+ */
+export async function readOrgPlanCheckoutSession(
+  organizationId: string,
+): Promise<string | null> {
+  const org = await prisma.organization.findUnique({
+    where: { id: organizationId },
+    select: { planCheckoutSessionId: true },
+  });
+  return org?.planCheckoutSessionId ?? null;
+}
+
+/**
+ * #9067 D3 step 9b — record the plan Checkout the route just opened, as one
+ * compare-and-set: only while the column still holds `expected` and no
+ * customer is bound. Answers whether one row moved; throws on a database
+ * error.
+ */
+export async function setOrgPlanCheckoutSession(
+  organizationId: string,
+  expected: string | null,
+  next: string,
+): Promise<boolean> {
+  const { count } = await prisma.organization.updateMany({
+    where: { id: organizationId, planCheckoutSessionId: expected, billingCustomerId: null },
+    data: { planCheckoutSessionId: next },
+  });
+  return count === 1;
+}
+
+/**
+ * #9067 7b (code review) — bind the Organization to the customer a COMPLETED
+ * plan Checkout created, when the webhook's bind never landed (a lost event,
+ * a database error the webhook swallowed). The same guarded compare-and-set
+ * the webhook runs: only while the column still holds `sessionId` and no
+ * customer is bound, and it clears the session. Answers whether one row
+ * moved; throws on a database error.
+ */
+export async function bindOrgPlanCheckout(
+  organizationId: string,
+  sessionId: string,
+  customerId: string,
+): Promise<boolean> {
+  const { count } = await prisma.organization.updateMany({
+    where: { id: organizationId, planCheckoutSessionId: sessionId, billingCustomerId: null },
+    data: { billingProvider: "stripe", billingCustomerId: customerId, planCheckoutSessionId: null },
+  });
+  return count === 1;
+}
+
+/** How long one customer's summary is reused, a failure included (#9067 NFR-1). */
+export const ORG_BILLING_SUMMARY_TTL_MS = 60_000;
+/** The most customers held at once; the oldest entry is evicted at the cap. */
+export const ORG_BILLING_SUMMARY_CACHE_MAX = 2_000;
+/** The longest one summary read may take before the keys are left absent (NFR-2). */
+export const ORG_BILLING_SUMMARY_TIMEOUT_MS = 3_000;
+
+type OrgBillingSummaryKeys = Partial<Pick<OrgBillingDetails, "renewsAt" | "sites" | "paymentMethod">>;
+
+/** Per customer: the settled keys and when they expire. Insertion order is age. */
+const orgBillingSummaryCache = new Map<string, { keys: OrgBillingSummaryKeys; expiresAt: number }>();
+/** Per customer: the one read in flight, joined by every concurrent miss. */
+const orgBillingSummaryInFlight = new Map<string, Promise<OrgBillingSummaryKeys>>();
+
+/**
+ * #9067 D5 — the Organization customer's renewal date, site count and card,
+ * from the cache when fresh, else one read shared by every concurrent caller
+ * of the same customer. The member read's wrapper (`services/subscription.ts`),
+ * rebuilt here because importing it would be a cycle. A throw or a timeout
+ * answers `{}` (every key absent) and is cached like a success; a value
+ * outside `orgBillingDetailsSchema`'s bounds is `null`.
+ */
+export async function readOrgBillingSummary(customerId: string): Promise<OrgBillingSummaryKeys> {
+  const cached = orgBillingSummaryCache.get(customerId);
+  if (cached && cached.expiresAt > Date.now()) return cached.keys;
+  const pending = orgBillingSummaryInFlight.get(customerId);
+  if (pending) return pending;
+
+  const read = settleOrgBillingSummary(customerId).then((keys) => {
+    orgBillingSummaryCache.delete(customerId);
+    if (orgBillingSummaryCache.size >= ORG_BILLING_SUMMARY_CACHE_MAX) {
+      const oldest = orgBillingSummaryCache.keys().next().value;
+      if (oldest !== undefined) orgBillingSummaryCache.delete(oldest);
+    }
+    orgBillingSummaryCache.set(customerId, {
+      keys,
+      expiresAt: Date.now() + ORG_BILLING_SUMMARY_TTL_MS,
+    });
+    return keys;
+  });
+  // Cleared however the read ends, so a rejection is never served forever.
+  void read.finally(() => orgBillingSummaryInFlight.delete(customerId)).catch(() => undefined);
+  orgBillingSummaryInFlight.set(customerId, read);
+  return read;
+}
+
+async function settleOrgBillingSummary(customerId: string): Promise<OrgBillingSummaryKeys> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timedOut = new Promise<"timeout">((resolve) => {
+      timer = setTimeout(() => resolve("timeout"), ORG_BILLING_SUMMARY_TIMEOUT_MS);
+    });
+    const summary = await Promise.race([readCustomerBillingSummary(customerId), timedOut]);
+    if (summary === "timeout") throw new Error("timeout");
+    const { shape } = orgBillingDetailsSchema;
+    const renewsAt = shape.renewsAt.safeParse(summary.renewsAt);
+    const sites = shape.sites.safeParse(summary.sites);
+    const paymentMethod = shape.paymentMethod.safeParse(summary.paymentMethod);
+    return {
+      renewsAt: renewsAt.success ? (renewsAt.data ?? null) : null,
+      sites: sites.success ? (sites.data ?? null) : null,
+      paymentMethod: paymentMethod.success ? (paymentMethod.data ?? null) : null,
+    };
+  } catch {
+    logger.warn(
+      { route: "billing", outcome: "summary_unavailable" },
+      "[billing] organization billing summary unavailable",
+    );
+    return {};
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Test seam: forget every cached and in-flight Organization summary. */
+export function __resetOrgBillingSummaryCache(): void {
+  orgBillingSummaryCache.clear();
+  orgBillingSummaryInFlight.clear();
+}