@avasapp/agent-bridge 0.1.0 → 0.3.0

package/dist/noop/realtime.cjs

@@ -0,0 +1,40 @@
+"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/noop/realtime.ts
+var realtime_exports = {};
+__export(realtime_exports, {
+  createRealtimeTap: () => createRealtimeTap,
+  fakeableConnection: () => fakeableConnection,
+  realtimeAdapter: () => realtimeAdapter,
+  tapListeners: () => tapListeners
+});
+module.exports = __toCommonJS(realtime_exports);
+var createRealtimeTap = () => ({
+  wrap: (_channel, listener) => ({
+    listener,
+    unsubscribe: () => {
+    }
+  }),
+  tools: {}
+});
+var tapListeners = () => {
+};
+var fakeableConnection = () => void 0;
+var realtimeAdapter = () => () => ({});

package/dist/noop/socket-io.cjs

@@ -0,0 +1,26 @@
+"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/noop/socket-io.ts
+var socket_io_exports = {};
+__export(socket_io_exports, {
+  socketIoTools: () => socketIoTools
+});
+module.exports = __toCommonJS(socket_io_exports);
+var socketIoTools = () => ({});

package/dist/realtime/index.cjs

@@ -0,0 +1,279 @@
+"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/realtime/index.ts
+var realtime_exports = {};
+__export(realtime_exports, {
+  createRealtimeTap: () => createRealtimeTap,
+  fakeableConnection: () => fakeableConnection,
+  realtimeAdapter: () => realtimeAdapter,
+  tapListeners: () => tapListeners
+});
+module.exports = __toCommonJS(realtime_exports);
+
+// src/realtime/patch.ts
+var list = (names) => Array.isArray(names) ? names : [names];
+var sameKey = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function split(args) {
+  const last = args[args.length - 1];
+  return typeof last === "function" ? { key: args.slice(0, -1), listener: last } : { key: args };
+}
+function tapListeners(tap, target, options) {
+  const methods = target;
+  const tracked = [];
+  const spread = options.message === "args";
+  for (const name of list(options.add)) {
+    const add = methods[name];
+    if (typeof add !== "function") continue;
+    methods[name] = function(...args) {
+      const { key, listener: original } = split(args);
+      const channel = original && options.channel(key);
+      if (!original || channel === void 0) return add.apply(this, args);
+      const accepts = options.accepts;
+      const { listener, unsubscribe } = tap.wrap(
+        channel,
+        (message, ...rest) => spread ? original.apply(target, message) : original.call(target, message, ...rest),
+        accepts ? { accepts: (m) => accepts(key, m) } : {}
+      );
+      const wrapped = spread ? (...received) => listener(received) : (message, ...rest) => listener(message, ...rest);
+      tracked.push({ key, original, wrapped, unsubscribe });
+      return add.apply(this, [...key, wrapped]);
+    };
+  }
+  for (const name of list(options.remove)) {
+    const remove = methods[name];
+    if (typeof remove !== "function") continue;
+    methods[name] = function(...args) {
+      const { key, listener } = split(args);
+      const hits = tracked.filter(
+        (t) => (!listener || t.original === listener || t.original.fn === listener) && (!key.length || sameKey(t.key, key))
+      );
+      for (const hit of hits) {
+        tracked.splice(tracked.indexOf(hit), 1);
+        hit.unsubscribe();
+      }
+      if (!listener || !hits.length) return remove.apply(this, args);
+      let result;
+      for (const hit of hits) result = remove.apply(this, [...hit.key, hit.wrapped]);
+      return result;
+    };
+  }
+}
+function fakeableConnection(target, options) {
+  const methods = target;
+  const events = methods?.[options.events];
+  if (!methods || typeof events !== "function") return void 0;
+  const read = options.read ?? String;
+  const write = options.write ?? ((state) => state);
+  const values = methods;
+  let fake = null;
+  let real = values[options.property];
+  const readReal = () => read(options.fakeProperty === false ? values[options.property] : real);
+  if (options.fakeProperty !== false)
+    Object.defineProperty(target, options.property, {
+      configurable: true,
+      enumerable: true,
+      get: () => fake === null ? real : write(fake),
+      set: (value) => {
+        real = value;
+      }
+    });
+  methods[options.events] = function(...args) {
+    return fake === null ? events.apply(this, args) : void 0;
+  };
+  const emit = (...args) => void events.apply(target, args);
+  return {
+    state: readReal,
+    states: options.states,
+    live: options.live,
+    fake: (state, previous) => {
+      fake = state;
+      const current = state ?? readReal();
+      if (current !== previous)
+        options.announce(emit, { current, previous, faked: state !== null });
+    }
+  };
+}
+function realtimeAdapter(install) {
+  const taps = /* @__PURE__ */ new WeakMap();
+  return (client, options = {}) => {
+    let tools = taps.get(client);
+    if (!tools) taps.set(client, tools = install(client, options).tools);
+    return tools;
+  };
+}
+
+// src/realtime/tap.ts
+var LOG_SIZE = 50;
+var ALL = "*";
+var defaultDescribe = (message) => {
+  const id = message?.id;
+  return typeof id === "string" ? { data: message, id } : { data: message };
+};
+var sameMessage = (a, b) => a === b || Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => v === b[i]);
+function createRealtimeTap(options = {}) {
+  const ns = options.namespace ?? "realtime";
+  const describe = options.describe ?? defaultDescribe;
+  const toMessage = options.toMessage ?? ((values) => values[0]);
+  const connection = options.connection;
+  const live = connection?.live ?? "connected";
+  const channels = /* @__PURE__ */ new Map();
+  const mutes = /* @__PURE__ */ new Map();
+  const log = [];
+  const last = /* @__PURE__ */ new Map();
+  let injectedCount = 0;
+  let faked = null;
+  const muteFor = (channel) => mutes.get(channel) ?? mutes.get(ALL);
+  const liveChannels = () => [...channels.keys()].join(", ") || "none";
+  function record(channel, message, injected, dropped) {
+    log.push({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      channel,
+      ...describe(message),
+      injected,
+      ...dropped && { dropped }
+    });
+    if (log.length > LOG_SIZE) log.splice(0, log.length - LOG_SIZE);
+  }
+  function receive(channel, entry, message, rest) {
+    const previous = last.get(channel);
+    const dropped = muteFor(channel) ? "muted" : faked !== null && faked !== live ? "connection" : void 0;
+    if (previous && !previous.seen.has(entry) && sameMessage(previous.message, message)) {
+      previous.seen.add(entry);
+    } else {
+      last.set(channel, { message, seen: /* @__PURE__ */ new Set([entry]) });
+      record(channel, message, false, dropped);
+    }
+    if (!dropped) entry.deliver(message, ...rest);
+  }
+  const wrap = (channel, listener, wrapOptions = {}) => {
+    const entry = {
+      deliver: listener,
+      accepts: wrapOptions.accepts
+    };
+    let entries = channels.get(channel);
+    if (!entries) channels.set(channel, entries = /* @__PURE__ */ new Set());
+    entries.add(entry);
+    return {
+      listener: (message, ...rest) => receive(channel, entry, message, rest),
+      unsubscribe: () => {
+        const current = channels.get(channel);
+        if (!current?.delete(entry) || current.size) return;
+        channels.delete(channel);
+        last.delete(channel);
+      }
+    };
+  };
+  function setMute(channel, mute) {
+    if (typeof channel !== "string" || !channel)
+      throw new Error(`Pass a channel name, or "${ALL}" for every channel`);
+    if (mute) mutes.set(channel, mute);
+    else if (channel === ALL) mutes.clear();
+    else mutes.delete(channel);
+    return { muted: [...mutes.keys()] };
+  }
+  function setConnection(conn, state) {
+    const shown = faked ?? conn.state();
+    if (state !== null && typeof state !== "string")
+      throw new Error('Pass a state such as "disconnected", or null for the real one');
+    if (state !== null && conn.states && !conn.states.includes(state))
+      throw new Error(
+        `Unknown state "${state}". Known: ${conn.states.join(", ")}`
+      );
+    if (state === faked) return;
+    faked = state;
+    conn.fake(state, shown);
+  }
+  const tools = {
+    [`${ns}.channels`]: {
+      description: "Channels the app listens on: listener count, muted, and what the library says about each.",
+      run: () => [...channels].map(([name, entries]) => ({
+        name,
+        listeners: entries.size,
+        muted: Boolean(muteFor(name)),
+        ...options.channelInfo?.(name)
+      }))
+    },
+    [`${ns}.log`]: {
+      description: `Recent messages, real and injected, newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit? }; clear: true empties the log after reading.`,
+      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);
+        if (filter.clear) log.length = 0;
+        return entries;
+      }
+    },
+    [`${ns}.emit`]: {
+      description: "Deliver a fake message to every listener on a channel: [channel, message]. Runs the app's own handlers. Returns { id, delivered }.",
+      run: (channel, ...values) => {
+        const entries = channels.get(channel);
+        if (!entries?.size)
+          throw new Error(
+            `Nothing listens on "${channel}". Live channels: ${liveChannels()}`
+          );
+        injectedCount += 1;
+        const message = toMessage(values, {
+          channel,
+          id: `agent-bridge-${injectedCount}`
+        });
+        const id = describe(message).id;
+        if (muteFor(channel)?.dropInjected) {
+          record(channel, message, true, "muted");
+          return { id, delivered: 0 };
+        }
+        record(channel, message, true);
+        let delivered = 0;
+        for (const entry of [...entries]) {
+          if (entry.accepts && !entry.accepts(message)) continue;
+          entry.deliver(message);
+          delivered += 1;
+        }
+        return { id, delivered };
+      }
+    },
+    [`${ns}.mute`]: {
+      description: `Drop real messages on a channel ("${ALL}" for all) until unmuted. Injected messages still get through unless { dropInjected: true }.`,
+      run: (channel, muteOptions = {}) => setMute(channel, { dropInjected: Boolean(muteOptions.dropInjected) })
+    },
+    [`${ns}.unmute`]: {
+      description: `Stop dropping messages on a channel ("${ALL}" for all).`,
+      run: (channel) => setMute(channel, null)
+    },
+    [`${ns}.restore`]: {
+      description: "Undo the agent: unmute every channel and go back to the real connection state.",
+      run: () => {
+        const unmuted = [...mutes.keys()];
+        mutes.clear();
+        const connectionFaked = faked !== null;
+        if (connection && connectionFaked) setConnection(connection, null);
+        return { unmuted, connectionFaked };
+      }
+    }
+  };
+  if (connection)
+    tools[`${ns}.connection`] = {
+      description: `The connection state, or fake one: [state] shows the app that state${connection.states ? ` (${connection.states.join(", ")})` : ""} and drops real messages unless it is "${live}"; [null] goes back to the real one.`,
+      run: (...args) => {
+        if (args.length) setConnection(connection, args[0] ?? null);
+        return { state: faked ?? connection.state(), real: connection.state(), faked: faked !== null };
+      }
+    };
+  return { wrap, tools };
+}

