@marcohefti/request-network-api-contracts 0.5.0

package/README.md

@@ -0,0 +1,56 @@
+# Request Network API Contracts
+
+Canonical contracts shared by the Request Network API clients. The package
+houses the OpenAPI specification, metadata, and webhook fixtures that both the
+TypeScript and PHP SDKs consume.
+
+This repository keeps the assets versioned in one place so language SDKs can
+reuse them without duplicating specs or fixtures. Clients consume it either
+via an npm dependency or as a Git submodule.
+
+## Installation
+
+Install via npm or pnpm:
+
+```bash
+# npm
+npm install --save-dev @marcohefti/request-network-api-contracts
+
+# pnpm
+pnpm add -D @marcohefti/request-network-api-contracts
+```
+
+## Contents
+
+- `specs/openapi/` – auto-generated REST contract and metadata (fetched from the Request API).
+- `specs/webhooks/` – manually curated webhook schema reference.
+- `fixtures/webhooks/*.json` – canonical webhook payloads used across SDK test suites.
+- `docs/` – release log, update instructions, and parity notes.
+
+## Consumption
+
+- SDK packages import assets via `@marcohefti/request-network-api-contracts/<path>` (e.g., `@marcohefti/request-network-api-contracts/specs/openapi/request-network-openapi.json`).
+
+## Status
+
+- **Phase:** authoritative. SDKs read specs/fixtures directly from this package during build and test phases.
+- **Publishing:** intended primarily as a Git/npm dependency for tooling and tests rather than an end‑user package.
+
+## Updating the spec
+
+Use the TypeScript client's tooling to refresh the contracts in-place:
+
+```bash
+pnpm --filter "./packages/request-api-client" prepare:spec
+pnpm --filter "./packages/request-client-contracts" verify
+```
+
+`prepare:spec` downloads the latest OpenAPI document into `specs/openapi/`, refreshes metadata, and regenerates the TypeScript/Zod outputs in the client package. Follow with `verify` to sanity-check file sizes and presence before committing updates across both packages.
+
+## Future work
+
+- [ ] Publish webhook fixture guidelines and add validation to ensure both SDKs reference the same payload set.
+- [ ] Provide a version manifest so SDKs can pin contract revisions.
+- [ ] Document Git submodule workflow for post-split repositories.
+
+See `docs/OVERVIEW.md` for deeper architectural context.

package/docs/OVERVIEW.md

@@ -0,0 +1,63 @@
+# Request Client Contracts Overview
+
+## Purpose
+
+Centralise the Request Network REST contracts and test fixtures in one place so
+all language clients stay in sync:
+
+- **OpenAPI spec** - canonical JSON used to generate DTOs, schema validators,
+  and parity tests.
+- **OpenAPI metadata** - etag/fetched-at/source info to track when the spec
+  last changed.
+- **Webhook fixtures** - shared payloads for signature verification and event
+  parsing tests across SDKs.
+
+Keeping these assets together avoids duplication today and ensures future
+standalone repositories (TypeScript, PHP, others) can include the contracts as a
+Git dependency.
+
+## Directory Structure
+
+```
+packages/request-client-contracts/
+├── README.md
+├── package.json              # workspace metadata (private)
+├── specs/
+│   ├── README.md                     # explains generated vs manual assets
+│   ├── openapi/
+│   │   ├── request-network-openapi.json
+│   │   └── request-network-openapi.meta.json
+│   └── webhooks/
+│       └── request-network-webhooks.json
+├── fixtures/
+│   └── webhooks/
+│       ├── payment-confirmed.json
+│       ├── payment-failed.json
+│       └── ...
+└── docs/
+    ├── OVERVIEW.md
+    └── UPDATES.md            # release notes + fetch summaries
+```
+
+## Consumption Strategy
+
+- **Monorepo:** SDK packages reference files via the workspace package name
+  (`@marcohefti/request-network-api-contracts/specs/...`). Build/validation scripts run from
+  the monorepo root can read from this package without additional tooling.
+- **Post-split:** Each SDK repository will include this repo via Git submodule
+  (or shallow git dependency) so the same files are available without copying.
+  Documentation here will outline the update workflow.
+
+## Update Workflow
+
+1. Run `pnpm --filter "./packages/request-api-client" prepare:spec` to download the latest OpenAPI spec and metadata into `specs/openapi/` and regenerate the TypeScript/Zod outputs in the client package.
+2. Update webhook fixtures in `fixtures/webhooks/` when Request publishes new payloads. Pair every new fixture with test coverage in each SDK.
+3. Execute `pnpm --filter "./packages/request-client-contracts" verify` to confirm the expected files are present and within size bounds.
+4. Commit the contract changes (`specs/**`, `fixtures/**`, docs) together with any regenerated client artefacts so consumers can diff the update in one review.
+5. Append an entry to `docs/UPDATES.md` capturing the date, upstream reference, and required SDK follow-up.
+
+## Related Backlog Tasks
+
+- **Track contract versioning** - provide a manifest so SDKs can pin/compare revisions.
+- **Webhook fixture parity automation** - ensure both SDKs validate against the shared payload set.
+- **Document submodule workflow** - outline how downstream repositories should consume this package post-split.

