@opendatalabs/vana-sdk 3.5.1 → 3.6.1

package/dist/direct/controller.js

@@ -0,0 +1,111 @@
+import { privateKeyToAccount } from "viem/accounts";
+import { parseScope } from "../protocol/scopes.js";
+import {
+  createDefaultAccessRequestClient
+} from "./access-request-client.js";
+import { getDirectEndpoints } from "./endpoints.js";
+import { AccessNotApprovedError, DirectConfigError } from "./errors.js";
+import {
+  readPersonalServerData
+} from "./personal-server-read.js";
+function isHexPrivateKey(value) {
+  return /^0x[0-9a-fA-F]{64}$/.test(value);
+}
+function createDirectDataController(config) {
+  const privateKey = config.appPrivateKey ?? config.builderPrivateKey;
+  if (!privateKey || !isHexPrivateKey(privateKey)) {
+    throw new DirectConfigError(
+      "appPrivateKey must be a 0x-prefixed 32-byte hex string"
+    );
+  }
+  if (!config.scopes || config.scopes.length === 0) {
+    throw new DirectConfigError("At least one scope is required");
+  }
+  for (const scope of config.scopes) {
+    parseScope(scope);
+  }
+  const env = config.env ?? "production";
+  const endpoints = {
+    ...getDirectEndpoints(env),
+    ...config.endpoints
+  };
+  const account = privateKeyToAccount(privateKey);
+  const signMessage = (message) => account.signMessage({ message });
+  const signTypedData = account.signTypedData;
+  const chainId = endpoints.chainId;
+  const accessRequestClient = config.accessRequestClient ?? createDefaultAccessRequestClient({
+    baseUrl: endpoints.accessRequestBaseUrl,
+    approvalBaseUrl: endpoints.approvalAppBaseUrl,
+    fetchFn: config.fetchFn,
+    appAddress: account.address,
+    signMessage
+  });
+  const escrow = config.escrow ? {
+    client: config.escrow.client,
+    escrowContract: config.escrow.escrowContract,
+    chainId: config.escrow.chainId ?? chainId,
+    nonceSource: config.escrow.nonceSource,
+    signTypedData
+  } : void 0;
+  return {
+    appAddress: account.address,
+    getAppAddress() {
+      return account.address;
+    },
+    getAppIdentity() {
+      return {
+        id: config.app.id,
+        name: config.app.name,
+        homepageUrl: config.app.homepageUrl,
+        address: account.address
+      };
+    },
+    async createAccessRequest(input) {
+      return accessRequestClient.createAccessRequest({
+        appAddress: account.address,
+        app: config.app,
+        source: config.source,
+        scopes: config.scopes,
+        returnUrl: input.returnUrl
+      });
+    },
+    async getAccessRequestStatus(requestId) {
+      return accessRequestClient.getAccessRequestStatus(requestId);
+    },
+    async readApprovedData(input) {
+      const status = await accessRequestClient.getAccessRequestStatus(
+        input.requestId
+      );
+      if (status.status !== "approved" || !status.personalServerUrl || !status.grantId || !status.scope) {
+        throw new AccessNotApprovedError(
+          "Request is not approved or is missing grantId/scope/personalServerUrl",
+          {
+            requestId: input.requestId,
+            status: status.status,
+            hasPersonalServerUrl: Boolean(status.personalServerUrl),
+            hasGrantId: Boolean(status.grantId),
+            hasScope: Boolean(status.scope)
+          }
+        );
+      }
+      const result = await readPersonalServerData({
+        personalServerUrl: status.personalServerUrl,
+        scope: status.scope,
+        grantId: status.grantId,
+        payerAddress: account.address,
+        signMessage,
+        escrow,
+        fetchFn: config.personalServerFetch
+      });
+      return {
+        scope: status.scope,
+        data: result.data,
+        payment: result.payment
+      };
+    }
+  };
+}
+export {
+  createDirectDataController
+};
+//# sourceMappingURL=controller.js.map

