@opendatalabs/vana-sdk 3.20.1 → 3.22.0

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 { parseScopeEntry } from \"../protocol/scope-actions\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport {\n  AccessNotApprovedError,\n  DirectConfigError,\n  ScopeNotApprovedError,\n} from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n  ForegroundDelivery,\n  MultiScopeDataResult,\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  /**\n   * Grant scope entries to request. At least one required.\n   *\n   * Each entry is `[operation:]scope` (see `parseScopeEntry`): a bare entry\n   * such as `\"icloud_notes.notes\"` requests read, and `\"write:coach.weekly\"`\n   * requests write. The entries are carried through to the access request\n   * verbatim and become the grant's `scopes`, so a request can mix both\n   * (`[\"oura.sleep\", \"coach.weekly\", \"write:coach.weekly\"]`).\n   *\n   * The scope part must be a concrete `{source}.{category}[.{subcategory}]`\n   * scope: this flow reads approved scopes back one by one, so wildcard\n   * patterns (`chatgpt.*`, `write:chatgpt.*`) are not accepted here for\n   * either operation.\n   */\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.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<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   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\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 and optional create retry key.\n   * @returns The request id, HTTPS approval URL, and — for a pending deep Direct\n   * request on mobile — an optional HTTPS `mobileContinuationUrl`.\n   */\n  createAccessRequest(input: {\n    returnUrl: string;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Stable retry key when the caller retries after an uncertain response.\n     * Each create without one gets its own generated key.\n     */\n    idempotencyKey?: string;\n  }): 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?, scopes? }`.\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, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * A request can approve several scopes. This reads **one** of them — `scope`\n   * when given, otherwise the first approved scope. Use\n   * {@link DirectDataController.readAllApprovedData} to read them all.\n   *\n   * Acknowledging moves the DCR to `completed`, which is terminal and no longer\n   * read-ready. To read several scopes with your own loop, pass\n   * `acknowledge: false` on every call but the last.\n   *\n   * @param input - The `dcr_*` request id, the optional `scope` to read, and an\n   *   optional `acknowledge` flag (default `true`).\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link ScopeNotApprovedError} if `scope` is not an approved scope.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n    scope?: string;\n    acknowledge?: boolean;\n  }): Promise<ApprovedDataResult<T>>;\n\n  /**\n   * Read every scope the user approved on a request.\n   *\n   * @remarks\n   * Reads the scopes in approval order, then acknowledges the DCR **once**,\n   * after the last read — acknowledging earlier would move the request to\n   * `completed` and make the remaining scopes unreadable.\n   *\n   * Each scope is a separate Personal Server read that settles its own\n   * `data_access` fee from escrow, so reading N scopes costs N times a\n   * single-scope read. The one-off registration fee is charged per grant, not\n   * per scope.\n   *\n   * A scope that fails does not abort the rest: successes land in `results` and\n   * failures in `errors`, because the fees for earlier scopes are already spent.\n   * If any scope fails the request is left unacknowledged, so the scopes that\n   * failed stay retryable — read them with `readApprovedData({ scope })` and\n   * acknowledge on the last one.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ results, errors }`, both keyed by scope.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   */\n  readAllApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<MultiScopeDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\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 is missing or malformed, when\n * `scopes` is empty, or when no escrow contract can be resolved.\n * @throws InvalidScopeEntryError when a `scopes` entry does not fit the\n * `[operation:]scope` grammar (an unknown operation prefix such as `delete:`).\n * @throws ZodError when the scope part of an entry is not a valid scope.\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. Each\n  // element is a grant scope entry (`[operation:]scope`), so the operation\n  // prefix is stripped first and only the scope part is checked against the\n  // scope grammar — `write:coach.weekly` is a valid write-grant request, and\n  // an unknown operation (`delete:x`) throws rather than being taken as read.\n  // The entries themselves are passed through to the access request verbatim,\n  // prefix included.\n  for (const entry of config.scopes) {\n    parseScope(parseScopeEntry(entry).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      env,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\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        network,\n        ...(input.foregroundDelivery !== undefined\n          ? { foregroundDelivery: input.foregroundDelivery }\n          : {}),\n        ...(input.idempotencyKey !== undefined\n          ? { idempotencyKey: input.idempotencyKey }\n          : {}),\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      scope?: string;\n      acknowledge?: boolean;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scope = resolveRequestedScope(status, input.scope);\n\n      const result = await readScope<T>(status, scope);\n      if (input.acknowledge !== false) {\n        await acknowledgeQuietly(input.requestId);\n      }\n      return result;\n    },\n\n    async readAllApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<MultiScopeDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scopes = approvedScopes(status);\n\n      const results: Record<string, ApprovedDataResult<T>> = {};\n      const errors: Record<string, Error> = {};\n      // Sequential, not parallel: each read settles its own escrow payment and\n      // the default nonce source is process-local, so concurrent reads would\n      // race on the payment nonce.\n      for (const scope of scopes) {\n        try {\n          results[scope] = await readScope<T>(status, scope);\n        } catch (error) {\n          errors[scope] =\n            error instanceof Error ? error : new Error(String(error));\n        }\n      }\n\n      // Acknowledge only after the last read, and only if every scope read —\n      // acking moves the DCR to `completed`, which is terminal and no longer\n      // read-ready, so acking on a partial failure would make the scope that\n      // failed impossible to retry.\n      if (Object.keys(errors).length === 0) {\n        await acknowledgeQuietly(input.requestId);\n      }\n\n      return { results, errors };\n    },\n  };\n\n  async function requireReadReady(\n    requestId: string,\n  ): Promise<AccessRequestStatus> {\n    const status = await accessRequestClient.getAccessRequestStatus(requestId);\n    // `scope` and `scopes` are both optional on the public status type, and a\n    // client may return either one — require at least one approved scope rather\n    // than the singular field specifically.\n    if (\n      !isReadReadyStatus(status.status) ||\n      !status.personalServerUrl ||\n      !status.grantId ||\n      approvedScopes(status).length === 0\n    ) {\n      throw new AccessNotApprovedError(\n        \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n        {\n          requestId,\n          status: status.status,\n          hasPersonalServerUrl: Boolean(status.personalServerUrl),\n          hasGrantId: Boolean(status.grantId),\n          hasScope: approvedScopes(status).length > 0,\n        },\n      );\n    }\n    return status;\n  }\n\n  /** Approved scopes in approval order, falling back to the single `scope`. */\n  function approvedScopes(status: AccessRequestStatus): string[] {\n    if (status.scopes && status.scopes.length > 0) return status.scopes;\n    return status.scope ? [status.scope] : [];\n  }\n\n  /**\n   * Resolve which scope to read. Rejects an unapproved scope up front so it\n   * never reaches the Personal Server and never settles a fee.\n   */\n  function resolveRequestedScope(\n    status: AccessRequestStatus,\n    requested?: string,\n  ): string {\n    const scopes = approvedScopes(status);\n    if (requested === undefined) return scopes[0];\n    if (!scopes.includes(requested)) {\n      throw new ScopeNotApprovedError(\n        `Scope \"${requested}\" is not approved on this request`,\n        { requestedScope: requested, approvedScopes: scopes },\n      );\n    }\n    return requested;\n  }\n\n  async function readScope<T>(\n    status: AccessRequestStatus,\n    scope: string,\n  ): Promise<ApprovedDataResult<T>> {\n    const result = await readPersonalServerData({\n      personalServerUrl: status.personalServerUrl as string,\n      scope,\n      grantId: status.grantId as string,\n      payerAddress: account.address,\n      signMessage,\n      escrow,\n      fetchFn: config.personalServerFetch,\n      transportRetry: config.personalServerTransportRetry,\n    });\n    return { scope, data: result.data as T, payment: result.payment };\n  }\n\n  async function acknowledgeQuietly(requestId: string): Promise<void> {\n    try {\n      await accessRequestClient.acknowledgeRead?.(requestId);\n    } catch {\n      // The read already succeeded; ack only drives Vana Web completion UX.\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 { parseScopeEntry } from \"../protocol/scope-actions\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  validateAccessRequestQuestions,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport {\n  AccessNotApprovedError,\n  DirectConfigError,\n  ScopeNotApprovedError,\n} from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestQuestion,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n  ForegroundDelivery,\n  MultiScopeDataResult,\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  /**\n   * Grant scope entries to request. At least one required.\n   *\n   * Each entry is `[operation:]scope` (see `parseScopeEntry`): a bare entry\n   * such as `\"icloud_notes.notes\"` requests read, and `\"write:coach.weekly\"`\n   * requests write. The entries are carried through to the access request\n   * verbatim and become the grant's `scopes`, so a request can mix both\n   * (`[\"oura.sleep\", \"coach.weekly\", \"write:coach.weekly\"]`).\n   *\n   * The scope part must be a concrete `{source}.{category}[.{subcategory}]`\n   * scope: this flow reads approved scopes back one by one, so wildcard\n   * patterns (`chatgpt.*`, `write:chatgpt.*`) are not accepted here for\n   * either operation.\n   */\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.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<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   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\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 and optional create retry key.\n   * @returns The request id, HTTPS approval URL, and — for a pending deep Direct\n   * request on mobile — an optional HTTPS `mobileContinuationUrl`.\n   */\n  createAccessRequest(input: {\n    returnUrl: string;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Derivative questions to carry on the request (1 to 4). Each question\n     * asks the user's Personal Server to compute its `derivedScope` from\n     * `sourceScopes` the app never reads; the derived scope must also appear\n     * in the controller's `scopes` as a bare read entry. Validated eagerly\n     * against the configured scopes before the request is sent. See\n     * {@link AccessRequestQuestion}.\n     */\n    questions?: AccessRequestQuestion[];\n    /**\n     * Stable retry key when the caller retries after an uncertain response.\n     * Each create without one gets its own generated key.\n     */\n    idempotencyKey?: string;\n  }): 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?, scopes? }`.\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, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * A request can approve several scopes. This reads **one** of them — `scope`\n   * when given, otherwise the first approved scope. Use\n   * {@link DirectDataController.readAllApprovedData} to read them all.\n   *\n   * Acknowledging moves the DCR to `completed`, which is terminal and no longer\n   * read-ready. To read several scopes with your own loop, pass\n   * `acknowledge: false` on every call but the last.\n   *\n   * @param input - The `dcr_*` request id, the optional `scope` to read, and an\n   *   optional `acknowledge` flag (default `true`).\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link ScopeNotApprovedError} if `scope` is not an approved scope.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n    scope?: string;\n    acknowledge?: boolean;\n  }): Promise<ApprovedDataResult<T>>;\n\n  /**\n   * Read every scope the user approved on a request.\n   *\n   * @remarks\n   * Reads the scopes in approval order, then acknowledges the DCR **once**,\n   * after the last read — acknowledging earlier would move the request to\n   * `completed` and make the remaining scopes unreadable.\n   *\n   * Each scope is a separate Personal Server read that settles its own\n   * `data_access` fee from escrow, so reading N scopes costs N times a\n   * single-scope read. The one-off registration fee is charged per grant, not\n   * per scope.\n   *\n   * A scope that fails does not abort the rest: successes land in `results` and\n   * failures in `errors`, because the fees for earlier scopes are already spent.\n   * If any scope fails the request is left unacknowledged, so the scopes that\n   * failed stay retryable — read them with `readApprovedData({ scope })` and\n   * acknowledge on the last one.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ results, errors }`, both keyed by scope.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   */\n  readAllApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<MultiScopeDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\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 is missing or malformed, when\n * `scopes` is empty, or when no escrow contract can be resolved.\n * @throws InvalidScopeEntryError when a `scopes` entry does not fit the\n * `[operation:]scope` grammar (an unknown operation prefix such as `delete:`).\n * @throws ZodError when the scope part of an entry is not a valid scope.\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. Each\n  // element is a grant scope entry (`[operation:]scope`), so the operation\n  // prefix is stripped first and only the scope part is checked against the\n  // scope grammar — `write:coach.weekly` is a valid write-grant request, and\n  // an unknown operation (`delete:x`) throws rather than being taken as read.\n  // The entries themselves are passed through to the access request verbatim,\n  // prefix included.\n  for (const entry of config.scopes) {\n    parseScope(parseScopeEntry(entry).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      env,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\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      // Fail fast even with an injected client: a malformed question would be\n      // rejected by the access-request service anyway, after a signed round\n      // trip.\n      if (input.questions !== undefined) {\n        validateAccessRequestQuestions(input.questions, config.scopes);\n      }\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        network,\n        ...(input.foregroundDelivery !== undefined\n          ? { foregroundDelivery: input.foregroundDelivery }\n          : {}),\n        ...(input.questions !== undefined\n          ? { questions: input.questions }\n          : {}),\n        ...(input.idempotencyKey !== undefined\n          ? { idempotencyKey: input.idempotencyKey }\n          : {}),\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      scope?: string;\n      acknowledge?: boolean;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scope = resolveRequestedScope(status, input.scope);\n\n      const result = await readScope<T>(status, scope);\n      if (input.acknowledge !== false) {\n        await acknowledgeQuietly(input.requestId);\n      }\n      return result;\n    },\n\n    async readAllApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<MultiScopeDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scopes = approvedScopes(status);\n\n      const results: Record<string, ApprovedDataResult<T>> = {};\n      const errors: Record<string, Error> = {};\n      // Sequential, not parallel: each read settles its own escrow payment and\n      // the default nonce source is process-local, so concurrent reads would\n      // race on the payment nonce.\n      for (const scope of scopes) {\n        try {\n          results[scope] = await readScope<T>(status, scope);\n        } catch (error) {\n          errors[scope] =\n            error instanceof Error ? error : new Error(String(error));\n        }\n      }\n\n      // Acknowledge only after the last read, and only if every scope read —\n      // acking moves the DCR to `completed`, which is terminal and no longer\n      // read-ready, so acking on a partial failure would make the scope that\n      // failed impossible to retry.\n      if (Object.keys(errors).length === 0) {\n        await acknowledgeQuietly(input.requestId);\n      }\n\n      return { results, errors };\n    },\n  };\n\n  async function requireReadReady(\n    requestId: string,\n  ): Promise<AccessRequestStatus> {\n    const status = await accessRequestClient.getAccessRequestStatus(requestId);\n    // `scope` and `scopes` are both optional on the public status type, and a\n    // client may return either one — require at least one approved scope rather\n    // than the singular field specifically.\n    if (\n      !isReadReadyStatus(status.status) ||\n      !status.personalServerUrl ||\n      !status.grantId ||\n      approvedScopes(status).length === 0\n    ) {\n      throw new AccessNotApprovedError(\n        \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n        {\n          requestId,\n          status: status.status,\n          hasPersonalServerUrl: Boolean(status.personalServerUrl),\n          hasGrantId: Boolean(status.grantId),\n          hasScope: approvedScopes(status).length > 0,\n        },\n      );\n    }\n    return status;\n  }\n\n  /** Approved scopes in approval order, falling back to the single `scope`. */\n  function approvedScopes(status: AccessRequestStatus): string[] {\n    if (status.scopes && status.scopes.length > 0) return status.scopes;\n    return status.scope ? [status.scope] : [];\n  }\n\n  /**\n   * Resolve which scope to read. Rejects an unapproved scope up front so it\n   * never reaches the Personal Server and never settles a fee.\n   */\n  function resolveRequestedScope(\n    status: AccessRequestStatus,\n    requested?: string,\n  ): string {\n    const scopes = approvedScopes(status);\n    if (requested === undefined) return scopes[0];\n    if (!scopes.includes(requested)) {\n      throw new ScopeNotApprovedError(\n        `Scope \"${requested}\" is not approved on this request`,\n        { requestedScope: requested, approvedScopes: scopes },\n      );\n    }\n    return requested;\n  }\n\n  async function readScope<T>(\n    status: AccessRequestStatus,\n    scope: string,\n  ): Promise<ApprovedDataResult<T>> {\n    const result = await readPersonalServerData({\n      personalServerUrl: status.personalServerUrl as string,\n      scope,\n      grantId: status.grantId as string,\n      payerAddress: account.address,\n      signMessage,\n      escrow,\n      fetchFn: config.personalServerFetch,\n      transportRetry: config.personalServerTransportRetry,\n    });\n    return { scope, data: result.data as T, payment: result.payment };\n  }\n\n  async function acknowledgeQuietly(requestId: string): Promise<void> {\n    try {\n      await accessRequestClient.acknowledgeRead?.(requestId);\n    } catch {\n      // The read already succeeded; ack only drives Vana Web completion UX.\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/direct/controller.d.ts

