@fun-xyz/fiat-contract 0.37.0 → 0.39.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.39.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
@@ -1159,7 +1159,8 @@ var $routingTableMethod = obj({
1159
1159
  });
1160
1160
  var $routingTableResponse = obj({
1161
1161
  expiresAt: $isoInstant,
1162
- methods: import_zod.z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
1162
+ methods: import_zod.z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once"),
1163
+ feeSubsidy: obj({ subsidized: import_zod.z.boolean() }).optional()
1163
1164
  });
1164
1165
  var FiatRoutingTableResponseSchema = $routingTableResponse;
1165
1166
  var $routingQuoteTermsShape = {
@@ -1291,7 +1292,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
1291
1292
  var FiatStepResponseSchema = $stepResponse;
1292
1293
 
1293
1294
  // package.json
1294
- var version = "0.37.0";
1295
+ var version = "0.39.0";
1295
1296
 
1296
1297
  // src/table.ts
1297
1298
  var TABLE_VERSION = version;
@@ -1651,15 +1652,15 @@ var TRANSITION_TABLE = {
1651
1652
  id: "poll",
1652
1653
  mode: "AWAIT",
1653
1654
  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."
1655
+ when: "status is non-terminal and the request carried no destinationAsset",
1656
+ 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
1657
  },
1657
1658
  {
1658
1659
  id: "delivery",
1659
1660
  mode: "AWAIT",
1660
1661
  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."
1662
+ when: "the request carried a destinationAsset: offered from creation, in every status",
1663
+ 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
1664
  },
1664
1665
  {
1665
1666
  id: "retry_payment",
@@ -1689,7 +1690,7 @@ var TRANSITION_TABLE = {
1689
1690
  "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
1690
1691
  "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
1692
  "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.",
1693
+ "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
1694
  "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
1694
1695
  ]
1695
1696
  },
@@ -1704,13 +1705,14 @@ var TRANSITION_TABLE = {
1704
1705
  id: "poll",
1705
1706
  mode: "AWAIT",
1706
1707
  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."
1708
+ 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
1709
  }
1709
1710
  ],
1710
1711
  mayReturn: ["DELIVERY:PENDING", "DELIVERY:SUCCEEDED", "DELIVERY:FAILED"],
1711
1712
  terminal: false,
1712
1713
  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."
1714
+ "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.",
1715
+ "No cancel here. TODO(open-decision): cancel placement (FE doc open questions 1+2)."
1714
1716
  ]
1715
1717
  },
1716
1718
  "DELIVERY:SUCCEEDED": {
@@ -1722,7 +1724,9 @@ var TRANSITION_TABLE = {
1722
1724
  allowedTransitions: [],
1723
1725
  mayReturn: [],
1724
1726
  terminal: true,
1725
- notes: ["The destinationAsset reached the user. txHash is the transaction that paid them."]
1727
+ notes: [
1728
+ "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."
1729
+ ]
1726
1730
  },
1727
1731
  "DELIVERY:FAILED": {
1728
1732
  key: "DELIVERY:FAILED",
@@ -1734,7 +1738,8 @@ var TRANSITION_TABLE = {
1734
1738
  mayReturn: [],
1735
1739
  terminal: true,
1736
1740
  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."
1741
+ "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.",
1742
+ "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
1743
  ]
1739
1744
  }
1740
1745
  };
@@ -1864,7 +1869,7 @@ var FIXTURE_DATA = {
1864
1869
  "intervalMs": 3e3,
1865
1870
  "backoffFactor": 1.5,
1866
1871
  "maxIntervalMs": 1e4,
1867
- "giveUpAfterMs": 3e5
1872
+ "giveUpAfterMs": 18e4
1868
1873
  }
1869
1874
  }
1870
1875
  ]
@@ -2173,6 +2178,41 @@ var FIXTURE_DATA = {
2173
2178
  }
2174
2179
  ]
2175
2180
  },
