@palgroup/simstream 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -41,10 +41,24 @@ export interface DeviceKind {
     count: number;
     free: number;
 }
+/**
+ * Which of a simulator's two apps something is.
+ *
+ * ‼️ A PREVIEW HOST IS NOT THE APP. `preview` is a build whose @main is generated: it carries every
+ * screen the project was written with and swaps between them live, which is what to look at while a
+ * screen is being built. `app` is the person's own binary, launched from their own @main — the only
+ * one that runs their launch sequence, their delegate, their deep links and their navigation, and so
+ * the only one that is the app rather than a picture of it.
+ *
+ * Nothing in a .app says which it is, so whoever built it says so when they push it.
+ */
+export type SimMode = 'app' | 'preview';
 export interface AppStatus {
     /** Empty when nothing has been pushed to this simulator yet. */
     phase?: 'downloading' | 'installing' | 'launching' | 'ready' | 'failed';
     bundle?: string;
+    /** Which of the two this install is, when the push said so. */
+    mode?: SimMode;
     /** Present only with phase 'failed', and it says what went wrong rather than that it did. */
     error?: string;
     elapsed?: string;
@@ -61,6 +75,11 @@ export interface StartOptions {
     device?: string;
     /** Launch it once installed. Default true. */
     launch?: boolean;
+    /**
+     * Which of the simulator's two apps `app` is. Say so whenever you intend to push the other one
+     * too: an unlabelled build runs perfectly well and simply cannot be switched away from.
+     */
+    mode?: SimMode;
     /**
      * Wait for a device when the fleet is full or this customer is at its limit, instead of
      * failing. The wait is usually seconds — a session ends every time somebody closes a tab.
@@ -93,6 +112,20 @@ export interface CustomerUsage {
     live: number;
     cost: number;
 }
+/** What a simulator says about its own two apps. */
+export interface SessionMode {
+    /** What is on screen. Absent on a simulator holding one unlabelled build. */
+    running?: SimMode;
+    /** What it can be switched to, right now. */
+    holds: SimMode[];
+    /** The bundle id on screen, so two launches of the same mode are tellable apart. */
+    bundle?: string;
+    /**
+     * Whether what is on screen takes live screen selection. False in `app` mode, and that is not a
+     * fault: the person's own binary carries no listener of ours.
+     */
+    live: boolean;
+}
 export type SimStreamErrorCode = 'unauthorized' | 'quota' | 'capacity' | 'timeout' | 'gone' | 'http';
 export declare class SimStreamError extends Error {
     readonly code: SimStreamErrorCode;
@@ -128,6 +161,7 @@ export declare class SimStream {
     pushBuild(app: string, opts?: {
         version?: string;
         launch?: boolean;
+        mode?: SimMode;
     }): Promise<{
         hosts: number;
         version?: string;
@@ -183,6 +217,35 @@ export declare class SimStream {
         screen?: string;
         variant?: string;
     }): Promise<void>;
+    /**
+     * Which of the simulator's two apps is on screen, and what it can be switched to.
+     *
+     * ‼️ THIS IS A LAUNCH, AND showPreview IS A MESSAGE. Picking a screen lands inside the process
+     * that is already running and arrives in a frame. Switching mode is a different bundle with a
+     * different bundle id, so it costs a terminate and a start — a second or two, because both builds
+     * are already on the device, rather than the build it would otherwise mean.
+     *
+     * `setMode` is rejected when that simulator was never given the build being asked for, and the
+     * message says which of the two it IS holding — "no app build" and "no build at all" send you to
+     * different places. Push both, labelled, and the switch is always available.
+     */
+    mode(session: string): Promise<SessionMode>;
+    /**
+     * Run the person's own app, or go back to the preview host.
+     *
+     * See `mode()` for reading where a session stands without moving it — which is what a panel
+     * drawing the toggle needs on load, because POSTing the mode it GUESSES is current is a relaunch
+     * every time the guess is wrong.
+     */
+    setMode(session: string, mode: SimMode): Promise<SessionMode>;
+    /**
+     * Press one of the simulator's hardware buttons.
+     *
+     * ‼️ A VIEWER EMBEDDED IN A PANEL CANNOT REACH THESE. The viewer page carries touch and keyboard,
+     * but home, lock and siri are the device's own buttons and live outside the screen it draws — so a
+     * customer showing the simulator inside their own product has no way to send them without this.
+     */
+    pressButton(session: string, button: 'home' | 'lock' | 'siri'): Promise<void>;
     /**
      * The language and theme the app renders in, changed live.
      *

package/dist/index.js

@@ -56,6 +56,7 @@ class SimStream {
         const body = {
             app: opts.app,
             launch: opts.launch,
+            mode: opts.mode,
             queue: opts.wait === true,
             device: opts.device,
         };
@@ -95,6 +96,7 @@ class SimStream {
             app,
             version: opts.version,
             launch: opts.launch,
+            mode: opts.mode,
         });
         if (res.status !== 200)
             throw await this.errorFor(res);
@@ -163,6 +165,49 @@ class SimStream {
         if (res.status !== 200)
             throw await this.errorFor(res);
     }
+    /**
+     * Which of the simulator's two apps is on screen, and what it can be switched to.
+     *
+     * ‼️ THIS IS A LAUNCH, AND showPreview IS A MESSAGE. Picking a screen lands inside the process
+     * that is already running and arrives in a frame. Switching mode is a different bundle with a
+     * different bundle id, so it costs a terminate and a start — a second or two, because both builds
+     * are already on the device, rather than the build it would otherwise mean.
+     *
+     * `setMode` is rejected when that simulator was never given the build being asked for, and the
+     * message says which of the two it IS holding — "no app build" and "no build at all" send you to
+     * different places. Push both, labelled, and the switch is always available.
+     */
+    async mode(session) {
+        const res = await this.request('GET', `/api/session/mode?session=${encodeURIComponent(session)}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * Run the person's own app, or go back to the preview host.
+     *
+     * See `mode()` for reading where a session stands without moving it — which is what a panel
+     * drawing the toggle needs on load, because POSTing the mode it GUESSES is current is a relaunch
+     * every time the guess is wrong.
+     */
+    async setMode(session, mode) {
+        const res = await this.request('POST', '/api/session/mode', { session, mode });
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * Press one of the simulator's hardware buttons.
+     *
+     * ‼️ A VIEWER EMBEDDED IN A PANEL CANNOT REACH THESE. The viewer page carries touch and keyboard,
+     * but home, lock and siri are the device's own buttons and live outside the screen it draws — so a
+     * customer showing the simulator inside their own product has no way to send them without this.
+     */
+    async pressButton(session, button) {
+        const res = await this.request('POST', '/api/session/button', { session, button });
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+    }
     /**
      * The language and theme the app renders in, changed live.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palgroup/simstream",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Start and drive remote iOS simulator sessions.",
   "license": "Apache-2.0",
   "main": "dist/index.js",