@fun-xyz/fiat-contract 0.37.0 → 0.38.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,5 +1,5 @@
1
1
  // package.json
2
- var version = "0.37.0";
2
+ var version = "0.38.0";
3
3
 
4
4
  // src/table.ts
5
5
  var TABLE_VERSION = version;
@@ -359,15 +359,15 @@ var TRANSITION_TABLE = {
359
359
  id: "poll",
360
360
  mode: "AWAIT",
361
361
  endpoint: "GET /fiat/orders/:id",
362
- when: "status is non-terminal",
363
- note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
362
+ when: "status is non-terminal and the request carried no destinationAsset",
363
+ note: "For older clients only: an order whose request carried a destinationAsset offers delivery instead. Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
364
364
  },
365
365
  {
366
366
  id: "delivery",
367
367
  mode: "AWAIT",
368
368
  endpoint: "GET /fiat/delivery/:deliveryId",
369
- when: "status is SETTLED and the order is a leg of a delivery with more legs after it: the provider paid a deposit address that converts into the destinationAsset",
370
- note: "The backend decides; the client never infers that a delivery has more legs. It follows this transition when offered, and otherwise treats SETTLED as done."
369
+ when: "the request carried a destinationAsset: offered from creation, in every status",
370
+ note: "The backend decides; the client never infers it. It follows this transition when offered and then polls only GET /fiat/delivery/:deliveryId, which reports both the fiat leg and any conversion after it. Without it the client polls the order and treats SETTLED as done. giveUpAfterMs is the time left in the one delivery polling window, which starts at the order's creation (15 minutes); see DELIVERY:PENDING."
371
371
  },
372
372
  {
373
373
  id: "retry_payment",
@@ -397,7 +397,7 @@ var TRANSITION_TABLE = {
397
397
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
398
398
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
399
399
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
400
- "SETTLED is terminal for the order and ends a direct purchase. When its delivery has more legs, it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/delivery/:deliveryId). The order body itself never describes the conversion.",
400
+ "SETTLED is terminal for the order. For a request that carried a destinationAsset the purchase is read from DELIVERY (GET /fiat/delivery/:deliveryId) from creation, so the client never polls the order. The order body itself never describes the conversion.",
401
401
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
402
402
  ]
403
403
  },
@@ -412,13 +412,14 @@ var TRANSITION_TABLE = {
412
412
  id: "poll",
413
413
  mode: "AWAIT",
414
414
  endpoint: "GET /fiat/delivery/:deliveryId",
415
- note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
415
+ note: "Every answer carries giveUpAfterMs: the time left in one polling window that starts at the order's creation (15 minutes), so the window never restarts. When it runs out the client closes the wizard and relies on the notification at the end of the purchase. Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
416
416
  }
417
417
  ],
418
418
  mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
419
419
  terminal: false,
420
420
  notes: [
421
- "The fiat leg is SETTLED; a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows a generic processing screen."
421
+ "Covers both legs: the fiat order is not terminal yet, or it settled and a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows one waiting screen.",
422
+ "No cancel here. TODO(open-decision): cancel placement (FE doc open questions 1+2)."
422
423
  ]
423
424
  },
