@condorinst/mobile-bridge 0.15.2 → 0.17.0

package/dist/index.d.cts

@@ -197,16 +197,121 @@ interface UserDevicePayload {
     devicesTelemetry: Array<Record<string, unknown>>;
     devicesUserConfig: Array<Record<string, unknown>>;
 }
+/**
+ * Canais crus do sensor de luz, com os nomes que o backend usa no
+ * `user_cmd=log` — mesmo vocabulário para histórico e tempo real.
+ *
+ * Presentes a partir da **nativeVersion 0.16.0**. Um bundle compilado contra
+ * este SDK pode rodar num app nativo mais velho, que não os emite: cheque o
+ * `nativeVersion` do `handshake-ack` antes de depender deles, ou leia
+ * defensivamente. Não são opcionais no tipo de propósito — opcional
+ * esconderia o skew de versão em vez de deixá-lo explícito.
+ *
+ * ⚠️ O `nativeVersion` só chega ao cliente a partir do **SDK 0.17.0**: até a
+ * `0.16.x` o shell respondia o handshake do cliente apenas com o
+ * `shellVersion`, então essa checagem era impossível de cumprir de dentro do
+ * iframe.
+ *
+ * `null` significa **canal ausente nesta geração de hardware**, nunca "leitura
+ * zero": `0.0` é leitura válida. Mesma distinção que o backend faz com
+ * `float | null`.
+ */
+type LightSensorsRawChannels = {
+    light_sensor_f1: number;
+    light_sensor_f2: number;
+    light_sensor_f3: number;
+    light_sensor_f4: number;
+    light_sensor_f5: number;
+    light_sensor_f6: number;
+    light_sensor_f7: number;
+    light_sensor_f8: number;
+    /** Luz total (`visible` no wire do device). */
+    light_sensor_clear: number;
+    /** Infravermelho próximo. */
+    light_sensor_nir: number;
+};
+/**
+ * Leitura de tempo real de um ActLumus gen1 (`type: 'actlumus'`).
+ *
+ * Espelha `LightSensorsActlumus1GraphicData.toMap()`
+ * (`packages/condor_interactors/lib/src/domain/entities/actlumus/1/light_sensors1_graphic_data_entity.dart`).
+ * O gen1 não tem as tristimulus nem o flicker detect — as quatro chaves vêm
+ * como `null`, presentes no schema para que ele não mude entre gerações.
+ */
+type LightSensorsActlumus1Data = LightSensorsRawChannels & {
+    time: number;
+    wavelength390: number;
+    wavelength415: number;
+    wavelength445: number;
+    wavelength480: number;
+    wavelength515: number;
+    wavelength555: number;
+    wavelength590: number;
+    wavelength630: number;
+    wavelength680: number;
+    wavelength750: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: null;
+    light_sensor_y: null;
+    light_sensor_x: null;
+    light_sensor_fd: null;
+};
+/**
+ * Leitura de tempo real de um ActLumus Plus / gen2 (`type: 'actlumus2'`).
+ *
+ * Espelha `LightSensorsActlumus2GraphicData.toMap()`
+ * (`packages/condor_interactors/lib/src/domain/entities/actlumus/2/light_sensors2_graphic_data_entity.dart`).
+ * ⚠️ Os comprimentos de onda **não** são os mesmos do gen1 — são 14 (395…800)
+ * contra 10 (390…750), sem nenhum valor em comum. Um gráfico que leia a lista
+ * do gen1 num device gen2 encontra `undefined` em todas as séries e renderiza
+ * vazio; discrimine sempre pelo `type`.
+ *
+ * `light_sensor_z/_y/_x` são as tristimulus CIE 1931 — Z no azul, Y no verde,
+ * X no vermelho.
+ */
+type LightSensorsActlumus2Data = LightSensorsRawChannels & {
+    time: number;
+    wavelength395: number;
+    wavelength426: number;
+    wavelength457: number;
+    wavelength488: number;
+    wavelength520: number;
+    wavelength551: number;
+    wavelength582: number;
+    wavelength613: number;
+    wavelength644: number;
+    wavelength675: number;
+    wavelength707: number;
+    wavelength738: number;
+    wavelength769: number;
+    wavelength800: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: number;
+    light_sensor_y: number;
+    light_sensor_x: number;
+    /** Flicker detect. Não entra na matriz do espectro. */
+    light_sensor_fd: number;
+};
 /**
  * Stream real-time de sensores de luz (FEST). Shape:
- * `{serialNo, type, data: <lightSensors.toMap()>}`. O subobjeto `data`
- * varia por device type — permissivo no MVP.
+ * `{serialNo, type, data: <lightSensors.toMap()>}`.
+ *
+ * União discriminada pelo `type`, que é o `DeviceType.name` do lado Dart. O
+ * `data` carrega **o espectro derivado e os canais crus que o originaram** —
+ * até a `0.16.0` só o espectro atravessava, e uma sonda que procurasse um canal
+ * cru pelo nome lia `undefined`.
  */