package/dist/direct/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/controller.ts"],"sourcesContent":["/**\n * Direct Data Controller — the server-side facade for the two-tab Data\n * Portability flow.\n *\n * @remarks\n * One controller owns an app's private key, source, scopes, app identity, and\n * payment flow. It exposes the three methods the builder guide documents:\n *\n * - {@link DirectDataController.createAccessRequest} — start an approval request.\n * - {@link DirectDataController.getAccessRequestStatus} — poll while the Vana tab is open.\n * - {@link DirectDataController.readApprovedData} — read from the Personal Server,\n *   handling 402 Payment Required.\n *\n * Access requests are created through the Vana Account access-request API; the\n * Personal Server read uses Web3Signed auth; and payment uses the DPv2 escrow\n * surface (`protocol/escrow`) — when a read returns `402`, the controller signs\n * a `GenericPayment` with the app key, settles it through the escrow gateway,\n * and retries.\n *\n * @category Direct\n * @module direct/controller\n */\n\nimport { privateKeyToAccount } from \"viem/accounts\";\nimport type { Hex } from \"viem\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport { parseScope } from \"../protocol/scopes\";\nimport {\n  createDefaultAccessRequestClient,\n  type FetchLike,\n} from \"./access-request-client\";\nimport { getDirectEndpoints } from \"./endpoints\";\nimport { AccessNotApprovedError, DirectConfigError } from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectServiceEndpoints,\n} from \"./types\";\n\n/** Configuration for {@link createDirectDataController}. */\nexport interface DirectDataControllerConfig {\n  /** Target environment. Defaults to `\"production\"`. */\n  env?: DirectEnv;\n  /**\n   * The app private key (`0x`-prefixed, 32 bytes). Server-side only — this key\n   * is the app's on-chain identity and is never exposed to the browser.\n   */\n  appPrivateKey?: string;\n  /**\n   * @deprecated Use {@link DirectDataControllerConfig.appPrivateKey}. Accepted as\n   * a backwards-compatible alias; if both are set, `appPrivateKey` wins.\n   */\n  builderPrivateKey?: string;\n  /** App identity advertised during approval. */\n  app: DirectAppConfig;\n  /** Data source key (e.g. `\"icloud_notes\"`). */\n  source: string;\n  /** Scopes to request (e.g. `[\"icloud_notes.notes\"]`). At least one required. */\n  scopes: string[];\n  /**\n   * Override the resolved service endpoints (partial). Useful for pointing at a\n   * non-standard deployment.\n   */\n  endpoints?: Partial<DirectServiceEndpoints>;\n  /**\n   * Client for the Vana Account access-request API. Defaults to a client against\n   * the resolved Vana Account endpoints; inject your own to point at a custom\n   * deployment or to supply a test double.\n   */\n  accessRequestClient?: AccessRequestClient;\n  /**\n   * Escrow settlement config used when a Personal Server read returns `402`.\n   *\n   * @remarks\n   * Wires the DPv2 escrow gateway (`protocol/escrow`). The controller supplies\n   * the EIP-712 `signTypedData` from the app key automatically, so you provide\n   * the gateway `client`, the `escrowContract` address, and (optionally) the\n   * `chainId` and a durable `nonceSource`. If omitted, a `402` from the Personal\n   * Server throws {@link PaymentRequiredError} carrying the amount/asset owed.\n   */\n  escrow?: DirectEscrowConfig;\n  /** `fetch` used by the default access-request client. Defaults to `globalThis.fetch`. */\n  fetchFn?: FetchLike;\n  /** `fetch` used for the Personal Server read. Defaults to `globalThis.fetch`. */\n  personalServerFetch?: PersonalServerFetch;\n}\n\n/**\n * Controller-level escrow config — the {@link EscrowPaymentConfig} minus the\n * `signTypedData` and `chainId` the controller injects itself.\n */\nexport interface DirectEscrowConfig extends Omit<\n  EscrowPaymentConfig,\n  \"signTypedData\" | \"chainId\"\n> {\n  /**\n   * Chain id for the EIP-712 domain. Defaults to the controller's environment\n   * (1480 for production, 14800 for dev).\n   */\n  chainId?: number;\n}\n\n/**\n * Server-side controller for the direct Data Portability flow.\n *\n * @typeParam T - Shape of the data returned by {@link DirectDataController.readApprovedData}.\n */\nexport interface DirectDataController {\n  /** The on-chain address of the app, derived from `appPrivateKey`. */\n  readonly appAddress: string;\n\n  /**\n   * The app's on-chain address — the address to fund and inspect in the Builder\n   * activity report. Equivalent to {@link DirectDataController.appAddress}.\n   *\n   * @returns The app's `0x`-prefixed address.\n   */\n  getAppAddress(): string;\n\n  /**\n   * The app's full identity: its configured id/name/homepage plus the derived\n   * on-chain address. Useful for telling builders which app address to fund or\n   * look up.\n   *\n   * @returns `{ id, name, homepageUrl, address }`.\n   */\n  getAppIdentity(): AppIdentity;\n\n  /**\n   * Create an access request the user can approve.\n   *\n   * @param input - The post-approval return URL.\n   * @returns `{ requestId, approvalUrl, appAddress }`.\n   */\n  createAccessRequest(input: { returnUrl: string }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of an access request.\n   *\n   * @param requestId - The `dcr_*` id from {@link DirectDataController.createAccessRequest}.\n   * @returns `{ status, personalServerUrl?, grantId?, scope? }`.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n\n  /**\n   * Read the approved data from the user's Personal Server.\n   *\n   * @remarks\n   * Resolves the request to its grant + Personal Server and performs a Web3Signed\n   * read. Hides the `402 Payment Required` flow by default: if a read needs\n   * payment and `escrow` is configured, it settles the grant via the escrow\n   * gateway and retries, attaching a {@link DirectPaymentReceipt} under\n   * `payment` so callers can inspect amount/asset/fee breakdown. If `escrow` is\n   * not configured, it throws {@link PaymentRequiredError} carrying the\n   * amount/asset owed.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<ApprovedDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n/**\n * Create a {@link DirectDataController}.\n *\n * @param config - Controller configuration (env, key, app identity, source, scopes).\n * @returns A ready-to-use controller.\n * @throws {@link DirectConfigError} when the key or scopes are invalid.\n */\nexport function createDirectDataController(\n  config: DirectDataControllerConfig,\n): DirectDataController {\n  // `appPrivateKey` is the documented field; `builderPrivateKey` is a\n  // deprecated alias kept for backwards compatibility.\n  const privateKey = config.appPrivateKey ?? config.builderPrivateKey;\n  if (!privateKey || !isHexPrivateKey(privateKey)) {\n    throw new DirectConfigError(\n      \"appPrivateKey must be a 0x-prefixed 32-byte hex string\",\n    );\n  }\n  if (!config.scopes || config.scopes.length === 0) {\n    throw new DirectConfigError(\"At least one scope is required\");\n  }\n  // Validate scopes eagerly so misconfiguration fails at construction.\n  for (const scope of config.scopes) {\n    parseScope(scope);\n  }\n\n  const env: DirectEnv = config.env ?? \"production\";\n  const endpoints: DirectServiceEndpoints = {\n    ...getDirectEndpoints(env),\n    ...config.endpoints,\n  };\n\n  const account = privateKeyToAccount(privateKey as Hex);\n  const signMessage: Web3SignedSignFn = (message: string) =>\n    account.signMessage({ message });\n  // viem's account.signTypedData satisfies the structural SignTypedDataFn used\n  // by the escrow GenericPayment signer.\n  const signTypedData = account.signTypedData as unknown as SignTypedDataFn;\n  const chainId = endpoints.chainId;\n\n  const accessRequestClient: AccessRequestClient =\n    config.accessRequestClient ??\n    createDefaultAccessRequestClient({\n      baseUrl: endpoints.accessRequestBaseUrl,\n      approvalBaseUrl: endpoints.approvalAppBaseUrl,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  const escrow: EscrowPaymentConfig | undefined = config.escrow\n    ? {\n        client: config.escrow.client,\n        escrowContract: config.escrow.escrowContract,\n        chainId: config.escrow.chainId ?? chainId,\n        nonceSource: config.escrow.nonceSource,\n        signTypedData,\n      }\n    : undefined;\n\n  return {\n    appAddress: account.address,\n\n    getAppAddress(): string {\n      return account.address;\n    },\n\n    getAppIdentity(): AppIdentity {\n      return {\n        id: config.app.id,\n        name: config.app.name,\n        homepageUrl: config.app.homepageUrl,\n        address: account.address,\n      };\n    },\n\n    async createAccessRequest(input): Promise<AccessRequest> {\n      return accessRequestClient.createAccessRequest({\n        appAddress: account.address,\n        app: config.app,\n        source: config.source,\n        scopes: config.scopes,\n        returnUrl: input.returnUrl,\n      });\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      return accessRequestClient.getAccessRequestStatus(requestId);\n    },\n\n    async readApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await accessRequestClient.getAccessRequestStatus(\n        input.requestId,\n      );\n      if (\n        status.status !== \"approved\" ||\n        !status.personalServerUrl ||\n        !status.grantId ||\n        !status.scope\n      ) {\n        throw new AccessNotApprovedError(\n          \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n          {\n            requestId: input.requestId,\n            status: status.status,\n            hasPersonalServerUrl: Boolean(status.personalServerUrl),\n            hasGrantId: Boolean(status.grantId),\n            hasScope: Boolean(status.scope),\n          },\n        );\n      }\n\n      const result = await readPersonalServerData({\n        personalServerUrl: status.personalServerUrl,\n        scope: status.scope,\n        grantId: status.grantId,\n        payerAddress: account.address,\n        signMessage,\n        escrow,\n        fetchFn: config.personalServerFetch,\n      });\n\n      return {\n        scope: status.scope,\n        data: result.data as T,\n        payment: result.payment,\n      };\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/controller.test.d.ts

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

