@opendatalabs/vana-sdk 3.6.3 → 3.7.0

package/README.md

@@ -119,6 +119,10 @@ your **frontend** drives a two-tab approval flow with a React hook
 > `accessRequestClient` to target a custom deployment, and `escrow` config to wire
 > the escrow gateway.
 
+Use `network: "moksha"` to keep production app/API URLs while running escrow and
+chain-aware defaults against Moksha. `env: "dev"` remains for Vana's internal dev
+deployment and switches deployment URLs.
+
 ### Backend controller
 
 ```typescript
@@ -129,6 +133,7 @@ import { createEscrowGatewayClient } from "@opendatalabs/vana-sdk/node";
 
 export const vana = createDirectDataController({
   env: process.env.VANA_ENV === "dev" ? "dev" : "production",
+  network: process.env.VANA_NETWORK === "moksha" ? "moksha" : "mainnet",
   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,
   app: {
     id: "notes-lens",

package/dist/direct/controller.cjs

@@ -44,14 +44,17 @@ function createDirectDataController(config) {
     (0, import_scopes.parseScope)(scope);
   }
   const env = config.env ?? "production";
+  const network = config.network ?? (0, import_endpoints.getDirectDefaultNetwork)(env);
+  const defaultEndpoints = (0, import_endpoints.getDirectEndpoints)(env);
+  const chainId = config.endpoints?.chainId ?? (0, import_endpoints.getDirectNetworkChainId)(network);
   const endpoints = {
-    ...(0, import_endpoints.getDirectEndpoints)(env),
-    ...config.endpoints
+    ...defaultEndpoints,
+    ...config.endpoints,
+    chainId
   };
   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,

package/dist/direct/controller.cjs.map

@@ -1 +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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBA,sBAAoC;AAGpC,oBAA2B;AAC3B,mCAGO;AACP,uBAAmC;AACnC,oBAA0D;AAK1D,kCAGO;AA2IP,SAAS,gBAAgB,OAA6B;AACpD,SAAO,sBAAsB,KAAK,KAAK;AACzC;AASO,SAAS,2BACd,QACsB;AAGtB,QAAM,aAAa,OAAO,iBAAiB,OAAO;AAClD,MAAI,CAAC,cAAc,CAAC,gBAAgB,UAAU,GAAG;AAC/C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,OAAO,UAAU,OAAO,OAAO,WAAW,GAAG;AAChD,UAAM,IAAI,gCAAkB,gCAAgC;AAAA,EAC9D;AAEA,aAAW,SAAS,OAAO,QAAQ;AACjC,kCAAW,KAAK;AAAA,EAClB;AAEA,QAAM,MAAiB,OAAO,OAAO;AACrC,QAAM,YAAoC;AAAA,IACxC,OAAG,qCAAmB,GAAG;AAAA,IACzB,GAAG,OAAO;AAAA,EACZ;AAEA,QAAM,cAAU,qCAAoB,UAAiB;AACrD,QAAM,cAAgC,CAAC,YACrC,QAAQ,YAAY,EAAE,QAAQ,CAAC;AAGjC,QAAM,gBAAgB,QAAQ;AAC9B,QAAM,UAAU,UAAU;AAE1B,QAAM,sBACJ,OAAO,2BACP,+DAAiC;AAAA,IAC/B,SAAS,UAAU;AAAA,IACnB,iBAAiB,UAAU;AAAA,IAC3B,SAAS,OAAO;AAAA,IAChB,YAAY,QAAQ;AAAA,IACpB;AAAA,EACF,CAAC;AAEH,QAAM,SAA0C,OAAO,SACnD;AAAA,IACE,QAAQ,OAAO,OAAO;AAAA,IACtB,gBAAgB,OAAO,OAAO;AAAA,IAC9B,SAAS,OAAO,OAAO,WAAW;AAAA,IAClC,aAAa,OAAO,OAAO;AAAA,IAC3B;AAAA,EACF,IACA;AAEJ,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IAEpB,gBAAwB;AACtB,aAAO,QAAQ;AAAA,IACjB;AAAA,IAEA,iBAA8B;AAC5B,aAAO;AAAA,QACL,IAAI,OAAO,IAAI;AAAA,QACf,MAAM,OAAO,IAAI;AAAA,QACjB,aAAa,OAAO,IAAI;AAAA,QACxB,SAAS,QAAQ;AAAA,MACnB;AAAA,IACF;AAAA,IAEA,MAAM,oBAAoB,OAA+B;AACvD,aAAO,oBAAoB,oBAAoB;AAAA,QAC7C,YAAY,QAAQ;AAAA,QACpB,KAAK,OAAO;AAAA,QACZ,QAAQ,OAAO;AAAA,QACf,QAAQ,OAAO;AAAA,QACf,WAAW,MAAM;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,IAEA,MAAM,uBACJ,WAC8B;AAC9B,aAAO,oBAAoB,uBAAuB,SAAS;AAAA,IAC7D;AAAA,IAEA,MAAM,iBAA8B,OAED;AACjC,YAAM,SAAS,MAAM,oBAAoB;AAAA,QACvC,MAAM;AAAA,MACR;AACA,UACE,OAAO,WAAW,cAClB,CAAC,OAAO,qBACR,CAAC,OAAO,WACR,CAAC,OAAO,OACR;AACA,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,YACE,WAAW,MAAM;AAAA,YACjB,QAAQ,OAAO;AAAA,YACf,sBAAsB,QAAQ,OAAO,iBAAiB;AAAA,YACtD,YAAY,QAAQ,OAAO,OAAO;AAAA,YAClC,UAAU,QAAQ,OAAO,KAAK;AAAA,UAChC;AAAA,QACF;AAAA,MACF;AAEA,YAAM,SAAS,UAAM,oDAAuB;AAAA,QAC1C,mBAAmB,OAAO;AAAA,QAC1B,OAAO,OAAO;AAAA,QACd,SAAS,OAAO;AAAA,QAChB,cAAc,QAAQ;AAAA,QACtB;AAAA,QACA;AAAA,QACA,SAAS,OAAO;AAAA,MAClB,CAAC;AAED,aAAO;AAAA,QACL,OAAO,OAAO;AAAA,QACd,MAAM,OAAO;AAAA,QACb,SAAS,OAAO;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"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 {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} 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  DirectNetwork,\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   * Target Vana network for chain-aware defaults. Defaults to the selected\n   * environment's historical network (`mainnet` for production, `moksha` for\n   * dev). Use `network: \"moksha\"` with the default production env for\n   * production app/API URLs on testnet.\n   */\n  network?: DirectNetwork;\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 mainnet, 14800 for moksha).\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 network: DirectNetwork = config.network ?? getDirectDefaultNetwork(env);\n  const defaultEndpoints = getDirectEndpoints(env);\n  const chainId = config.endpoints?.chainId ?? getDirectNetworkChainId(network);\n  const endpoints: DirectServiceEndpoints = {\n    ...defaultEndpoints,\n    ...config.endpoints,\n    chainId,\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 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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBA,sBAAoC;AAGpC,oBAA2B;AAC3B,mCAGO;AACP,uBAIO;AACP,oBAA0D;AAK1D,kCAGO;AAmJP,SAAS,gBAAgB,OAA6B;AACpD,SAAO,sBAAsB,KAAK,KAAK;AACzC;AASO,SAAS,2BACd,QACsB;AAGtB,QAAM,aAAa,OAAO,iBAAiB,OAAO;AAClD,MAAI,CAAC,cAAc,CAAC,gBAAgB,UAAU,GAAG;AAC/C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,OAAO,UAAU,OAAO,OAAO,WAAW,GAAG;AAChD,UAAM,IAAI,gCAAkB,gCAAgC;AAAA,EAC9D;AAEA,aAAW,SAAS,OAAO,QAAQ;AACjC,kCAAW,KAAK;AAAA,EAClB;AAEA,QAAM,MAAiB,OAAO,OAAO;AACrC,QAAM,UAAyB,OAAO,eAAW,0CAAwB,GAAG;AAC5E,QAAM,uBAAmB,qCAAmB,GAAG;AAC/C,QAAM,UAAU,OAAO,WAAW,eAAW,0CAAwB,OAAO;AAC5E,QAAM,YAAoC;AAAA,IACxC,GAAG;AAAA,IACH,GAAG,OAAO;AAAA,IACV;AAAA,EACF;AAEA,QAAM,cAAU,qCAAoB,UAAiB;AACrD,QAAM,cAAgC,CAAC,YACrC,QAAQ,YAAY,EAAE,QAAQ,CAAC;AAGjC,QAAM,gBAAgB,QAAQ;AAC9B,QAAM,sBACJ,OAAO,2BACP,+DAAiC;AAAA,IAC/B,SAAS,UAAU;AAAA,IACnB,iBAAiB,UAAU;AAAA,IAC3B,SAAS,OAAO;AAAA,IAChB,YAAY,QAAQ;AAAA,IACpB;AAAA,EACF,CAAC;AAEH,QAAM,SAA0C,OAAO,SACnD;AAAA,IACE,QAAQ,OAAO,OAAO;AAAA,IACtB,gBAAgB,OAAO,OAAO;AAAA,IAC9B,SAAS,OAAO,OAAO,WAAW;AAAA,IAClC,aAAa,OAAO,OAAO;AAAA,IAC3B;AAAA,EACF,IACA;AAEJ,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IAEpB,gBAAwB;AACtB,aAAO,QAAQ;AAAA,IACjB;AAAA,IAEA,iBAA8B;AAC5B,aAAO;AAAA,QACL,IAAI,OAAO,IAAI;AAAA,QACf,MAAM,OAAO,IAAI;AAAA,QACjB,aAAa,OAAO,IAAI;AAAA,QACxB,SAAS,QAAQ;AAAA,MACnB;AAAA,IACF;AAAA,IAEA,MAAM,oBAAoB,OAA+B;AACvD,aAAO,oBAAoB,oBAAoB;AAAA,QAC7C,YAAY,QAAQ;AAAA,QACpB,KAAK,OAAO;AAAA,QACZ,QAAQ,OAAO;AAAA,QACf,QAAQ,OAAO;AAAA,QACf,WAAW,MAAM;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,IAEA,MAAM,uBACJ,WAC8B;AAC9B,aAAO,oBAAoB,uBAAuB,SAAS;AAAA,IAC7D;AAAA,IAEA,MAAM,iBAA8B,OAED;AACjC,YAAM,SAAS,MAAM,oBAAoB;AAAA,QACvC,MAAM;AAAA,MACR;AACA,UACE,OAAO,WAAW,cAClB,CAAC,OAAO,qBACR,CAAC,OAAO,WACR,CAAC,OAAO,OACR;AACA,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,YACE,WAAW,MAAM;AAAA,YACjB,QAAQ,OAAO;AAAA,YACf,sBAAsB,QAAQ,OAAO,iBAAiB;AAAA,YACtD,YAAY,QAAQ,OAAO,OAAO;AAAA,YAClC,UAAU,QAAQ,OAAO,KAAK;AAAA,UAChC;AAAA,QACF;AAAA,MACF;AAEA,YAAM,SAAS,UAAM,oDAAuB;AAAA,QAC1C,mBAAmB,OAAO;AAAA,QAC1B,OAAO,OAAO;AAAA,QACd,SAAS,OAAO;AAAA,QAChB,cAAc,QAAQ;AAAA,QACtB;AAAA,QACA;AAAA,QACA,SAAS,OAAO;AAAA,MAClB,CAAC;AAED,aAAO;AAAA,QACL,OAAO,OAAO;AAAA,QACd,MAAM,OAAO;AAAA,QACb,SAAS,OAAO;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/direct/controller.d.ts

