@opendatalabs/vana-sdk 3.14.1 → 3.16.0

package/dist/protocol/scope-actions.cjs

@@ -0,0 +1,185 @@
+"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 scope_actions_exports = {};
+__export(scope_actions_exports, {
+  InvalidScopeEntryError: () => InvalidScopeEntryError,
+  SCOPE_ACTIONS: () => SCOPE_ACTIONS,
+  formatScopeEntry: () => formatScopeEntry,
+  grantPermissions: () => grantPermissions,
+  hasAction: () => hasAction,
+  parseScopeEntry: () => parseScopeEntry,
+  permissionsToScopes: () => permissionsToScopes,
+  tryGrantPermissions: () => tryGrantPermissions
+});
+module.exports = __toCommonJS(scope_actions_exports);
+var import_scopes = require("./scopes");
+const SCOPE_ACTIONS = ["read", "write"];
+class InvalidScopeEntryError extends Error {
+  /** The offending entry, verbatim (unknown because it may not be a string). */
+  entry;
+  constructor(entry, reason) {
+    super(`Invalid scope entry ${describeValue(entry)}: ${reason}`);
+    this.name = "InvalidScopeEntryError";
+    this.entry = entry;
+  }
+}
+const OPERATION_SEPARATOR = ":";
+function describeValue(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  return `[${typeof value}]`;
+}
+const OPERATION_BY_PREFIX = {
+  write: "write"
+};
+function assertScopePart(entry, scope) {
+  if (scope.length === 0) {
+    throw new InvalidScopeEntryError(entry, "scope part is empty");
+  }
+  if (scope.includes(OPERATION_SEPARATOR)) {
+    throw new InvalidScopeEntryError(
+      entry,
+      `scope part must not contain "${OPERATION_SEPARATOR}"`
+    );
+  }
+}
+function parseScopeEntry(entry) {
+  const raw = entry;
+  if (typeof raw !== "string") {
+    throw new InvalidScopeEntryError(raw, "entry must be a string");
+  }
+  const separatorIndex = entry.indexOf(OPERATION_SEPARATOR);
+  if (separatorIndex === -1) {
+    assertScopePart(entry, entry);
+    return { scope: entry, action: "read" };
+  }
+  const prefix = entry.slice(0, separatorIndex);
+  const scope = entry.slice(separatorIndex + 1);
+  const action = Object.hasOwn(OPERATION_BY_PREFIX, prefix) ? OPERATION_BY_PREFIX[prefix] : void 0;
+  if (action === void 0) {
+    throw new InvalidScopeEntryError(
+      entry,
+      `unknown operation "${prefix}" (known: ${Object.keys(OPERATION_BY_PREFIX).join(", ")}; read has no prefix)`
+    );
+  }
+  assertScopePart(entry, scope);
+  return { scope, action };
+}
+function formatScopeEntry(parsed) {
+  const { scope, action } = parsed;
+  assertScopePart(scope, scope);
+  if (action === "read") return scope;
+  const prefix = Object.entries(OPERATION_BY_PREFIX).find(
+    ([, candidate]) => candidate === action
+  )?.[0];
+  if (prefix === void 0) {
+    throw new InvalidScopeEntryError(
+      scope,
+      `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(", ")})`
+    );
+  }
+  return `${prefix}${OPERATION_SEPARATOR}${scope}`;
+}
+function compareScopes(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function sortActions(actions) {
+  const present = new Set(actions);
+  return SCOPE_ACTIONS.filter((action) => present.has(action));
+}
+function grantPermissions(scopes) {
+  const byScope = /* @__PURE__ */ new Map();
+  for (const entry of scopes) {
+    const { scope, action } = parseScopeEntry(entry);
+    let actions = byScope.get(scope);
+    if (actions === void 0) {
+      actions = /* @__PURE__ */ new Set();
+      byScope.set(scope, actions);
+    }
+    actions.add(action);
+  }
+  return [...byScope.keys()].sort(compareScopes).map((scope) => ({
+    scope,
+    actions: sortActions(byScope.get(scope) ?? [])
+  }));
+}
+function permissionsToScopes(permissions) {
+  const byScope = /* @__PURE__ */ new Map();
+  for (const { scope, actions } of permissions) {
+    let merged = byScope.get(scope);
+    if (merged === void 0) {
+      merged = /* @__PURE__ */ new Set();
+      byScope.set(scope, merged);
+    }
+    for (const action of actions) {
+      if (!SCOPE_ACTIONS.includes(action)) {
+        throw new InvalidScopeEntryError(
+          scope,
+          `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(", ")})`
+        );
+      }
+      merged.add(action);
+    }
+  }
+  const entries = [];
+  for (const scope of [...byScope.keys()].sort(compareScopes)) {
+    for (const action of sortActions(byScope.get(scope) ?? [])) {
+      entries.push(formatScopeEntry({ scope, action }));
+    }
+  }
+  return entries;
+}
+function hasAction(scopes, scope, action) {
+  if (scope.includes(OPERATION_SEPARATOR)) return false;
+  for (const entry of scopes) {
+    let parsed;
+    try {
+      parsed = parseScopeEntry(entry);
+    } catch (error) {
+      if (error instanceof InvalidScopeEntryError) continue;
+      throw error;
+    }
+    if (parsed.action === action && (0, import_scopes.scopeMatchesPattern)(scope, parsed.scope)) {
+      return true;
+    }
+  }
+  return false;
+}
+function tryGrantPermissions(scopes) {
+  try {
+    return grantPermissions(scopes);
+  } catch (error) {
+    if (error instanceof InvalidScopeEntryError) return void 0;
+    throw error;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InvalidScopeEntryError,
+  SCOPE_ACTIONS,
+  formatScopeEntry,
+  grantPermissions,
+  hasAction,
+  parseScopeEntry,
+  permissionsToScopes,
+  tryGrantPermissions
+});
+//# sourceMappingURL=scope-actions.cjs.map

package/dist/protocol/scope-actions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/scope-actions.ts"],"sourcesContent":["import { scopeMatchesPattern } from \"./scopes\";\n\n/**\n * Grant scope-entry grammar.\n *\n * A signed grant carries `scopes: string[]`. Each entry is\n * `[operation:]scope` - an optional lowercase ASCII operation prefix before\n * the first `:`, then a scope pattern (`*`, `{prefix}.*`, or an exact scope).\n * A missing prefix means read. `write:notes.entries` authorizes writing\n * `notes.entries` and nothing else; `notes.entries` authorizes reading it.\n *\n * The string form is the wire and storage detail: it is what the grantor\n * signs (EIP-712 `GrantRegistration.scopes`) and what the gateway stores\n * verbatim. The Personal Server is the sole interpreter, and this module is\n * the SDK-side mirror of that interpretation. Builders and consent UIs should\n * work with the grouped `{ scope, actions }` view (see\n * {@link grantPermissions}) and never construct or parse the strings by hand.\n *\n * Matching rules, pinned by the Personal Server policy\n * (personal-server-ts `packages/core/src/policy/data-write.ts` and\n * `data-read.ts`):\n * - the operation is compared exactly, case-sensitively;\n * - wildcards apply to the scope part only, via {@link scopeMatchesPattern};\n * - an entry whose operation is not recognised never authorizes anything.\n *   The parser fails closed on it (throws) rather than treating it as read;\n *   the matcher ({@link hasAction}) skips it, which is how the Personal\n *   Server treats an entry it does not understand.\n */\n\n/** Operations the grammar defines today, in canonical (output) order. */\nexport const SCOPE_ACTIONS = [\"read\", \"write\"] as const;\n\n/** An operation a grant entry can authorize over a scope. */\nexport type ScopeAction = (typeof SCOPE_ACTIONS)[number];\n\n/** One grant entry, split into its operation and scope pattern. */\nexport interface ParsedScopeEntry {\n  scope: string;\n  action: ScopeAction;\n}\n\n/**\n * The grouped view of a grant's scope entries: one row per scope pattern\n * with every operation the grant authorizes over it.\n */\nexport interface GrantPermission {\n  scope: string;\n  actions: ScopeAction[];\n}\n\n/**\n * Thrown when a scope entry does not fit the grammar - an unknown or\n * malformed operation prefix, or an empty scope part.\n */\nexport class InvalidScopeEntryError extends Error {\n  /** The offending entry, verbatim (unknown because it may not be a string). */\n  readonly entry: unknown;\n\n  constructor(entry: unknown, reason: string) {\n    super(`Invalid scope entry ${describeValue(entry)}: ${reason}`);\n    this.name = \"InvalidScopeEntryError\";\n    this.entry = entry;\n  }\n}\n\nconst OPERATION_SEPARATOR = \":\";\n\n// Render an untrusted value for an error message without ever throwing:\n// String() and JSON.stringify() both defer to the value's own toString /\n// toJSON, which a hostile JSON body can make throw.\nfunction describeValue(value: unknown): string {\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (value === null) return \"null\";\n  return `[${typeof value}]`;\n}\n\n// The only operation that is ever written out. Read has no prefix, and\n// `read:` is NOT an alias for it: the Personal Server's read policy matches\n// entries verbatim, so a `read:x` entry would authorize nothing there, and\n// the parser must reject it for the same reason.\nconst OPERATION_BY_PREFIX: Readonly<Record<string, ScopeAction>> = {\n  write: \"write\",\n};\n\nfunction assertScopePart(entry: string, scope: string): void {\n  if (scope.length === 0) {\n    throw new InvalidScopeEntryError(entry, \"scope part is empty\");\n  }\n  if (scope.includes(OPERATION_SEPARATOR)) {\n    throw new InvalidScopeEntryError(\n      entry,\n      `scope part must not contain \"${OPERATION_SEPARATOR}\"`,\n    );\n  }\n}\n\n/**\n * Split one grant scope entry into its operation and scope pattern.\n *\n * - `notes.entries` parses as `{ scope: \"notes.entries\", action: \"read\" }`\n * - `write:notes.*` parses as `{ scope: \"notes.*\", action: \"write\" }`\n *\n * Fails closed: a non-string entry, or an entry whose operation prefix is\n * not recognised (including\n * `read:`, any uppercase or non-ASCII prefix, or a wildcard in the operation\n * position) throws {@link InvalidScopeEntryError} and is never treated as a\n * read entry. An empty scope part (`write:`) throws as well.\n *\n * @param entry - A single element of a grant's `scopes` array.\n * @returns The operation and the scope pattern it applies to.\n * @throws InvalidScopeEntryError when the entry does not fit the grammar.\n */\nexport function parseScopeEntry(entry: string): ParsedScopeEntry {\n  // Grant bodies arrive from the network; a non-string element is a grammar\n  // violation like any other, not a TypeError from indexOf.\n  const raw: unknown = entry;\n  if (typeof raw !== \"string\") {\n    throw new InvalidScopeEntryError(raw, \"entry must be a string\");\n  }\n  const separatorIndex = entry.indexOf(OPERATION_SEPARATOR);\n  if (separatorIndex === -1) {\n    assertScopePart(entry, entry);\n    return { scope: entry, action: \"read\" };\n  }\n\n  const prefix = entry.slice(0, separatorIndex);\n  const scope = entry.slice(separatorIndex + 1);\n  const action = Object.hasOwn(OPERATION_BY_PREFIX, prefix)\n    ? OPERATION_BY_PREFIX[prefix]\n    : undefined;\n  if (action === undefined) {\n    throw new InvalidScopeEntryError(\n      entry,\n      `unknown operation \"${prefix}\" (known: ${Object.keys(OPERATION_BY_PREFIX).join(\", \")}; read has no prefix)`,\n    );\n  }\n  assertScopePart(entry, scope);\n  return { scope, action };\n}\n\n/**\n * Inverse of {@link parseScopeEntry}: render one operation over one scope\n * pattern as a grant scope entry. Read has no prefix.\n *\n * @param parsed - The operation and scope pattern to encode.\n * @returns The wire-form entry, e.g. `write:notes.entries` or `notes.entries`.\n * @throws InvalidScopeEntryError when the action is unknown or the scope part\n * is empty or contains `:`.\n */\nexport function formatScopeEntry(parsed: ParsedScopeEntry): string {\n  const { scope, action } = parsed;\n  assertScopePart(scope, scope);\n  if (action === \"read\") return scope;\n  // Looked up rather than hard-coded so an action can never be emitted\n  // without a prefix the parser accepts (and JS callers passing an unknown\n  // action fail closed instead of producing a read entry).\n  const prefix = Object.entries(OPERATION_BY_PREFIX).find(\n    ([, candidate]) => candidate === action,\n  )?.[0];\n  if (prefix === undefined) {\n    throw new InvalidScopeEntryError(\n      scope,\n      `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(\", \")})`,\n    );\n  }\n  return `${prefix}${OPERATION_SEPARATOR}${scope}`;\n}\n\nfunction compareScopes(a: string, b: string): number {\n  // Plain code-unit order: locale-independent, so the grouping is identical\n  // on every runtime.\n  if (a < b) return -1;\n  if (a > b) return 1;\n  return 0;\n}\n\nfunction sortActions(actions: Iterable<ScopeAction>): ScopeAction[] {\n  const present = new Set(actions);\n  return SCOPE_ACTIONS.filter((action) => present.has(action));\n}\n\n/**\n * Group a grant's scope entries into one `{ scope, actions }` row per scope\n * pattern - the view builders and consent UIs should render instead of the\n * raw strings.\n *\n * The result is canonical: rows are ordered by scope (code-unit order),\n * actions within a row follow {@link SCOPE_ACTIONS} order, and neither rows\n * nor actions repeat, whatever order or duplication the input had.\n *\n * Fails closed: if any entry does not fit the grammar this throws\n * {@link InvalidScopeEntryError} rather than silently dropping it, so a grant\n * carrying an operation this SDK does not know is never shown as narrower\n * than it is.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @returns The grouped, canonically ordered permissions.\n * @throws InvalidScopeEntryError when any entry does not fit the grammar.\n */\nexport function grantPermissions(scopes: readonly string[]): GrantPermission[] {\n  const byScope = new Map<string, Set<ScopeAction>>();\n  for (const entry of scopes) {\n    const { scope, action } = parseScopeEntry(entry);\n    let actions = byScope.get(scope);\n    if (actions === undefined) {\n      actions = new Set<ScopeAction>();\n      byScope.set(scope, actions);\n    }\n    actions.add(action);\n  }\n  return [...byScope.keys()].sort(compareScopes).map((scope) => ({\n    scope,\n    actions: sortActions(byScope.get(scope) ?? []),\n  }));\n}\n\n/**\n * Inverse of {@link grantPermissions}: flatten grouped permissions back into\n * the `string[]` form a grant is signed with.\n *\n * Output is canonical (scopes in code-unit order, read before write, no\n * duplicates), so `permissionsToScopes(grantPermissions(scopes))` is the\n * canonical form of `scopes`, and `grantPermissions(permissionsToScopes(p))`\n * is the canonical form of `p`. Rows with no actions contribute nothing; a\n * row with an action the grammar does not define throws rather than being\n * dropped.\n *\n * @param permissions - Grouped permissions, in any order, possibly repeating\n * a scope.\n * @returns The scope entries, one per (scope, action) pair.\n * @throws InvalidScopeEntryError when a scope or action does not fit the\n * grammar.\n */\nexport function permissionsToScopes(\n  permissions: readonly GrantPermission[],\n): string[] {\n  const byScope = new Map<string, Set<ScopeAction>>();\n  for (const { scope, actions } of permissions) {\n    let merged = byScope.get(scope);\n    if (merged === undefined) {\n      merged = new Set<ScopeAction>();\n      byScope.set(scope, merged);\n    }\n    for (const action of actions) {\n      if (!(SCOPE_ACTIONS as readonly string[]).includes(action)) {\n        throw new InvalidScopeEntryError(\n          scope,\n          `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(\", \")})`,\n        );\n      }\n      merged.add(action);\n    }\n  }\n  const entries: string[] = [];\n  for (const scope of [...byScope.keys()].sort(compareScopes)) {\n    for (const action of sortActions(byScope.get(scope) ?? [])) {\n      entries.push(formatScopeEntry({ scope, action }));\n    }\n  }\n  return entries;\n}\n\n/**\n * Does this grant authorize `action` over `scope`?\n *\n * The scope part is matched with the SDK's scope wildcard matcher\n * ({@link scopeMatchesPattern}: `*`, `{prefix}.*`, or exact), the action\n * exactly. Entries that do not fit the grammar are skipped - they authorize\n * nothing, which is exactly how the Personal Server treats them - so a grant\n * that carries an operation this SDK does not know still answers correctly\n * for the operations it does.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @param scope - The concrete scope being requested. Never prefixed: a value\n * containing `:` is not a scope id and yields `false`.\n * @param action - The operation being requested.\n * @returns `true` if some entry grants `action` over a pattern covering\n * `scope`.\n */\nexport function hasAction(\n  scopes: readonly string[],\n  scope: string,\n  action: ScopeAction,\n): boolean {\n  // A requested scope is a concrete scope id and never carries a prefix; the\n  // Personal Server rejects anything else with ScopeSchema before it ever\n  // reaches its matcher, so answer the same way here instead of letting\n  // `write:x` fall through to a `*` entry.\n  if (scope.includes(OPERATION_SEPARATOR)) return false;\n  for (const entry of scopes) {\n    let parsed: ParsedScopeEntry;\n    try {\n      parsed = parseScopeEntry(entry);\n    } catch (error) {\n      if (error instanceof InvalidScopeEntryError) continue;\n      throw error;\n    }\n    if (parsed.action === action && scopeMatchesPattern(scope, parsed.scope)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * {@link grantPermissions} for a grant record read back from the gateway:\n * returns `undefined` instead of throwing when the scope list carries an\n * entry this SDK version cannot interpret, so a grant with a newer operation\n * still loads (with `scopes` intact) rather than failing the whole read.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @returns The grouped permissions, or `undefined` if any entry is\n * uninterpretable.\n */\nexport function tryGrantPermissions(\n  scopes: readonly string[],\n): GrantPermission[] | undefined {\n  try {\n    return grantPermissions(scopes);\n  } catch (error) {\n    if (error instanceof InvalidScopeEntryError) return undefined;\n    throw error;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/scope-actions.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Grant scope-entry grammar.
+ *
+ * A signed grant carries `scopes: string[]`. Each entry is
+ * `[operation:]scope` - an optional lowercase ASCII operation prefix before
+ * the first `:`, then a scope pattern (`*`, `{prefix}.*`, or an exact scope).
+ * A missing prefix means read. `write:notes.entries` authorizes writing
+ * `notes.entries` and nothing else; `notes.entries` authorizes reading it.
+ *
+ * The string form is the wire and storage detail: it is what the grantor
+ * signs (EIP-712 `GrantRegistration.scopes`) and what the gateway stores
+ * verbatim. The Personal Server is the sole interpreter, and this module is
+ * the SDK-side mirror of that interpretation. Builders and consent UIs should
+ * work with the grouped `{ scope, actions }` view (see
+ * {@link grantPermissions}) and never construct or parse the strings by hand.
+ *
+ * Matching rules, pinned by the Personal Server policy
+ * (personal-server-ts `packages/core/src/policy/data-write.ts` and
+ * `data-read.ts`):
+ * - the operation is compared exactly, case-sensitively;
+ * - wildcards apply to the scope part only, via {@link scopeMatchesPattern};
+ * - an entry whose operation is not recognised never authorizes anything.
+ *   The parser fails closed on it (throws) rather than treating it as read;
+ *   the matcher ({@link hasAction}) skips it, which is how the Personal
+ *   Server treats an entry it does not understand.
+ */
+/** Operations the grammar defines today, in canonical (output) order. */
+export declare const SCOPE_ACTIONS: readonly ["read", "write"];
+/** An operation a grant entry can authorize over a scope. */
+export type ScopeAction = (typeof SCOPE_ACTIONS)[number];
+/** One grant entry, split into its operation and scope pattern. */
+export interface ParsedScopeEntry {
+    scope: string;
+    action: ScopeAction;
+}
+/**
+ * The grouped view of a grant's scope entries: one row per scope pattern
+ * with every operation the grant authorizes over it.
+ */
+export interface GrantPermission {
+    scope: string;
+    actions: ScopeAction[];
+}
+/**
+ * Thrown when a scope entry does not fit the grammar - an unknown or
+ * malformed operation prefix, or an empty scope part.
+ */
+export declare class InvalidScopeEntryError extends Error {
+    /** The offending entry, verbatim (unknown because it may not be a string). */
+    readonly entry: unknown;
+    constructor(entry: unknown, reason: string);
+}
+/**
+ * Split one grant scope entry into its operation and scope pattern.
+ *
+ * - `notes.entries` parses as `{ scope: "notes.entries", action: "read" }`
+ * - `write:notes.*` parses as `{ scope: "notes.*", action: "write" }`
+ *
+ * Fails closed: a non-string entry, or an entry whose operation prefix is
+ * not recognised (including
+ * `read:`, any uppercase or non-ASCII prefix, or a wildcard in the operation
+ * position) throws {@link InvalidScopeEntryError} and is never treated as a
+ * read entry. An empty scope part (`write:`) throws as well.
+ *
+ * @param entry - A single element of a grant's `scopes` array.
+ * @returns The operation and the scope pattern it applies to.
+ * @throws InvalidScopeEntryError when the entry does not fit the grammar.
+ */
+export declare function parseScopeEntry(entry: string): ParsedScopeEntry;
+/**
+ * Inverse of {@link parseScopeEntry}: render one operation over one scope
+ * pattern as a grant scope entry. Read has no prefix.
+ *
+ * @param parsed - The operation and scope pattern to encode.
+ * @returns The wire-form entry, e.g. `write:notes.entries` or `notes.entries`.
+ * @throws InvalidScopeEntryError when the action is unknown or the scope part
+ * is empty or contains `:`.
+ */
+export declare function formatScopeEntry(parsed: ParsedScopeEntry): string;
+/**
+ * Group a grant's scope entries into one `{ scope, actions }` row per scope
+ * pattern - the view builders and consent UIs should render instead of the
+ * raw strings.
+ *
+ * The result is canonical: rows are ordered by scope (code-unit order),
+ * actions within a row follow {@link SCOPE_ACTIONS} order, and neither rows
+ * nor actions repeat, whatever order or duplication the input had.
+ *
+ * Fails closed: if any entry does not fit the grammar this throws
+ * {@link InvalidScopeEntryError} rather than silently dropping it, so a grant
+ * carrying an operation this SDK does not know is never shown as narrower
+ * than it is.
+ *
+ * @param scopes - A grant's `scopes` array, verbatim.
+ * @returns The grouped, canonically ordered permissions.
+ * @throws InvalidScopeEntryError when any entry does not fit the grammar.
+ */
+export declare function grantPermissions(scopes: readonly string[]): GrantPermission[];
+/**
+ * Inverse of {@link grantPermissions}: flatten grouped permissions back into
+ * the `string[]` form a grant is signed with.
+ *
+ * Output is canonical (scopes in code-unit order, read before write, no
+ * duplicates), so `permissionsToScopes(grantPermissions(scopes))` is the
+ * canonical form of `scopes`, and `grantPermissions(permissionsToScopes(p))`
+ * is the canonical form of `p`. Rows with no actions contribute nothing; a
+ * row with an action the grammar does not define throws rather than being
+ * dropped.
+ *
+ * @param permissions - Grouped permissions, in any order, possibly repeating
+ * a scope.
+ * @returns The scope entries, one per (scope, action) pair.
+ * @throws InvalidScopeEntryError when a scope or action does not fit the
+ * grammar.
+ */
+export declare function permissionsToScopes(permissions: readonly GrantPermission[]): string[];
+/**
+ * Does this grant authorize `action` over `scope`?
+ *
+ * The scope part is matched with the SDK's scope wildcard matcher
+ * ({@link scopeMatchesPattern}: `*`, `{prefix}.*`, or exact), the action
+ * exactly. Entries that do not fit the grammar are skipped - they authorize
+ * nothing, which is exactly how the Personal Server treats them - so a grant
+ * that carries an operation this SDK does not know still answers correctly
+ * for the operations it does.
+ *
+ * @param scopes - A grant's `scopes` array, verbatim.
+ * @param scope - The concrete scope being requested. Never prefixed: a value
+ * containing `:` is not a scope id and yields `false`.
+ * @param action - The operation being requested.
+ * @returns `true` if some entry grants `action` over a pattern covering
+ * `scope`.
+ */
+export declare function hasAction(scopes: readonly string[], scope: string, action: ScopeAction): boolean;
+/**
+ * {@link grantPermissions} for a grant record read back from the gateway:
+ * returns `undefined` instead of throwing when the scope list carries an
+ * entry this SDK version cannot interpret, so a grant with a newer operation
+ * still loads (with `scopes` intact) rather than failing the whole read.
+ *
+ * @param scopes - A grant's `scopes` array, verbatim.
+ * @returns The grouped permissions, or `undefined` if any entry is
+ * uninterpretable.
+ */
+export declare function tryGrantPermissions(scopes: readonly string[]): GrantPermission[] | undefined;

package/dist/protocol/scope-actions.js

@@ -0,0 +1,154 @@
+import { scopeMatchesPattern } from "./scopes.js";
+const SCOPE_ACTIONS = ["read", "write"];
+class InvalidScopeEntryError extends Error {
+  /** The offending entry, verbatim (unknown because it may not be a string). */
+  entry;
+  constructor(entry, reason) {
+    super(`Invalid scope entry ${describeValue(entry)}: ${reason}`);
+    this.name = "InvalidScopeEntryError";
+    this.entry = entry;
+  }
+}
+const OPERATION_SEPARATOR = ":";
+function describeValue(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  return `[${typeof value}]`;
+}
+const OPERATION_BY_PREFIX = {
+  write: "write"
+};
+function assertScopePart(entry, scope) {
+  if (scope.length === 0) {
+    throw new InvalidScopeEntryError(entry, "scope part is empty");
+  }
+  if (scope.includes(OPERATION_SEPARATOR)) {
+    throw new InvalidScopeEntryError(
+      entry,
+      `scope part must not contain "${OPERATION_SEPARATOR}"`
+    );
+  }
+}
+function parseScopeEntry(entry) {
+  const raw = entry;
+  if (typeof raw !== "string") {
+    throw new InvalidScopeEntryError(raw, "entry must be a string");
+  }
+  const separatorIndex = entry.indexOf(OPERATION_SEPARATOR);
+  if (separatorIndex === -1) {
+    assertScopePart(entry, entry);
+    return { scope: entry, action: "read" };
+  }
+  const prefix = entry.slice(0, separatorIndex);
+  const scope = entry.slice(separatorIndex + 1);
+  const action = Object.hasOwn(OPERATION_BY_PREFIX, prefix) ? OPERATION_BY_PREFIX[prefix] : void 0;
+  if (action === void 0) {
+    throw new InvalidScopeEntryError(
+      entry,
+      `unknown operation "${prefix}" (known: ${Object.keys(OPERATION_BY_PREFIX).join(", ")}; read has no prefix)`
+    );
+  }
+  assertScopePart(entry, scope);
+  return { scope, action };
+}
+function formatScopeEntry(parsed) {
+  const { scope, action } = parsed;
+  assertScopePart(scope, scope);
+  if (action === "read") return scope;
+  const prefix = Object.entries(OPERATION_BY_PREFIX).find(
+    ([, candidate]) => candidate === action
+  )?.[0];
+  if (prefix === void 0) {
+    throw new InvalidScopeEntryError(
+      scope,
+      `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(", ")})`
+    );
+  }
+  return `${prefix}${OPERATION_SEPARATOR}${scope}`;
+}
+function compareScopes(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function sortActions(actions) {
+  const present = new Set(actions);
+  return SCOPE_ACTIONS.filter((action) => present.has(action));
+}
+function grantPermissions(scopes) {
+  const byScope = /* @__PURE__ */ new Map();
+  for (const entry of scopes) {
+    const { scope, action } = parseScopeEntry(entry);
+    let actions = byScope.get(scope);
+    if (actions === void 0) {
+      actions = /* @__PURE__ */ new Set();
+      byScope.set(scope, actions);
+    }
+    actions.add(action);
+  }
+  return [...byScope.keys()].sort(compareScopes).map((scope) => ({
+    scope,
+    actions: sortActions(byScope.get(scope) ?? [])
+  }));
+}
+function permissionsToScopes(permissions) {
+  const byScope = /* @__PURE__ */ new Map();
+  for (const { scope, actions } of permissions) {
+    let merged = byScope.get(scope);
+    if (merged === void 0) {
+      merged = /* @__PURE__ */ new Set();
+      byScope.set(scope, merged);
+    }
+    for (const action of actions) {
+      if (!SCOPE_ACTIONS.includes(action)) {
+        throw new InvalidScopeEntryError(
+          scope,
+          `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(", ")})`
+        );
+      }
+      merged.add(action);
+    }
+  }
+  const entries = [];
+  for (const scope of [...byScope.keys()].sort(compareScopes)) {
+    for (const action of sortActions(byScope.get(scope) ?? [])) {
+      entries.push(formatScopeEntry({ scope, action }));
+    }
+  }
+  return entries;
+}
+function hasAction(scopes, scope, action) {
+  if (scope.includes(OPERATION_SEPARATOR)) return false;
+  for (const entry of scopes) {
+    let parsed;
+    try {
+      parsed = parseScopeEntry(entry);
+    } catch (error) {
+      if (error instanceof InvalidScopeEntryError) continue;
+      throw error;
+    }
+    if (parsed.action === action && scopeMatchesPattern(scope, parsed.scope)) {
+      return true;
+    }
+  }
+  return false;
+}
+function tryGrantPermissions(scopes) {
+  try {
+    return grantPermissions(scopes);
+  } catch (error) {
+    if (error instanceof InvalidScopeEntryError) return void 0;
+    throw error;
+  }
+}
+export {
+  InvalidScopeEntryError,
+  SCOPE_ACTIONS,
+  formatScopeEntry,
+  grantPermissions,
+  hasAction,
+  parseScopeEntry,
+  permissionsToScopes,
+  tryGrantPermissions
+};
+//# sourceMappingURL=scope-actions.js.map

package/dist/protocol/scope-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/scope-actions.ts"],"sourcesContent":["import { scopeMatchesPattern } from \"./scopes\";\n\n/**\n * Grant scope-entry grammar.\n *\n * A signed grant carries `scopes: string[]`. Each entry is\n * `[operation:]scope` - an optional lowercase ASCII operation prefix before\n * the first `:`, then a scope pattern (`*`, `{prefix}.*`, or an exact scope).\n * A missing prefix means read. `write:notes.entries` authorizes writing\n * `notes.entries` and nothing else; `notes.entries` authorizes reading it.\n *\n * The string form is the wire and storage detail: it is what the grantor\n * signs (EIP-712 `GrantRegistration.scopes`) and what the gateway stores\n * verbatim. The Personal Server is the sole interpreter, and this module is\n * the SDK-side mirror of that interpretation. Builders and consent UIs should\n * work with the grouped `{ scope, actions }` view (see\n * {@link grantPermissions}) and never construct or parse the strings by hand.\n *\n * Matching rules, pinned by the Personal Server policy\n * (personal-server-ts `packages/core/src/policy/data-write.ts` and\n * `data-read.ts`):\n * - the operation is compared exactly, case-sensitively;\n * - wildcards apply to the scope part only, via {@link scopeMatchesPattern};\n * - an entry whose operation is not recognised never authorizes anything.\n *   The parser fails closed on it (throws) rather than treating it as read;\n *   the matcher ({@link hasAction}) skips it, which is how the Personal\n *   Server treats an entry it does not understand.\n */\n\n/** Operations the grammar defines today, in canonical (output) order. */\nexport const SCOPE_ACTIONS = [\"read\", \"write\"] as const;\n\n/** An operation a grant entry can authorize over a scope. */\nexport type ScopeAction = (typeof SCOPE_ACTIONS)[number];\n\n/** One grant entry, split into its operation and scope pattern. */\nexport interface ParsedScopeEntry {\n  scope: string;\n  action: ScopeAction;\n}\n\n/**\n * The grouped view of a grant's scope entries: one row per scope pattern\n * with every operation the grant authorizes over it.\n */\nexport interface GrantPermission {\n  scope: string;\n  actions: ScopeAction[];\n}\n\n/**\n * Thrown when a scope entry does not fit the grammar - an unknown or\n * malformed operation prefix, or an empty scope part.\n */\nexport class InvalidScopeEntryError extends Error {\n  /** The offending entry, verbatim (unknown because it may not be a string). */\n  readonly entry: unknown;\n\n  constructor(entry: unknown, reason: string) {\n    super(`Invalid scope entry ${describeValue(entry)}: ${reason}`);\n    this.name = \"InvalidScopeEntryError\";\n    this.entry = entry;\n  }\n}\n\nconst OPERATION_SEPARATOR = \":\";\n\n// Render an untrusted value for an error message without ever throwing:\n// String() and JSON.stringify() both defer to the value's own toString /\n// toJSON, which a hostile JSON body can make throw.\nfunction describeValue(value: unknown): string {\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (value === null) return \"null\";\n  return `[${typeof value}]`;\n}\n\n// The only operation that is ever written out. Read has no prefix, and\n// `read:` is NOT an alias for it: the Personal Server's read policy matches\n// entries verbatim, so a `read:x` entry would authorize nothing there, and\n// the parser must reject it for the same reason.\nconst OPERATION_BY_PREFIX: Readonly<Record<string, ScopeAction>> = {\n  write: \"write\",\n};\n\nfunction assertScopePart(entry: string, scope: string): void {\n  if (scope.length === 0) {\n    throw new InvalidScopeEntryError(entry, \"scope part is empty\");\n  }\n  if (scope.includes(OPERATION_SEPARATOR)) {\n    throw new InvalidScopeEntryError(\n      entry,\n      `scope part must not contain \"${OPERATION_SEPARATOR}\"`,\n    );\n  }\n}\n\n/**\n * Split one grant scope entry into its operation and scope pattern.\n *\n * - `notes.entries` parses as `{ scope: \"notes.entries\", action: \"read\" }`\n * - `write:notes.*` parses as `{ scope: \"notes.*\", action: \"write\" }`\n *\n * Fails closed: a non-string entry, or an entry whose operation prefix is\n * not recognised (including\n * `read:`, any uppercase or non-ASCII prefix, or a wildcard in the operation\n * position) throws {@link InvalidScopeEntryError} and is never treated as a\n * read entry. An empty scope part (`write:`) throws as well.\n *\n * @param entry - A single element of a grant's `scopes` array.\n * @returns The operation and the scope pattern it applies to.\n * @throws InvalidScopeEntryError when the entry does not fit the grammar.\n */\nexport function parseScopeEntry(entry: string): ParsedScopeEntry {\n  // Grant bodies arrive from the network; a non-string element is a grammar\n  // violation like any other, not a TypeError from indexOf.\n  const raw: unknown = entry;\n  if (typeof raw !== \"string\") {\n    throw new InvalidScopeEntryError(raw, \"entry must be a string\");\n  }\n  const separatorIndex = entry.indexOf(OPERATION_SEPARATOR);\n  if (separatorIndex === -1) {\n    assertScopePart(entry, entry);\n    return { scope: entry, action: \"read\" };\n  }\n\n  const prefix = entry.slice(0, separatorIndex);\n  const scope = entry.slice(separatorIndex + 1);\n  const action = Object.hasOwn(OPERATION_BY_PREFIX, prefix)\n    ? OPERATION_BY_PREFIX[prefix]\n    : undefined;\n  if (action === undefined) {\n    throw new InvalidScopeEntryError(\n      entry,\n      `unknown operation \"${prefix}\" (known: ${Object.keys(OPERATION_BY_PREFIX).join(\", \")}; read has no prefix)`,\n    );\n  }\n  assertScopePart(entry, scope);\n  return { scope, action };\n}\n\n/**\n * Inverse of {@link parseScopeEntry}: render one operation over one scope\n * pattern as a grant scope entry. Read has no prefix.\n *\n * @param parsed - The operation and scope pattern to encode.\n * @returns The wire-form entry, e.g. `write:notes.entries` or `notes.entries`.\n * @throws InvalidScopeEntryError when the action is unknown or the scope part\n * is empty or contains `:`.\n */\nexport function formatScopeEntry(parsed: ParsedScopeEntry): string {\n  const { scope, action } = parsed;\n  assertScopePart(scope, scope);\n  if (action === \"read\") return scope;\n  // Looked up rather than hard-coded so an action can never be emitted\n  // without a prefix the parser accepts (and JS callers passing an unknown\n  // action fail closed instead of producing a read entry).\n  const prefix = Object.entries(OPERATION_BY_PREFIX).find(\n    ([, candidate]) => candidate === action,\n  )?.[0];\n  if (prefix === undefined) {\n    throw new InvalidScopeEntryError(\n      scope,\n      `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(\", \")})`,\n    );\n  }\n  return `${prefix}${OPERATION_SEPARATOR}${scope}`;\n}\n\nfunction compareScopes(a: string, b: string): number {\n  // Plain code-unit order: locale-independent, so the grouping is identical\n  // on every runtime.\n  if (a < b) return -1;\n  if (a > b) return 1;\n  return 0;\n}\n\nfunction sortActions(actions: Iterable<ScopeAction>): ScopeAction[] {\n  const present = new Set(actions);\n  return SCOPE_ACTIONS.filter((action) => present.has(action));\n}\n\n/**\n * Group a grant's scope entries into one `{ scope, actions }` row per scope\n * pattern - the view builders and consent UIs should render instead of the\n * raw strings.\n *\n * The result is canonical: rows are ordered by scope (code-unit order),\n * actions within a row follow {@link SCOPE_ACTIONS} order, and neither rows\n * nor actions repeat, whatever order or duplication the input had.\n *\n * Fails closed: if any entry does not fit the grammar this throws\n * {@link InvalidScopeEntryError} rather than silently dropping it, so a grant\n * carrying an operation this SDK does not know is never shown as narrower\n * than it is.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @returns The grouped, canonically ordered permissions.\n * @throws InvalidScopeEntryError when any entry does not fit the grammar.\n */\nexport function grantPermissions(scopes: readonly string[]): GrantPermission[] {\n  const byScope = new Map<string, Set<ScopeAction>>();\n  for (const entry of scopes) {\n    const { scope, action } = parseScopeEntry(entry);\n    let actions = byScope.get(scope);\n    if (actions === undefined) {\n      actions = new Set<ScopeAction>();\n      byScope.set(scope, actions);\n    }\n    actions.add(action);\n  }\n  return [...byScope.keys()].sort(compareScopes).map((scope) => ({\n    scope,\n    actions: sortActions(byScope.get(scope) ?? []),\n  }));\n}\n\n/**\n * Inverse of {@link grantPermissions}: flatten grouped permissions back into\n * the `string[]` form a grant is signed with.\n *\n * Output is canonical (scopes in code-unit order, read before write, no\n * duplicates), so `permissionsToScopes(grantPermissions(scopes))` is the\n * canonical form of `scopes`, and `grantPermissions(permissionsToScopes(p))`\n * is the canonical form of `p`. Rows with no actions contribute nothing; a\n * row with an action the grammar does not define throws rather than being\n * dropped.\n *\n * @param permissions - Grouped permissions, in any order, possibly repeating\n * a scope.\n * @returns The scope entries, one per (scope, action) pair.\n * @throws InvalidScopeEntryError when a scope or action does not fit the\n * grammar.\n */\nexport function permissionsToScopes(\n  permissions: readonly GrantPermission[],\n): string[] {\n  const byScope = new Map<string, Set<ScopeAction>>();\n  for (const { scope, actions } of permissions) {\n    let merged = byScope.get(scope);\n    if (merged === undefined) {\n      merged = new Set<ScopeAction>();\n      byScope.set(scope, merged);\n    }\n    for (const action of actions) {\n      if (!(SCOPE_ACTIONS as readonly string[]).includes(action)) {\n        throw new InvalidScopeEntryError(\n          scope,\n          `unknown action ${describeValue(action)} (known: ${SCOPE_ACTIONS.join(\", \")})`,\n        );\n      }\n      merged.add(action);\n    }\n  }\n  const entries: string[] = [];\n  for (const scope of [...byScope.keys()].sort(compareScopes)) {\n    for (const action of sortActions(byScope.get(scope) ?? [])) {\n      entries.push(formatScopeEntry({ scope, action }));\n    }\n  }\n  return entries;\n}\n\n/**\n * Does this grant authorize `action` over `scope`?\n *\n * The scope part is matched with the SDK's scope wildcard matcher\n * ({@link scopeMatchesPattern}: `*`, `{prefix}.*`, or exact), the action\n * exactly. Entries that do not fit the grammar are skipped - they authorize\n * nothing, which is exactly how the Personal Server treats them - so a grant\n * that carries an operation this SDK does not know still answers correctly\n * for the operations it does.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @param scope - The concrete scope being requested. Never prefixed: a value\n * containing `:` is not a scope id and yields `false`.\n * @param action - The operation being requested.\n * @returns `true` if some entry grants `action` over a pattern covering\n * `scope`.\n */\nexport function hasAction(\n  scopes: readonly string[],\n  scope: string,\n  action: ScopeAction,\n): boolean {\n  // A requested scope is a concrete scope id and never carries a prefix; the\n  // Personal Server rejects anything else with ScopeSchema before it ever\n  // reaches its matcher, so answer the same way here instead of letting\n  // `write:x` fall through to a `*` entry.\n  if (scope.includes(OPERATION_SEPARATOR)) return false;\n  for (const entry of scopes) {\n    let parsed: ParsedScopeEntry;\n    try {\n      parsed = parseScopeEntry(entry);\n    } catch (error) {\n      if (error instanceof InvalidScopeEntryError) continue;\n      throw error;\n    }\n    if (parsed.action === action && scopeMatchesPattern(scope, parsed.scope)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * {@link grantPermissions} for a grant record read back from the gateway:\n * returns `undefined` instead of throwing when the scope list carries an\n * entry this SDK version cannot interpret, so a grant with a newer operation\n * still loads (with `scopes` intact) rather than failing the whole read.\n *\n * @param scopes - A grant's `scopes` array, verbatim.\n * @returns The grouped permissions, or `undefined` if any entry is\n * uninterpretable.\n */\nexport function tryGrantPermissions(\n  scopes: readonly string[],\n): GrantPermission[] | undefined {\n  try {\n    return grantPermissions(scopes);\n  } catch (error) {\n    if (error instanceof InvalidScopeEntryError) return undefined;\n    throw error;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/scope-actions.test.d.ts

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

package/dist/react.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.ts"],"sourcesContent":["/**\n * React entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link useDirectVanaConnect} (and the underlying framework-agnostic\n * connect-flow store) for browser apps. This entry point is browser-safe and\n * imports nothing Node-only. `react` is a peer dependency.\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useDirectVanaConnect } from \"@opendatalabs/vana-sdk/react\";\n *\n * export function ConnectNotesButton() {\n *   const connect = useDirectVanaConnect({\n *     createRequest: () => fetch(\"/api/vana/request\", { method: \"POST\" }).then((r) => r.json()),\n *     getStatus: (id) => fetch(`/api/vana/status?requestId=${id}`).then((r) => r.json()),\n *     readResult: (id) => fetch(`/api/vana/data?requestId=${id}`).then((r) => r.json()),\n *   });\n *   const { state, start } = connect;\n *   return (\n *     <div>\n *       <button disabled={state.type !== \"idle\"} onClick={start} type=\"button\">\n *         {state.type === \"idle\" ? \"Connect Apple Notes\" : \"Connecting...\"}\n *       </button>\n *       {state.type === \"awaiting_approval\" && (\n *         // Fallback link: if the browser blocked the approval popup, the user\n *         // can still open it manually instead of the flow silently hanging.\n *         <a href={state.request.approvalUrl} target=\"_blank\" rel=\"noreferrer\">\n *           {state.popupBlocked ? \"Popup blocked — open approval\" : \"Open approval\"}\n *         </a>\n *       )}\n *     </div>\n *   );\n * }\n * ```\n *\n * @category Direct\n * @module react\n */\n\nexport {\n  useDirectVanaConnect,\n  type UseDirectVanaConnectOptions,\n  type UseDirectVanaConnectResult,\n} from \"./direct/use-direct-vana-connect\";\n\n// Framework-agnostic store (usable without React).\nexport {\n  createDirectConnectFlow,\n  type ConnectWindow,\n  type DirectConnectFlow,\n  type DirectConnectState,\n  type DirectConnectOptions,\n  type DirectConnectTransports,\n} from \"./direct/connect-flow\";\n\n// Shared types useful when typing the transports.\nexport type {\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n} from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyCA,qCAIO;AAGP,0BAOO;","names":[]}
+{"version":3,"sources":["../src/react.ts"],"sourcesContent":["/**\n * React entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link useDirectVanaConnect} (and the underlying framework-agnostic\n * connect-flow store) for browser apps. This entry point is browser-safe and\n * imports nothing Node-only. `react` is a peer dependency.\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useDirectVanaConnect } from \"@opendatalabs/vana-sdk/react\";\n *\n * export function ConnectNotesButton() {\n *   const connect = useDirectVanaConnect({\n *     createRequest: () => fetch(\"/api/vana/request\", { method: \"POST\" }).then((r) => r.json()),\n *     getStatus: (id) => fetch(`/api/vana/status?requestId=${id}`).then((r) => r.json()),\n *     readResult: (id) => fetch(`/api/vana/data?requestId=${id}`).then((r) => r.json()),\n *   });\n *   const { state, start } = connect;\n *   return (\n *     <div>\n *       <button disabled={state.type !== \"idle\"} onClick={start} type=\"button\">\n *         {state.type === \"idle\" ? \"Connect Apple Notes\" : \"Connecting...\"}\n *       </button>\n *       {state.type === \"awaiting_approval\" && (\n *         // Fallback link: if the browser blocked the approval popup, the user\n *         // can still open it manually instead of the flow silently hanging.\n *         <a href={state.request.approvalUrl} target=\"_blank\" rel=\"noreferrer\">\n *           {state.popupBlocked ? \"Popup blocked — open approval\" : \"Open approval\"}\n *         </a>\n *       )}\n *       {state.type === \"ready_to_open\" && (\n *         // Mobile deep Direct: render the HTTPS continuation as a primary tap.\n *         // The SDK keeps polling in this tab; if the tab is lost, restart.\n *         <a href={state.mobileContinuationUrl} target=\"_blank\" rel=\"noreferrer\">\n *           Open Vana\n *         </a>\n *       )}\n *     </div>\n *   );\n * }\n * ```\n *\n * @category Direct\n * @module react\n */\n\nexport {\n  useDirectVanaConnect,\n  type UseDirectVanaConnectOptions,\n  type UseDirectVanaConnectResult,\n} from \"./direct/use-direct-vana-connect\";\n\n// Framework-agnostic store (usable without React).\nexport {\n  createDirectConnectFlow,\n  type ConnectWindow,\n  type DirectBrowserPlatform,\n  type DirectBrowserPlatformPolicy,\n  type DirectConnectFlow,\n  type DirectConnectState,\n  type DirectConnectOptions,\n  type DirectConnectTransports,\n} from \"./direct/connect-flow\";\n\n// Shared types useful when typing the transports.\nexport type {\n  ForegroundDelivery,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n} from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgDA,qCAIO;AAGP,0BASO;","names":[]}

package/dist/react.d.ts

@@ -30,6 +30,13 @@
  *           {state.popupBlocked ? "Popup blocked — open approval" : "Open approval"}
  *         </a>
  *       )}
