@marcohefti/request-network-api-contracts 0.7.0 → 0.7.1

package/README.md

@@ -49,6 +49,11 @@ npm run verify
 `sync:openapi` fetches and normalizes the production Request and Auth APIs, applies only documented compatibility patches,
 and records raw/normalized hashes. Client code generation remains the responsibility of each client repository.
 
+Webhook fee items preserve their required `type`, `amount`, and `currency` fields while accepting additional
+provider-supplied fields. This follows an authenticated `payment.confirmed` payload that included an unmodeled fee
+extension. A nullable fee `amount` is a compatibility inference from the related Request API fee schema, not a field
+independently confirmed by that webhook payload.
+
 ### Local schema drift patching
 
 See `docs/OPENAPI-0.31.0-AUDIT.md` for the operation inventory and the evidence behind nullable-union, fee-drift,

package/docs/UPDATES.md

@@ -12,6 +12,16 @@ change so SDK maintainers know when to regenerate code.
 -	**Notes:** Regeneration impact, required SDK updates, new fixtures
 
 ## History
+- **Date:** 2026-09-08
+- **Spec Version:** contracts 0.7.1
+- **Change Summary:** Opened `WebhookFeeItem` to provider-supplied extensions and made its string `amount` nullable;
+  the required `type`, `amount`, and `currency` fields remain unchanged. Added a synthetic null-amount/extension
+  regression fixture and guards that preserve the behavior through webhook regeneration.
+- **Source:** Authenticated `payment.confirmed` delivery (fee extension) and related Request API fee schema
+  (nullable amount).
+- **Notes:** The extra fee field is confirmed by the webhook delivery. Nullable webhook `amount` is an API-schema
+  compatibility inference, not an independently observed webhook field. Regenerate TS/PHP clients against 0.7.1.
+
 - **Date:** 2026-09-03
 - **Spec Version:** Request API 0.31.0; Auth API 0.14.0; contracts 0.7.0
 - **Change Summary:** Added the separate Auth contract, synchronized all 82 Request operations, removed two obsolete

package/fixtures/webhooks/payment-confirmed-fee-extension.json

