@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,321 @@
1
+ // Referral program grant logic + failure recorder.
2
+ //
3
+ // Originally moved verbatim out of stripe-webhook/index.ts so the SAME
4
+ // grant logic could be re-invoked on demand by admin-referral-retry (a
5
+ // grant_failed referral needs to re-run this exact function, not a second
6
+ // hand-written copy of Stripe balance-transaction logic that could drift
7
+ // from it over time). Since then (second-model review, 2026-08-24) it has
8
+ // picked up real behavioral fixes on top of that extraction -- it is no
9
+ // longer byte-identical to the original inline version, and should not be
10
+ // described that way again:
11
+ // - `fromStatuses` is now a parameter (default ['signed_up'], the
12
+ // webhook's original single case) instead of a hardcoded 'signed_up'
13
+ // literal, so admin-referral-retry can call this SAME function on a
14
+ // grant_failed row directly -- no separate reset-to-signed_up step,
15
+ // no window where the row sits in a state nothing recognizes.
16
+ // - A failed persist of either side's Stripe transaction id is now a
17
+ // hard stop with a loud last_error, not a console.error-and-continue
18
+ // (see the two `partialUpdErr` blocks below) -- see "24h idempotency
19
+ // key" comment for why this matters.
20
+ // The Supabase and Stripe clients are explicit parameters (same convention
21
+ // as _shared/membershipWelcome.ts and _shared/bookingEffects.ts) instead of
22
+ // closure captures, and console.error tags read [referralGrant] instead of
23
+ // [stripe-webhook] since this code now runs from two different callers.
24
+ //
25
+ // The two clawback functions (maybeClawbackReferralCredit and
26
+ // maybeClawbackReferralCreditForRefundOrDispute) stay in stripe-webhook/
27
+ // index.ts -- they're deliberately NOT extracted here. There are two
28
+ // different clawback code paths and a clawback_failed row alone doesn't
29
+ // say which one failed, so clawback retry is a human decision for now
30
+ // (see AdminReferrals.tsx), not an automated one. recordReferralFailure is
31
+ // still exported here since both index.ts's clawback functions and this
32
+ // file's grant function need it -- index.ts imports it from here rather
33
+ // than keeping a second copy.
34
+
35
+ import type { createClient, SupabaseClient } from 'npm:@supabase/supabase-js@2';
36
+ import type Stripe from 'npm:stripe@17.5.0';
37
+ import { logOps } from './ops.ts';
38
+ import { computeReferralCredits } from './referralCredits.ts';
39
+
40
+ type SupabaseLike = SupabaseClient<any, 'public', any>;
41
+
42
+ interface ReferralGrantRow {
43
+ id: string;
44
+ status: 'signed_up' | 'grant_failed';
45
+ referring_membership_id: string;
46
+ referred_membership_id: string;
47
+ referred_plan_price_cents: number | null;
48
+ is_private_office: boolean | null;
49
+ stripe_balance_txn_id_referrer: string | null;
50
+ stripe_balance_txn_id_referred: string | null;
51
+ }
52
+
53
+
54
+ /**
55
+ * Records a permanent grant/clawback failure on the referrals row itself
56
+ * (fix #4 from the round-2 review) instead of only console.error/warn --
57
+ * without this, a permanently-failed referral was indistinguishable from
58
+ * one still genuinely pending. Guarded with `.eq('status', fromStatus)` so
59
+ * a failure recorded after the fact can never clobber a row that a
60
+ * concurrent/retried webhook delivery (or a concurrent admin retry) already
61
+ * carried to success -- `fromStatus` must be the row's ACTUAL current
62
+ * status at the time of the call, not an assumed one, or this guard can
63
+ * silently no-op (0 rows updated, no error) instead of protecting anything.
64
+ */
65
+ export async function recordReferralFailure(
66
+ supabase: SupabaseLike,
67
+ referralId: string,
68
+ fromStatus: 'signed_up' | 'grant_failed' | 'credited',
69
+ toStatus: 'grant_failed' | 'clawback_failed',
70
+ error: unknown,
71
+ ) {
72
+ const message = (error instanceof Error ? error.message : String(error)).slice(0, 2000);
73
+ const { error: updErr } = await supabase
74
+ .from('referrals')
75
+ .update({ status: toStatus, last_error: message })
76
+ .eq('id', referralId)
77
+ .eq('status', fromStatus);
78
+ if (updErr) {
79
+ console.error('[referralGrant] recordReferralFailure: failed to persist failure status', {
80
+ referral_id: referralId, target_status: toStatus, message: updErr.message,
81
+ });
82
+ }
83
+ // Round-3 review finding 4c: a terminal grant_failed/clawback_failed row
84
+ // is otherwise only visible to someone who thinks to query the table.
85
+ // Route it through the same ops-alert channel stripe-webhook uses.
86
+ await logOps(supabase, 'referral_' + toStatus,
87
+ { referral_id: referralId, message },
88
+ { severity: 'error' }).catch(() => {});
89
+ }
90
+
91
+ /**
92
+ * Referral program Phase 1, step 2 (grant at first-invoice-paid).
93
+ *
94
+ * Called from the webhook only when the first_invoice_paid_at compare-and-
95
+ * swap in the invoice.paid handler actually affected a row (genuinely the
96
+ * first real paid invoice for this membership) -- that call passes no
97
+ * `fromStatuses` override, so it only ever matches a 'signed_up' row.
98
+ *
99
+ * admin-referral-retry calls this SAME function with
100
+ * `fromStatuses: ['grant_failed']` to retry a previously-failed grant --
101
+ * see that function's own header comment for why it gates on the referred
102
+ * membership's live status first, and why it does NOT reset the row to
103
+ * 'signed_up' before calling this (that reset-then-call shape was tried and
104
+ * reverted after a second-model review found it opened a stranded-row
105
+ * window and a same-row race between two concurrent retries).
106
+ *
107
+ * Computes real credit amounts, grants a NEGATIVE Stripe Customer Balance
108
+ * Transaction (a credit) on each of the two Stripe customers, and marks the
109
+ * referral 'credited'.
110
+ *
111
+ * Entirely wrapped in try/catch and logs with the referral id on failure --
112
+ * a Stripe failure here must never break invoice.paid processing for an
113
+ * unrelated membership.
114
+ *
115
+ * IDEMPOTENT BY DESIGN -- this is also what makes it safe for
116
+ * admin-referral-retry to call again on a grant_failed row: before each
117
+ * Stripe call it checks whether this referral already has a txn id
118
+ * persisted, and each Stripe call carries a fixed idempotency key derived
119
+ * from the referral id, so a retry only attempts whichever side didn't
120
+ * already complete. Never write a second, separate recovery path -- retry
121
+ * by calling this function again.
122
+ */
123
+ export async function maybeGrantReferralCredit(
124
+ supabase: SupabaseLike,
125
+ stripe: Stripe,
126
+ referredMembershipId: string,
127
+ fromStatuses: readonly ('signed_up' | 'grant_failed')[] = ['signed_up'],
128
+ ) {
129
+ let referralId: string | null = null;
130
+ // Guard used by every recordReferralFailure call below -- always the
131
+ // row's REAL current status as read from the DB just now, never an
132
+ // assumption, so the optimistic-concurrency guard inside
133
+ // recordReferralFailure actually protects against a concurrent winner.
134
+ let currentStatus: 'signed_up' | 'grant_failed' = 'signed_up';
135
+ try {
136
+ const { data: rawReferral, error: refErr } = await supabase
137
+ .from('referrals')
138
+ .select(
139
+ 'id,status,referring_membership_id,referred_membership_id,referred_plan_price_cents,is_private_office,' +
140
+ 'stripe_balance_txn_id_referrer,stripe_balance_txn_id_referred',
141
+ )
142
+ .eq('referred_membership_id', referredMembershipId)
143
+ .in('status', fromStatuses)
144
+ .maybeSingle();
145
+ if (refErr) {
146
+ console.error('[referralGrant] referral lookup failed', {
147
+ membership_id: referredMembershipId, message: refErr.message,
148
+ });
149
+ return;
150
+ }
151
+ if (!rawReferral) return; // this membership has no referral in a retryable state -- normal case
152
+ const typedReferral = rawReferral as unknown as ReferralGrantRow;
153
+ referralId = typedReferral.id;
154
+ currentStatus = typedReferral.status;
155
+
156
+ const { referrerCents, referredCents } = computeReferralCredits(
157
+ typedReferral.referred_plan_price_cents ?? 0,
158
+ typedReferral.is_private_office === true,
159
+ );
160
+
161
+ const { data: parties, error: partiesErr } = await supabase
162
+ .from('memberships')
163
+ .select('id,stripe_customer_id')
164
+ .in('id', [typedReferral.referring_membership_id, typedReferral.referred_membership_id]);
165
+ if (partiesErr || !parties) {
166
+ console.error('[referralGrant] referral credit membership lookup failed', {
167
+ referral_id: typedReferral.id, message: partiesErr?.message ?? 'no rows',
168
+ });
169
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed', partiesErr ?? new Error('membership lookup returned no rows'));
170
+ return;
171
+ }
172
+ const referringCustomerId =
173
+ parties.find((m) => m.id === typedReferral.referring_membership_id)?.stripe_customer_id ?? null;
174
+ const referredCustomerId =
175
+ parties.find((m) => m.id === typedReferral.referred_membership_id)?.stripe_customer_id ?? null;
176
+ if (!referringCustomerId || !referredCustomerId) {
177
+ console.error('[referralGrant] referral credit missing stripe_customer_id', { referral_id: typedReferral.id });
178
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed', new Error('missing stripe_customer_id on one or both parties'));
179
+ return;
180
+ }
181
+
182
+ // Each call carries a deterministic idempotency key derived from the
183
+ // referral row's own id -- a webhook redelivery, or our own retry after
184
+ // a transient failure below, can never double-credit either party even
185
+ // if our own DB state is momentarily inconsistent; Stripe itself
186
+ // refuses to apply the same key twice.
187
+ //
188
+ // Round-3 review foot-gun: idempotency keys expire after 24h (Stripe),
189
+ // but a `grant_failed` row can be manually flipped back for retry well
190
+ // after that -- at which point a stale key would no longer protect
191
+ // against a double charge. The real guard is checking whether this
192
+ // referral ALREADY has a txn id persisted (from a prior partial
193
+ // attempt) and skipping straight past re-charging Stripe for that side
194
+ // if so -- which is exactly why a failure to PERSIST that txn id after
195
+ // a successful Stripe call (the `partialUpdErr`/`partialUpdErr2` blocks
196
+ // below) must be treated as fatal, not logged-and-ignored: if the id
197
+ // never lands in the DB, a later retry past the 24h window has no way
198
+ // to know the money already moved, and will move it again.
199
+ let referrerTxnId: string | null = typedReferral.stripe_balance_txn_id_referrer ?? null;
200
+ if (!referrerTxnId) {
201
+ try {
202
+ // A NEGATIVE amount on a Customer Balance Transaction decreases what
203
+ // the customer owes -- i.e. grants them a credit against their next
204
+ // invoice. POST /v1/customers/{customer}/balance_transactions.
205
+ const referrerTxn = await stripe.customers.createBalanceTransaction(
206
+ referringCustomerId,
207
+ {
208
+ amount: -referrerCents,
209
+ currency: 'usd',
210
+ description: `Referral credit: friend joined via your referral link (referral ${typedReferral.id})`,
211
+ },
212
+ { idempotencyKey: `ref-${typedReferral.id}-referrer-grant` },
213
+ );
214
+ referrerTxnId = referrerTxn.id;
215
+ } catch (e) {
216
+ console.error('[referralGrant] referral referrer balance transaction creation failed', {
217
+ referral_id: typedReferral.id, message: e instanceof Error ? e.message : String(e),
218
+ });
219
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed', e);
220
+ return;
221
+ }
222
+
223
+ // Persist immediately -- if the referred-side call below throws, this
224
+ // row already shows real money moved once, with the txn id needed to
225
+ // reconcile or manually complete the pair. A failure to persist THIS
226
+ // txn id is fatal (see the 24h-idempotency-key comment above): the
227
+ // Stripe transaction already exists for real, so silently continuing
228
+ // would leave a retry blind to that fact.
229
+ const { error: partialUpdErr } = await supabase
230
+ .from('referrals')
231
+ .update({ stripe_balance_txn_id_referrer: referrerTxnId, referrer_credit_cents: referrerCents })
232
+ .eq('id', typedReferral.id);
233
+ if (partialUpdErr) {
234
+ console.error('[referralGrant] referral partial grant persist failed -- REFERRER STRIPE CREDIT ALREADY GRANTED', {
235
+ referral_id: typedReferral.id, referrer_txn_id: referrerTxnId, message: partialUpdErr.message,
236
+ });
237
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed',
238
+ new Error(`REFERRER CREDIT GRANTED (txn ${referrerTxnId}) BUT TXN ID NOT PERSISTED (${partialUpdErr.message}) -- reconcile in Stripe before retrying; a retry past 24h without this id would charge again`));
239
+ return;
240
+ }
241
+ }
242
+
243
+ let referredTxnId: string | null = typedReferral.stripe_balance_txn_id_referred ?? null;
244
+ if (!referredTxnId) {
245
+ try {
246
+ const referredTxn = await stripe.customers.createBalanceTransaction(
247
+ referredCustomerId,
248
+ {
249
+ amount: -referredCents,
250
+ currency: 'usd',
251
+ description: `Referral credit: welcome credit for signing up with a referral code (referral ${typedReferral.id})`,
252
+ },
253
+ { idempotencyKey: `ref-${typedReferral.id}-referred-grant` },
254
+ );
255
+ referredTxnId = referredTxn.id;
256
+ } catch (e) {
257
+ console.error('[referralGrant] referral referred balance transaction creation failed -- referrer side already credited above', {
258
+ referral_id: typedReferral.id, referrer_txn_id: referrerTxnId, message: e instanceof Error ? e.message : String(e),
259
+ });
260
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed', e);
261
+ return;
262
+ }
263
+
264
+ // Same reasoning as the referrer side above -- a failed persist here
265
+ // means a real Stripe credit exists with no durable record of its id.
266
+ const { error: partialUpdErr2 } = await supabase
267
+ .from('referrals')
268
+ .update({ stripe_balance_txn_id_referred: referredTxnId, referred_credit_cents: referredCents })
269
+ .eq('id', typedReferral.id);
270
+ if (partialUpdErr2) {
271
+ console.error('[referralGrant] referral partial grant persist (referred side) failed -- REFERRED STRIPE CREDIT ALREADY GRANTED', {
272
+ referral_id: typedReferral.id, referred_txn_id: referredTxnId, message: partialUpdErr2.message,
273
+ });
274
+ await recordReferralFailure(supabase, typedReferral.id, currentStatus, 'grant_failed',
275
+ new Error(`REFERRED CREDIT GRANTED (txn ${referredTxnId}) BUT TXN ID NOT PERSISTED (${partialUpdErr2.message}) -- reconcile in Stripe before retrying; a retry past 24h without this id would charge again`));
276
+ return;
277
+ }
278
+ }
279
+
280
+ // referrer_credit_cents/referred_credit_cents are NOT set here -- each
281
+ // was already persisted, atomically with its own txn id, above (round-4
282
+ // review finding) -- so the amount recorded always matches what that
283
+ // specific Stripe transaction actually charged, even across a retry
284
+ // where the formula or the referral's price_cents might have changed.
285
+ //
286
+ // Guarded on `currentStatus` (the row's real status as read at the top
287
+ // of this call), not a hardcoded 'signed_up' -- a retry from
288
+ // grant_failed must flip FROM grant_failed, not from a status the row
289
+ // was never actually in.
290
+ const { error: creditUpdErr } = await supabase
291
+ .from('referrals')
292
+ .update({
293
+ status: 'credited',
294
+ credited_at: new Date().toISOString(),
295
+ clawback_eligible_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
296
+ })
297
+ .eq('id', typedReferral.id)
298
+ .eq('status', currentStatus);
299
+ if (creditUpdErr) {
300
+ console.error('[referralGrant] referral row update after crediting failed -- BOTH stripe transactions already succeeded, only this status flip failed', {
301
+ referral_id: typedReferral.id, referrer_txn_id: referrerTxnId, referred_txn_id: referredTxnId,
302
+ message: creditUpdErr.message,
303
+ });
304
+ await logOps(supabase, 'referral_credited_status_flip_failed',
305
+ { referral_id: typedReferral.id, referrer_txn_id: referrerTxnId, referred_txn_id: referredTxnId, message: creditUpdErr.message },
306
+ { severity: 'error' }).catch(() => {});
307
+ // Deliberately NOT recordReferralFailure here -- both Stripe
308
+ // transactions already succeeded, so 'grant_failed' would misleadingly
309
+ // imply the grant itself failed. The row stays at `currentStatus` with
310
+ // both txn ids already persisted above, so a later retry of this
311
+ // function is now SAFE: it will skip both createBalanceTransaction
312
+ // calls (already have referrerTxnId/referredTxnId) and just
313
+ // re-attempt this status flip.
314
+ }
315
+ } catch (e) {
316
+ console.error('[referralGrant] maybeGrantReferralCredit failed', {
317
+ membership_id: referredMembershipId, message: e instanceof Error ? e.message : String(e),
318
+ });
319
+ if (referralId) await recordReferralFailure(supabase, referralId, currentStatus, 'grant_failed', e);
320
+ }
321
+ }