@antelopejs/interface-payment 0.0.2 → 0.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.
@@ -1,16 +1,20 @@
1
- # Webhooks and events
1
+ ---
2
+ title: Webhooks and events
3
+ description: Verify a webhook delivery with VerifyWebhook, learn the normalised event set, and handle repeated and out-of-order events.
4
+ mode: how-to
5
+ ---
2
6
 
3
7
  Every provider this interface targets settles some payments asynchronously. A
4
- backend that reads only what its own calls return will report a payment pending
5
- that succeeded twenty minutes ago. Webhooks are not optional here — they are the
6
- only way to learn a terminal state.
8
+ backend that reads only what its own calls return can report a payment as
9
+ pending twenty minutes after it succeeded. Webhooks are required here, because
10
+ they are the only way to learn a terminal state.
7
11
 
8
12
  ## Verifying a delivery
9
13
 
10
14
  In an `@antelopejs/interface-api` controller, read all headers from the request
11
- context. `handle` below is your application's idempotent event handler.
15
+ context. In the example, `handle` is your application's idempotent event handler.
12
16
 
13
- ```ts
17
+ ```ts fragment
14
18
  import { Context, HTTPResult, Post, RawBody } from "@antelopejs/interface-api";
15
19
  import type { RequestContext } from "@antelopejs/interface-api";
16
20
  import { VerifyWebhook, WebhookVerificationError } from "@antelopejs/interface-payment";
@@ -32,21 +36,21 @@ async webhook(@RawBody() body: Buffer, @Context() context: RequestContext) {
32
36
  }