424
425
  "DELIVERY:SUCCEEDED": {
@@ -430,7 +431,9 @@ var TRANSITION_TABLE = {
430
431
  allowedTransitions: [],
431
432
  mayReturn: [],
432
433
  terminal: true,
433
- notes: ["The destinationAsset reached the user. txHash is the transaction that paid them."]
434
+ notes: [
435
+ "The destinationAsset reached the user. txHash is the transaction that paid them: the fiat order payout on a direct delivery, the conversion payout on a converted one."
436
+ ]
434
437
  },
435
438
  "DELIVERY:FAILED": {
436
439
  key: "DELIVERY:FAILED",
@@ -442,7 +445,8 @@ var TRANSITION_TABLE = {
442
445
  mayReturn: [],
443
446
  terminal: true,
444
447
  notes: [
445
- "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
448
+ "FAILED covers both legs: the fiat order failed, was refunded, expired or was cancelled, or the buyer paid and the asset did not arrive. The state carries no reason field.",
449
+ "FAILED offers no transition: the client shows the failure screen and offers no new payment from it. When the buyer paid, support recovers the funds."
446
450
  ]
447
451
  }
448
452
  };
package/dist/index.js CHANGED
@@ -1244,8 +1244,16 @@ var $providerBoundStepResponse = obj({
1244
1244
  expiresAt: import_zod.z.string()
1245
1245
  }).optional(),
1246
1246
  orderId: import_zod.z.string().optional(),
1247
- refreshLimits: import_zod.z.literal(true).optional()
1247
+ refreshLimits: import_zod.z.literal(true).optional(),
1248
+ feeSubsidy: obj({ estimatedFee: $money.optional() }).optional()
1248
1249
  }).superRefine((response, context) => {
1250
+ if (response.feeSubsidy !== void 0 && "quote" in response.state && response.state.quote?.feeSubsidy !== void 0) {
1251
+ context.addIssue({
1252
+ code: "custom",
1253
+ path: ["feeSubsidy"],
1254
+ message: "a priced quote carries quote.feeSubsidy instead"
1255
+ });
1256
+ }
1249
1257
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1250
1258
  context.addIssue({
1251
1259
  code: "custom",
@@ -1291,7 +1299,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
1291
1299
  var FiatStepResponseSchema = $stepResponse;
1292
1300
 
1293
1301
  // package.json
1294
- var version = "0.37.0";
1302
+ var version = "0.38.0";
1295
1303
 
1296
1304
  // src/table.ts
1297
1305
  var TABLE_VERSION = version;
@@ -1651,15 +1659,15 @@ var TRANSITION_TABLE = {
1651
1659
  id: "poll",
1652
1660
  mode: "AWAIT",
1653
1661
  endpoint: "GET /fiat/orders/:id",
1654
- when: "status is non-terminal",
1655
- note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
1662
+ when: "status is non-terminal and the request carried no destinationAsset",
1663
+ note: "For older clients only: an order whose request carried a destinationAsset offers delivery instead. Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
1656
1664
  },
1657
1665
  {
1658
1666
  id: "delivery",
1659
1667
  mode: "AWAIT",
1660
1668
  endpoint: "GET /fiat/delivery/:deliveryId",
1661
- when: "status is SETTLED and the order is a leg of a delivery with more legs after it: the provider paid a deposit address that converts into the destinationAsset",
1662
- note: "The backend decides; the client never infers that a delivery has more legs. It follows this transition when offered, and otherwise treats SETTLED as done."
1669
+ when: "the request carried a destinationAsset: offered from creation, in every status",
1670
+ note: "The backend decides; the client never infers it. It follows this transition when offered and then polls only GET /fiat/delivery/:deliveryId, which reports both the fiat leg and any conversion after it. Without it the client polls the order and treats SETTLED as done. giveUpAfterMs is the time left in the one delivery polling window, which starts at the order's creation (15 minutes); see DELIVERY:PENDING."
1663
1671
  },
1664
1672
  {
1665
1673
  id: "retry_payment",
@@ -1689,7 +1697,7 @@ var TRANSITION_TABLE = {
1689
1697
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
1690
1698
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
1691
1699
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
1692
- "SETTLED is terminal for the order and ends a direct purchase. When its delivery has more legs, it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/delivery/:deliveryId). The order body itself never describes the conversion.",
1700
+ "SETTLED is terminal for the order. For a request that carried a destinationAsset the purchase is read from DELIVERY (GET /fiat/delivery/:deliveryId) from creation, so the client never polls the order. The order body itself never describes the conversion.",
1693
1701
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
1694
1702
  ]
1695
1703
  },
@@ -1704,13 +1712,14 @@ var TRANSITION_TABLE = {
1704
1712
  id: "poll",
1705
1713
  mode: "AWAIT",
1706
1714
  endpoint: "GET /fiat/delivery/:deliveryId",
1707
- note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
1715
+ note: "Every answer carries giveUpAfterMs: the time left in one polling window that starts at the order's creation (15 minutes), so the window never restarts. When it runs out the client closes the wizard and relies on the notification at the end of the purchase. Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
1708
1716
  }
1709
1717
  ],
1710
1718
  mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
1711
1719
  terminal: false,
1712
1720
  notes: [
1713
- "The fiat leg is SETTLED; a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows a generic processing screen."
1721
+ "Covers both legs: the fiat order is not terminal yet, or it settled and a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows one waiting screen.",
1722
+ "No cancel here. TODO(open-decision): cancel placement (FE doc open questions 1+2)."
1714
1723
  ]
1715
1724
  },
1716
1725
  "DELIVERY:SUCCEEDED": {
@@ -1722,7 +1731,9 @@ var TRANSITION_TABLE = {
1722
1731
  allowedTransitions: [],
1723
1732
  mayReturn: [],
1724
1733
  terminal: true,
1725
- notes: ["The destinationAsset reached the user. txHash is the transaction that paid them."]
1734
+ notes: [
1735
+ "The destinationAsset reached the user. txHash is the transaction that paid them: the fiat order payout on a direct delivery, the conversion payout on a converted one."
1736
+ ]
1726
1737
  },
1727
1738
  "DELIVERY:FAILED": {
1728
1739
  key: "DELIVERY:FAILED",
@@ -1734,7 +1745,8 @@ var TRANSITION_TABLE = {
1734
1745
  mayReturn: [],
1735
1746
  terminal: true,
1736
1747
  notes: [
1737
- "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
1748
+ "FAILED covers both legs: the fiat order failed, was refunded, expired or was cancelled, or the buyer paid and the asset did not arrive. The state carries no reason field.",
1749
+ "FAILED offers no transition: the client shows the failure screen and offers no new payment from it. When the buyer paid, support recovers the funds."
1738
1750
  ]
1739
1751
  }
1740
1752
  };
@@ -1864,7 +1876,7 @@ var FIXTURE_DATA = {
1864
1876
  "intervalMs": 3e3,
1865
1877
  "backoffFactor": 1.5,
1866
1878
  "maxIntervalMs": 1e4,
1867
- "giveUpAfterMs": 3e5
1879
+ "giveUpAfterMs": 18e4
1868
1880
  }
1869
1881
  }
1870
1882
  ]
@@ -2173,6 +2185,41 @@ var FIXTURE_DATA = {
2173
2185
  }
2174
2186
  ]
