@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

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 (267) hide show
  1. package/LICENSE +183 -0
  2. package/README.md +141 -2
  3. package/dist/AccountingBridge.d.ts +65 -0
  4. package/dist/AccountingBridge.d.ts.map +1 -0
  5. package/dist/AccountingBridge.js +102 -0
  6. package/dist/AccountingBridge.js.map +1 -0
  7. package/dist/AdvanceOrderStateOperation.d.ts +80 -0
  8. package/dist/AdvanceOrderStateOperation.d.ts.map +1 -0
  9. package/dist/AdvanceOrderStateOperation.js +267 -0
  10. package/dist/AdvanceOrderStateOperation.js.map +1 -0
  11. package/dist/ApplyAccountCreditOperation.d.ts +97 -0
  12. package/dist/ApplyAccountCreditOperation.d.ts.map +1 -0
  13. package/dist/ApplyAccountCreditOperation.js +275 -0
  14. package/dist/ApplyAccountCreditOperation.js.map +1 -0
  15. package/dist/BaseDeliveryChannel.d.ts +106 -0
  16. package/dist/BaseDeliveryChannel.d.ts.map +1 -0
  17. package/dist/BaseDeliveryChannel.js +36 -0
  18. package/dist/BaseDeliveryChannel.js.map +1 -0
  19. package/dist/BasePaymentProvider.d.ts +239 -0
  20. package/dist/BasePaymentProvider.d.ts.map +1 -0
  21. package/dist/BasePaymentProvider.js +91 -0
  22. package/dist/BasePaymentProvider.js.map +1 -0
  23. package/dist/BundleBehavior.d.ts +139 -0
  24. package/dist/BundleBehavior.d.ts.map +1 -0
  25. package/dist/BundleBehavior.js +173 -0
  26. package/dist/BundleBehavior.js.map +1 -0
  27. package/dist/BundleEngine.d.ts +60 -0
  28. package/dist/BundleEngine.d.ts.map +1 -0
  29. package/dist/BundleEngine.js +197 -0
  30. package/dist/BundleEngine.js.map +1 -0
  31. package/dist/CancelSubscriptionOperation.d.ts +98 -0
  32. package/dist/CancelSubscriptionOperation.d.ts.map +1 -0
  33. package/dist/CancelSubscriptionOperation.js +317 -0
  34. package/dist/CancelSubscriptionOperation.js.map +1 -0
  35. package/dist/CapturePaymentOperation.d.ts +62 -0
  36. package/dist/CapturePaymentOperation.d.ts.map +1 -0
  37. package/dist/CapturePaymentOperation.js +463 -0
  38. package/dist/CapturePaymentOperation.js.map +1 -0
  39. package/dist/CheckEntitlementOperation.d.ts +27 -0
  40. package/dist/CheckEntitlementOperation.d.ts.map +1 -0
  41. package/dist/CheckEntitlementOperation.js +45 -0
  42. package/dist/CheckEntitlementOperation.js.map +1 -0
  43. package/dist/CheckoutSessionService.d.ts +258 -0
  44. package/dist/CheckoutSessionService.d.ts.map +1 -0
  45. package/dist/CheckoutSessionService.js +1557 -0
  46. package/dist/CheckoutSessionService.js.map +1 -0
  47. package/dist/DeliveryBehavior.d.ts +121 -0
  48. package/dist/DeliveryBehavior.d.ts.map +1 -0
  49. package/dist/DeliveryBehavior.js +145 -0
  50. package/dist/DeliveryBehavior.js.map +1 -0
  51. package/dist/DeliveryRecipientResolver.d.ts +38 -0
  52. package/dist/DeliveryRecipientResolver.d.ts.map +1 -0
  53. package/dist/DeliveryRecipientResolver.js +93 -0
  54. package/dist/DeliveryRecipientResolver.js.map +1 -0
  55. package/dist/DeliveryResolver.d.ts +14 -0
  56. package/dist/DeliveryResolver.d.ts.map +1 -0
  57. package/dist/DeliveryResolver.js +45 -0
  58. package/dist/DeliveryResolver.js.map +1 -0
  59. package/dist/EmailDeliveryChannel.d.ts +31 -0
  60. package/dist/EmailDeliveryChannel.d.ts.map +1 -0
  61. package/dist/EmailDeliveryChannel.js +158 -0
  62. package/dist/EmailDeliveryChannel.js.map +1 -0
  63. package/dist/EntitlementBehavior.d.ts +235 -0
  64. package/dist/EntitlementBehavior.d.ts.map +1 -0
  65. package/dist/EntitlementBehavior.js +330 -0
  66. package/dist/EntitlementBehavior.js.map +1 -0
  67. package/dist/EntitlementEngine.d.ts +97 -0
  68. package/dist/EntitlementEngine.d.ts.map +1 -0
  69. package/dist/EntitlementEngine.js +338 -0
  70. package/dist/EntitlementEngine.js.map +1 -0
  71. package/dist/EntitlementGrantClaimDriver.d.ts +42 -0
  72. package/dist/EntitlementGrantClaimDriver.d.ts.map +1 -0
  73. package/dist/EntitlementGrantClaimDriver.js +158 -0
  74. package/dist/EntitlementGrantClaimDriver.js.map +1 -0
  75. package/dist/EntitlementRead.d.ts +82 -0
  76. package/dist/EntitlementRead.d.ts.map +1 -0
  77. package/dist/EntitlementRead.js +368 -0
  78. package/dist/EntitlementRead.js.map +1 -0
  79. package/dist/FulfillOrderLinesOperation.d.ts +34 -0
  80. package/dist/FulfillOrderLinesOperation.d.ts.map +1 -0
  81. package/dist/FulfillOrderLinesOperation.js +208 -0
  82. package/dist/FulfillOrderLinesOperation.js.map +1 -0
  83. package/dist/FulfillmentBehavior.d.ts +101 -0
  84. package/dist/FulfillmentBehavior.d.ts.map +1 -0
  85. package/dist/FulfillmentBehavior.js +145 -0
  86. package/dist/FulfillmentBehavior.js.map +1 -0
  87. package/dist/GLAccountResolver.d.ts +123 -0
  88. package/dist/GLAccountResolver.d.ts.map +1 -0
  89. package/dist/GLAccountResolver.js +175 -0
  90. package/dist/GLAccountResolver.js.map +1 -0
  91. package/dist/GetFulfillmentQueueOperation.d.ts +35 -0
  92. package/dist/GetFulfillmentQueueOperation.d.ts.map +1 -0
  93. package/dist/GetFulfillmentQueueOperation.js +221 -0
  94. package/dist/GetFulfillmentQueueOperation.js.map +1 -0
  95. package/dist/GetOverdueWorklistOperation.d.ts +41 -0
  96. package/dist/GetOverdueWorklistOperation.d.ts.map +1 -0
  97. package/dist/GetOverdueWorklistOperation.js +210 -0
  98. package/dist/GetOverdueWorklistOperation.js.map +1 -0
  99. package/dist/GiftCardBehavior.d.ts +97 -0
  100. package/dist/GiftCardBehavior.d.ts.map +1 -0
  101. package/dist/GiftCardBehavior.js +121 -0
  102. package/dist/GiftCardBehavior.js.map +1 -0
  103. package/dist/GiftCardEngine.d.ts +59 -0
  104. package/dist/GiftCardEngine.d.ts.map +1 -0
  105. package/dist/GiftCardEngine.js +197 -0
  106. package/dist/GiftCardEngine.js.map +1 -0
  107. package/dist/GuestOrderClaimDriver.d.ts +36 -0
  108. package/dist/GuestOrderClaimDriver.d.ts.map +1 -0
  109. package/dist/GuestOrderClaimDriver.js +161 -0
  110. package/dist/GuestOrderClaimDriver.js.map +1 -0
  111. package/dist/InvoiceBehavior.d.ts +394 -0
  112. package/dist/InvoiceBehavior.d.ts.map +1 -0
  113. package/dist/InvoiceBehavior.js +496 -0
  114. package/dist/InvoiceBehavior.js.map +1 -0
  115. package/dist/InvoiceBuilder.d.ts +48 -0
  116. package/dist/InvoiceBuilder.d.ts.map +1 -0
  117. package/dist/InvoiceBuilder.js +352 -0
  118. package/dist/InvoiceBuilder.js.map +1 -0
  119. package/dist/InvoiceDisplay.d.ts +96 -0
  120. package/dist/InvoiceDisplay.d.ts.map +1 -0
  121. package/dist/InvoiceDisplay.js +121 -0
  122. package/dist/InvoiceDisplay.js.map +1 -0
  123. package/dist/ListEntitlementsOperation.d.ts +21 -0
  124. package/dist/ListEntitlementsOperation.d.ts.map +1 -0
  125. package/dist/ListEntitlementsOperation.js +39 -0
  126. package/dist/ListEntitlementsOperation.js.map +1 -0
  127. package/dist/ManualPaymentProvider.d.ts +19 -0
  128. package/dist/ManualPaymentProvider.d.ts.map +1 -0
  129. package/dist/ManualPaymentProvider.js +92 -0
  130. package/dist/ManualPaymentProvider.js.map +1 -0
  131. package/dist/OrderEntityServer.d.ts +542 -0
  132. package/dist/OrderEntityServer.d.ts.map +1 -0
  133. package/dist/OrderEntityServer.js +2100 -0
  134. package/dist/OrderEntityServer.js.map +1 -0
  135. package/dist/OrderJournalEntryFactory.d.ts +140 -0
  136. package/dist/OrderJournalEntryFactory.d.ts.map +1 -0
  137. package/dist/OrderJournalEntryFactory.js +466 -0
  138. package/dist/OrderJournalEntryFactory.js.map +1 -0
  139. package/dist/OrderLineEntityServer.d.ts +90 -0
  140. package/dist/OrderLineEntityServer.d.ts.map +1 -0
  141. package/dist/OrderLineEntityServer.js +260 -0
  142. package/dist/OrderLineEntityServer.js.map +1 -0
  143. package/dist/OrdersSettings.d.ts +36 -0
  144. package/dist/OrdersSettings.d.ts.map +1 -0
  145. package/dist/OrdersSettings.js +147 -0
  146. package/dist/OrdersSettings.js.map +1 -0
  147. package/dist/PaymentAllocationFactory.d.ts +128 -0
  148. package/dist/PaymentAllocationFactory.d.ts.map +1 -0
  149. package/dist/PaymentAllocationFactory.js +235 -0
  150. package/dist/PaymentAllocationFactory.js.map +1 -0
  151. package/dist/PaymentHeaderEntityServer.d.ts +180 -0
  152. package/dist/PaymentHeaderEntityServer.d.ts.map +1 -0
  153. package/dist/PaymentHeaderEntityServer.js +656 -0
  154. package/dist/PaymentHeaderEntityServer.js.map +1 -0
  155. package/dist/PaymentIntentService.d.ts +101 -0
  156. package/dist/PaymentIntentService.d.ts.map +1 -0
  157. package/dist/PaymentIntentService.js +150 -0
  158. package/dist/PaymentIntentService.js.map +1 -0
  159. package/dist/PaymentJournalEntryFactory.d.ts +99 -0
  160. package/dist/PaymentJournalEntryFactory.d.ts.map +1 -0
  161. package/dist/PaymentJournalEntryFactory.js +127 -0
  162. package/dist/PaymentJournalEntryFactory.js.map +1 -0
  163. package/dist/PaymentLineEntityServer.d.ts +73 -0
  164. package/dist/PaymentLineEntityServer.d.ts.map +1 -0
  165. package/dist/PaymentLineEntityServer.js +303 -0
  166. package/dist/PaymentLineEntityServer.js.map +1 -0
  167. package/dist/PaymentProviderBehavior.d.ts +222 -0
  168. package/dist/PaymentProviderBehavior.d.ts.map +1 -0
  169. package/dist/PaymentProviderBehavior.js +368 -0
  170. package/dist/PaymentProviderBehavior.js.map +1 -0
  171. package/dist/PaymentProviderResolver.d.ts +84 -0
  172. package/dist/PaymentProviderResolver.d.ts.map +1 -0
  173. package/dist/PaymentProviderResolver.js +220 -0
  174. package/dist/PaymentProviderResolver.js.map +1 -0
  175. package/dist/PaymentReversalFactory.d.ts +107 -0
  176. package/dist/PaymentReversalFactory.d.ts.map +1 -0
  177. package/dist/PaymentReversalFactory.js +174 -0
  178. package/dist/PaymentReversalFactory.js.map +1 -0
  179. package/dist/PaymentSettlement.d.ts +56 -0
  180. package/dist/PaymentSettlement.d.ts.map +1 -0
  181. package/dist/PaymentSettlement.js +243 -0
  182. package/dist/PaymentSettlement.js.map +1 -0
  183. package/dist/PaymentTermsBehavior.d.ts +109 -0
  184. package/dist/PaymentTermsBehavior.d.ts.map +1 -0
  185. package/dist/PaymentTermsBehavior.js +172 -0
  186. package/dist/PaymentTermsBehavior.js.map +1 -0
  187. package/dist/PaymentWebhookHandler.d.ts +103 -0
  188. package/dist/PaymentWebhookHandler.d.ts.map +1 -0
  189. package/dist/PaymentWebhookHandler.js +246 -0
  190. package/dist/PaymentWebhookHandler.js.map +1 -0
  191. package/dist/PreviewPriceOperation.d.ts +62 -0
  192. package/dist/PreviewPriceOperation.d.ts.map +1 -0
  193. package/dist/PreviewPriceOperation.js +161 -0
  194. package/dist/PreviewPriceOperation.js.map +1 -0
  195. package/dist/PriceOrderOperation.d.ts +93 -0
  196. package/dist/PriceOrderOperation.d.ts.map +1 -0
  197. package/dist/PriceOrderOperation.js +146 -0
  198. package/dist/PriceOrderOperation.js.map +1 -0
  199. package/dist/ProductPriceEntityServer.d.ts +34 -0
  200. package/dist/ProductPriceEntityServer.d.ts.map +1 -0
  201. package/dist/ProductPriceEntityServer.js +97 -0
  202. package/dist/ProductPriceEntityServer.js.map +1 -0
  203. package/dist/RefundPaymentOperation.d.ts +61 -0
  204. package/dist/RefundPaymentOperation.d.ts.map +1 -0
  205. package/dist/RefundPaymentOperation.js +177 -0
  206. package/dist/RefundPaymentOperation.js.map +1 -0
  207. package/dist/RevenueRecognition.d.ts +76 -0
  208. package/dist/RevenueRecognition.d.ts.map +1 -0
  209. package/dist/RevenueRecognition.js +133 -0
  210. package/dist/RevenueRecognition.js.map +1 -0
  211. package/dist/ReversalBehavior.d.ts +82 -0
  212. package/dist/ReversalBehavior.d.ts.map +1 -0
  213. package/dist/ReversalBehavior.js +100 -0
  214. package/dist/ReversalBehavior.js.map +1 -0
  215. package/dist/ReversalResolver.d.ts +37 -0
  216. package/dist/ReversalResolver.d.ts.map +1 -0
  217. package/dist/ReversalResolver.js +96 -0
  218. package/dist/ReversalResolver.js.map +1 -0
  219. package/dist/SpawnRenewalsOperation.d.ts +109 -0
  220. package/dist/SpawnRenewalsOperation.d.ts.map +1 -0
  221. package/dist/SpawnRenewalsOperation.js +295 -0
  222. package/dist/SpawnRenewalsOperation.js.map +1 -0
  223. package/dist/StoredValuePaymentProvider.d.ts +52 -0
  224. package/dist/StoredValuePaymentProvider.d.ts.map +1 -0
  225. package/dist/StoredValuePaymentProvider.js +205 -0
  226. package/dist/StoredValuePaymentProvider.js.map +1 -0
  227. package/dist/StripeACHPaymentProvider.d.ts +50 -0
  228. package/dist/StripeACHPaymentProvider.d.ts.map +1 -0
  229. package/dist/StripeACHPaymentProvider.js +211 -0
  230. package/dist/StripeACHPaymentProvider.js.map +1 -0
  231. package/dist/StripePaymentProvider.d.ts +83 -0
  232. package/dist/StripePaymentProvider.d.ts.map +1 -0
  233. package/dist/StripePaymentProvider.js +442 -0
  234. package/dist/StripePaymentProvider.js.map +1 -0
  235. package/dist/SubscriptionBehavior.d.ts +197 -0
  236. package/dist/SubscriptionBehavior.d.ts.map +1 -0
  237. package/dist/SubscriptionBehavior.js +415 -0
  238. package/dist/SubscriptionBehavior.js.map +1 -0
  239. package/dist/checkoutCaptureAlert.d.ts +16 -0
  240. package/dist/checkoutCaptureAlert.d.ts.map +1 -0
  241. package/dist/checkoutCaptureAlert.js +55 -0
  242. package/dist/checkoutCaptureAlert.js.map +1 -0
  243. package/dist/checkoutCaptureRetry.d.ts +27 -0
  244. package/dist/checkoutCaptureRetry.d.ts.map +1 -0
  245. package/dist/checkoutCaptureRetry.js +50 -0
  246. package/dist/checkoutCaptureRetry.js.map +1 -0
  247. package/dist/claimDriverHelpers.d.ts +15 -0
  248. package/dist/claimDriverHelpers.d.ts.map +1 -0
  249. package/dist/claimDriverHelpers.js +34 -0
  250. package/dist/claimDriverHelpers.js.map +1 -0
  251. package/dist/entity-names.d.ts +15 -0
  252. package/dist/entity-names.d.ts.map +1 -0
  253. package/dist/entity-names.js +15 -0
  254. package/dist/entity-names.js.map +1 -0
  255. package/dist/identityClaimContracts.d.ts +118 -0
  256. package/dist/identityClaimContracts.d.ts.map +1 -0
  257. package/dist/identityClaimContracts.js +58 -0
  258. package/dist/identityClaimContracts.js.map +1 -0
  259. package/dist/index.d.ts +126 -0
  260. package/dist/index.d.ts.map +1 -0
  261. package/dist/index.js +115 -0
  262. package/dist/index.js.map +1 -0
  263. package/dist/sql-guards.d.ts +78 -0
  264. package/dist/sql-guards.d.ts.map +1 -0
  265. package/dist/sql-guards.js +115 -0
  266. package/dist/sql-guards.js.map +1 -0
  267. package/package.json +50 -5