package/docs/UPDATE-WORKFLOW.md

@@ -0,0 +1,36 @@
+# Contracts Update Workflow
+
+Use this checklist whenever the Request Network API publishes contract changes. The TypeScript client's tooling writes new assets directly into this package. Follow the steps below to keep every SDK in sync.
+
+## 1. Refresh the OpenAPI spec
+
+```bash
+pnpm --filter "./packages/request-api-client" prepare:spec
+```
+
+`prepare:spec` downloads the latest OpenAPI document into `specs/openapi/` (updating both the JSON and `.meta.json`) and regenerates the TypeScript + Zod outputs referenced by the client.
+
+## 2. Update webhook schema (if needed)
+
+- Manually edit `specs/webhooks/request-network-webhooks.json` when Request publishes new webhook fields or events.
+- Keep any breaking changes coordinated across SDKs-update shared enums and validation helpers in the clients immediately after adjusting the schema.
+
+## 3. Sync webhook fixtures
+
+- Add or update payload samples under `fixtures/webhooks/`.
+- Ensure each new fixture has corresponding parity tests in every SDK that consumes it.
+
+## 4. Verify assets
+
+```bash
+pnpm --filter "./packages/request-client-contracts" verify
+```
+
+The verification script asserts that the expected files exist and logs their sizes for a quick sanity check.
+
+## 5. Document and commit
+
+- Record the change in `docs/UPDATES.md` (date, summary, upstream source, required SDK follow-up).
+- Commit the updated contracts alongside regenerated client artefacts so downstream packages pick up the change in one review.
+
+Repeat this workflow whenever the upstream API contract or webhook catalogue changes.

package/docs/UPDATES.md

@@ -0,0 +1,15 @@
+# Contracts Update Log
+
+Record noteworthy contract updates here (spec revisions, new fixtures). Each
+entry should reference the Request API release or Git commit that introduced the
+change so SDK maintainers know when to regenerate code.
+
+## Template
+-	**Date:** YYYY-MM-DD
+-	**Spec Version:** e.g. 2025-03-12
+-	**Change Summary:**
+-	**Source:** Link to Request API changelog / ticket
+-	**Notes:** Regeneration impact, required SDK updates, new fixtures
+
+## History
+- *No entries yet* - initial import seeded via `pnpm --filter "./packages/request-api-client" prepare:spec` on 2025-11-06.

package/fixtures/webhooks/compliance-approved.json

@@ -0,0 +1,9 @@
+{
+  "event": "compliance.updated",
+  "requestId": "req_compliance123",
+  "clientUserId": "user-123",
+  "kycStatus": "approved",
+  "agreementStatus": "signed",
+  "isCompliant": true,
+  "timestamp": "2025-08-28T22:25:45.995Z"
+}