33
37
  ```
34
38
 
35
- `WebhookRequest.body` is typed `Uint8Array` rather than `Buffer` so this
36
- package's published types carry no ambient Node dependency — a consumer
37
- compiling without `@types/node` would otherwise fail inside `node_modules`. A
38
- Node `Buffer` is a `Uint8Array`, and is what an HTTP handler hands you, so pass
39
- it straight through.
39
+ `WebhookRequest.body` has the type `Uint8Array`, not `Buffer`, so the published
40
+ types of this package need no ambient Node.js types. Without that choice, a
41
+ consumer that compiles without `@types/node` would fail inside `node_modules`. A
42
+ Node.js `Buffer` is a `Uint8Array`, and an HTTP handler gives you a `Buffer`, so
43
+ pass it straight through.
40
44
 
41
- **The body must be the raw bytes.** Signature schemes cover the bytes as sent, so
42
- a body that has been through `JSON.parse` and re-serialised will not verify —
45
+ **The body must be the raw bytes.** A signature covers the bytes as sent. A body
46
+ that has been through `JSON.parse` and serialised again does not verify, because
43
47
  key order and whitespace change. Use a raw body handler on this route.
44
48
 
45
- Node's `rawRequest.headers` provides lowercase names and preserves the
46
- `string | string[] | undefined` values accepted by `WebhookRequest.headers`.
47
- There is no `@Headers()` decorator in the API interface.
49
+ Node.js gives `rawRequest.headers` lowercase names, and its values have the
50
+ `string | string[] | undefined` type that `WebhookRequest.headers` accepts.
51
+ The API interface has no `@Headers()` decorator.
48
52
 
49
- Three outcomes, and they are distinct on purpose:
53
+ `VerifyWebhook` has three distinct outcomes:
50
54
 
51
55
  | Outcome | Meaning | Respond |
52
56
  | -------------------------- | ------------------------------------------ | ------------------- |
@@ -54,22 +58,23 @@ Three outcomes, and they are distinct on purpose:
54
58
  | `undefined` | Genuine, but not one of the modelled types | 200 |
55
59
  | `WebhookVerificationError` | Could not be established as genuine | 403, act on nothing |
56
60
 
57
- **"Genuine" is not always a signature check.** Stripe, Adyen and PayPal sign, so
58
- verification is the signature over the raw bytes. Mollie and Mangopay do not
59
- sign: the delivery is a bare record identifier, and the implementation
60
- establishes it by reading that record back from the provider. A body naming no
61
- record, or one the provider will not confirm, raises `WebhookVerificationError`
62
- on those providers just as a bad signature does on the others. Your handler is
63
- the same either way — which is the point.
61
+ **"Genuine" is not always a signature check.** Stripe, Adyen, and PayPal sign
62
+ their deliveries, so verification checks the signature over the raw bytes.
63
+ Mollie and Mangopay do not sign. Their delivery is a bare record identifier, and
64
+ the implementation establishes it by reading that record back from the provider.
65
+ On those providers, a body that names no record, or a record the provider does
66
+ not confirm, raises `WebhookVerificationError`, just as a bad signature does on
67
+ the others. Your handler is the same for both kinds of provider, and that is the
68
+ reason for the design.
64
69
 
65
70
  ### Where an event's fields may come from
66
71
 
67
- This is the part that bites, and it is a rule for implementations rather than
68
- for callers.
72
+ This rule is for implementations, not for callers, and it is the easiest one to
73
+ get wrong.
69
74
 
70
75
  **Every field of the returned event must come from data the implementation has
71
- authenticated.** Establishing a delivery and populating an event are two steps,
72
- and the first proves different things on different providers:
76
+ authenticated.** Establishing a delivery and populating an event are two steps.
77
+ The first step proves different things on different providers:
73
78
 
74
79
  | Style | What establishing proves | What the event may be built from |
75
80
  | ------------------------------ | ---------------------------- | -------------------------------- |
@@ -77,94 +82,104 @@ and the first proves different things on different providers:
77
82
  | Re-fetched (Mollie, Mangopay) | A record with that id exists | **The record read back, only** |
78
83
 
79
84
  A re-fetch proves the identifier. It proves nothing about any other field in the
80
- body — not the event type, not the amount, not the status. So on a re-fetch
81
- provider the body is a pointer and nothing else: the event's `type`, the kind of
82
- record it is, and every field of `payment`, `refund` or `dispute` come from the
83
- record that was read.
84
-
85
- The failure mode is writing a re-fetch provider by analogy with a signed one,
86
- which is what a careful implementer does. Mangopay's delivery carries
87
- `RessourceId`, `EventType` and `Date`, and `EventType` maps neatly onto
88
- `PaymentEvent.type` — so an implementation that re-fetches to establish the
89
- delivery and then reads `EventType` from the body accepts an unauthenticated
90
- payment-state forgery. Anyone who can reach the endpoint posts a real payment id
91
- with a succeeded event type; the read confirms the id exists; verification
92
- passes; the backend ships goods for a payment the provider's own record says is
93
- pending or failed.
94
-
95
- Mollie is safe here by accident rather than by design — its body is only
96
- `id=tr_xxx`, so there is nothing else to trust even if an implementer wanted to.
97
- Mangopay is the live case, and a provider added later is the general one.
98
-
99
- The `undefined` case is the common one. Providers send dozens of event types —
100
- account updates, payout notifications, report completions — and an interface that
101
- threw on all of them would make every implementation reject genuine traffic,
102
- which providers answer by retrying for days. Verified-but-unmodelled is a normal
103
- result, not a problem.
85
+ body: not the event type, not the amount, and not the status. On a re-fetch
86
+ provider, the body is a pointer and nothing else. The event's `type`, the kind of
87
+ record, and every field of `payment`, `refund`, or `dispute` come from the record
88
+ that the implementation read.
89
+
90
+ The failure mode is an implementation for a re-fetch provider written by analogy
91
+ with a signed one, and a careful implementer can make this mistake. A Mangopay
92
+ delivery carries `RessourceId`, `EventType`, and `Date`, and `EventType` maps
93
+ neatly onto `PaymentEvent.type`. Suppose an implementation re-fetches to
94
+ establish the delivery and then reads `EventType` from the body. It accepts an
95
+ unauthenticated forgery of the payment state. Anyone who can reach the endpoint
96
+ posts a real payment id with a succeeded event type. The read confirms that the
97
+ id exists, and verification passes. The backend then ships goods for a payment
98
+ that the provider's own record says is pending or failed.
99
+
100
+ Mollie avoids this problem by accident, not by design. Its body is only
101
+ `id=tr_xxx`, so there is nothing else for an implementer to trust. Mangopay is
102
+ the real case, and any provider added later is the general case.
103
+
104
+ The `undefined` outcome is the common one. Providers send dozens of event types,
105
+ such as account updates, payout notifications, and report completions. If the
106
+ interface threw on all of them, every implementation would reject genuine
107
+ traffic, and providers answer a rejection by retrying for days. A verified but
108
+ unmodelled delivery is a normal result.
104
109
 
105
110
  ## The event set
106
111
 
107
- ```ts
112
+ ```text
108
113
  "payment.pending" "payment.authorized" "payment.succeeded"
109
114
  "payment.failed" "payment.canceled" "refund.succeeded"
110
115
  "refund.failed" "dispute.opened"
111
116
  ```
