@opendatalabs/vana-sdk 3.5.1 → 3.6.1

package/README.md

@@ -104,6 +104,122 @@ const result = await storage.upload(myBlob, "report.json");
 console.log(result.url);
 ```
 
+## Build a direct Vana app
+
+Request user-approved data, read it from the user's Personal Server, and pay
+for the read — without the browser ever seeing your app private key or choosing
+scopes. Your **backend** owns the controller (`@opendatalabs/vana-sdk/server`);
+your **frontend** drives a two-tab approval flow with a React hook
+(`@opendatalabs/vana-sdk/react`).
+
+> **How it fits together.** Access requests are created through the Vana Account
+> access-request API; the Personal Server read uses Web3Signed auth; and payment
+> settles on a `402` through the DPv2 escrow surface (`protocol/escrow`), where the
+> controller signs a `GenericPayment` with your app key. You can inject your own
+> `accessRequestClient` to target a custom deployment, and `escrow` config to wire
+> the escrow gateway.
+
+### Backend controller
+
+```typescript
+// lib/vana.ts
+import { createDirectDataController } from "@opendatalabs/vana-sdk/server";
+
+import { createEscrowGatewayClient } from "@opendatalabs/vana-sdk/node";
+
+export const vana = createDirectDataController({
+  env: process.env.VANA_ENV === "dev" ? "dev" : "production",
+  appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,
+  app: {
+    id: "notes-lens",
+    name: "Notes Lens",
+    homepageUrl: process.env.VANA_APP_URL!,
+  },
+  source: "icloud_notes",
+  scopes: ["icloud_notes.notes"],
+  // Settle paid reads through the DPv2 escrow gateway. The controller signs the
+  // GenericPayment with your app key; you supply the gateway client + contract.
+  escrow: {
+    client: createEscrowGatewayClient(process.env.VANA_DP_RPC_URL!),
+    escrowContract: process.env.VANA_ESCROW_CONTRACT! as `0x${string}`,
+  },
+});
+
+// The app's on-chain address — fund and inspect this in the Builder activity
+// report. (`vana.getAppIdentity()` also returns the configured id/name/homepage.)
+console.log(vana.getAppAddress()); // 0x...
+```
+
+Wire it to three routes — your backend chooses the source and scopes, owns the
+private key, and handles `402 Payment Required`:
+
+```typescript
+// POST /api/vana/request
+const request = await vana.createAccessRequest({
+  returnUrl: `${process.env.VANA_APP_URL}/connect/return`,
+});
+// -> { requestId: "dcr_...", approvalUrl: "https://app.vana.org/...", appAddress: "0x..." }
+
+// GET /api/vana/status?requestId=...
+const status = await vana.getAccessRequestStatus(requestId);
+// -> { status: "approved", personalServerUrl, grantId, scope }
+
+// GET /api/vana/data?requestId=...
+const result = await vana.readApprovedData({ requestId });
+// -> {
+//   scope: "icloud_notes.notes",
+//   data: ...,
+//   payment?: {            // present only when this read settled a payment
+//     amount, asset, paymentNonce, paidAt,
+//     breakdown: { registrationFee, dataAccessFee, registrationPaid },
+//   },
+// }
+```
+
+`readApprovedData` hides the payment flow for normal builders. If the Personal
+Server returns `402 Payment Required`, the controller settles the grant through
+the escrow gateway and retries, attaching a `payment` receipt so you can inspect
+the amount, asset, and fee breakdown. If `escrow` is not configured (or the read
+still requires payment afterward), it throws `PaymentRequiredError` carrying the
+amount and asset owed.
+
+### Frontend hook
+
+```tsx
+"use client";
+import { useDirectVanaConnect } from "@opendatalabs/vana-sdk/react";
+
+export function ConnectNotesButton() {
+  const connect = useDirectVanaConnect({
+    createRequest: () =>
+      fetch("/api/vana/request", { method: "POST" }).then((r) => r.json()),
+    getStatus: (requestId) =>
+      fetch(`/api/vana/status?requestId=${encodeURIComponent(requestId)}`).then(
+        (r) => r.json(),
+      ),
+    readResult: (requestId) =>
+      fetch(`/api/vana/data?requestId=${encodeURIComponent(requestId)}`).then(
+        (r) => r.json(),
+      ),
+  });
+
+  return (
+    <button
+      disabled={connect.state.type !== "idle"}
+      onClick={connect.start}
+      type="button"
+    >
+      {connect.state.type === "idle" ? "Connect Apple Notes" : "Connecting..."}
+    </button>
+  );
+}
+```
+
+The hook calls `createRequest`, opens the Vana approval URL, polls `getStatus`
+until the request is approved, then calls `readResult`. `react` is an optional
+peer dependency. The underlying `createDirectConnectFlow` store is also exported
+for non-React frontends.
+
 ## Networks
 
 | Network        | Chain ID | RPC URL                     |

package/dist/direct/access-request-client.cjs

@@ -0,0 +1,149 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var access_request_client_exports = {};
+__export(access_request_client_exports, {
+  buildApprovalUrl: () => buildApprovalUrl,
+  buildDirectAccessRequestAuthMessage: () => buildDirectAccessRequestAuthMessage,
+  createDefaultAccessRequestClient: () => createDefaultAccessRequestClient
+});
+module.exports = __toCommonJS(access_request_client_exports);
+const VALID_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired"
+];
+function normalizeStatus(value) {
+  return VALID_STATUSES.includes(value) ? value : "pending";
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+const DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX = "Vana Direct Access Request v1";
+function buildDirectAccessRequestAuthMessage(input) {
+  return [
+    DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX,
+    `method:${input.method.toUpperCase()}`,
+    `path:${input.path}`,
+    `timestamp:${input.timestamp}`,
+    `body:${input.body}`
+  ].join("\n");
+}
+async function buildDirectAccessRequestHeaders(options, input) {
+  if (!options.appAddress && !options.signMessage) {
+    return {};
+  }
+  if (!options.appAddress || !options.signMessage) {
+    throw new Error(
+      "Direct access-request authentication requires both `appAddress` and `signMessage`."
+    );
+  }
+  const timestamp = String(options.now?.() ?? Date.now());
+  const signature = await options.signMessage(
+    buildDirectAccessRequestAuthMessage({ ...input, timestamp })
+  );
+  return {
+    "X-Vana-App-Address": options.appAddress,
+    "X-Vana-App-Signature": signature,
+    "X-Vana-App-Timestamp": timestamp
+  };
+}
+function buildApprovalUrl(approvalBaseUrl, requestId) {
+  return `${stripTrailingSlash(approvalBaseUrl)}/data-connection-requests/${encodeURIComponent(
+    requestId
+  )}?mode=page`;
+}
+function createDefaultAccessRequestClient(options) {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  if (!fetchFn) {
+    throw new Error(
+      "No fetch implementation available. Pass `fetchFn` to createDefaultAccessRequestClient."
+    );
+  }
+  const base = stripTrailingSlash(options.baseUrl);
+  return {
+    async createAccessRequest(input) {
+      const path = "/api/data-connection-requests";
+      const body = JSON.stringify({
+        appAddress: input.appAddress,
+        app: input.app,
+        source: input.source,
+        scopes: input.scopes,
+        returnUrl: input.returnUrl
+      });
+      const res = await fetchFn(`${base}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...await buildDirectAccessRequestHeaders(options, {
+            body,
+            method: "POST",
+            path
+          })
+        },
+        body
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const responseBody = await res.json();
+      const requestId = responseBody.requestId ?? responseBody.id;
+      if (!requestId) {
+        throw new Error("Access request service returned no requestId");
+      }
+      return {
+        requestId,
+        approvalUrl: responseBody.approvalUrl ?? buildApprovalUrl(options.approvalBaseUrl, requestId),
+        appAddress: responseBody.appAddress ?? input.appAddress
+      };
+    },
+    async getAccessRequestStatus(requestId) {
+      const path = `/api/data-connection-requests/${encodeURIComponent(requestId)}`;
+      const res = await fetchFn(`${base}${path}`, {
+        method: "GET",
+        headers: await buildDirectAccessRequestHeaders(options, {
+          body: "",
+          method: "GET",
+          path
+        })
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const body = await res.json();
+      return {
+        status: normalizeStatus(body.status),
+        personalServerUrl: body.personalServerUrl,
+        grantId: body.grantId,
+        scope: body.scope
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildApprovalUrl,
+  buildDirectAccessRequestAuthMessage,
+  createDefaultAccessRequestClient
+});
+//# sourceMappingURL=access-request-client.cjs.map

package/dist/direct/access-request-client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/access-request-client.ts"],"sourcesContent":["/**\n * Default client for the Vana Account access-request API.\n *\n * @remarks\n * Calls the Vana Account endpoints that issue `dcr_*` ids and approval URLs and\n * report request status. Inject a custom {@link AccessRequestClient} on the\n * controller to point at a different deployment; pass `fetchFn` to supply a test\n * double for the HTTP layer.\n *\n * @category Direct\n * @module direct/access-request-client\n */\n\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n} from \"./types\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\n\n/** Minimal `fetch` signature so the client is testable without a global fetch. */\nexport type FetchLike = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  statusText: string;\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}>;\n\n/** Options for {@link createDefaultAccessRequestClient}. */\nexport interface DefaultAccessRequestClientOptions {\n  /** Base URL of the Vana Account access-request API. */\n  baseUrl: string;\n  /** Base URL the user is sent to for approval. */\n  approvalBaseUrl: string;\n  /** `fetch` implementation. Defaults to the global `fetch`. */\n  fetchFn?: FetchLike;\n  /** App identity address used for direct access-request authentication. */\n  appAddress?: string;\n  /** EIP-191 signer for direct access-request authentication. */\n  signMessage?: Web3SignedSignFn;\n  /** Clock source used for signed request timestamps. */\n  now?: () => number;\n}\n\nconst VALID_STATUSES: readonly AccessRequestStatusValue[] = [\n  \"pending\",\n  \"approved\",\n  \"denied\",\n  \"expired\",\n];\n\nfunction normalizeStatus(value: unknown): AccessRequestStatusValue {\n  return VALID_STATUSES.includes(value as AccessRequestStatusValue)\n    ? (value as AccessRequestStatusValue)\n    : \"pending\";\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\nconst DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX = \"Vana Direct Access Request v1\";\n\ninterface DirectAccessRequestAuthInput {\n  body: string;\n  method: string;\n  path: string;\n  timestamp: string;\n}\n\nexport function buildDirectAccessRequestAuthMessage(\n  input: DirectAccessRequestAuthInput,\n): string {\n  return [\n    DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX,\n    `method:${input.method.toUpperCase()}`,\n    `path:${input.path}`,\n    `timestamp:${input.timestamp}`,\n    `body:${input.body}`,\n  ].join(\"\\n\");\n}\n\nasync function buildDirectAccessRequestHeaders(\n  options: DefaultAccessRequestClientOptions,\n  input: Omit<DirectAccessRequestAuthInput, \"timestamp\">,\n): Promise<Record<string, string>> {\n  if (!options.appAddress && !options.signMessage) {\n    return {};\n  }\n  if (!options.appAddress || !options.signMessage) {\n    throw new Error(\n      \"Direct access-request authentication requires both `appAddress` and `signMessage`.\",\n    );\n  }\n\n  const timestamp = String(options.now?.() ?? Date.now());\n  const signature = await options.signMessage(\n    buildDirectAccessRequestAuthMessage({ ...input, timestamp }),\n  );\n\n  return {\n    \"X-Vana-App-Address\": options.appAddress,\n    \"X-Vana-App-Signature\": signature,\n    \"X-Vana-App-Timestamp\": timestamp,\n  };\n}\n\n/**\n * Build an approval URL for a request id, matching the documented format\n * (`{app}/data-connection-requests/{requestId}?mode=page`).\n *\n * @param approvalBaseUrl - Base URL of the Vana approval app.\n * @param requestId - The `dcr_*` request id.\n * @returns The full approval URL.\n */\nexport function buildApprovalUrl(\n  approvalBaseUrl: string,\n  requestId: string,\n): string {\n  return `${stripTrailingSlash(approvalBaseUrl)}/data-connection-requests/${encodeURIComponent(\n    requestId,\n  )}?mode=page`;\n}\n\n/**\n * Create the default {@link AccessRequestClient} for the Vana Account\n * access-request API.\n *\n * @param options - Base URLs and an optional `fetch` implementation.\n * @returns An {@link AccessRequestClient} backed by HTTP calls.\n */\nexport function createDefaultAccessRequestClient(\n  options: DefaultAccessRequestClientOptions,\n): AccessRequestClient {\n  const fetchFn = options.fetchFn ?? (globalThis.fetch as FetchLike);\n  if (!fetchFn) {\n    throw new Error(\n      \"No fetch implementation available. Pass `fetchFn` to createDefaultAccessRequestClient.\",\n    );\n  }\n  const base = stripTrailingSlash(options.baseUrl);\n\n  return {\n    async createAccessRequest(input): Promise<AccessRequest> {\n      const path = \"/api/data-connection-requests\";\n      const body = JSON.stringify({\n        appAddress: input.appAddress,\n        app: input.app,\n        source: input.source,\n        scopes: input.scopes,\n        returnUrl: input.returnUrl,\n      });\n      const res = await fetchFn(`${base}${path}`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          ...(await buildDirectAccessRequestHeaders(options, {\n            body,\n            method: \"POST\",\n            path,\n          })),\n        },\n        body,\n      });\n      if (!res.ok) {\n        throw new Error(\n          `Access request service error: ${res.status} ${res.statusText}`,\n        );\n      }\n      const responseBody = (await res.json()) as {\n        requestId?: string;\n        id?: string;\n        approvalUrl?: string;\n        appAddress?: string;\n      };\n      const requestId = responseBody.requestId ?? responseBody.id;\n      if (!requestId) {\n        throw new Error(\"Access request service returned no requestId\");\n      }\n      return {\n        requestId,\n        approvalUrl:\n          responseBody.approvalUrl ??\n          buildApprovalUrl(options.approvalBaseUrl, requestId),\n        appAddress: responseBody.appAddress ?? input.appAddress,\n      };\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      const path = `/api/data-connection-requests/${encodeURIComponent(requestId)}`;\n      const res = await fetchFn(`${base}${path}`, {\n        method: \"GET\",\n        headers: await buildDirectAccessRequestHeaders(options, {\n          body: \"\",\n          method: \"GET\",\n          path,\n        }),\n      });\n      if (!res.ok) {\n        throw new Error(\n          `Access request service error: ${res.status} ${res.statusText}`,\n        );\n      }\n      const body = (await res.json()) as {\n        status?: string;\n        personalServerUrl?: string;\n        grantId?: string;\n        scope?: string;\n      };\n      return {\n        status: normalizeStatus(body.status),\n        personalServerUrl: body.personalServerUrl,\n        grantId: body.grantId,\n        scope: body.scope,\n      };\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/access-request-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Default client for the Vana Account access-request API.
+ *
+ * @remarks
+ * Calls the Vana Account endpoints that issue `dcr_*` ids and approval URLs and
+ * report request status. Inject a custom {@link AccessRequestClient} on the
+ * controller to point at a different deployment; pass `fetchFn` to supply a test
+ * double for the HTTP layer.
+ *
+ * @category Direct
+ * @module direct/access-request-client
+ */
+import type { AccessRequestClient } from "./types";
+import type { Web3SignedSignFn } from "../auth/web3-signed-builder";
+/** Minimal `fetch` signature so the client is testable without a global fetch. */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+/** Options for {@link createDefaultAccessRequestClient}. */
+export interface DefaultAccessRequestClientOptions {
+    /** Base URL of the Vana Account access-request API. */
+    baseUrl: string;
+    /** Base URL the user is sent to for approval. */
+    approvalBaseUrl: string;
+    /** `fetch` implementation. Defaults to the global `fetch`. */
+    fetchFn?: FetchLike;
+    /** App identity address used for direct access-request authentication. */
+    appAddress?: string;
+    /** EIP-191 signer for direct access-request authentication. */
+    signMessage?: Web3SignedSignFn;
+    /** Clock source used for signed request timestamps. */
+    now?: () => number;
+}
+interface DirectAccessRequestAuthInput {
+    body: string;
+    method: string;
+    path: string;
+    timestamp: string;
+}
+export declare function buildDirectAccessRequestAuthMessage(input: DirectAccessRequestAuthInput): string;
+/**
+ * Build an approval URL for a request id, matching the documented format
+ * (`{app}/data-connection-requests/{requestId}?mode=page`).
+ *
+ * @param approvalBaseUrl - Base URL of the Vana approval app.
+ * @param requestId - The `dcr_*` request id.
+ * @returns The full approval URL.
+ */
+export declare function buildApprovalUrl(approvalBaseUrl: string, requestId: string): string;
+/**
+ * Create the default {@link AccessRequestClient} for the Vana Account
+ * access-request API.
+ *
+ * @param options - Base URLs and an optional `fetch` implementation.
+ * @returns An {@link AccessRequestClient} backed by HTTP calls.
+ */
+export declare function createDefaultAccessRequestClient(options: DefaultAccessRequestClientOptions): AccessRequestClient;
+export {};

package/dist/direct/access-request-client.js

@@ -0,0 +1,123 @@
+const VALID_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired"
+];
+function normalizeStatus(value) {
+  return VALID_STATUSES.includes(value) ? value : "pending";
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+const DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX = "Vana Direct Access Request v1";
+function buildDirectAccessRequestAuthMessage(input) {
+  return [
+    DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX,
+    `method:${input.method.toUpperCase()}`,
+    `path:${input.path}`,
+    `timestamp:${input.timestamp}`,
+    `body:${input.body}`
+  ].join("\n");
+}
+async function buildDirectAccessRequestHeaders(options, input) {
+  if (!options.appAddress && !options.signMessage) {
+    return {};
+  }
+  if (!options.appAddress || !options.signMessage) {
+    throw new Error(
+      "Direct access-request authentication requires both `appAddress` and `signMessage`."
+    );
+  }
+  const timestamp = String(options.now?.() ?? Date.now());
+  const signature = await options.signMessage(
+    buildDirectAccessRequestAuthMessage({ ...input, timestamp })
+  );
+  return {
+    "X-Vana-App-Address": options.appAddress,
+    "X-Vana-App-Signature": signature,
+    "X-Vana-App-Timestamp": timestamp
+  };
+}
+function buildApprovalUrl(approvalBaseUrl, requestId) {
+  return `${stripTrailingSlash(approvalBaseUrl)}/data-connection-requests/${encodeURIComponent(
+    requestId
+  )}?mode=page`;
+}
+function createDefaultAccessRequestClient(options) {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  if (!fetchFn) {
+    throw new Error(
+      "No fetch implementation available. Pass `fetchFn` to createDefaultAccessRequestClient."
+    );
+  }
+  const base = stripTrailingSlash(options.baseUrl);
+  return {
+    async createAccessRequest(input) {
+      const path = "/api/data-connection-requests";
+      const body = JSON.stringify({
+        appAddress: input.appAddress,
+        app: input.app,
+        source: input.source,
+        scopes: input.scopes,
+        returnUrl: input.returnUrl
+      });
+      const res = await fetchFn(`${base}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...await buildDirectAccessRequestHeaders(options, {
+            body,
+            method: "POST",
+            path
+          })
+        },
+        body
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const responseBody = await res.json();
+      const requestId = responseBody.requestId ?? responseBody.id;
+      if (!requestId) {
+        throw new Error("Access request service returned no requestId");
+      }
+      return {
+        requestId,
+        approvalUrl: responseBody.approvalUrl ?? buildApprovalUrl(options.approvalBaseUrl, requestId),
+        appAddress: responseBody.appAddress ?? input.appAddress
+      };
+    },
+    async getAccessRequestStatus(requestId) {
+      const path = `/api/data-connection-requests/${encodeURIComponent(requestId)}`;
+      const res = await fetchFn(`${base}${path}`, {
+        method: "GET",
+        headers: await buildDirectAccessRequestHeaders(options, {
+          body: "",
+          method: "GET",
+          path
+        })
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const body = await res.json();
+      return {
+        status: normalizeStatus(body.status),
+        personalServerUrl: body.personalServerUrl,
+        grantId: body.grantId,
+        scope: body.scope
+      };
+    }
+  };
+}
+export {
+  buildApprovalUrl,
+  buildDirectAccessRequestAuthMessage,
+  createDefaultAccessRequestClient
+};
+//# sourceMappingURL=access-request-client.js.map

package/dist/direct/access-request-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/direct/access-request-client.ts"],"sourcesContent":["/**\n * Default client for the Vana Account access-request API.\n *\n * @remarks\n * Calls the Vana Account endpoints that issue `dcr_*` ids and approval URLs and\n * report request status. Inject a custom {@link AccessRequestClient} on the\n * controller to point at a different deployment; pass `fetchFn` to supply a test\n * double for the HTTP layer.\n *\n * @category Direct\n * @module direct/access-request-client\n */\n\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n} from \"./types\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\n\n/** Minimal `fetch` signature so the client is testable without a global fetch. */\nexport type FetchLike = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  statusText: string;\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}>;\n\n/** Options for {@link createDefaultAccessRequestClient}. */\nexport interface DefaultAccessRequestClientOptions {\n  /** Base URL of the Vana Account access-request API. */\n  baseUrl: string;\n  /** Base URL the user is sent to for approval. */\n  approvalBaseUrl: string;\n  /** `fetch` implementation. Defaults to the global `fetch`. */\n  fetchFn?: FetchLike;\n  /** App identity address used for direct access-request authentication. */\n  appAddress?: string;\n  /** EIP-191 signer for direct access-request authentication. */\n  signMessage?: Web3SignedSignFn;\n  /** Clock source used for signed request timestamps. */\n  now?: () => number;\n}\n\nconst VALID_STATUSES: readonly AccessRequestStatusValue[] = [\n  \"pending\",\n  \"approved\",\n  \"denied\",\n  \"expired\",\n];\n\nfunction normalizeStatus(value: unknown): AccessRequestStatusValue {\n  return VALID_STATUSES.includes(value as AccessRequestStatusValue)\n    ? (value as AccessRequestStatusValue)\n    : \"pending\";\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\nconst DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX = \"Vana Direct Access Request v1\";\n\ninterface DirectAccessRequestAuthInput {\n  body: string;\n  method: string;\n  path: string;\n  timestamp: string;\n}\n\nexport function buildDirectAccessRequestAuthMessage(\n  input: DirectAccessRequestAuthInput,\n): string {\n  return [\n    DIRECT_ACCESS_REQUEST_MESSAGE_PREFIX,\n    `method:${input.method.toUpperCase()}`,\n    `path:${input.path}`,\n    `timestamp:${input.timestamp}`,\n    `body:${input.body}`,\n  ].join(\"\\n\");\n}\n\nasync function buildDirectAccessRequestHeaders(\n  options: DefaultAccessRequestClientOptions,\n  input: Omit<DirectAccessRequestAuthInput, \"timestamp\">,\n): Promise<Record<string, string>> {\n  if (!options.appAddress && !options.signMessage) {\n    return {};\n  }\n  if (!options.appAddress || !options.signMessage) {\n    throw new Error(\n      \"Direct access-request authentication requires both `appAddress` and `signMessage`.\",\n    );\n  }\n\n  const timestamp = String(options.now?.() ?? Date.now());\n  const signature = await options.signMessage(\n    buildDirectAccessRequestAuthMessage({ ...input, timestamp }),\n  );\n\n  return {\n    \"X-Vana-App-Address\": options.appAddress,\n    \"X-Vana-App-Signature\": signature,\n    \"X-Vana-App-Timestamp\": timestamp,\n  };\n}\n\n/**\n * Build an approval URL for a request id, matching the documented format\n * (`{app}/data-connection-requests/{requestId}?mode=page`).\n *\n * @param approvalBaseUrl - Base URL of the Vana approval app.\n * @param requestId - The `dcr_*` request id.\n * @returns The full approval URL.\n */\nexport function buildApprovalUrl(\n  approvalBaseUrl: string,\n  requestId: string,\n): string {\n  return `${stripTrailingSlash(approvalBaseUrl)}/data-connection-requests/${encodeURIComponent(\n    requestId,\n  )}?mode=page`;\n}\n\n/**\n * Create the default {@link AccessRequestClient} for the Vana Account\n * access-request API.\n *\n * @param options - Base URLs and an optional `fetch` implementation.\n * @returns An {@link AccessRequestClient} backed by HTTP calls.\n */\nexport function createDefaultAccessRequestClient(\n  options: DefaultAccessRequestClientOptions,\n): AccessRequestClient {\n  const fetchFn = options.fetchFn ?? (globalThis.fetch as FetchLike);\n  if (!fetchFn) {\n    throw new Error(\n      \"No fetch implementation available. Pass `fetchFn` to createDefaultAccessRequestClient.\",\n    );\n  }\n  const base = stripTrailingSlash(options.baseUrl);\n\n  return {\n    async createAccessRequest(input): Promise<AccessRequest> {\n      const path = \"/api/data-connection-requests\";\n      const body = JSON.stringify({\n        appAddress: input.appAddress,\n        app: input.app,\n        source: input.source,\n        scopes: input.scopes,\n        returnUrl: input.returnUrl,\n      });\n      const res = await fetchFn(`${base}${path}`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          ...(await buildDirectAccessRequestHeaders(options, {\n            body,\n            method: \"POST\",\n            path,\n          })),\n        },\n        body,\n      });\n      if (!res.ok) {\n        throw new Error(\n          `Access request service error: ${res.status} ${res.statusText}`,\n        );\n      }\n      const responseBody = (await res.json()) as {\n        requestId?: string;\n        id?: string;\n        approvalUrl?: string;\n        appAddress?: string;\n      };\n      const requestId = responseBody.requestId ?? responseBody.id;\n      if (!requestId) {\n        throw new Error(\"Access request service returned no requestId\");\n      }\n      return {\n        requestId,\n        approvalUrl:\n          responseBody.approvalUrl ??\n          buildApprovalUrl(options.approvalBaseUrl, requestId),\n        appAddress: responseBody.appAddress ?? input.appAddress,\n      };\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      const path = `/api/data-connection-requests/${encodeURIComponent(requestId)}`;\n      const res = await fetchFn(`${base}${path}`, {\n        method: \"GET\",\n        headers: await buildDirectAccessRequestHeaders(options, {\n          body: \"\",\n          method: \"GET\",\n          path,\n        }),\n      });\n      if (!res.ok) {\n        throw new Error(\n          `Access request service error: ${res.status} ${res.statusText}`,\n        );\n      }\n      const body = (await res.json()) as {\n        status?: string;\n        personalServerUrl?: string;\n        grantId?: string;\n        scope?: string;\n      };\n      return {\n        status: normalizeStatus(body.status),\n        personalServerUrl: body.personalServerUrl,\n        grantId: body.grantId,\n        scope: body.scope,\n      };\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/direct/access-request-client.test.d.ts

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

package/dist/direct/connect-flow.cjs

@@ -0,0 +1,152 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var connect_flow_exports = {};
+__export(connect_flow_exports, {
+  createDirectConnectFlow: () => createDirectConnectFlow
+});
+module.exports = __toCommonJS(connect_flow_exports);
+const DEFAULT_POLL_INTERVAL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 3e5;
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+function createDirectConnectFlow(transports, options = {}) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const openWindow = options.openWindow ?? ((url) => {
+    if (typeof window !== "undefined" && window.open) {
+      window.open(url, "_blank", "noopener,noreferrer");
+    }
+  });
+  const setTimeoutFn = options.setTimeoutFn ?? ((cb, ms) => globalThis.setTimeout(cb, ms));
+  const clearTimeoutFn = options.clearTimeoutFn ?? ((handle) => {
+    globalThis.clearTimeout(handle);
+  });
+  const now = options.now ?? (() => Date.now());
+  let state = { type: "idle" };
+  const listeners = /* @__PURE__ */ new Set();
+  let pollHandle = null;
+  let running = false;
+  function emit() {
+    for (const listener of listeners) listener();
+  }
+  function setState(next) {
+    state = next;
+    emit();
+  }
+  function clearPoll() {
+    if (pollHandle !== null) {
+      clearTimeoutFn(pollHandle);
+      pollHandle = null;
+    }
+  }
+  function isRunningPhase() {
+    return state.type === "creating" || state.type === "awaiting_approval" || state.type === "reading";
+  }
+  async function readAndFinish(request) {
+    setState({ type: "reading", request });
+    try {
+      const result = await transports.readResult(request.requestId);
+      if (!running) return;
+      setState({ type: "done", result });
+    } catch (err) {
+      if (!running) return;
+      setState({ type: "error", error: toError(err) });
+    } finally {
+      running = false;
+    }
+  }
+  function scheduleNextPoll(request, deadline) {
+    pollHandle = setTimeoutFn(() => {
+      void poll(request, deadline);
+    }, pollIntervalMs);
+  }
+  async function poll(request, deadline) {
+    if (!running) return;
+    if (now() >= deadline) {
+      running = false;
+      setState({
+        type: "error",
+        error: new Error("Timed out waiting for approval")
+      });
+      return;
+    }
+    let status;
+    try {
+      status = await transports.getStatus(request.requestId);
+    } catch (err) {
+      if (!running) return;
+      running = false;
+      setState({ type: "error", error: toError(err) });
+      return;
+    }
+    if (!running) return;
+    if (status.status === "approved") {
+      clearPoll();
+      await readAndFinish(request);
+      return;
+    }
+    if (status.status === "denied" || status.status === "expired") {
+      running = false;
+      setState({
+        type: "error",
+        error: new Error(`Access request ${status.status}`)
+      });
+      return;
+    }
+    scheduleNextPoll(request, deadline);
+  }
+  return {
+    getState() {
+      return state;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async start() {
+      if (running || isRunningPhase()) return;
+      running = true;
+      setState({ type: "creating" });
+      let request;
+      try {
+        request = await transports.createRequest();
+      } catch (err) {
+        running = false;
+        setState({ type: "error", error: toError(err) });
+        return;
+      }
+      if (!running) return;
+      setState({ type: "awaiting_approval", request });
+      openWindow(request.approvalUrl);
+      const deadline = now() + timeoutMs;
+      scheduleNextPoll(request, deadline);
+    },
+    reset() {
+      running = false;
+      clearPoll();
+      setState({ type: "idle" });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDirectConnectFlow
+});
+//# sourceMappingURL=connect-flow.cjs.map