package/fixtures/webhooks/compliance-pending.json

@@ -0,0 +1,8 @@
+{
+  "event": "compliance.updated",
+  "requestId": "req_compliance789",
+  "clientUserId": "user-789",
+  "kycStatus": "initiated",
+  "agreementStatus": "pending",
+  "timestamp": "2025-08-29T00:25:45.995Z"
+}

package/fixtures/webhooks/compliance-rejected.json

@@ -0,0 +1,8 @@
+{
+  "event": "compliance.updated",
+  "requestId": "req_compliance456",
+  "clientUserId": "user-456",
+  "kycStatus": "pending",
+  "agreementStatus": "rejected",
+  "timestamp": "2025-08-28T23:25:45.995Z"
+}

package/fixtures/webhooks/payment-confirmed.json

@@ -0,0 +1,24 @@
+{
+  "event": "payment.confirmed",
+  "requestId": "req_test123456789abcdef",
+  "requestID": "req_test123456789abcdef",
+  "paymentReference": "0x1234567890abcdef1234567890abcdef12345678",
+  "explorer": "https://scan.request.network/request/req_test123456789abcdef",
+  "amount": "100.0",
+  "totalAmountPaid": "100.0",
+  "expectedAmount": "100.0",
+  "timestamp": "2025-08-28T12:25:45.995Z",
+  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+  "network": "ethereum",
+  "currency": "USDC",
+  "paymentCurrency": "USDC",
+  "isCryptoToFiat": false,
+  "paymentProcessor": "request-network",
+  "fees": [
+    {
+      "type": "network",
+      "amount": "0.02",
+      "currency": "ETH"
+    }
+  ]
+}

package/fixtures/webhooks/payment-detail-approved.json

@@ -0,0 +1,7 @@
+{
+  "event": "payment_detail.updated",
+  "requestId": "req_detail123",
+  "paymentAccountId": "acct_approved_123",
+  "status": "approved",
+  "timestamp": "2025-08-28T19:25:45.995Z"
+}

package/fixtures/webhooks/payment-detail-failed.json

@@ -0,0 +1,8 @@
+{
+  "event": "payment_detail.updated",
+  "requestId": "req_detail456",
+  "paymentAccountId": "acct_failed_456",
+  "status": "failed",
+  "rejectionMessage": "Bank verification failed",
+  "timestamp": "2025-08-28T20:25:45.995Z"
+}

package/fixtures/webhooks/payment-detail-pending.json

@@ -0,0 +1,7 @@
+{
+  "event": "payment_detail.updated",
+  "requestId": "req_detail789",
+  "paymentAccountId": "acct_pending_789",
+  "status": "pending",
+  "timestamp": "2025-08-28T21:25:45.995Z"
+}

package/fixtures/webhooks/payment-detail-verified.json

@@ -0,0 +1,11 @@
+{
+  "event": "payment_detail.updated",
+  "paymentDetailsId": "pd_test_verified",
+  "clientUserId": "user_test_verified",
+  "status": "verified",
+  "timestamp": "2025-11-04T05:18:54.721Z",
+  "rawPayload": {
+    "bankAccount": "verified",
+    "method": "bank_transfer"
+  }
+}

package/fixtures/webhooks/payment-failed.json

@@ -0,0 +1,15 @@
+{
+  "event": "payment.failed",
+  "requestId": "req_fail1234567890",
+  "paymentReference": "0xfail1234567890abcdef1234567890abcdef1234",
+  "amount": "100.0",
+  "totalAmountPaid": "0.0",
+  "expectedAmount": "100.0",
+  "timestamp": "2025-08-28T18:25:45.995Z",
+  "paymentCurrency": "USDC",
+  "isCryptoToFiat": true,
+  "paymentProcessor": "request-network",
+  "subStatus": "insufficient_funds",
+  "failureReason": "Insufficient fiat liquidity",
+  "retryAfter": "2025-08-29T18:25:45.995Z"
+}