package/dist/direct/endpoints.cjs

@@ -0,0 +1,45 @@
+"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 endpoints_exports = {};
+__export(endpoints_exports, {
+  DEV_ENDPOINTS: () => DEV_ENDPOINTS,
+  PRODUCTION_ENDPOINTS: () => PRODUCTION_ENDPOINTS,
+  getDirectEndpoints: () => getDirectEndpoints
+});
+module.exports = __toCommonJS(endpoints_exports);
+const PRODUCTION_ENDPOINTS = {
+  chainId: 1480,
+  accessRequestBaseUrl: "https://app.vana.org",
+  approvalAppBaseUrl: "https://app.vana.org"
+};
+const DEV_ENDPOINTS = {
+  chainId: 14800,
+  accessRequestBaseUrl: "https://app-dev.vana.org",
+  approvalAppBaseUrl: "https://app-dev.vana.org"
+};
+function getDirectEndpoints(env) {
+  return env === "dev" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEV_ENDPOINTS,
+  PRODUCTION_ENDPOINTS,
+  getDirectEndpoints
+});
+//# sourceMappingURL=endpoints.cjs.map

package/dist/direct/endpoints.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/endpoints.ts"],"sourcesContent":["/**\n * Per-environment service URLs for the Direct Data Controller.\n *\n * @remarks\n * The SDK ships production defaults; pass `env: \"dev\"` only when testing against\n * Vana's dev stack. This module is the single source of truth for those URLs.\n *\n * @category Direct\n * @module direct/endpoints\n */\n\nimport type { DirectEnv, DirectServiceEndpoints } from \"./types\";\n\n/** Production (mainnet) service URLs. */\nexport const PRODUCTION_ENDPOINTS: DirectServiceEndpoints = {\n  chainId: 1480,\n  accessRequestBaseUrl: \"https://app.vana.org\",\n  approvalAppBaseUrl: \"https://app.vana.org\",\n} as const;\n\n/** Dev/testnet (moksha) service URLs. */\nexport const DEV_ENDPOINTS: DirectServiceEndpoints = {\n  chainId: 14800,\n  accessRequestBaseUrl: \"https://app-dev.vana.org\",\n  approvalAppBaseUrl: \"https://app-dev.vana.org\",\n} as const;\n\n/**\n * Resolve the default {@link DirectServiceEndpoints} for an environment.\n *\n * @param env - Target environment.\n * @returns The default endpoints for that environment.\n */\nexport function getDirectEndpoints(env: DirectEnv): DirectServiceEndpoints {\n  return env === \"dev\" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcO,MAAM,uBAA+C;AAAA,EAC1D,SAAS;AAAA,EACT,sBAAsB;AAAA,EACtB,oBAAoB;AACtB;AAGO,MAAM,gBAAwC;AAAA,EACnD,SAAS;AAAA,EACT,sBAAsB;AAAA,EACtB,oBAAoB;AACtB;AAQO,SAAS,mBAAmB,KAAwC;AACzE,SAAO,QAAQ,QAAQ,gBAAgB;AACzC;","names":[]}