112
117
 
113
- The `payment.*` types are exactly the `PaymentStatus` values a backend learns
114
- about asynchronously. `requires_action` has no event because it is known
115
- synchronously, from the call that created the payment — no provider tells you
116
- later that a payer needs to authenticate.
118
+ The `payment.*` types are exactly the `PaymentStatus` values that a backend
119
+ learns asynchronously. `requires_action` has no event, because the call that
120
+ created the payment returns it synchronously. No provider tells you later that a
121
+ payer needs to authenticate.
117
122
 
118
- `payment.canceled` covers abandonment and expiry, not just a `CancelPayment` you
123
+ `payment.canceled` covers abandonment and expiry as well as a `CancelPayment` you
119
124
  made yourself. An abandoned checkout is the most common outcome of a hosted
120
- session, and without this event a backend leaks orders that sit pending forever.
125
+ session. Without this event, a backend keeps orders pending forever.
121
126
 
122
- `payment.authorized` is what tells an auth-then-capture backend that the hold
123
- landed. Without it the auth/capture flow would only work synchronously, which on
124
- a redirect-first provider means not at all.
127
+ `payment.authorized` tells a backend that authorizes and then captures that the
128
+ hold is in place. Without it, the authorize and capture flow would work only
129
+ synchronously. On a provider that redirects first, it would not work at all.
125
130
 
126
- Exactly one of `payment`, `refund` and `dispute` is set, matching the type
127
- prefix, and it carries the object's state at the moment the provider sent it.
131
+ Exactly one of `payment`, `refund`, and `dispute` is set, matching the type
132
+ prefix. It carries the object's state at the moment the provider sent the event,
133
+ which may already be stale.
128
134
 
129
135
  ## Handling
130
136
 
131
- ```ts
132
- const HANDLERS = {
133
- "payment.succeeded": (event) => orders.fulfil(event.payment!.reference),
134
- "payment.failed": (event) => orders.declined(event.payment!.reference),
135
- "payment.canceled": (event) => orders.release(event.payment!.reference),
136
- "payment.authorized": (event) => orders.readyToShip(event.payment!.reference),
137
- "payment.pending": (event) =>
138
- orders.awaitingSettlement(event.payment!.reference),
139
- "refund.succeeded": (event) => refunds.settled(event.refund!.id),
140
- "refund.failed": (event) => refunds.retry(event.refund!.id),
141
- "dispute.opened": (event) => disputes.open(event.dispute!),
137
+ ```ts fragment
138
+ import type {
139
+ PaymentEvent,
140
+ PaymentEventType,
141
+ } from "@antelopejs/interface-payment";
142
+
143
+ const HANDLERS: Record<PaymentEventType, (event: PaymentEvent) => unknown> = {
144
+ "payment.succeeded": ({ payment }) =>
145
+ payment && orders.fulfil(payment.reference),
146
+ "payment.failed": ({ payment }) =>
147
+ payment && orders.declined(payment.reference),
148
+ "payment.canceled": ({ payment }) =>
149
+ payment && orders.release(payment.reference),
150
+ "payment.authorized": ({ payment }) =>
151
+ payment && orders.readyToShip(payment.reference),
152
+ "payment.pending": ({ payment }) =>
153
+ payment && orders.awaitingSettlement(payment.reference),
154
+ "refund.succeeded": ({ refund }) => refund && refunds.settled(refund.id),
155
+ "refund.failed": ({ refund }) => refund && refunds.retry(refund.id),
156
+ "dispute.opened": ({ dispute }) => dispute && disputes.open(dispute),
142
157
  };
143
158
 