-interface DeviceLightSensorsPayload {
+type DeviceLightSensorsPayload = {
     serialNo: number;
-    type: string;
-    data: Record<string, unknown>;
-}
+    type: 'actlumus';
+    data: LightSensorsActlumus1Data;
+} | {
+    serialNo: number;
+    type: 'actlumus2';
+    data: LightSensorsActlumus2Data;
+};
 /** Ack de comando `syncTime`. */
 interface SyncTimeAckPayload {
     serialNo: number;
@@ -539,6 +644,16 @@ declare const Bridge: CondorBridge;
 
 interface BridgeClientHandshakeAck {
     shellVersion: string;
+    /**
+     * Versão do schema do **nativo**, repassada pelo shell — `null` se o nativo
+     * ainda não respondeu ou não existe (mock de browser).
+     *
+     * É por este número que um cliente decide se pode depender de capacidade
+     * nova: não há negociação de versão, e o cliente sandboxed não alcança o
+     * nativo por nenhum outro caminho. Ex.: canais crus de luz
+     * (`light_sensor_*` em `deviceLightSensors`) existem a partir da `0.16.0`.
+     */
+    nativeVersion: string | null;
     accepted: boolean;
 }
 interface CondorBridgeClient {
@@ -665,6 +780,15 @@ declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"handshake-ack", undefined>;
     readonly ack: v.ObjectSchema<{
         readonly shellVersion: v.StringSchema<undefined>;
+        /**
+         * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+         *
+         * `null` quando o nativo ainda não respondeu (ou não existe, como no
+         * mock de browser). O cliente roda dentro de um iframe sandboxed e não
+         * fala com o nativo diretamente, então este é o **único** caminho pelo
+         * qual ele descobre de qual versão são as capacidades disponíveis.
+         */
+        readonly nativeVersion: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly accepted: v.BooleanSchema<undefined>;
     }, undefined>;
 }, undefined>, v.ObjectSchema<{
@@ -768,6 +892,13 @@ declare class BridgeShell {
     private readonly onConfirm?;
     private readonly subscriptions;
     private detached;
+    /**
+     * Versão do nativo, obtida uma vez e cacheada. `null` até o nativo
+     * responder — e permanentemente `null` num browser sem nativo.
+     */
+    private nativeVersion;
+    /** Handshake com o nativo em voo; garante uma única chamada. */
+    private nativeHandshake;
     private pendingVerifies;
     constructor(opts: BridgeShellOptions);
     /**
@@ -823,7 +954,17 @@ declare class BridgeShell {
     private handleSubscribe;
     private handleUnsubscribe;
     private handleSend;
+    /**
+     * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
+     * vez e cacheando o resultado.
+     *
+     * ⚠️ `Bridge.handshake` **não tem timeout**: a Promise só resolve quando o
+     * nativo emite `handshake-ack`. Num browser sem nativo ela nunca resolve,
+     * então o `race` abaixo é o que garante que o cliente sempre receba
+     * resposta — com `null` — em vez de ficar pendurado.
+     */
+    private resolveNativeVersion;
     private postToClient;
 }
 
-export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type MockMessage, type MockState, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };
+export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };

