@zadq/x402 0.1.0 → 0.2.0

package/README.md

@@ -26,6 +26,10 @@ import { withIdentityPolicy } from '@zadq/x402/extension';
 import { resolveSignal } from '@zadq/x402/explorer';
 ```
 
+When the service serves its own statement about the seller's guarantee deposit
+beside the verdict, `readDepositDeclaration(verdict)` returns it — a state and
+a level band, never an amount — and `null` otherwise.
+
 Subpath exports: `verdict`, `extension`, `header`, `receipt`, `explorer`,
 `keys`, `webhook`, `holder` (Node only) — or everything from the root. The
 contracts each module honours are documented at

package/dist/brand.d.ts

@@ -1 +1,2 @@
 export declare const BRAND = "ZadQ";
+export declare const VERDICT_EXTENSION_KEY: string;

package/dist/brand.js

@@ -1,3 +1,6 @@
 // Single brand constant: a rename is an edit here plus DNS. No brand string
 // appears anywhere else in src/ (scripts/check-brand.mjs enforces it).
 export const BRAND = 'ZadQ';
+// The verifying party's own extension key beside the verdict (the service's
+// deposit declaration): the brand in lower case, as the API names it.
+export const VERDICT_EXTENSION_KEY = BRAND.toLowerCase();

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { BRAND } from './brand.js';
-export { CHAINS, DEFAULT_TIMEOUT_MS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, verifyVerdictSignature, type Chain, type Freshness, type SignatureCheck, type Verdict, type VerdictOutcome, type VerdictReason, type VerdictSubject, } from './verdict.js';
+export { BRAND, VERDICT_EXTENSION_KEY } from './brand.js';
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, readDepositDeclaration, verifyVerdictSignature, type Chain, type DepositDeclaration, type DepositDeclarationState, type DepositLevel, type Freshness, type SignatureCheck, type Verdict, type VerdictOutcome, type VerdictReason, type VerdictSubject, } from './verdict.js';
 export { IDENTITY_POLICY_EXTENSION, MINTID_IDENTITY_EXTENSION, PERIMETER_EXTENSION, readIdentityPolicy, readMintidIdentity, readPerimeterInvitation, withIdentityPolicy, withMintidIdentity, withPerimeterInvitation, withSellerIdentity, type ClaimPolicyEntry, type CredentialState, type IdentityPolicy, type MintidIdentityPolicy, type PaymentRequiredBody, type PerimeterInvitation, type SellerIdentity, } from './extension.js';
 export { X_PAYMENT_HEADER, X_PAYMENT_IDENTITY_HEADER, attachIdentityProof, readIdentityProof, type IdentityProof, } from './header.js';
 export { ATTESTATION_RECEIPT_FORMAT, attestationReceiptProof, canonicalJson, isReceipt, readAttestationReceipt, receiptSigningInput, verifyAttestationReceipt, type AttestationReceipt, type ReceiptCheck, } from './receipt.js';

package/dist/index.js

@@ -6,8 +6,8 @@
 // Transport follows the bIP-0002 x402 profile of the MintID identity network
 // (cited by name): identity policy in a `PaymentRequired` extension, proof alongside
 // the `X-PAYMENT` header.
-export { BRAND } from "./brand.js";
-export { CHAINS, DEFAULT_TIMEOUT_MS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, verifyVerdictSignature, } from "./verdict.js";
+export { BRAND, VERDICT_EXTENSION_KEY } from "./brand.js";
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, readDepositDeclaration, verifyVerdictSignature, } from "./verdict.js";
 export { IDENTITY_POLICY_EXTENSION, MINTID_IDENTITY_EXTENSION, PERIMETER_EXTENSION, readIdentityPolicy, readMintidIdentity, readPerimeterInvitation, withIdentityPolicy, withMintidIdentity, withPerimeterInvitation, withSellerIdentity, } from "./extension.js";
 export { X_PAYMENT_HEADER, X_PAYMENT_IDENTITY_HEADER, attachIdentityProof, readIdentityProof, } from "./header.js";
 export { ATTESTATION_RECEIPT_FORMAT, attestationReceiptProof, canonicalJson, isReceipt, readAttestationReceipt, receiptSigningInput, verifyAttestationReceipt, } from "./receipt.js";

package/dist/verdict.d.ts

@@ -1,10 +1,3 @@
-/**
- * The payment rails the seller rail covers (Platform Decision 14): USDC on
- * Base (`base`, an EVM address) or on Solana (`solana`). The contract is a
- * closed enumeration — the service answers a 400 problem to any other value,
- * and other EVM chains are not declared until a seller needs one — so the
- * type is the same closed union, not a string.
- */
 export type Chain = 'base' | 'solana';
 /** The declared rails, in the order the contract lists them. */
 export declare const CHAINS: readonly Chain[];
@@ -52,7 +45,39 @@ export type Verdict = {
     keyId?: string;
     /** Present on every non-positive outcome, from the closed vocabulary; absent on `human_backed`. */
     reason?: VerdictReason;
+    /**
+     * The verifying party's own statements beside the canonical verdict, keyed
+     * by its brand in lower case (`VERDICT_EXTENSION_KEY`). Outside the signed
+     * bytes; absent on most verdicts. Read with `readDepositDeclaration`.
+     */
+    extensions?: Record<string, {
+        deposit?: DepositDeclaration;
+    } | undefined>;
 };
+/** The declaration's public states — one code per label of the seller's deposit, as the service publishes them. */
+export declare const DEPOSIT_DECLARATION_STATES: readonly ["required", "awaiting_funds", "held", "below_level", "claim_pending", "released_partial", "returning", "returned"];
+export type DepositDeclarationState = (typeof DEPOSIT_DECLARATION_STATES)[number];
+/** The band of the deposit, named by the schedule tier; the amount is never carried. */
+export declare const DEPOSIT_LEVELS: readonly ["attested_vendor", "regulated_compliance"];
+export type DepositLevel = (typeof DEPOSIT_LEVELS)[number];
+/**
+ * The service's own statement about the seller's guarantee deposit under its
+ * Terms, beside the verdict: a state and a level band read from the service's
+ * record at `verifiedAt` — never an amount, a balance or a holder reference.
+ * The identity network carries no fact about this deposit; the statement is
+ * the service's and sits outside the verdict's signed bytes.
+ */
+export type DepositDeclaration = {
+    state: DepositDeclarationState;
+    level: DepositLevel;
+    verifiedAt: string;
+};
+/**
+ * The deposit declaration a verdict carries, or `null` when it carries none
+ * (the deposit rail off, no deposit owed, or a reader that was served the
+ * verdict alone). Malformed content reads as none — nothing throws.
+ */
+export declare function readDepositDeclaration(verdict: Verdict | undefined | null): DepositDeclaration | null;
 export declare const DEFAULT_TIMEOUT_MS = 3000;
 /**
  * Fetches the current verdict for an endpoint from the free verification path.

package/dist/verdict.js

@@ -10,6 +10,14 @@
 // or an absent verdict as "no signal". Nothing here throws on network failure
 // and nothing blocks your payment flow — your integration keeps working
 // unchanged when no verification response is available.
+/**
+ * The payment rails the seller rail covers (Platform Decision 14): USDC on
+ * Base (`base`, an EVM address) or on Solana (`solana`). The contract is a
+ * closed enumeration — the service answers a 400 problem to any other value,
+ * and other EVM chains are not declared until a seller needs one — so the
+ * type is the same closed union, not a string.
+ */
+import { VERDICT_EXTENSION_KEY } from "./brand.js";
 /** The declared rails, in the order the contract lists them. */
 export const CHAINS = ['base', 'solana'];
 /** Runtime guard for the `Chain` enumeration (input from a wire, an agent or an env var). */
@@ -33,6 +41,37 @@ export function canonicalPayTo(chain, payTo) {
 export function canonicalSubject(subject) {
     return { ...subject, payTo: canonicalPayTo(subject.chain, subject.payTo) };
 }
+/** The declaration's public states — one code per label of the seller's deposit, as the service publishes them. */
+export const DEPOSIT_DECLARATION_STATES = [
+    'required',
+    'awaiting_funds',
+    'held',
+    'below_level',
+    'claim_pending',
+    'released_partial',
+    'returning',
+    'returned',
+];
+/** The band of the deposit, named by the schedule tier; the amount is never carried. */
+export const DEPOSIT_LEVELS = ['attested_vendor', 'regulated_compliance'];
+/**
+ * The deposit declaration a verdict carries, or `null` when it carries none
+ * (the deposit rail off, no deposit owed, or a reader that was served the
+ * verdict alone). Malformed content reads as none — nothing throws.
+ */
+export function readDepositDeclaration(verdict) {
+    const d = verdict?.extensions?.[VERDICT_EXTENSION_KEY]?.deposit;
+    if (typeof d !== 'object' || d === null)
+        return null;
+    const { state, level, verifiedAt } = d;
+    if (!DEPOSIT_DECLARATION_STATES.includes(String(state)))
+        return null;
+    if (!DEPOSIT_LEVELS.includes(String(level)))
+        return null;
+    if (typeof verifiedAt !== 'string' || Number.isNaN(Date.parse(verifiedAt)))
+        return null;
+    return { state: state, level: level, verifiedAt };
+}
 export const DEFAULT_TIMEOUT_MS = 3000;
 /**
  * Fetches the current verdict for an endpoint from the free verification path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zadq/x402",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Client helpers for the free seller-verification path of x402 endpoints: the signed verdict and its local Ed25519 check, the HTTP 402 identity-policy extension and companion header, the issuer receipt, the explorer client, the webhook receiver and the seller holder driver. Zero runtime dependencies; every helper degrades to \"unknown\".",
   "license": "Apache-2.0",
   "type": "module",