@opendatalabs/vana-sdk 3.5.0 → 3.5.1-pr.159.12a6f39

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,104 @@
+"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,
+  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(/\/+$/, "");
+}
+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 res = await fetchFn(`${base}/api/v1/data-connection-requests`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          appAddress: input.appAddress,
+          app: input.app,
+          source: input.source,
+          scopes: input.scopes,
+          returnUrl: input.returnUrl
+        })
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const body = await res.json();
+      const requestId = body.requestId ?? body.id;
+      if (!requestId) {
+        throw new Error("Access request service returned no requestId");
+      }
+      return {
+        requestId,
+        approvalUrl: body.approvalUrl ?? buildApprovalUrl(options.approvalBaseUrl, requestId),
+        appAddress: body.appAddress ?? input.appAddress
+      };
+    },
+    async getAccessRequestStatus(requestId) {
+      const res = await fetchFn(
+        `${base}/api/v1/data-connection-requests/${encodeURIComponent(requestId)}`,
+        { method: "GET" }
+      );
+      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,
+  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\";\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}\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\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 res = await fetchFn(`${base}/api/v1/data-connection-requests`, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        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      });\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        requestId?: string;\n        id?: string;\n        approvalUrl?: string;\n        appAddress?: string;\n      };\n      const requestId = body.requestId ?? body.id;\n      if (!requestId) {\n        throw new Error(\"Access request service returned no requestId\");\n      }\n      return {\n        requestId,\n        approvalUrl:\n          body.approvalUrl ??\n          buildApprovalUrl(options.approvalBaseUrl, requestId),\n        appAddress: body.appAddress ?? input.appAddress,\n      };\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      const res = await fetchFn(\n        `${base}/api/v1/data-connection-requests/${encodeURIComponent(requestId)}`,\n        { method: \"GET\" },\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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CA,MAAM,iBAAsD;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,gBAAgB,OAA0C;AACjE,SAAO,eAAe,SAAS,KAAiC,IAC3D,QACD;AACN;AAEA,SAAS,mBAAmB,KAAqB;AAC/C,SAAO,IAAI,QAAQ,QAAQ,EAAE;AAC/B;AAUO,SAAS,iBACd,iBACA,WACQ;AACR,SAAO,GAAG,mBAAmB,eAAe,CAAC,6BAA6B;AAAA,IACxE;AAAA,EACF,CAAC;AACH;AASO,SAAS,iCACd,SACqB;AACrB,QAAM,UAAU,QAAQ,WAAY,WAAW;AAC/C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,QAAM,OAAO,mBAAmB,QAAQ,OAAO;AAE/C,SAAO;AAAA,IACL,MAAM,oBAAoB,OAA+B;AACvD,YAAM,MAAM,MAAM,QAAQ,GAAG,IAAI,oCAAoC;AAAA,QACnE,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAC9C,MAAM,KAAK,UAAU;AAAA,UACnB,YAAY,MAAM;AAAA,UAClB,KAAK,MAAM;AAAA,UACX,QAAQ,MAAM;AAAA,UACd,QAAQ,MAAM;AAAA,UACd,WAAW,MAAM;AAAA,QACnB,CAAC;AAAA,MACH,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI;AAAA,UACR,iCAAiC,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,QAC/D;AAAA,MACF;AACA,YAAM,OAAQ,MAAM,IAAI,KAAK;AAM7B,YAAM,YAAY,KAAK,aAAa,KAAK;AACzC,UAAI,CAAC,WAAW;AACd,cAAM,IAAI,MAAM,8CAA8C;AAAA,MAChE;AACA,aAAO;AAAA,QACL;AAAA,QACA,aACE,KAAK,eACL,iBAAiB,QAAQ,iBAAiB,SAAS;AAAA,QACrD,YAAY,KAAK,cAAc,MAAM;AAAA,MACvC;AAAA,IACF;AAAA,IAEA,MAAM,uBACJ,WAC8B;AAC9B,YAAM,MAAM,MAAM;AAAA,QAChB,GAAG,IAAI,oCAAoC,mBAAmB,SAAS,CAAC;AAAA,QACxE,EAAE,QAAQ,MAAM;AAAA,MAClB;AACA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI;AAAA,UACR,iCAAiC,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,QAC/D;AAAA,MACF;AACA,YAAM,OAAQ,MAAM,IAAI,KAAK;AAM7B,aAAO;AAAA,QACL,QAAQ,gBAAgB,KAAK,MAAM;AAAA,QACnC,mBAAmB,KAAK;AAAA,QACxB,SAAS,KAAK;AAAA,QACd,OAAO,KAAK;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

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

@@ -0,0 +1,51 @@
+/**
+ * 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";
+/** 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;
+}
+/**
+ * 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;

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

@@ -0,0 +1,79 @@
+const VALID_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired"
+];
+function normalizeStatus(value) {
+  return VALID_STATUSES.includes(value) ? value : "pending";
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+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 res = await fetchFn(`${base}/api/v1/data-connection-requests`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          appAddress: input.appAddress,
+          app: input.app,
+          source: input.source,
+          scopes: input.scopes,
+          returnUrl: input.returnUrl
+        })
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Access request service error: ${res.status} ${res.statusText}`
+        );
+      }
+      const body = await res.json();
+      const requestId = body.requestId ?? body.id;
+      if (!requestId) {
+        throw new Error("Access request service returned no requestId");
+      }
+      return {
+        requestId,
+        approvalUrl: body.approvalUrl ?? buildApprovalUrl(options.approvalBaseUrl, requestId),
+        appAddress: body.appAddress ?? input.appAddress
+      };
+    },
+    async getAccessRequestStatus(requestId) {
+      const res = await fetchFn(
+        `${base}/api/v1/data-connection-requests/${encodeURIComponent(requestId)}`,
+        { method: "GET" }
+      );
+      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,
+  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\";\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}\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\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 res = await fetchFn(`${base}/api/v1/data-connection-requests`, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        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      });\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        requestId?: string;\n        id?: string;\n        approvalUrl?: string;\n        appAddress?: string;\n      };\n      const requestId = body.requestId ?? body.id;\n      if (!requestId) {\n        throw new Error(\"Access request service returned no requestId\");\n      }\n      return {\n        requestId,\n        approvalUrl:\n          body.approvalUrl ??\n          buildApprovalUrl(options.approvalBaseUrl, requestId),\n        appAddress: body.appAddress ?? input.appAddress,\n      };\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      const res = await fetchFn(\n        `${base}/api/v1/data-connection-requests/${encodeURIComponent(requestId)}`,\n        { method: \"GET\" },\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":"AA8CA,MAAM,iBAAsD;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,gBAAgB,OAA0C;AACjE,SAAO,eAAe,SAAS,KAAiC,IAC3D,QACD;AACN;AAEA,SAAS,mBAAmB,KAAqB;AAC/C,SAAO,IAAI,QAAQ,QAAQ,EAAE;AAC/B;AAUO,SAAS,iBACd,iBACA,WACQ;AACR,SAAO,GAAG,mBAAmB,eAAe,CAAC,6BAA6B;AAAA,IACxE;AAAA,EACF,CAAC;AACH;AASO,SAAS,iCACd,SACqB;AACrB,QAAM,UAAU,QAAQ,WAAY,WAAW;AAC/C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,QAAM,OAAO,mBAAmB,QAAQ,OAAO;AAE/C,SAAO;AAAA,IACL,MAAM,oBAAoB,OAA+B;AACvD,YAAM,MAAM,MAAM,QAAQ,GAAG,IAAI,oCAAoC;AAAA,QACnE,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAC9C,MAAM,KAAK,UAAU;AAAA,UACnB,YAAY,MAAM;AAAA,UAClB,KAAK,MAAM;AAAA,UACX,QAAQ,MAAM;AAAA,UACd,QAAQ,MAAM;AAAA,UACd,WAAW,MAAM;AAAA,QACnB,CAAC;AAAA,MACH,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI;AAAA,UACR,iCAAiC,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,QAC/D;AAAA,MACF;AACA,YAAM,OAAQ,MAAM,IAAI,KAAK;AAM7B,YAAM,YAAY,KAAK,aAAa,KAAK;AACzC,UAAI,CAAC,WAAW;AACd,cAAM,IAAI,MAAM,8CAA8C;AAAA,MAChE;AACA,aAAO;AAAA,QACL;AAAA,QACA,aACE,KAAK,eACL,iBAAiB,QAAQ,iBAAiB,SAAS;AAAA,QACrD,YAAY,KAAK,cAAc,MAAM;AAAA,MACvC;AAAA,IACF;AAAA,IAEA,MAAM,uBACJ,WAC8B;AAC9B,YAAM,MAAM,MAAM;AAAA,QAChB,GAAG,IAAI,oCAAoC,mBAAmB,SAAS,CAAC;AAAA,QACxE,EAAE,QAAQ,MAAM;AAAA,MAClB;AACA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI;AAAA,UACR,iCAAiC,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,QAC/D;AAAA,MACF;AACA,YAAM,OAAQ,MAAM,IAAI,KAAK;AAM7B,aAAO;AAAA,QACL,QAAQ,gBAAgB,KAAK,MAAM;AAAA,QACnC,mBAAmB,KAAK;AAAA,QACxB,SAAS,KAAK;AAAA,QACd,OAAO,KAAK;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACF;","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

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

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

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

@@ -0,0 +1,85 @@
+/**
+ * Framework-agnostic connect-flow state machine for the browser two-tab helper.
+ *
+ * @remarks
+ * This is the testable core behind {@link useDirectVanaConnect}. It is pure
+ * TypeScript (no React, no DOM-only APIs beyond an injectable window opener and
+ * timers) so the full flow — create request, open Vana, poll status, read data —
+ * can be exercised in a Node test environment.
+ *
+ * The React hook is a thin `useSyncExternalStore` binding over this store.
+ *
+ * @category Direct
+ * @module direct/connect-flow
+ */
+import type { AccessRequest, AccessRequestStatus, ApprovedDataResult } from "./types";
+/**
+ * Caller-supplied transports. These typically `fetch` the app's own backend
+ * routes, which in turn delegate to a {@link DirectDataController}.
+ */
+export interface DirectConnectTransports<T = unknown> {
+    /** Ask the backend to create an access request. */
+    createRequest: () => Promise<AccessRequest>;
+    /** Ask the backend for the current status of a request. */
+    getStatus: (requestId: string) => Promise<AccessRequestStatus>;
+    /** Ask the backend to read the approved data. */
+    readResult: (requestId: string) => Promise<ApprovedDataResult<T>>;
+}
+/** Tunables for the connect flow. */
+export interface DirectConnectOptions {
+    /** Status poll interval in ms. Defaults to 1500. */
+    pollIntervalMs?: number;
+    /** Overall timeout in ms before giving up. Defaults to 300000 (5 min). */
+    timeoutMs?: number;
+    /** Opens the approval URL. Defaults to `window.open`. Injectable for tests. */
+    openWindow?: (url: string) => void;
+    /** `setTimeout`. Injectable for tests. Defaults to `globalThis.setTimeout`. */
+    setTimeoutFn?: (cb: () => void, ms: number) => unknown;
+    /** `clearTimeout`. Injectable for tests. Defaults to `globalThis.clearTimeout`. */
+    clearTimeoutFn?: (handle: unknown) => void;
+    /** Clock source in ms. Injectable for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Discriminated connect-flow state.
+ *
+ * @remarks
+ * `type` matches the builder guide: it starts at `"idle"` and is non-idle while
+ * connecting. The intermediate phases give richer UIs something to render.
+ */
+export type DirectConnectState<T = unknown> = {
+    type: "idle";
+} | {
+    type: "creating";
+} | {
+    type: "awaiting_approval";
+    request: AccessRequest;
+} | {
+    type: "reading";
+    request: AccessRequest;
+} | {
+    type: "done";
+    result: ApprovedDataResult<T>;
+} | {
+    type: "error";
+    error: Error;
+};
+/** The store returned by {@link createDirectConnectFlow}. */
+export interface DirectConnectFlow<T = unknown> {
+    /** Current state. */
+    getState(): DirectConnectState<T>;
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Begin the flow. No-op if already running. */
+    start(): Promise<void>;
+    /** Reset to `idle` and stop any in-flight polling. */
+    reset(): void;
+}
+/**
+ * Create a connect-flow store.
+ *
+ * @param transports - Backend transports (`createRequest`, `getStatus`, `readResult`).
+ * @param options - Polling/timeout tunables and injectable side effects.
+ * @returns A {@link DirectConnectFlow} store.
+ */
+export declare function createDirectConnectFlow<T = unknown>(transports: DirectConnectTransports<T>, options?: DirectConnectOptions): DirectConnectFlow<T>;