vet-sdk-core-ts 0.4.17 → 0.4.19

package/README.md

@@ -1,11 +1,28 @@
 # VetChain Core SDK
 
+Development and releases follow the mandatory
+[`local-first TDD and release contract`](docs/LOCAL_FIRST_RELEASE_CONTRACT.md).
+
 Browser-safe VetChain domain contracts. This repository is independent from
 UHC SDK packages and must not import them.
 
 The SDK consumes governed browser-safe values from `vet-data-utils-ts` and
 owns gateway request construction. GW VET remains the policy authority.
 
+## USDC payment quotes
+
+`vet-sdk-core-ts/payment` separates the payment provider, asset and EVM network
+instead of treating every token named USDC as equivalent. It pins Circle USDC
+on Base Sepolia and Base mainnet, validates the server-authored recipient,
+integer six-decimal amount and expiry, and keeps mainnet disabled unless the
+caller supplies a separately approved release policy. Local Anvil deployments
+provide their deployed mock-token contract through the same network contract;
+they never reuse a production address.
+
+The quote authorizes no payment by itself. A server payment adapter must still
+verify the receipt, Transfer log, payer, recipient, amount, confirmation depth,
+invoice state and transaction-hash idempotency before reconciling the payment.
+
 ## Research studies
 
 `buildVeterinaryResearchStudyCreateWorkflowIds` accepts a client-generated

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
 export * from "./reusable-bff.js";
 export * from "./research-study.js";
+export * from "./payment.js";
 export * from "vet-data-utils-ts";

package/dist/index.js

@@ -5,4 +5,5 @@ export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
 export * from "./reusable-bff.js";
 export * from "./research-study.js";
+export * from "./payment.js";
 export * from "vet-data-utils-ts";

package/dist/payment.d.ts

@@ -0,0 +1,10 @@
+import { type EvmPaymentNetworkId, type EvmTransferNetwork, type EvmTransferPaymentQuote } from 'vet-data-utils-ts/payment';
+export { EvmPaymentNetworkIds, PaymentAssetIds, PaymentCurrencyCodes, PaymentProviderIds, USDC_BASE_NETWORKS, USDC_DECIMALS, VET_PAYMENT_TEST_DATA, type EvmPaymentNetworkId, type PaymentProviderId, type EvmTransferNetwork, type EvmTransferPaymentConfirmation, type EvmTransferPaymentQuote, usdOfferToUsdcMinor, } from 'vet-data-utils-ts/payment';
+export type EvmTransferPaymentQuotePolicy = Readonly<{
+    now: Date;
+    recipient: `0x${string}`;
+    allowMainnet: boolean;
+    networks?: Readonly<Partial<Record<EvmPaymentNetworkId, EvmTransferNetwork>>>;
+}>;
+/** Validates a server-authored quote without trusting browser network fields. */
+export declare function validateEvmTransferPaymentQuote(value: unknown, policy: EvmTransferPaymentQuotePolicy): EvmTransferPaymentQuote;

package/dist/payment.js

@@ -0,0 +1,49 @@
+import { PaymentProviderIds, PaymentAssetIds, USDC_DECIMALS, USDC_BASE_NETWORKS, } from 'vet-data-utils-ts/payment';
+export { EvmPaymentNetworkIds, PaymentAssetIds, PaymentCurrencyCodes, PaymentProviderIds, USDC_BASE_NETWORKS, USDC_DECIMALS, VET_PAYMENT_TEST_DATA, usdOfferToUsdcMinor, } from 'vet-data-utils-ts/payment';
+const EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
+const POSITIVE_INTEGER_PATTERN = /^[1-9][0-9]*$/;
+function paymentContractError(code) {
+    throw new Error(code);
+}
+/** Validates a server-authored quote without trusting browser network fields. */
+export function validateEvmTransferPaymentQuote(value, policy) {
+    if (!value || typeof value !== "object")
+        paymentContractError("payment_quote_invalid");
+    const quote = value;
+    if (quote.version !== 1
+        || quote.provider !== PaymentProviderIds.EvmTransfer
+        || quote.asset !== PaymentAssetIds.Usdc) {
+        paymentContractError("payment_quote_invalid");
+    }
+    const networks = policy.networks || USDC_BASE_NETWORKS;
+    const network = quote.network ? networks[quote.network] : undefined;
+    if (!network || quote.chainId !== network.chainId)
+        paymentContractError("payment_network_not_allowed");
+    if (network.mainnet && !policy.allowMainnet)
+        paymentContractError("payment_mainnet_not_enabled");
+    if (!EVM_ADDRESS_PATTERN.test(String(quote.tokenContract || ""))
+        || quote.asset !== network.asset
+        || quote.tokenContract?.toLowerCase() !== network.tokenContract.toLowerCase()) {
+        paymentContractError("payment_token_contract_not_allowed");
+    }
+    if (!EVM_ADDRESS_PATTERN.test(String(quote.recipient || ""))
+        || quote.recipient?.toLowerCase() !== policy.recipient.toLowerCase()) {
+        paymentContractError("payment_recipient_mismatch");
+    }
+    if (!POSITIVE_INTEGER_PATTERN.test(String(quote.amountMinor || "")) || quote.decimals !== USDC_DECIMALS) {
+        paymentContractError("payment_amount_invalid");
+    }
+    if (!String(quote.paymentReference || "").trim()
+        || !String(quote.invoiceId || "").trim()
+        || !String(quote.offerId || "").trim()) {
+        paymentContractError("payment_reference_invalid");
+    }
+    const expiresAt = Date.parse(String(quote.expiresAt || ""));
+    const createdAt = Date.parse(String(quote.createdAt || ""));
+    if (!Number.isFinite(createdAt) || !Number.isFinite(expiresAt) || createdAt >= expiresAt) {
+        paymentContractError("payment_quote_invalid");
+    }
+    if (expiresAt <= policy.now.getTime())
+        paymentContractError("payment_quote_expired");
+    return quote;
+}