2181
+ "screen-07b-order-created-delivery": {
2182
+ "state": {
2183
+ "kind": "ORDER",
2184
+ "phase": "CREATED",
2185
+ "order": {
2186
+ "orderId": "o_31c",
2187
+ "fiat": {
2188
+ "currency": "USD",
2189
+ "amount": "50.00"
2190
+ },
2191
+ "crypto": {
2192
+ "currency": "USDC",
2193
+ "network": "base",
2194
+ "amount": "48.73"
2195
+ },
2196
+ "method": "apple_pay",
2197
+ "createdAt": "\u2026"
2198
+ },
2199
+ "status": "PROCESSING"
2200
+ },
2201
+ "provider": "MOONPAY",
2202
+ "transitions": [
2203
+ {
2204
+ "id": "delivery",
2205
+ "mode": "AWAIT",
2206
+ "poll": {
2207
+ "endpoint": "GET /fiat/delivery/dlv_31c",
2208
+ "intervalMs": 3e3,
2209
+ "backoffFactor": 1.5,
2210
+ "maxIntervalMs": 1e4,
2211
+ "giveUpAfterMs": 9e5
2212
+ }
2213
+ }
2214
+ ]
2215
+ },
2176
2216
  "screen-08-kyc-capture": {
2177
2217
  "state": {
2178
2218
  "kind": "KYC",
@@ -2455,7 +2495,7 @@ var FIXTURE_DATA = {
2455
2495
  "intervalMs": 3e3,
2456
2496
  "backoffFactor": 1.5,
2457
2497
  "maxIntervalMs": 1e4,
2458
- "giveUpAfterMs": 3e5
2498
+ "giveUpAfterMs": 6e5
2459
2499
  }
2460
2500
  }
2461
2501
  ]
@@ -2767,15 +2807,26 @@ var FIXTURES = [
2767
2807
  screen: 13,
2768
2808
  stateKey: "ORDER/CREATED"
2769
2809
  },
2810
+ {
2811
+ id: "screen-07b-order-created-delivery",
2812
+ file: "screen-07b-order-created-delivery.json",
2813
+ source: "CONTRACT_DOC",
2814
+ docRef: "Package README \xA7Delivery \xB7 an order whose request carried a destinationAsset",
2815
+ screen: 7,
2816
+ stateKey: "ORDER/CREATED",
2817
+ notes: [
2818
+ "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)."
2819
+ ]
2820
+ },
2770
2821
  {
2771
2822
  id: "screen-13b-order-settled-converted",
2772
2823
  file: "screen-13b-order-settled-converted.json",
2773
2824
  source: "CONTRACT_DOC",
2774
- docRef: "Package README \xA7Delivery \xB7 an order at SETTLED whose delivery has more legs",
2825
+ docRef: "Package README \xA7Delivery \xB7 a destinationAsset order at SETTLED",
2775
2826
  screen: 13,
2776
2827
  stateKey: "ORDER/CREATED",
2777
2828
  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."
2829
+ "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
2830
  ]
2780
2831
  },
