vana-cli 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenDataLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# OpenDataLabs Context Gateway JavaScript SDK
+
+`vana-cli` is the JavaScript client SDK for
+[OpenDataLabs Context Gateway](https://www.opendatalabs.com/context-gateway).
+Use it to let users connect their own data to your app.
+
+## CLI
+
+The `vana` CLI collects your personal data from any platform. See the **[CLI README](./cli/README.md)**.
+
+Install on macOS with Homebrew:
+
+```bash
+brew tap vana-com/tap
+brew install vana
+vana status
+```
+
+Or use the hosted prerelease installer on macOS/Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/vana-com/vana-cli/main/install/install.sh | sh
+```
+
+Branch prerelease:
+
+- `https://github.com/vana-com/vana-cli/releases/tag/canary-feat-connect-cli-v1`
+
+Once installed:
+
+```bash
+vana connect linkedin
+```
+
+## What problem this solves
+
+Your users already have rich personal data — ChatGPT conversations, Instagram activity, Gmail, purchase history — but it's locked inside the platforms that collected it. As a builder, you can't easily use that data to personalize onboarding, tailor recommendations, or skip lengthy signup forms.
+
+**Data portability** means users can export their data from these platforms and grant your app scoped access to it — with their explicit consent, cryptographic verification, and full control over what's shared and when to revoke it.
+
+Today, getting access to user data means asking for manual file uploads (high friction), scraping on their behalf (fragile and legally risky), or negotiating enterprise API deals (slow and expensive). This SDK gives you a standardized way to request and receive personal data through Vana's [Data Portability Protocol](https://docs.vana.org/), handling session creation, grant verification, and data fetching in three function calls.
+
+## How it works
+
+```
+Your App                         Vana Protocol
+──────────────────────────────   ──────────────────────────────
+
+1. connect({ scopes })
+   → creates session
+   → returns deep link      ──▶  2. User opens DataConnect
+                                    reviews scopes, exports data,
+                                    approves grant
+
+3. Poll resolves with grant  ◀──  Grant signed & registered
+
+4. getData({ grant })        ──▶  5. Personal Server returns
+   → structured JSON                 user data over TLS
+```
+
+The [Data Portability Protocol](https://docs.vana.org/) defines how users collect data from platforms, store it under their control (on-device or hosted), and grant third-party apps scoped access. This SDK handles session creation, cryptographic request signing, polling, and data fetching. You write three function calls; the protocol handles the rest.
+
+## Getting started
+
+The fastest way to get up and running is with the `examples/nextjs-starter` — a complete working app which uses the development environment and has full flow of data portability wired up:
+
+```bash
+git clone https://github.com/vana-com/vana-cli.git
+cd vana-connect/examples/nextjs-starter
+cp .env.local.example .env.local
+```
+
+Use the pre-registered dev key in .env.local. Note that this private key is ONLY for testing and works only with a testing Vana environment.
+
+```
+VANA_PRIVATE_KEY=0x3c05ac1a00546bc0b1b8d3a11fb908409005fac3f26d25f70711e4f632e720d3
+APP_URL=http://localhost:3001
+```
+
+Install and run
+
+```
+pnpm install
+pnpm dev
+```
+
+Note that while testing this example app, you should have a development version of the [DataConnect app](https://github.com/vana-com/data-connect?tab=readme-ov-file#development).
+
+There is one caveat in development: the deep-link for DataConnect app doesn't open the dev version of the app.
+This means that when testing your app from the end user perspective, once you see this screen:
+<img width="627" height="560" alt="Screenshot 2026-02-21 at 15 02 58" src="https://github.com/user-attachments/assets/477ae78f-d84d-4178-a1e9-48abedf36946" />
+
+Instead of clicking the "Launch DataConnect" button, you should right-click on it and copy its address. The address will be something like `vana://connect?sessionId=...`.
+
+Then, in your dev version of DataConnect (likely built from the `main` branch) you will see a place to copy the link in the right-bottom corner of the app:
+
+<img width="348" height="258" alt="Screenshot 2026-02-21 at 15 09 18" src="https://github.com/user-attachments/assets/9f9d7a14-c92e-4185-bdc2-a2d93282c748" />
+
+---
+
+## Manual integration
+
+If you prefer to integrate the SDK into an existing project, follow the steps below.
+
+## Headless CLI
+
+`vana-connect` now also ships a local collection CLI for connector setup and data export flows.
+
+If you only care about the CLI, start with [docs/CLI-README.md](./docs/CLI-README.md).
+
+For the full CLI review surface, use:
+
+- [CLI review surface](./docs/CLI-REVIEW-SURFACE.md)
+- [CLI transcripts](./docs/transcripts/README.md)
+- [CLI demos](./docs/vhs/README.md)
+
+`pnpm build:sea` uses Node 25's `--build-sea` flow to create a small `vana` launcher and packages the real app payload next to it under `app/`.
+It produces a platform-specific release directory plus a release archive and matching checksum file under `artifacts/sea/`.
+
+### Programmatic runtime access
+
+If you are building an app surface like DataConnect Desktop or a hosted orchestration layer, use the SDK modules instead of shelling out to the CLI where possible.
+
+```ts
+import { ManagedPlaywrightRuntime } from "vana-cli/runtime";
+import { listAvailableSources } from "vana-cli/connectors";
+```
+
+Intended split:
+
+- app surfaces consume SDK/runtime APIs
+- agent skills consume the CLI
+- `data-connectors` remains the connector and schema source of truth
+
+### Installation
+
+```bash
+pnpm add vana-cli
+```
+
+### Package manager
+
+This repo is pnpm-only for local development and examples. Use `pnpm` commands, not `npm`.
+
+### Prerequisites
+
+First, register your app in the [Developer Portal](https://vana-developers.replit.app/). You will need to provide the URL where your app will be deployed, and then be given a private key after registration.
+
+### Quickstart
+
+#### 1. Create a session (server)
+
+```typescript
+import { connect } from "vana-cli/server";
+
+const session = await connect({
+  privateKey: process.env.VANA_APP_PRIVATE_KEY as `0x${string}`,
+  scopes: ["chatgpt.conversations"],
+  webhookUrl: "https://yourapp.com/api/webhook", // optional, data can be pushed to a web hook after a grant is approved
+  appUserId: "yourapp-user-42", // optional: correlate your app user with the data they provided
+});
+
+// Return to your frontend:
+// session.sessionId  — used for polling
+// session.connectUrl — opens the Vana account page → launches DataConnect
+// session.expiresAt  — ISO 8601 expiration
+```
+
+#### 2. Poll for user approval (client)
+
+```tsx
+import { useVanaConnect } from "vana-cli/react";
+
+function ConnectData({ sessionId }: { sessionId: string }) {
+  const { connect, status, grant, connectUrl } = useVanaConnect();
+
+  useEffect(() => {
+    connect({ sessionId });
+  }, [sessionId]);
+
+  if (status === "waiting" && connectUrl) {
+    return <a href={connectUrl}>Connect your data</a>;
+  }
+  if (status === "approved" && grant) {
+    // grant.grantId, grant.userAddress, grant.scopes are available
+    return <p>Connected.</p>;
+  }
+  return <p>{status}</p>;
+}
+```
+
+Or use the pre-built button:
+
+```tsx
+import { ConnectButton } from "vana-cli/react";
+
+<ConnectButton
+  sessionId={sessionId}
+  onComplete={(grant) => saveGrant(grant)}
+  onError={(err) => console.error(err)}
+/>;
+```
+
+#### 3. Fetch user data (server)
+
+```typescript
+import { getData } from "vana-cli/server";
+
+const data = await getData({
+  privateKey: process.env.VANA_APP_PRIVATE_KEY as `0x${string}`,
+  grant, // GrantPayload from step 2
+});
+
+// Record<string, unknown> keyed by scope
+const conversations = data["chatgpt.conversations"];
+```
+
+#### Web App Manifest
+
+The DataConnect App verifies your identity by fetching your manifest. Use `signVanaManifest()` to generate it:
+
+```typescript
+import { signVanaManifest } from "vana-cli/server";
+
+// In your manifest route handler (e.g. Next.js /manifest.json/route.ts):
+const vanaBlock = await signVanaManifest({
+  privateKey: process.env.VANA_APP_PRIVATE_KEY as `0x${string}`,
+  appUrl: "https://yourapp.com",
+  privacyPolicyUrl: "https://yourapp.com/privacy",
+  termsUrl: "https://yourapp.com/terms",
+  supportUrl: "https://yourapp.com/support",
+  webhookUrl: "https://yourapp.com/api/webhook",
+});
+
+const manifest = {
+  name: "Your App",
+  short_name: "YourApp",
+  start_url: "/",
+  display: "standalone",
+  vana: vanaBlock, // signed identity block
+};
+```
+
+Make sure your HTML includes `<link rel="manifest" href="/manifest.json">`.
+
+## Connectors
+
+Available data connectors and their scopes (schema definitions):
+[`vana-com/data-connectors/schemas`](https://github.com/vana-com/data-connectors/tree/main/schemas)
+
+## API Reference
+
+### Entrypoints
+
+| Import            | Environment | Exports                                                           |
+| ----------------- | ----------- | ----------------------------------------------------------------- |
+| `vana-cli/server` | Node.js     | `connect()`, `getData()`, `signVanaManifest()`, low-level clients |
+| `vana-cli/react`  | Browser     | `useVanaConnect()`, `useVanaData()`, `ConnectButton`              |
+| `vana-cli/core`   | Universal   | Types, `ConnectError`, constants                                  |
+
+### `connect(config): Promise<SessionInitResult>`
+
+Creates a session on the Session Relay. Returns `sessionId`, `connectUrl`, and `expiresAt`.
+
+| Param        | Type                | Required | Description                                                            |
+| ------------ | ------------------- | -------- | ---------------------------------------------------------------------- |
+| `privateKey` | `` `0x${string}` `` | Yes      | Builder private key                                                    |
+| `scopes`     | `string[]`          | Yes      | Data scopes to request                                                 |
+| `webhookUrl` | `string`            | No       | Public HTTPS URL for grant event notifications (localhost is rejected) |
+| `appUserId`  | `string`            | No       | Your app's user ID for correlation                                     |
+
+### `getData(config): Promise<Record<string, unknown>>`
+
+Fetches user data from their Personal Server using a signed grant.
+
+| Param        | Type                | Required | Description                  |
+| ------------ | ------------------- | -------- | ---------------------------- |
+| `privateKey` | `` `0x${string}` `` | Yes      | Builder private key          |
+| `grant`      | `GrantPayload`      | Yes      | Grant from the approval step |
+
+### `useVanaConnect(config?): UseVanaConnectResult`
+
+React hook that polls the Session Relay and manages connection state.
+
+```typescript
+const { connect, status, grant, error, connectUrl, reset } = useVanaConnect();
+```
+
+`status` transitions: `idle` &rarr; `connecting` &rarr; `waiting` &rarr; `approved` | `denied` | `expired` | `error`
+
+### `GrantPayload`
+
+Returned when a user approves access:
+
+```typescript
+interface GrantPayload {
+  grantId: string; // on-chain permission ID
+  userAddress: string; // user's wallet address
+  builderAddress: string; // your registered address
+  scopes: string[]; // approved data scopes
+  serverAddress?: string; // user's Personal Server
+  appUserId?: string; // your app's user ID (if provided)
+}
+```
+
+### Low-level clients
+
+For full control over individual protocol interactions:
+
+```typescript
+import {
+  createRequestSigner, // Web3Signed header generation
+  createSessionRelay, // Session Relay HTTP client
+  createDataClient, // Data Gateway HTTP client
+} from "vana-cli/server";
+```
+
+## License
+
+MIT

package/dist/cli/auth.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Credential management for Vana CLI authentication.
+ *
+ * Stores and retrieves auth credentials from ~/.vana/auth.json.
+ * Supports the device code flow for browser-based login and
+ * env var overrides for CI/automation.
+ */
+export interface VanaCredentials {
+    account: {
+        address: string;
+        session_token: string;
+        expires_at: string;
+    };
+    personal_server: {
+        url: string;
+        session_token: string;
+        expires_at: string;
+    } | null;
+}
+/**
+ * Load credentials from disk or env vars.
+ *
+ * Priority:
+ * 1. Env vars (VANA_SESSION_TOKEN, VANA_PS_TOKEN, VANA_PS_URL)
+ * 2. File (~/.vana/auth.json)
+ *
+ * Returns null if no credentials are available or if they are expired.
+ */
+export declare function loadCredentials(): VanaCredentials | null;
+/**
+ * Save credentials to ~/.vana/auth.json with 0600 permissions.
+ */
+export declare function saveCredentials(creds: VanaCredentials): Promise<void>;
+/**
+ * Delete ~/.vana/auth.json.
+ */
+export declare function clearCredentials(): Promise<void>;
+/**
+ * Check if the account session token has expired.
+ */
+export declare function isExpired(creds: VanaCredentials): boolean;
+/**
+ * Format an address for display: 0x2Ab3...fa1
+ */
+export declare function formatAddress(address: string): string;
+/**
+ * Return human-readable time until expiry: "29 days", "3 hours", etc.
+ */
+export declare function formatExpiresIn(expiresAt: string): string;
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceCodePollAuthorized {
+    status: "authorized";
+    session_token: string;
+    personal_server_url?: string;
+    personal_server_session_token?: string;
+    ps_access_token?: string;
+    address: string;
+    expires_in?: number;
+    expires_at?: string;
+}
+export interface DeviceCodePollPending {
+    status: "pending";
+}
+export interface DeviceCodePollSlowDown {
+    status: "slow_down";
+}
+export interface DeviceCodePollExpired {
+    status: "expired";
+}
+export type DeviceCodePollResponse = DeviceCodePollAuthorized | DeviceCodePollPending | DeviceCodePollSlowDown | DeviceCodePollExpired;
+export interface DeviceCodeFlowOptions {
+    clientId?: string;
+}
+interface DeviceCodeFlowCallbacks {
+    onCode: (code: string, verificationUri: string) => void;
+    onWaiting: () => void;
+    onAuthorized: (creds: VanaCredentials) => void | Promise<void>;
+    onExpired: () => void;
+    onError: (error: Error) => void;
+}
+export declare function resolveOAuthClientId(accountUrl?: string): string;
+/**
+ * Request a device code from the auth server.
+ */
+export declare function requestDeviceCode(): Promise<DeviceCodeResponse>;
+/**
+ * Poll for device code authorization.
+ */
+export declare function pollDeviceCode(deviceCode: string): Promise<DeviceCodePollResponse>;
+/**
+ * Open a URL in the user's default browser.
+ * Best-effort — failures are silently ignored.
+ */
+export declare function openBrowser(url: string): void;
+/**
+ * Run the full device code login flow.
+ *
+ * Returns credentials on success, or null if the code expired.
+ * Calls the provided callbacks for UI updates.
+ */
+export declare function runDeviceCodeFlow(callbacks: DeviceCodeFlowCallbacks, options?: DeviceCodeFlowOptions): Promise<VanaCredentials | null>;
+export type AuthTarget = "cloud" | "self-hosted";
+export declare function getAuthTarget(psUrl: string | null): AuthTarget;
+export declare function resolvePersonalServerUrl(): string | undefined;
+export declare function runSelfHostedLoginFlow(serverUrl: string, onLoginUrl: (url: string) => void): Promise<{
+    server: string;
+    address: string;
+    session_token: string;
+    expires_at: string;
+}>;
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/cli/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cli/auth.ts"],"names":[],"mappings":"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"}