@npaw/forge-react-native 10.0.4 → 10.2.0

package/ios/ForgeModuleImpl.swift

@@ -36,11 +36,17 @@ public final class ForgeModuleImpl: NSObject {
     /// Set by the TurboModule shell; receives the channel body for every line
     /// of the kernel's rendered decision log.
     @objc public var logSink: (([String: Any]) -> Void)?
+    /// Set by the TurboModule shell; receives the channel body for every
+    /// subscribed remote command.
+    @objc public var commandSink: (([String: Any]) -> Void)?
 
     private let lock = NSLock()
     private var instances: [String: NPAWForge] = [:]
     private var subscriptions: [String: ForgeEventSubscription] = [:]
     private var logSubscriptions: [String: ForgeEventSubscription] = [:]
+    /// Remote command subscriptions per instance, one native listener per
+    /// subscribed name; explicit, so they do not follow `listenerCount`.
+    private var commandSubscriptions: [String: [String: ForgeEventSubscription]] = [:]
     private var adReporters: [Int: ManualAdReporter] = [:]
     private var nextInstanceId = 1
     private var nextReporterId = 1
@@ -106,6 +112,7 @@ public final class ForgeModuleImpl: NSObject {
         let forge = instances.removeValue(forKey: instanceId)
         let subscription = subscriptions.removeValue(forKey: instanceId)
         let logSubscription = logSubscriptions.removeValue(forKey: instanceId)
+        let commandSubscription = commandSubscriptions.removeValue(forKey: instanceId)
         lock.unlock()
 
         guard let forge else {
@@ -114,9 +121,66 @@ public final class ForgeModuleImpl: NSObject {
         }
         subscription?.cancel()
         logSubscription?.cancel()
+        commandSubscription?.values.forEach { $0.cancel() }
         resolve(Self.outcomeToDictionary(forge.destroy()))
     }
 
+    // MARK: - Remote commands
+
+    @objc public func setCommandSubscriptions(
+        _ instanceId: String,
+        names: [String],
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        var current = commandSubscriptions[instanceId] ?? [:]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        let wanted = Set(names.filter { !$0.isEmpty })
+        var cancelled: [ForgeEventSubscription] = []
+        for name in Array(current.keys) where !wanted.contains(name) {
+            if let subscription = current.removeValue(forKey: name) {
+                cancelled.append(subscription)
+            }
+        }
+        for name in wanted where current[name] == nil {
+            // One native listener per name; the JS registry fans out to its
+            // own listeners and answers by id through answerCommand.
+            current[name] = forge.onCommand(name) { [weak self] command, _ in
+                guard let self, let sink = self.commandSink else { return }
+                sink([
+                    "instanceId": instanceId,
+                    "id": command.id,
+                    "name": command.name,
+                    "args": command.args,
+                ])
+            }
+        }
+        lock.lock()
+        commandSubscriptions[instanceId] = current
+        lock.unlock()
+        cancelled.forEach { $0.cancel() }
+        resolve(Self.outcomeToDictionary(.accepted))
+    }
+
+    @objc public func answerCommand(
+        _ instanceId: String,
+        commandId: String,
+        handled: Bool,
+        details: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.answerCommand(id: commandId, handled: handled, details: Self.stringMap(details))
+        }
+    }
+
     @objc public func setLogLevel(
         _ instanceId: String,
         level: String,
@@ -959,9 +1023,11 @@ public final class ForgeModuleImpl: NSObject {
     @objc public func invalidate() {
         lock.lock()
         let cancelled = Array(subscriptions.values) + Array(logSubscriptions.values)
+            + commandSubscriptions.values.flatMap { Array($0.values) }
         let live = Array(instances.values)
         subscriptions.removeAll()
         logSubscriptions.removeAll()
+        commandSubscriptions.removeAll()
         instances.removeAll()
         adReporters.removeAll()
         listenerCount = 0

package/ios/NPAWForgeTurboModule.mm

@@ -26,6 +26,7 @@
 
 static NSString *const kForgeEventChannel = @"NPAWForgeEvent";
 static NSString *const kForgeLogChannel = @"NPAWForgeLog";
+static NSString *const kForgeCommandChannel = @"NPAWForgeCommand";
 
 @interface NPAWForgeReactNative : RCTEventEmitter
 #ifdef RCT_NEW_ARCH_ENABLED
@@ -52,13 +53,16 @@ RCT_EXPORT_MODULE(NPAWForgeRN)
     ForgeModuleImpl.shared.logSink = ^(NSDictionary<NSString *, id> *body) {
       [weakSelf sendEventWithName:kForgeLogChannel body:body];
     };
+    ForgeModuleImpl.shared.commandSink = ^(NSDictionary<NSString *, id> *body) {
+      [weakSelf sendEventWithName:kForgeCommandChannel body:body];
+    };
   }
   return self;
 }
 
 - (NSArray<NSString *> *)supportedEvents
 {
-  return @[ kForgeEventChannel, kForgeLogChannel ];
+  return @[ kForgeEventChannel, kForgeLogChannel, kForgeCommandChannel ];
 }
 
 - (void)startObserving
@@ -75,6 +79,7 @@ RCT_EXPORT_MODULE(NPAWForgeRN)
 {
   ForgeModuleImpl.shared.eventSink = nil;
   ForgeModuleImpl.shared.logSink = nil;
+  ForgeModuleImpl.shared.commandSink = nil;
   [ForgeModuleImpl.shared invalidate];
   [super invalidate];
 }
@@ -105,6 +110,16 @@ RCT_EXPORT_METHOD(setLogLevel : (NSString *)instanceId level : (NSString *)level
   [ForgeModuleImpl.shared setLogLevel:instanceId level:level resolve:resolve reject:ForgeMakeReject(reject)];
 }
 
+RCT_EXPORT_METHOD(setCommandSubscriptions : (NSString *)instanceId names : (NSArray<NSString *> *)names resolve : (RCTPromiseResolveBlock)resolve reject : (RCTPromiseRejectBlock)reject)
+{
+  [ForgeModuleImpl.shared setCommandSubscriptions:instanceId names:names ?: @[] resolve:resolve reject:ForgeMakeReject(reject)];
+}
+
+RCT_EXPORT_METHOD(answerCommand : (NSString *)instanceId commandId : (NSString *)commandId handled : (BOOL)handled details : (NSDictionary *)details resolve : (RCTPromiseResolveBlock)resolve reject : (RCTPromiseRejectBlock)reject)
+{
+  [ForgeModuleImpl.shared answerCommand:instanceId commandId:commandId handled:handled details:details resolve:resolve reject:ForgeMakeReject(reject)];
+}
+
 RCT_EXPORT_METHOD(startSession : (NSString *)instanceId metadata : (NSDictionary *)metadata resolve : (RCTPromiseResolveBlock)resolve reject : (RCTPromiseRejectBlock)reject)
 {
   [ForgeModuleImpl.shared startSession:instanceId metadata:metadata resolve:resolve reject:ForgeMakeReject(reject)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npaw/forge-react-native",
-  "version": "10.0.4",
+  "version": "10.2.0",
   "description": "NPAW Forge analytics for React Native: New Architecture TurboModule facade over the native Forge Android/Apple SDKs.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Victor Soto <victor.soto@nicepeopleatwork.com>",

package/src/NPAWForge.ts

@@ -14,8 +14,12 @@
 
 import NativeNPAWForge from './specs/NativeNPAWForge';
 import { ForgeVideo } from './ForgeVideo';
-import { subscribeInstanceEvents, subscribeInstanceLogs } from './events';
+import { subscribeInstanceCommands, subscribeInstanceEvents, subscribeInstanceLogs } from './events';
 import type {
+  ForgeCommand,
+  ForgeCommandAnswer,
+  ForgeCommandEvent,
+  ForgeCommandListener,
   ForgeConfig,
   ForgeEventSubscription,
   ForgeNetworkRequestRecord,
@@ -32,7 +36,18 @@ function asOutcome(value: Promise<unknown>): Promise<ForgeOutcome> {
   return value as Promise<ForgeOutcome>;
 }
 
+/** Distinct command names one host may subscribe to (the kernel cap). */
+export const MAX_COMMAND_SUBSCRIPTIONS = 64;
+
+const COMMAND_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+
+const NOOP_SUBSCRIPTION: ForgeEventSubscription = { remove: () => undefined };
+
 export class NPAWForge {
+  private readonly commandListeners = new Map<string, Set<ForgeCommandListener>>();
+  private commandChannel: ForgeEventSubscription | undefined;
+  private commandsClosed = false;
+
   private constructor(readonly instanceId: string) {}
 
   /** Builds a Forge instance; resolves once the native runtime is live. */
@@ -44,6 +59,12 @@ export class NPAWForge {
   // ---- lifecycle ----
 
   destroy(): Promise<ForgeOutcome> {
+    // Listeners go first: the native subscriptions die with the instance and
+    // a late answer must not reach a destroyed runtime.
+    this.commandsClosed = true;
+    this.commandListeners.clear();
+    this.commandChannel?.remove();
+    this.commandChannel = undefined;
     return asOutcome(NativeNPAWForge.destroy(this.instanceId));
   }
 
@@ -176,6 +197,115 @@ export class NPAWForge {
     return subscribeInstanceEvents(this.instanceId, callback);
   }
 
+  // ---- remote commands ----
+
+  /**
+   * Listens for a remote command by name. The backend delivers commands in
+   * the responses of Forge's own analytics requests, so they arrive only
+   * while events flow; a command nobody subscribed to is answered
+   * `handled=false` by the kernel and never re-delivered, so register early.
+   * Every listener of the name runs; call `answer(handled, details?)` at most
+   * once per listener, the first answer per command id is reported as a
+   * `command-answer` event. Blank or malformed names and the 65th distinct
+   * name are refused with a console warning.
+   */
+  onCommand(name: string, listener: ForgeCommandListener): ForgeEventSubscription {
+    const normalized = typeof name === 'string' ? name.trim() : '';
+    if (!COMMAND_NAME_PATTERN.test(normalized)) {
+      console.warn('[NPAWForge] ignored command listener: names are 1-64 characters of [A-Za-z0-9_.-]');
+      return NOOP_SUBSCRIPTION;
+    }
+    if (this.commandsClosed) {
+      return NOOP_SUBSCRIPTION;
+    }
+    let listeners = this.commandListeners.get(normalized);
+    if (!listeners) {
+      if (this.commandListeners.size >= MAX_COMMAND_SUBSCRIPTIONS) {
+        console.warn(
+          `[NPAWForge] ignored command listener: at most ${MAX_COMMAND_SUBSCRIPTIONS} distinct command names can be subscribed`
+        );
+        return NOOP_SUBSCRIPTION;
+      }
+      listeners = new Set<ForgeCommandListener>();
+      this.commandListeners.set(normalized, listeners);
+    }
+    listeners.add(listener);
+    if (!this.commandChannel) {
+      this.commandChannel = subscribeInstanceCommands(this.instanceId, (event) => this.dispatchCommand(event));
+    }
+    void this.syncCommandSubscriptions();
+    let active = true;
+    return {
+      remove: () => {
+        if (!active) {
+          return;
+        }
+        active = false;
+        const current = this.commandListeners.get(normalized);
+        if (!current) {
+          return;
+        }
+        current.delete(listener);
+        if (current.size === 0) {
+          this.commandListeners.delete(normalized);
+        }
+        if (this.commandListeners.size === 0) {
+          this.commandChannel?.remove();
+          this.commandChannel = undefined;
+        }
+        if (!this.commandsClosed) {
+          void this.syncCommandSubscriptions();
+        }
+      },
+    };
+  }
+
+  /** The remote command names currently subscribed, sorted. */
+  commandSubscriptions(): string[] {
+    return Array.from(this.commandListeners.keys()).sort();
+  }
+
+  /**
+   * Answers a delivered remote command by id, for hosts that correlate
+   * answers themselves. Prefer the `answer` handed to the listener. The
+   * kernel keeps the first answer per command id.
+   */
+  answerCommand(commandId: string, handled: boolean, details: Record<string, string> = {}): Promise<ForgeOutcome> {
+    if (this.commandsClosed) {
+      // The runtime is gone (or going): a late answer must not reach native.
+      return Promise.resolve({ code: 'ignored_invalid_state', isAccepted: false } as ForgeOutcome);
+    }
+    return asOutcome(NativeNPAWForge.answerCommand(this.instanceId, commandId, Boolean(handled), details));
+  }
+
+  private syncCommandSubscriptions(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.setCommandSubscriptions(this.instanceId, this.commandSubscriptions()));
+  }
+
+  private dispatchCommand(event: ForgeCommandEvent): void {
+    const listeners = this.commandListeners.get(event.name);
+    if (!listeners || listeners.size === 0) {
+      return;
+    }
+    const args = Array.isArray(event.args) ? event.args.map((arg) => String(arg)) : [];
+    for (const listener of Array.from(listeners)) {
+      let answered = false;
+      const answer: ForgeCommandAnswer = (handled, details) => {
+        if (answered) {
+          return Promise.resolve({ code: 'ignored_duplicate', isAccepted: false } as ForgeOutcome);
+        }
+        answered = true;
+        return this.answerCommand(event.id, handled, details ?? {});
+      };
+      const command: ForgeCommand = { id: event.id, name: event.name, args: [...args] };
+      try {
+        listener(command, answer);
+      } catch (error) {
+        console.warn('[NPAWForge] command listener failed', error);
+      }
+    }
+  }
+
   /**
    * Live feed of the kernel's rendered decision log for this instance - the
    * same lines `logLevel: 'trace'` writes to the platform console, without

package/src/events.ts

@@ -15,6 +15,7 @@
 import { NativeEventEmitter, NativeModules } from 'react-native';
 import NativeNPAWForge from './specs/NativeNPAWForge';
 import type {
+  ForgeCommandEvent,
   ForgeEventSubscription,
   ForgeRecordedEvent,
   ForgeRenderedLog,
@@ -22,6 +23,7 @@ import type {
 
 export const FORGE_EVENT_CHANNEL = 'NPAWForgeEvent';
 export const FORGE_LOG_CHANNEL = 'NPAWForgeLog';
+export const FORGE_COMMAND_CHANNEL = 'NPAWForgeCommand';
 
 const emitter = new NativeEventEmitter(
   // The spec module implements addListener/removeListeners; iOS needs the
@@ -58,3 +60,18 @@ export function subscribeInstanceLogs(
   );
   return { remove: () => subscription.remove() };
 }
+
+export function subscribeInstanceCommands(
+  instanceId: string,
+  callback: (command: ForgeCommandEvent) => void
+): ForgeEventSubscription {
+  const subscription = emitter.addListener(
+    FORGE_COMMAND_CHANNEL,
+    (command: ForgeCommandEvent) => {
+      if (command.instanceId === instanceId) {
+        callback(command);
+      }
+    }
+  );
+  return { remove: () => subscription.remove() };
+}

package/src/index.ts

@@ -12,10 +12,10 @@
  * @description: Public exports for @npaw/forge-react-native.
  */
 
-export { NPAWForge, DEFAULT_VIDEO_IDENTIFIER } from './NPAWForge';
+export { NPAWForge, DEFAULT_VIDEO_IDENTIFIER, MAX_COMMAND_SUBSCRIPTIONS } from './NPAWForge';
 export { ForgeVideo } from './ForgeVideo';
 export { ForgeAdReporter } from './ForgeAdReporter';
-export { FORGE_EVENT_CHANNEL, FORGE_LOG_CHANNEL } from './events';
+export { FORGE_COMMAND_CHANNEL, FORGE_EVENT_CHANNEL, FORGE_LOG_CHANNEL } from './events';
 export {
   installErrorCapture,
   trackScreenView,
@@ -31,6 +31,10 @@ export type {
   ForgeViewToken,
 } from './sections';
 export type {
+  ForgeCommand,
+  ForgeCommandAnswer,
+  ForgeCommandEvent,
+  ForgeCommandListener,
   ForgeConfig,
   ForgeEventSubscription,
   ForgeLogLevelName,

package/src/specs/NativeNPAWForge.ts

@@ -163,6 +163,15 @@ export interface Spec extends TurboModule {
   adFireBreakStop(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
   adFireDestroy(reporterId: number): Promise<UnsafeObject>;
 
+  // ---- remote commands ----
+  setCommandSubscriptions(instanceId: string, names: string[]): Promise<UnsafeObject>;
+  answerCommand(
+    instanceId: string,
+    commandId: string,
+    handled: boolean,
+    details: UnsafeObject
+  ): Promise<UnsafeObject>;
+
   // ---- event feed (classic emitter contract) ----
   addListener(eventName: string): void;
   removeListeners(count: number): void;

package/src/types.ts

@@ -148,3 +148,24 @@ export type ForgeNetworkRequestRecord = {
 };
 
 export type ForgeEventSubscription = { remove: () => void };
+
+/**
+ * A remote command the backend addressed to this client (delivered in the
+ * `npaw-command` header of an NQS response). `args` are positional strings in
+ * header order; `id` is opaque and echoed as `commandId` on the answer.
+ */
+export type ForgeCommand = { id: string; name: string; args: string[] };
+
+/**
+ * Answers a delivered command. Call it at most once per listener: the first
+ * call reports `handled` plus optional flat string `details` as a
+ * `command-answer` analytics event, later calls resolve `ignored_duplicate`
+ * locally. Only the first answer per command id across all listeners is
+ * emitted by the kernel.
+ */
+export type ForgeCommandAnswer = (handled: boolean, details?: Record<string, string>) => Promise<ForgeOutcome>;
+
+export type ForgeCommandListener = (command: ForgeCommand, answer: ForgeCommandAnswer) => void;
+
+/** Channel body of `NPAWForgeCommand`: the command plus its instance id. */
+export type ForgeCommandEvent = ForgeCommand & { instanceId: string };