package/dist/direct/endpoints.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-environment service URLs for the Direct Data Controller.
+ *
+ * @remarks
+ * The SDK ships production defaults; pass `env: "dev"` only when testing against
+ * Vana's dev stack. This module is the single source of truth for those URLs.
+ *
+ * @category Direct
+ * @module direct/endpoints
+ */
+import type { DirectEnv, DirectServiceEndpoints } from "./types";
+/** Production (mainnet) service URLs. */
+export declare const PRODUCTION_ENDPOINTS: DirectServiceEndpoints;
+/** Dev/testnet (moksha) service URLs. */
+export declare const DEV_ENDPOINTS: DirectServiceEndpoints;
+/**
+ * Resolve the default {@link DirectServiceEndpoints} for an environment.
+ *
+ * @param env - Target environment.
+ * @returns The default endpoints for that environment.
+ */
+export declare function getDirectEndpoints(env: DirectEnv): DirectServiceEndpoints;

package/dist/direct/endpoints.js

@@ -0,0 +1,19 @@
+const PRODUCTION_ENDPOINTS = {
+  chainId: 1480,
+  accessRequestBaseUrl: "https://app.vana.org",
+  approvalAppBaseUrl: "https://app.vana.org"
+};
+const DEV_ENDPOINTS = {
+  chainId: 14800,
+  accessRequestBaseUrl: "https://app-dev.vana.org",
+  approvalAppBaseUrl: "https://app-dev.vana.org"
+};
+function getDirectEndpoints(env) {
+  return env === "dev" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;
+}
+export {
+  DEV_ENDPOINTS,
+  PRODUCTION_ENDPOINTS,
+  getDirectEndpoints
+};
+//# sourceMappingURL=endpoints.js.map

