@simplelayer/graniteer-core 0.0.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/index.js +2 -2
  2. package/package.json +98 -15
  3. package/src/adminBookingCredit.test.ts +451 -0
  4. package/src/adminBookingCredit.ts +239 -0
  5. package/src/availability.test.ts +25 -0
  6. package/src/availability.ts +201 -0
  7. package/src/bookingHoldReclaim.ts +94 -0
  8. package/src/checkoutSessionParams.ts +56 -0
  9. package/src/commonsContract.ts +175 -0
  10. package/src/conductorAdmin.ts +141 -0
  11. package/src/email-templates/email-change.tsx +92 -0
  12. package/src/email-templates/invite.tsx +79 -0
  13. package/src/email-templates/reauthentication.tsx +60 -0
  14. package/src/functions/admin-cancel-membership.ts +311 -0
  15. package/src/functions/admin-change-membership-plan.ts +308 -0
  16. package/src/functions/admin-charge-guest-print.ts +229 -0
  17. package/src/functions/admin-correct-booking.ts +333 -0
  18. package/src/functions/admin-create-commons-event.ts +244 -0
  19. package/src/functions/admin-debug-boldsign-doc.ts +93 -0
  20. package/src/functions/admin-door-write.ts +272 -0
  21. package/src/functions/admin-mark-booking-paid.ts +203 -0
  22. package/src/functions/admin-photo-upload.ts +128 -0
  23. package/src/functions/admin-remove-team-member.ts +150 -0
  24. package/src/functions/admin-reset-mfa.ts +138 -0
  25. package/src/functions/admin-reverse-coupon-redemption.ts +98 -0
  26. package/src/functions/admin-send-commons-agreement.ts +214 -0
  27. package/src/functions/admin-set-credit-amount.ts +123 -0
  28. package/src/functions/admin-skip-commons-contract.ts +165 -0
  29. package/src/functions/admin-undo-membership-cancel.ts +144 -0
  30. package/src/functions/admin-wall-photo-write.ts +141 -0
  31. package/src/functions/boldsign-sender-identity.ts +114 -0
  32. package/src/functions/booking-availability.ts +419 -0
  33. package/src/functions/booking-member-preview.ts +136 -0
  34. package/src/functions/day-pass-status.ts +89 -0
  35. package/src/functions/dayStatus.ts +71 -0
  36. package/src/functions/diag-webpush-test.ts +45 -0
  37. package/src/functions/event-access-store.ts +309 -0
  38. package/src/functions/ezeep-print-webhook.ts +213 -0
  39. package/src/functions/ezeep-usage-reconcile.ts +299 -0
  40. package/src/functions/get-signing-link.ts +211 -0
  41. package/src/functions/guest-print-setup-confirm.ts +128 -0
  42. package/src/functions/guest-print-submit.ts +149 -0
  43. package/src/functions/luma-webhook.ts +165 -0
  44. package/src/functions/migration-collision-alert.copy.ts +232 -0
  45. package/src/functions/migration-collision-alert.test.ts +349 -0
  46. package/src/functions/migration-collision-alert.ts +232 -0
  47. package/src/functions/office-assignment-end.ts +146 -0
  48. package/src/functions/portal-booking-access.ts +95 -0
  49. package/src/functions/portal-list-invoices.ts +99 -0
  50. package/src/functions/print-billing-recover.ts +97 -0
  51. package/src/functions/print-billing-run.ts +183 -0
  52. package/src/functions/public-facts.ts +168 -0
  53. package/src/functions/space-availability-range.acceptance.test.ts +161 -0
  54. package/src/functions/space-availability-range.ts +142 -0
  55. package/src/functions/sync-gcal-blackouts.ts +298 -0
  56. package/src/functions/timetable-event-register.ts +162 -0
  57. package/src/functions/timetable-event-status.ts +90 -0
  58. package/src/functions/timetable-spaces.ts +219 -0
  59. package/src/functions/touch-pass-reconciler.ts +689 -0
  60. package/src/functions/virtual-onboarding-purge.ts +134 -0
  61. package/src/functions/virtual-onboarding-submit.ts +315 -0
  62. package/src/functions/voice-inquiry.test.ts +301 -0
  63. package/src/functions/voice-inquiry.ts +198 -0
  64. package/src/functions/voice-tour-availability.ts +204 -0
  65. package/src/gcalSync.ts +142 -0
  66. package/src/ghlNote.ts +34 -0
  67. package/src/ghlTask.ts +48 -0
  68. package/src/ghlVoiceInquiry.ts +90 -0
  69. package/src/guestPrintCapture.test.ts +722 -0
  70. package/src/guestPrintCapture.ts +538 -0
  71. package/src/lumaGhl.ts +195 -0
  72. package/src/membership.ts +109 -0
  73. package/src/money.ts +36 -0
  74. package/src/ops.ts +97 -0
  75. package/src/pacificDate.ts +34 -0
  76. package/src/policyAcknowledgment.test.ts +50 -0
  77. package/src/policyAcknowledgment.ts +96 -0
  78. package/src/portalSession.ts +46 -0
  79. package/src/pricing.test.ts +660 -0
  80. package/src/pricing.ts +1025 -0
  81. package/src/printBilling.test.ts +750 -0
  82. package/src/printBilling.ts +891 -0
  83. package/src/printBillingAdapters.ts +169 -0
  84. package/src/printCorrections.test.ts +348 -0
  85. package/src/printCorrections.ts +496 -0
  86. package/src/rateLimit.ts +82 -0
  87. package/src/referralCredits.test.ts +31 -0
  88. package/src/referralCredits.ts +34 -0
  89. package/src/referralGrant.ts +321 -0
  90. package/src/rescheduleCredit.test.ts +521 -0
  91. package/src/rescheduleCredit.ts +337 -0
  92. package/src/reservationWifiCode.test.ts +69 -0
  93. package/src/reservationWifiCode.ts +81 -0
  94. package/src/retellCallAnalyzed.test.ts +167 -0
  95. package/src/retellCallAnalyzed.ts +113 -0
  96. package/src/retellSignature.test.ts +137 -0
  97. package/src/retellSignature.ts +82 -0
  98. package/src/slackAlert.ts +38 -0
  99. package/src/supabaseTestFakes.ts +131 -0
  100. package/src/tier1Agreement.ts +125 -0
