@avasapp/agent-bridge 0.4.2 → 0.6.0

package/dist/adapters/redux.d.cts

@@ -0,0 +1,28 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+import { N as NamedRedact } from '../store-common-j0cHHvBr.cjs';
+
+/** Anything with a Redux store's shape, including Redux Toolkit's configureStore. */
+type ReduxStoreLike = {
+    getState: () => unknown;
+    dispatch(action: {
+        type: string;
+        payload?: unknown;
+    }): unknown;
+};
+
+type ReduxToolsOptions = {
+    /** By slice name, as `{ auth: ['token'] }` or `{ session: true }`, or a hook `(slice, path, value)`. */
+    redact?: NamedRedact;
+};
+/**
+ * Wrap the root reducer so the bridge can replace the state (redux.set and
+ * restore): `bridgeReducer(rootReducer)`. With redux-persist, wrap the reducer
+ * inside persistReducer: `persistReducer(config, bridgeReducer(rootReducer))`,
+ * so the saved copy follows. Release builds get the noop stub, which returns
+ * the reducer unchanged.
+ */
+declare function bridgeReducer<R extends (state: any, action: any) => any>(reducer: R): R;
+/** Read, set, dispatch to and restore a Redux store. */
+declare function reduxTools(store: ReduxStoreLike, options?: ReduxToolsOptions): Tools;
+
+export { NamedRedact as ReduxRedact, type ReduxStoreLike, type ReduxToolsOptions, bridgeReducer, reduxTools };

package/dist/adapters/secure-store.cjs