@@ -23,7 +23,7 @@
 import { type FetchLike } from "./access-request-client.js";
 import { type EscrowPaymentConfig } from "./escrow-payment.js";
 import { type PersonalServerFetch, type PersonalServerTransportRetryOptions } from "./personal-server-read.js";
-import type { AccessRequest, AccessRequestClient, AccessRequestStatus, ApprovedDataResult, AppIdentity, DirectAppConfig, DirectEnv, DirectNetwork, DirectServiceEndpoints, ForegroundDelivery, MultiScopeDataResult } from "./types.js";
+import type { AccessRequest, AccessRequestClient, AccessRequestQuestion, AccessRequestStatus, ApprovedDataResult, AppIdentity, DirectAppConfig, DirectEnv, DirectNetwork, DirectServiceEndpoints, ForegroundDelivery, MultiScopeDataResult } from "./types.js";
 /** Configuration for {@link createDirectDataController}. */
 export interface DirectDataControllerConfig {
     /** Target environment. Defaults to `"production"`. */
@@ -149,6 +149,15 @@ export interface DirectDataController {
         returnUrl: string;
         /** Optional foreground mobile delivery callback. */
         foregroundDelivery?: ForegroundDelivery;
+        /**
+         * Derivative questions to carry on the request (1 to 4). Each question
+         * asks the user's Personal Server to compute its `derivedScope` from
+         * `sourceScopes` the app never reads; the derived scope must also appear
+         * in the controller's `scopes` as a bare read entry. Validated eagerly
+         * against the configured scopes before the request is sent. See
+         * {@link AccessRequestQuestion}.
+         */
+        questions?: AccessRequestQuestion[];
         /**
          * Stable retry key when the caller retries after an uncertain response.
          * Each create without one gets its own generated key.

package/dist/direct/controller.js

@@ -4,7 +4,8 @@ import { parseScopeEntry } from "../protocol/scope-actions.js";
 import { createEscrowGatewayClient } from "../protocol/escrow.js";
 import { CONTRACTS } from "../generated/addresses.js";
 import {
-  createDefaultAccessRequestClient
+  createDefaultAccessRequestClient,
+  validateAccessRequestQuestions
 } from "./access-request-client.js";
 import {
   getDirectDefaultNetwork,
@@ -86,6 +87,9 @@ function createDirectDataController(config) {
       };
     },
     async createAccessRequest(input) {
+      if (input.questions !== void 0) {
+        validateAccessRequestQuestions(input.questions, config.scopes);
+      }
       return accessRequestClient.createAccessRequest({
         appAddress: account.address,
         app: config.app,
@@ -94,6 +98,7 @@ function createDirectDataController(config) {
         returnUrl: input.returnUrl,
         network,
         ...input.foregroundDelivery !== void 0 ? { foregroundDelivery: input.foregroundDelivery } : {},
+        ...input.questions !== void 0 ? { questions: input.questions } : {},
         ...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {}
       });
     },

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 { parseScopeEntry } from \"../protocol/scope-actions\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport {\n  AccessNotApprovedError,\n  DirectConfigError,\n  ScopeNotApprovedError,\n} from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n  ForegroundDelivery,\n  MultiScopeDataResult,\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  /**\n   * Grant scope entries to request. At least one required.\n   *\n   * Each entry is `[operation:]scope` (see `parseScopeEntry`): a bare entry\n   * such as `\"icloud_notes.notes\"` requests read, and `\"write:coach.weekly\"`\n   * requests write. The entries are carried through to the access request\n   * verbatim and become the grant's `scopes`, so a request can mix both\n   * (`[\"oura.sleep\", \"coach.weekly\", \"write:coach.weekly\"]`).\n   *\n   * The scope part must be a concrete `{source}.{category}[.{subcategory}]`\n   * scope: this flow reads approved scopes back one by one, so wildcard\n   * patterns (`chatgpt.*`, `write:chatgpt.*`) are not accepted here for\n   * either operation.\n   */\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.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<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   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\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 and optional create retry key.\n   * @returns The request id, HTTPS approval URL, and — for a pending deep Direct\n   * request on mobile — an optional HTTPS `mobileContinuationUrl`.\n   */\n  createAccessRequest(input: {\n    returnUrl: string;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Stable retry key when the caller retries after an uncertain response.\n     * Each create without one gets its own generated key.\n     */\n    idempotencyKey?: string;\n  }): 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?, scopes? }`.\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, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * A request can approve several scopes. This reads **one** of them — `scope`\n   * when given, otherwise the first approved scope. Use\n   * {@link DirectDataController.readAllApprovedData} to read them all.\n   *\n   * Acknowledging moves the DCR to `completed`, which is terminal and no longer\n   * read-ready. To read several scopes with your own loop, pass\n   * `acknowledge: false` on every call but the last.\n   *\n   * @param input - The `dcr_*` request id, the optional `scope` to read, and an\n   *   optional `acknowledge` flag (default `true`).\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link ScopeNotApprovedError} if `scope` is not an approved scope.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n    scope?: string;\n    acknowledge?: boolean;\n  }): Promise<ApprovedDataResult<T>>;\n\n  /**\n   * Read every scope the user approved on a request.\n   *\n   * @remarks\n   * Reads the scopes in approval order, then acknowledges the DCR **once**,\n   * after the last read — acknowledging earlier would move the request to\n   * `completed` and make the remaining scopes unreadable.\n   *\n   * Each scope is a separate Personal Server read that settles its own\n   * `data_access` fee from escrow, so reading N scopes costs N times a\n   * single-scope read. The one-off registration fee is charged per grant, not\n   * per scope.\n   *\n   * A scope that fails does not abort the rest: successes land in `results` and\n   * failures in `errors`, because the fees for earlier scopes are already spent.\n   * If any scope fails the request is left unacknowledged, so the scopes that\n   * failed stay retryable — read them with `readApprovedData({ scope })` and\n   * acknowledge on the last one.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ results, errors }`, both keyed by scope.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   */\n  readAllApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<MultiScopeDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\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 is missing or malformed, when\n * `scopes` is empty, or when no escrow contract can be resolved.\n * @throws InvalidScopeEntryError when a `scopes` entry does not fit the\n * `[operation:]scope` grammar (an unknown operation prefix such as `delete:`).\n * @throws ZodError when the scope part of an entry is not a valid scope.\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. Each\n  // element is a grant scope entry (`[operation:]scope`), so the operation\n  // prefix is stripped first and only the scope part is checked against the\n  // scope grammar — `write:coach.weekly` is a valid write-grant request, and\n  // an unknown operation (`delete:x`) throws rather than being taken as read.\n  // The entries themselves are passed through to the access request verbatim,\n  // prefix included.\n  for (const entry of config.scopes) {\n    parseScope(parseScopeEntry(entry).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      env,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\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        network,\n        ...(input.foregroundDelivery !== undefined\n          ? { foregroundDelivery: input.foregroundDelivery }\n          : {}),\n        ...(input.idempotencyKey !== undefined\n          ? { idempotencyKey: input.idempotencyKey }\n          : {}),\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      scope?: string;\n      acknowledge?: boolean;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scope = resolveRequestedScope(status, input.scope);\n\n      const result = await readScope<T>(status, scope);\n      if (input.acknowledge !== false) {\n        await acknowledgeQuietly(input.requestId);\n      }\n      return result;\n    },\n\n    async readAllApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<MultiScopeDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scopes = approvedScopes(status);\n\n      const results: Record<string, ApprovedDataResult<T>> = {};\n      const errors: Record<string, Error> = {};\n      // Sequential, not parallel: each read settles its own escrow payment and\n      // the default nonce source is process-local, so concurrent reads would\n      // race on the payment nonce.\n      for (const scope of scopes) {\n        try {\n          results[scope] = await readScope<T>(status, scope);\n        } catch (error) {\n          errors[scope] =\n            error instanceof Error ? error : new Error(String(error));\n        }\n      }\n\n      // Acknowledge only after the last read, and only if every scope read —\n      // acking moves the DCR to `completed`, which is terminal and no longer\n      // read-ready, so acking on a partial failure would make the scope that\n      // failed impossible to retry.\n      if (Object.keys(errors).length === 0) {\n        await acknowledgeQuietly(input.requestId);\n      }\n\n      return { results, errors };\n    },\n  };\n\n  async function requireReadReady(\n    requestId: string,\n  ): Promise<AccessRequestStatus> {\n    const status = await accessRequestClient.getAccessRequestStatus(requestId);\n    // `scope` and `scopes` are both optional on the public status type, and a\n    // client may return either one — require at least one approved scope rather\n    // than the singular field specifically.\n    if (\n      !isReadReadyStatus(status.status) ||\n      !status.personalServerUrl ||\n      !status.grantId ||\n      approvedScopes(status).length === 0\n    ) {\n      throw new AccessNotApprovedError(\n        \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n        {\n          requestId,\n          status: status.status,\n          hasPersonalServerUrl: Boolean(status.personalServerUrl),\n          hasGrantId: Boolean(status.grantId),\n          hasScope: approvedScopes(status).length > 0,\n        },\n      );\n    }\n    return status;\n  }\n\n  /** Approved scopes in approval order, falling back to the single `scope`. */\n  function approvedScopes(status: AccessRequestStatus): string[] {\n    if (status.scopes && status.scopes.length > 0) return status.scopes;\n    return status.scope ? [status.scope] : [];\n  }\n\n  /**\n   * Resolve which scope to read. Rejects an unapproved scope up front so it\n   * never reaches the Personal Server and never settles a fee.\n   */\n  function resolveRequestedScope(\n    status: AccessRequestStatus,\n    requested?: string,\n  ): string {\n    const scopes = approvedScopes(status);\n    if (requested === undefined) return scopes[0];\n    if (!scopes.includes(requested)) {\n      throw new ScopeNotApprovedError(\n        `Scope \"${requested}\" is not approved on this request`,\n        { requestedScope: requested, approvedScopes: scopes },\n      );\n    }\n    return requested;\n  }\n\n  async function readScope<T>(\n    status: AccessRequestStatus,\n    scope: string,\n  ): Promise<ApprovedDataResult<T>> {\n    const result = await readPersonalServerData({\n      personalServerUrl: status.personalServerUrl as string,\n      scope,\n      grantId: status.grantId as string,\n      payerAddress: account.address,\n      signMessage,\n      escrow,\n      fetchFn: config.personalServerFetch,\n      transportRetry: config.personalServerTransportRetry,\n    });\n    return { scope, data: result.data as T, payment: result.payment };\n  }\n\n  async function acknowledgeQuietly(requestId: string): Promise<void> {\n    try {\n      await accessRequestClient.acknowledgeRead?.(requestId);\n    } catch {\n      // The read already succeeded; ack only drives Vana Web completion UX.\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 { parseScopeEntry } from \"../protocol/scope-actions\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  validateAccessRequestQuestions,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport {\n  AccessNotApprovedError,\n  DirectConfigError,\n  ScopeNotApprovedError,\n} from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestQuestion,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n  ForegroundDelivery,\n  MultiScopeDataResult,\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  /**\n   * Grant scope entries to request. At least one required.\n   *\n   * Each entry is `[operation:]scope` (see `parseScopeEntry`): a bare entry\n   * such as `\"icloud_notes.notes\"` requests read, and `\"write:coach.weekly\"`\n   * requests write. The entries are carried through to the access request\n   * verbatim and become the grant's `scopes`, so a request can mix both\n   * (`[\"oura.sleep\", \"coach.weekly\", \"write:coach.weekly\"]`).\n   *\n   * The scope part must be a concrete `{source}.{category}[.{subcategory}]`\n   * scope: this flow reads approved scopes back one by one, so wildcard\n   * patterns (`chatgpt.*`, `write:chatgpt.*`) are not accepted here for\n   * either operation.\n   */\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.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<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   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\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 and optional create retry key.\n   * @returns The request id, HTTPS approval URL, and — for a pending deep Direct\n   * request on mobile — an optional HTTPS `mobileContinuationUrl`.\n   */\n  createAccessRequest(input: {\n    returnUrl: string;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Derivative questions to carry on the request (1 to 4). Each question\n     * asks the user's Personal Server to compute its `derivedScope` from\n     * `sourceScopes` the app never reads; the derived scope must also appear\n     * in the controller's `scopes` as a bare read entry. Validated eagerly\n     * against the configured scopes before the request is sent. See\n     * {@link AccessRequestQuestion}.\n     */\n    questions?: AccessRequestQuestion[];\n    /**\n     * Stable retry key when the caller retries after an uncertain response.\n     * Each create without one gets its own generated key.\n     */\n    idempotencyKey?: string;\n  }): 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?, scopes? }`.\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, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * A request can approve several scopes. This reads **one** of them — `scope`\n   * when given, otherwise the first approved scope. Use\n   * {@link DirectDataController.readAllApprovedData} to read them all.\n   *\n   * Acknowledging moves the DCR to `completed`, which is terminal and no longer\n   * read-ready. To read several scopes with your own loop, pass\n   * `acknowledge: false` on every call but the last.\n   *\n   * @param input - The `dcr_*` request id, the optional `scope` to read, and an\n   *   optional `acknowledge` flag (default `true`).\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link ScopeNotApprovedError} if `scope` is not an approved scope.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n    scope?: string;\n    acknowledge?: boolean;\n  }): Promise<ApprovedDataResult<T>>;\n\n  /**\n   * Read every scope the user approved on a request.\n   *\n   * @remarks\n   * Reads the scopes in approval order, then acknowledges the DCR **once**,\n   * after the last read — acknowledging earlier would move the request to\n   * `completed` and make the remaining scopes unreadable.\n   *\n   * Each scope is a separate Personal Server read that settles its own\n   * `data_access` fee from escrow, so reading N scopes costs N times a\n   * single-scope read. The one-off registration fee is charged per grant, not\n   * per scope.\n   *\n   * A scope that fails does not abort the rest: successes land in `results` and\n   * failures in `errors`, because the fees for earlier scopes are already spent.\n   * If any scope fails the request is left unacknowledged, so the scopes that\n   * failed stay retryable — read them with `readApprovedData({ scope })` and\n   * acknowledge on the last one.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ results, errors }`, both keyed by scope.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   */\n  readAllApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<MultiScopeDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\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 is missing or malformed, when\n * `scopes` is empty, or when no escrow contract can be resolved.\n * @throws InvalidScopeEntryError when a `scopes` entry does not fit the\n * `[operation:]scope` grammar (an unknown operation prefix such as `delete:`).\n * @throws ZodError when the scope part of an entry is not a valid scope.\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. Each\n  // element is a grant scope entry (`[operation:]scope`), so the operation\n  // prefix is stripped first and only the scope part is checked against the\n  // scope grammar — `write:coach.weekly` is a valid write-grant request, and\n  // an unknown operation (`delete:x`) throws rather than being taken as read.\n  // The entries themselves are passed through to the access request verbatim,\n  // prefix included.\n  for (const entry of config.scopes) {\n    parseScope(parseScopeEntry(entry).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      env,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\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      // Fail fast even with an injected client: a malformed question would be\n      // rejected by the access-request service anyway, after a signed round\n      // trip.\n      if (input.questions !== undefined) {\n        validateAccessRequestQuestions(input.questions, config.scopes);\n      }\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        network,\n        ...(input.foregroundDelivery !== undefined\n          ? { foregroundDelivery: input.foregroundDelivery }\n          : {}),\n        ...(input.questions !== undefined\n          ? { questions: input.questions }\n          : {}),\n        ...(input.idempotencyKey !== undefined\n          ? { idempotencyKey: input.idempotencyKey }\n          : {}),\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      scope?: string;\n      acknowledge?: boolean;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scope = resolveRequestedScope(status, input.scope);\n\n      const result = await readScope<T>(status, scope);\n      if (input.acknowledge !== false) {\n        await acknowledgeQuietly(input.requestId);\n      }\n      return result;\n    },\n\n    async readAllApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<MultiScopeDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scopes = approvedScopes(status);\n\n      const results: Record<string, ApprovedDataResult<T>> = {};\n      const errors: Record<string, Error> = {};\n      // Sequential, not parallel: each read settles its own escrow payment and\n      // the default nonce source is process-local, so concurrent reads would\n      // race on the payment nonce.\n      for (const scope of scopes) {\n        try {\n          results[scope] = await readScope<T>(status, scope);\n        } catch (error) {\n          errors[scope] =\n            error instanceof Error ? error : new Error(String(error));\n        }\n      }\n\n      // Acknowledge only after the last read, and only if every scope read —\n      // acking moves the DCR to `completed`, which is terminal and no longer\n      // read-ready, so acking on a partial failure would make the scope that\n      // failed impossible to retry.\n      if (Object.keys(errors).length === 0) {\n        await acknowledgeQuietly(input.requestId);\n      }\n\n      return { results, errors };\n    },\n  };\n\n  async function requireReadReady(\n    requestId: string,\n  ): Promise<AccessRequestStatus> {\n    const status = await accessRequestClient.getAccessRequestStatus(requestId);\n    // `scope` and `scopes` are both optional on the public status type, and a\n    // client may return either one — require at least one approved scope rather\n    // than the singular field specifically.\n    if (\n      !isReadReadyStatus(status.status) ||\n      !status.personalServerUrl ||\n      !status.grantId ||\n      approvedScopes(status).length === 0\n    ) {\n      throw new AccessNotApprovedError(\n        \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n        {\n          requestId,\n          status: status.status,\n          hasPersonalServerUrl: Boolean(status.personalServerUrl),\n          hasGrantId: Boolean(status.grantId),\n          hasScope: approvedScopes(status).length > 0,\n        },\n      );\n    }\n    return status;\n  }\n\n  /** Approved scopes in approval order, falling back to the single `scope`. */\n  function approvedScopes(status: AccessRequestStatus): string[] {\n    if (status.scopes && status.scopes.length > 0) return status.scopes;\n    return status.scope ? [status.scope] : [];\n  }\n\n  /**\n   * Resolve which scope to read. Rejects an unapproved scope up front so it\n   * never reaches the Personal Server and never settles a fee.\n   */\n  function resolveRequestedScope(\n    status: AccessRequestStatus,\n    requested?: string,\n  ): string {\n    const scopes = approvedScopes(status);\n    if (requested === undefined) return scopes[0];\n    if (!scopes.includes(requested)) {\n      throw new ScopeNotApprovedError(\n        `Scope \"${requested}\" is not approved on this request`,\n        { requestedScope: requested, approvedScopes: scopes },\n      );\n    }\n    return requested;\n  }\n\n  async function readScope<T>(\n    status: AccessRequestStatus,\n    scope: string,\n  ): Promise<ApprovedDataResult<T>> {\n    const result = await readPersonalServerData({\n      personalServerUrl: status.personalServerUrl as string,\n      scope,\n      grantId: status.grantId as string,\n      payerAddress: account.address,\n      signMessage,\n      escrow,\n      fetchFn: config.personalServerFetch,\n      transportRetry: config.personalServerTransportRetry,\n    });\n    return { scope, data: result.data as T, payment: result.payment };\n  }\n\n  async function acknowledgeQuietly(requestId: string): Promise<void> {\n    try {\n      await accessRequestClient.acknowledgeRead?.(requestId);\n    } catch {\n      // The read already succeeded; ack only drives Vana Web completion UX.\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/direct/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\nimport type { ProtocolNetwork } from \"../protocol/networks\";\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 = ProtocolNetwork;\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/** One-time HTTPS callback used to deliver a foreground mobile Direct read. */\nexport interface ForegroundDelivery {\n  /** Fixed, same-origin consumer callback URL. */\n  url: string;\n  /** High-entropy bearer capability, generated and retained by the consumer. */\n  token: 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  /** Base URL of the DP RPC escrow gateway used to settle `402 Payment Required`. */\n  escrowGatewayUrl: 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  /** Protocol network echoed by the access-request service. */\n  network?: DirectNetwork;\n  /** Authoritative ISO-8601 expiry for the access request. */\n  expiresAt?: string;\n  /**\n   * HTTPS continuation URL for a deep Direct request on a mobile browser.\n   *\n   * @remarks\n   * Present only for a server-classified deep Direct DCR while it remains\n   * pending, and only when Mobile continuation is enabled. It is an ordinary\n   * `https://open[-dev].vana.org/continue#<ticket>` link the mobile UI renders\n   * as a primary \"Open Vana\" tap — iOS Universal Links / Android App Links\n   * deliver it to Vana Mobile, and its web fallback recovers an absent app. The\n   * SDK never launches it automatically and owns no persistence.\n   */\n  mobileContinuationUrl?: string;\n}\n\n/** Canonical mobile continuation link host per {@link DirectEnv}. */\nconst MOBILE_CONTINUATION_HOSTS: Record<DirectEnv, string> = {\n  production: \"open.vana.org\",\n  dev: \"open-dev.vana.org\",\n};\n\n/** URL-fragment-safe opaque ticket: no separators, query, or scheme chars. */\nconst MOBILE_CONTINUATION_TICKET = /^[A-Za-z0-9._~-]+$/;\n\n/**\n * @internal Strictly validate a mobile HTTPS continuation URL at the SDK\n * boundary.\n *\n * @remarks\n * Accepts only `https://open[-dev].vana.org/continue#<ticket>` with exactly one\n * well-formed opaque fragment ticket and no user info, port, or query. When\n * `env` is supplied only that environment's host is allowed; otherwise both\n * canonical hosts are accepted for structural (defense-in-depth) validation.\n *\n * @param value - The candidate URL from a create or status response.\n * @param env - Optional environment to pin the allowed host to.\n * @returns The canonical URL string, or `undefined` when it fails validation.\n */\nexport function normalizeMobileContinuationUrl(\n  value: unknown,\n  env?: DirectEnv,\n): string | undefined {\n  if (typeof value !== \"string\" || value.length === 0) return undefined;\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    return undefined;\n  }\n  if (url.protocol !== \"https:\") return undefined;\n  const allowedHosts = env\n    ? [MOBILE_CONTINUATION_HOSTS[env]]\n    : Object.values(MOBILE_CONTINUATION_HOSTS);\n  if (!allowedHosts.includes(url.hostname)) return undefined;\n  if (url.pathname !== \"/continue\") return undefined;\n  if (url.username !== \"\" || url.password !== \"\") return undefined;\n  if (url.port !== \"\") return undefined;\n  if (url.search !== \"\") return undefined;\n  const ticket = url.hash.startsWith(\"#\") ? url.hash.slice(1) : \"\";\n  if (!MOBILE_CONTINUATION_TICKET.test(ticket)) return undefined;\n  return url.toString();\n}\n\n/**\n * Lifecycle status of an access request.\n *\n * @remarks\n * - `\"pending\"` — created, awaiting user approval.\n * - `\"approved\"` / `\"ready_for_read\"` — the grant exists and the Personal\n *   Server is reachable; the data is read-ready (see {@link DirectDataController.readApprovedData}).\n * - `\"completed\"` — the app has already read the data and acknowledged it, so\n *   the DCR is terminal. A `\"completed\"` request is **not** read-ready — the\n *   browser Personal Server may no longer be serving it.\n * - `\"denied\"` / `\"expired\"` — terminal, no data was delivered.\n */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"ready_for_read\"\n  | \"completed\"\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 data is ready to read. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once data is ready to read. */\n  grantId?: string;\n  /**\n   * The first approved scope — present once data is ready to read.\n   *\n   * @remarks\n   * Kept for backwards compatibility. A request can approve many scopes; read\n   * {@link AccessRequestStatus.scopes} to see all of them.\n   */\n  scope?: string;\n  /**\n   * Fresh HTTPS mobile continuation URL, returned only while the deep Direct\n   * DCR is still pending. Its embedded ticket may rotate between polls.\n   */\n  mobileContinuationUrl?: string;\n  /**\n   * Every scope the user approved on this request — present once data is ready\n   * to read.\n   *\n   * @remarks\n   * A grant is keyed by `(user, app)` and carries a list of scopes, so a single\n   * approval can cover several. Against an older Vana Account deployment that\n   * only returns `scope`, this falls back to `[scope]`.\n   */\n  scopes?: 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   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Use for display/debugging, not accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\n/**\n * Result of {@link DirectDataController.readApprovedData} across every approved\n * scope.\n *\n * @remarks\n * Successes and failures are reported side by side rather than as a thrown\n * error, because each scope read settles its own fee: throwing on the third\n * scope would discard data the app has already paid for. Check `errors` before\n * treating the read as complete.\n */\nexport interface MultiScopeDataResult<T = unknown> {\n  /** Scopes that read successfully, keyed by scope. */\n  results: Record<string, ApprovedDataResult<T>>;\n  /** Scopes that failed, keyed by scope. Empty when every scope read. */\n  errors: Record<string, Error>;\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, network, 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    /** Vana protocol network for this request (`\"mainnet\"` or `\"moksha\"`). */\n    network: DirectNetwork;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Optional retry key. The default client generates a fresh key per call\n     * when omitted; pass a stable key to retry a create whose response was\n     * lost without risking a duplicate DCR.\n     */\n    idempotencyKey?: 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   * Acknowledge that the app successfully read the approved data.\n   *\n   * @remarks\n   * Direct Vana Web DCRs remain in `ready_for_read` while the browser Personal\n   * Server is serving the app. After a successful Personal Server read, the\n   * controller calls this hook so Vana Web can mark the request completed and\n   * close/redirect the approval tab.\n   *\n   * Optional so injected clients from older SDK integrations keep compiling;\n   * the default HTTP client implements it.\n   */\n  acknowledgeRead?(requestId: string): Promise<void>;\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 * GenericPayment uses `\"grant\"` for legacy grant lifecycle payments and\n * `\"data_access\"` for standalone receipt-bound reads.\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 challenged operation and amount/asset.\n * The controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The\n * full unmodified body is preserved under\n * {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id authorizing the Personal Server read. */\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  /** Data-access receipt carrying a signature for the gateway to verify. */\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/** A validated legacy grant payment challenge. */\nexport interface PersonalServerGrantPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"grant\";\n  /** Grant id settled by the escrow payment. */\n  opId: string;\n}\n\n/** A validated receipt-bound data-access payment challenge. */\nexport interface PersonalServerDataAccessPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"data_access\";\n  /** Access-record id settled by the escrow payment. */\n  opId: string;\n  /** Complete receipt whose signature is verified later by the gateway. */\n  accessRecord: EscrowAccessRecord;\n  /** Positive uint256 nonce supplied by the Personal Server challenge. */\n  paymentNonce: string;\n}\n\n/**\n * A Personal Server payment challenge whose escrow operation has been\n * validated.\n *\n * @remarks\n * Validation here is structural and binds operation ids to their receipt. It\n * does not cryptographically verify the receipt signature; the Personal\n * Server and Data Gateway perform that verification.\n */\nexport type PersonalServerPaymentOperation =\n  | PersonalServerGrantPaymentOperation\n  | PersonalServerDataAccessPaymentOperation;\n\n/** Shape-validated payment response returned directly by the escrow gateway. */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (a grant id or access-record 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 * Untrusted payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * The SDK validates every field before exposing this shape, but the response\n * header is not signed by the gateway. Use it for display and debugging only,\n * never as accounting proof that a payment occurred.\n */\nexport type DirectPaymentResponseMetadata = DirectPaymentReceipt;\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;AAAA;AA6GA,MAAM,4BAAuD;AAAA,EAC3D,YAAY;AAAA,EACZ,KAAK;AACP;AAGA,MAAM,6BAA6B;AAgB5B,SAAS,+BACd,OACA,KACoB;AACpB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,IAAI,aAAa,SAAU,QAAO;AACtC,QAAM,eAAe,MACjB,CAAC,0BAA0B,GAAG,CAAC,IAC/B,OAAO,OAAO,yBAAyB;AAC3C,MAAI,CAAC,aAAa,SAAS,IAAI,QAAQ,EAAG,QAAO;AACjD,MAAI,IAAI,aAAa,YAAa,QAAO;AACzC,MAAI,IAAI,aAAa,MAAM,IAAI,aAAa,GAAI,QAAO;AACvD,MAAI,IAAI,SAAS,GAAI,QAAO;AAC5B,MAAI,IAAI,WAAW,GAAI,QAAO;AAC9B,QAAM,SAAS,IAAI,KAAK,WAAW,GAAG,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI;AAC9D,MAAI,CAAC,2BAA2B,KAAK,MAAM,EAAG,QAAO;AACrD,SAAO,IAAI,SAAS;AACtB;AA2JO,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\";\nimport type { ProtocolNetwork } from \"../protocol/networks\";\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 = ProtocolNetwork;\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/** One-time HTTPS callback used to deliver a foreground mobile Direct read. */\nexport interface ForegroundDelivery {\n  /** Fixed, same-origin consumer callback URL. */\n  url: string;\n  /** High-entropy bearer capability, generated and retained by the consumer. */\n  token: string;\n}\n\n/**\n * One derivative question carried on an access request.\n *\n * @remarks\n * A question asks the user's Personal Server to compute an answer scope\n * (`derivedScope`) from source scopes the app never reads. On approval, the\n * Vana app registers the question on the Personal Server as the owner and the\n * grant covers only the derived scope, so the raw sources stay private to the\n * user. The SDK validates each question before the create request is signed\n * (see `validateAccessRequestQuestions`); the access-request service remains\n * authoritative and re-validates server-side.\n */\nexport interface AccessRequestQuestion {\n  /**\n   * Concrete scope the computed answer is written to and read from (no\n   * wildcards, no operation prefix). It must also appear verbatim in the\n   * request `scopes` as a bare read entry, and its first dot-segment must\n   * differ from the first dot-segment of every entry in\n   * {@link AccessRequestQuestion.sourceScopes}.\n   */\n  derivedScope: string;\n  /**\n   * Concrete scopes the answer is computed from: 1 to 16 entries, no\n   * duplicates, none equal to {@link AccessRequestQuestion.derivedScope}.\n   * These scopes are never granted to the app.\n   */\n  sourceScopes: string[];\n  /**\n   * Natural-language question the Personal Server answers from the source\n   * scopes. Must be 1 to 4000 characters after trimming.\n   */\n  question: string;\n  /**\n   * When the Personal Server recomputes the answer. `\"snapshot\"` computes\n   * once at registration; `\"on-change\"` also recomputes when a source scope\n   * changes. When omitted, the server-side default applies.\n   */\n  recompute?: \"snapshot\" | \"on-change\";\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  /** Base URL of the DP RPC escrow gateway used to settle `402 Payment Required`. */\n  escrowGatewayUrl: 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  /** Protocol network echoed by the access-request service. */\n  network?: DirectNetwork;\n  /** Authoritative ISO-8601 expiry for the access request. */\n  expiresAt?: string;\n  /**\n   * HTTPS continuation URL for a deep Direct request on a mobile browser.\n   *\n   * @remarks\n   * Present only for a server-classified deep Direct DCR while it remains\n   * pending, and only when Mobile continuation is enabled. It is an ordinary\n   * `https://open[-dev].vana.org/continue#<ticket>` link the mobile UI renders\n   * as a primary \"Open Vana\" tap — iOS Universal Links / Android App Links\n   * deliver it to Vana Mobile, and its web fallback recovers an absent app. The\n   * SDK never launches it automatically and owns no persistence.\n   */\n  mobileContinuationUrl?: string;\n}\n\n/** Canonical mobile continuation link host per {@link DirectEnv}. */\nconst MOBILE_CONTINUATION_HOSTS: Record<DirectEnv, string> = {\n  production: \"open.vana.org\",\n  dev: \"open-dev.vana.org\",\n};\n\n/** URL-fragment-safe opaque ticket: no separators, query, or scheme chars. */\nconst MOBILE_CONTINUATION_TICKET = /^[A-Za-z0-9._~-]+$/;\n\n/**\n * @internal Strictly validate a mobile HTTPS continuation URL at the SDK\n * boundary.\n *\n * @remarks\n * Accepts only `https://open[-dev].vana.org/continue#<ticket>` with exactly one\n * well-formed opaque fragment ticket and no user info, port, or query. When\n * `env` is supplied only that environment's host is allowed; otherwise both\n * canonical hosts are accepted for structural (defense-in-depth) validation.\n *\n * @param value - The candidate URL from a create or status response.\n * @param env - Optional environment to pin the allowed host to.\n * @returns The canonical URL string, or `undefined` when it fails validation.\n */\nexport function normalizeMobileContinuationUrl(\n  value: unknown,\n  env?: DirectEnv,\n): string | undefined {\n  if (typeof value !== \"string\" || value.length === 0) return undefined;\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    return undefined;\n  }\n  if (url.protocol !== \"https:\") return undefined;\n  const allowedHosts = env\n    ? [MOBILE_CONTINUATION_HOSTS[env]]\n    : Object.values(MOBILE_CONTINUATION_HOSTS);\n  if (!allowedHosts.includes(url.hostname)) return undefined;\n  if (url.pathname !== \"/continue\") return undefined;\n  if (url.username !== \"\" || url.password !== \"\") return undefined;\n  if (url.port !== \"\") return undefined;\n  if (url.search !== \"\") return undefined;\n  const ticket = url.hash.startsWith(\"#\") ? url.hash.slice(1) : \"\";\n  if (!MOBILE_CONTINUATION_TICKET.test(ticket)) return undefined;\n  return url.toString();\n}\n\n/**\n * Lifecycle status of an access request.\n *\n * @remarks\n * - `\"pending\"` — created, awaiting user approval.\n * - `\"approved\"` / `\"ready_for_read\"` — the grant exists and the Personal\n *   Server is reachable; the data is read-ready (see {@link DirectDataController.readApprovedData}).\n * - `\"completed\"` — the app has already read the data and acknowledged it, so\n *   the DCR is terminal. A `\"completed\"` request is **not** read-ready — the\n *   browser Personal Server may no longer be serving it.\n * - `\"denied\"` / `\"expired\"` — terminal, no data was delivered.\n */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"ready_for_read\"\n  | \"completed\"\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 data is ready to read. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once data is ready to read. */\n  grantId?: string;\n  /**\n   * The first approved scope — present once data is ready to read.\n   *\n   * @remarks\n   * Kept for backwards compatibility. A request can approve many scopes; read\n   * {@link AccessRequestStatus.scopes} to see all of them.\n   */\n  scope?: string;\n  /**\n   * Fresh HTTPS mobile continuation URL, returned only while the deep Direct\n   * DCR is still pending. Its embedded ticket may rotate between polls.\n   */\n  mobileContinuationUrl?: string;\n  /**\n   * Every scope the user approved on this request — present once data is ready\n   * to read.\n   *\n   * @remarks\n   * A grant is keyed by `(user, app)` and carries a list of scopes, so a single\n   * approval can cover several. Against an older Vana Account deployment that\n   * only returns `scope`, this falls back to `[scope]`.\n   */\n  scopes?: 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   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Use for display/debugging, not accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\n/**\n * Result of {@link DirectDataController.readApprovedData} across every approved\n * scope.\n *\n * @remarks\n * Successes and failures are reported side by side rather than as a thrown\n * error, because each scope read settles its own fee: throwing on the third\n * scope would discard data the app has already paid for. Check `errors` before\n * treating the read as complete.\n */\nexport interface MultiScopeDataResult<T = unknown> {\n  /** Scopes that read successfully, keyed by scope. */\n  results: Record<string, ApprovedDataResult<T>>;\n  /** Scopes that failed, keyed by scope. Empty when every scope read. */\n  errors: Record<string, Error>;\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, network, 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    /** Vana protocol network for this request (`\"mainnet\"` or `\"moksha\"`). */\n    network: DirectNetwork;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Derivative questions to carry on the request (1 to 4). When present,\n     * the array is validated client-side and serialized into the signed\n     * create body verbatim. See {@link AccessRequestQuestion}.\n     */\n    questions?: AccessRequestQuestion[];\n    /**\n     * Optional retry key. The default client generates a fresh key per call\n     * when omitted; pass a stable key to retry a create whose response was\n     * lost without risking a duplicate DCR.\n     */\n    idempotencyKey?: 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   * Acknowledge that the app successfully read the approved data.\n   *\n   * @remarks\n   * Direct Vana Web DCRs remain in `ready_for_read` while the browser Personal\n   * Server is serving the app. After a successful Personal Server read, the\n   * controller calls this hook so Vana Web can mark the request completed and\n   * close/redirect the approval tab.\n   *\n   * Optional so injected clients from older SDK integrations keep compiling;\n   * the default HTTP client implements it.\n   */\n  acknowledgeRead?(requestId: string): Promise<void>;\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 * GenericPayment uses `\"grant\"` for legacy grant lifecycle payments and\n * `\"data_access\"` for standalone receipt-bound reads.\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 challenged operation and amount/asset.\n * The controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The\n * full unmodified body is preserved under\n * {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id authorizing the Personal Server read. */\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  /** Data-access receipt carrying a signature for the gateway to verify. */\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/** A validated legacy grant payment challenge. */\nexport interface PersonalServerGrantPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"grant\";\n  /** Grant id settled by the escrow payment. */\n  opId: string;\n}\n\n/** A validated receipt-bound data-access payment challenge. */\nexport interface PersonalServerDataAccessPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"data_access\";\n  /** Access-record id settled by the escrow payment. */\n  opId: string;\n  /** Complete receipt whose signature is verified later by the gateway. */\n  accessRecord: EscrowAccessRecord;\n  /** Positive uint256 nonce supplied by the Personal Server challenge. */\n  paymentNonce: string;\n}\n\n/**\n * A Personal Server payment challenge whose escrow operation has been\n * validated.\n *\n * @remarks\n * Validation here is structural and binds operation ids to their receipt. It\n * does not cryptographically verify the receipt signature; the Personal\n * Server and Data Gateway perform that verification.\n */\nexport type PersonalServerPaymentOperation =\n  | PersonalServerGrantPaymentOperation\n  | PersonalServerDataAccessPaymentOperation;\n\n/** Shape-validated payment response returned directly by the escrow gateway. */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (a grant id or access-record 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 * Untrusted payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * The SDK validates every field before exposing this shape, but the response\n * header is not signed by the gateway. Use it for display and debugging only,\n * never as accounting proof that a payment occurred.\n */\nexport type DirectPaymentResponseMetadata = DirectPaymentReceipt;\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;AAAA;AAqJA,MAAM,4BAAuD;AAAA,EAC3D,YAAY;AAAA,EACZ,KAAK;AACP;AAGA,MAAM,6BAA6B;AAgB5B,SAAS,+BACd,OACA,KACoB;AACpB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,IAAI,aAAa,SAAU,QAAO;AACtC,QAAM,eAAe,MACjB,CAAC,0BAA0B,GAAG,CAAC,IAC/B,OAAO,OAAO,yBAAyB;AAC3C,MAAI,CAAC,aAAa,SAAS,IAAI,QAAQ,EAAG,QAAO;AACjD,MAAI,IAAI,aAAa,YAAa,QAAO;AACzC,MAAI,IAAI,aAAa,MAAM,IAAI,aAAa,GAAI,QAAO;AACvD,MAAI,IAAI,SAAS,GAAI,QAAO;AAC5B,MAAI,IAAI,WAAW,GAAI,QAAO;AAC9B,QAAM,SAAS,IAAI,KAAK,WAAW,GAAG,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI;AAC9D,MAAI,CAAC,2BAA2B,KAAK,MAAM,EAAG,QAAO;AACrD,SAAO,IAAI,SAAS;AACtB;AAiKO,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

@@ -54,6 +54,45 @@ export interface ForegroundDelivery {
     /** High-entropy bearer capability, generated and retained by the consumer. */
     token: string;
 }
+/**
+ * One derivative question carried on an access request.
+ *
+ * @remarks
+ * A question asks the user's Personal Server to compute an answer scope
+ * (`derivedScope`) from source scopes the app never reads. On approval, the
+ * Vana app registers the question on the Personal Server as the owner and the
+ * grant covers only the derived scope, so the raw sources stay private to the
+ * user. The SDK validates each question before the create request is signed
+ * (see `validateAccessRequestQuestions`); the access-request service remains
+ * authoritative and re-validates server-side.
+ */
+export interface AccessRequestQuestion {
+    /**
+     * Concrete scope the computed answer is written to and read from (no
+     * wildcards, no operation prefix). It must also appear verbatim in the
+     * request `scopes` as a bare read entry, and its first dot-segment must
+     * differ from the first dot-segment of every entry in
+     * {@link AccessRequestQuestion.sourceScopes}.
+     */
+    derivedScope: string;
+    /**
+     * Concrete scopes the answer is computed from: 1 to 16 entries, no
+     * duplicates, none equal to {@link AccessRequestQuestion.derivedScope}.
+     * These scopes are never granted to the app.
+     */
+    sourceScopes: string[];
+    /**
+     * Natural-language question the Personal Server answers from the source
+     * scopes. Must be 1 to 4000 characters after trimming.
+     */
+    question: string;
+    /**
+     * When the Personal Server recomputes the answer. `"snapshot"` computes
+     * once at registration; `"on-change"` also recomputes when a source scope
+     * changes. When omitted, the server-side default applies.
+     */
+    recompute?: "snapshot" | "on-change";
+}
 /**
  * Resolved service URLs and chain id for a given {@link DirectEnv}.
  *
@@ -211,6 +250,12 @@ export interface AccessRequestClient {
         network: DirectNetwork;
         /** Optional foreground mobile delivery callback. */
         foregroundDelivery?: ForegroundDelivery;
+        /**
+         * Derivative questions to carry on the request (1 to 4). When present,
+         * the array is validated client-side and serialized into the signed
+         * create body verbatim. See {@link AccessRequestQuestion}.
+         */
+        questions?: AccessRequestQuestion[];
         /**
          * Optional retry key. The default client generates a fresh key per call
          * when omitted; pass a stable key to retry a create whose response was

package/dist/direct/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/types.ts"],"sourcesContent":["import type { EscrowAccessRecord } from \"../protocol/escrow\";\nimport type { ProtocolNetwork } from \"../protocol/networks\";\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 = ProtocolNetwork;\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/** One-time HTTPS callback used to deliver a foreground mobile Direct read. */\nexport interface ForegroundDelivery {\n  /** Fixed, same-origin consumer callback URL. */\n  url: string;\n  /** High-entropy bearer capability, generated and retained by the consumer. */\n  token: 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  /** Base URL of the DP RPC escrow gateway used to settle `402 Payment Required`. */\n  escrowGatewayUrl: 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  /** Protocol network echoed by the access-request service. */\n  network?: DirectNetwork;\n  /** Authoritative ISO-8601 expiry for the access request. */\n  expiresAt?: string;\n  /**\n   * HTTPS continuation URL for a deep Direct request on a mobile browser.\n   *\n   * @remarks\n   * Present only for a server-classified deep Direct DCR while it remains\n   * pending, and only when Mobile continuation is enabled. It is an ordinary\n   * `https://open[-dev].vana.org/continue#<ticket>` link the mobile UI renders\n   * as a primary \"Open Vana\" tap — iOS Universal Links / Android App Links\n   * deliver it to Vana Mobile, and its web fallback recovers an absent app. The\n   * SDK never launches it automatically and owns no persistence.\n   */\n  mobileContinuationUrl?: string;\n}\n\n/** Canonical mobile continuation link host per {@link DirectEnv}. */\nconst MOBILE_CONTINUATION_HOSTS: Record<DirectEnv, string> = {\n  production: \"open.vana.org\",\n  dev: \"open-dev.vana.org\",\n};\n\n/** URL-fragment-safe opaque ticket: no separators, query, or scheme chars. */\nconst MOBILE_CONTINUATION_TICKET = /^[A-Za-z0-9._~-]+$/;\n\n/**\n * @internal Strictly validate a mobile HTTPS continuation URL at the SDK\n * boundary.\n *\n * @remarks\n * Accepts only `https://open[-dev].vana.org/continue#<ticket>` with exactly one\n * well-formed opaque fragment ticket and no user info, port, or query. When\n * `env` is supplied only that environment's host is allowed; otherwise both\n * canonical hosts are accepted for structural (defense-in-depth) validation.\n *\n * @param value - The candidate URL from a create or status response.\n * @param env - Optional environment to pin the allowed host to.\n * @returns The canonical URL string, or `undefined` when it fails validation.\n */\nexport function normalizeMobileContinuationUrl(\n  value: unknown,\n  env?: DirectEnv,\n): string | undefined {\n  if (typeof value !== \"string\" || value.length === 0) return undefined;\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    return undefined;\n  }\n  if (url.protocol !== \"https:\") return undefined;\n  const allowedHosts = env\n    ? [MOBILE_CONTINUATION_HOSTS[env]]\n    : Object.values(MOBILE_CONTINUATION_HOSTS);\n  if (!allowedHosts.includes(url.hostname)) return undefined;\n  if (url.pathname !== \"/continue\") return undefined;\n  if (url.username !== \"\" || url.password !== \"\") return undefined;\n  if (url.port !== \"\") return undefined;\n  if (url.search !== \"\") return undefined;\n  const ticket = url.hash.startsWith(\"#\") ? url.hash.slice(1) : \"\";\n  if (!MOBILE_CONTINUATION_TICKET.test(ticket)) return undefined;\n  return url.toString();\n}\n\n/**\n * Lifecycle status of an access request.\n *\n * @remarks\n * - `\"pending\"` — created, awaiting user approval.\n * - `\"approved\"` / `\"ready_for_read\"` — the grant exists and the Personal\n *   Server is reachable; the data is read-ready (see {@link DirectDataController.readApprovedData}).\n * - `\"completed\"` — the app has already read the data and acknowledged it, so\n *   the DCR is terminal. A `\"completed\"` request is **not** read-ready — the\n *   browser Personal Server may no longer be serving it.\n * - `\"denied\"` / `\"expired\"` — terminal, no data was delivered.\n */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"ready_for_read\"\n  | \"completed\"\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 data is ready to read. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once data is ready to read. */\n  grantId?: string;\n  /**\n   * The first approved scope — present once data is ready to read.\n   *\n   * @remarks\n   * Kept for backwards compatibility. A request can approve many scopes; read\n   * {@link AccessRequestStatus.scopes} to see all of them.\n   */\n  scope?: string;\n  /**\n   * Fresh HTTPS mobile continuation URL, returned only while the deep Direct\n   * DCR is still pending. Its embedded ticket may rotate between polls.\n   */\n  mobileContinuationUrl?: string;\n  /**\n   * Every scope the user approved on this request — present once data is ready\n   * to read.\n   *\n   * @remarks\n   * A grant is keyed by `(user, app)` and carries a list of scopes, so a single\n   * approval can cover several. Against an older Vana Account deployment that\n   * only returns `scope`, this falls back to `[scope]`.\n   */\n  scopes?: 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   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Use for display/debugging, not accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\n/**\n * Result of {@link DirectDataController.readApprovedData} across every approved\n * scope.\n *\n * @remarks\n * Successes and failures are reported side by side rather than as a thrown\n * error, because each scope read settles its own fee: throwing on the third\n * scope would discard data the app has already paid for. Check `errors` before\n * treating the read as complete.\n */\nexport interface MultiScopeDataResult<T = unknown> {\n  /** Scopes that read successfully, keyed by scope. */\n  results: Record<string, ApprovedDataResult<T>>;\n  /** Scopes that failed, keyed by scope. Empty when every scope read. */\n  errors: Record<string, Error>;\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, network, 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    /** Vana protocol network for this request (`\"mainnet\"` or `\"moksha\"`). */\n    network: DirectNetwork;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Optional retry key. The default client generates a fresh key per call\n     * when omitted; pass a stable key to retry a create whose response was\n     * lost without risking a duplicate DCR.\n     */\n    idempotencyKey?: 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   * Acknowledge that the app successfully read the approved data.\n   *\n   * @remarks\n   * Direct Vana Web DCRs remain in `ready_for_read` while the browser Personal\n   * Server is serving the app. After a successful Personal Server read, the\n   * controller calls this hook so Vana Web can mark the request completed and\n   * close/redirect the approval tab.\n   *\n   * Optional so injected clients from older SDK integrations keep compiling;\n   * the default HTTP client implements it.\n   */\n  acknowledgeRead?(requestId: string): Promise<void>;\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 * GenericPayment uses `\"grant\"` for legacy grant lifecycle payments and\n * `\"data_access\"` for standalone receipt-bound reads.\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 challenged operation and amount/asset.\n * The controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The\n * full unmodified body is preserved under\n * {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id authorizing the Personal Server read. */\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  /** Data-access receipt carrying a signature for the gateway to verify. */\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/** A validated legacy grant payment challenge. */\nexport interface PersonalServerGrantPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"grant\";\n  /** Grant id settled by the escrow payment. */\n  opId: string;\n}\n\n/** A validated receipt-bound data-access payment challenge. */\nexport interface PersonalServerDataAccessPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"data_access\";\n  /** Access-record id settled by the escrow payment. */\n  opId: string;\n  /** Complete receipt whose signature is verified later by the gateway. */\n  accessRecord: EscrowAccessRecord;\n  /** Positive uint256 nonce supplied by the Personal Server challenge. */\n  paymentNonce: string;\n}\n\n/**\n * A Personal Server payment challenge whose escrow operation has been\n * validated.\n *\n * @remarks\n * Validation here is structural and binds operation ids to their receipt. It\n * does not cryptographically verify the receipt signature; the Personal\n * Server and Data Gateway perform that verification.\n */\nexport type PersonalServerPaymentOperation =\n  | PersonalServerGrantPaymentOperation\n  | PersonalServerDataAccessPaymentOperation;\n\n/** Shape-validated payment response returned directly by the escrow gateway. */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (a grant id or access-record 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 * Untrusted payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * The SDK validates every field before exposing this shape, but the response\n * header is not signed by the gateway. Use it for display and debugging only,\n * never as accounting proof that a payment occurred.\n */\nexport type DirectPaymentResponseMetadata = DirectPaymentReceipt;\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":"AA6GA,MAAM,4BAAuD;AAAA,EAC3D,YAAY;AAAA,EACZ,KAAK;AACP;AAGA,MAAM,6BAA6B;AAgB5B,SAAS,+BACd,OACA,KACoB;AACpB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,IAAI,aAAa,SAAU,QAAO;AACtC,QAAM,eAAe,MACjB,CAAC,0BAA0B,GAAG,CAAC,IAC/B,OAAO,OAAO,yBAAyB;AAC3C,MAAI,CAAC,aAAa,SAAS,IAAI,QAAQ,EAAG,QAAO;AACjD,MAAI,IAAI,aAAa,YAAa,QAAO;AACzC,MAAI,IAAI,aAAa,MAAM,IAAI,aAAa,GAAI,QAAO;AACvD,MAAI,IAAI,SAAS,GAAI,QAAO;AAC5B,MAAI,IAAI,WAAW,GAAI,QAAO;AAC9B,QAAM,SAAS,IAAI,KAAK,WAAW,GAAG,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI;AAC9D,MAAI,CAAC,2BAA2B,KAAK,MAAM,EAAG,QAAO;AACrD,SAAO,IAAI,SAAS;AACtB;AA2JO,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\";\nimport type { ProtocolNetwork } from \"../protocol/networks\";\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 = ProtocolNetwork;\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/** One-time HTTPS callback used to deliver a foreground mobile Direct read. */\nexport interface ForegroundDelivery {\n  /** Fixed, same-origin consumer callback URL. */\n  url: string;\n  /** High-entropy bearer capability, generated and retained by the consumer. */\n  token: string;\n}\n\n/**\n * One derivative question carried on an access request.\n *\n * @remarks\n * A question asks the user's Personal Server to compute an answer scope\n * (`derivedScope`) from source scopes the app never reads. On approval, the\n * Vana app registers the question on the Personal Server as the owner and the\n * grant covers only the derived scope, so the raw sources stay private to the\n * user. The SDK validates each question before the create request is signed\n * (see `validateAccessRequestQuestions`); the access-request service remains\n * authoritative and re-validates server-side.\n */\nexport interface AccessRequestQuestion {\n  /**\n   * Concrete scope the computed answer is written to and read from (no\n   * wildcards, no operation prefix). It must also appear verbatim in the\n   * request `scopes` as a bare read entry, and its first dot-segment must\n   * differ from the first dot-segment of every entry in\n   * {@link AccessRequestQuestion.sourceScopes}.\n   */\n  derivedScope: string;\n  /**\n   * Concrete scopes the answer is computed from: 1 to 16 entries, no\n   * duplicates, none equal to {@link AccessRequestQuestion.derivedScope}.\n   * These scopes are never granted to the app.\n   */\n  sourceScopes: string[];\n  /**\n   * Natural-language question the Personal Server answers from the source\n   * scopes. Must be 1 to 4000 characters after trimming.\n   */\n  question: string;\n  /**\n   * When the Personal Server recomputes the answer. `\"snapshot\"` computes\n   * once at registration; `\"on-change\"` also recomputes when a source scope\n   * changes. When omitted, the server-side default applies.\n   */\n  recompute?: \"snapshot\" | \"on-change\";\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  /** Base URL of the DP RPC escrow gateway used to settle `402 Payment Required`. */\n  escrowGatewayUrl: 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  /** Protocol network echoed by the access-request service. */\n  network?: DirectNetwork;\n  /** Authoritative ISO-8601 expiry for the access request. */\n  expiresAt?: string;\n  /**\n   * HTTPS continuation URL for a deep Direct request on a mobile browser.\n   *\n   * @remarks\n   * Present only for a server-classified deep Direct DCR while it remains\n   * pending, and only when Mobile continuation is enabled. It is an ordinary\n   * `https://open[-dev].vana.org/continue#<ticket>` link the mobile UI renders\n   * as a primary \"Open Vana\" tap — iOS Universal Links / Android App Links\n   * deliver it to Vana Mobile, and its web fallback recovers an absent app. The\n   * SDK never launches it automatically and owns no persistence.\n   */\n  mobileContinuationUrl?: string;\n}\n\n/** Canonical mobile continuation link host per {@link DirectEnv}. */\nconst MOBILE_CONTINUATION_HOSTS: Record<DirectEnv, string> = {\n  production: \"open.vana.org\",\n  dev: \"open-dev.vana.org\",\n};\n\n/** URL-fragment-safe opaque ticket: no separators, query, or scheme chars. */\nconst MOBILE_CONTINUATION_TICKET = /^[A-Za-z0-9._~-]+$/;\n\n/**\n * @internal Strictly validate a mobile HTTPS continuation URL at the SDK\n * boundary.\n *\n * @remarks\n * Accepts only `https://open[-dev].vana.org/continue#<ticket>` with exactly one\n * well-formed opaque fragment ticket and no user info, port, or query. When\n * `env` is supplied only that environment's host is allowed; otherwise both\n * canonical hosts are accepted for structural (defense-in-depth) validation.\n *\n * @param value - The candidate URL from a create or status response.\n * @param env - Optional environment to pin the allowed host to.\n * @returns The canonical URL string, or `undefined` when it fails validation.\n */\nexport function normalizeMobileContinuationUrl(\n  value: unknown,\n  env?: DirectEnv,\n): string | undefined {\n  if (typeof value !== \"string\" || value.length === 0) return undefined;\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    return undefined;\n  }\n  if (url.protocol !== \"https:\") return undefined;\n  const allowedHosts = env\n    ? [MOBILE_CONTINUATION_HOSTS[env]]\n    : Object.values(MOBILE_CONTINUATION_HOSTS);\n  if (!allowedHosts.includes(url.hostname)) return undefined;\n  if (url.pathname !== \"/continue\") return undefined;\n  if (url.username !== \"\" || url.password !== \"\") return undefined;\n  if (url.port !== \"\") return undefined;\n  if (url.search !== \"\") return undefined;\n  const ticket = url.hash.startsWith(\"#\") ? url.hash.slice(1) : \"\";\n  if (!MOBILE_CONTINUATION_TICKET.test(ticket)) return undefined;\n  return url.toString();\n}\n\n/**\n * Lifecycle status of an access request.\n *\n * @remarks\n * - `\"pending\"` — created, awaiting user approval.\n * - `\"approved\"` / `\"ready_for_read\"` — the grant exists and the Personal\n *   Server is reachable; the data is read-ready (see {@link DirectDataController.readApprovedData}).\n * - `\"completed\"` — the app has already read the data and acknowledged it, so\n *   the DCR is terminal. A `\"completed\"` request is **not** read-ready — the\n *   browser Personal Server may no longer be serving it.\n * - `\"denied\"` / `\"expired\"` — terminal, no data was delivered.\n */\nexport type AccessRequestStatusValue =\n  | \"pending\"\n  | \"approved\"\n  | \"ready_for_read\"\n  | \"completed\"\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 data is ready to read. */\n  personalServerUrl?: string;\n  /** Grant id covering the approved scope — present once data is ready to read. */\n  grantId?: string;\n  /**\n   * The first approved scope — present once data is ready to read.\n   *\n   * @remarks\n   * Kept for backwards compatibility. A request can approve many scopes; read\n   * {@link AccessRequestStatus.scopes} to see all of them.\n   */\n  scope?: string;\n  /**\n   * Fresh HTTPS mobile continuation URL, returned only while the deep Direct\n   * DCR is still pending. Its embedded ticket may rotate between polls.\n   */\n  mobileContinuationUrl?: string;\n  /**\n   * Every scope the user approved on this request — present once data is ready\n   * to read.\n   *\n   * @remarks\n   * A grant is keyed by `(user, app)` and carries a list of scopes, so a single\n   * approval can cover several. Against an older Vana Account deployment that\n   * only returns `scope`, this falls back to `[scope]`.\n   */\n  scopes?: 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   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Use for display/debugging, not accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\n/**\n * Result of {@link DirectDataController.readApprovedData} across every approved\n * scope.\n *\n * @remarks\n * Successes and failures are reported side by side rather than as a thrown\n * error, because each scope read settles its own fee: throwing on the third\n * scope would discard data the app has already paid for. Check `errors` before\n * treating the read as complete.\n */\nexport interface MultiScopeDataResult<T = unknown> {\n  /** Scopes that read successfully, keyed by scope. */\n  results: Record<string, ApprovedDataResult<T>>;\n  /** Scopes that failed, keyed by scope. Empty when every scope read. */\n  errors: Record<string, Error>;\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, network, 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    /** Vana protocol network for this request (`\"mainnet\"` or `\"moksha\"`). */\n    network: DirectNetwork;\n    /** Optional foreground mobile delivery callback. */\n    foregroundDelivery?: ForegroundDelivery;\n    /**\n     * Derivative questions to carry on the request (1 to 4). When present,\n     * the array is validated client-side and serialized into the signed\n     * create body verbatim. See {@link AccessRequestQuestion}.\n     */\n    questions?: AccessRequestQuestion[];\n    /**\n     * Optional retry key. The default client generates a fresh key per call\n     * when omitted; pass a stable key to retry a create whose response was\n     * lost without risking a duplicate DCR.\n     */\n    idempotencyKey?: 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   * Acknowledge that the app successfully read the approved data.\n   *\n   * @remarks\n   * Direct Vana Web DCRs remain in `ready_for_read` while the browser Personal\n   * Server is serving the app. After a successful Personal Server read, the\n   * controller calls this hook so Vana Web can mark the request completed and\n   * close/redirect the approval tab.\n   *\n   * Optional so injected clients from older SDK integrations keep compiling;\n   * the default HTTP client implements it.\n   */\n  acknowledgeRead?(requestId: string): Promise<void>;\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 * GenericPayment uses `\"grant\"` for legacy grant lifecycle payments and\n * `\"data_access\"` for standalone receipt-bound reads.\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 challenged operation and amount/asset.\n * The controller settles it via the DPv2 escrow gateway (`/v1/escrow/pay`). The\n * full unmodified body is preserved under\n * {@link PersonalServerPaymentRequired.raw}.\n */\nexport interface PersonalServerPaymentRequired {\n  /** Grant id authorizing the Personal Server read. */\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  /** Data-access receipt carrying a signature for the gateway to verify. */\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/** A validated legacy grant payment challenge. */\nexport interface PersonalServerGrantPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"grant\";\n  /** Grant id settled by the escrow payment. */\n  opId: string;\n}\n\n/** A validated receipt-bound data-access payment challenge. */\nexport interface PersonalServerDataAccessPaymentOperation extends PersonalServerPaymentRequired {\n  /** Escrow operation discriminator. */\n  opType: \"data_access\";\n  /** Access-record id settled by the escrow payment. */\n  opId: string;\n  /** Complete receipt whose signature is verified later by the gateway. */\n  accessRecord: EscrowAccessRecord;\n  /** Positive uint256 nonce supplied by the Personal Server challenge. */\n  paymentNonce: string;\n}\n\n/**\n * A Personal Server payment challenge whose escrow operation has been\n * validated.\n *\n * @remarks\n * Validation here is structural and binds operation ids to their receipt. It\n * does not cryptographically verify the receipt signature; the Personal\n * Server and Data Gateway perform that verification.\n */\nexport type PersonalServerPaymentOperation =\n  | PersonalServerGrantPaymentOperation\n  | PersonalServerDataAccessPaymentOperation;\n\n/** Shape-validated payment response returned directly by the escrow gateway. */\nexport interface DirectPaymentReceipt {\n  /** Op type settled (the gateway `opType`, e.g. `\"grant\"`). */\n  opType: string;\n  /** Op id settled (a grant id or access-record 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 * Untrusted payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * The SDK validates every field before exposing this shape, but the response\n * header is not signed by the gateway. Use it for display and debugging only,\n * never as accounting proof that a payment occurred.\n */\nexport type DirectPaymentResponseMetadata = DirectPaymentReceipt;\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":"AAqJA,MAAM,4BAAuD;AAAA,EAC3D,YAAY;AAAA,EACZ,KAAK;AACP;AAGA,MAAM,6BAA6B;AAgB5B,SAAS,+BACd,OACA,KACoB;AACpB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,IAAI,aAAa,SAAU,QAAO;AACtC,QAAM,eAAe,MACjB,CAAC,0BAA0B,GAAG,CAAC,IAC/B,OAAO,OAAO,yBAAyB;AAC3C,MAAI,CAAC,aAAa,SAAS,IAAI,QAAQ,EAAG,QAAO;AACjD,MAAI,IAAI,aAAa,YAAa,QAAO;AACzC,MAAI,IAAI,aAAa,MAAM,IAAI,aAAa,GAAI,QAAO;AACvD,MAAI,IAAI,SAAS,GAAI,QAAO;AAC5B,MAAI,IAAI,WAAW,GAAI,QAAO;AAC9B,QAAM,SAAS,IAAI,KAAK,WAAW,GAAG,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI;AAC9D,MAAI,CAAC,2BAA2B,KAAK,MAAM,EAAG,QAAO;AACrD,SAAO,IAAI,SAAS;AACtB;AAiKO,MAAM,eAAe;AAAA,EAC1B,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AACvB;","names":[]}

package/dist/index.browser.d.ts

@@ -51,7 +51,8 @@ export { ScopeSchema, parseScope, scopeToPathSegments, scopeMatchesPattern, scop
 export { SCOPE_ACTIONS, InvalidScopeEntryError, parseScopeEntry, formatScopeEntry, grantPermissions, permissionsToScopes, tryGrantPermissions, hasAction, type ScopeAction, type ParsedScopeEntry, type GrantPermission, } from "./protocol/scope-actions.js";
 export { WRITE_SESSION_PATH, WRITE_SIGNATURE_HEADER, WRITE_METADATA_HEADER, WRITE_FILENAME_HEADER, WRITE_CONTENT_DISPOSITION_HEADER, WRITER_ATTRIBUTION_KEY, LINEAGE_KEY, LINEAGE_FIELD, MAX_LINEAGE_SOURCES, RESERVED_WRITE_KEYS, openWriteSession, writeData, writePersonalServerData, sessionCoversScope, binaryWriteSignedBytes, normalizeBinaryMimeType, parseWriteMetadataHeader, encodeWriteMetadataHeader, type WriteTransportRetryOptions, type WriteSession, type OpenWriteSessionParams, type WriteBinaryPayload, type LineageSource, type WriteJsonDataParams, type WriteBinaryDataParams, type WriteDataParams, type WriteDataResult, type WritePersonalServerDataParams, type WritePersonalServerDataResult, type BinaryWriteSignedBytesInput, } from "./protocol/personal-server-write.js";
 export { resolveWriteSigner, type WriteSigner, type WriteSignerSource, type ViemWriteAccount, type ViemWriteWalletClient, type ResolveWriteSignerOptions, } from "./protocol/write-signer.js";
-export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, DERIVATIVE_ERROR_CODES, DerivativeErrorCodeSchema, type DerivativeErrorCode, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_STATUS_PATH, DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS, DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS, derivativeStatusTarget, getDerivativeStatus, waitForDerivativeStatus, isDerivativeStatusSettled, DerivativeStatusSchema, type DerivativeStatus, type GetDerivativeStatusParams, type WaitForDerivativeStatusParams, } from "./protocol/derivative-status.js";
 export { deriveDataPointId, isDataPointId, scopeNamespace, derivedScopeViolatesNaming, assertDerivedScopeNaming, isRedactedLineageNode, personalServerLineagePath, gatewayLineagePath, getLineage, getPersonalServerLineage, getGatewayLineage, LineageNodeSchema, RedactedLineageNodeSchema, LineageEntrySchema, LineageGraphSchema, type LineageNode, type RedactedLineageNode, type LineageEntry, type LineageGraph, type LineageReadResult, type PersonalServerLineageParams, type GatewayLineageParams, type GetLineageParams, } from "./protocol/lineage.js";
 export { DataFileEnvelopeSchema, createDataFileEnvelope, IngestResponseSchema, type DataFileEnvelope, type IngestResponse, } from "./protocol/data-file.js";
 export { createGatewayClient, type GatewayEnvelope, type GatewayProof, type Builder, type Schema, type ServerInfo, type OwnerServerRecord, type OwnerServersResult, type GatewayGrantFee, type GatewayGrantStatus, type GatewayGrantResponse, type GrantListItem, type DataPointRecord, type DataPointListResult, type ListDataPointsOptions, type RegisterServerParams, type RegisterServerResult, type RegisterBuilderParams, type RegisterBuilderResult, type RegisterDataPointParams, type RegisterDataPointResult, type GetDataPointOptions, type DeleteDataPointParams, type DeleteDataPointResult, type CreateGrantParams, type RevokeGrantParams, type AccessRecord, type PayForOperationParams, type PayForOperationResult, type SettleOpType, type SettleItem, type SettlePromoteResult, type SettleReconcileItem, type SettleParams, type SettleResult, type GatewayClient, } from "./protocol/gateway.js";