@@ -0,0 +1,15 @@
+{
+  "event": "payment.confirmed",
+  "requestId": "synthetic-payment-confirmed-fee-extension",
+  "timestamp": "2026-09-08T00:00:00Z",
+  "fees": [
+    {
+      "type": "network",
+      "amount": null,
+      "currency": "ETH",
+      "syntheticExtension": {
+        "fixture": "contract-regression"
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcohefti/request-network-api-contracts",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "description": "Shared contracts for Request Network API clients (OpenAPI spec, webhook fixtures).",
   "license": "MIT",

package/scripts/sync-openapi.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const openApiDirectory = resolve(root, "specs/openapi");
-const contractVersion = "0.7.0";
+const contractVersion = "0.7.1";
 
 const sources = [
   {

package/scripts/sync-webhooks.mjs

@@ -64,6 +64,16 @@ async function main() {
     payerEoaAddress: { type: "string", nullable: true, description: "Connected payer EOA when available." },
   });
 
+  const webhookFeeItem = schema.components.schemas.WebhookFeeItem;
+  webhookFeeItem.additionalProperties = true;
+  webhookFeeItem.properties.amount = {
+    ...webhookFeeItem.properties.amount,
+    type: "string",
+    nullable: true,
+    description: "Human-readable amount as a string when supplied; nullable for fee records without a settled amount.",
+  };
+  webhookFeeItem.required = ["type", "amount", "currency"];
+
   Object.assign(schema.components.schemas, {
     ClientIdLinkedEvent: eventSchema("client_id.linked", {
       clientId: { type: "string" },
@@ -111,6 +121,7 @@ async function main() {
 
   Object.assign(schema.components.examples, {
     payment_confirmed: { summary: "Official current settlement example", value: JSON.parse(await readFile(resolve(root, "fixtures/webhooks/payment-confirmed.json"), "utf8")) },
+    payment_confirmed_fee_extension: { summary: "Synthetic fee-extension compatibility regression", value: JSON.parse(await readFile(resolve(root, "fixtures/webhooks/payment-confirmed-fee-extension.json"), "utf8")) },
     payment_failed: { summary: "Official current failure example", value: JSON.parse(await readFile(resolve(root, "fixtures/webhooks/payment-failed.json"), "utf8")) },
     client_id_linked: { summary: "Official hosted onboarding example", value: JSON.parse(await readFile(resolve(root, "fixtures/webhooks/client-id-linked.json"), "utf8")) },
     kyt_screening_completed: { summary: "Official definitive KYT example", value: JSON.parse(await readFile(resolve(root, "fixtures/webhooks/kyt-screening-completed.json"), "utf8")) },

package/scripts/verify.js

@@ -13,6 +13,7 @@ const files = [
   path.join(root, 'specs', 'openapi', 'manifest.json'),
   path.join(root, 'specs', 'webhooks', 'request-network-webhooks.json'),
   path.join(root, 'specs', 'webhooks', 'manifest.json'),
+  path.join(root, 'fixtures', 'webhooks', 'payment-confirmed-fee-extension.json'),
 ];
 
 for (const file of files) {
@@ -75,6 +76,20 @@ try {
   assert(requestSpec['x-contract-patches'].includes('secure-payment-response-shapes'), 'secure-payment response patch is not declared');
   assert(authSpec['x-contract-patches'].includes('platform-webhook-client-id-auth'), 'Auth webhook security patch is not declared');
 
+  const webhookFeeItem = webhookSpec.components.schemas.WebhookFeeItem;
+  assert(webhookSpec.components.schemas.WebhookBase.additionalProperties === true, 'WebhookBase must remain open for event-level extensions');
+  assert(webhookFeeItem.additionalProperties === true, 'WebhookFeeItem must allow fee-provider extensions');
+  assert(JSON.stringify(webhookFeeItem.required) === JSON.stringify(['type', 'amount', 'currency']), 'WebhookFeeItem must require type, amount, and currency');
+  assert(webhookFeeItem.properties.type.type === 'string', 'WebhookFeeItem.type must remain a string');
+  assert(webhookFeeItem.properties.amount.type === 'string' && webhookFeeItem.properties.amount.nullable === true, 'WebhookFeeItem.amount must be a nullable string');
+  assert(webhookFeeItem.properties.currency.type === 'string', 'WebhookFeeItem.currency must remain a string');
+
+  const feeExtensionFixture = readJson('fixtures/webhooks/payment-confirmed-fee-extension.json');
+  const syntheticFee = feeExtensionFixture.fees?.[0];
+  assert(feeExtensionFixture.event === 'payment.confirmed', 'fee-extension fixture must be a payment.confirmed event');
+  assert(syntheticFee?.amount === null, 'fee-extension fixture must cover a null fee amount');
+  assert(Object.hasOwn(syntheticFee ?? {}, 'syntheticExtension'), 'fee-extension fixture must cover an unknown fee extension');
+
   const createResponse = requestSpec.paths['/v2/secure-payments'].post.responses['201'].content['application/json'].schema;
   for (const key of ['requestIds', 'securePaymentUrl', 'token']) {
     assert(createResponse.required.includes(key), `secure-payment response does not require ${key}`);

package/specs/openapi/manifest.json

@@ -1,5 +1,5 @@
 {
-  "contractsVersion": "0.7.0",
+  "contractsVersion": "0.7.1",
   "fetchedAt": "2026-09-03T09:13:49.531Z",
   "defaultEnvironment": "production",
   "supportedRuntimeHosts": [

package/specs/webhooks/request-network-webhooks.json

@@ -494,7 +494,7 @@
     "schemas": {
       "WebhookFeeItem": {
         "type": "object",
-        "additionalProperties": false,
+        "additionalProperties": true,
         "properties": {
           "type": {
             "type": "string",
@@ -502,7 +502,8 @@
           },
           "amount": {
             "type": "string",
-            "description": "Human-readable amount as a string."
+            "description": "Human-readable amount as a string when supplied; nullable for fee records without a settled amount.",
+            "nullable": true
           },
           "currency": {
             "type": "string",
@@ -1318,6 +1319,24 @@
           "attemptedPayerWalletAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
           "timestamp": "2026-08-10T10:05:00.000Z"
         }
+      },
+      "payment_confirmed_fee_extension": {
+        "summary": "Synthetic fee-extension compatibility regression",
+        "value": {
+          "event": "payment.confirmed",
+          "requestId": "synthetic-payment-confirmed-fee-extension",
+          "timestamp": "2026-09-08T00:00:00Z",
+          "fees": [
+            {
+              "type": "network",
+              "amount": null,
+              "currency": "ETH",
+              "syntheticExtension": {
+                "fixture": "contract-regression"
+              }
+            }
+          ]
+        }
       }
     }
   }