package/dist/direct/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/endpoints.ts"],"sourcesContent":["/**\n * Per-environment service URLs for the Direct Data Controller.\n *\n * @remarks\n * The SDK ships production defaults; pass `env: \"dev\"` only when testing against\n * Vana's dev stack. This module is the single source of truth for those URLs.\n *\n * @category Direct\n * @module direct/endpoints\n */\n\nimport type { DirectEnv, DirectServiceEndpoints } from \"./types\";\n\n/** Production (mainnet) service URLs. */\nexport const PRODUCTION_ENDPOINTS: DirectServiceEndpoints = {\n  chainId: 1480,\n  accessRequestBaseUrl: \"https://app.vana.org\",\n  approvalAppBaseUrl: \"https://app.vana.org\",\n} as const;\n\n/** Dev/testnet (moksha) service URLs. */\nexport const DEV_ENDPOINTS: DirectServiceEndpoints = {\n  chainId: 14800,\n  accessRequestBaseUrl: \"https://app-dev.vana.org\",\n  approvalAppBaseUrl: \"https://app-dev.vana.org\",\n} as const;\n\n/**\n * Resolve the default {@link DirectServiceEndpoints} for an environment.\n *\n * @param env - Target environment.\n * @returns The default endpoints for that environment.\n */\nexport function getDirectEndpoints(env: DirectEnv): DirectServiceEndpoints {\n  return env === \"dev\" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;\n}\n"],"mappings":"AAcO,MAAM,uBAA+C;AAAA,EAC1D,SAAS;AAAA,EACT,sBAAsB;AAAA,EACtB,oBAAoB;AACtB;AAGO,MAAM,gBAAwC;AAAA,EACnD,SAAS;AAAA,EACT,sBAAsB;AAAA,EACtB,oBAAoB;AACtB;AAQO,SAAS,mBAAmB,KAAwC;AACzE,SAAO,QAAQ,QAAQ,gBAAgB;AACzC;","names":[]}