144
- async function handle(event) {
159
+ async function handle(event: PaymentEvent) {
145
160
  if (await events.seen(event.id)) return;
146
- await HANDLERS[event.type]?.(event);
161
+ await HANDLERS[event.type](event);
147
162
  await events.record(event.id);
148
163
  }
149
164
  ```
150
165
 
151
- Two rules, and both bite in production:
166
+ Follow two rules. Production traffic breaks both if you ignore them.
152
167
 
153
- **De-duplicate on `event.id`.** Providers redeliver. A delivery your handler
154
- acknowledged can arrive again because the acknowledgement was lost, and a
155
- handler that ships an order twice is a real loss.
168
+ **De-duplicate on `event.id`.** Providers redeliver. A delivery that your handler
169
+ acknowledged can arrive again because the acknowledgement was lost. A handler
170
+ that ships an order twice loses real money.
156
171
 
157
172
  **Do not assume an event is newer than what you hold.** Providers deliver out of
158
- order, and a `payment.pending` can land after the `payment.succeeded` for the
159
- same payment. Guard on your own record's state, or re-read with `GetPayment`
160
- before acting on a transition backwards.
173
+ order, and a `payment.pending` can arrive after the `payment.succeeded` for the
174
+ same payment. Guard on your own record's state, or read the payment again with
175
+ `GetPayment` before you act on a backwards transition.
161
176
 
162
177
  ## Disputes
163
178
 
164
- `dispute.opened` reports that a payer has challenged a captured payment, so a
165
- backend can react — hold the goods, notify someone, flag the account.
179
+ `dispute.opened` reports that a payer has challenged a captured payment. A
180
+ backend can then react: hold the goods, notify someone, or flag the account.
166
181
 
167
- Responding to a dispute is not modelled. The evidence a provider wants, the
168
- format, the deadlines and the appeal path differ so much between them that an
182
+ The interface does not model the response to a dispute. Providers differ so much
183
+ in the evidence they want, its format, the deadlines, and the appeal path that an
169
184
  abstraction would be a thin wrapper nobody could use portably. Respond through
170
185
  the provider's own interface or its dashboard.
@@ -1,16 +1,21 @@
1
- # Provider capability matrix
1
+ ---
2
+ title: Provider capability matrix
3
+ description: How each provider family implements each call in the contract, where the contract changed to fit them, and why some features stay out.
4
+ mode: explanation
5
+ ---
2
6
 
3
7
  This interface is not the lowest common denominator, and it is not Stripe with
4
- the names changed. It is the set of flows a typical backend needs where all four
5
- provider families can plausibly implement each one.
8
+ the names changed. It is the set of flows a typical backend needs, chosen so that
9
+ all four provider families can plausibly implement each one.
6
10
 
7
- The bar: a backend on this interface can change provider. An implementation may
8
- decline a flow and throw `UnsupportedOperationError`, but the feature set is
9
- chosen so that declining is uncommon.
11
+ The bar is that a backend on this interface can change provider. An
12
+ implementation may decline a flow and throw `UnsupportedOperationError`, but the
13
+ feature set is chosen so that declining is uncommon.
10
14
 
11
- Only Stripe is implemented in the AntelopeJS ecosystem today. The other three
12
- families are paper constraints on the shape — each was checked against its public
13
- API before a proxy was added, and full coverage is expected of none of them.
15
+ `@antelopejs/stripe` is the public AntelopeJS module that implements this
16
+ interface. For the other families, the authors checked each one against its
17
+ public API before they added a function, and the design expects full coverage
18
+ from none of them.
14
19
 
15
20
  ## The four families
16
21
 
@@ -23,7 +28,8 @@ API before a proxy was added, and full coverage is expected of none of them.
23
28
 
24
29
  ## What is in, and what each family does behind it
25
30
 
26
- ✅ native · ⚠️ implementable with work · ❌ would have to decline
31
+ The table uses three marks: ✅ native, ⚠️ implementable with work, and ❌ would
32
+ have to decline.
27
33
 
28
34
  | Contract | Stripe | PayPal | Adyen | Mollie | Mangopay |
29
35
  | ---------------------------------- | --------------------------- | ------------------------- | ------------------------- | ------------------------------- | --------------------- |
@@ -43,105 +49,110 @@ API before a proxy was added, and full coverage is expected of none of them.
43
49
  | `DeleteCustomer` | ✅ | ⚠️ detach all tokens | ⚠️ disable all | ✅ | ⚠️ deactivate user |
44
50
  | `VerifyWebhook` | ✅ signed | ✅ verify-signature call | ✅ HMAC | ⚠️ unsigned; re-fetch | ⚠️ re-fetch |
45
51
 
46
- Nothing in the contract is ❌ for any family. That is the test the feature set was
47
- chosen to pass.
52
+ No call in the contract is ❌ for any family. The feature set was chosen to pass
53
+ that test.
48
54
 
49
55
  ## The two places the contract bent to fit
50
56
 
51
- These are design changes made _because_ of the four-family audit, not despite it.
57
+ The four-family audit caused these two design changes.
52
58
 
53
59
  ### Customers are an identifier, not a profile
54
60
 
55
- PayPal and Adyen have no first-class customer object. PayPal's vault hangs tokens
56
- off a `customer_id` you mint yourself; Adyen's `shopperReference` is a string you
57
- choose. Neither stores an email or a name you can read back.
61
+ PayPal and Adyen have no first-class customer object. PayPal's vault attaches
62
+ tokens to a `customer_id` that you create yourself. Adyen's `shopperReference` is
63
+ a string you choose. Neither stores an email or a name that you can read back.
58
64
 
59
- Modelling `Customer` as a record with retrievable attributes would have made two
60
- of five implementations return a mostly-empty object and quietly break backends
61
- that read `customer.email`. So `Customer` guarantees the identifier and nothing
62
- else, `email` and `name` are documented as write-where-supported, and the
63
- conformance suite asserts only that the identifier round-trips.
65
+ If `Customer` were a record with attributes you could read back, two of five
66
+ implementations would return a mostly empty object. Backends that read
67
+ `customer.email` would break without an error. So `Customer` guarantees the
68
+ identifier and nothing else. The TSDoc says that `email` and `name` are stored
69
+ where supported, and the conformance suite asserts only that the identifier
70
+ round-trips.
64
71
 
65
- What a customer _is_ here is a container for saved payment methods — which is
66
- exactly what `shopperReference` is. The flow survives the audit; the data model
67
- had to shrink to survive it.
72
+ Here, a customer _is_ a container for saved payment methods, which is exactly
73
+ what `shopperReference` is. The flow survived the audit, but the data model had
74
+ to shrink.
68
75
 
69
76
  ### Unsigned webhooks still verify
70
77
 
71
78
  Mollie does not sign webhooks. The delivery is a payment identifier and nothing
72
- else, and the documented way to trust it is to call the API and read the current
73
- state. Mangopay is similar.
79
+ else, and Mollie documents one way to trust it: call the API and read the current
80
+ state. Mangopay works the same way.
74
81
 
75
- `VerifyWebhook` is therefore specified by its _outcome_ — a normalised event you
76
- can trust — rather than as a signature check. A Mollie implementation fetches the
77
- payment inside `VerifyWebhook` and returns a full event; a Stripe implementation
82
+ So the contract specifies `VerifyWebhook` by its _outcome_, a normalised event
83
+ you can trust, and not as a signature check. A Mollie implementation fetches the
84
+ payment inside `VerifyWebhook` and returns a full event. A Stripe implementation
78
85
  checks the HMAC and reads the body. Both satisfy the same contract, and a backend
79
86
  writes one handler.
80
87
 
81
- Had the contract been `VerifyWebhookSignature(body, signature) => boolean`,
82
- Mollie would have had to decline it.
88
+ With a contract of `VerifyWebhookSignature(body, signature) => boolean`, Mollie
89
+ would have had to decline.
83
90
 
84
- The residual risk in this bend is that establishing a delivery and populating an
85
- event prove different things. A signature authenticates the whole body; a
86
- re-fetch authenticates one record and says nothing about the rest of the body.
87
- The contract therefore requires that on a re-fetch provider every field of the
88
- event comes from the record read back, and that the body is treated as a pointer
89
- only — see [Webhooks](./4.webhooks.md). Without that rule, a Mangopay module
90
- written by analogy with the Stripe one accepts a forged payment state.
91
+ The remaining risk is that establishing a delivery and populating an event prove
92
+ different things. A signature authenticates the whole body. A re-fetch
93
+ authenticates one record and says nothing about the rest of the body. So the
94
+ contract requires that, on a re-fetch provider, every field of the event comes
95
+ from the record read back, and that the implementation treats the body as a
96
+ pointer only. [Webhooks](./4.webhooks.md) covers the details. Without that rule,
97
+ a Mangopay module written by analogy with the Stripe one accepts a forged payment
98
+ state.
91
99
 
92
- This rule is **specified but not enforced by the conformance suite**: forging a
93
- delivery is not portable across providers, and the suite has no endpoint to
94
- receive a genuine one at, so `VerifyWebhook`'s success path is untested
95
- altogether. It is held by review of each implementation.
100
+ The contract **specifies this rule, but the conformance suite does not enforce
101
+ it**. Forging a delivery is not portable across providers, and the suite has no
102
+ endpoint where a genuine delivery could arrive. As a result, the suite does not
103
+ test the success path of `VerifyWebhook` at all. Review of each implementation
104
+ holds the rule.
96
105
 
97
106
  ## What is out, and why
98
107
 
99
108
  ### Subscriptions, invoicing, proration, dunning, tax, coupons
100
109
 
101
- The largest single judgement call. Provider subscription objects diverge more
102
- than any other area: billing anchors, proration arithmetic, trial handling,
103
- dunning schedules and tax engines are all different, and several families have no
104
- equivalent at all. An interface over them would be one most implementations
105
- decline.
110
+ This was the largest single judgement call. Provider subscription objects differ
111
+ more than any other area. Billing anchors, proration arithmetic, trial handling,
112
+ dunning schedules, and tax engines all differ, and several families have no
113
+ equivalent at all. Most implementations would decline an interface over them.
106
114
 
107
- What _is_ portable is the mechanism underneath: save a payment method, charge it
108
- off-session on your own schedule. A backend selling recurring access runs its own
109
- cycle on `ListPaymentMethods` + `CreatePayment`, and that works on all five.
110
- Filed as a follow-up rather than dropped — if a portable subset emerges, it would
111
- build on saved methods rather than on provider subscription objects.
115
+ The portable part is the mechanism underneath: save a payment method, then charge
116
+ it off-session on your own schedule. A backend that sells recurring access runs
117
+ its own cycle on `ListPaymentMethods` and `CreatePayment`, and that works on all
118
+ five providers. The portable subset lives in a separate interface,
119
+ `@antelopejs/interface-subscriptions`. `@antelopejs/payment-subscriptions`
120
+ implements it on saved methods and off-session charges, not on provider
121
+ subscription objects.
112
122
 
113
123
  ### Marketplace and split payments
114
124
 
115
- Stripe Connect, PayPal Commerce Platform, Adyen for Platforms and Mangopay's
116
- wallets are incompatible models, not different spellings of one. Connect splits a
117
- charge; Mangopay moves money between wallets it holds; PayPal routes to
118
- merchants. A backend doing this is deep in one provider's model and should use
119
- that provider's own interface.
125
+ Stripe Connect, PayPal Commerce Platform, Adyen for Platforms, and Mangopay's
126
+ wallets are incompatible models, not different spellings of one model. Connect
127
+ splits a charge. Mangopay moves money between wallets it holds. PayPal routes
128
+ payments to merchants. A backend that does this depends deeply on one provider's
129
+ model, and should use that provider's own interface.
120
130
 
121
131
  ### Dispute management
122
132
 
123
- An event, not an API. Evidence formats, deadlines and appeal paths differ so much
124
- that a portable submission call would be a wrapper nobody could use. `dispute.opened`
125
- tells a backend to react; responding goes through the provider.
133
+ A dispute is an event here, with no API to respond. Evidence formats, deadlines,
134
+ and appeal paths differ so much that a portable submission call would be a
135
+ wrapper nobody could use. `dispute.opened` tells a backend to react, and the
136
+ response goes through the provider.
126
137
 
127
138
  ### Payment links and in-person terminals
128
139
 
129
- Payment links are a dashboard feature more than an API one, and terminal
130
- integrations are hardware-bound and provider-specific.
140
+ Payment links are mostly a dashboard feature, not an API feature. Terminal
141
+ integrations depend on hardware and on one provider.
131
142
 
132
143
  ## How this is kept honest
133
144
 
134
- `src/tests/payment.test.ts` ships in the package and runs against whichever
135
- provider module is wired in. It is written against the contract, not against
136
- Stripe's behaviour, and it is what the second provider will be held to.
145
+ The conformance suite in `src/tests` ships in the package and runs against
146
+ whichever provider module is wired in. It tests the contract, not Stripe's
147
+ behavior, and every provider implementation must pass it.
137
148
 
138
- Most of it needs no fixture and cannot pass without touching a live provider:
139
- session creation, customer lifecycle, idempotency replay, unknown-identifier
140
- errors, webhook signature rejection.
149
+ Most of the suite needs no fixture, and cannot pass without a live provider. That
150
+ part covers session creation, the customer lifecycle, idempotency replay,
151
+ unknown-identifier errors, and webhook signature rejection.
141
152
 
142
- The charge tests need a chargeable test payment method, which has no portable way
143
- to mint — a card is entered by a payer, and every provider publishes its own test
144
- token instead. The provider module supplies one through
145
- `ANTELOPE_PAYMENT_TEST_METHOD`, and those tests skip, visibly and by name, when
146
- it is absent. That is test _data_ supplied at the boundary, not a stub standing
147
- in for provider behaviour.
153
+ The charge tests need a chargeable test payment method, and there is no portable
154
+ way to create one. A payer enters a real card, and every provider publishes its
155
+ own test token instead. The provider module supplies one through
156
+ `ANTELOPE_PAYMENT_TEST_METHOD`. When it is absent, those tests skip, visibly and
157
+ by name. The token is test _data_ supplied at the boundary, not a stub that
158
+ stands in for provider behavior.
@@ -1,6 +1,8 @@
1
1
  {
2
2
  "extends": "../tsconfig.json",
3
3
  "compilerOptions": {
4
+ "module": "esnext",
5
+ "moduleResolution": "bundler",
4
6
  "noEmit": true,
5
7
  "composite": false,
6
8
  "incremental": false,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-payment",
3
- "version": "0.0.2",
3
+ "version": "0.2.0",
4
4
  "description": "Provider-agnostic AntelopeJS payment interface: hosted checkout, direct payments with auth/capture, refunds, saved payment methods, and normalised webhook events",
5
5
  "keywords": [
6
6
  "antelopejs",
@@ -26,6 +26,12 @@
26
26
  ],
27
27
  "main": "dist/index.js",
28
28
  "types": "dist/index.d.ts",
29
+ "imports": {
30
+ "#built": {
31
+ "types": "./src/index.ts",
32
+ "default": "./dist/index.js"
33
+ }
34
+ },
29
35
  "exports": {
30
36
  ".": {
31
37
  "types": "./dist/index.d.ts",
@@ -48,18 +54,27 @@
48
54
  "lint:fix": "oxlint --fix",
49
55
  "lint": "oxlint",
50
56
  "prepack": "pnpm run build",
51
- "release": "pnpm run lint && pnpm run prepack && release-it",
57
+ "release": "pnpm run lint && pnpm run test && pnpm run prepack && release-it",
52
58
  "format:check": "oxfmt --check .",
53
- "knip": "knip"
59
+ "knip": "knip",
60
+ "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
61
+ "checks": "antelopejs-checks",
62
+ "size": "antelopejs-check-size",
63
+ "sync": "antelopejs-sync",
64
+ "sync:check": "antelopejs-sync --check",
65
+ "typecheck": "tsc --noEmit",
66
+ "suppressions": "antelopejs-suppressions",
67
+ "suppressions:update": "antelopejs-suppressions --update"
54
68
  },
55
69
  "devDependencies": {
56
70
  "@antelopejs/core": "1.16.0",
57
71
  "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
58
- "@antelopejs/tooling-configs": "^0.0.8",
72
+ "@antelopejs/tooling-configs": "^0.2.17",
59
73
  "@types/mocha": "^10.0.10",
60
74
  "@types/node": "^22.19.15",
61
75
  "eslint-plugin-perfectionist": "^5.11.0",
62
76
  "knip": "^6.34.0",
77
+ "lefthook": "^2.2.2",
63
78
  "oxfmt": "^0.66.0",
64
79
  "oxlint": "1.81.0",
65
80
  "oxlint-tsgolint": "^7.0.2001",
@@ -76,6 +91,9 @@
76
91
  "test": "src/antelope.test.ts",
77
92
  "skills": [
78
93
  "./skills"
79
- ]
94
+ ],
95
+ "docs": {
96
+ "standard": true
97
+ }
80
98
  }
81
99
  }