@avasapp/agent-bridge 0.2.0 → 0.4.0

package/dist/client/index.d.ts

@@ -20,11 +20,64 @@ type DeviceInfo = {
     name: string;
     platform: string;
     protocol: number;
+    /** Same as ResultMessage.loadId. Absent from older runtimes. */
+    loadId?: string;
     tools: ToolInfo[];
 };
 
 type TransportName = 'expo' | 'cdp';
 
+/** A scenario a flow needs: a name, or a name with options. */
+type FlowScenario = string | {
+    name: string;
+    options?: unknown;
+};
+type FlowApi = {
+    bridge: AgentBridge;
+    call: AgentBridge['call'];
+    /**
+     * Times one call. Arguments are spread, `step('press', 'screen.press', 'Confirm')`.
+     * A single array is the whole argument list, as with `agent-bridge call`, so
+     * to pass one array as the only argument wrap it: `step('s', 'cart.setItems', [[a, b]])`.
+     * `call` does not do this: it passes its arguments as they are.
+     */
+    step: (label: string, tool: string, ...args: unknown[]) => Promise<unknown>;
+    /** What each declared scenario's apply returned, by name. */
+    scenarios: Record<string, unknown>;
+};
+/** A flow file: `export default async ({ step, call }) => {}`, plus what it needs. */
+type FlowModule = {
+    default: (api: FlowApi) => Promise<void>;
+    /** Applied before the flow and undone after it, even when it fails. */
+    scenario?: FlowScenario;
+    scenarios?: FlowScenario[];
+};
+type FlowResult = {
+    steps: number;
+    /** Errors the app logged during the flow. */
+    errors: number;
+    /** Restorers that failed in the closing bridge.restore, with why. */
+    restoreErrors: string[];
+    /** "app reloaded; N pending restores lost" warnings seen during the flow. */
+    notices: string[];
+};
+type RunFlowOptions = {
+    /** Where step lines go. Default: console.log. */
+    print?: (line: string) => void;
+    /** More scenarios to apply, e.g. from `--scenario`; one of the same name replaces the flow's. */
+    scenarios?: Array<{
+        name: string;
+        options?: unknown;
+    }>;
+};
+/**
+ * Runs a flow module you imported: applies its scenarios, runs it, and when
+ * there were any, undoes everything with bridge.restore afterwards, even
+ * when it fails. Throws what the flow threw; otherwise returns how it went.
+ * It runs only the code you hand it, in this process.
+ */
+declare function runFlow(bridge: AgentBridge, flow: FlowModule, options?: RunFlowOptions): Promise<FlowResult>;
+
 /** What a running session writes next to its socket. Readable only by the user. */
 type SessionState = {
     name: string;
@@ -36,6 +89,8 @@ type SessionState = {
         deviceId: string;
         platform: string;
     };
+    /** The project the session was started in (see `projectRoot`). */
+    project?: string;
     /** The --device filter the session was started with, reused to reconnect. */
     deviceFilter?: string;
     transport: TransportName;
@@ -48,7 +103,7 @@ type SessionState = {
 declare function listSessions(dir?: string): SessionState[];
 
 type SessionConnectOptions = {
-    /** Session name. Defaults to $AGENT_BRIDGE_SESSION, else the only session on this Metro. */
+    /** Session name. Defaults to $AGENT_BRIDGE_SESSION, else the only session (matching --metro/--device when given). */
     name?: string;
     metro?: string;
     device?: string;
@@ -78,9 +133,13 @@ declare class AgentBridgeCallError extends Error {
     readonly tool: string;
     /** Errors the app attached to the failed reply. */
     readonly logs: LogEntry[];
+    /** Through a session: the app reloaded, so its pending restores are lost. */
+    readonly notice?: string | undefined;
     constructor(tool: string, message: string, 
     /** Errors the app attached to the failed reply. */
-    logs?: LogEntry[]);
+    logs?: LogEntry[], 
+    /** Through a session: the app reloaded, so its pending restores are lost. */
+    notice?: string | undefined);
 }
 /** `logs`: errors the app recorded since its previous reply. */
 type Timed<T> = {
@@ -88,6 +147,8 @@ type Timed<T> = {
     ms: number;
     appMs: number;
     logs: LogEntry[];
+    /** Through a session: the app reloaded since the previous call, so its restores are lost. */
+    notice?: string;
 };
 type AgentBridge = {
     transport: TransportName;
@@ -109,4 +170,4 @@ type ListedDevice = {
 /** Apps with the bridge on Expo's socket, plus every React Native page Metro knows. */
 declare function listDevices(options?: Pick<ConnectOptions, 'metro'>): Promise<ListedDevice[]>;
 
-export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type ListedDevice, type LogEntry, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions };
+export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type FlowApi, type FlowModule, type FlowResult, type FlowScenario, type ListedDevice, type LogEntry, type RunFlowOptions, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions, runFlow };

package/dist/client/index.js

@@ -3,12 +3,14 @@ import {
   connect,
   connectSession,
   listDevices,
-  listSessions
-} from "../chunk-LBYZ5JHF.js";
+  listSessions,
+  runFlow
+} from "../chunk-AJD3XTNT.js";
 export {
   AgentBridgeCallError,
   connect,
   connectSession,
   listDevices,
-  listSessions
+  listSessions,
+  runFlow
 };

package/dist/expo/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Transport } from '../types-C6DUUHnB.cjs';
+import { a as Transport } from '../types-BmpykP1P.cjs';
 
 /**
  * Plain JSON over Expo's dev-tools plugin socket: no string evaluation, emoji