2175
2187
  },
2188
+ "screen-07b-order-created-delivery": {
2189
+ "state": {
2190
+ "kind": "ORDER",
2191
+ "phase": "CREATED",
2192
+ "order": {
2193
+ "orderId": "o_31c",
2194
+ "fiat": {
2195
+ "currency": "USD",
2196
+ "amount": "50.00"
2197
+ },
2198
+ "crypto": {
2199
+ "currency": "USDC",
2200
+ "network": "base",
2201
+ "amount": "48.73"
2202
+ },
2203
+ "method": "apple_pay",
2204
+ "createdAt": "\u2026"
2205
+ },
2206
+ "status": "PROCESSING"
2207
+ },
2208
+ "provider": "MOONPAY",
2209
+ "transitions": [
2210
+ {
2211
+ "id": "delivery",
2212
+ "mode": "AWAIT",
2213
+ "poll": {
2214
+ "endpoint": "GET /fiat/delivery/dlv_31c",
2215
+ "intervalMs": 3e3,
2216
+ "backoffFactor": 1.5,
2217
+ "maxIntervalMs": 1e4,
2218
+ "giveUpAfterMs": 9e5
2219
+ }
2220
+ }
2221
+ ]
2222
+ },
2176
2223
  "screen-08-kyc-capture": {
2177
2224
  "state": {
2178
2225
  "kind": "KYC",
@@ -2455,7 +2502,7 @@ var FIXTURE_DATA = {
2455
2502
  "intervalMs": 3e3,
2456
2503
  "backoffFactor": 1.5,
2457
2504
  "maxIntervalMs": 1e4,
2458
- "giveUpAfterMs": 3e5
2505
+ "giveUpAfterMs": 6e5
2459
2506
  }
2460
2507
  }
2461
2508
  ]
@@ -2767,15 +2814,26 @@ var FIXTURES = [
2767
2814
  screen: 13,
2768
2815
  stateKey: "ORDER/CREATED"
2769
2816
  },