package/docs/LOCAL_FIRST_RELEASE_CONTRACT.md

@@ -0,0 +1,100 @@
+# Local-first TDD and release contract
+
+This contract is mandatory for behavior changes, shared packages, gateways and
+portals. Repository skills and release-continuity tests enforce it.
+
+## 1. Canonical types and reusable test data
+
+Before inventing a type, enum, code, identifier, claim, vocabulary or test
+literal, search the applicable standards and the owning shared packages.
+
+Use the canonical type or terminology from HL7/FHIR, LOINC, SNOMED CT, ICD-10,
+WHO ATC, Schema.org or the applicable governed standard. Then reuse the
+exported type, builder or fixture from the versioned domain data package
+(`<version>-data` or `<version>-data-utils`) or `common-utils`.
+
+If it does not exist, add it first to the owning shared package with its own
+red-green test and export it. Consumers import that export. They must not copy
+or locally recreate governed strings, object shapes or identifiers.
+
+## 2. TDD contract
+
+Every new or modified test file starts on its first line with a
+`// Flow contract:` comment that links this document and names the production
+journey, authorization boundary and persistence invariant under proof.
+
+Apply strict `red -> green -> refactor`:
+
+1. Write the smallest executable contract and run it red.
+2. The red result must fail because the required production behavior is absent
+   or wrong, not because the test is malformed or setup is missing.
+3. Implement only enough production code to make that contract green.
+4. Run the smallest affected integration and real-boundary gate.
+5. Refactor while keeping the focused contract green.
+
+A skip, accepted error, placeholder, pending setup, fixture-only UI or mock that
+replaces the real boundary is never a green result. Unit mocks may isolate code,
+but local service and Playwright proof must exercise the real UI -> BFF ->
+high-level SDK -> GW/DataConv boundary when that journey is affected.
+
+## 3. Local-first gates and failure continuation
+
+Promotion order is cumulative:
+
+`test -> local-network -> test-network/staging -> network/production`
+
+The `test` stage includes every affected unit, integration, local service,
+real UI and Playwright gate without blockchain. After a failure, resume only
+the smallest failed gate. Do not repeat a green gate unless the fix changed its
+boundary, it creates required state, or the environment is no longer
+trustworthy. Run the complete affected local matrix once at branch closure.
+
+## 4. Unpublished package iteration
+
+Keep all participating repositories on pushed but unmerged branches while the
+local matrix is still being corrected. Build an immutable tarball with
+`npm pack` and install it in downstream branches with `--no-save`.
+
+Start every downstream proof from its committed lockfile with `npm ci`. If a
+normal `npm install --no-save <tarball>` would re-resolve unrelated dependency
+ranges, do not use that resolver path: overlay the exact packed contents in the
+matching `node_modules` package directory, or use an equivalent isolated
+installation that leaves `package.json` and the lockfile unchanged. Before
+testing, verify the exact local package versions and any runtime-sensitive
+baseline dependencies. A later `npm ci` must remove the temporary overlay.
+
+The tarball is temporary test input. Never commit a `file:`, Git, workspace or
+vendored tarball dependency or its generated lockfile state. An npm
+authorization or publication failure must never stop the local `test` stage.
+
+Do not attempt `npm publish` until every affected local gate in section 3 is
+green.
+
+## 5. Publication and merge order
+
+After all local gates are green:
+
+1. Publish and verify immutable npm packages from the lowest changed dependency
+   upward.
+2. In gateway consumers, replace the temporary tarball with the exact published
+   registry version; commit the registry dependency and lockfile.
+3. Run only the minimal clean-install, import/export and startup smoke needed to
+   prove the registry artifact matches the tested tarball. Do not repeat the
+   green local matrix unless the artifact differs or invalidates prior evidence.
+4. Merge and push package repositories to `main`.
+5. Merge and push gateway consumers to `main` only with exact registry
+   versions installed, then build immutable GW images and run `local-network`.
+6. Portal consumers remain on pushed, unmerged branches with the immutable
+   tarball during `local-network`; do not reinstall or repeat their already-green
+   local matrix. The gateway image and Fabric gate do not require changing a
+   portal that already proved the same package tarball locally.
+7. After `local-network` is green, install the exact registry version in each
+   affected portal, commit its registry dependency and lockfile, and run only
+   the minimal artifact smoke.
+8. Merge portal consumers to `main`, continue to `test-network`/staging and
+   finally `network`/production. No tarball or local dependency may reach
+   `main`.
+
+Missing exact registry publication blocks consumer merge, image build and
+environment promotion. It does not block continued local testing with the
+immutable tarball.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -39,6 +39,10 @@
     "./research-study": {
       "types": "./dist/research-study.d.ts",
       "default": "./dist/research-study.js"
+    },
+    "./payment": {
+      "types": "./dist/payment.d.ts",
+      "default": "./dist/payment.js"
     }
   },
   "files": [
@@ -64,6 +68,6 @@
   "dependencies": {
     "@noble/hashes": "^2.2.0",
     "gdc-common-utils-ts": "2.9.4",
-    "vet-data-utils-ts": "0.5.3"
+    "vet-data-utils-ts": "0.5.5"
   }
 }