+ *       {state.type === "ready_to_open" && (
+ *         // Mobile deep Direct: render the HTTPS continuation as a primary tap.
+ *         // The SDK keeps polling in this tab; if the tab is lost, restart.
+ *         <a href={state.mobileContinuationUrl} target="_blank" rel="noreferrer">
+ *           Open Vana
+ *         </a>
+ *       )}
  *     </div>
  *   );
  * }
@@ -39,5 +46,5 @@
  * @module react
  */
 export { useDirectVanaConnect, type UseDirectVanaConnectOptions, type UseDirectVanaConnectResult, } from "./direct/use-direct-vana-connect.js";
-export { createDirectConnectFlow, type ConnectWindow, type DirectConnectFlow, type DirectConnectState, type DirectConnectOptions, type DirectConnectTransports, } from "./direct/connect-flow.js";
-export type { AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, } from "./direct/types.js";
+export { createDirectConnectFlow, type ConnectWindow, type DirectBrowserPlatform, type DirectBrowserPlatformPolicy, type DirectConnectFlow, type DirectConnectState, type DirectConnectOptions, type DirectConnectTransports, } from "./direct/connect-flow.js";
+export type { ForegroundDelivery, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, } from "./direct/types.js";

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.ts"],"sourcesContent":["/**\n * React entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link useDirectVanaConnect} (and the underlying framework-agnostic\n * connect-flow store) for browser apps. This entry point is browser-safe and\n * imports nothing Node-only. `react` is a peer dependency.\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useDirectVanaConnect } from \"@opendatalabs/vana-sdk/react\";\n *\n * export function ConnectNotesButton() {\n *   const connect = useDirectVanaConnect({\n *     createRequest: () => fetch(\"/api/vana/request\", { method: \"POST\" }).then((r) => r.json()),\n *     getStatus: (id) => fetch(`/api/vana/status?requestId=${id}`).then((r) => r.json()),\n *     readResult: (id) => fetch(`/api/vana/data?requestId=${id}`).then((r) => r.json()),\n *   });\n *   const { state, start } = connect;\n *   return (\n *     <div>\n *       <button disabled={state.type !== \"idle\"} onClick={start} type=\"button\">\n *         {state.type === \"idle\" ? \"Connect Apple Notes\" : \"Connecting...\"}\n *       </button>\n *       {state.type === \"awaiting_approval\" && (\n *         // Fallback link: if the browser blocked the approval popup, the user\n *         // can still open it manually instead of the flow silently hanging.\n *         <a href={state.request.approvalUrl} target=\"_blank\" rel=\"noreferrer\">\n *           {state.popupBlocked ? \"Popup blocked — open approval\" : \"Open approval\"}\n *         </a>\n *       )}\n *     </div>\n *   );\n * }\n * ```\n *\n * @category Direct\n * @module react\n */\n\nexport {\n  useDirectVanaConnect,\n  type UseDirectVanaConnectOptions,\n  type UseDirectVanaConnectResult,\n} from \"./direct/use-direct-vana-connect\";\n\n// Framework-agnostic store (usable without React).\nexport {\n  createDirectConnectFlow,\n  type ConnectWindow,\n  type DirectConnectFlow,\n  type DirectConnectState,\n  type DirectConnectOptions,\n  type DirectConnectTransports,\n} from \"./direct/connect-flow\";\n\n// Shared types useful when typing the transports.\nexport type {\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n} from \"./direct/types\";\n"],"mappings":"AAyCA;AAAA,EACE;AAAA,OAGK;AAGP;AAAA,EACE;AAAA,OAMK;","names":[]}
+{"version":3,"sources":["../src/react.ts"],"sourcesContent":["/**\n * React entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link useDirectVanaConnect} (and the underlying framework-agnostic\n * connect-flow store) for browser apps. This entry point is browser-safe and\n * imports nothing Node-only. `react` is a peer dependency.\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useDirectVanaConnect } from \"@opendatalabs/vana-sdk/react\";\n *\n * export function ConnectNotesButton() {\n *   const connect = useDirectVanaConnect({\n *     createRequest: () => fetch(\"/api/vana/request\", { method: \"POST\" }).then((r) => r.json()),\n *     getStatus: (id) => fetch(`/api/vana/status?requestId=${id}`).then((r) => r.json()),\n *     readResult: (id) => fetch(`/api/vana/data?requestId=${id}`).then((r) => r.json()),\n *   });\n *   const { state, start } = connect;\n *   return (\n *     <div>\n *       <button disabled={state.type !== \"idle\"} onClick={start} type=\"button\">\n *         {state.type === \"idle\" ? \"Connect Apple Notes\" : \"Connecting...\"}\n *       </button>\n *       {state.type === \"awaiting_approval\" && (\n *         // Fallback link: if the browser blocked the approval popup, the user\n *         // can still open it manually instead of the flow silently hanging.\n *         <a href={state.request.approvalUrl} target=\"_blank\" rel=\"noreferrer\">\n *           {state.popupBlocked ? \"Popup blocked — open approval\" : \"Open approval\"}\n *         </a>\n *       )}\n *       {state.type === \"ready_to_open\" && (\n *         // Mobile deep Direct: render the HTTPS continuation as a primary tap.\n *         // The SDK keeps polling in this tab; if the tab is lost, restart.\n *         <a href={state.mobileContinuationUrl} target=\"_blank\" rel=\"noreferrer\">\n *           Open Vana\n *         </a>\n *       )}\n *     </div>\n *   );\n * }\n * ```\n *\n * @category Direct\n * @module react\n */\n\nexport {\n  useDirectVanaConnect,\n  type UseDirectVanaConnectOptions,\n  type UseDirectVanaConnectResult,\n} from \"./direct/use-direct-vana-connect\";\n\n// Framework-agnostic store (usable without React).\nexport {\n  createDirectConnectFlow,\n  type ConnectWindow,\n  type DirectBrowserPlatform,\n  type DirectBrowserPlatformPolicy,\n  type DirectConnectFlow,\n  type DirectConnectState,\n  type DirectConnectOptions,\n  type DirectConnectTransports,\n} from \"./direct/connect-flow\";\n\n// Shared types useful when typing the transports.\nexport type {\n  ForegroundDelivery,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n} from \"./direct/types\";\n"],"mappings":"AAgDA;AAAA,EACE;AAAA,OAGK;AAGP;AAAA,EACE;AAAA,OAQK;","names":[]}

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAKO;AACP,kCAUO;AAEP,4BAeO;AACP,uBAIO;AAGP,oBAMO;AA0BP,mBAA6B;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  ForegroundDelivery,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAKO;AACP,kCAUO;AAEP,4BAeO;AACP,uBAIO;AAGP,oBAMO;AA2BP,mBAA6B;","names":[]}