2817
+ {
2818
+ id: "screen-07b-order-created-delivery",
2819
+ file: "screen-07b-order-created-delivery.json",
2820
+ source: "CONTRACT_DOC",
2821
+ docRef: "Package README \xA7Delivery \xB7 an order whose request carried a destinationAsset",
2822
+ screen: 7,
2823
+ stateKey: "ORDER/CREATED",
2824
+ notes: [
2825
+ "Offered from creation: the request carried a destinationAsset, so the order offers delivery and no poll. The client polls only GET /fiat/delivery/:deliveryId from here, within one 15-minute window from the order's creation (giveUpAfterMs)."
2826
+ ]
2827
+ },
2770
2828
  {
2771
2829
  id: "screen-13b-order-settled-converted",
2772
2830
  file: "screen-13b-order-settled-converted.json",
2773
2831
  source: "CONTRACT_DOC",
2774
- docRef: "Package README \xA7Delivery \xB7 an order at SETTLED whose delivery has more legs",
2832
+ docRef: "Package README \xA7Delivery \xB7 a destinationAsset order at SETTLED",
2775
2833
  screen: 13,
2776
2834
  stateKey: "ORDER/CREATED",
2777
2835
  notes: [
2778
- "The order body is the fiat leg only, as for a direct order. The backend offers the delivery transition because the delivery this order belongs to has a crypto conversion leg after it; the client follows it instead of showing success."
2836
+ "The order body is the fiat leg only. The backend offers the delivery transition because the request carried a destinationAsset (from creation, so also at SETTLED); the client follows it instead of showing success."
2779
2837
  ]
2780
2838
  },
2781
2839
  {
@@ -2833,8 +2891,11 @@ var FIXTURES = [
2833
2891
  id: "delivery-01-pending",
2834
2892
  file: "delivery-01-pending.json",
2835
2893
  source: "CONTRACT_DOC",
2836
- docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2837
- stateKey: "DELIVERY:PENDING"
2894
+ docRef: "Package README \xA7Delivery \xB7 the purchase is running",
2895
+ stateKey: "DELIVERY:PENDING",
2896
+ notes: [
2897
+ "giveUpAfterMs is what is left of the one 15-minute window that started when the order was created (here 12 minutes later), so the window never restarts."
2898
+ ]
2838
2899
  },
2839
2900
  {
2840
2901
  id: "delivery-02-succeeded",
@@ -2847,9 +2908,11 @@ var FIXTURES = [
2847
2908
  id: "delivery-03-failed",
2848
2909
  file: "delivery-03-failed.json",
2849
2910
  source: "CONTRACT_DOC",
2850
- docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2911
+ docRef: "Package README \xA7Delivery \xB7 the purchase failed",
2851
2912
  stateKey: "DELIVERY:FAILED",
2852
- notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2913
+ notes: [
2914
+ "No transition, whichever leg failed: the client offers no new payment from it. When the buyer paid, support recovers the funds."
2915
+ ]
2853
2916
  }
2854
2917
  ];
2855
2918
  var FIXTURE_COVERAGE_GAPS = [
package/dist/index.mjs CHANGED
@@ -12,7 +12,7 @@ import {
12
12
  tableEntry,
13
13
  unofferedEndpoints,
14
14
  unreachableStates
15
- } from "./chunk-PPYEYBTH.mjs";
15
+ } from "./chunk-QVBSAAXU.mjs";
16
16
  import {
17
17
  MOONPAY_ENDPOINTS
18
18
  } from "./chunk-TIEGTTFY.mjs";
@@ -1094,8 +1094,16 @@ var $providerBoundStepResponse = obj({
1094
1094
  expiresAt: z.string()
1095
1095
  }).optional(),
1096
1096
  orderId: z.string().optional(),
1097
- refreshLimits: z.literal(true).optional()
1097
+ refreshLimits: z.literal(true).optional(),
1098
+ feeSubsidy: obj({ estimatedFee: $money.optional() }).optional()
1098
1099
  }).superRefine((response, context) => {
1100
+ if (response.feeSubsidy !== void 0 && "quote" in response.state && response.state.quote?.feeSubsidy !== void 0) {
1101
+ context.addIssue({
1102
+ code: "custom",
1103
+ path: ["feeSubsidy"],
1104
+ message: "a priced quote carries quote.feeSubsidy instead"
1105
+ });
1106
+ }
1099
1107
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1100
1108
  context.addIssue({
1101
1109
  code: "custom",
@@ -1157,7 +1165,7 @@ var FIXTURE_DATA = {
1157
1165
  "intervalMs": 3e3,
1158
1166
  "backoffFactor": 1.5,
1159
1167
  "maxIntervalMs": 1e4,
1160
- "giveUpAfterMs": 3e5
1168
+ "giveUpAfterMs": 18e4
1161
1169
  }
1162
1170
  }
1163
1171
  ]
@@ -1466,6 +1474,41 @@ var FIXTURE_DATA = {
1466
1474
  }
1467
1475
  ]
1468
1476
  },