2781
2832
  {
@@ -2833,8 +2884,11 @@ var FIXTURES = [
2833
2884
  id: "delivery-01-pending",
2834
2885
  file: "delivery-01-pending.json",
2835
2886
  source: "CONTRACT_DOC",
2836
- docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2837
- stateKey: "DELIVERY:PENDING"
2887
+ docRef: "Package README \xA7Delivery \xB7 the purchase is running",
2888
+ stateKey: "DELIVERY:PENDING",
2889
+ notes: [
2890
+ "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."
2891
+ ]
2838
2892
  },
2839
2893
  {
2840
2894
  id: "delivery-02-succeeded",
@@ -2847,9 +2901,11 @@ var FIXTURES = [
2847
2901
  id: "delivery-03-failed",
2848
2902
  file: "delivery-03-failed.json",
2849
2903
  source: "CONTRACT_DOC",
2850
- docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2904
+ docRef: "Package README \xA7Delivery \xB7 the purchase failed",
2851
2905
  stateKey: "DELIVERY:FAILED",
2852
- notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2906
+ notes: [
2907
+ "No transition, whichever leg failed: the client offers no new payment from it. When the buyer paid, support recovers the funds."
2908
+ ]
2853
2909
  }
2854
2910
  ];
2855
2911
  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-LMF4OMUW.mjs";
16
16
  import {
17
17
  MOONPAY_ENDPOINTS
18
18
  } from "./chunk-TIEGTTFY.mjs";
@@ -1009,7 +1009,8 @@ var $routingTableMethod = obj({
1009
1009
  });
1010
1010
  var $routingTableResponse = obj({
1011
1011
  expiresAt: $isoInstant,
1012
- methods: z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
1012
+ methods: z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once"),
1013
+ feeSubsidy: obj({ subsidized: z.boolean() }).optional()
1013
1014
  });
1014
1015
  var FiatRoutingTableResponseSchema = $routingTableResponse;
1015
1016
  var $routingQuoteTermsShape = {
@@ -1157,7 +1158,7 @@ var FIXTURE_DATA = {
1157
1158
  "intervalMs": 3e3,
1158
1159
  "backoffFactor": 1.5,
1159
1160
  "maxIntervalMs": 1e4,
1160
- "giveUpAfterMs": 3e5
1161
+ "giveUpAfterMs": 18e4
1161
1162
  }
1162
1163
  }
1163
1164
  ]
@@ -1466,6 +1467,41 @@ var FIXTURE_DATA = {
1466
1467
  }
1467
1468
  ]
1468
1469
  },
1470
+ "screen-07b-order-created-delivery": {
1471
+ "state": {
1472
+ "kind": "ORDER",
1473
+ "phase": "CREATED",
1474
+ "order": {
1475
+ "orderId": "o_31c",
1476
+ "fiat": {
1477
+ "currency": "USD",
1478
+ "amount": "50.00"
1479
+ },
1480
+ "crypto": {
1481
+ "currency": "USDC",
1482
+ "network": "base",
1483
+ "amount": "48.73"
1484
+ },
1485
+ "method": "apple_pay",
1486
+ "createdAt": "\u2026"
1487
+ },
1488
+ "status": "PROCESSING"
1489
+ },
1490
+ "provider": "MOONPAY",
1491
+ "transitions": [
1492
+ {
1493
+ "id": "delivery",
1494
+ "mode": "AWAIT",
1495
+ "poll": {
1496
+ "endpoint": "GET /fiat/delivery/dlv_31c",
1497
+ "intervalMs": 3e3,
1498
+ "backoffFactor": 1.5,
1499
+ "maxIntervalMs": 1e4,
1500
+ "giveUpAfterMs": 9e5
1501
+ }
1502
+ }
1503
+ ]
1504
+ },
1469
1505
  "screen-08-kyc-capture": {
1470
1506
  "state": {
1471
1507
  "kind": "KYC",
@@ -1748,7 +1784,7 @@ var FIXTURE_DATA = {
1748
1784
  "intervalMs": 3e3,
1749
1785
  "backoffFactor": 1.5,
1750
1786
  "maxIntervalMs": 1e4,
1751
- "giveUpAfterMs": 3e5
1787
+ "giveUpAfterMs": 6e5
1752
1788
  }
1753
1789
  }
1754
1790
  ]
@@ -2060,15 +2096,26 @@ var FIXTURES = [
2060
2096
  screen: 13,
2061
2097
  stateKey: "ORDER/CREATED"
2062
2098
  },
2099
+ {
2100
+ id: "screen-07b-order-created-delivery",
2101
+ file: "screen-07b-order-created-delivery.json",
2102
+ source: "CONTRACT_DOC",
2103
+ docRef: "Package README \xA7Delivery \xB7 an order whose request carried a destinationAsset",
2104
+ screen: 7,
2105
+ stateKey: "ORDER/CREATED",
2106
+ notes: [
2107
+ "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)."
2108
+ ]
2109
+ },
2063
2110
  {
2064
2111
  id: "screen-13b-order-settled-converted",
2065
2112
  file: "screen-13b-order-settled-converted.json",
2066
2113
  source: "CONTRACT_DOC",
2067
- docRef: "Package README \xA7Delivery \xB7 an order at SETTLED whose delivery has more legs",
2114
+ docRef: "Package README \xA7Delivery \xB7 a destinationAsset order at SETTLED",
2068
2115
  screen: 13,
2069
2116
  stateKey: "ORDER/CREATED",
2070
2117
  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."
2118
+ "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
2119
  ]