@@ -0,0 +1,169 @@
+"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);
+
+// src/adapters/secure-store.ts
+var secure_store_exports = {};
+__export(secure_store_exports, {
+  secureStoreTools: () => secureStoreTools
+});
+module.exports = __toCommonJS(secure_store_exports);
+
+// src/adapters/storage-undo.ts
+function toStored(tool, key, value) {
+  if (typeof key !== "string" || !key)
+    throw new Error(`${tool} needs the key name as a non-empty string`);
+  if (value === void 0 || value === null)
+    throw new Error(`${tool} needs a value; use the delete tool to remove "${key}"`);
+  const stored = typeof value === "string" ? value : JSON.stringify(value);
+  if (typeof stored !== "string")
+    throw new Error(`${tool} cannot store that value as JSON`);
+  return stored;
+}
+async function change(undo, id, io, value) {
+  let entry = undo.get(id);
+  if (!entry) {
+    const original = io.read();
+    entry = { io, original, last: null };
+    undo.set(id, entry);
+    try {
+      entry.last = await original;
+    } catch (error) {
+      if (undo.get(id) === entry) undo.delete(id);
+      throw error;
+    }
+  } else {
+    await entry.original;
+  }
+  if (value === null) await io.remove();
+  else await io.write(value);
+  entry.last = value;
+}
+async function restore(undo, label) {
+  let restored = 0;
+  const skipped = [];
+  const failed = [];
+  for (const [id, entry] of [...undo]) {
+    try {
+      let original;
+      try {
+        original = await entry.original;
+      } catch {
+        undo.delete(id);
+        continue;
+      }
+      if (await entry.io.read() !== entry.last) {
+        undo.delete(id);
+        skipped.push(label(id));
+        continue;
+      }
+      if (original === null) await entry.io.remove();
+      else await entry.io.write(original);
+      undo.delete(id);
+      restored += 1;
+    } catch {
+      failed.push(label(id));
+    }
+  }
+  return { restored, skipped, failed };
+}
+function describeRestore(r, what) {
+  if (r.failed.length)
+    throw new Error(
+      `Restored ${r.restored}, could not restore: ${r.failed.join(", ")}. ${what} stay pending; run it again.`
+    );
+  return r.skipped.length ? { restored: r.restored, skipped: r.skipped } : r.restored;
+}
+
+// src/adapters/secure-store.ts
+var originals = /* @__PURE__ */ new WeakMap();
+var hide = (value) => value === null ? null : `[redacted, ${value.length} chars]`;
+function secureStoreTools(store, keys = [], options) {
+  let undo = originals.get(store);
+  if (!undo) originals.set(store, undo = /* @__PURE__ */ new Map());
+  const pending = undo;
+  const optionsFor = (key) => typeof options === "function" ? options(key) : options;
+  const guarded = (key) => optionsFor(key)?.requireAuthentication === true;
+  const idOf = (key) => {
+    const o = optionsFor(key);
+    return JSON.stringify([o?.keychainService ?? "", o?.accessGroup ?? "", key]);
+  };
+  const apply = async (key, value) => {
+    const o = optionsFor(key);
+    const io = {
+      read: () => store.getItemAsync(key, o),
+      write: (v) => store.setItemAsync(key, v, o),
+      remove: () => store.deleteItemAsync(key, o)
+    };
+    try {
+      await change(pending, idOf(key), io, value);
+    } catch (error) {
+      if (guarded(key) && !pending.has(idOf(key)))
+        throw new Error(
+          `Could not read the protected key "${key}" to save its old value (${error instanceof Error ? error.message : String(error)}); nothing was changed.`
+        );
+      throw error;
+    }
+  };
+  return {
+    "secureStore.list": {
+      description: "The keys the app passed to secureStoreTools, each with whether it is set and its length. Keys the app protects with requireAuthentication are not read (they would prompt): they show {authRequired:true}. SecureStore cannot list keys itself: for any other key, call secureStore.get with its name. Values are not shown.",
+      run: async () => Object.fromEntries(
+        await Promise.all(
+          keys.map(async (k) => {
+            if (guarded(k)) return [k, { authRequired: true }];
+            const v = await store.getItemAsync(k, optionsFor(k));
+            return [k, v === null ? { set: false } : { set: true, length: v.length }];
+          })
+        )
+      )
+    },
+    "secureStore.get": {
+      description: "A key's value, redacted to its length unless {full:true}; null when missing. Pass the key name: SecureStore has no key listing.",
+      run: async (key, getOptions) => {
+        const value = await store.getItemAsync(key, optionsFor(key));
+        return getOptions?.full ? value : hide(value);
+      }
+    },
+    "secureStore.set": {
+      description: "Set a value (a string; other values are stored as JSON). The old value is kept in memory for secureStore.restore.",
+      run: async (key, value) => {
+        await apply(key, toStored("secureStore.set", key, value));
+        return true;
+      }
+    },
+    "secureStore.delete": {
+      description: "Delete a key.",
+      run: async (key) => {
+        if (typeof key !== "string" || !key)
+          throw new Error("secureStore.delete needs the key name as a non-empty string");
+        await apply(key, null);
+        return true;
+      }
+    },
+    "secureStore.restore": {
+      // Always a plain true: bridge.pending must not show key names or values.
+      pending: () => pending.size > 0,
+      description: "Undo the agent: put back keys changed with secureStore.set or secureStore.delete (with the same options), deleting ones that did not exist. Returns how many; a key the app has written since is left alone and returned in {skipped}. Lost when the JS reloads: restore before app.reload.",
+      run: async () => describeRestore(
+        await restore(pending, (id) => JSON.parse(id)[2]),
+        "Those keys"
+      )
+    }
+  };
+}

package/dist/adapters/secure-store.d.cts