package/dist/direct/errors.cjs

@@ -0,0 +1,65 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  AccessNotApprovedError: () => AccessNotApprovedError,
+  DirectConfigError: () => DirectConfigError,
+  PaymentRequiredError: () => PaymentRequiredError,
+  PersonalServerReadError: () => PersonalServerReadError
+});
+module.exports = __toCommonJS(errors_exports);
+var import_errors = require("../errors");
+class DirectConfigError extends import_errors.VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_CONFIG_ERROR");
+    this.details = details;
+  }
+  details;
+}
+class AccessNotApprovedError extends import_errors.VanaError {
+  constructor(message = "Access request is not approved yet", details) {
+    super(message, "DIRECT_ACCESS_NOT_APPROVED");
+    this.details = details;
+  }
+  details;
+}
+class PersonalServerReadError extends import_errors.VanaError {
+  constructor(message, status, details) {
+    super(message, "DIRECT_PERSONAL_SERVER_READ_ERROR");
+    this.status = status;
+    this.details = details;
+  }
+  status;
+  details;
+}
+class PaymentRequiredError extends import_errors.VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_PAYMENT_REQUIRED");
+    this.details = details;
+  }
+  details;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccessNotApprovedError,
+  DirectConfigError,
+  PaymentRequiredError,
+  PersonalServerReadError
+});
+//# sourceMappingURL=errors.cjs.map

package/dist/direct/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYA,oBAA0B;AAGnB,MAAM,0BAA0B,wBAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,wBAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,wBAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,wBAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}

