@opendatalabs/vana-sdk 3.5.1 → 3.6.0

package/dist/direct/connect-flow.js

@@ -0,0 +1,128 @@
+const DEFAULT_POLL_INTERVAL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 3e5;
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+function createDirectConnectFlow(transports, options = {}) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const openWindow = options.openWindow ?? ((url) => {
+    if (typeof window !== "undefined" && window.open) {
+      window.open(url, "_blank", "noopener,noreferrer");
+    }
+  });
+  const setTimeoutFn = options.setTimeoutFn ?? ((cb, ms) => globalThis.setTimeout(cb, ms));
+  const clearTimeoutFn = options.clearTimeoutFn ?? ((handle) => {
+    globalThis.clearTimeout(handle);
+  });
+  const now = options.now ?? (() => Date.now());
+  let state = { type: "idle" };
+  const listeners = /* @__PURE__ */ new Set();
+  let pollHandle = null;
+  let running = false;
+  function emit() {
+    for (const listener of listeners) listener();
+  }
+  function setState(next) {
+    state = next;
+    emit();
+  }
+  function clearPoll() {
+    if (pollHandle !== null) {
+      clearTimeoutFn(pollHandle);
+      pollHandle = null;
+    }
+  }
+  function isRunningPhase() {
+    return state.type === "creating" || state.type === "awaiting_approval" || state.type === "reading";
+  }
+  async function readAndFinish(request) {
+    setState({ type: "reading", request });
+    try {
+      const result = await transports.readResult(request.requestId);
+      if (!running) return;
+      setState({ type: "done", result });
+    } catch (err) {
+      if (!running) return;
+      setState({ type: "error", error: toError(err) });
+    } finally {
+      running = false;
+    }
+  }
+  function scheduleNextPoll(request, deadline) {
+    pollHandle = setTimeoutFn(() => {
+      void poll(request, deadline);
+    }, pollIntervalMs);
+  }
+  async function poll(request, deadline) {
+    if (!running) return;
+    if (now() >= deadline) {
+      running = false;
+      setState({
+        type: "error",
+        error: new Error("Timed out waiting for approval")
+      });
+      return;
+    }
+    let status;
+    try {
+      status = await transports.getStatus(request.requestId);
+    } catch (err) {
+      if (!running) return;
+      running = false;
+      setState({ type: "error", error: toError(err) });
+      return;
+    }
+    if (!running) return;
+    if (status.status === "approved") {
+      clearPoll();
+      await readAndFinish(request);
+      return;
+    }
+    if (status.status === "denied" || status.status === "expired") {
+      running = false;
+      setState({
+        type: "error",
+        error: new Error(`Access request ${status.status}`)
+      });
+      return;
+    }
+    scheduleNextPoll(request, deadline);
+  }
+  return {
+    getState() {
+      return state;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async start() {
+      if (running || isRunningPhase()) return;
+      running = true;
+      setState({ type: "creating" });
+      let request;
+      try {
+        request = await transports.createRequest();
+      } catch (err) {
+        running = false;
+        setState({ type: "error", error: toError(err) });
+        return;
+      }
+      if (!running) return;
+      setState({ type: "awaiting_approval", request });
+      openWindow(request.approvalUrl);
+      const deadline = now() + timeoutMs;
+      scheduleNextPoll(request, deadline);
+    },
+    reset() {
+      running = false;
+      clearPoll();
+      setState({ type: "idle" });
+    }
+  };
+}
+export {
+  createDirectConnectFlow
+};
+//# sourceMappingURL=connect-flow.js.map