2073
2120
  },
2074
2121
  {
@@ -2126,8 +2173,11 @@ var FIXTURES = [
2126
2173
  id: "delivery-01-pending",
2127
2174
  file: "delivery-01-pending.json",
2128
2175
  source: "CONTRACT_DOC",
2129
- docRef: "Package README \xA7Delivery \xB7 the conversion is running",
2130
- stateKey: "DELIVERY:PENDING"
2176
+ docRef: "Package README \xA7Delivery \xB7 the purchase is running",
2177
+ stateKey: "DELIVERY:PENDING",
2178
+ notes: [
2179
+ "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."
2180
+ ]
2131
2181
  },
2132
2182
  {
2133
2183
  id: "delivery-02-succeeded",
@@ -2140,9 +2190,11 @@ var FIXTURES = [
2140
2190
  id: "delivery-03-failed",
2141
2191
  file: "delivery-03-failed.json",
2142
2192
  source: "CONTRACT_DOC",
2143
- docRef: "Package README \xA7Delivery \xB7 the conversion failed after payment",
2193
+ docRef: "Package README \xA7Delivery \xB7 the purchase failed",
2144
2194
  stateKey: "DELIVERY:FAILED",
2145
- notes: ["No transition: the buyer has paid, so the client offers no new payment. Support recovers the funds."]
2195
+ notes: [
2196
+ "No transition, whichever leg failed: the client offers no new payment from it. When the buyer paid, support recovers the funds."
2197
+ ]
2146
2198
  }
2147
2199
  ];
2148
2200
  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/routing.d.ts CHANGED
@@ -108,6 +108,15 @@ export interface FiatRoutingTableResponse {
108
108
  expiresAt: string;
109
109
  /** In request order, duplicates removed. */
110
110
  methods: RoutingTableMethod[];
111
+ /**
112
+ * Whether this buyer's next order in the table's corridor has its fee reimbursed: show the fee as FREE
113
+ * when `subsidized`, before and after an amount is entered. A priced `Quote.feeSubsidy` is the exact
114
+ * amount and wins. Absent when the backend could not decide: treat it as not subsidized. A prediction:
115
+ * settlement decides again.
116
+ */
117
+ feeSubsidy?: {
118
+ subsidized: boolean;
119
+ };
111
120
  }
112
121
  /** The purchase terms and optional host restriction, independent of the current ordered candidates. */
113
122
  export interface FiatRoutingQuoteTerms {
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.39.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-LMF4OMUW.mjs";
15
15
  export {
16
16
  DOCUMENTED_ENDPOINTS,
17
17
  STATE_KEYS,
package/dist/types.d.ts CHANGED
@@ -684,12 +684,13 @@ export type FlowState =
684
684
  error?: FailureReason;
685
685
  }
686
686
  /**
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.
687
+ * The whole purchase after the order is created, from `GET /fiat/delivery/:deliveryId`: the fiat
688
+ * provider's leg and, on a converted order, the conversion after it. A request that carried a
689
+ * `destinationAsset` gets the `delivery` transition from `ORDER{CREATED}` at creation and polls only
690
+ * here. `PENDING` polls itself; each answer's `giveUpAfterMs` is the time left in one window that
691
+ * starts at the order's creation. `SUCCEEDED` carries the transaction that paid the user. `FAILED`
692
+ * offers no transition: the client offers no new payment from it, and when the buyer paid, support
693
+ * recovers the funds.
693
694
  */
694
695
  | {
695
696
  kind: 'DELIVERY';
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.39.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": {