@opendatalabs/vana-sdk 3.5.1 → 3.6.0

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

@@ -0,0 +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 { NATIVE_ASSET_ADDRESS } from \"../protocol/escrow\";\nimport {\n  authorizeGrantPayment,\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\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 = (raw ?? {}) as {\n    grantId?: unknown;\n    opId?: unknown;\n    asset?: unknown;\n    amount?: unknown;\n    maxAmountRequired?: unknown;\n  };\n  const resolvedGrantId =\n    typeof body.grantId === \"string\"\n      ? body.grantId\n      : typeof body.opId === \"string\"\n        ? body.opId\n        : grantId;\n  const amountValue =\n    typeof body.amount === \"string\"\n      ? body.amount\n      : typeof body.maxAmountRequired === \"string\"\n        ? body.maxAmountRequired\n        : \"0\";\n  return {\n    grantId: resolvedGrantId,\n    asset: typeof body.asset === \"string\" ? body.asset : NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\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    payment = await authorizeGrantPayment({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry — the settled payment unlocks the read.\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":[]}

package/dist/direct/personal-server-read.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.
+ *
+ * @remarks
+ * The read targets the Personal Server data path (`/v1/data/{scope}`),
+ * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),
+ * and — on `402 Payment Required` — settles the grant's data-access fee through
+ * the DPv2 escrow gateway and retries once.
+ *
+ * The 402 body is parsed into a {@link PersonalServerPaymentRequired} (grant id,
+ * asset, and amount owed), which drives the escrow settlement.
+ *
+ * @category Direct
+ * @module direct/personal-server-read
+ */
+import type { Web3SignedSignFn } from "../auth/web3-signed-builder";
+import { type EscrowPaymentConfig } from "./escrow-payment";
+import type { DirectPaymentReceipt, PersonalServerPaymentRequired } from "./types";
+/** Minimal `Response`-like shape so the read loop is testable without a DOM. */
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */
+export type PersonalServerFetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+}) => Promise<FetchResponseLike>;
+/** A built, ready-to-send Personal Server data read request. */
+export interface PersonalServerDataReadRequest {
+    /** Absolute URL of the read endpoint. */
+    url: string;
+    /** HTTP method (always `"GET"`). */
+    method: "GET";
+    /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */
+    path: string;
+    /** Headers including the Web3Signed `Authorization` value. */
+    headers: Record<string, string>;
+}
+/** Outcome of {@link readPersonalServerData}: the payload plus optional receipt. */
+export interface PersonalServerReadResult {
+    /** The decoded JSON payload returned by the Personal Server. */
+    data: unknown;
+    /** Present only when this read required (and settled) a payment. */
+    payment?: DirectPaymentReceipt;
+}
+/** Compute the data path for a scope (`/v1/data/{scope}`). */
+export declare function dataPathForScope(scope: string): string;
+/**
+ * Build a Web3Signed-authenticated Personal Server data read request.
+ *
+ * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.
+ * @returns The request URL, method, path, and headers (including `Authorization`).
+ */
+export declare function buildPersonalServerDataReadRequest(params: {
+    /** Base URL of the user's Personal Server. */
+    personalServerUrl: string;
+    /** Scope to read (e.g. `"icloud_notes.notes"`). */
+    scope: string;
+    /** Grant id authorizing the read. */
+    grantId: string;
+    /** EIP-191 signer for the Web3Signed header (the app key). */
+    signMessage: Web3SignedSignFn;
+}): Promise<PersonalServerDataReadRequest>;
+/**
+ * Parse a `402 Payment Required` body into a {@link PersonalServerPaymentRequired}.
+ *
+ * @remarks
+ * Accepts a few field spellings and falls back to the read's own grantId and the
+ * native asset when a field is absent.
+ *
+ * @param res - The 402 response.
+ * @param grantId - The grant id of the read (default `opId`).
+ * @returns The parsed payment requirement.
+ */
+export declare function parsePersonalServerPaymentRequired(res: FetchResponseLike, grantId: string): Promise<PersonalServerPaymentRequired>;
+/**
+ * Read approved data from a Personal Server, settling a 402 via escrow.
+ *
+ * @remarks
+ * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what
+ * is owed, authorizes an escrow payment for the grant via `escrow`, and retries
+ * once. If escrow is not configured, throws {@link PaymentRequiredError} carrying
+ * the parsed requirement so callers can debug amount/asset.
+ *
+ * @param params - Connection details, app signer, optional escrow config and fetch.
+ * @returns `{ data, payment? }`.
+ */
+export declare function readPersonalServerData(params: {
+    personalServerUrl: string;
+    scope: string;
+    grantId: string;
+    payerAddress: `0x${string}`;
+    signMessage: Web3SignedSignFn;
+    escrow?: EscrowPaymentConfig;
+    fetchFn?: PersonalServerFetch;
+}): Promise<PersonalServerReadResult>;

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