package/fixtures/webhooks/payment-partial.json

@@ -0,0 +1,11 @@
+{
+  "event": "payment.partial",
+  "requestId": "req_partial1234567890",
+  "paymentReference": "0xpartial1234567890abcdef1234567890abcdef1234",
+  "amount": "50.0",
+  "totalAmountPaid": "50.0",
+  "expectedAmount": "100.0",
+  "timestamp": "2025-11-04T05:19:59.380Z",
+  "paymentProcessor": "request-network",
+  "fees": []
+}

package/fixtures/webhooks/payment-processing.json

@@ -0,0 +1,13 @@
+{
+  "event": "payment.processing",
+  "requestId": "req_proc1234567890",
+  "paymentReference": "0xproc1234567890abcdef1234567890abcdef1234",
+  "amount": "100.0",
+  "totalAmountPaid": "0.0",
+  "expectedAmount": "100.0",
+  "timestamp": "2025-08-28T18:25:45.995Z",
+  "paymentCurrency": "USDC",
+  "isCryptoToFiat": true,
+  "paymentProcessor": "request-network",
+  "subStatus": "processing"
+}

package/fixtures/webhooks/payment-refunded.json

@@ -0,0 +1,10 @@
+{
+  "event": "payment.refunded",
+  "requestId": "req_refunded1234567890",
+  "paymentReference": "0xrefund1234567890abcdef1234567890abcdef5678",
+  "refundedTo": "0x742d35cc6634c0532925a3b8d78ecf23ee6d63d4",
+  "refundAmount": "100.0",
+  "currency": "USDC",
+  "timestamp": "2025-11-04T05:20:45.123Z",
+  "paymentProcessor": "request-network"
+}

package/fixtures/webhooks/request-recurring.json

@@ -0,0 +1,9 @@
+{
+  "event": "request.recurring",
+  "requestId": "req_recurring9876543210",
+  "paymentReference": "0x9876543210fedcba9876543210fedcba98765432",
+  "originalRequestId": "req_original1234567890",
+  "originalRequestPaymentReference": "0x1234567890abcdef1234567890abcdef12345678",
+  "timestamp": "2025-11-04T05:21:22.149Z",
+  "paymentProcessor": "request-network"
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@marcohefti/request-network-api-contracts",
+  "version": "0.5.0",
+  "private": false,
+  "description": "Shared contracts for Request Network API clients (OpenAPI spec, webhook fixtures).",
+  "license": "MIT",
+  "keywords": [
+    "request-network",
+    "contracts",
+    "openapi",
+    "webhook"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/marcohefti/request-network-api-contracts.git"
+  },
+  "files": [
+    "specs",
+    "fixtures",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "verify": "node scripts/verify.js"
+  }
+}

package/specs/README.md

@@ -0,0 +1,23 @@
+# Specs Directory
+
+This folder holds the contracts consumed by the Request client SDKs.
+
+```
+openapi/   # auto-generated from the Request REST API
+webhooks/  # manually curated webhook schema
+```
+
+## `openapi/`
+- `request-network-openapi.json` – fetched via automation from the upstream
+  Request API.
+- `request-network-openapi.meta.json` – metadata captured during fetch (e.g.
+  etag, timestamp, source URL).
+
+These files should only change through the regeneration script (`pnpm --filter "./packages/request-api-client" fetch:openapi` or the broader `prepare:spec`). Avoid manual edits. Rerun the fetch command when upstream changes land and commit the updated JSON + metadata.
+
+## `webhooks/`
+- `request-network-webhooks.json` – maintained manually. Update it when webhook
+  documentation or behaviour changes, and keep fixtures/tests in sync.
+
+This separation ensures automation never overwrites the manual webhook spec while
+making it obvious which files are generated vs. curated.