@opendatalabs/connect 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,38 @@
-# @opendatalabs/connect
+# Vana Connect SDK
 
-SDK for integrating Vana Data Portability "Connect data" flows into builder applications.
+Let your users customize your app with their own data.
+
+Users connect platforms they already use — ChatGPT, Instagram, Gmail, and more — through the [Vana Desktop App](https://www.vana.com/download), which keeps them in control of what's shared. Your app receives structured, user-consented data through a cryptographically verified grant. No scraping, no OAuth token juggling, no compliance gray areas.
+
+## How it works
+
+```
+Your App                         Vana Protocol
+──────────────────────────────   ──────────────────────────────
+
+1. connect({ scopes })
+   → creates session
+   → returns deep link      ──▶  2. User opens Desktop App
+                                     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 SDK handles session creation, cryptographic request signing, polling, and data fetching. You write three function calls; the protocol handles the rest.
+
+## Where this fits in the Vana protocol
+
+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. The protocol participants are:
+
+- **Personal Server** — stores and serves user data, enforces grants
+- **Data Portability Gateway** — fast API with eventual on-chain consistency
+- **Vana L1** — on-chain source of truth for grants, builder registry, and file records
+
+**This SDK is the builder integration layer.** It sits between your app and the protocol, abstracting the Session Relay handshake, Web3Signed authentication, and Personal Server data fetching into a clean API.
 
 ## Installation
 
@@ -8,37 +40,36 @@ SDK for integrating Vana Data Portability "Connect data" flows into builder appl
 npm install @opendatalabs/connect
 ```
 
-## Entrypoints
+## Prerequisites
 
-| Entrypoint                     | Environment | Description                                                       |
-| ------------------------------ | ----------- | ----------------------------------------------------------------- |
-| `@opendatalabs/connect/server` | Node.js     | `connect()`, `getData()`, `signVanaManifest()`, low-level clients |
-| `@opendatalabs/connect/react`  | Browser     | Polling hook, connect button                                      |
-| `@opendatalabs/connect/core`   | Universal   | Shared types, errors, and constants                               |
+Register as a builder through the Vana Desktop App first.
 
-## Quick Start
+## Quickstart
 
-### 1. Initialize a session (server)
+### 1. Create a session (server)
 
 ```typescript
 import { connect } from "@opendatalabs/connect/server";
 
 const session = await connect({
-  privateKey: process.env.VANA_PRIVATE_KEY as `0x${string}`,
+  privateKey: process.env.VANA_APP_PRIVATE_KEY as `0x${string}`,
   scopes: ["chatgpt.conversations"],
+  webhookUrl: "https://yourapp.com/api/webhook", // optional
+  appUserId: "user-42", // optional
 });
 
-// session.sessionId   — pass to the client for polling
-// session.deepLinkUrl — surface to the user (QR code, deep link, etc.)
-// session.expiresAt   — session expiration timestamp
+// Return to your frontend:
+// session.sessionId   — used for polling
+// session.deepLinkUrl — opens the Vana Desktop App
+// session.expiresAt   — ISO 8601 expiration
 ```
 
-### 2. Poll for approval (client)
+### 2. Poll for user approval (client)
 
 ```tsx
 import { useVanaConnect } from "@opendatalabs/connect/react";
 
-function ConnectPage({ sessionId }: { sessionId: string }) {
+function ConnectData({ sessionId }: { sessionId: string }) {
   const { connect, status, grant, deepLinkUrl } = useVanaConnect();
 
   useEffect(() => {
@@ -46,72 +77,141 @@ function ConnectPage({ sessionId }: { sessionId: string }) {
   }, [sessionId]);
 
   if (status === "waiting" && deepLinkUrl) {
-    return <a href={deepLinkUrl}>Open Vana Desktop App</a>;
+    return <a href={deepLinkUrl}>Connect your data</a>;
   }
-
   if (status === "approved" && grant) {
-    return <p>Connected! Grant: {grant.grantId}</p>;
+    // grant.grantId, grant.userAddress, grant.scopes are available
+    return <p>Connected.</p>;
   }
-
-  return <p>Status: {status}</p>;
+  return <p>{status}</p>;
 }
 ```
 
-### 3. Fetch data (server)
+Or use the pre-built button:
+
+```tsx
+import { ConnectButton } from "@opendatalabs/connect/react";
+
+<ConnectButton
+  sessionId={sessionId}
+  onComplete={(grant) => saveGrant(grant)}
+  onError={(err) => console.error(err)}
+/>;
+```
+
+### 3. Fetch user data (server)
 
 ```typescript
 import { getData } from "@opendatalabs/connect/server";
 
 const data = await getData({
-  privateKey: process.env.VANA_PRIVATE_KEY as `0x${string}`,
-  grant, // GrantPayload from the approval step
+  privateKey: process.env.VANA_APP_PRIVATE_KEY as `0x${string}`,
+  grant, // GrantPayload from step 2
 });
 
-// data is a Map<string, unknown> keyed by scope
+// Record<string, unknown> keyed by scope
+const conversations = data["chatgpt.conversations"];
 ```
 
-### Options
+### Web App Manifest
+
+The Desktop App verifies your identity by fetching your manifest. Use `signVanaManifest()` to generate it:
 
 ```typescript
-// connect() options
-await connect({
-  privateKey: "0x...",
-  scopes: ["chatgpt.conversations"],
-  webhookUrl: "https://...", // optional webhook for session events
-  appUserId: "user-42", // optional app-level user ID
+import { signVanaManifest } from "@opendatalabs/connect/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
+};
 ```
 
-### 4. Sign a web app manifest (server)
+Make sure your HTML includes `<link rel="manifest" href="/manifest.json">`.
+
+## API Reference
+
+### Entrypoints
+
+| Import                         | Environment | Exports                                                           |
+| ------------------------------ | ----------- | ----------------------------------------------------------------- |
+| `@opendatalabs/connect/server` | Node.js     | `connect()`, `getData()`, `signVanaManifest()`, low-level clients |
+| `@opendatalabs/connect/react`  | Browser     | `useVanaConnect()`, `useVanaData()`, `ConnectButton`              |
+| `@opendatalabs/connect/core`   | Universal   | Types, `ConnectError`, constants                                  |
+
+### `connect(config): Promise<SessionInitResult>`
+
+Creates a session on the Session Relay. Returns `sessionId`, `deepLinkUrl`, 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
-import { signVanaManifest } from "@opendatalabs/connect/server";
+const { connect, status, grant, error, deepLinkUrl, reset } = useVanaConnect();
+```
 
-const vanaBlock = await signVanaManifest({
-  privateKey: process.env.VANA_PRIVATE_KEY as `0x${string}`,
-  appUrl: "https://your-app.example.com",
-  privacyPolicyUrl: "https://your-app.example.com/privacy",
-  termsUrl: "https://your-app.example.com/terms",
-  supportUrl: "https://your-app.example.com/support",
-  webhookUrl: "https://your-app.example.com/api/webhook",
-});
+`status` transitions: `idle` &rarr; `connecting` &rarr; `waiting` &rarr; `approved` | `denied` | `expired` | `error`
 
-// Include vanaBlock in your W3C Web App Manifest as the "vana" key
-// The Desktop App fetches this manifest to verify builder identity
+### `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)
+}
 ```
 
-### Advanced (Low-Level APIs)
+### Low-level clients
 
-For full control, the low-level factories are still available:
+For full control over individual protocol interactions:
 
 ```typescript
 import {
-  createSessionRelay,
-  createDataClient,
-  createRequestSigner,
+  createRequestSigner, // Web3Signed header generation
+  createSessionRelay, // Session Relay HTTP client
+  createDataClient, // Data Gateway HTTP client
 } from "@opendatalabs/connect/server";
 ```
 
+## Examples
+
+See [`examples/nextjs-starter`](./examples/nextjs-starter) for a complete working integration with Next.js, including manifest signing, webhook handling, and the full connect-to-data-fetch flow.
+
 ## License
 
 MIT

package/dist/core/constants.d.ts

@@ -1,3 +1,29 @@
-export declare const SESSION_RELAY_URL = "https://session-relay-git-dev-opendatalabs.vercel.app";
-export declare const GATEWAY_URL = "https://data-gateway-env-dev-opendatalabs.vercel.app";
+/** SDK environment selector. */
+export type VanaEnvironment = "dev" | "prod";
+/** URL configuration for each SDK environment. */
+export declare const ENV_CONFIG: {
+    readonly dev: {
+        readonly sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app";
+        readonly gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app";
+    };
+    readonly prod: {
+        readonly sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app";
+        readonly gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app";
+    };
+};
+/** Default environment used when none is specified. */
+export declare const DEFAULT_ENVIRONMENT: VanaEnvironment;
+/**
+ * Returns the URL configuration for the given environment.
+ *
+ * @param environment - `"dev"` or `"prod"`. Defaults to {@link DEFAULT_ENVIRONMENT}.
+ * @returns An object with `sessionRelayUrl` and `gatewayUrl`.
+ */
+export declare function getEnvConfig(environment?: VanaEnvironment): {
+    readonly sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app";
+    readonly gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app";
+} | {
+    readonly sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app";
+    readonly gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app";
+};
 //# sourceMappingURL=constants.d.ts.map

package/dist/core/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,0DAC2B,CAAC;AAC1D,eAAO,MAAM,WAAW,yDACgC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C,kDAAkD;AAClD,eAAO,MAAM,UAAU;;;;;;;;;CAUb,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,EAAE,eAAwB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,CAAC,EAAE,eAAe;;;;;;EAEzD"}

package/dist/core/constants.js

@@ -1,3 +1,24 @@
-export const SESSION_RELAY_URL = "https://session-relay-git-dev-opendatalabs.vercel.app";
-export const GATEWAY_URL = "https://data-gateway-env-dev-opendatalabs.vercel.app";
+/** URL configuration for each SDK environment. */
+export const ENV_CONFIG = {
+    dev: {
+        sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app",
+        gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app",
+    },
+    prod: {
+        // TODO: Replace with actual production URLs
+        sessionRelayUrl: "https://session-relay-git-dev-opendatalabs.vercel.app",
+        gatewayUrl: "https://data-gateway-env-dev-opendatalabs.vercel.app",
+    },
+};
+/** Default environment used when none is specified. */
+export const DEFAULT_ENVIRONMENT = "prod";
+/**
+ * Returns the URL configuration for the given environment.
+ *
+ * @param environment - `"dev"` or `"prod"`. Defaults to {@link DEFAULT_ENVIRONMENT}.
+ * @returns An object with `sessionRelayUrl` and `gatewayUrl`.
+ */
+export function getEnvConfig(environment) {
+    return ENV_CONFIG[environment ?? DEFAULT_ENVIRONMENT];
+}
 //# sourceMappingURL=constants.js.map

package/dist/core/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAC5B,uDAAuD,CAAC;AAC1D,MAAM,CAAC,MAAM,WAAW,GACtB,sDAAsD,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAGA,kDAAkD;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,GAAG,EAAE;QACH,eAAe,EAAE,uDAAuD;QACxE,UAAU,EAAE,sDAAsD;KACnE;IACD,IAAI,EAAE;QACJ,4CAA4C;QAC5C,eAAe,EAAE,uDAAuD;QACxE,UAAU,EAAE,sDAAsD;KACnE;CACO,CAAC;AAEX,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAoB,MAAM,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,WAA6B;IACxD,OAAO,UAAU,CAAC,WAAW,IAAI,mBAAmB,CAAC,CAAC;AACxD,CAAC"}

package/dist/core/errors.d.ts

@@ -1,6 +1,47 @@
+/**
+ * Known error codes thrown by the SDK.
+ *
+ * Use these constants for typed `catch` handling instead of comparing raw strings.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectError, ConnectErrorCode } from "@opendatalabs/connect/core";
+ *
+ * try {
+ *   await getData({ privateKey, grant });
+ * } catch (err) {
+ *   if (err instanceof ConnectError && err.code === ConnectErrorCode.SERVER_NOT_FOUND) {
+ *     // handle missing server
+ *   }
+ * }
+ * ```
+ */
+export declare const ConnectErrorCode: {
+    readonly SESSION_INIT_FAILED: "SESSION_INIT_FAILED";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly POLL_FAILED: "POLL_FAILED";
+    readonly POLL_TIMEOUT: "POLL_TIMEOUT";
+    readonly SERVER_NOT_FOUND: "SERVER_NOT_FOUND";
+    readonly GATEWAY_ERROR: "GATEWAY_ERROR";
+    readonly DATA_FETCH_FAILED: "DATA_FETCH_FAILED";
+    readonly LIST_SCOPES_FAILED: "LIST_SCOPES_FAILED";
+    readonly LIST_VERSIONS_FAILED: "LIST_VERSIONS_FAILED";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly WEBHOOK_INVALID: "WEBHOOK_INVALID";
+};
+/** Union type of all known error code string values. */
+export type ConnectErrorCode = (typeof ConnectErrorCode)[keyof typeof ConnectErrorCode];
+/**
+ * Error class thrown by all SDK operations.
+ *
+ * Includes a typed {@link code} for programmatic handling and an optional
+ * {@link statusCode} from HTTP responses.
+ */
 export declare class ConnectError extends Error {
-    readonly code: string;
+    /** Machine-readable error code. One of {@link ConnectErrorCode} or an arbitrary server-returned string. */
+    readonly code: ConnectErrorCode | (string & {});
+    /** HTTP status code from the upstream response, if applicable. */
     readonly statusCode?: number;
-    constructor(message: string, code: string, statusCode?: number);
+    constructor(message: string, code: ConnectErrorCode | (string & {}), statusCode?: number);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAM/D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;CAYnB,CAAC;AAEX,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACtC,UAAU,CAAC,EAAE,MAAM;CAOtB"}

package/dist/core/errors.js

@@ -1,5 +1,44 @@
+/**
+ * Known error codes thrown by the SDK.
+ *
+ * Use these constants for typed `catch` handling instead of comparing raw strings.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectError, ConnectErrorCode } from "@opendatalabs/connect/core";
+ *
+ * try {
+ *   await getData({ privateKey, grant });
+ * } catch (err) {
+ *   if (err instanceof ConnectError && err.code === ConnectErrorCode.SERVER_NOT_FOUND) {
+ *     // handle missing server
+ *   }
+ * }
+ * ```
+ */
+export const ConnectErrorCode = {
+    SESSION_INIT_FAILED: "SESSION_INIT_FAILED",
+    SESSION_EXPIRED: "SESSION_EXPIRED",
+    POLL_FAILED: "POLL_FAILED",
+    POLL_TIMEOUT: "POLL_TIMEOUT",
+    SERVER_NOT_FOUND: "SERVER_NOT_FOUND",
+    GATEWAY_ERROR: "GATEWAY_ERROR",
+    DATA_FETCH_FAILED: "DATA_FETCH_FAILED",
+    LIST_SCOPES_FAILED: "LIST_SCOPES_FAILED",
+    LIST_VERSIONS_FAILED: "LIST_VERSIONS_FAILED",
+    CONFIG_INVALID: "CONFIG_INVALID",
+    WEBHOOK_INVALID: "WEBHOOK_INVALID",
+};
+/**
+ * Error class thrown by all SDK operations.
+ *
+ * Includes a typed {@link code} for programmatic handling and an optional
+ * {@link statusCode} from HTTP responses.
+ */
 export class ConnectError extends Error {
+    /** Machine-readable error code. One of {@link ConnectErrorCode} or an arbitrary server-returned string. */
     code;
+    /** HTTP status code from the upstream response, if applicable. */
     statusCode;
     constructor(message, code, statusCode) {
         super(message);

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAS;IACb,UAAU,CAAU;IAE7B,YAAY,OAAe,EAAE,IAAY,EAAE,UAAmB;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,mBAAmB,EAAE,qBAAqB;IAC1C,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAC1B,YAAY,EAAE,cAAc;IAC5B,gBAAgB,EAAE,kBAAkB;IACpC,aAAa,EAAE,eAAe;IAC9B,iBAAiB,EAAE,mBAAmB;IACtC,kBAAkB,EAAE,oBAAoB;IACxC,oBAAoB,EAAE,sBAAsB;IAC5C,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAMX;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,2GAA2G;IAClG,IAAI,CAAmC;IAChD,kEAAkE;IACzD,UAAU,CAAU;IAE7B,YACE,OAAe,EACf,IAAsC,EACtC,UAAmB;QAEnB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/core/grants.d.ts

@@ -0,0 +1,19 @@
+import type { GrantPayload } from "./types.js";
+/**
+ * Type guard that checks whether an unknown value has the shape of a {@link GrantPayload}.
+ *
+ * Validates the presence and types of required fields: `grantId`, `userAddress`,
+ * `builderAddress`, and `scopes` (non-empty string array).
+ *
+ * @example
+ * ```typescript
+ * const body = await request.json();
+ * if (!isValidGrant(body.grant)) {
+ *   return NextResponse.json({ error: "Invalid grant" }, { status: 400 });
+ * }
+ * // body.grant is now typed as GrantPayload
+ * const data = await getData({ privateKey, grant: body.grant });
+ * ```
+ */
+export declare function isValidGrant(value: unknown): value is GrantPayload;
+//# sourceMappingURL=grants.d.ts.map

package/dist/core/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/core/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAgBlE"}

package/dist/core/grants.js

@@ -0,0 +1,31 @@
+/**
+ * Type guard that checks whether an unknown value has the shape of a {@link GrantPayload}.
+ *
+ * Validates the presence and types of required fields: `grantId`, `userAddress`,
+ * `builderAddress`, and `scopes` (non-empty string array).
+ *
+ * @example
+ * ```typescript
+ * const body = await request.json();
+ * if (!isValidGrant(body.grant)) {
+ *   return NextResponse.json({ error: "Invalid grant" }, { status: 400 });
+ * }
+ * // body.grant is now typed as GrantPayload
+ * const data = await getData({ privateKey, grant: body.grant });
+ * ```
+ */
+export function isValidGrant(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const obj = value;
+    return (typeof obj.grantId === "string" &&
+        obj.grantId.length > 0 &&
+        typeof obj.userAddress === "string" &&
+        obj.userAddress.length > 0 &&
+        typeof obj.builderAddress === "string" &&
+        obj.builderAddress.length > 0 &&
+        Array.isArray(obj.scopes) &&
+        obj.scopes.length > 0 &&
+        obj.scopes.every((s) => typeof s === "string" && s.length > 0));
+}
+//# sourceMappingURL=grants.js.map

package/dist/core/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/core/grants.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,OAAO,CACL,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QACtB,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ;QACnC,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAC1B,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ;QACtC,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC7B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QACzB,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QACrB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC"}

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
-export { ConnectError } from "./errors.js";
-export { SESSION_RELAY_URL, GATEWAY_URL } from "./constants.js";
+export { ConnectError, ConnectErrorCode } from "./errors.js";
+export { isValidGrant } from "./grants.js";
+export { getEnvConfig, ENV_CONFIG, DEFAULT_ENVIRONMENT, type VanaEnvironment, } from "./constants.js";
 export type { ConnectionStatus, SessionInitParams, SessionInitResult, SessionPollResult, GrantPayload, DataFetchParams, RequestSignerConfig, SessionRelayConfig, DataClientConfig, ConnectConfig, GetDataConfig, VanaManifestConfig, VanaManifestBlock, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/core/index.js

@@ -1,3 +1,4 @@
-export { ConnectError } from "./errors.js";
-export { SESSION_RELAY_URL, GATEWAY_URL } from "./constants.js";
+export { ConnectError, ConnectErrorCode } from "./errors.js";
+export { isValidGrant } from "./grants.js";
+export { getEnvConfig, ENV_CONFIG, DEFAULT_ENVIRONMENT, } from "./constants.js";
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,GAEpB,MAAM,gBAAgB,CAAC"}