@@ -0,0 +1,211 @@
1
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
2
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
3
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
4
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
5
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
6
+ };
7
+ /**
8
+ * StripeACHPaymentProvider — collecting by US bank debit, where "paid" is an opinion for four days.
9
+ *
10
+ * IT IS A SUBCLASS BECAUSE IT IS THE SAME GATEWAY. Stripe treats a bank debit as a PaymentIntent with
11
+ * a different payment-method type, so the auth, the form encoding, the error reading, the signature
12
+ * verification and the fee lookup are all identical to the card driver's. A separate top-level class
13
+ * would have copied every one of them, and the copies would have drifted the first time Stripe changed
14
+ * a response shape. What genuinely differs is small enough to read in one screen, and it is all here.
15
+ *
16
+ * IT IS A SEPARATE `PaymentProviderType` ROW because the two rails are different money. They settle on
17
+ * different timescales, cost different amounts (0.8% capped at $5 against 2.9% + 30c), fail for
18
+ * different reasons, and — the one that matters operationally — a bank debit can be TAKEN BACK after
19
+ * it has been booked. Configuring them as one provider would mean an operator could not turn one off,
20
+ * and every fee expectation in the system would have to branch on the instrument rather than the
21
+ * account.
22
+ *
23
+ * ═══ THE THING THAT MAKES THIS RAIL DIFFERENT ═══
24
+ *
25
+ * A card answers at the till. A bank debit answers up to four business days later, and it can answer a
26
+ * SECOND time — insufficient funds, account closed, "I never authorised this" — weeks after the money
27
+ * appeared to arrive. So there is no moment at which `Capture` can honestly report that cash moved,
28
+ * and the driver does not pretend there is:
29
+ *
30
+ * `CreateIntent` submits the debit → the intent is `Processing`
31
+ * `Capture` READS what the bank said → it does not capture anything; see below
32
+ * the webhook promotes, fails, or reverses the payment when the answer arrives
33
+ *
34
+ * `Capture` IS A READ, AND THAT IS NOT A HACK. `PaymentHeaderEntityServer.settleWithProvider` calls it
35
+ * for one purpose: to ask the gateway what actually moved, because the gateway is the authority on the
36
+ * amount and the fee. For a card the answer requires an action; for a bank debit the action already
37
+ * happened and the answer is a lookup. Overriding it to POST `/capture` would fail — there is nothing
38
+ * to capture — and inventing a second method would fork the one path that books cash. So `Capture`
39
+ * asks Stripe for the intent, refuses unless it says `succeeded`, and reports the real amount and the
40
+ * real fee. Every line of `PaymentHeaderEntityServer` stays as it was.
41
+ *
42
+ * WHAT THIS DRIVER DOES NOT DO. It does not collect or verify a bank account, and it does not capture
43
+ * a NACHA authorisation. Both belong to a SetupIntent flow the customer walks through once, and its
44
+ * output — a `us_bank_account` payment method plus the mandate Stripe retains against it — is what
45
+ * arrives here as `ProviderInstrumentRef`. Building that flow into a back-office capture path would
46
+ * put a consent screen behind an API call nobody is watching.
47
+ *
48
+ * CONNECTS TO:
49
+ * BASE: ./StripePaymentProvider.ts — auth, HTTP, form encoding, signature, fee lookup
50
+ * PURE: ./PaymentProviderBehavior.ts — AchFeeEstimate, DecideSettlement
51
+ * EFFECTS: ./PaymentSettlement.ts — what the webhook does with the answer
52
+ * DOC: plans/archive/bizapps-orders-master.md D19, D37
53
+ */
54
+ import { RegisterClass } from '@memberjunction/global';
55
+ import { BasePaymentProvider } from './BasePaymentProvider.js';
56
+ import { StripePaymentProvider } from './StripePaymentProvider.js';
57
+ import { AchFeeEstimate, FromMinorUnits } from './PaymentProviderBehavior.js';
58
+ /**
59
+ * Stripe's payment-method type for a US bank debit. Its own constant because it appears in the intent
60
+ * body and in the refusal messages, and a typo in either is a runtime surprise rather than a build one.
61
+ */
62
+ const US_BANK_ACCOUNT = 'us_bank_account';
63
+ /**
64
+ * The events this rail acts on.
65
+ *
66
+ * `payment_intent.processing` is here so the SUBMISSION is recorded rather than inferred from silence —
67
+ * without it, a payment sits `Pending` for four days with nothing on the intent to say the bank ever
68
+ * heard about it, and an operator cannot tell "submitted, waiting" from "never sent".
69
+ *
70
+ * BOTH `charge.failed` AND `payment_intent.payment_failed` ARE HANDLED, DELIBERATELY. A debit that
71
+ * fails before settling and one RETURNED after settling are different events at Stripe, and which
72
+ * arrives when is exactly the sort of detail this code should not be confident about. Handling both is
73
+ * safe rather than sloppy: `DecideSettlement` keys off the PAYMENT'S state, not the event's name, so a
74
+ * failure against a `Pending` payment fails it and a failure against a `Captured` one reverses it — no
75
+ * matter which of the two names Stripe used. The duplicate case costs nothing either, because
76
+ * `ProviderEventID` makes a second delivery of the SAME event a no-op and a second DIFFERENT event
77
+ * resolves to `None` once the first has been applied.
78
+ */
79
+ const ACH_HANDLED = [
80
+ 'payment_intent.processing',
81
+ 'payment_intent.succeeded',
82
+ 'payment_intent.payment_failed',
83
+ 'payment_intent.canceled',
84
+ 'charge.failed',
85
+ 'charge.refunded',
86
+ ];
87
+ let StripeACHPaymentProvider = class StripeACHPaymentProvider extends StripePaymentProvider {
88
+ /**
89
+ * The declaration that changes who books the cash. See `BasePaymentProvider.SettlesAsynchronously` —
90
+ * with this true, a caller leaves the payment `Pending` and the webhook promotes it.
91
+ */
92
+ get SettlesAsynchronously() {
93
+ return true;
94
+ }
95
+ get HandledEventKinds() {
96
+ return ACH_HANDLED;
97
+ }
98
+ /** A submitted debit is already in flight; it never waits for an instrument the way a card does. */
99
+ get StubIntentStatus() {
100
+ return 'Processing';
101
+ }
102
+ /** 0.8% capped at $5 — see `AchFeeEstimate` for why the stub reports a fee at all. */
103
+ StubFeeFor(amount, currencyCode) {
104
+ return AchFeeEstimate(amount, currencyCode);
105
+ }
106
+ /**
107
+ * Pin the intent to the bank-debit rail.
108
+ *
109
+ * EXPLICIT RATHER THAN `automatic_payment_methods`. Letting Stripe choose would make the rail a
110
+ * property of the account's dashboard settings, so the same code could open a card intent on one
111
+ * deployment and a bank debit on another — with a fee, a settlement delay and a reversal risk that
112
+ * differ by a factor of four and several days. The provider row says which rail this is; the
113
+ * request should say the same thing.
114
+ */
115
+ DecorateIntentBody(body, _request) {
116
+ body['payment_method_types[0]'] = US_BANK_ACCOUNT;
117
+ }
118
+ /**
119
+ * Ask the bank what happened. Nothing is captured here — see the header.
120
+ *
121
+ * REFUSES ON ANYTHING BUT `succeeded`, and the two refusals say different things on purpose.
122
+ * "Still processing" is the ordinary case — somebody captured too early, and they should wait for
123
+ * the webhook — while a failure means the debit will not clear and waiting is pointless. Both come
124
+ * back as refusals rather than exceptions, because neither is a fault: the gateway answered.
125
+ */
126
+ async Capture(request) {
127
+ if (this.useStub) {
128
+ const amount = request.Amount ?? 0;
129
+ return {
130
+ Success: true,
131
+ Amount: amount,
132
+ FeeAmount: this.StubFeeFor(amount, request.CurrencyCode),
133
+ ProviderChargeID: `ch_stub_ach_${request.ProviderIntentID.slice(-12)}`,
134
+ Status: 'Succeeded',
135
+ };
136
+ }
137
+ const read = await this.call('GET', `/payment_intents/${encodeURIComponent(request.ProviderIntentID)}`);
138
+ if (!read.Ok)
139
+ return { Success: false, Reason: read.Reason };
140
+ const status = String(read.Body.status ?? '');
141
+ if (status !== 'succeeded') {
142
+ return {
143
+ Success: false,
144
+ Status: status === 'processing' ? 'Processing' : 'Failed',
145
+ Reason: status === 'processing'
146
+ ? `The bank debit ${request.ProviderIntentID} has not cleared yet — it is still processing. ` +
147
+ `A bank debit settles on the bank's schedule, so this payment will be captured by the ` +
148
+ `webhook when the answer arrives rather than by asking again now.`
149
+ : `The bank debit ${request.ProviderIntentID} reads '${status}' at Stripe, so no money moved. ` +
150
+ `Capturing it would book cash that does not exist.`,
151
+ };
152
+ }
153
+ const currency = read.Body.currency ?? request.CurrencyCode;
154
+ const charge = this.latestCharge(read.Body);
155
+ const receivedMinor = Number(read.Body.amount_received ?? read.Body.amount ?? 0);
156
+ return {
157
+ Success: true,
158
+ Amount: FromMinorUnits(receivedMinor, currency),
159
+ // UNDEFINED rather than zero when it cannot be read — the same rule as the card path, and
160
+ // for the same reason: "we do not know the fee" must not be recorded as "there was no fee".
161
+ FeeAmount: await this.feeFor(charge, currency),
162
+ ProviderChargeID: charge ?? undefined,
163
+ Status: 'Succeeded',
164
+ };
165
+ }
166
+ /**
167
+ * Read a `charge.failed`, which the base driver has no reason to know about.
168
+ *
169
+ * THIS IS THE RETURN, and it is the event this whole rail exists to survive. It can arrive after
170
+ * the payment has been booked, in which case `charge.failed` is the only notice that money which
171
+ * appeared to arrive has gone back out. The base handles `payment_intent.*` and `charge.refunded`
172
+ * correctly, so everything else defers to it.
173
+ *
174
+ * The failure MESSAGE is carried through verbatim. Stripe writes it for a human ("insufficient
175
+ * funds", "no account"), and it ends up on the reversing payment's reason — which is the only place
176
+ * anyone reconciling next month will look.
177
+ */
178
+ ParseWebhookEvent(rawBody) {
179
+ const event = super.ParseWebhookEvent(rawBody);
180
+ if (!event || event.Kind !== 'charge.failed')
181
+ return event;
182
+ let object;
183
+ try {
184
+ const payload = JSON.parse(rawBody);
185
+ object = (payload.data?.object ?? {});
186
+ }
187
+ catch {
188
+ return event;
189
+ }
190
+ const currency = (object.currency ?? 'usd').toUpperCase();
191
+ event.ProviderChargeID = object.id ?? event.ProviderChargeID;
192
+ event.ProviderIntentID = object.payment_intent ?? event.ProviderIntentID;
193
+ event.Status = 'Failed';
194
+ const minor = Number(object.amount ?? 0);
195
+ if (Number.isFinite(minor) && minor > 0)
196
+ event.Amount = FromMinorUnits(minor, currency);
197
+ const message = object.failure_message ?? object.failure_code;
198
+ if (message)
199
+ event.FailureReason = String(message);
200
+ return event;
201
+ }
202
+ };
203
+ StripeACHPaymentProvider = __decorate([
204
+ RegisterClass(BasePaymentProvider, 'StripeACH')
205
+ ], StripeACHPaymentProvider);
206
+ export { StripeACHPaymentProvider };
207
+ /** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
208
+ export function LoadStripeACHPaymentProvider() {
209
+ // intentionally empty
210
+ }
211
+ //# sourceMappingURL=StripeACHPaymentProvider.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"StripeACHPaymentProvider.js","sourceRoot":"","sources":["../src/StripeACHPaymentProvider.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,83 @@
1
+ import { BasePaymentProvider, type CaptureRequest, type CaptureResult, type CreateIntentRequest, type CreateIntentResult, type RefundRequest, type RefundResult, type RetrieveIntentRequest, type RetrieveIntentResult, type WebhookEvent } from './BasePaymentProvider.js';
2
+ import { type IntentStatus } from './PaymentProviderBehavior.js';
3
+ export declare class StripePaymentProvider extends BasePaymentProvider {
4
+ get HandledEventKinds(): readonly string[];
5
+ /** The stub stands in whenever the configured account is not live. */
6
+ protected get useStub(): boolean;
7
+ /**
8
+ * The intent status the STUB reports on creation.
9
+ *
10
+ * A card intent opens waiting for an instrument. A bank debit opens already submitted, and a stub
11
+ * that claimed otherwise would exercise a state the real rail never passes through.
12
+ */
13
+ protected get StubIntentStatus(): IntentStatus;
14
+ /**
15
+ * The fee the STUB reports on capture — 2.9% + 30c, Stripe's standard US card rate.
16
+ *
17
+ * See the note at the call site for why a stub must not report zero.
18
+ */
19
+ protected StubFeeFor(amount: number, _currencyCode: string): number;
20
+ /**
21
+ * Last chance to add rail-specific fields to a `POST /payment_intents` body.
22
+ *
23
+ * Mutates rather than returns, so a subclass that forgets to call `super` cannot silently discard
24
+ * everything the base assembled — there is nothing to discard.
25
+ */
26
+ protected DecorateIntentBody(_body: Record<string, string>, _request: CreateIntentRequest): void;
27
+ CreateIntent(request: CreateIntentRequest): Promise<CreateIntentResult>;
28
+ RetrieveIntent(request: RetrieveIntentRequest): Promise<RetrieveIntentResult>;
29
+ Capture(request: CaptureRequest): Promise<CaptureResult>;
30
+ Refund(request: RefundRequest): Promise<RefundResult>;
31
+ VerifyWebhook(rawBody: string, headers: Record<string, string | undefined>): Promise<{
32
+ Valid: boolean;
33
+ Reason?: string;
34
+ }>;
35
+ ParseWebhookEvent(rawBody: string): WebhookEvent | null;
36
+ /**
37
+ * One call, with Stripe's own error shape read out of the body.
38
+ *
39
+ * A 4xx from Stripe is usually a REFUSAL — a declined card, an intent in the wrong state — and its
40
+ * `error.message` is written for a human. Surfacing that rather than "HTTP 402" is the difference
41
+ * between a support ticket somebody can answer and one they cannot.
42
+ *
43
+ * Only transport failures and 5xx throw. Those are faults; the rest are answers.
44
+ */
45
+ protected call(method: 'POST' | 'GET', path: string, body?: Record<string, string>, idempotencyKey?: string): Promise<{
46
+ Ok: boolean;
47
+ Reason?: string;
48
+ Body: Record<string, unknown>;
49
+ }>;
50
+ /**
51
+ * Map a Succeeded Stripe PaymentIntent body onto our CaptureResult. Shared by a real
52
+ * POST /capture and by the already-captured retrieve fallback so both paths stamp the
53
+ * same charge id and fee.
54
+ */
55
+ private captureResultFromIntent;
56
+ /** `latest_charge` is a string on modern API versions and an object on older expanded responses. */
57
+ protected latestCharge(object: Record<string, unknown>): string | null;
58
+ /**
59
+ * The gateway's cut, from the charge's balance transaction.
60
+ *
61
+ * Returns UNDEFINED when it cannot be determined, never 0 — see the note at the call site. A failed
62
+ * lookup here must not silently suppress the fee leg of the capture entry, and it must not fail the
63
+ * capture either: the money HAS moved by this point, and refusing now would leave the ledger
64
+ * disagreeing with the gateway.
65
+ */
66
+ protected feeFor(chargeID: string | null, currency: string): Promise<number | undefined>;
67
+ }
68
+ /**
69
+ * Stripe wants `application/x-www-form-urlencoded`, including for nested keys like `metadata[Foo]`.
70
+ *
71
+ * `URLSearchParams` encodes the brackets as `%5B%5D`, which Stripe accepts — so this is a thin wrapper
72
+ * rather than hand-rolled escaping. It exists as a named function because the temptation to build the
73
+ * body with template strings is exactly how an unescaped value ends up changing the request.
74
+ */
75
+ export declare function ToFormBody(fields: Record<string, string>): string;
76
+ /**
77
+ * True when Stripe refused POST /capture because the intent was already captured
78
+ * (automatic-capture confirmCardPayment, or a retried Capture).
79
+ */
80
+ export declare function stripeCaptureAlreadyCollected(reason: string | undefined, body: Record<string, unknown>): boolean;
81
+ /** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
82
+ export declare function LoadStripePaymentProvider(): void;
83
+ //# sourceMappingURL=StripePaymentProvider.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"StripePaymentProvider.d.ts","sourceRoot":"","sources":["../src/StripePaymentProvider.ts"],"names":[],"mappings":"AA8BA,OAAO,EACH,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAKH,KAAK,YAAY,EACpB,MAAM,8BAA8B,CAAC;AAYtC,qBACa,qBAAsB,SAAQ,mBAAmB;IAC1D,IAAoB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAEzD;IAED,sEAAsE;IACtE,SAAS,KAAK,OAAO,IAAI,OAAO,CAE/B;IAUD;;;;;OAKG;IACH,SAAS,KAAK,gBAAgB,IAAI,YAAY,CAE7C;IAED;;;;OAIG;IACH,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAInE;;;;;OAKG;IACH,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAM1E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6CvE,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA2B7E,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuDxD,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiCrD,aAAa,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC5C,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAM/B,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAqDvE;;;;;;;;OAQG;cACa,IAAI,CAChB,MAAM,EAAE,MAAM,GAAG,KAAK,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,cAAc,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAuD3E;;;;OAIG;YACW,uBAAuB;IAoBrC,oGAAoG;IACpG,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI;IAStE;;;;;;;OAOG;cACa,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAcjG;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAMjE;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAST;AAED,0FAA0F;AAC1F,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}