@@ -0,0 +1,538 @@
1
+ // Guest print-payment capture (D5).
2
+ //
3
+ // Design: PRINT-GUEST-CAPTURE-DESIGN.md v1 (not committed to this repo --
4
+ // design docs for this project live outside git; see the D5 build report).
5
+ //
6
+ // Kyle answered GATE-0194 with option (B): a print job itself creates the
7
+ // "known contact" qualifying record -- a guest becomes portal-account-
8
+ // eligible simply by showing up to print, no prior day-pass/booking purchase
9
+ // required. This module is the decision core for that flow's two new Stripe
10
+ // primitives, neither of which existed anywhere in this codebase before D5:
11
+ //
12
+ // 1. A SetupIntent, created at print-SUBMISSION time, before the job's
13
+ // actual cost is known -- so the guest's card is saved and reusable.
14
+ // 2. An off-session PaymentIntent, created and confirmed once the job's
15
+ // actual usage/cost IS known (from the existing ezeep print_jobs
16
+ // ingest -- see _shared/printBilling.ts for the analogous member-side
17
+ // flow this deliberately does NOT reuse; that system is subscription/
18
+ // invoice-based and assumes an existing membership + Stripe customer
19
+ // with a subscription, neither of which a walk-in guest has).
20
+ //
21
+ // THIS MODULE MAKES NO NETWORK CALLS AND IMPORTS NOTHING. Stripe and the
22
+ // database both arrive as injected, structurally-typed dependencies (the
23
+ // same discipline as _shared/printBilling.ts's P2 design) so the whole of
24
+ // the money logic is exercisable against hand-rolled stubs with zero network
25
+ // risk. The real Stripe/Supabase clients are wired up only in the three
26
+ // edge functions that import this: guest-print-submit, guest-print-setup-
27
+ // confirm, and admin-charge-guest-print.
28
+ //
29
+ // Deliberately NOT built on supabase/functions/stripe-webhook/index.ts
30
+ // (2400+ lines, a shared money-path router, explicitly out of scope to
31
+ // touch for this feature). The SetupIntent confirmation is instead picked
32
+ // up by a dedicated confirm callback (guest-print-setup-confirm) that the
33
+ // frontend calls after Stripe.js confirms the SetupIntent client-side --
34
+ // and this module never trusts that client-side report on its own; it
35
+ // always re-retrieves the SetupIntent from Stripe first and acts only on
36
+ // what Stripe itself says. A `setup_intent.succeeded` webhook handler would
37
+ // be a reasonable defense-in-depth follow-up (covers a guest who confirms
38
+ // the card but the confirm-callback network call never lands) but is
39
+ // explicitly left for a future pass -- see the D5 build report.
40
+
41
+ export const GUEST_BILLING_CODE_ALPHABET = '23456789ABCDEFGHJKLMNPQRSTUVWXYZ'; // no 0/O/1/I
42
+ export const GUEST_BILLING_CODE_LENGTH = 6;
43
+
44
+ export function guestPrintSetupIntentKey(submissionId: string): string {
45
+ return `gc-guest-print-si-${submissionId}`;
46
+ }
47
+ // Amount is part of the key (not just the submission id) so a legitimate
48
+ // retry with a CORRECTED amount after a failed/stuck attempt is never
49
+ // silently blocked by Stripe reusing the first attempt's stored response for
50
+ // 24h against an identical key. A retry with the SAME amount still
51
+ // idempotently collapses onto the original attempt, which is the behavior
52
+ // we want. See D5 build report / adversarial review round 1, B3.
53
+ export function guestPrintChargeKey(submissionId: string, amountCents: number): string {
54
+ return `gc-guest-print-pi-${submissionId}-${amountCents}`;
55
+ }
56
+
57
+ // ---------------------------------------------------------------- types --
58
+
59
+ export interface GpStripeCustomer {
60
+ id: string;
61
+ }
62
+ export interface GpSetupIntent {
63
+ id: string;
64
+ status: string;
65
+ client_secret: string | null;
66
+ payment_method: string | { id: string } | null;
67
+ }
68
+ export interface GpPaymentIntent {
69
+ id: string;
70
+ status: string;
71
+ /** Required so the already-succeeded recovery branch in
72
+ * chargeGuestPrintJob can record what the PRIOR PaymentIntent actually
73
+ * charged, not what the CURRENT (possibly different, e.g. a staff
74
+ * correction) amountCents parameter says -- see that branch's comment. */
75
+ amount: number;
76
+ }
77
+
78
+ /** Structural on purpose: a hand-rolled test fake satisfies this without
79
+ * pulling in the Stripe SDK, exactly like _shared/printBilling.ts's
80
+ * PrintStripeLike. */
81
+ export interface GuestPrintStripeLike {
82
+ customers: {
83
+ search(params: { query: string; limit: number }): Promise<{ data: GpStripeCustomer[] }>;
84
+ list(params: { email: string; limit: number }): Promise<{ data: GpStripeCustomer[] }>;
85
+ create(params: { email: string }): Promise<GpStripeCustomer>;
86
+ };
87
+ setupIntents: {
88
+ create(params: Record<string, unknown>, opts?: { idempotencyKey?: string }): Promise<GpSetupIntent>;
89
+ retrieve(id: string, params?: Record<string, unknown>): Promise<GpSetupIntent>;
90
+ };
91
+ paymentIntents: {
92
+ create(params: Record<string, unknown>, opts?: { idempotencyKey?: string }): Promise<GpPaymentIntent>;
93
+ /** Added for the B4 fix (round 2 review): before creating a NEW
94
+ * PaymentIntent for a submission that already has one on file, we must
95
+ * check whether that prior PI is still live (see chargeGuestPrintJob).
96
+ */
97
+ retrieve(id: string): Promise<GpPaymentIntent>;
98
+ };
99
+ }
100
+
101
+ /** The two statuses claimForCharge accepts as a valid claim source. A
102
+ * previously-failed charge attempt ('charge_failed') IS retryable; the
103
+ * pre-card 'failed' status is NOT (see the status-check constraint's
104
+ * comment in the migration). Exported as a single source of truth so the
105
+ * real SQL filter and any test double are provably testing the SAME list,
106
+ * not two hand-copies that can silently drift apart -- see round 2 review's
107
+ * test-vacuity finding on the original 'card_saved'/'charge_failed'
108
+ * hardcoding. */
109
+ export const CLAIMABLE_CHARGE_STATUSES: string[] = ['card_saved', 'charge_failed'];
110
+
111
+ /** The only prior-PaymentIntent statuses chargeGuestPrintJob treats as a
112
+ * genuinely dead end safe to create a fresh PaymentIntent alongside. This is
113
+ * deliberately an ALLOWLIST, not a denylist of known-still-live statuses --
114
+ * an unrecognized/future/malformed status must fail CLOSED (refuse) the same
115
+ * way the retrieve-throws branch above it already does, rather than fall
116
+ * through to a new charge just because it didn't match a hardcoded list of
117
+ * live statuses we happened to think of. Exported as a single source of
118
+ * truth mirroring CLAIMABLE_CHARGE_STATUSES above -- see D5 adversarial
119
+ * review, S10. */
120
+ export const DEAD_PRIOR_PI_STATUSES: string[] = ['canceled', 'requires_payment_method'];
121
+
122
+ export interface SubmissionRow {
123
+ id: string;
124
+ email: string;
125
+ status: string;
126
+ stripe_customer_id: string | null;
127
+ stripe_setup_intent_id: string | null;
128
+ stripe_payment_method_id: string | null;
129
+ /** Set by a PRIOR charge attempt (writebackCharged or writebackChargeFailed
130
+ * with a real PI id -- see B2). MUST be read and checked by
131
+ * chargeGuestPrintJob before ever creating a second PaymentIntent for
132
+ * this row -- see the B4 fix. */
133
+ stripe_payment_intent_id: string | null;
134
+ guest_billing_code: string;
135
+ }
136
+
137
+ /** Every DB write is one focused call so the money-moving step
138
+ * (claimForCharge) can be tested in isolation from the bookkeeping ones. */
139
+ export interface GuestPrintDbLike {
140
+ /** Insert the placeholder row BEFORE any Stripe call, so a row -- and
141
+ * therefore the portal-login "known contact" qualifying record -- exists
142
+ * even if the Stripe call that follows fails outright. Mirrors D3's M-14
143
+ * discipline of writing evidence before it can be lost to a crash. */
144
+ insertPending(args: { email: string; guestName: string | null; guestBillingCode: string }): Promise<string>;
145
+ attachStripeIds(id: string, customerId: string, setupIntentId: string): Promise<void>;
146
+ markCardSaved(id: string, paymentMethodId: string): Promise<void>;
147
+ markFailed(id: string, reason: string): Promise<void>;
148
+ getById(id: string): Promise<SubmissionRow | null>;
149
+ /** Atomic compare-and-swap: succeeds (returns true) ONLY if the row is
150
+ * currently 'card_saved' OR 'charge_failed' (a previously-failed charge
151
+ * attempt IS retryable -- see D5 adversarial review round 1, B3; the
152
+ * ORIGINAL 'failed' status stays reserved for a pre-card failure in
153
+ * submitGuestPrintJob, which is NOT retryable via this path since no card
154
+ * was ever saved), atomically advancing it to 'charging' in the same
155
+ * statement. Returns false -- NOT an error -- if another invocation
156
+ * already claimed it or the row isn't chargeable yet. This one guarantee
157
+ * is the entire double-charge guard for this feature: two concurrent
158
+ * charge attempts against the same submission cannot both win it, because
159
+ * the underlying UPDATE ... WHERE status = 'card_saved' can only ever
160
+ * match the row once. See the D5 build report for why this is enough
161
+ * here and D3's heavier write-once trigger (_shared/printBilling.ts) is
162
+ * not needed: this table has exactly one row per submission and exactly
163
+ * three callers touching it in sequence, not a shared contended resource
164
+ * with an independent recovery sweep racing live requests. */
165
+ claimForCharge(id: string): Promise<boolean>;
166
+ writebackCharged(id: string, amountCents: number, paymentIntentId: string): Promise<void>;
167
+ /** `paymentIntentId` is passed whenever Stripe actually returned a PI
168
+ * object, even one that never reached 'succeeded' (e.g. stuck on
169
+ * 'requires_action' from a 3DS challenge on an off-session charge). A
170
+ * real-but-non-succeeded PaymentIntent still exists live in Stripe and
171
+ * must be findable from this row afterward -- see D5 adversarial review
172
+ * round 1, B2. Omitted only when Stripe's create call itself threw and no
173
+ * PI object was ever returned at all. */
174
+ writebackChargeFailed(id: string, reason: string, paymentIntentId?: string): Promise<void>;
175
+ }
176
+
177
+ // ------------------------------------------------------------ pure helpers --
178
+
179
+ /** Caller supplies the randomness (crypto.getRandomValues in the real edge
180
+ * function) so this stays a pure, deterministically-testable function. */
181
+ export function generateGuestBillingCode(randomBytes: Uint8Array): string {
182
+ if (randomBytes.length < GUEST_BILLING_CODE_LENGTH) {
183
+ throw new Error(
184
+ `generateGuestBillingCode: need at least ${GUEST_BILLING_CODE_LENGTH} random bytes, got ${randomBytes.length}`,
185
+ );
186
+ }
187
+ let out = '';
188
+ for (let i = 0; i < GUEST_BILLING_CODE_LENGTH; i++) {
189
+ out += GUEST_BILLING_CODE_ALPHABET[randomBytes[i] % GUEST_BILLING_CODE_ALPHABET.length];
190
+ }
191
+ return out;
192
+ }
193
+
194
+ function pmId(ref: string | { id: string } | null): string | null {
195
+ if (!ref) return null;
196
+ return typeof ref === 'string' ? ref : ref.id;
197
+ }
198
+
199
+ /**
200
+ * Reuse-or-create a Stripe Customer by email. Verbatim-pattern copy of the
201
+ * search-then-list-then-create sequence in create-day-pass-checkout/index.ts
202
+ * and create-booking/index.ts: search first (fast path once indexed), fall
203
+ * back to list because Search is eventually consistent (~1 min) and would
204
+ * otherwise miss a customer created seconds ago by a different flow and
205
+ * create a duplicate.
206
+ */
207
+ export async function resolveGuestStripeCustomer(
208
+ stripe: GuestPrintStripeLike,
209
+ email: string,
210
+ ): Promise<string> {
211
+ const emailKey = email.toLowerCase();
212
+ try {
213
+ const found = await stripe.customers.search({
214
+ query: `email:'${emailKey.replace(/'/g, "\\'")}'`,
215
+ limit: 1,
216
+ });
217
+ if (found.data.length > 0) return found.data[0].id;
218
+ } catch {
219
+ // fall through to list
220
+ }
221
+ try {
222
+ const listed = await stripe.customers.list({ email: emailKey, limit: 1 });
223
+ if (listed.data.length > 0) return listed.data[0].id;
224
+ } catch {
225
+ // fall through to create
226
+ }
227
+ const created = await stripe.customers.create({ email: emailKey });
228
+ return created.id;
229
+ }
230
+
231
+ // ------------------------------------------------------ STEP 1: submission --
232
+
233
+ export interface SubmitInput {
234
+ email: string;
235
+ guestName: string | null;
236
+ guestBillingCode: string;
237
+ }
238
+
239
+ export interface SubmitOutcome {
240
+ ok: boolean;
241
+ submissionId: string;
242
+ clientSecret?: string | null;
243
+ guestBillingCode?: string;
244
+ detail?: string;
245
+ }
246
+
247
+ /**
248
+ * The guest submits a print job. We do not yet know its cost -- the whole
249
+ * point of the SetupIntent is to save a reusable card BEFORE that's known.
250
+ * The DB row is written FIRST (status='pending_card'), then the Stripe
251
+ * customer+SetupIntent are created and attached to it. If either Stripe call
252
+ * fails, the row still exists (marked 'failed') -- it still qualifies the
253
+ * guest as a known contact per GATE-0194(B), which is a deliberate choice:
254
+ * the qualifying event is submitting the print job, not the card succeeding.
255
+ */
256
+ export async function submitGuestPrintJob(
257
+ stripe: GuestPrintStripeLike,
258
+ db: GuestPrintDbLike,
259
+ input: SubmitInput,
260
+ ): Promise<SubmitOutcome> {
261
+ const email = input.email.toLowerCase();
262
+ const submissionId = await db.insertPending({
263
+ email, guestName: input.guestName, guestBillingCode: input.guestBillingCode,
264
+ });
265
+
266
+ let customerId: string;
267
+ try {
268
+ customerId = await resolveGuestStripeCustomer(stripe, email);
269
+ } catch (e) {
270
+ await db.markFailed(submissionId, `customer_resolve_failed: ${String(e)}`);
271
+ return { ok: false, submissionId, detail: 'customer_resolve_failed' };
272
+ }
273
+
274
+ let setupIntent: GpSetupIntent;
275
+ try {
276
+ setupIntent = await stripe.setupIntents.create({
277
+ customer: customerId,
278
+ payment_method_types: ['card'],
279
+ usage: 'off_session',
280
+ metadata: {
281
+ gc_feature: 'guest_print',
282
+ gc_submission_id: submissionId,
283
+ gc_guest_billing_code: input.guestBillingCode,
284
+ },
285
+ }, { idempotencyKey: guestPrintSetupIntentKey(submissionId) });
286
+ } catch (e) {
287
+ await db.markFailed(submissionId, `setup_intent_failed: ${String(e)}`);
288
+ return { ok: false, submissionId, detail: 'setup_intent_failed' };
289
+ }
290
+
291
+ try {
292
+ await db.attachStripeIds(submissionId, customerId, setupIntent.id);
293
+ } catch (e) {
294
+ // The SetupIntent now exists LIVE in Stripe (created above, successfully)
295
+ // but failed to be recorded on the row. Unlike the two Stripe-call
296
+ // failures above, we do NOT want to silently leave the row looking like
297
+ // a normal, still-in-progress 'pending_card' submission -- staff would
298
+ // have no way to notice a live, orphaned SetupIntent exists. Mark the
299
+ // row failed with the live SetupIntent id embedded in last_error so a
300
+ // human can reconcile it manually (see D5 adversarial review round 1,
301
+ // S6). This is a rare failure mode: a DB write failing immediately after
302
+ // two successful prior writes to the same table in the same request.
303
+ console.error('[guestPrintCapture] attachStripeIds failed after a live Stripe SetupIntent was created', {
304
+ submissionId, liveSetupIntentId: setupIntent.id, error: String(e),
305
+ });
306
+ try {
307
+ await db.markFailed(
308
+ submissionId,
309
+ `attach_stripe_ids_failed: ${String(e)}; live_setup_intent_id=${setupIntent.id}; live_customer_id=${customerId}`,
310
+ );
311
+ } catch {
312
+ // Best-effort only -- do not let a second failure here mask the real
313
+ // outcome being reported to the caller below.
314
+ }
315
+ return { ok: false, submissionId, detail: 'attach_stripe_ids_failed' };
316
+ }
317
+
318
+ return {
319
+ ok: true,
320
+ submissionId,
321
+ clientSecret: setupIntent.client_secret,
322
+ guestBillingCode: input.guestBillingCode,
323
+ };
324
+ }
325
+
326
+ // -------------------------------------------------- STEP 2: confirm --
327
+
328
+ export interface ConfirmOutcome {
329
+ ok: boolean;
330
+ status: string;
331
+ detail?: string;
332
+ }
333
+
334
+ /**
335
+ * Called after the FRONTEND has already confirmed the SetupIntent client-side
336
+ * via Stripe.js (confirmCardSetup). That client-side report is never trusted
337
+ * on its own -- this re-retrieves the SetupIntent from Stripe and acts only
338
+ * on what Stripe itself reports.
339
+ *
340
+ * `expectedSubmissionId`'s row is checked against `setupIntentId` by the
341
+ * CALLER before this runs (see guest-print-setup-confirm/index.ts) -- this
342
+ * function assumes that binding has already been verified and only handles
343
+ * the Stripe-side confirmation logic, to keep it testable without a DB fake
344
+ * that also has to simulate an ownership check.
345
+ */
346
+ export async function confirmGuestPrintSetup(
347
+ stripe: GuestPrintStripeLike,
348
+ db: GuestPrintDbLike,
349
+ submissionId: string,
350
+ setupIntentId: string,
351
+ ): Promise<ConfirmOutcome> {
352
+ const si = await stripe.setupIntents.retrieve(setupIntentId);
353
+ if (si.id !== setupIntentId) {
354
+ // Should be unreachable against a real Stripe client; guards a
355
+ // misbehaving test double / future refactor rather than a real API
356
+ // failure mode.
357
+ return { ok: false, status: 'mismatch', detail: 'retrieved id does not match requested id' };
358
+ }
359
+ if (si.status !== 'succeeded') {
360
+ return { ok: false, status: si.status, detail: 'setup_intent_not_succeeded' };
361
+ }
362
+ const pm = pmId(si.payment_method);
363
+ if (!pm) {
364
+ return { ok: false, status: si.status, detail: 'succeeded_but_no_payment_method' };
365
+ }
366
+ await db.markCardSaved(submissionId, pm);
367
+ return { ok: true, status: 'card_saved' };
368
+ }
369
+
370
+ // ---------------------------------------------------------- STEP 3: charge --
371
+
372
+ export interface ChargeOutcome {
373
+ ok: boolean;
374
+ status: string;
375
+ detail?: string;
376
+ paymentIntentId?: string;
377
+ /** Set ONLY when a charge was actually recorded to the ledger via
378
+ * writebackCharged (the happy path or the already-succeeded recovery
379
+ * branch) -- always the TRUE amount that was written, which in the
380
+ * recovery branch is the PRIOR PaymentIntent's real amount and can differ
381
+ * from the amountCents this call was invoked with. Absent for every
382
+ * outcome that never reached a writebackCharged call. See D5 adversarial
383
+ * review, S9. */
384
+ amountCents?: number;
385
+ }
386
+
387
+ /**
388
+ * Called once the job's actual usage/cost is known (staff-entered via
389
+ * admin-charge-guest-print for this build -- see the D5 build report for
390
+ * why automatic ezeep-webhook correlation is deliberately deferred).
391
+ *
392
+ * Gets the same discipline D3 applies to its money-moving step: an atomic
393
+ * DB claim BEFORE touching Stripe (so two concurrent invocations for the
394
+ * same submission cannot both charge), and a deterministic idempotency key
395
+ * sent to Stripe itself as defense in depth if the claim is ever bypassed
396
+ * (e.g. a client retry racing the DB write of its own first attempt's
397
+ * result).
398
+ */
399
+ export async function chargeGuestPrintJob(
400
+ stripe: GuestPrintStripeLike,
401
+ db: GuestPrintDbLike,
402
+ submissionId: string,
403
+ amountCents: number,
404
+ ): Promise<ChargeOutcome> {
405
+ if (!Number.isInteger(amountCents) || amountCents <= 0) {
406
+ return { ok: false, status: 'invalid_amount', detail: 'amountCents must be a positive integer' };
407
+ }
408
+
409
+ const claimed = await db.claimForCharge(submissionId);
410
+ if (!claimed) {
411
+ // Not an error at the DECISION-CORE level: either another invocation
412
+ // already has this submission, or it isn't in a claimable state (still
413
+ // pending_card, already charging/charged/canceled). Mirrors D3's
414
+ // 'already_in_flight' shape. IMPORTANT: this does NOT mean "success" --
415
+ // a caller (e.g. admin-charge-guest-print) MUST NOT report this outcome
416
+ // as an HTTP 200/ok:true to its own caller; see D5 adversarial review
417
+ // round 1, B1. `ok: true` here means only "the core itself hit no
418
+ // exception," not "the charge happened or is safe to treat as done."
419
+ return { ok: true, status: 'not_claimed', detail: 'already_charging_or_not_ready' };
420
+ }
421
+
422
+ const row = await db.getById(submissionId);
423
+ if (!row) {
424
+ return { ok: false, status: 'row_missing' };
425
+ }
426
+ if (!row.stripe_customer_id || !row.stripe_payment_method_id) {
427
+ await db.writebackChargeFailed(submissionId, 'no_saved_payment_method');
428
+ return { ok: false, status: 'no_saved_payment_method' };
429
+ }
430
+
431
+ // B4 (round 2 review): B3 made the charge idempotency key vary by amount,
432
+ // which was necessary so a corrected-amount retry isn't blocked -- but it
433
+ // also means a SECOND, genuinely-different PaymentIntent can now be
434
+ // created for a submission that already has a PRIOR one on file. If that
435
+ // prior PI is still LIVE (e.g. it's sitting on 'requires_action' from a
436
+ // 3DS challenge the guest has not yet completed, or is still
437
+ // 'processing'), the guest could complete it at any time -- including
438
+ // AFTER staff has already successfully charged a new, corrected-amount PI
439
+ // -- resulting in a genuine double charge. So: before ever creating a new
440
+ // PI, retrieve any prior one and refuse to proceed while it's still live.
441
+ if (row.stripe_payment_intent_id) {
442
+ let prior: GpPaymentIntent;
443
+ try {
444
+ prior = await stripe.paymentIntents.retrieve(row.stripe_payment_intent_id);
445
+ } catch (e) {
446
+ // Fail CLOSED: we cannot prove the prior PI is safely dead (canceled
447
+ // or a clean decline), so refuse rather than risk a second live PI.
448
+ await db.writebackChargeFailed(
449
+ submissionId, `prior_pi_retrieve_failed: ${String(e)}`, row.stripe_payment_intent_id,
450
+ );
451
+ return {
452
+ ok: false, status: 'prior_payment_intent_unverifiable', paymentIntentId: row.stripe_payment_intent_id,
453
+ };
454
+ }
455
+ if (prior.status === 'succeeded') {
456
+ // Already charged by a truly prior attempt (e.g. Stripe confirmed it
457
+ // but our own writebackCharged call itself then failed) -- record it
458
+ // now rather than creating a second charge. This is a recovery, not a
459
+ // new charge: we never call stripe.paymentIntents.create below.
460
+ //
461
+ // IMPORTANT: record `prior.amount` (what Stripe actually charged on
462
+ // the prior PI), NOT the CALLER's `amountCents` parameter -- those can
463
+ // legitimately differ (e.g. staff is re-entering what they believe is
464
+ // a corrected amount, unaware the original attempt actually
465
+ // succeeded). Writing the caller's amount here would silently
466
+ // corrupt the ledger with a number Stripe never actually charged.
467
+ await db.writebackCharged(submissionId, prior.amount, prior.id);
468
+ // S9: outcome.amountCents carries the TRUE (prior) amount back to the
469
+ // caller -- previously this was silently dropped, so a caller (e.g.
470
+ // admin-charge-guest-print) had no way to notice prior.amount diverged
471
+ // from the amountCents it was asked to charge with. The caller is
472
+ // responsible for comparing this against the originally-requested
473
+ // amount and surfacing a mismatch; this function still reports the
474
+ // recovery as an ordinary 'charged' success since the ledger itself
475
+ // (writebackCharged, above) IS correct.
476
+ return { ok: true, status: 'charged', paymentIntentId: prior.id, amountCents: prior.amount };
477
+ }
478
+ if (!DEAD_PRIOR_PI_STATUSES.includes(prior.status)) {
479
+ // Fail CLOSED (S10): this branch now covers every known-still-live
480
+ // status (requires_action, requires_confirmation, processing,
481
+ // requires_capture -- each of which could still resolve to
482
+ // 'succeeded' later without any further action from this function,
483
+ // e.g. the guest finishes a 3DS challenge in their own browser tab
484
+ // days later) AND, deliberately, any status this function has never
485
+ // seen before -- an allowlist-of-dead-statuses guard fails safe
486
+ // against an unrecognized value the same way the retrieve-throws
487
+ // branch above already does, rather than a denylist that would fall
488
+ // through to a new charge for anything it doesn't recognize. Do NOT
489
+ // create a second PaymentIntent while this is possible. Staff must
490
+ // resolve the prior PI first (cancel it in the Stripe dashboard, or
491
+ // wait it out).
492
+ await db.writebackChargeFailed(
493
+ submissionId, `prior_payment_intent_still_live: ${prior.status}`, prior.id,
494
+ );
495
+ return { ok: false, status: 'prior_payment_intent_still_live', paymentIntentId: prior.id };
496
+ }
497
+ // Otherwise prior.status is in DEAD_PRIOR_PI_STATUSES -- a genuinely dead
498
+ // end -- it's safe to proceed with a new attempt.
499
+ }
500
+
501
+ let pi: GpPaymentIntent;
502
+ try {
503
+ pi = await stripe.paymentIntents.create({
504
+ customer: row.stripe_customer_id,
505
+ payment_method: row.stripe_payment_method_id,
506
+ amount: amountCents,
507
+ currency: 'usd',
508
+ off_session: true,
509
+ confirm: true,
510
+ description: 'Guest print & copy usage',
511
+ receipt_email: row.email,
512
+ metadata: {
513
+ gc_feature: 'guest_print',
514
+ gc_submission_id: submissionId,
515
+ },
516
+ // amountCents is part of the key: see guestPrintChargeKey's doc comment.
517
+ }, { idempotencyKey: guestPrintChargeKey(submissionId, amountCents) });
518
+ } catch (e) {
519
+ // Stripe's create call itself threw -- no PI object was ever returned,
520
+ // so there is genuinely no id to persist here.
521
+ await db.writebackChargeFailed(submissionId, `payment_intent_failed: ${String(e)}`);
522
+ return { ok: false, status: 'payment_intent_failed', detail: String(e) };
523
+ }
524
+
525
+ if (pi.status !== 'succeeded') {
526
+ // e.g. 'requires_action' -- a saved card can still demand 3DS on an
527
+ // off-session charge. Not charged; needs staff follow-up (a fresh,
528
+ // on-session confirmation from the guest). Never marked 'charged'. A
529
+ // real PaymentIntent DOES exist live in Stripe at this point, so its id
530
+ // is persisted via writebackChargeFailed (D5 adversarial review round 1,
531
+ // B2) -- otherwise a 3DS-stuck live PI would be unfindable from the DB.
532
+ await db.writebackChargeFailed(submissionId, `payment_intent_status_${pi.status}`, pi.id);
533
+ return { ok: false, status: pi.status, paymentIntentId: pi.id };
534
+ }
535
+
536
+ await db.writebackCharged(submissionId, amountCents, pi.id);
537
+ return { ok: true, status: 'charged', paymentIntentId: pi.id, amountCents };
538
+ }