@agentshouse/app-bridge 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -13,7 +13,14 @@ port's one listener. It carries four families:
   returns there when it completes. An App names an address House gave it in a
   reading and composes none.
 - **Status** - the App reference the Runtime port is attached under, sync
-  state, credential state, release availability and observed failure.
+  state, credential state, release availability and observed failure, `ga`:
+  whether the page measures and the visitor's stored analytics choice, and
+  `service_mode`: `open`, `write-halted` while House refuses writes, so the
+  App can stop retrying them, or `null` while the runtime holds no House
+  connection.
+  The App reports the visitor's choice with `gaConsent('accept')` or
+  `gaConsent('decline')`; the shell hands it to House's analytics loader, and
+  the choice never reaches House.
 - **Site image read** - given a Published Room and an original attachment
   reference, it answers the web copy's path and metadata, or `null` when no
   copy exists. The original bytes never cross this bridge at a Site.
@@ -71,4 +78,7 @@ slice below the App's path, admitting nothing, so it delivers `//notes` exactly
 as a browser at `/apps/<app>//notes` does. It records every push and replace
 and answers each with the address the shell would then show, records an
 admitted ceremony, refuses a push, replace or ceremony that is not a
-same-origin absolute path, publishes a status, and attaches a Runtime port.
+same-origin absolute path, publishes a status, its `service_mode` included,
+records in `consents` each
+`gaConsent` it takes while that status measures and publishes the status the
+choice leaves, and attaches a Runtime port.

package/client/src/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { HouseBridgePort, HouseMessagePort, HouseStatus } from './wire.js';
+import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseStatus } from './wire.js';
 export declare class HouseCeremonyRefused extends Error {
     readonly path: string | null;
     constructor(path: string | null);
@@ -23,5 +23,6 @@ export interface HouseBridge {
     readAttachment(room: string, attachment: string): Promise<HouseImageCopy | null>;
     status(): HouseStatus | null;
     onStatus(listener: (status: HouseStatus) => void): () => void;
+    gaConsent(choice: HouseGaChoice): void;
 }
 export declare function connectHouseBridge(source?: Promise<HouseBridgePort>): HouseBridge;

package/client/src/bridge.js

@@ -150,5 +150,8 @@ export function connectHouseBridge(source = heldBridge()) {
                 statusListeners.delete(listener);
             };
         },
+        gaConsent(choice) {
+            send({ house: 'ga/consent', choice });
+        },
     };
 }

package/client/src/index.d.ts

@@ -1,3 +1,3 @@
 export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, type HouseImageCopy, } from './bridge.js';
 export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
-export type { HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseMessagePort, HouseNavigationMode, HouseStatus, HouseSyncState, } from './wire.js';
+export type { HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseGa, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseStatus, HouseSyncState, } from './wire.js';

package/client/src/test-host.d.ts

@@ -1,5 +1,5 @@
 import type { HouseImageCopy } from './bridge.js';
-import type { HouseBridgePort, HouseMessagePort, HouseNavigationMode, HouseStatus } from './wire.js';
+import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseStatus } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
@@ -8,6 +8,7 @@ export interface HouseBridgeTestHost {
     readonly port: Promise<HouseBridgePort>;
     readonly navigations: readonly HouseBridgeNavigation[];
     readonly ceremonies: readonly string[];
+    readonly consents: readonly HouseGaChoice[];
     address(): string;
     open(address: string): void;
     publish(status: HouseStatus): void;

package/client/src/test-host.js

@@ -14,10 +14,12 @@ function sameOriginPath(value) {
 export function createHouseBridgeTestHost(options = {}) {
     const navigations = [];
     const ceremonies = [];
+    const consents = [];
     const listeners = new Set();
     const queued = [];
     let started = false;
     let address = appAddressOf('/', options.address ?? '/');
+    let status = options.status ?? null;
     function deliver(data, ports = []) {
         const event = { data, ports };
         if (!started) {
@@ -53,6 +55,18 @@ export function createHouseBridgeTestHost(options = {}) {
         }
         ceremonies.push(target);
     }
+    function publish(next) {
+        status = next;
+        deliver({ house: 'status', status });
+    }
+    function consent(choice) {
+        if (status === null || !status.ga.measures)
+            return;
+        if (choice !== 'accept' && choice !== 'decline')
+            return;
+        consents.push(choice);
+        publish({ ...status, ga: { measures: true, choice } });
+    }
     function receive(message) {
         const data = message;
         if (data === null || typeof data !== 'object')
@@ -63,6 +77,9 @@ export function createHouseBridgeTestHost(options = {}) {
         else if (data.house === 'ceremony') {
             ceremony(data.path);
         }
+        else if (data.house === 'ga/consent') {
+            consent(data.choice);
+        }
         else if (data.house === 'attachment-read') {
             const asked = data;
             const image = options.images?.find((entry) => entry.room === asked.room && entry.attachment === asked.attachment);
@@ -98,22 +115,21 @@ export function createHouseBridgeTestHost(options = {}) {
             });
         },
     };
-    if (options.status !== undefined)
-        deliver({ house: 'status', status: options.status });
+    if (status !== null)
+        deliver({ house: 'status', status });
     deliver({ house: 'address', address, navigated: false });
     return {
         port: Promise.resolve(port),
         navigations,
         ceremonies,
+        consents,
         address() {
             return address;
         },
         open(asked) {
             arrive(appAddressOf('/', asked), false);
         },
-        publish(status) {
-            deliver({ house: 'status', status });
-        },
+        publish,
         attachRuntime(runtime) {
             deliver({ house: 'runtime' }, [runtime]);
         },

package/client/src/wire.d.ts

@@ -16,6 +16,11 @@ export interface HouseCredentialState {
     readonly state: 'none' | 'held' | 'rejected';
     readonly expires_at: number | null;
 }
+export type HouseGaChoice = 'accept' | 'decline';
+export interface HouseGa {
+    readonly measures: boolean;
+    readonly choice: HouseGaChoice | null;
+}
 export interface HouseStatus {
     readonly app: string;
     readonly runtime: string;
@@ -26,6 +31,8 @@ export interface HouseStatus {
     } | null;
     readonly loss: string | null;
     readonly release: unknown;
+    readonly ga: HouseGa;
+    readonly service_mode: 'open' | 'write-halted' | null;
 }
 export type HouseNavigationMode = 'push' | 'replace';
 export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Renderer-side client of the agents.house App bridge: navigation, ceremonies, status and Site image reads, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",