@@ -0,0 +1,28 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+
+/** The options expo-secure-store takes on every call. */
+type SecureStoreOptions = {
+    keychainService?: string;
+    keychainAccessible?: number;
+    requireAuthentication?: boolean;
+    authenticationPrompt?: string;
+    accessGroup?: string;
+};
+/** The expo-secure-store surface this adapter uses (`import * as SecureStore`). */
+type SecureStoreLike = {
+    getItemAsync: (key: string, options?: SecureStoreOptions) => Promise<string | null>;
+    setItemAsync: (key: string, value: string, options?: SecureStoreOptions) => Promise<void>;
+    deleteItemAsync: (key: string, options?: SecureStoreOptions) => Promise<void>;
+};
+/** One options object for every key, or a function that picks them per key. */
+type SecureStoreOptionsFor = SecureStoreOptions | ((key: string) => SecureStoreOptions | undefined);
+/**
+ * Read and write expo-secure-store. Its values are secrets, so reads are
+ * redacted unless {full:true}. It cannot list keys: pass the ones the app
+ * knows as `keys` to let `secureStore.list` show them. `options` must match
+ * what the app passes (a `keychainService` picks a different item), as one
+ * object or a function of the key.
+ */
+declare function secureStoreTools(store: SecureStoreLike, keys?: readonly string[], options?: SecureStoreOptionsFor): Tools;
+
+export { type SecureStoreLike, type SecureStoreOptions, type SecureStoreOptionsFor, secureStoreTools };

package/dist/adapters/socket-io.cjs

@@ -72,6 +72,21 @@ function tapListeners(tap, target, options) {
     };
   }
 }
+function tapOutgoing(tap, target, options) {
+  const methods = target;
+  for (const name of list(options.methods)) {
+    const send = methods[name];
+    if (typeof send !== "function") continue;
+    methods[name] = function(...args) {
+      try {
+        const channel = options.skip?.(this) ? void 0 : options.channel(args);
+        if (channel !== void 0) tap.sent(channel, options.describe(args));
+      } catch {
+      }
+      return send.apply(this, args);
+    };
+  }
+}
 function fakeableConnection(target, options) {
   const methods = target;
   const events = methods?.[options.events];
@@ -116,6 +131,46 @@ function realtimeAdapter(install) {
   };
 }
 