package/dist/index.d.ts

@@ -197,16 +197,121 @@ interface UserDevicePayload {
     devicesTelemetry: Array<Record<string, unknown>>;
     devicesUserConfig: Array<Record<string, unknown>>;
 }
+/**
+ * Canais crus do sensor de luz, com os nomes que o backend usa no
+ * `user_cmd=log` — mesmo vocabulário para histórico e tempo real.
+ *
+ * Presentes a partir da **nativeVersion 0.16.0**. Um bundle compilado contra
+ * este SDK pode rodar num app nativo mais velho, que não os emite: cheque o
+ * `nativeVersion` do `handshake-ack` antes de depender deles, ou leia
+ * defensivamente. Não são opcionais no tipo de propósito — opcional
+ * esconderia o skew de versão em vez de deixá-lo explícito.
+ *
+ * ⚠️ O `nativeVersion` só chega ao cliente a partir do **SDK 0.17.0**: até a
+ * `0.16.x` o shell respondia o handshake do cliente apenas com o
+ * `shellVersion`, então essa checagem era impossível de cumprir de dentro do
+ * iframe.
+ *
+ * `null` significa **canal ausente nesta geração de hardware**, nunca "leitura
+ * zero": `0.0` é leitura válida. Mesma distinção que o backend faz com
+ * `float | null`.
+ */
+type LightSensorsRawChannels = {
+    light_sensor_f1: number;
+    light_sensor_f2: number;
+    light_sensor_f3: number;
+    light_sensor_f4: number;
+    light_sensor_f5: number;
+    light_sensor_f6: number;
+    light_sensor_f7: number;
+    light_sensor_f8: number;
+    /** Luz total (`visible` no wire do device). */
+    light_sensor_clear: number;
+    /** Infravermelho próximo. */
+    light_sensor_nir: number;
+};
+/**
+ * Leitura de tempo real de um ActLumus gen1 (`type: 'actlumus'`).
+ *
+ * Espelha `LightSensorsActlumus1GraphicData.toMap()`
+ * (`packages/condor_interactors/lib/src/domain/entities/actlumus/1/light_sensors1_graphic_data_entity.dart`).
+ * O gen1 não tem as tristimulus nem o flicker detect — as quatro chaves vêm
+ * como `null`, presentes no schema para que ele não mude entre gerações.
+ */
+type LightSensorsActlumus1Data = LightSensorsRawChannels & {
+    time: number;
+    wavelength390: number;
+    wavelength415: number;
+    wavelength445: number;
+    wavelength480: number;
+    wavelength515: number;
+    wavelength555: number;
+    wavelength590: number;
+    wavelength630: number;
+    wavelength680: number;
+    wavelength750: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: null;
+    light_sensor_y: null;
+    light_sensor_x: null;
+    light_sensor_fd: null;
+};
+/**
+ * Leitura de tempo real de um ActLumus Plus / gen2 (`type: 'actlumus2'`).
+ *
+ * Espelha `LightSensorsActlumus2GraphicData.toMap()`
+ * (`packages/condor_interactors/lib/src/domain/entities/actlumus/2/light_sensors2_graphic_data_entity.dart`).
+ * ⚠️ Os comprimentos de onda **não** são os mesmos do gen1 — são 14 (395…800)
+ * contra 10 (390…750), sem nenhum valor em comum. Um gráfico que leia a lista
+ * do gen1 num device gen2 encontra `undefined` em todas as séries e renderiza
+ * vazio; discrimine sempre pelo `type`.
+ *
+ * `light_sensor_z/_y/_x` são as tristimulus CIE 1931 — Z no azul, Y no verde,
+ * X no vermelho.
+ */
+type LightSensorsActlumus2Data = LightSensorsRawChannels & {
+    time: number;
+    wavelength395: number;
+    wavelength426: number;
+    wavelength457: number;
+    wavelength488: number;
+    wavelength520: number;
+    wavelength551: number;
+    wavelength582: number;
+    wavelength613: number;
+    wavelength644: number;
+    wavelength675: number;
+    wavelength707: number;
+    wavelength738: number;
+    wavelength769: number;
+    wavelength800: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: number;
+    light_sensor_y: number;
+    light_sensor_x: number;
+    /** Flicker detect. Não entra na matriz do espectro. */
+    light_sensor_fd: number;
+};
 /**
  * Stream real-time de sensores de luz (FEST). Shape:
- * `{serialNo, type, data: <lightSensors.toMap()>}`. O subobjeto `data`
- * varia por device type — permissivo no MVP.
+ * `{serialNo, type, data: <lightSensors.toMap()>}`.
+ *
+ * União discriminada pelo `type`, que é o `DeviceType.name` do lado Dart. O
+ * `data` carrega **o espectro derivado e os canais crus que o originaram** —
+ * até a `0.16.0` só o espectro atravessava, e uma sonda que procurasse um canal
+ * cru pelo nome lia `undefined`.
  */