package/dist/direct/connect-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/connect-flow.ts"],"sourcesContent":["/**\n * Framework-agnostic connect-flow state machine for the browser two-tab helper.\n *\n * @remarks\n * This is the testable core behind {@link useDirectVanaConnect}. It is pure\n * TypeScript (no React, no DOM-only APIs beyond an injectable window opener and\n * timers) so the full flow — create request, open Vana, poll status, read data —\n * can be exercised in a Node test environment.\n *\n * The React hook is a thin `useSyncExternalStore` binding over this store.\n *\n * @category Direct\n * @module direct/connect-flow\n */\n\nimport type {\n  AccessRequest,\n  AccessRequestStatus,\n  ApprovedDataResult,\n} from \"./types\";\n\n/**\n * Caller-supplied transports. These typically `fetch` the app's own backend\n * routes, which in turn delegate to a {@link DirectDataController}.\n */\nexport interface DirectConnectTransports<T = unknown> {\n  /** Ask the backend to create an access request. */\n  createRequest: () => Promise<AccessRequest>;\n  /** Ask the backend for the current status of a request. */\n  getStatus: (requestId: string) => Promise<AccessRequestStatus>;\n  /** Ask the backend to read the approved data. */\n  readResult: (requestId: string) => Promise<ApprovedDataResult<T>>;\n}\n\n/** Tunables for the connect flow. */\nexport interface DirectConnectOptions {\n  /** Status poll interval in ms. Defaults to 1500. */\n  pollIntervalMs?: number;\n  /** Overall timeout in ms before giving up. Defaults to 300000 (5 min). */\n  timeoutMs?: number;\n  /** Opens the approval URL. Defaults to `window.open`. Injectable for tests. */\n  openWindow?: (url: string) => void;\n  /** `setTimeout`. Injectable for tests. Defaults to `globalThis.setTimeout`. */\n  setTimeoutFn?: (cb: () => void, ms: number) => unknown;\n  /** `clearTimeout`. Injectable for tests. Defaults to `globalThis.clearTimeout`. */\n  clearTimeoutFn?: (handle: unknown) => void;\n  /** Clock source in ms. Injectable for tests. Defaults to `Date.now`. */\n  now?: () => number;\n}\n\n/**\n * Discriminated connect-flow state.\n *\n * @remarks\n * `type` matches the builder guide: it starts at `\"idle\"` and is non-idle while\n * connecting. The intermediate phases give richer UIs something to render.\n */\nexport type DirectConnectState<T = unknown> =\n  | { type: \"idle\" }\n  | { type: \"creating\" }\n  | { type: \"awaiting_approval\"; request: AccessRequest }\n  | { type: \"reading\"; request: AccessRequest }\n  | { type: \"done\"; result: ApprovedDataResult<T> }\n  | { type: \"error\"; error: Error };\n\n/** The store returned by {@link createDirectConnectFlow}. */\nexport interface DirectConnectFlow<T = unknown> {\n  /** Current state. */\n  getState(): DirectConnectState<T>;\n  /** Subscribe to state changes; returns an unsubscribe function. */\n  subscribe(listener: () => void): () => void;\n  /** Begin the flow. No-op if already running. */\n  start(): Promise<void>;\n  /** Reset to `idle` and stop any in-flight polling. */\n  reset(): void;\n}\n\nconst DEFAULT_POLL_INTERVAL_MS = 1500;\nconst DEFAULT_TIMEOUT_MS = 300_000;\n\nfunction toError(value: unknown): Error {\n  return value instanceof Error ? value : new Error(String(value));\n}\n\n/**\n * Create a connect-flow store.\n *\n * @param transports - Backend transports (`createRequest`, `getStatus`, `readResult`).\n * @param options - Polling/timeout tunables and injectable side effects.\n * @returns A {@link DirectConnectFlow} store.\n */\nexport function createDirectConnectFlow<T = unknown>(\n  transports: DirectConnectTransports<T>,\n  options: DirectConnectOptions = {},\n): DirectConnectFlow<T> {\n  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const openWindow =\n    options.openWindow ??\n    ((url: string) => {\n      if (typeof window !== \"undefined\" && window.open) {\n        window.open(url, \"_blank\", \"noopener,noreferrer\");\n      }\n    });\n  const setTimeoutFn =\n    options.setTimeoutFn ??\n    ((cb: () => void, ms: number) => globalThis.setTimeout(cb, ms));\n  const clearTimeoutFn =\n    options.clearTimeoutFn ??\n    ((handle: unknown) => {\n      globalThis.clearTimeout(handle as never);\n    });\n  const now = options.now ?? (() => Date.now());\n\n  let state: DirectConnectState<T> = { type: \"idle\" };\n  const listeners = new Set<() => void>();\n  let pollHandle: unknown = null;\n  let running = false;\n\n  function emit(): void {\n    for (const listener of listeners) listener();\n  }\n\n  function setState(next: DirectConnectState<T>): void {\n    state = next;\n    emit();\n  }\n\n  function clearPoll(): void {\n    if (pollHandle !== null) {\n      clearTimeoutFn(pollHandle);\n      pollHandle = null;\n    }\n  }\n\n  function isRunningPhase(): boolean {\n    return (\n      state.type === \"creating\" ||\n      state.type === \"awaiting_approval\" ||\n      state.type === \"reading\"\n    );\n  }\n\n  async function readAndFinish(request: AccessRequest): Promise<void> {\n    setState({ type: \"reading\", request });\n    try {\n      const result = await transports.readResult(request.requestId);\n      if (!running) return;\n      setState({ type: \"done\", result });\n    } catch (err) {\n      if (!running) return;\n      setState({ type: \"error\", error: toError(err) });\n    } finally {\n      running = false;\n    }\n  }\n\n  function scheduleNextPoll(request: AccessRequest, deadline: number): void {\n    pollHandle = setTimeoutFn(() => {\n      void poll(request, deadline);\n    }, pollIntervalMs);\n  }\n\n  async function poll(request: AccessRequest, deadline: number): Promise<void> {\n    if (!running) return;\n    if (now() >= deadline) {\n      running = false;\n      setState({\n        type: \"error\",\n        error: new Error(\"Timed out waiting for approval\"),\n      });\n      return;\n    }\n    let status: AccessRequestStatus;\n    try {\n      status = await transports.getStatus(request.requestId);\n    } catch (err) {\n      if (!running) return;\n      running = false;\n      setState({ type: \"error\", error: toError(err) });\n      return;\n    }\n    if (!running) return;\n\n    if (status.status === \"approved\") {\n      clearPoll();\n      await readAndFinish(request);\n      return;\n    }\n    if (status.status === \"denied\" || status.status === \"expired\") {\n      running = false;\n      setState({\n        type: \"error\",\n        error: new Error(`Access request ${status.status}`),\n      });\n      return;\n    }\n    scheduleNextPoll(request, deadline);\n  }\n\n  return {\n    getState() {\n      return state;\n    },\n\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n\n    async start(): Promise<void> {\n      if (running || isRunningPhase()) return;\n      running = true;\n      setState({ type: \"creating\" });\n\n      let request: AccessRequest;\n      try {\n        request = await transports.createRequest();\n      } catch (err) {\n        running = false;\n        setState({ type: \"error\", error: toError(err) });\n        return;\n      }\n      if (!running) return;\n\n      setState({ type: \"awaiting_approval\", request });\n      openWindow(request.approvalUrl);\n\n      const deadline = now() + timeoutMs;\n      scheduleNextPoll(request, deadline);\n    },\n\n    reset(): void {\n      running = false;\n      clearPoll();\n      setState({ type: \"idle\" });\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/connect-flow.test.d.ts

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