package/dist/server.d.ts

@@ -28,5 +28,5 @@ export { buildPersonalServerDataReadRequest, readPersonalServerData, parsePerson
 export { authorizeEscrowPayment, authorizeGrantPayment, buildEscrowPaymentHeader, buildGrantPaymentHeader, paymentResponseMetadataFromHeader, toDirectPaymentReceipt, toDirectFeeBreakdown, createDefaultNonceSource, DATA_ACCESS_OP_TYPE, GRANT_OP_TYPE, type EscrowPaymentConfig, type EscrowPaymentHeaderConfig, type SignTypedDataFn, type PaymentNonceSource, } from "./direct/escrow-payment.js";
 export { getDirectEndpoints, PRODUCTION_ENDPOINTS, DEV_ENDPOINTS, } from "./direct/endpoints.js";
 export { DirectConfigError, AccessNotApprovedError, ScopeNotApprovedError, PersonalServerReadError, PaymentRequiredError, } from "./direct/errors.js";
-export type { DirectEnv, DirectNetwork, DirectAppConfig, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, MultiScopeDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerDataAccessPaymentOperation, PersonalServerGrantPaymentOperation, PersonalServerPaymentOperation, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectPaymentResponseMetadata, DirectFeeBreakdown, } from "./direct/types.js";
+export type { DirectEnv, DirectNetwork, DirectAppConfig, ForegroundDelivery, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, MultiScopeDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerDataAccessPaymentOperation, PersonalServerGrantPaymentOperation, PersonalServerPaymentOperation, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectPaymentResponseMetadata, DirectFeeBreakdown, } from "./direct/types.js";
 export { DirectOpType } from "./direct/types.js";