package/dist/realtime/index.d.cts

@@ -0,0 +1,138 @@
+import { T as Tools } from '../types-6kKQsLC1.cjs';
+
+/** How a message shows up in `realtime.log`. */
+type MessageSummary = {
+    /** The event or message name, when the library has one. */
+    event?: string;
+    data?: unknown;
+    id?: string;
+};
+/** Lets the agent fake the client's connection state. */
+type RealtimeConnection = {
+    /** The client's real state, e.g. "connected". */
+    state: () => string;
+    /**
+     * Show `state` to the app instead of the real one, as if the client had
+     * moved there from `previous`. `null` goes back to the real state.
+     */
+    fake: (state: string | null, previous: string) => void;
+    /** States the agent may pick, for error messages. */
+    states?: readonly string[];
+    /** The state in which real messages flow. Defaults to "connected". */
+    live?: string;
+};
+type RealtimeTapOptions<M> = {
+    /** Tool name prefix. Defaults to "realtime"; set it when an app has two taps. */
+    namespace?: string;
+    /** What to log for a message. Defaults to the message as `data`, with its `id` if it has one. */
+    describe?: (message: M) => MessageSummary;
+    /**
+     * Builds the message `realtime.emit` delivers, from the JSON values the
+     * agent passed after the channel. Defaults to the first value.
+     */
+    toMessage?: (values: unknown[], context: {
+        channel: string;
+        id: string;
+    }) => M;
+    /** Extra fields for `realtime.channels`, e.g. the library's channel state. */
+    channelInfo?: (channel: string) => Record<string, unknown>;
+    /** Adds `realtime.connection`, to fake connection states. */
+    connection?: RealtimeConnection;
+};
+type WrapOptions<M> = {
+    /**
+     * Whether this listener would get the message from the library, e.g. an
+     * event-name filter. Injected messages skip listeners that say no.
+     */
+    accepts?: (message: M) => boolean;
+};
+type RealtimeTap<M> = {
+    /**
+     * Wraps the app's listener for `channel`. Hand `listener` to the library
+     * instead of the original, and call `unsubscribe` when the app unsubscribes.
+     * Arguments after the message reach the app's listener untouched.
+     */
+    wrap: (channel: string, listener: (message: M, ...rest: never[]) => void, options?: WrapOptions<M>) => {
+        listener: (message: M, ...rest: unknown[]) => void;
+        unsubscribe: () => void;
+    };
+    /** `realtime.*`, or `<namespace>.*`. */
+    tools: Tools;
+};
+type RealtimeLogEntry = MessageSummary & {
+    at: string;
+    channel: string;
+    injected: boolean;
+    /** Why the app didn't get it. */
+    dropped?: 'muted' | 'connection';
+};
+/**
+ * Lets the agent see, fake and drop realtime messages, whatever library
+ * delivers them. Wrap each listener with `wrap`, and add `tools` to the bridge.
+ */
+declare function createRealtimeTap<M = unknown>(options?: RealtimeTapOptions<M>): RealtimeTap<M>;
+
+type TapListenersOptions<M> = {
+    /** Methods that add a listener, e.g. "on" or ["on", "addEventListener"]. */
+    add: string | string[];
+    /** Methods that remove one, e.g. "off". */
+    remove: string | string[];
+    /**
+     * The channel a call is for, from the arguments before the listener (its
+     * "key", e.g. the event name). Return undefined to leave the call alone.
+     */
+    channel: (key: unknown[]) => string | undefined;
+    /** Whether a listener added with `key` would get `message`, e.g. an event-name filter. */
+    accepts?: (key: unknown[], message: M) => boolean;
+    /**
+     * "first" (default): the message is the listener's first argument, and the
+     * rest reach the listener untouched. "args": every argument, as an array.
+     */
+    message?: 'first' | 'args';
+};
+/**
+ * Routes a client's add/remove-listener methods through `tap`, e.g.
+ * `socket.on` / `socket.off` or `channel.subscribe` / `channel.unsubscribe`.
+ * Removing works in every usual form: all, by key, by listener, or both.
+ */
+declare function tapListeners<M>(tap: RealtimeTap<M>, target: object, options: TapListenersOptions<M>): void;
+type FakeableConnectionOptions = {
+    /** The property holding the state, e.g. "state" or "connected". */
+    property: string;
+    /** The method the client tells listeners about changes with. Silent while a state is faked. */
+    events: string;
+    /** States the agent may pick. */
+    states: readonly string[];
+    /** The state in which real messages flow. Defaults to "connected". */
+    live?: string;
+    /** Property value to state name. Defaults to the value itself. */
+    read?: (value: unknown) => string;
+    /** State name to property value. Defaults to the name itself. */
+    write?: (state: string) => unknown;
+    /**
+     * false leaves the property showing the real state. Use it when the client
+     * reads the property itself to decide whether to deliver or send (socket.io
+     * does), or faking it would hold real traffic back. Defaults to true.
+     */
+    fakeProperty?: boolean;
+    /** Tells the app about a change, through the client's own (unsilenced) events method. */
+    announce: (emit: (...args: unknown[]) => void, change: {
+        current: string;
+        previous: string;
+        faked: boolean;
+    }) => void;
+};
+/**
+ * Lets `realtime.connection` fake a client's connection state: the property
+ * reads the fake (unless `fakeProperty: false`), real changes still land
+ * underneath but aren't announced, and going back announces the real state. Undefined when `target` lacks
+ * the events method, so the tool is left out rather than broken.
+ */
+declare function fakeableConnection(target: object | undefined, options: FakeableConnectionOptions): RealtimeConnection | undefined;
+/**
+ * Turns an install function into an adapter's `xxxTools(client, options)`.
+ * The client is patched on the first call; later calls return the same tools.
+ */
+declare function realtimeAdapter<C extends object, O extends object>(install: (client: C, options: O) => Pick<RealtimeTap<unknown>, 'tools'>): (client: C, options?: O) => Tools;
+
+export { type FakeableConnectionOptions, type MessageSummary, type RealtimeConnection, type RealtimeLogEntry, type RealtimeTap, type RealtimeTapOptions, type TapListenersOptions, type WrapOptions, createRealtimeTap, fakeableConnection, realtimeAdapter, tapListeners };