1477
+ "screen-07b-order-created-delivery": {
1478
+ "state": {
1479
+ "kind": "ORDER",
1480
+ "phase": "CREATED",
1481
+ "order": {
1482
+ "orderId": "o_31c",
1483
+ "fiat": {
1484
+ "currency": "USD",
1485
+ "amount": "50.00"
1486
+ },
1487
+ "crypto": {
1488
+ "currency": "USDC",
1489
+ "network": "base",
1490
+ "amount": "48.73"
1491
+ },
1492
+ "method": "apple_pay",
1493
+ "createdAt": "\u2026"
1494
+ },
1495
+ "status": "PROCESSING"
1496
+ },
1497
+ "provider": "MOONPAY",
1498
+ "transitions": [
1499
+ {
1500
+ "id": "delivery",
1501
+ "mode": "AWAIT",
1502
+ "poll": {
1503
+ "endpoint": "GET /fiat/delivery/dlv_31c",
1504
+ "intervalMs": 3e3,
1505
+ "backoffFactor": 1.5,
1506
+ "maxIntervalMs": 1e4,
1507
+ "giveUpAfterMs": 9e5
1508
+ }
1509
+ }
1510
+ ]
1511
+ },
1469
1512
  "screen-08-kyc-capture": {
1470
1513
  "state": {
1471
1514
  "kind": "KYC",
@@ -1748,7 +1791,7 @@ var FIXTURE_DATA = {
1748
1791
  "intervalMs": 3e3,
1749
1792
  "backoffFactor": 1.5,
1750
1793
  "maxIntervalMs": 1e4,
1751
- "giveUpAfterMs": 3e5
1794
+ "giveUpAfterMs": 6e5
1752
1795
  }
1753
1796
  }
1754
1797
  ]
@@ -2060,15 +2103,26 @@ var FIXTURES = [
2060
2103
  screen: 13,
2061
2104
  stateKey: "ORDER/CREATED"
2062
2105
  },
2106
+ {
2107
+ id: "screen-07b-order-created-delivery",
2108
+ file: "screen-07b-order-created-delivery.json",
2109
+ source: "CONTRACT_DOC",
2110
+ docRef: "Package README \xA7Delivery \xB7 an order whose request carried a destinationAsset",
2111
+ screen: 7,
2112
+ stateKey: "ORDER/CREATED",
2113
+ notes: [
2114
+ "Offered from creation: the request carried a destinationAsset, so the order offers delivery and no poll. The client polls only GET /fiat/delivery/:deliveryId from here, within one 15-minute window from the order's creation (giveUpAfterMs)."
2115
+ ]
2116
+ },
2063
2117
  {
2064
2118
  id: "screen-13b-order-settled-converted",
2065
2119
  file: "screen-13b-order-settled-converted.json",
2066
2120
  source: "CONTRACT_DOC",
2067
- docRef: "Package README \xA7Delivery \xB7 an order at SETTLED whose delivery has more legs",
2121
+ docRef: "Package README \xA7Delivery \xB7 a destinationAsset order at SETTLED",
2068
2122
  screen: 13,
2069
2123
  stateKey: "ORDER/CREATED",
2070
2124
  notes: [
2071
- "The order body is the fiat leg only, as for a direct order. The backend offers the delivery transition because the delivery this order belongs to has a crypto conversion leg after it; the client follows it instead of showing success."
2125
+ "The order body is the fiat leg only. The backend offers the delivery transition because the request carried a destinationAsset (from creation, so also at SETTLED); the client follows it instead of showing success."
2072
2126
  ]
2073
2127
  },