@@ -23,11 +23,18 @@
 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";
+import type { AccessRequest, AccessRequestClient, AccessRequestStatus, ApprovedDataResult, AppIdentity, DirectAppConfig, DirectEnv, DirectNetwork, DirectServiceEndpoints } from "./types";
 /** Configuration for {@link createDirectDataController}. */
 export interface DirectDataControllerConfig {
     /** Target environment. Defaults to `"production"`. */
     env?: DirectEnv;
+    /**
+     * Target Vana network for chain-aware defaults. Defaults to the selected
+     * environment's historical network (`mainnet` for production, `moksha` for
+     * dev). Use `network: "moksha"` with the default production env for
+     * production app/API URLs on testnet.
+     */
+    network?: DirectNetwork;
     /**
      * 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.
@@ -78,7 +85,7 @@ export interface DirectDataControllerConfig {
 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).
+     * (1480 for mainnet, 14800 for moksha).
      */
     chainId?: number;
 }

package/dist/direct/controller.js

@@ -3,7 +3,11 @@ import { parseScope } from "../protocol/scopes.js";
 import {
   createDefaultAccessRequestClient
 } from "./access-request-client.js";
-import { getDirectEndpoints } from "./endpoints.js";
+import {
+  getDirectDefaultNetwork,
+  getDirectEndpoints,
+  getDirectNetworkChainId
+} from "./endpoints.js";
 import { AccessNotApprovedError, DirectConfigError } from "./errors.js";
 import {
   readPersonalServerData
@@ -25,14 +29,17 @@ function createDirectDataController(config) {
     parseScope(scope);
   }
   const env = config.env ?? "production";
+  const network = config.network ?? getDirectDefaultNetwork(env);
+  const defaultEndpoints = getDirectEndpoints(env);
+  const chainId = config.endpoints?.chainId ?? getDirectNetworkChainId(network);
   const endpoints = {
-    ...getDirectEndpoints(env),
-    ...config.endpoints
+    ...defaultEndpoints,
+    ...config.endpoints,
+    chainId
   };
   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,

package/dist/direct/controller.js.map

@@ -1 +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":[]}
+{"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 {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} 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  DirectNetwork,\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   * Target Vana network for chain-aware defaults. Defaults to the selected\n   * environment's historical network (`mainnet` for production, `moksha` for\n   * dev). Use `network: \"moksha\"` with the default production env for\n   * production app/API URLs on testnet.\n   */\n  network?: DirectNetwork;\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 mainnet, 14800 for moksha).\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 network: DirectNetwork = config.network ?? getDirectDefaultNetwork(env);\n  const defaultEndpoints = getDirectEndpoints(env);\n  const chainId = config.endpoints?.chainId ?? getDirectNetworkChainId(network);\n  const endpoints: DirectServiceEndpoints = {\n    ...defaultEndpoints,\n    ...config.endpoints,\n    chainId,\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 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":"AAuBA,SAAS,2BAA2B;AAGpC,SAAS,kBAAkB;AAC3B;AAAA,EACE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,wBAAwB,yBAAyB;AAK1D;AAAA,EACE;AAAA,OAEK;AAmJP,SAAS,gBAAgB,OAA6B;AACpD,SAAO,sBAAsB,KAAK,KAAK;AACzC;AASO,SAAS,2BACd,QACsB;AAGtB,QAAM,aAAa,OAAO,iBAAiB,OAAO;AAClD,MAAI,CAAC,cAAc,CAAC,gBAAgB,UAAU,GAAG;AAC/C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,OAAO,UAAU,OAAO,OAAO,WAAW,GAAG;AAChD,UAAM,IAAI,kBAAkB,gCAAgC;AAAA,EAC9D;AAEA,aAAW,SAAS,OAAO,QAAQ;AACjC,eAAW,KAAK;AAAA,EAClB;AAEA,QAAM,MAAiB,OAAO,OAAO;AACrC,QAAM,UAAyB,OAAO,WAAW,wBAAwB,GAAG;AAC5E,QAAM,mBAAmB,mBAAmB,GAAG;AAC/C,QAAM,UAAU,OAAO,WAAW,WAAW,wBAAwB,OAAO;AAC5E,QAAM,YAAoC;AAAA,IACxC,GAAG;AAAA,IACH,GAAG,OAAO;AAAA,IACV;AAAA,EACF;AAEA,QAAM,UAAU,oBAAoB,UAAiB;AACrD,QAAM,cAAgC,CAAC,YACrC,QAAQ,YAAY,EAAE,QAAQ,CAAC;AAGjC,QAAM,gBAAgB,QAAQ;AAC9B,QAAM,sBACJ,OAAO,uBACP,iCAAiC;AAAA,IAC/B,SAAS,UAAU;AAAA,IACnB,iBAAiB,UAAU;AAAA,IAC3B,SAAS,OAAO;AAAA,IAChB,YAAY,QAAQ;AAAA,IACpB;AAAA,EACF,CAAC;AAEH,QAAM,SAA0C,OAAO,SACnD;AAAA,IACE,QAAQ,OAAO,OAAO;AAAA,IACtB,gBAAgB,OAAO,OAAO;AAAA,IAC9B,SAAS,OAAO,OAAO,WAAW;AAAA,IAClC,aAAa,OAAO,OAAO;AAAA,IAC3B;AAAA,EACF,IACA;AAEJ,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IAEpB,gBAAwB;AACtB,aAAO,QAAQ;AAAA,IACjB;AAAA,IAEA,iBAA8B;AAC5B,aAAO;AAAA,QACL,IAAI,OAAO,IAAI;AAAA,QACf,MAAM,OAAO,IAAI;AAAA,QACjB,aAAa,OAAO,IAAI;AAAA,QACxB,SAAS,QAAQ;AAAA,MACnB;AAAA,IACF;AAAA,IAEA,MAAM,oBAAoB,OAA+B;AACvD,aAAO,oBAAoB,oBAAoB;AAAA,QAC7C,YAAY,QAAQ;AAAA,QACpB,KAAK,OAAO;AAAA,QACZ,QAAQ,OAAO;AAAA,QACf,QAAQ,OAAO;AAAA,QACf,WAAW,MAAM;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,IAEA,MAAM,uBACJ,WAC8B;AAC9B,aAAO,oBAAoB,uBAAuB,SAAS;AAAA,IAC7D;AAAA,IAEA,MAAM,iBAA8B,OAED;AACjC,YAAM,SAAS,MAAM,oBAAoB;AAAA,QACvC,MAAM;AAAA,MACR;AACA,UACE,OAAO,WAAW,cAClB,CAAC,OAAO,qBACR,CAAC,OAAO,WACR,CAAC,OAAO,OACR;AACA,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,YACE,WAAW,MAAM;AAAA,YACjB,QAAQ,OAAO;AAAA,YACf,sBAAsB,QAAQ,OAAO,iBAAiB;AAAA,YACtD,YAAY,QAAQ,OAAO,OAAO;AAAA,YAClC,UAAU,QAAQ,OAAO,KAAK;AAAA,UAChC;AAAA,QACF;AAAA,MACF;AAEA,YAAM,SAAS,MAAM,uBAAuB;AAAA,QAC1C,mBAAmB,OAAO;AAAA,QAC1B,OAAO,OAAO;AAAA,QACd,SAAS,OAAO;AAAA,QAChB,cAAc,QAAQ;AAAA,QACtB;AAAA,QACA;AAAA,QACA,SAAS,OAAO;AAAA,MAClB,CAAC;AAED,aAAO;AAAA,QACL,OAAO,OAAO;AAAA,QACd,MAAM,OAAO;AAAA,QACb,SAAS,OAAO;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/direct/endpoints.cjs

@@ -20,7 +20,9 @@ var endpoints_exports = {};
 __export(endpoints_exports, {
   DEV_ENDPOINTS: () => DEV_ENDPOINTS,
   PRODUCTION_ENDPOINTS: () => PRODUCTION_ENDPOINTS,
-  getDirectEndpoints: () => getDirectEndpoints
+  getDirectDefaultNetwork: () => getDirectDefaultNetwork,
+  getDirectEndpoints: () => getDirectEndpoints,
+  getDirectNetworkChainId: () => getDirectNetworkChainId
 });
 module.exports = __toCommonJS(endpoints_exports);
 const PRODUCTION_ENDPOINTS = {
@@ -34,12 +36,23 @@ const DEV_ENDPOINTS = {
   approvalAppBaseUrl: "https://app-dev.vana.org"
 };
 function getDirectEndpoints(env) {
-  return env === "dev" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;
+  if (env === "dev") {
+    return DEV_ENDPOINTS;
+  }
+  return PRODUCTION_ENDPOINTS;
+}
+function getDirectDefaultNetwork(env) {
+  return env === "dev" ? "moksha" : "mainnet";
+}
+function getDirectNetworkChainId(network) {
+  return network === "moksha" ? 14800 : 1480;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEV_ENDPOINTS,
   PRODUCTION_ENDPOINTS,
-  getDirectEndpoints
+  getDirectDefaultNetwork,
+  getDirectEndpoints,
+  getDirectNetworkChainId
 });
 //# sourceMappingURL=endpoints.cjs.map

package/dist/direct/endpoints.cjs.map

@@ -1 +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":[]}
+{"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\n * against Vana's internal dev stack. Use the controller `network` option for\n * chain selection without changing deployment URLs.\n *\n * @category Direct\n * @module direct/endpoints\n */\n\nimport type { DirectEnv, DirectNetwork, 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/** Internal dev stack 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  if (env === \"dev\") {\n    return DEV_ENDPOINTS;\n  }\n\n  return PRODUCTION_ENDPOINTS;\n}\n\n/**\n * Resolve the default network for a deployment environment.\n *\n * @param env - Target deployment environment.\n * @returns The network historically paired with that deployment.\n */\nexport function getDirectDefaultNetwork(env: DirectEnv): DirectNetwork {\n  return env === \"dev\" ? \"moksha\" : \"mainnet\";\n}\n\n/**\n * Resolve the Vana chain id for a network.\n *\n * @param network - Target Vana network.\n * @returns The network chain id.\n */\nexport function getDirectNetworkChainId(network: DirectNetwork): number {\n  return network === \"moksha\" ? 14800 : 1480;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeO,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,MAAI,QAAQ,OAAO;AACjB,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAQO,SAAS,wBAAwB,KAA+B;AACrE,SAAO,QAAQ,QAAQ,WAAW;AACpC;AAQO,SAAS,wBAAwB,SAAgC;AACtE,SAAO,YAAY,WAAW,QAAQ;AACxC;","names":[]}

package/dist/direct/endpoints.d.ts

@@ -2,16 +2,17 @@
  * 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.
+ * The SDK ships production defaults; pass `env: "dev"` only when testing
+ * against Vana's internal dev stack. Use the controller `network` option for
+ * chain selection without changing deployment URLs.
  *
  * @category Direct
  * @module direct/endpoints
  */
-import type { DirectEnv, DirectServiceEndpoints } from "./types";
+import type { DirectEnv, DirectNetwork, DirectServiceEndpoints } from "./types";
 /** Production (mainnet) service URLs. */
 export declare const PRODUCTION_ENDPOINTS: DirectServiceEndpoints;
-/** Dev/testnet (moksha) service URLs. */
+/** Internal dev stack service URLs. */
 export declare const DEV_ENDPOINTS: DirectServiceEndpoints;
 /**
  * Resolve the default {@link DirectServiceEndpoints} for an environment.
@@ -20,3 +21,17 @@ export declare const DEV_ENDPOINTS: DirectServiceEndpoints;
  * @returns The default endpoints for that environment.
  */
 export declare function getDirectEndpoints(env: DirectEnv): DirectServiceEndpoints;
+/**
+ * Resolve the default network for a deployment environment.
+ *
+ * @param env - Target deployment environment.
+ * @returns The network historically paired with that deployment.
+ */
+export declare function getDirectDefaultNetwork(env: DirectEnv): DirectNetwork;
+/**
+ * Resolve the Vana chain id for a network.
+ *
+ * @param network - Target Vana network.
+ * @returns The network chain id.
+ */
+export declare function getDirectNetworkChainId(network: DirectNetwork): number;

package/dist/direct/endpoints.js

@@ -9,11 +9,22 @@ const DEV_ENDPOINTS = {
   approvalAppBaseUrl: "https://app-dev.vana.org"
 };
 function getDirectEndpoints(env) {
-  return env === "dev" ? DEV_ENDPOINTS : PRODUCTION_ENDPOINTS;
+  if (env === "dev") {
+    return DEV_ENDPOINTS;
+  }
+  return PRODUCTION_ENDPOINTS;
+}
+function getDirectDefaultNetwork(env) {
+  return env === "dev" ? "moksha" : "mainnet";
+}
+function getDirectNetworkChainId(network) {
+  return network === "moksha" ? 14800 : 1480;
 }
 export {
   DEV_ENDPOINTS,
   PRODUCTION_ENDPOINTS,
-  getDirectEndpoints
+  getDirectDefaultNetwork,
+  getDirectEndpoints,
+  getDirectNetworkChainId
 };
 //# sourceMappingURL=endpoints.js.map

package/dist/direct/endpoints.js.map

@@ -1 +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":[]}
+{"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\n * against Vana's internal dev stack. Use the controller `network` option for\n * chain selection without changing deployment URLs.\n *\n * @category Direct\n * @module direct/endpoints\n */\n\nimport type { DirectEnv, DirectNetwork, 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/** Internal dev stack 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  if (env === \"dev\") {\n    return DEV_ENDPOINTS;\n  }\n\n  return PRODUCTION_ENDPOINTS;\n}\n\n/**\n * Resolve the default network for a deployment environment.\n *\n * @param env - Target deployment environment.\n * @returns The network historically paired with that deployment.\n */\nexport function getDirectDefaultNetwork(env: DirectEnv): DirectNetwork {\n  return env === \"dev\" ? \"moksha\" : \"mainnet\";\n}\n\n/**\n * Resolve the Vana chain id for a network.\n *\n * @param network - Target Vana network.\n * @returns The network chain id.\n */\nexport function getDirectNetworkChainId(network: DirectNetwork): number {\n  return network === \"moksha\" ? 14800 : 1480;\n}\n"],"mappings":"AAeO,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,MAAI,QAAQ,OAAO;AACjB,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAQO,SAAS,wBAAwB,KAA+B;AACrE,SAAO,QAAQ,QAAQ,WAAW;AACpC;AAQO,SAAS,wBAAwB,SAAgC;AACtE,SAAO,YAAY,WAAW,QAAQ;AACxC;","names":[]}

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

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

package/dist/direct/types.cjs.map

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

package/dist/direct/types.d.ts

@@ -15,10 +15,17 @@ import type { EscrowAccessRecord } from "../protocol/escrow";
  * Target environment for a {@link DirectDataController}.
  *
  * - `"production"` — Vana mainnet stack (default service URLs).
- * - `"dev"` — Vana internal dev/testnet stack. Use only when testing against
+ * - `"dev"` — Vana internal dev stack. Use only when testing against
  *   Vana's dev infrastructure.
  */
 export type DirectEnv = "dev" | "production";
+/**
+ * Vana network used for chain-aware Direct defaults.
+ *
+ * - `"mainnet"` — Vana mainnet (`chainId` 1480).
+ * - `"moksha"` — Moksha testnet (`chainId` 14800).
+ */
+export type DirectNetwork = "mainnet" | "moksha";
 /**
  * App identity advertised to users during approval and attributed in Builder
  * League activity reports.
@@ -40,7 +47,7 @@ export interface AppIdentity extends DirectAppConfig {
     address: string;
 }
 /**
- * Resolved service URLs for a given {@link DirectEnv}.
+ * Resolved service URLs and chain id for a given {@link DirectEnv}.
  *
  * @remarks
  * Centralizes the per-environment base URLs the controller talks to. Each can

package/dist/direct/types.js.map

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

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeGrantPayment,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectAppConfig,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAKO;AACP,kCASO;AAEP,4BASO;AACP,uBAIO;AAGP,oBAKO;AAoBP,mBAA6B;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeGrantPayment,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAKO;AACP,kCASO;AAEP,4BASO;AACP,uBAIO;AAGP,oBAKO;AAqBP,mBAA6B;","names":[]}

package/dist/server.d.ts

@@ -28,5 +28,5 @@ export { buildPersonalServerDataReadRequest, readPersonalServerData, parsePerson
 export { authorizeGrantPayment, toDirectPaymentReceipt, toDirectFeeBreakdown, createDefaultNonceSource, GRANT_OP_TYPE, type EscrowPaymentConfig, type SignTypedDataFn, type PaymentNonceSource, } from "./direct/escrow-payment";
 export { getDirectEndpoints, PRODUCTION_ENDPOINTS, DEV_ENDPOINTS, } from "./direct/endpoints";
 export { DirectConfigError, AccessNotApprovedError, PersonalServerReadError, PaymentRequiredError, } from "./direct/errors";
-export type { DirectEnv, DirectAppConfig, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectFeeBreakdown, } from "./direct/types";
+export type { DirectEnv, DirectNetwork, DirectAppConfig, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectFeeBreakdown, } from "./direct/types";
 export { DirectOpType } from "./direct/types";

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeGrantPayment,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectAppConfig,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":"AAyBA;AAAA,EACE;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAoBP,SAAS,oBAAoB;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeGrantPayment,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":"AAyBA;AAAA,EACE;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAqBP,SAAS,oBAAoB;","names":[]}

package/package.json

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