package/dist/direct/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Typed errors for the Direct Data Controller flow.
+ *
+ * @remarks
+ * These extend {@link VanaError} so direct-controller callers can branch on the
+ * structured `code` field. The messages map to the failure modes documented in
+ * the builder guide ("Common Errors").
+ *
+ * @category Direct
+ * @module direct/errors
+ */
+import { VanaError } from "../errors";
+/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */
+export declare class DirectConfigError extends VanaError {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when {@link DirectDataController.readApprovedData} is called for a
+ * request that is not yet approved (missing grantId, scope, or personalServerUrl).
+ */
+export declare class AccessNotApprovedError extends VanaError {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message?: string, details?: Record<string, unknown> | undefined);
+}
+/** Thrown when the Personal Server cannot be reached or returns an error. */
+export declare class PersonalServerReadError extends VanaError {
+    readonly status?: number | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, status?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config
+ * is set, or the read still requires payment after escrow settlement.
+ *
+ * @remarks
+ * `details` carries structured debug data (`scope`, `grantId`, `asset`,
+ * `amount`, and — after a settlement attempt — the `payment` receipt) so callers
+ * can see exactly what was owed.
+ */
+export declare class PaymentRequiredError extends VanaError {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}

package/dist/direct/errors.js

@@ -0,0 +1,38 @@
+import { VanaError } from "../errors.js";
+class DirectConfigError extends VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_CONFIG_ERROR");
+    this.details = details;
+  }
+  details;
+}
+class AccessNotApprovedError extends VanaError {
+  constructor(message = "Access request is not approved yet", details) {
+    super(message, "DIRECT_ACCESS_NOT_APPROVED");
+    this.details = details;
+  }
+  details;
+}
+class PersonalServerReadError extends VanaError {
+  constructor(message, status, details) {
+    super(message, "DIRECT_PERSONAL_SERVER_READ_ERROR");
+    this.status = status;
+    this.details = details;
+  }
+  status;
+  details;
+}
+class PaymentRequiredError extends VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_PAYMENT_REQUIRED");
+    this.details = details;
+  }
+  details;
+}
+export {
+  AccessNotApprovedError,
+  DirectConfigError,
+  PaymentRequiredError,
+  PersonalServerReadError
+};
+//# sourceMappingURL=errors.js.map

package/dist/direct/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":"AAYA,SAAS,iBAAiB;AAGnB,MAAM,0BAA0B,UAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,UAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,UAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,UAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}

package/dist/direct/escrow-payment.cjs

@@ -0,0 +1,96 @@
+"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 escrow_payment_exports = {};
+__export(escrow_payment_exports, {
+  GRANT_OP_TYPE: () => GRANT_OP_TYPE,
+  authorizeGrantPayment: () => authorizeGrantPayment,
+  createDefaultNonceSource: () => createDefaultNonceSource,
+  toDirectFeeBreakdown: () => toDirectFeeBreakdown,
+  toDirectPaymentReceipt: () => toDirectPaymentReceipt
+});
+module.exports = __toCommonJS(escrow_payment_exports);
+var import_escrow = require("../protocol/escrow");
+const GRANT_OP_TYPE = "grant";
+function toDirectFeeBreakdown(breakdown) {
+  return {
+    registrationFee: breakdown.registrationFee,
+    dataAccessFee: breakdown.dataAccessFee,
+    registrationPaid: breakdown.registrationPaid
+  };
+}
+function toDirectPaymentReceipt(result) {
+  return {
+    opType: result.opType,
+    opId: result.opId,
+    asset: result.asset,
+    amount: result.amount,
+    paymentNonce: result.paymentNonce,
+    breakdown: toDirectFeeBreakdown(result.breakdown),
+    paidAt: result.paidAt
+  };
+}
+function createDefaultNonceSource() {
+  const counters = /* @__PURE__ */ new Map();
+  return (payerAddress) => {
+    const key = payerAddress.toLowerCase();
+    const next = (counters.get(key) ?? 0n) + 1n;
+    counters.set(key, next);
+    return next;
+  };
+}
+async function authorizeGrantPayment(params) {
+  const { payerAddress, required, config } = params;
+  const nonceSource = config.nonceSource ?? createDefaultNonceSource();
+  const paymentNonce = BigInt(await nonceSource(payerAddress));
+  const asset = required.asset || import_escrow.NATIVE_ASSET_ADDRESS;
+  const opId = required.grantId;
+  const amount = BigInt(required.amount);
+  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
+    }
+  });
+  const result = await config.client.payForOp({
+    payerAddress,
+    opType: GRANT_OP_TYPE,
+    opId,
+    asset,
+    amount: amount.toString(),
+    paymentNonce: paymentNonce.toString(),
+    signature
+  });
+  return toDirectPaymentReceipt(result);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GRANT_OP_TYPE,
+  authorizeGrantPayment,
+  createDefaultNonceSource,
+  toDirectFeeBreakdown,
+  toDirectPaymentReceipt
+});
+//# sourceMappingURL=escrow-payment.cjs.map

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