@@ -0,0 +1,124 @@
+import { buildWeb3SignedHeader } from "../auth/web3-signed-builder.js";
+import { NATIVE_ASSET_ADDRESS } from "../protocol/escrow.js";
+import {
+  authorizeGrantPayment
+} from "./escrow-payment.js";
+import { PaymentRequiredError, PersonalServerReadError } from "./errors.js";
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function dataPathForScope(scope) {
+  return `/v1/data/${encodeURIComponent(scope)}`;
+}
+async function buildPersonalServerDataReadRequest(params) {
+  const base = stripTrailingSlash(params.personalServerUrl);
+  const path = dataPathForScope(params.scope);
+  const authorization = await buildWeb3SignedHeader({
+    signMessage: params.signMessage,
+    aud: base,
+    method: "GET",
+    uri: path,
+    grantId: params.grantId
+  });
+  const headers = {
+    Authorization: authorization,
+    Accept: "application/json"
+  };
+  return { url: `${base}${path}`, method: "GET", path, headers };
+}
+async function parsePersonalServerPaymentRequired(res, grantId) {
+  let raw = void 0;
+  try {
+    raw = await res.json();
+  } catch {
+    raw = void 0;
+  }
+  const body = raw ?? {};
+  const resolvedGrantId = typeof body.grantId === "string" ? body.grantId : typeof body.opId === "string" ? body.opId : grantId;
+  const amountValue = typeof body.amount === "string" ? body.amount : typeof body.maxAmountRequired === "string" ? body.maxAmountRequired : "0";
+  return {
+    grantId: resolvedGrantId,
+    asset: typeof body.asset === "string" ? body.asset : NATIVE_ASSET_ADDRESS,
+    amount: amountValue,
+    raw
+  };
+}
+async function readPersonalServerData(params) {
+  const fetchFn = params.fetchFn ?? globalThis.fetch;
+  if (!fetchFn) {
+    throw new PersonalServerReadError(
+      "No fetch implementation available for Personal Server read"
+    );
+  }
+  const initial = await buildPersonalServerDataReadRequest({
+    personalServerUrl: params.personalServerUrl,
+    scope: params.scope,
+    grantId: params.grantId,
+    signMessage: params.signMessage
+  });
+  let res = await fetchFn(initial.url, {
+    method: initial.method,
+    headers: initial.headers
+  });
+  let payment;
+  if (res.status === 402) {
+    const required = await parsePersonalServerPaymentRequired(
+      res,
+      params.grantId
+    );
+    if (!params.escrow) {
+      throw new PaymentRequiredError(
+        "Personal Server requires payment but no escrow config is set",
+        {
+          scope: params.scope,
+          grantId: required.grantId,
+          asset: required.asset,
+          amount: required.amount
+        }
+      );
+    }
+    payment = await authorizeGrantPayment({
+      payerAddress: params.payerAddress,
+      required,
+      config: params.escrow
+    });
+    const retry = await buildPersonalServerDataReadRequest({
+      personalServerUrl: params.personalServerUrl,
+      scope: params.scope,
+      grantId: params.grantId,
+      signMessage: params.signMessage
+    });
+    res = await fetchFn(retry.url, {
+      method: retry.method,
+      headers: retry.headers
+    });
+    if (res.status === 402) {
+      throw new PaymentRequiredError(
+        "Personal Server still requires payment after escrow settlement",
+        {
+          scope: params.scope,
+          grantId: required.grantId,
+          asset: required.asset,
+          amount: required.amount,
+          payment
+        }
+      );
+    }
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new PersonalServerReadError(
+      `Personal Server read failed: ${res.status} ${res.statusText}`,
+      res.status,
+      { scope: params.scope, body: detail.slice(0, 500) }
+    );
+  }
+  return { data: await res.json(), payment };
+}
+export {
+  buildPersonalServerDataReadRequest,
+  dataPathForScope,
+  parsePersonalServerPaymentRequired,
+  readPersonalServerData
+};
+//# sourceMappingURL=personal-server-read.js.map

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