+// src/network/headers.ts
+var SECRET = /auth|cookie|token|secret|session|password|passwd|signature|api-?key|credential|jwt/i;
+
+// src/realtime/snapshot.ts
+var MAX_STRING = 2e3;
+var MAX_ITEMS = 50;
+var MAX_DEPTH = 5;
+var isPlain = (v) => {
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+function snapshot(value, depth = 0) {
+  if (typeof value === "string")
+    return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}\u2026 (+${value.length - MAX_STRING} chars)` : value;
+  if (typeof value === "function") return "[function]";
+  if (!value || typeof value !== "object") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+    return `[${value.constructor.name} ${value.byteLength} bytes]`;
+  if (depth >= MAX_DEPTH) return "[\u2026]";
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ITEMS).map((v) => snapshot(v, depth + 1));
+    if (value.length > MAX_ITEMS) items.push(`\u2026 (+${value.length - MAX_ITEMS} items)`);
+    return items;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (!isPlain(value)) return `[${value.constructor?.name ?? "object"}]`;
+  const out = {};
+  for (const key of Object.keys(value).slice(0, MAX_ITEMS))
+    out[key] = snapshot(value[key], depth + 1);
+  return out;
+}
+function redact(value, depth = 0) {
+  if (!value || typeof value !== "object" || depth >= MAX_DEPTH + 1) return value;
+  if (Array.isArray(value)) return value.map((v) => redact(v, depth + 1));
+  const out = {};
+  for (const [key, v] of Object.entries(value))
+    out[key] = SECRET.test(key) ? "[redacted]" : redact(v, depth + 1);
+  return out;
+}
+
 // src/realtime/tap.ts
 var LOG_SIZE = 50;
 var ALL = "*";
@@ -159,6 +214,17 @@ function createRealtimeTap(options = {}) {
     }
     if (!dropped) entry.deliver(message, ...rest);
   }
+  const sent = (channel, summary) => {
+    log.push({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      channel,
+      ...summary,
+      ..."data" in summary && { data: snapshot(summary.data) },
+      injected: false,
+      sent: true
+    });
+    if (log.length > LOG_SIZE) log.splice(0, log.length - LOG_SIZE);
+  };
   const wrap = (channel, listener, wrapOptions = {}) => {
     const entry = {
       deliver: listener,
@@ -208,11 +274,11 @@ function createRealtimeTap(options = {}) {
       }))
     },
     [`${ns}.log`]: {
-      description: `Recent messages, real and injected, newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit? }; clear: true empties the log after reading.`,
+      description: `Recent messages, real, injected, and ones the app sent (sent: true) (socket.emit, Ably publish), newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit?, full? }; clear: true empties the log after reading. Sent messages are copied and cut, and keys like token, password or authorization show [redacted] unless full: true.`,
       run: (filter = {}) => {
         const entries = log.filter(
           (e) => (!filter.channel || e.channel === filter.channel) && (!filter.event || e.event === filter.event)
-        ).reverse().slice(0, filter.limit ?? 20);
+        ).reverse().slice(0, filter.limit ?? 20).map((e) => e.sent && !filter.full && "data" in e ? { ...e, data: redact(e.data) } : e);
         if (filter.clear) log.length = 0;
         return entries;
       }
@@ -273,7 +339,7 @@ function createRealtimeTap(options = {}) {
         return { state: faked ?? connection.state(), real: connection.state(), faked: faked !== null };
       }
     };
-  return { wrap, tools };
+  return { wrap, sent, tools };
 }
 
 // src/adapters/socket-io.ts
@@ -314,6 +380,14 @@ var socketIoTools = realtimeAdapter(
       channel: ([event]) => typeof event === "string" && !RESERVED.has(event) ? event : void 0,
       message: "args"
     });
+    tapOutgoing(tap, socket, {
+      methods: "emit",
+      channel: ([event]) => typeof event === "string" && !RESERVED.has(event) ? event : void 0,
+      // socket.io's retry queue calls emit again for the same message.
+      skip: (target) => Boolean(target.flags?.fromQueue),
+      // Always the argument list, so emit('x', [1, 2]) and emit('x', 1, 2) differ.
+      describe: ([, ...args]) => ({ data: args.filter((a) => typeof a !== "function") })
+    });
     return tap;
   }
 );

package/dist/adapters/socket-io.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-BmpykP1P.cjs';
+import { T as Tools } from '../types-qlwdcGjt.cjs';
 
 type Listener = (...args: any[]) => void;
 /** A socket.io client socket (`io(url)`), typed structurally. */
@@ -6,6 +6,7 @@ type SocketLike = {
     on(event: string, listener: Listener): unknown;
     off(event?: string, listener?: Listener): unknown;
     connected?: boolean;
+    emit?(event: string, ...args: never[]): unknown;
 };
 type SocketIoToolsOptions = {
     /** Tool name prefix. Defaults to "realtime". */

package/dist/adapters/tanstack-query.cjs

@@ -222,6 +222,9 @@ function atPath(value, path) {
   return current;
 }
 function queryTools(queryClient) {
+  return toolsFor(queryClient);
+}
+function toolsFor(queryClient) {
   const cache = queryClient.getQueryCache();
   const state = pinStateFor(queryClient);
   const { pins, seeded } = state;

package/dist/adapters/tanstack-query.d.cts

@@ -1,10 +1,19 @@
-import { QueryClient } from '@tanstack/query-core';
-import { T as Tools } from '../types-BmpykP1P.cjs';
+import { T as Tools } from '../types-qlwdcGjt.cjs';
 
+/** A TanStack Query `QueryClient`, e.g. from `useQueryClient()`. */
+type QueryClientLike = {
+    getQueryCache(): object;
+    getQueryData(queryKey: readonly unknown[]): unknown;
+    setQueryData(queryKey: readonly unknown[], updater: unknown): unknown;
+    invalidateQueries(filters?: object): Promise<void>;
+    refetchQueries(filters?: object): Promise<void>;
+    resetQueries(filters?: object): Promise<void>;
+    getDefaultOptions(): object;
+};
 /**
  * Read and seed the TanStack Query cache. `query.pin` keeps a seed in place:
  * when a refetch lands with real data, the seed is put back until unpinned.
  */
-declare function queryTools(queryClient: QueryClient): Tools;
+declare function queryTools(queryClient: QueryClientLike): Tools;
 
-export { queryTools };
+export { type QueryClientLike, queryTools };