2074
2128
  {
@@ -2126,8 +2180,11 @@ var FIXTURES = [
2126
2180
  id: "delivery-01-pending",
2127
2181
  file: "delivery-01-pending.json",
2128
2182
  source: "CONTRACT_DOC",
2129
- docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2130
- stateKey: "DELIVERY:PENDING"
2183
+ docRef: "Package README \xA7Delivery \xB7 the purchase is running",
2184
+ stateKey: "DELIVERY:PENDING",
2185
+ notes: [
2186
+ "giveUpAfterMs is what is left of the one 15-minute window that started when the order was created (here 12 minutes later), so the window never restarts."
2187
+ ]
2131
2188
  },
2132
2189
  {
2133
2190
  id: "delivery-02-succeeded",
@@ -2140,9 +2197,11 @@ var FIXTURES = [
2140
2197
  id: "delivery-03-failed",
2141
2198
  file: "delivery-03-failed.json",
2142
2199
  source: "CONTRACT_DOC",
2143
- docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2200
+ docRef: "Package README \xA7Delivery \xB7 the purchase failed",
2144
2201
  stateKey: "DELIVERY:FAILED",
2145
- notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2202
+ notes: [
2203
+ "No transition, whichever leg failed: the client offers no new payment from it. When the buyer paid, support recovers the funds."
2204
+ ]
2146
2205
  }
2147
2206
  ];
2148
2207
  var FIXTURE_COVERAGE_GAPS = [
@@ -5,7 +5,8 @@
5
5
  * the client needs to do it. The client's request names it in `action` and carries the result. Every
6
6
  * response is the next action, `done`, or `refused` (`MoonPayResponseFor`). `observe` carries no
7
7
  * result and answers the current next action. `wait` has no request: the client sends `observe` after it.
8
- * `orderPending` answers only `order` and has no request either: the client sends the same `order` after it.
8
+ * `orderPending` answers only `order` and has no request either: the client follows its order body's `delivery`
9
+ * transition when it offers one, and otherwise sends the same `order` after it.
9
10
  *
10
11
  * The body is `MoonPayNextRequest`: `provider`, the shared `geo`, the context (`checkout`, and
11
12
  * `credentials` after `connect`), and the action's result. Identity and the deposit wallet always
@@ -223,8 +224,9 @@ export type MoonPayOrderRequest = {
223
224
  /**
224
225
  * The charge is made or in flight and its order is not terminal yet. `order` is the order's current body
225
226
  * (status, and the settlement transaction once observed) for the client to show, or `null` while MoonPay
226
- * does not list or price the charge and no order exists yet. Do not mount Apple Pay. After `retryAfterMs`,
227
- * send the same `order` request again: each one reads MoonPay and moves the order forward.
227
+ * does not list or price the charge and no order exists yet. Do not mount Apple Pay. When `order` offers the
228
+ * `delivery` transition, follow it to `GET /fiat/delivery/:deliveryId` and stop sending `order`. Otherwise,
229
+ * after `retryAfterMs`, send the same `order` request again: each one reads MoonPay and moves the order forward.
228
230
  */
229
231
  export type MoonPayOrderPendingNextAction = {
230
232
  next: 'orderPending';
@@ -270,9 +272,11 @@ export type MoonPayStepResponse = MoonPayNextAction | MoonPayRefused<MoonPayStep
270
272
  /**
271
273
  * The answer to `order`. `done` once the order is terminal. A failed charge is recorded too: `done` with
272
274
  * the order in `FAILED`, and the client requotes for a new `orderId`. `orderPending` while the order is
273
- * not terminal, or MoonPay does not list or price the transaction yet: the client polls by sending the
274
- * same `order` request, never `GET /fiat/orders/:orderId`. A refusal after a charge never requotes:
275
- * that would start a second payment.
275
+ * not terminal, or MoonPay does not list or price the transaction yet. When its `order` body offers the
276
+ * `delivery` transition (the request carried a `destinationAsset`), the client follows it to
277
+ * `GET /fiat/delivery/:deliveryId` and stops sending `order`; otherwise it polls by sending the same
278
+ * `order` request, never `GET /fiat/orders/:orderId`. A refusal after a charge never requotes: that would
279
+ * start a second payment.
276
280
  */
277
281
  export type MoonPayOrderResponse = MoonPayDone | MoonPayOrderNextAction | MoonPayOrderPendingNextAction | MoonPayRefused<MoonPayOrderRefusal, 'NONE'>;
278
282
  export type MoonPayResponseFor = {
package/dist/table.js CHANGED
@@ -36,7 +36,7 @@ __export(table_exports, {
36
36
  module.exports = __toCommonJS(table_exports);
37
37
 
38
38
  // package.json
39
- var version = "0.37.0";
39
+ var version = "0.38.0";
40
40
 
41
41
  // src/table.ts
42
42
  var TABLE_VERSION = version;
@@ -396,15 +396,15 @@ var TRANSITION_TABLE = {
396
396
  id: "poll",
397
397
  mode: "AWAIT",
398
398
  endpoint: "GET /fiat/orders/:id",
399
- when: "status is non-terminal",
400
- note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
399
+ when: "status is non-terminal and the request carried no destinationAsset",
400
+ note: "For older clients only: an order whose request carried a destinationAsset offers delivery instead. Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
401
401
  },
402
402
  {
403
403
  id: "delivery",
404
404
  mode: "AWAIT",
405
405
  endpoint: "GET /fiat/delivery/:deliveryId",
406
- when: "status is SETTLED and the order is a leg of a delivery with more legs after it: the provider paid a deposit address that converts into the destinationAsset",
407
- note: "The backend decides; the client never infers that a delivery has more legs. It follows this transition when offered, and otherwise treats SETTLED as done."
406
+ when: "the request carried a destinationAsset: offered from creation, in every status",
407
+ note: "The backend decides; the client never infers it. It follows this transition when offered and then polls only GET /fiat/delivery/:deliveryId, which reports both the fiat leg and any conversion after it. Without it the client polls the order and treats SETTLED as done. giveUpAfterMs is the time left in the one delivery polling window, which starts at the order's creation (15 minutes); see DELIVERY:PENDING."
408
408
  },
409
409
  {
410
410
  id: "retry_payment",
@@ -434,7 +434,7 @@ var TRANSITION_TABLE = {
434
434
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
435
435
  "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
436
436
  "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
437
- "SETTLED is terminal for the order and ends a direct purchase. When its delivery has more legs, it carries the delivery transition, and the purchase continues in DELIVERY (GET /fiat/delivery/:deliveryId). The order body itself never describes the conversion.",
437
+ "SETTLED is terminal for the order. For a request that carried a destinationAsset the purchase is read from DELIVERY (GET /fiat/delivery/:deliveryId) from creation, so the client never polls the order. The order body itself never describes the conversion.",
438
438
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
439
439
  ]
440
440
  },
@@ -449,13 +449,14 @@ var TRANSITION_TABLE = {
449
449
  id: "poll",
450
450
  mode: "AWAIT",
451
451
  endpoint: "GET /fiat/delivery/:deliveryId",
452
- note: "Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
452
+ note: "Every answer carries giveUpAfterMs: the time left in one polling window that starts at the order's creation (15 minutes), so the window never restarts. When it runs out the client closes the wizard and relies on the notification at the end of the purchase. Giving up the poll does not fail the purchase: the backend still finishes the delivery or raises it to support."
453
453
  }
454
454
  ],
455
455
  mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
456
456
  terminal: false,
457
457
  notes: [
458
- "The fiat leg is SETTLED; a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows a generic processing screen."
458
+ "Covers both legs: the fiat order is not terminal yet, or it settled and a crypto asset provider is converting it into the destinationAsset and paying the user. The client shows one waiting screen.",
459
+ "No cancel here. TODO(open-decision): cancel placement (FE doc open questions 1+2)."
459
460
  ]
460
461
  },
461
462
  "DELIVERY:SUCCEEDED": {
@@ -467,7 +468,9 @@ var TRANSITION_TABLE = {
467
468
  allowedTransitions: [],
468
469
  mayReturn: [],
469
470
  terminal: true,
470
- notes: ["The destinationAsset reached the user. txHash is the transaction that paid them."]
471
+ notes: [
472
+ "The destinationAsset reached the user. txHash is the transaction that paid them: the fiat order payout on a direct delivery, the conversion payout on a converted one."
473
+ ]
471
474
  },
472
475
  "DELIVERY:FAILED": {
473
476
  key: "DELIVERY:FAILED",
@@ -479,7 +482,8 @@ var TRANSITION_TABLE = {
479
482
  mayReturn: [],
480
483
  terminal: true,
481
484
  notes: [
482
- "The buyer has paid and the asset did not arrive. Support recovers the funds, so the client shows a dedicated failure screen that offers no new payment."
485
+ "FAILED covers both legs: the fiat order failed, was refunded, expired or was cancelled, or the buyer paid and the asset did not arrive. The state carries no reason field.",
486
+ "FAILED offers no transition: the client shows the failure screen and offers no new payment from it. When the buyer paid, support recovers the funds."
483
487
  ]
484
488
  }
485
489
  };
package/dist/table.mjs CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  tableEntry,
12
12
  unofferedEndpoints,
13
13
  unreachableStates
14
- } from "./chunk-PPYEYBTH.mjs";
14
+ } from "./chunk-QVBSAAXU.mjs";
15
15
  export {
16
16
  DOCUMENTED_ENDPOINTS,
17
17
  STATE_KEYS,
package/dist/types.d.ts CHANGED
@@ -162,6 +162,17 @@ export interface Quote {
162
162
  */
163
163
  feeSubsidy?: FiatAmount;
164
164
  }
165
+ /**
166
+ * The fee is predicted to be reimbursed after settlement: render it as FREE. Settlement decides again.
167
+ * Carried before any provider price exists; a priced `Quote` carries `Quote.feeSubsidy` instead.
168
+ */
169
+ export interface FeeSubsidy {
170
+ /**
171
+ * The fee being waived, estimated from the provider's published schedule. Absent when the provider
172
+ * or the delivered target has no reliable estimate: show FREE without a number, never a guess.
173
+ */
174
+ estimatedFee?: FiatAmount;
175
+ }
165
176
  /** One inclusive amount interval the current routing set can actually serve. */
166
177
  export interface QuoteLimitRange {
167
178
  min: string;
@@ -684,12 +695,13 @@ export type FlowState =
684
695
  error?: FailureReason;
685
696
  }
686
697
  /**
687
- * A delivery: the purchase as a whole, of which the order is the fiat provider's leg. Read from
688
- * `GET /fiat/delivery/:deliveryId`, which an `ORDER{CREATED, SETTLED}` offers through its `delivery`
689
- * transition only when the delivery has legs after the order.
690
- * `PENDING` polls itself. `SUCCEEDED` carries the transaction that paid the user. `FAILED` means the
691
- * buyer has paid and the asset did not arrive: support recovers the funds, so the client never offers
692
- * another payment from it.
698
+ * The whole purchase after the order is created, from `GET /fiat/delivery/:deliveryId`: the fiat
699
+ * provider's leg and, on a converted order, the conversion after it. A request that carried a
700
+ * `destinationAsset` gets the `delivery` transition from `ORDER{CREATED}` at creation and polls only
701
+ * here. `PENDING` polls itself; each answer's `giveUpAfterMs` is the time left in one window that
702
+ * starts at the order's creation. `SUCCEEDED` carries the transaction that paid the user. `FAILED`
703
+ * offers no transition: the client offers no new payment from it, and when the buyer paid, support
704
+ * recovers the funds.
693
705
  */
694
706
  | {
695
707
  kind: 'DELIVERY';
@@ -758,6 +770,12 @@ export type FiatStepResponse = (FiatStepResponseBase & {
758
770
  kind: 'BLOCKED';
759
771
  }>;
760
772
  provider: FiatProvider;
773
+ /**
774
+ * Sent only on the response that answers a quote request, before a price: never beside a
775
+ * `Quote.feeSubsidy`. Keep it by the `quoteRef` this response's transitions carry; later steps of
776
+ * that ref omit it, and a ref with no prediction is not subsidized.
777
+ */
778
+ feeSubsidy?: FeeSubsidy;
761
779
  /** Optional future payment artifact; never one of this response's currently active transitions. */
762
780
  preparedPayment?: PreparedPayment;
763
781
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fun-xyz/fiat-contract",
3
- "version": "0.37.0",
3
+ "version": "0.38.0",
4
4
  "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
5
5
  "license": "MIT",
6
6
  "repository": {