-interface DeviceLightSensorsPayload {
+type DeviceLightSensorsPayload = {
     serialNo: number;
-    type: string;
-    data: Record<string, unknown>;
-}
+    type: 'actlumus';
+    data: LightSensorsActlumus1Data;
+} | {
+    serialNo: number;
+    type: 'actlumus2';
+    data: LightSensorsActlumus2Data;
+};
 /** Ack de comando `syncTime`. */
 interface SyncTimeAckPayload {
     serialNo: number;
@@ -539,6 +644,16 @@ declare const Bridge: CondorBridge;
 
 interface BridgeClientHandshakeAck {
     shellVersion: string;
+    /**
+     * Versão do schema do **nativo**, repassada pelo shell — `null` se o nativo
+     * ainda não respondeu ou não existe (mock de browser).
+     *
+     * É por este número que um cliente decide se pode depender de capacidade
+     * nova: não há negociação de versão, e o cliente sandboxed não alcança o
+     * nativo por nenhum outro caminho. Ex.: canais crus de luz
+     * (`light_sensor_*` em `deviceLightSensors`) existem a partir da `0.16.0`.
+     */
+    nativeVersion: string | null;
     accepted: boolean;
 }
 interface CondorBridgeClient {
@@ -665,6 +780,15 @@ declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"handshake-ack", undefined>;
     readonly ack: v.ObjectSchema<{
         readonly shellVersion: v.StringSchema<undefined>;
+        /**
+         * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+         *
+         * `null` quando o nativo ainda não respondeu (ou não existe, como no
+         * mock de browser). O cliente roda dentro de um iframe sandboxed e não
+         * fala com o nativo diretamente, então este é o **único** caminho pelo
+         * qual ele descobre de qual versão são as capacidades disponíveis.
+         */
+        readonly nativeVersion: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly accepted: v.BooleanSchema<undefined>;
     }, undefined>;
 }, undefined>, v.ObjectSchema<{
@@ -768,6 +892,13 @@ declare class BridgeShell {
     private readonly onConfirm?;
     private readonly subscriptions;
     private detached;
+    /**
+     * Versão do nativo, obtida uma vez e cacheada. `null` até o nativo
+     * responder — e permanentemente `null` num browser sem nativo.
+     */
+    private nativeVersion;
+    /** Handshake com o nativo em voo; garante uma única chamada. */
+    private nativeHandshake;
     private pendingVerifies;
     constructor(opts: BridgeShellOptions);
     /**
@@ -823,7 +954,17 @@ declare class BridgeShell {
     private handleSubscribe;
     private handleUnsubscribe;
     private handleSend;
+    /**
+     * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
+     * vez e cacheando o resultado.
+     *
+     * ⚠️ `Bridge.handshake` **não tem timeout**: a Promise só resolve quando o
+     * nativo emite `handshake-ack`. Num browser sem nativo ela nunca resolve,
+     * então o `race` abaixo é o que garante que o cliente sempre receba
+     * resposta — com `null` — em vez de ficar pendurado.
+     */
+    private resolveNativeVersion;
     private postToClient;
 }
 
-export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type MockMessage, type MockState, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };
+export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };

package/dist/index.js

@@ -632,6 +632,8 @@ function onMessage(event) {
         pendingHandshake2 = null;
         resolve({
           shellVersion: msg.ack?.shellVersion ?? "unknown",
+          // `?? null` cobre o shell anterior à 0.17.0, que não mandava o campo.
+          nativeVersion: msg.ack?.nativeVersion ?? null,
           accepted: msg.ack?.accepted ?? false
         });
       }
@@ -790,6 +792,15 @@ var HandshakeAckMessage = v.object({
   type: v.literal("handshake-ack"),
   ack: v.object({
     shellVersion: v.string(),
+    /**
+     * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+     *
+     * `null` quando o nativo ainda não respondeu (ou não existe, como no
+     * mock de browser). O cliente roda dentro de um iframe sandboxed e não
+     * fala com o nativo diretamente, então este é o **único** caminho pelo
+     * qual ele descobre de qual versão são as capacidades disponíveis.
+     */
+    nativeVersion: v.nullable(v.string()),
     accepted: v.boolean()
   })
 });
@@ -810,7 +821,8 @@ var ShellToClientMessage = v.variant("type", [
 ]);
 
 // src/bridge-shell.ts
-var SHELL_VERSION = "0.5.1";
+var SHELL_VERSION = "0.6.0";
+var NATIVE_HANDSHAKE_TIMEOUT_MS = 2e3;
 var VERIFY_TIMEOUT_MS = 2e3;
 var OVERRIDE_PREFIX = `<script>
 (function(){
@@ -848,6 +860,13 @@ var BridgeShell = class {
   constructor(opts) {
     this.subscriptions = /* @__PURE__ */ new Map();
     this.detached = false;
+    /**
+     * Versão do nativo, obtida uma vez e cacheada. `null` até o nativo
+     * responder — e permanentemente `null` num browser sem nativo.
+     */
+    this.nativeVersion = null;
+    /** Handshake com o nativo em voo; garante uma única chamada. */
+    this.nativeHandshake = null;
     // Map de `verify-sandbox` round-trips pendentes — key gerada por nonce.
     this.pendingVerifies = /* @__PURE__ */ new Map();
     this.onMessage = async (event) => {
@@ -872,9 +891,11 @@ var BridgeShell = class {
           await this.handleSend(msg.command, msg.args ?? {});
           break;
         case "handshake":
-          this.postToClient({
-            type: "handshake-ack",
-            ack: { shellVersion: SHELL_VERSION, accepted: true }
+          void this.resolveNativeVersion().then((nativeVersion) => {
+            this.postToClient({
+              type: "handshake-ack",
+              ack: { shellVersion: SHELL_VERSION, nativeVersion, accepted: true }
+            });
           });
           break;
         case "jsError":
@@ -1053,6 +1074,29 @@ var BridgeShell = class {
     }
     Bridge.send(command, args);
   }
+  /**
+   * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
+   * vez e cacheando o resultado.
+   *
+   * ⚠️ `Bridge.handshake` **não tem timeout**: a Promise só resolve quando o
+   * nativo emite `handshake-ack`. Num browser sem nativo ela nunca resolve,
+   * então o `race` abaixo é o que garante que o cliente sempre receba
+   * resposta — com `null` — em vez de ficar pendurado.
+   */
+  async resolveNativeVersion() {
+    if (this.nativeVersion !== null) return this.nativeVersion;
+    if (!this.nativeHandshake) {
+      this.nativeHandshake = Bridge.handshake({ clientVersion: SHELL_VERSION }).then((ack) => {
+        this.nativeVersion = ack.nativeVersion;
+      }).catch(() => {
+      });
+    }
+    await Promise.race([
+      this.nativeHandshake,
+      new Promise((resolve) => setTimeout(resolve, NATIVE_HANDSHAKE_TIMEOUT_MS))
+    ]);
+    return this.nativeVersion;
+  }
   postToClient(msg) {
     if (this.detached) return;
     this.iframe.contentWindow?.postMessage(msg, "*");