@@ -0,0 +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(await nonceSource(payerAddress));\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  });\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,OAAO,MAAM,YAAY,YAAY,CAAC;AAC3D,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,EACF,CAAC;AAED,SAAO,uBAAuB,MAAM;AACtC;","names":[]}

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

@@ -0,0 +1,81 @@
+/**
+ * Escrow-backed payment authorization for the Direct Data Controller.
+ *
+ * @remarks
+ * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal
+ * Server read returns `402 Payment Required`, the controller settles the
+ * grant's data-access fee through the escrow gateway:
+ *
+ *  1. Sign a `GenericPayment` EIP-712 message (op `"grant"`, opId = grantId)
+ *     with the app key.
+ *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.
+ *  3. Map the gateway's {@link EscrowPayResult} into a typed
+ *     {@link DirectPaymentReceipt} for the caller to inspect.
+ *
+ * This module adapts the escrow `payForOp` flow to the direct-read use case; it
+ * does not define its own payment scheme.
+ *
+ * @category Direct
+ * @module direct/escrow-payment
+ */
+import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowGatewayClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow";
+import type { DirectFeeBreakdown, DirectPaymentReceipt, PersonalServerPaymentRequired } from "./types";
+/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */
+export declare const GRANT_OP_TYPE: "grant";
+/**
+ * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).
+ *
+ * @remarks
+ * Kept structurally minimal so any viem account/wallet client satisfies it
+ * without the SDK depending on viem's exact `signTypedData` overload set.
+ */
+export type SignTypedDataFn = (args: {
+    domain: ReturnType<typeof genericPaymentDomain>;
+    types: typeof GENERIC_PAYMENT_TYPES;
+    primaryType: "GenericPayment";
+    message: {
+        payerAddress: `0x${string}`;
+        opType: string;
+        opId: `0x${string}`;
+        asset: `0x${string}`;
+        amount: bigint;
+        paymentNonce: bigint;
+    };
+}) => Promise<`0x${string}`>;
+/** Supplies a monotonically-increasing payment nonce per payer. */
+export type PaymentNonceSource = (payerAddress: string) => Promise<bigint> | bigint;
+/** Escrow settlement configuration for the controller. */
+export interface EscrowPaymentConfig {
+    /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */
+    client: EscrowGatewayClient;
+    /** Deployed `DataPortabilityEscrow` contract address. */
+    escrowContract: `0x${string}`;
+    /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */
+    chainId: number;
+    /** App EIP-712 signer. */
+    signTypedData: SignTypedDataFn;
+    /**
+     * Supplies the next payment nonce for a payer. Defaults to a process-local
+     * monotonic counter seeded at 1. Provide a durable source in production so
+     * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).
+     */
+    nonceSource?: PaymentNonceSource;
+}
+/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */
+export declare function toDirectFeeBreakdown(breakdown: PaymentBreakdown): DirectFeeBreakdown;
+/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */
+export declare function toDirectPaymentReceipt(result: EscrowPayResult): DirectPaymentReceipt;
+/** Default in-process monotonic nonce counter (seeded at 1 per payer). */
+export declare function createDefaultNonceSource(): PaymentNonceSource;
+/**
+ * Authorize an escrow payment for a grant data-access fee.
+ *
+ * @param params - The payment requirement, the payer address, and escrow config.
+ * @returns The gateway's {@link EscrowPayResult} as a typed
+ * {@link DirectPaymentReceipt}.
+ */
+export declare function authorizeGrantPayment(params: {
+    payerAddress: `0x${string}`;
+    required: PersonalServerPaymentRequired;
+    config: EscrowPaymentConfig;
+}): Promise<DirectPaymentReceipt>;