@opendatalabs/vana-sdk 3.6.2 → 3.6.3

package/dist/direct/escrow-payment.cjs

@@ -20,7 +20,9 @@ var escrow_payment_exports = {};
 __export(escrow_payment_exports, {
   GRANT_OP_TYPE: () => GRANT_OP_TYPE,
   authorizeGrantPayment: () => authorizeGrantPayment,
+  buildGrantPaymentHeader: () => buildGrantPaymentHeader,
   createDefaultNonceSource: () => createDefaultNonceSource,
+  paymentReceiptFromHeader: () => paymentReceiptFromHeader,
   toDirectFeeBreakdown: () => toDirectFeeBreakdown,
   toDirectPaymentReceipt: () => toDirectPaymentReceipt
 });
@@ -54,7 +56,18 @@ function createDefaultNonceSource() {
     return next;
   };
 }
-async function authorizeGrantPayment(params) {
+function base64EncodeJson(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function base64DecodeJson(value) {
+  const binary = atob(value);
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function signGrantPayment(params) {
   const { payerAddress, required, config } = params;
   const nonceSource = config.nonceSource ?? createDefaultNonceSource();
   const paymentNonce = BigInt(
@@ -63,27 +76,59 @@ async function authorizeGrantPayment(params) {
   const asset = required.asset || import_escrow.NATIVE_ASSET_ADDRESS;
   const opId = required.grantId;
   const amount = BigInt(required.amount);
+  const message = {
+    payerAddress,
+    opType: GRANT_OP_TYPE,
+    opId,
+    asset,
+    amount,
+    paymentNonce
+  };
   const signature = await config.signTypedData({
     domain: (0, import_escrow.genericPaymentDomain)(config.chainId, config.escrowContract),
     types: import_escrow.GENERIC_PAYMENT_TYPES,
     primaryType: "GenericPayment",
-    message: {
-      payerAddress,
-      opType: GRANT_OP_TYPE,
-      opId,
-      asset,
-      amount,
-      paymentNonce
-    }
+    message
   });
+  return {
+    message: {
+      ...message,
+      amount: amount.toString(),
+      paymentNonce: paymentNonce.toString()
+    },
+    signature,
+    ...required.accessRecord ? { accessRecord: required.accessRecord } : {}
+  };
+}
+async function buildGrantPaymentHeader(params) {
+  const signed = await signGrantPayment(params);
+  const payment = {
+    x402Version: 1,
+    scheme: "vana-escrow-grant",
+    network: params.required.network ?? `vana:${params.config.chainId}`,
+    payload: signed
+  };
+  return base64EncodeJson(payment);
+}
+function paymentReceiptFromHeader(header) {
+  if (!header) return void 0;
+  try {
+    return toDirectPaymentReceipt(base64DecodeJson(header));
+  } catch {
+    return void 0;
+  }
+}
+async function authorizeGrantPayment(params) {
+  const { payerAddress, required, config } = params;
+  const signed = await signGrantPayment(params);
   const result = await config.client.payForOp({
     payerAddress,
     opType: GRANT_OP_TYPE,
-    opId,
-    asset,
-    amount: amount.toString(),
-    paymentNonce: paymentNonce.toString(),
-    signature,
+    opId: signed.message.opId,
+    asset: signed.message.asset,
+    amount: signed.message.amount,
+    paymentNonce: signed.message.paymentNonce,
+    signature: signed.signature,
     accessRecord: required.accessRecord
   });
   return toDirectPaymentReceipt(result);
@@ -92,7 +137,9 @@ async function authorizeGrantPayment(params) {
 0 && (module.exports = {
   GRANT_OP_TYPE,
   authorizeGrantPayment,
+  buildGrantPaymentHeader,
   createDefaultNonceSource,
+  paymentReceiptFromHeader,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt
 });

package/dist/direct/escrow-payment.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * grant's data-access fee through the escrow gateway:\n *\n *  1. Sign a `GenericPayment` EIP-712 message (op `\"grant\"`, opId = grantId)\n *     with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module adapts the escrow `payForOp` flow to the direct-read use case; it\n * does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\n/** Escrow settlement configuration for the controller. */\nexport interface EscrowPaymentConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, required, config } = params;\n  const nonceSource = config.nonceSource ?? createDefaultNonceSource();\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.grantId as `0x${string}`;\n  const amount = BigInt(required.amount);\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message: {\n      payerAddress,\n      opType: GRANT_OP_TYPE,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n    },\n  });\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId,\n    asset,\n    amount: amount.toString(),\n    paymentNonce: paymentNonce.toString(),\n    signature,\n    accessRecord: required.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,oBAOO;AAQA,MAAM,gBAAgB;AA+CtB,SAAS,qBACd,WACoB;AACpB,SAAO;AAAA,IACL,iBAAiB,UAAU;AAAA,IAC3B,eAAe,UAAU;AAAA,IACzB,kBAAkB,UAAU;AAAA,EAC9B;AACF;AAGO,SAAS,uBACd,QACsB;AACtB,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,MAAM,OAAO;AAAA,IACb,OAAO,OAAO;AAAA,IACd,QAAQ,OAAO;AAAA,IACf,cAAc,OAAO;AAAA,IACrB,WAAW,qBAAqB,OAAO,SAAS;AAAA,IAChD,QAAQ,OAAO;AAAA,EACjB;AACF;AAGO,SAAS,2BAA+C;AAC7D,QAAM,WAAW,oBAAI,IAAoB;AACzC,SAAO,CAAC,iBAAiC;AACvC,UAAM,MAAM,aAAa,YAAY;AACrC,UAAM,QAAQ,SAAS,IAAI,GAAG,KAAK,MAAM;AACzC,aAAS,IAAI,KAAK,IAAI;AACtB,WAAO;AAAA,EACT;AACF;AASA,eAAsB,sBAAsB,QAIV;AAChC,QAAM,EAAE,cAAc,UAAU,OAAO,IAAI;AAC3C,QAAM,cAAc,OAAO,eAAe,yBAAyB;AACnE,QAAM,eAAe;AAAA,IACnB,SAAS,gBAAiB,MAAM,YAAY,YAAY;AAAA,EAC1D;AACA,QAAM,QAAS,SAAS,SAAS;AACjC,QAAM,OAAO,SAAS;AACtB,QAAM,SAAS,OAAO,SAAS,MAAM;AAErC,QAAM,YAAY,MAAM,OAAO,cAAc;AAAA,IAC3C,YAAQ,oCAAqB,OAAO,SAAS,OAAO,cAAc;AAAA,IAClE,OAAO;AAAA,IACP,aAAa;AAAA,IACb,SAAS;AAAA,MACP;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF,CAAC;AAED,QAAM,SAAS,MAAM,OAAO,OAAO,SAAS;AAAA,IAC1C;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,QAAQ,OAAO,SAAS;AAAA,IACxB,cAAc,aAAa,SAAS;AAAA,IACpC;AAAA,IACA,cAAc,SAAS;AAAA,EACzB,CAAC;AAED,SAAO,uBAAuB,MAAM;AACtC;","names":[]}
+{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * grant's data-access fee through the escrow gateway:\n *\n *  1. Sign a `GenericPayment` EIP-712 message (op `\"grant\"`, opId = grantId)\n *     with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module adapts the escrow `payForOp` flow to the direct-read use case; it\n * does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface GrantPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedGrantPayment {\n  message: GrantPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedGrantPayment;\n}\n\n/** Escrow settlement configuration for the controller. */\nexport interface EscrowPaymentConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<SignedGrantPayment> {\n  const { payerAddress, required, config } = params;\n  const nonceSource = config.nonceSource ?? createDefaultNonceSource();\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.grantId as `0x${string}`;\n  const amount = BigInt(required.amount);\n\n  const message = {\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  const signed = await signGrantPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network: params.required.network ?? `vana:${params.config.chainId}`,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentReceipt | undefined {\n  if (!header) return undefined;\n  try {\n    return toDirectPaymentReceipt(base64DecodeJson(header) as EscrowPayResult);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, required, config } = params;\n  const signed = await signGrantPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: required.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}

package/dist/direct/escrow-payment.d.ts

@@ -67,6 +67,12 @@ export declare function toDirectFeeBreakdown(breakdown: PaymentBreakdown): Direc
 export declare function toDirectPaymentReceipt(result: EscrowPayResult): DirectPaymentReceipt;
 /** Default in-process monotonic nonce counter (seeded at 1 per payer). */
 export declare function createDefaultNonceSource(): PaymentNonceSource;
+export declare function buildGrantPaymentHeader(params: {
+    payerAddress: `0x${string}`;
+    required: PersonalServerPaymentRequired;
+    config: EscrowPaymentConfig;
+}): Promise<string>;
+export declare function paymentReceiptFromHeader(header: string | null | undefined): DirectPaymentReceipt | undefined;
 /**
  * Authorize an escrow payment for a grant data-access fee.
  *

package/dist/direct/escrow-payment.js

@@ -31,7 +31,18 @@ function createDefaultNonceSource() {
     return next;
   };
 }
-async function authorizeGrantPayment(params) {
+function base64EncodeJson(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function base64DecodeJson(value) {
+  const binary = atob(value);
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function signGrantPayment(params) {
   const { payerAddress, required, config } = params;
   const nonceSource = config.nonceSource ?? createDefaultNonceSource();
   const paymentNonce = BigInt(
@@ -40,27 +51,59 @@ async function authorizeGrantPayment(params) {
   const asset = required.asset || NATIVE_ASSET_ADDRESS;
   const opId = required.grantId;
   const amount = BigInt(required.amount);
+  const message = {
+    payerAddress,
+    opType: GRANT_OP_TYPE,
+    opId,
+    asset,
+    amount,
+    paymentNonce
+  };
   const signature = await config.signTypedData({
     domain: genericPaymentDomain(config.chainId, config.escrowContract),
     types: GENERIC_PAYMENT_TYPES,
     primaryType: "GenericPayment",
-    message: {
-      payerAddress,
-      opType: GRANT_OP_TYPE,
-      opId,
-      asset,
-      amount,
-      paymentNonce
-    }
+    message
   });
+  return {
+    message: {
+      ...message,
+      amount: amount.toString(),
+      paymentNonce: paymentNonce.toString()
+    },
+    signature,
+    ...required.accessRecord ? { accessRecord: required.accessRecord } : {}
+  };
+}
+async function buildGrantPaymentHeader(params) {
+  const signed = await signGrantPayment(params);
+  const payment = {
+    x402Version: 1,
+    scheme: "vana-escrow-grant",
+    network: params.required.network ?? `vana:${params.config.chainId}`,
+    payload: signed
+  };
+  return base64EncodeJson(payment);
+}
+function paymentReceiptFromHeader(header) {
+  if (!header) return void 0;
+  try {
+    return toDirectPaymentReceipt(base64DecodeJson(header));
+  } catch {
+    return void 0;
+  }
+}
+async function authorizeGrantPayment(params) {
+  const { payerAddress, required, config } = params;
+  const signed = await signGrantPayment(params);
   const result = await config.client.payForOp({
     payerAddress,
     opType: GRANT_OP_TYPE,
-    opId,
-    asset,
-    amount: amount.toString(),
-    paymentNonce: paymentNonce.toString(),
-    signature,
+    opId: signed.message.opId,
+    asset: signed.message.asset,
+    amount: signed.message.amount,
+    paymentNonce: signed.message.paymentNonce,
+    signature: signed.signature,
     accessRecord: required.accessRecord
   });
   return toDirectPaymentReceipt(result);
@@ -68,7 +111,9 @@ async function authorizeGrantPayment(params) {
 export {
   GRANT_OP_TYPE,
   authorizeGrantPayment,
+  buildGrantPaymentHeader,
   createDefaultNonceSource,
+  paymentReceiptFromHeader,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt
 };

package/dist/direct/escrow-payment.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * grant's data-access fee through the escrow gateway:\n *\n *  1. Sign a `GenericPayment` EIP-712 message (op `\"grant\"`, opId = grantId)\n *     with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module adapts the escrow `payForOp` flow to the direct-read use case; it\n * does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\n/** Escrow settlement configuration for the controller. */\nexport interface EscrowPaymentConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, required, config } = params;\n  const nonceSource = config.nonceSource ?? createDefaultNonceSource();\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.grantId as `0x${string}`;\n  const amount = BigInt(required.amount);\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message: {\n      payerAddress,\n      opType: GRANT_OP_TYPE,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n    },\n  });\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId,\n    asset,\n    amount: amount.toString(),\n    paymentNonce: paymentNonce.toString(),\n    signature,\n    accessRecord: required.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"AAqBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAQA,MAAM,gBAAgB;AA+CtB,SAAS,qBACd,WACoB;AACpB,SAAO;AAAA,IACL,iBAAiB,UAAU;AAAA,IAC3B,eAAe,UAAU;AAAA,IACzB,kBAAkB,UAAU;AAAA,EAC9B;AACF;AAGO,SAAS,uBACd,QACsB;AACtB,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,MAAM,OAAO;AAAA,IACb,OAAO,OAAO;AAAA,IACd,QAAQ,OAAO;AAAA,IACf,cAAc,OAAO;AAAA,IACrB,WAAW,qBAAqB,OAAO,SAAS;AAAA,IAChD,QAAQ,OAAO;AAAA,EACjB;AACF;AAGO,SAAS,2BAA+C;AAC7D,QAAM,WAAW,oBAAI,IAAoB;AACzC,SAAO,CAAC,iBAAiC;AACvC,UAAM,MAAM,aAAa,YAAY;AACrC,UAAM,QAAQ,SAAS,IAAI,GAAG,KAAK,MAAM;AACzC,aAAS,IAAI,KAAK,IAAI;AACtB,WAAO;AAAA,EACT;AACF;AASA,eAAsB,sBAAsB,QAIV;AAChC,QAAM,EAAE,cAAc,UAAU,OAAO,IAAI;AAC3C,QAAM,cAAc,OAAO,eAAe,yBAAyB;AACnE,QAAM,eAAe;AAAA,IACnB,SAAS,gBAAiB,MAAM,YAAY,YAAY;AAAA,EAC1D;AACA,QAAM,QAAS,SAAS,SAAS;AACjC,QAAM,OAAO,SAAS;AACtB,QAAM,SAAS,OAAO,SAAS,MAAM;AAErC,QAAM,YAAY,MAAM,OAAO,cAAc;AAAA,IAC3C,QAAQ,qBAAqB,OAAO,SAAS,OAAO,cAAc;AAAA,IAClE,OAAO;AAAA,IACP,aAAa;AAAA,IACb,SAAS;AAAA,MACP;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF,CAAC;AAED,QAAM,SAAS,MAAM,OAAO,OAAO,SAAS;AAAA,IAC1C;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,QAAQ,OAAO,SAAS;AAAA,IACxB,cAAc,aAAa,SAAS;AAAA,IACpC;AAAA,IACA,cAAc,SAAS;AAAA,EACzB,CAAC;AAED,SAAO,uBAAuB,MAAM;AACtC;","names":[]}
+{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * grant's data-access fee through the escrow gateway:\n *\n *  1. Sign a `GenericPayment` EIP-712 message (op `\"grant\"`, opId = grantId)\n *     with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module adapts the escrow `payForOp` flow to the direct-read use case; it\n * does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface GrantPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedGrantPayment {\n  message: GrantPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedGrantPayment;\n}\n\n/** Escrow settlement configuration for the controller. */\nexport interface EscrowPaymentConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<SignedGrantPayment> {\n  const { payerAddress, required, config } = params;\n  const nonceSource = config.nonceSource ?? createDefaultNonceSource();\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.grantId as `0x${string}`;\n  const amount = BigInt(required.amount);\n\n  const message = {\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  const signed = await signGrantPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network: params.required.network ?? `vana:${params.config.chainId}`,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentReceipt | undefined {\n  if (!header) return undefined;\n  try {\n    return toDirectPaymentReceipt(base64DecodeJson(header) as EscrowPayResult);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, required, config } = params;\n  const signed = await signGrantPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: required.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}

package/dist/direct/personal-server-read.cjs

@@ -126,6 +126,7 @@ async function parsePersonalServerPaymentRequired(res, grantId) {
   const amountValue = stringField(message, "amount") ?? stringField(body, "amount") ?? stringField(body, "maxAmountRequired") ?? "0";
   return {
     grantId,
+    network: stringField(accept, "network") ?? stringField(body, "network"),
     paymentNonce: stringField(message, "paymentNonce") ?? stringField(body, "paymentNonce"),
     accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),
     asset: stringField(message, "asset") ?? stringField(body, "asset") ?? import_escrow.NATIVE_ASSET_ADDRESS,
@@ -182,7 +183,7 @@ async function readPersonalServerData(params) {
         }
       );
     }
-    payment = await (0, import_escrow_payment.authorizeGrantPayment)({
+    const paymentHeader = await (0, import_escrow_payment.buildGrantPaymentHeader)({
       payerAddress: params.payerAddress,
       required,
       config: params.escrow
@@ -195,7 +196,7 @@ async function readPersonalServerData(params) {
     });
     res = await fetchFn(retry.url, {
       method: retry.method,
-      headers: retry.headers
+      headers: { ...retry.headers, "X-PAYMENT": paymentHeader }
     });
     if (res.status === 402) {
       throw new import_errors.PaymentRequiredError(
@@ -218,6 +219,7 @@ async function readPersonalServerData(params) {
       { scope: params.scope, body: detail.slice(0, 500) }
     );
   }
+  payment = (0, import_escrow_payment.paymentReceiptFromHeader)(res.headers.get("X-PAYMENT-RESPONSE"));
   return { data: await res.json(), payment };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/direct/personal-server-read.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — settles the grant's data-access fee through\n * the DPv2 escrow gateway and retries once.\n *\n * The 402 body is parsed into a {@link PersonalServerPaymentRequired} (grant id,\n * asset, and amount owed), which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  authorizeGrantPayment,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/** Outcome of {@link readPersonalServerData}: the payload plus optional receipt. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /** Present only when this read required (and settled) a payment. */\n  payment?: DirectPaymentReceipt;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nfunction assertChallengeMatchesGrant(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): void {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  if (challengeOpType && challengeOpType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const challengedGrantId = challengeOpId ?? challengeGrantId;\n  if (!challengedGrantId) return;\n\n  if (!isBytes32Hex(challengedGrantId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId: challengedGrantId },\n    );\n  }\n\n  if (challengedGrantId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId: challengedGrantId, grantId },\n    );\n  }\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a {@link PersonalServerPaymentRequired}.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentRequired> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  const accept =\n    Array.isArray(body.accepts) && body.accepts.length > 0\n      ? asRecord(body.accepts[0])\n      : undefined;\n  const message = asRecord(accept?.message);\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId =\n    stringField(message, \"opId\") ?? stringField(body, \"opId\");\n  const challengeOpType =\n    stringField(message, \"opType\") ?? stringField(body, \"opType\");\n\n  assertChallengeMatchesGrant({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(message, \"amount\") ??\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  return {\n    grantId,\n    paymentNonce:\n      stringField(message, \"paymentNonce\") ?? stringField(body, \"paymentNonce\"),\n    accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),\n    asset:\n      stringField(message, \"asset\") ??\n      stringField(body, \"asset\") ??\n      NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes an escrow payment for the grant via `escrow`, and retries\n * once. If escrow is not configured, throws {@link PaymentRequiredError} carrying\n * the parsed requirement so callers can debug amount/asset.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentConfig;\n  fetchFn?: PersonalServerFetch;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n\n  const initial = await buildPersonalServerDataReadRequest({\n    personalServerUrl: params.personalServerUrl,\n    scope: params.scope,\n    grantId: params.grantId,\n    signMessage: params.signMessage,\n  });\n\n  let res = await fetchFn(initial.url, {\n    method: initial.method,\n    headers: initial.headers,\n  });\n\n  let payment: DirectPaymentReceipt | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (!hasPositiveAmount(required.amount)) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge did not include a positive amount\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    payment = await authorizeGrantPayment({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry after the escrow gateway accepts the payment.\n    const retry = await buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n    res = await fetchFn(retry.url, {\n      method: retry.method,\n      headers: retry.headers,\n    });\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  return { data: await res.json(), payment };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — settles the grant's data-access fee through\n * the DPv2 escrow gateway and retries once.\n *\n * The 402 body is parsed into a {@link PersonalServerPaymentRequired} (grant id,\n * asset, and amount owed), which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildGrantPaymentHeader,\n  GRANT_OP_TYPE,\n  paymentReceiptFromHeader,\n  type EscrowPaymentConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/** Outcome of {@link readPersonalServerData}: the payload plus optional receipt. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /** Present only when this read required (and settled) a payment. */\n  payment?: DirectPaymentReceipt;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nfunction assertChallengeMatchesGrant(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): void {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  if (challengeOpType && challengeOpType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const challengedGrantId = challengeOpId ?? challengeGrantId;\n  if (!challengedGrantId) return;\n\n  if (!isBytes32Hex(challengedGrantId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId: challengedGrantId },\n    );\n  }\n\n  if (challengedGrantId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId: challengedGrantId, grantId },\n    );\n  }\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a {@link PersonalServerPaymentRequired}.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentRequired> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  const accept =\n    Array.isArray(body.accepts) && body.accepts.length > 0\n      ? asRecord(body.accepts[0])\n      : undefined;\n  const message = asRecord(accept?.message);\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId =\n    stringField(message, \"opId\") ?? stringField(body, \"opId\");\n  const challengeOpType =\n    stringField(message, \"opType\") ?? stringField(body, \"opType\");\n\n  assertChallengeMatchesGrant({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(message, \"amount\") ??\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  return {\n    grantId,\n    network: stringField(accept, \"network\") ?? stringField(body, \"network\"),\n    paymentNonce:\n      stringField(message, \"paymentNonce\") ?? stringField(body, \"paymentNonce\"),\n    accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),\n    asset:\n      stringField(message, \"asset\") ??\n      stringField(body, \"asset\") ??\n      NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes an escrow payment for the grant via `escrow`, and retries\n * once. If escrow is not configured, throws {@link PaymentRequiredError} carrying\n * the parsed requirement so callers can debug amount/asset.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentConfig;\n  fetchFn?: PersonalServerFetch;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n\n  const initial = await buildPersonalServerDataReadRequest({\n    personalServerUrl: params.personalServerUrl,\n    scope: params.scope,\n    grantId: params.grantId,\n    signMessage: params.signMessage,\n  });\n\n  let res = await fetchFn(initial.url, {\n    method: initial.method,\n    headers: initial.headers,\n  });\n\n  let payment: DirectPaymentReceipt | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (!hasPositiveAmount(required.amount)) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge did not include a positive amount\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildGrantPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to validate.\n    const retry = await buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n    res = await fetchFn(retry.url, {\n      method: retry.method,\n      headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n    });\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentReceiptFromHeader(res.headers.get(\"X-PAYMENT-RESPONSE\"));\n  return { data: await res.json(), payment };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/personal-server-read.js

@@ -3,8 +3,9 @@ import {
   NATIVE_ASSET_ADDRESS
 } from "../protocol/escrow.js";
 import {
-  authorizeGrantPayment,
-  GRANT_OP_TYPE
+  buildGrantPaymentHeader,
+  GRANT_OP_TYPE,
+  paymentReceiptFromHeader
 } from "./escrow-payment.js";
 import { PaymentRequiredError, PersonalServerReadError } from "./errors.js";
 function stripTrailingSlash(url) {
@@ -105,6 +106,7 @@ async function parsePersonalServerPaymentRequired(res, grantId) {
   const amountValue = stringField(message, "amount") ?? stringField(body, "amount") ?? stringField(body, "maxAmountRequired") ?? "0";
   return {
     grantId,
+    network: stringField(accept, "network") ?? stringField(body, "network"),
     paymentNonce: stringField(message, "paymentNonce") ?? stringField(body, "paymentNonce"),
     accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),
     asset: stringField(message, "asset") ?? stringField(body, "asset") ?? NATIVE_ASSET_ADDRESS,
@@ -161,7 +163,7 @@ async function readPersonalServerData(params) {
         }
       );
     }
-    payment = await authorizeGrantPayment({
+    const paymentHeader = await buildGrantPaymentHeader({
       payerAddress: params.payerAddress,
       required,
       config: params.escrow
@@ -174,7 +176,7 @@ async function readPersonalServerData(params) {
     });
     res = await fetchFn(retry.url, {
       method: retry.method,
-      headers: retry.headers
+      headers: { ...retry.headers, "X-PAYMENT": paymentHeader }
     });
     if (res.status === 402) {
       throw new PaymentRequiredError(
@@ -197,6 +199,7 @@ async function readPersonalServerData(params) {
       { scope: params.scope, body: detail.slice(0, 500) }
     );
   }
+  payment = paymentReceiptFromHeader(res.headers.get("X-PAYMENT-RESPONSE"));
   return { data: await res.json(), payment };
 }
 export {

package/dist/direct/personal-server-read.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — settles the grant's data-access fee through\n * the DPv2 escrow gateway and retries once.\n *\n * The 402 body is parsed into a {@link PersonalServerPaymentRequired} (grant id,\n * asset, and amount owed), which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  authorizeGrantPayment,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/** Outcome of {@link readPersonalServerData}: the payload plus optional receipt. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /** Present only when this read required (and settled) a payment. */\n  payment?: DirectPaymentReceipt;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nfunction assertChallengeMatchesGrant(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): void {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  if (challengeOpType && challengeOpType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const challengedGrantId = challengeOpId ?? challengeGrantId;\n  if (!challengedGrantId) return;\n\n  if (!isBytes32Hex(challengedGrantId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId: challengedGrantId },\n    );\n  }\n\n  if (challengedGrantId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId: challengedGrantId, grantId },\n    );\n  }\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a {@link PersonalServerPaymentRequired}.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentRequired> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  const accept =\n    Array.isArray(body.accepts) && body.accepts.length > 0\n      ? asRecord(body.accepts[0])\n      : undefined;\n  const message = asRecord(accept?.message);\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId =\n    stringField(message, \"opId\") ?? stringField(body, \"opId\");\n  const challengeOpType =\n    stringField(message, \"opType\") ?? stringField(body, \"opType\");\n\n  assertChallengeMatchesGrant({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(message, \"amount\") ??\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  return {\n    grantId,\n    paymentNonce:\n      stringField(message, \"paymentNonce\") ?? stringField(body, \"paymentNonce\"),\n    accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),\n    asset:\n      stringField(message, \"asset\") ??\n      stringField(body, \"asset\") ??\n      NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes an escrow payment for the grant via `escrow`, and retries\n * once. If escrow is not configured, throws {@link PaymentRequiredError} carrying\n * the parsed requirement so callers can debug amount/asset.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentConfig;\n  fetchFn?: PersonalServerFetch;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n\n  const initial = await buildPersonalServerDataReadRequest({\n    personalServerUrl: params.personalServerUrl,\n    scope: params.scope,\n    grantId: params.grantId,\n    signMessage: params.signMessage,\n  });\n\n  let res = await fetchFn(initial.url, {\n    method: initial.method,\n    headers: initial.headers,\n  });\n\n  let payment: DirectPaymentReceipt | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (!hasPositiveAmount(required.amount)) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge did not include a positive amount\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    payment = await authorizeGrantPayment({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry after the escrow gateway accepts the payment.\n    const retry = await buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n    res = await fetchFn(retry.url, {\n      method: retry.method,\n      headers: retry.headers,\n    });\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  return { data: await res.json(), payment };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — settles the grant's data-access fee through\n * the DPv2 escrow gateway and retries once.\n *\n * The 402 body is parsed into a {@link PersonalServerPaymentRequired} (grant id,\n * asset, and amount owed), which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildGrantPaymentHeader,\n  GRANT_OP_TYPE,\n  paymentReceiptFromHeader,\n  type EscrowPaymentConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/** Outcome of {@link readPersonalServerData}: the payload plus optional receipt. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /** Present only when this read required (and settled) a payment. */\n  payment?: DirectPaymentReceipt;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nfunction assertChallengeMatchesGrant(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): void {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  if (challengeOpType && challengeOpType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const challengedGrantId = challengeOpId ?? challengeGrantId;\n  if (!challengedGrantId) return;\n\n  if (!isBytes32Hex(challengedGrantId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId: challengedGrantId },\n    );\n  }\n\n  if (challengedGrantId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId: challengedGrantId, grantId },\n    );\n  }\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a {@link PersonalServerPaymentRequired}.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentRequired> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  const accept =\n    Array.isArray(body.accepts) && body.accepts.length > 0\n      ? asRecord(body.accepts[0])\n      : undefined;\n  const message = asRecord(accept?.message);\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId =\n    stringField(message, \"opId\") ?? stringField(body, \"opId\");\n  const challengeOpType =\n    stringField(message, \"opType\") ?? stringField(body, \"opType\");\n\n  assertChallengeMatchesGrant({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(message, \"amount\") ??\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  return {\n    grantId,\n    network: stringField(accept, \"network\") ?? stringField(body, \"network\"),\n    paymentNonce:\n      stringField(message, \"paymentNonce\") ?? stringField(body, \"paymentNonce\"),\n    accessRecord: parseAccessRecord(accept?.accessRecord ?? body.accessRecord),\n    asset:\n      stringField(message, \"asset\") ??\n      stringField(body, \"asset\") ??\n      NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes an escrow payment for the grant via `escrow`, and retries\n * once. If escrow is not configured, throws {@link PaymentRequiredError} carrying\n * the parsed requirement so callers can debug amount/asset.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentConfig;\n  fetchFn?: PersonalServerFetch;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n\n  const initial = await buildPersonalServerDataReadRequest({\n    personalServerUrl: params.personalServerUrl,\n    scope: params.scope,\n    grantId: params.grantId,\n    signMessage: params.signMessage,\n  });\n\n  let res = await fetchFn(initial.url, {\n    method: initial.method,\n    headers: initial.headers,\n  });\n\n  let payment: DirectPaymentReceipt | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (!hasPositiveAmount(required.amount)) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge did not include a positive amount\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildGrantPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to validate.\n    const retry = await buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n    res = await fetchFn(retry.url, {\n      method: retry.method,\n      headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n    });\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentReceiptFromHeader(res.headers.get(\"X-PAYMENT-RESPONSE\"));\n  return { data: await res.json(), payment };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\n\n/**\n * Shared types for the Direct Data Controller and the browser connect helper.\n *\n * @remarks\n * These types describe the \"two-tab\" Data Portability flow documented in the\n * builder guide: a backend controller creates an access request, the browser\n * opens Vana for user approval, and the backend reads the approved data from\n * the user's Personal Server (handling 402 Payment Required).\n *\n * @category Direct\n * @module direct/types\n */\n\n/**\n * Target environment for a {@link DirectDataController}.\n *\n * - `\"production\"` — Vana mainnet stack (default service URLs).\n * - `\"dev\"` — Vana internal dev/testnet stack. Use only when testing against\n *   Vana's dev infrastructure.\n */\nexport type DirectEnv = \"dev\" | \"production\";\n\n/**\n * App identity advertised to users during approval and attributed in Builder\n * League activity reports.\n */\nexport interface DirectAppConfig {\n  /** Stable, human-readable app id (e.g. `\"notes-lens\"`). */\n  id: string;\n  /** Display name shown to the user in the Vana approval UI. */\n  name: string;\n  /** Public homepage URL for the app. */\n  homepageUrl: string;\n}\n\n/**\n * Resolved app identity: the configured {@link DirectAppConfig} plus the app's\n * derived on-chain address (the address to fund and inspect).\n */\nexport interface AppIdentity extends DirectAppConfig {\n  /** The app's `0x`-prefixed on-chain address (derived from `appPrivateKey`). */\n  address: string;\n}\n\n/**\n * Resolved service URLs for a given {@link DirectEnv}.\n *\n * @remarks\n * Centralizes the per-environment base URLs the controller talks to. Each can\n * be overridden via {@link DirectDataControllerConfig.endpoints} when pointing\n * at a non-standard deployment.\n */\nexport interface DirectServiceEndpoints {\n  /** Vana chain id for this environment (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** Base URL of the Vana Account access-request API that issues `dcr_*` ids. */\n  accessRequestBaseUrl: string;\n  /** Base URL users are sent to for approval (the Vana app). */\n  approvalAppBaseUrl: string;\n}\n\n/** Result of {@link DirectDataController.createAccessRequest}. */\nexport interface AccessRequest {\n  /** Opaque request id (e.g. `\"dcr_123\"`). */\n  requestId: string;\n  /** URL the browser opens so the user can approve the requested scopes. */\n  approvalUrl: string;\n  /** On-chain address of the (registered or reused) app. */\n  appAddress: string;\n}\n\n/** Lifecycle status of an access request. */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"denied\"\n  | \"expired\";\n\n/** Result of {@link DirectDataController.getAccessRequestStatus}. */\nexport interface AccessRequestStatus {\n  /** Current lifecycle status of the request. */\n  status: AccessRequestStatusValue;\n  /** Personal Server base URL — present once `status === \"approved\"`. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once approved. */\n  grantId?: string;\n  /** The approved scope — present once approved. */\n  scope?: string;\n}\n\n/** Result of {@link DirectDataController.readApprovedData}. */\nexport interface ApprovedDataResult<T = unknown> {\n  /** The scope the data was read for. */\n  scope: string;\n  /** The decoded payload returned by the Personal Server. */\n  data: T;\n  /**\n   * Payment receipt — present only when this read required (and settled) a\n   * payment. Lets builders inspect the amount, asset, and fee breakdown without\n   * digging into the underlying 402/escrow exchange. Reads served from a paid-up\n   * grant omit this field.\n   */\n  payment?: DirectPaymentReceipt;\n}\n\n/**\n * Client for the Vana Account access-request API — the service that turns a\n * registered app + scopes into a `dcr_*` id and approval URL.\n *\n * @remarks\n * The controller uses a default client against the Vana Account endpoints. You\n * can inject your own implementation to point at a custom deployment or to\n * supply a test double.\n */\nexport interface AccessRequestClient {\n  /**\n   * Create an access request for the given app + scopes.\n   *\n   * @param input - App identity, source, scopes, and the post-approval return URL.\n   * @returns The created {@link AccessRequest}.\n   */\n  createAccessRequest(input: {\n    appAddress: string;\n    app: DirectAppConfig;\n    source: string;\n    scopes: string[];\n    returnUrl: string;\n  }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of a previously created access request.\n   *\n   * @param requestId - The `dcr_*` id returned by {@link AccessRequestClient.createAccessRequest}.\n   * @returns The current {@link AccessRequestStatus}.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n}\n\n/**\n * Op-type vocabulary used by the DPv2 escrow payment surface.\n *\n * @remarks\n * These are the operations the gateway prices and settles via\n * `POST /v1/escrow/pay` (`opType` field of the `GenericPayment` message). A\n * direct data read settles the {@link DirectOpType.DataAccess} op for the\n * approved grant; the other op types are listed here for completeness and to\n * give builders a typed vocabulary when inspecting fee breakdowns.\n *\n * Note: the escrow `GenericPayment` `opType` is currently `\"grant\"` on the wire\n * for grant lifecycle payments; this enum names the higher-level fee categories\n * the gateway reports in a {@link PaymentBreakdown}.\n */\nexport const DirectOpType = {\n  GrantRegistration: \"grant_registration\",\n  DataAccess: \"data_access\",\n  DataRegistration: \"data_registration\",\n  ServerRegistration: \"server_registration\",\n  BuilderRegistration: \"builder_registration\",\n} as const;\n\n/** A direct-flow op type (see {@link DirectOpType}). */\nexport type DirectOpTypeValue =\n  (typeof DirectOpType)[keyof typeof DirectOpType];\n\n/**\n * What a Personal Server `402 Payment Required` tells the controller is owed for\n * a data read.\n *\n * @remarks\n * The PS read 402 body identifies the grant to settle and the amount/asset. The\n * controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The full\n * unmodified body is preserved under {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id to settle (the escrow `opId`). Defaults to the read's grantId. */\n  grantId: string;\n  /** Payment nonce requested by the 402 challenge. */\n  paymentNonce?: string;\n  /** Server-signed data access receipt requested by the 402 challenge. */\n  accessRecord?: EscrowAccessRecord;\n  /** Asset address owed (zero address = native VANA). */\n  asset: string;\n  /** Amount owed, as a decimal base-unit string (preserves uint256 precision). */\n  amount: string;\n  /** The full, unmodified 402 response body. */\n  raw: unknown;\n}\n\n/**\n * Structured payment metadata attached to a successful paid read.\n *\n * @remarks\n * Derived from the gateway's {@link EscrowPayResult}. Lets builders debug the\n * amount, asset, and per-op fee breakdown without re-deriving anything from the\n * raw 402/payment exchange.\n */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (the grant id). */\n  opId: string;\n  /** Asset paid in (zero address = native VANA). */\n  asset: string;\n  /** Total amount paid, as a decimal base-unit string. */\n  amount: string;\n  /** Payment nonce used for this settlement. */\n  paymentNonce: string;\n  /** Fee breakdown reported by the gateway (registration vs data-access fee). */\n  breakdown: DirectFeeBreakdown;\n  /** ISO timestamp the gateway recorded the payment. */\n  paidAt: string;\n}\n\n/**\n * Per-op fee breakdown reported by the gateway.\n *\n * @remarks\n * Mirrors the escrow {@link PaymentBreakdown}: a one-time registration fee plus\n * the per-read data-access fee, and whether this settlement covered the\n * registration fee.\n */\nexport interface DirectFeeBreakdown {\n  /** One-time registration fee for the op, as a decimal base-unit string. */\n  registrationFee: string;\n  /** Per-read data-access fee, as a decimal base-unit string. */\n  dataAccessFee: string;\n  /** True when this settlement paid the registration fee. */\n  registrationPaid: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA0JO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}
+{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\n\n/**\n * Shared types for the Direct Data Controller and the browser connect helper.\n *\n * @remarks\n * These types describe the \"two-tab\" Data Portability flow documented in the\n * builder guide: a backend controller creates an access request, the browser\n * opens Vana for user approval, and the backend reads the approved data from\n * the user's Personal Server (handling 402 Payment Required).\n *\n * @category Direct\n * @module direct/types\n */\n\n/**\n * Target environment for a {@link DirectDataController}.\n *\n * - `\"production\"` — Vana mainnet stack (default service URLs).\n * - `\"dev\"` — Vana internal dev/testnet stack. Use only when testing against\n *   Vana's dev infrastructure.\n */\nexport type DirectEnv = \"dev\" | \"production\";\n\n/**\n * App identity advertised to users during approval and attributed in Builder\n * League activity reports.\n */\nexport interface DirectAppConfig {\n  /** Stable, human-readable app id (e.g. `\"notes-lens\"`). */\n  id: string;\n  /** Display name shown to the user in the Vana approval UI. */\n  name: string;\n  /** Public homepage URL for the app. */\n  homepageUrl: string;\n}\n\n/**\n * Resolved app identity: the configured {@link DirectAppConfig} plus the app's\n * derived on-chain address (the address to fund and inspect).\n */\nexport interface AppIdentity extends DirectAppConfig {\n  /** The app's `0x`-prefixed on-chain address (derived from `appPrivateKey`). */\n  address: string;\n}\n\n/**\n * Resolved service URLs for a given {@link DirectEnv}.\n *\n * @remarks\n * Centralizes the per-environment base URLs the controller talks to. Each can\n * be overridden via {@link DirectDataControllerConfig.endpoints} when pointing\n * at a non-standard deployment.\n */\nexport interface DirectServiceEndpoints {\n  /** Vana chain id for this environment (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** Base URL of the Vana Account access-request API that issues `dcr_*` ids. */\n  accessRequestBaseUrl: string;\n  /** Base URL users are sent to for approval (the Vana app). */\n  approvalAppBaseUrl: string;\n}\n\n/** Result of {@link DirectDataController.createAccessRequest}. */\nexport interface AccessRequest {\n  /** Opaque request id (e.g. `\"dcr_123\"`). */\n  requestId: string;\n  /** URL the browser opens so the user can approve the requested scopes. */\n  approvalUrl: string;\n  /** On-chain address of the (registered or reused) app. */\n  appAddress: string;\n}\n\n/** Lifecycle status of an access request. */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"denied\"\n  | \"expired\";\n\n/** Result of {@link DirectDataController.getAccessRequestStatus}. */\nexport interface AccessRequestStatus {\n  /** Current lifecycle status of the request. */\n  status: AccessRequestStatusValue;\n  /** Personal Server base URL — present once `status === \"approved\"`. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once approved. */\n  grantId?: string;\n  /** The approved scope — present once approved. */\n  scope?: string;\n}\n\n/** Result of {@link DirectDataController.readApprovedData}. */\nexport interface ApprovedDataResult<T = unknown> {\n  /** The scope the data was read for. */\n  scope: string;\n  /** The decoded payload returned by the Personal Server. */\n  data: T;\n  /**\n   * Payment receipt — present only when this read required (and settled) a\n   * payment. Lets builders inspect the amount, asset, and fee breakdown without\n   * digging into the underlying 402/escrow exchange. Reads served from a paid-up\n   * grant omit this field.\n   */\n  payment?: DirectPaymentReceipt;\n}\n\n/**\n * Client for the Vana Account access-request API — the service that turns a\n * registered app + scopes into a `dcr_*` id and approval URL.\n *\n * @remarks\n * The controller uses a default client against the Vana Account endpoints. You\n * can inject your own implementation to point at a custom deployment or to\n * supply a test double.\n */\nexport interface AccessRequestClient {\n  /**\n   * Create an access request for the given app + scopes.\n   *\n   * @param input - App identity, source, scopes, and the post-approval return URL.\n   * @returns The created {@link AccessRequest}.\n   */\n  createAccessRequest(input: {\n    appAddress: string;\n    app: DirectAppConfig;\n    source: string;\n    scopes: string[];\n    returnUrl: string;\n  }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of a previously created access request.\n   *\n   * @param requestId - The `dcr_*` id returned by {@link AccessRequestClient.createAccessRequest}.\n   * @returns The current {@link AccessRequestStatus}.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n}\n\n/**\n * Op-type vocabulary used by the DPv2 escrow payment surface.\n *\n * @remarks\n * These are the operations the gateway prices and settles via\n * `POST /v1/escrow/pay` (`opType` field of the `GenericPayment` message). A\n * direct data read settles the {@link DirectOpType.DataAccess} op for the\n * approved grant; the other op types are listed here for completeness and to\n * give builders a typed vocabulary when inspecting fee breakdowns.\n *\n * Note: the escrow `GenericPayment` `opType` is currently `\"grant\"` on the wire\n * for grant lifecycle payments; this enum names the higher-level fee categories\n * the gateway reports in a {@link PaymentBreakdown}.\n */\nexport const DirectOpType = {\n  GrantRegistration: \"grant_registration\",\n  DataAccess: \"data_access\",\n  DataRegistration: \"data_registration\",\n  ServerRegistration: \"server_registration\",\n  BuilderRegistration: \"builder_registration\",\n} as const;\n\n/** A direct-flow op type (see {@link DirectOpType}). */\nexport type DirectOpTypeValue =\n  (typeof DirectOpType)[keyof typeof DirectOpType];\n\n/**\n * What a Personal Server `402 Payment Required` tells the controller is owed for\n * a data read.\n *\n * @remarks\n * The PS read 402 body identifies the grant to settle and the amount/asset. The\n * controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The full\n * unmodified body is preserved under {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id to settle (the escrow `opId`). Defaults to the read's grantId. */\n  grantId: string;\n  /** X402 network advertised by the Personal Server challenge. */\n  network?: string;\n  /** Payment nonce requested by the 402 challenge. */\n  paymentNonce?: string;\n  /** Server-signed data access receipt requested by the 402 challenge. */\n  accessRecord?: EscrowAccessRecord;\n  /** Asset address owed (zero address = native VANA). */\n  asset: string;\n  /** Amount owed, as a decimal base-unit string (preserves uint256 precision). */\n  amount: string;\n  /** The full, unmodified 402 response body. */\n  raw: unknown;\n}\n\n/**\n * Structured payment metadata attached to a successful paid read.\n *\n * @remarks\n * Derived from the gateway's {@link EscrowPayResult}. Lets builders debug the\n * amount, asset, and per-op fee breakdown without re-deriving anything from the\n * raw 402/payment exchange.\n */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (the grant id). */\n  opId: string;\n  /** Asset paid in (zero address = native VANA). */\n  asset: string;\n  /** Total amount paid, as a decimal base-unit string. */\n  amount: string;\n  /** Payment nonce used for this settlement. */\n  paymentNonce: string;\n  /** Fee breakdown reported by the gateway (registration vs data-access fee). */\n  breakdown: DirectFeeBreakdown;\n  /** ISO timestamp the gateway recorded the payment. */\n  paidAt: string;\n}\n\n/**\n * Per-op fee breakdown reported by the gateway.\n *\n * @remarks\n * Mirrors the escrow {@link PaymentBreakdown}: a one-time registration fee plus\n * the per-read data-access fee, and whether this settlement covered the\n * registration fee.\n */\nexport interface DirectFeeBreakdown {\n  /** One-time registration fee for the op, as a decimal base-unit string. */\n  registrationFee: string;\n  /** Per-read data-access fee, as a decimal base-unit string. */\n  dataAccessFee: string;\n  /** True when this settlement paid the registration fee. */\n  registrationPaid: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA0JO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}

package/dist/direct/types.d.ts

@@ -157,6 +157,8 @@ export type DirectOpTypeValue = (typeof DirectOpType)[keyof typeof DirectOpType]
 export interface PersonalServerPaymentRequired {
     /** Grant id to settle (the escrow `opId`). Defaults to the read's grantId. */
     grantId: string;
+    /** X402 network advertised by the Personal Server challenge. */
+    network?: string;
     /** Payment nonce requested by the 402 challenge. */
     paymentNonce?: string;
     /** Server-signed data access receipt requested by the 402 challenge. */

package/dist/direct/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\n\n/**\n * Shared types for the Direct Data Controller and the browser connect helper.\n *\n * @remarks\n * These types describe the \"two-tab\" Data Portability flow documented in the\n * builder guide: a backend controller creates an access request, the browser\n * opens Vana for user approval, and the backend reads the approved data from\n * the user's Personal Server (handling 402 Payment Required).\n *\n * @category Direct\n * @module direct/types\n */\n\n/**\n * Target environment for a {@link DirectDataController}.\n *\n * - `\"production\"` — Vana mainnet stack (default service URLs).\n * - `\"dev\"` — Vana internal dev/testnet stack. Use only when testing against\n *   Vana's dev infrastructure.\n */\nexport type DirectEnv = \"dev\" | \"production\";\n\n/**\n * App identity advertised to users during approval and attributed in Builder\n * League activity reports.\n */\nexport interface DirectAppConfig {\n  /** Stable, human-readable app id (e.g. `\"notes-lens\"`). */\n  id: string;\n  /** Display name shown to the user in the Vana approval UI. */\n  name: string;\n  /** Public homepage URL for the app. */\n  homepageUrl: string;\n}\n\n/**\n * Resolved app identity: the configured {@link DirectAppConfig} plus the app's\n * derived on-chain address (the address to fund and inspect).\n */\nexport interface AppIdentity extends DirectAppConfig {\n  /** The app's `0x`-prefixed on-chain address (derived from `appPrivateKey`). */\n  address: string;\n}\n\n/**\n * Resolved service URLs for a given {@link DirectEnv}.\n *\n * @remarks\n * Centralizes the per-environment base URLs the controller talks to. Each can\n * be overridden via {@link DirectDataControllerConfig.endpoints} when pointing\n * at a non-standard deployment.\n */\nexport interface DirectServiceEndpoints {\n  /** Vana chain id for this environment (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** Base URL of the Vana Account access-request API that issues `dcr_*` ids. */\n  accessRequestBaseUrl: string;\n  /** Base URL users are sent to for approval (the Vana app). */\n  approvalAppBaseUrl: string;\n}\n\n/** Result of {@link DirectDataController.createAccessRequest}. */\nexport interface AccessRequest {\n  /** Opaque request id (e.g. `\"dcr_123\"`). */\n  requestId: string;\n  /** URL the browser opens so the user can approve the requested scopes. */\n  approvalUrl: string;\n  /** On-chain address of the (registered or reused) app. */\n  appAddress: string;\n}\n\n/** Lifecycle status of an access request. */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"denied\"\n  | \"expired\";\n\n/** Result of {@link DirectDataController.getAccessRequestStatus}. */\nexport interface AccessRequestStatus {\n  /** Current lifecycle status of the request. */\n  status: AccessRequestStatusValue;\n  /** Personal Server base URL — present once `status === \"approved\"`. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once approved. */\n  grantId?: string;\n  /** The approved scope — present once approved. */\n  scope?: string;\n}\n\n/** Result of {@link DirectDataController.readApprovedData}. */\nexport interface ApprovedDataResult<T = unknown> {\n  /** The scope the data was read for. */\n  scope: string;\n  /** The decoded payload returned by the Personal Server. */\n  data: T;\n  /**\n   * Payment receipt — present only when this read required (and settled) a\n   * payment. Lets builders inspect the amount, asset, and fee breakdown without\n   * digging into the underlying 402/escrow exchange. Reads served from a paid-up\n   * grant omit this field.\n   */\n  payment?: DirectPaymentReceipt;\n}\n\n/**\n * Client for the Vana Account access-request API — the service that turns a\n * registered app + scopes into a `dcr_*` id and approval URL.\n *\n * @remarks\n * The controller uses a default client against the Vana Account endpoints. You\n * can inject your own implementation to point at a custom deployment or to\n * supply a test double.\n */\nexport interface AccessRequestClient {\n  /**\n   * Create an access request for the given app + scopes.\n   *\n   * @param input - App identity, source, scopes, and the post-approval return URL.\n   * @returns The created {@link AccessRequest}.\n   */\n  createAccessRequest(input: {\n    appAddress: string;\n    app: DirectAppConfig;\n    source: string;\n    scopes: string[];\n    returnUrl: string;\n  }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of a previously created access request.\n   *\n   * @param requestId - The `dcr_*` id returned by {@link AccessRequestClient.createAccessRequest}.\n   * @returns The current {@link AccessRequestStatus}.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n}\n\n/**\n * Op-type vocabulary used by the DPv2 escrow payment surface.\n *\n * @remarks\n * These are the operations the gateway prices and settles via\n * `POST /v1/escrow/pay` (`opType` field of the `GenericPayment` message). A\n * direct data read settles the {@link DirectOpType.DataAccess} op for the\n * approved grant; the other op types are listed here for completeness and to\n * give builders a typed vocabulary when inspecting fee breakdowns.\n *\n * Note: the escrow `GenericPayment` `opType` is currently `\"grant\"` on the wire\n * for grant lifecycle payments; this enum names the higher-level fee categories\n * the gateway reports in a {@link PaymentBreakdown}.\n */\nexport const DirectOpType = {\n  GrantRegistration: \"grant_registration\",\n  DataAccess: \"data_access\",\n  DataRegistration: \"data_registration\",\n  ServerRegistration: \"server_registration\",\n  BuilderRegistration: \"builder_registration\",\n} as const;\n\n/** A direct-flow op type (see {@link DirectOpType}). */\nexport type DirectOpTypeValue =\n  (typeof DirectOpType)[keyof typeof DirectOpType];\n\n/**\n * What a Personal Server `402 Payment Required` tells the controller is owed for\n * a data read.\n *\n * @remarks\n * The PS read 402 body identifies the grant to settle and the amount/asset. The\n * controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The full\n * unmodified body is preserved under {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id to settle (the escrow `opId`). Defaults to the read's grantId. */\n  grantId: string;\n  /** Payment nonce requested by the 402 challenge. */\n  paymentNonce?: string;\n  /** Server-signed data access receipt requested by the 402 challenge. */\n  accessRecord?: EscrowAccessRecord;\n  /** Asset address owed (zero address = native VANA). */\n  asset: string;\n  /** Amount owed, as a decimal base-unit string (preserves uint256 precision). */\n  amount: string;\n  /** The full, unmodified 402 response body. */\n  raw: unknown;\n}\n\n/**\n * Structured payment metadata attached to a successful paid read.\n *\n * @remarks\n * Derived from the gateway's {@link EscrowPayResult}. Lets builders debug the\n * amount, asset, and per-op fee breakdown without re-deriving anything from the\n * raw 402/payment exchange.\n */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (the grant id). */\n  opId: string;\n  /** Asset paid in (zero address = native VANA). */\n  asset: string;\n  /** Total amount paid, as a decimal base-unit string. */\n  amount: string;\n  /** Payment nonce used for this settlement. */\n  paymentNonce: string;\n  /** Fee breakdown reported by the gateway (registration vs data-access fee). */\n  breakdown: DirectFeeBreakdown;\n  /** ISO timestamp the gateway recorded the payment. */\n  paidAt: string;\n}\n\n/**\n * Per-op fee breakdown reported by the gateway.\n *\n * @remarks\n * Mirrors the escrow {@link PaymentBreakdown}: a one-time registration fee plus\n * the per-read data-access fee, and whether this settlement covered the\n * registration fee.\n */\nexport interface DirectFeeBreakdown {\n  /** One-time registration fee for the op, as a decimal base-unit string. */\n  registrationFee: string;\n  /** Per-read data-access fee, as a decimal base-unit string. */\n  dataAccessFee: string;\n  /** True when this settlement paid the registration fee. */\n  registrationPaid: boolean;\n}\n"],"mappings":"AA0JO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}
+{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\n\n/**\n * Shared types for the Direct Data Controller and the browser connect helper.\n *\n * @remarks\n * These types describe the \"two-tab\" Data Portability flow documented in the\n * builder guide: a backend controller creates an access request, the browser\n * opens Vana for user approval, and the backend reads the approved data from\n * the user's Personal Server (handling 402 Payment Required).\n *\n * @category Direct\n * @module direct/types\n */\n\n/**\n * Target environment for a {@link DirectDataController}.\n *\n * - `\"production\"` — Vana mainnet stack (default service URLs).\n * - `\"dev\"` — Vana internal dev/testnet stack. Use only when testing against\n *   Vana's dev infrastructure.\n */\nexport type DirectEnv = \"dev\" | \"production\";\n\n/**\n * App identity advertised to users during approval and attributed in Builder\n * League activity reports.\n */\nexport interface DirectAppConfig {\n  /** Stable, human-readable app id (e.g. `\"notes-lens\"`). */\n  id: string;\n  /** Display name shown to the user in the Vana approval UI. */\n  name: string;\n  /** Public homepage URL for the app. */\n  homepageUrl: string;\n}\n\n/**\n * Resolved app identity: the configured {@link DirectAppConfig} plus the app's\n * derived on-chain address (the address to fund and inspect).\n */\nexport interface AppIdentity extends DirectAppConfig {\n  /** The app's `0x`-prefixed on-chain address (derived from `appPrivateKey`). */\n  address: string;\n}\n\n/**\n * Resolved service URLs for a given {@link DirectEnv}.\n *\n * @remarks\n * Centralizes the per-environment base URLs the controller talks to. Each can\n * be overridden via {@link DirectDataControllerConfig.endpoints} when pointing\n * at a non-standard deployment.\n */\nexport interface DirectServiceEndpoints {\n  /** Vana chain id for this environment (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** Base URL of the Vana Account access-request API that issues `dcr_*` ids. */\n  accessRequestBaseUrl: string;\n  /** Base URL users are sent to for approval (the Vana app). */\n  approvalAppBaseUrl: string;\n}\n\n/** Result of {@link DirectDataController.createAccessRequest}. */\nexport interface AccessRequest {\n  /** Opaque request id (e.g. `\"dcr_123\"`). */\n  requestId: string;\n  /** URL the browser opens so the user can approve the requested scopes. */\n  approvalUrl: string;\n  /** On-chain address of the (registered or reused) app. */\n  appAddress: string;\n}\n\n/** Lifecycle status of an access request. */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"denied\"\n  | \"expired\";\n\n/** Result of {@link DirectDataController.getAccessRequestStatus}. */\nexport interface AccessRequestStatus {\n  /** Current lifecycle status of the request. */\n  status: AccessRequestStatusValue;\n  /** Personal Server base URL — present once `status === \"approved\"`. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once approved. */\n  grantId?: string;\n  /** The approved scope — present once approved. */\n  scope?: string;\n}\n\n/** Result of {@link DirectDataController.readApprovedData}. */\nexport interface ApprovedDataResult<T = unknown> {\n  /** The scope the data was read for. */\n  scope: string;\n  /** The decoded payload returned by the Personal Server. */\n  data: T;\n  /**\n   * Payment receipt — present only when this read required (and settled) a\n   * payment. Lets builders inspect the amount, asset, and fee breakdown without\n   * digging into the underlying 402/escrow exchange. Reads served from a paid-up\n   * grant omit this field.\n   */\n  payment?: DirectPaymentReceipt;\n}\n\n/**\n * Client for the Vana Account access-request API — the service that turns a\n * registered app + scopes into a `dcr_*` id and approval URL.\n *\n * @remarks\n * The controller uses a default client against the Vana Account endpoints. You\n * can inject your own implementation to point at a custom deployment or to\n * supply a test double.\n */\nexport interface AccessRequestClient {\n  /**\n   * Create an access request for the given app + scopes.\n   *\n   * @param input - App identity, source, scopes, and the post-approval return URL.\n   * @returns The created {@link AccessRequest}.\n   */\n  createAccessRequest(input: {\n    appAddress: string;\n    app: DirectAppConfig;\n    source: string;\n    scopes: string[];\n    returnUrl: string;\n  }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of a previously created access request.\n   *\n   * @param requestId - The `dcr_*` id returned by {@link AccessRequestClient.createAccessRequest}.\n   * @returns The current {@link AccessRequestStatus}.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n}\n\n/**\n * Op-type vocabulary used by the DPv2 escrow payment surface.\n *\n * @remarks\n * These are the operations the gateway prices and settles via\n * `POST /v1/escrow/pay` (`opType` field of the `GenericPayment` message). A\n * direct data read settles the {@link DirectOpType.DataAccess} op for the\n * approved grant; the other op types are listed here for completeness and to\n * give builders a typed vocabulary when inspecting fee breakdowns.\n *\n * Note: the escrow `GenericPayment` `opType` is currently `\"grant\"` on the wire\n * for grant lifecycle payments; this enum names the higher-level fee categories\n * the gateway reports in a {@link PaymentBreakdown}.\n */\nexport const DirectOpType = {\n  GrantRegistration: \"grant_registration\",\n  DataAccess: \"data_access\",\n  DataRegistration: \"data_registration\",\n  ServerRegistration: \"server_registration\",\n  BuilderRegistration: \"builder_registration\",\n} as const;\n\n/** A direct-flow op type (see {@link DirectOpType}). */\nexport type DirectOpTypeValue =\n  (typeof DirectOpType)[keyof typeof DirectOpType];\n\n/**\n * What a Personal Server `402 Payment Required` tells the controller is owed for\n * a data read.\n *\n * @remarks\n * The PS read 402 body identifies the grant to settle and the amount/asset. The\n * controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The full\n * unmodified body is preserved under {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id to settle (the escrow `opId`). Defaults to the read's grantId. */\n  grantId: string;\n  /** X402 network advertised by the Personal Server challenge. */\n  network?: string;\n  /** Payment nonce requested by the 402 challenge. */\n  paymentNonce?: string;\n  /** Server-signed data access receipt requested by the 402 challenge. */\n  accessRecord?: EscrowAccessRecord;\n  /** Asset address owed (zero address = native VANA). */\n  asset: string;\n  /** Amount owed, as a decimal base-unit string (preserves uint256 precision). */\n  amount: string;\n  /** The full, unmodified 402 response body. */\n  raw: unknown;\n}\n\n/**\n * Structured payment metadata attached to a successful paid read.\n *\n * @remarks\n * Derived from the gateway's {@link EscrowPayResult}. Lets builders debug the\n * amount, asset, and per-op fee breakdown without re-deriving anything from the\n * raw 402/payment exchange.\n */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (the grant id). */\n  opId: string;\n  /** Asset paid in (zero address = native VANA). */\n  asset: string;\n  /** Total amount paid, as a decimal base-unit string. */\n  amount: string;\n  /** Payment nonce used for this settlement. */\n  paymentNonce: string;\n  /** Fee breakdown reported by the gateway (registration vs data-access fee). */\n  breakdown: DirectFeeBreakdown;\n  /** ISO timestamp the gateway recorded the payment. */\n  paidAt: string;\n}\n\n/**\n * Per-op fee breakdown reported by the gateway.\n *\n * @remarks\n * Mirrors the escrow {@link PaymentBreakdown}: a one-time registration fee plus\n * the per-read data-access fee, and whether this settlement covered the\n * registration fee.\n */\nexport interface DirectFeeBreakdown {\n  /** One-time registration fee for the op, as a decimal base-unit string. */\n  registrationFee: string;\n  /** Per-read data-access fee, as a decimal base-unit string. */\n  dataAccessFee: string;\n  /** True when this settlement paid the registration fee. */\n  registrationPaid: boolean;\n}\n"],"mappings":"AA0JO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/vana-sdk",
-  "version": "3.6.2",
+  "version": "3.6.3",
   "description": "A TypeScript library for interacting with Vana Network smart contracts.",
   "publishConfig": {
     "access": "public"