package/dist/direct/controller.cjs

@@ -0,0 +1,129 @@
+"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 controller_exports = {};
+__export(controller_exports, {
+  createDirectDataController: () => createDirectDataController
+});
+module.exports = __toCommonJS(controller_exports);
+var import_accounts = require("viem/accounts");
+var import_scopes = require("../protocol/scopes");
+var import_access_request_client = require("./access-request-client");
+var import_endpoints = require("./endpoints");
+var import_errors = require("./errors");
+var import_personal_server_read = require("./personal-server-read");
+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 import_errors.DirectConfigError(
+      "appPrivateKey must be a 0x-prefixed 32-byte hex string"
+    );
+  }
+  if (!config.scopes || config.scopes.length === 0) {
+    throw new import_errors.DirectConfigError("At least one scope is required");
+  }
+  for (const scope of config.scopes) {
+    (0, import_scopes.parseScope)(scope);
+  }
+  const env = config.env ?? "production";
+  const endpoints = {
+    ...(0, import_endpoints.getDirectEndpoints)(env),
+    ...config.endpoints
+  };
+  const account = (0, import_accounts.privateKeyToAccount)(privateKey);
+  const signMessage = (message) => account.signMessage({ message });
+  const signTypedData = account.signTypedData;
+  const chainId = endpoints.chainId;
+  const accessRequestClient = config.accessRequestClient ?? (0, import_access_request_client.createDefaultAccessRequestClient)({
+    baseUrl: endpoints.accessRequestBaseUrl,
+    approvalBaseUrl: endpoints.approvalAppBaseUrl,
+    fetchFn: config.fetchFn
+  });
+  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 import_errors.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 (0, import_personal_server_read.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
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDirectDataController
+});
+//# sourceMappingURL=controller.cjs.map