@@ -0,0 +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 { NATIVE_ASSET_ADDRESS } from \"../protocol/escrow\";\nimport {\n  authorizeGrantPayment,\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\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 = (raw ?? {}) as {\n    grantId?: unknown;\n    opId?: unknown;\n    asset?: unknown;\n    amount?: unknown;\n    maxAmountRequired?: unknown;\n  };\n  const resolvedGrantId =\n    typeof body.grantId === \"string\"\n      ? body.grantId\n      : typeof body.opId === \"string\"\n        ? body.opId\n        : grantId;\n  const amountValue =\n    typeof body.amount === \"string\"\n      ? body.amount\n      : typeof body.maxAmountRequired === \"string\"\n        ? body.maxAmountRequired\n        : \"0\";\n  return {\n    grantId: resolvedGrantId,\n    asset: typeof body.asset === \"string\" ? body.asset : NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\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    payment = await authorizeGrantPayment({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry — the settled payment unlocks the read.\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":[]}

package/dist/direct/personal-server-read.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/direct/types.cjs

@@ -0,0 +1,35 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+__export(types_exports, {
+  DirectOpType: () => DirectOpType
+});
+module.exports = __toCommonJS(types_exports);
+const DirectOpType = {
+  GrantRegistration: "grant_registration",
+  DataAccess: "data_access",
+  DataRegistration: "data_registration",
+  ServerRegistration: "server_registration",
+  BuilderRegistration: "builder_registration"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DirectOpType
+});
+//# sourceMappingURL=types.cjs.map

package/dist/direct/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["/**\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  /** 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;AAwJO,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

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

package/dist/direct/types.js

@@ -0,0 +1,11 @@
+const DirectOpType = {
+  GrantRegistration: "grant_registration",
+  DataAccess: "data_access",
+  DataRegistration: "data_registration",
+  ServerRegistration: "server_registration",
+  BuilderRegistration: "builder_registration"
+};
+export {
+  DirectOpType
+};
+//# sourceMappingURL=types.js.map

package/dist/direct/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["/**\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  /** 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":"AAwJO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}

package/dist/direct/use-direct-vana-connect.cjs

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var use_direct_vana_connect_exports = {};
+__export(use_direct_vana_connect_exports, {
+  useDirectVanaConnect: () => useDirectVanaConnect
+});
+module.exports = __toCommonJS(use_direct_vana_connect_exports);
+var import_react = require("react");
+var import_connect_flow = require("./connect-flow");
+function useDirectVanaConnect(options) {
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const flow = (0, import_react.useMemo)(
+    () => (0, import_connect_flow.createDirectConnectFlow)(
+      {
+        createRequest: () => optionsRef.current.createRequest(),
+        getStatus: (id) => optionsRef.current.getStatus(id),
+        readResult: (id) => optionsRef.current.readResult(id)
+      },
+      {
+        get pollIntervalMs() {
+          return optionsRef.current.pollIntervalMs;
+        },
+        get timeoutMs() {
+          return optionsRef.current.timeoutMs;
+        },
+        get openWindow() {
+          return optionsRef.current.openWindow;
+        }
+      }
+    ),
+    // Created once per component instance; callbacks are read via optionsRef.
+    []
+  );
+  const state = (0, import_react.useSyncExternalStore)(
+    flow.subscribe,
+    flow.getState,
+    flow.getState
+  );
+  const start = (0, import_react.useCallback)(() => {
+    void flow.start();
+  }, [flow]);
+  const reset = (0, import_react.useCallback)(() => {
+    flow.reset();
+  }, [flow]);
+  return { state, start, reset };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDirectVanaConnect
+});
+//# sourceMappingURL=use-direct-vana-connect.cjs.map