package/dist/direct/controller.cjs.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    });\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.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Direct Data Controller — the server-side facade for the two-tab Data
+ * Portability flow.
+ *
+ * @remarks
+ * One controller owns an app's private key, source, scopes, app identity, and
+ * payment flow. It exposes the three methods the builder guide documents:
+ *
+ * - {@link DirectDataController.createAccessRequest} — start an approval request.
+ * - {@link DirectDataController.getAccessRequestStatus} — poll while the Vana tab is open.
+ * - {@link DirectDataController.readApprovedData} — read from the Personal Server,
+ *   handling 402 Payment Required.
+ *
+ * Access requests are created through the Vana Account access-request API; the
+ * Personal Server read uses Web3Signed auth; and payment uses the DPv2 escrow
+ * surface (`protocol/escrow`) — when a read returns `402`, the controller signs
+ * a `GenericPayment` with the app key, settles it through the escrow gateway,
+ * and retries.
+ *
+ * @category Direct
+ * @module direct/controller
+ */
+import { type FetchLike } from "./access-request-client";
+import { type EscrowPaymentConfig } from "./escrow-payment";
+import { type PersonalServerFetch } from "./personal-server-read";
+import type { AccessRequest, AccessRequestClient, AccessRequestStatus, ApprovedDataResult, AppIdentity, DirectAppConfig, DirectEnv, DirectServiceEndpoints } from "./types";
+/** Configuration for {@link createDirectDataController}. */
+export interface DirectDataControllerConfig {
+    /** Target environment. Defaults to `"production"`. */
+    env?: DirectEnv;
+    /**
+     * The app private key (`0x`-prefixed, 32 bytes). Server-side only — this key
+     * is the app's on-chain identity and is never exposed to the browser.
+     */
+    appPrivateKey?: string;
+    /**
+     * @deprecated Use {@link DirectDataControllerConfig.appPrivateKey}. Accepted as
+     * a backwards-compatible alias; if both are set, `appPrivateKey` wins.
+     */
+    builderPrivateKey?: string;
+    /** App identity advertised during approval. */
+    app: DirectAppConfig;
+    /** Data source key (e.g. `"icloud_notes"`). */
+    source: string;
+    /** Scopes to request (e.g. `["icloud_notes.notes"]`). At least one required. */
+    scopes: string[];
+    /**
+     * Override the resolved service endpoints (partial). Useful for pointing at a
+     * non-standard deployment.
+     */
+    endpoints?: Partial<DirectServiceEndpoints>;
+    /**
+     * Client for the Vana Account access-request API. Defaults to a client against
+     * the resolved Vana Account endpoints; inject your own to point at a custom
+     * deployment or to supply a test double.
+     */
+    accessRequestClient?: AccessRequestClient;
+    /**
+     * Escrow settlement config used when a Personal Server read returns `402`.
+     *
+     * @remarks
+     * Wires the DPv2 escrow gateway (`protocol/escrow`). The controller supplies
+     * the EIP-712 `signTypedData` from the app key automatically, so you provide
+     * the gateway `client`, the `escrowContract` address, and (optionally) the
+     * `chainId` and a durable `nonceSource`. If omitted, a `402` from the Personal
+     * Server throws {@link PaymentRequiredError} carrying the amount/asset owed.
+     */
+    escrow?: DirectEscrowConfig;
+    /** `fetch` used by the default access-request client. Defaults to `globalThis.fetch`. */
+    fetchFn?: FetchLike;
+    /** `fetch` used for the Personal Server read. Defaults to `globalThis.fetch`. */
+    personalServerFetch?: PersonalServerFetch;
+}
+/**
+ * Controller-level escrow config — the {@link EscrowPaymentConfig} minus the
+ * `signTypedData` and `chainId` the controller injects itself.
+ */
+export interface DirectEscrowConfig extends Omit<EscrowPaymentConfig, "signTypedData" | "chainId"> {
+    /**
+     * Chain id for the EIP-712 domain. Defaults to the controller's environment
+     * (1480 for production, 14800 for dev).
+     */
+    chainId?: number;
+}
+/**
+ * Server-side controller for the direct Data Portability flow.
+ *
+ * @typeParam T - Shape of the data returned by {@link DirectDataController.readApprovedData}.
+ */
+export interface DirectDataController {
+    /** The on-chain address of the app, derived from `appPrivateKey`. */
+    readonly appAddress: string;
+    /**
+     * The app's on-chain address — the address to fund and inspect in the Builder
+     * activity report. Equivalent to {@link DirectDataController.appAddress}.
+     *
+     * @returns The app's `0x`-prefixed address.
+     */
+    getAppAddress(): string;
+    /**
+     * The app's full identity: its configured id/name/homepage plus the derived
+     * on-chain address. Useful for telling builders which app address to fund or
+     * look up.
+     *
+     * @returns `{ id, name, homepageUrl, address }`.
+     */
+    getAppIdentity(): AppIdentity;
+    /**
+     * Create an access request the user can approve.
+     *
+     * @param input - The post-approval return URL.
+     * @returns `{ requestId, approvalUrl, appAddress }`.
+     */
+    createAccessRequest(input: {
+        returnUrl: string;
+    }): Promise<AccessRequest>;
+    /**
+     * Fetch the current status of an access request.
+     *
+     * @param requestId - The `dcr_*` id from {@link DirectDataController.createAccessRequest}.
+     * @returns `{ status, personalServerUrl?, grantId?, scope? }`.
+     */
+    getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;
+    /**
+     * Read the approved data from the user's Personal Server.
+     *
+     * @remarks
+     * Resolves the request to its grant + Personal Server and performs a Web3Signed
+     * read. Hides the `402 Payment Required` flow by default: if a read needs
+     * payment and `escrow` is configured, it settles the grant via the escrow
+     * gateway and retries, attaching a {@link DirectPaymentReceipt} under
+     * `payment` so callers can inspect amount/asset/fee breakdown. If `escrow` is
+     * not configured, it throws {@link PaymentRequiredError} carrying the
+     * amount/asset owed.
+     *
+     * @param input - The `dcr_*` request id to read.
+     * @returns `{ scope, data, payment? }`.
+     * @throws {@link AccessNotApprovedError} if the request is not approved.
+     * @throws {@link PaymentRequiredError} if payment is required but unsettled.
+     */
+    readApprovedData<T = unknown>(input: {
+        requestId: string;
+    }): Promise<ApprovedDataResult<T>>;
+}
+/**
+ * Create a {@link DirectDataController}.
+ *
+ * @param config - Controller configuration (env, key, app identity, source, scopes).
+ * @returns A ready-to-use controller.
+ * @throws {@link DirectConfigError} when the key or scopes are invalid.
+ */
+export declare function createDirectDataController(config: DirectDataControllerConfig): DirectDataController;

package/dist/direct/controller.js

@@ -0,0 +1,109 @@
+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
+  });
+  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    });\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":[]}