@player-ui/external-state-plugin 1.0.0--canary.865.36694 → 1.0.0

package/src/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { expect, test, vitest, describe } from "vitest";
 import type { Flow, InProgressState, NamedState } from "@player-ui/player";
 import { Player } from "@player-ui/player";
-import { ExternalStatePlugin } from "..";
+import { ExternalStatePlugin, ExternalStateError } from "..";
 import { waitFor } from "@testing-library/react";
 
 const externalFlow = {
@@ -242,6 +242,12 @@ test("only transitions if player still on this external state", async () => {
             });
           },
         },
+        {
+          ref: "test-2",
+          handlerFunction: () => {
+            return "Next";
+          },
+        },
       ]),
     ],
   });
@@ -319,6 +325,151 @@ test("only transitions if player still on this external state", async () => {
   ).toBe("EXT_2");
 });
 
+const flowWithErrorTransitions = {
+  id: "test-flow",
+  data: {},
+  views: [
+    {
+      id: "error-view",
+      type: "test",
+    },
+  ],
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "EXT_1",
+      errorTransitions: {
+        externalState: "ERROR_VIEW",
+      },
+      EXT_1: {
+        state_type: "EXTERNAL",
+        ref: "test-1",
+        transitions: { Next: "END_FWD" },
+      },
+      ERROR_VIEW: {
+        state_type: "VIEW",
+        ref: "error-view",
+        transitions: {},
+      },
+      END_FWD: {
+        state_type: "END",
+        outcome: "FWD",
+      },
+    },
+  },
+};
+
+test("missing handler error navigates via content errorTransitions", async () => {
+  const player = new Player({
+    plugins: [new ExternalStatePlugin([])],
+  });
+
+  player.start(flowWithErrorTransitions as Flow);
+
+  await waitFor(() => {
+    const state = player.getState() as InProgressState;
+    expect(state.controllers.flow.current?.currentState?.name).toBe(
+      "ERROR_VIEW",
+    );
+  });
+});
+
+test("missing transition value error navigates via content errorTransitions", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        { ref: "test-1", handlerFunction: () => undefined },
+      ]),
+    ],
+  });
+
+  player.start(flowWithErrorTransitions as Flow);
+
+  await waitFor(() => {
+    const state = player.getState() as InProgressState;
+    expect(state.controllers.flow.current?.currentState?.name).toBe(
+      "ERROR_VIEW",
+    );
+  });
+});
+
+test("missing handler error is observable via onError tap", async () => {
+  const onErrorSpy = vitest.fn().mockReturnValue(true);
+
+  const player = new Player({
+    plugins: [new ExternalStatePlugin([])],
+  });
+
+  player.hooks.errorController.tap("test", (ec) => {
+    ec.hooks.onError.tap("test", onErrorSpy);
+  });
+
+  player.start(externalFlow as Flow);
+
+  await waitFor(() => expect(onErrorSpy).toHaveBeenCalledOnce());
+
+  const error = onErrorSpy.mock.calls[0]?.[0] as ExternalStateError;
+  expect(error).toBeInstanceOf(ExternalStateError);
+  expect(error.type).toBe("externalState");
+  expect(error.metadata).toStrictEqual({
+    ref: "test-1",
+    reason: "missing-handler",
+  });
+});
+
+test("missing transition value error is observable via onError tap", async () => {
+  const onErrorSpy = vitest.fn().mockReturnValue(true);
+
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        { ref: "test-1", handlerFunction: () => undefined },
+      ]),
+    ],
+  });
+
+  player.hooks.errorController.tap("test", (ec) => {
+    ec.hooks.onError.tap("test", onErrorSpy);
+  });
+
+  player.start(externalFlow as Flow);
+
+  await waitFor(() => expect(onErrorSpy).toHaveBeenCalledOnce());
+
+  const error = onErrorSpy.mock.calls[0]?.[0] as ExternalStateError;
+  expect(error).toBeInstanceOf(ExternalStateError);
+  expect(error.metadata).toStrictEqual({
+    ref: "test-1",
+    reason: "missing-transition-value",
+  });
+});
+
+describe("ExternalStateError", () => {
+  test("missingHandler has correct shape", () => {
+    const error = ExternalStateError.missingHandler("my-ref");
+    expect(error.type).toBe("externalState");
+    expect(error.metadata).toStrictEqual({
+      ref: "my-ref",
+      reason: "missing-handler",
+    });
+    expect(error.message).toBe(
+      'No handler found for external state with ref: "my-ref". Ensure a handler is registered for this state.',
+    );
+  });
+
+  test("missingTransitionValue has correct shape", () => {
+    const error = ExternalStateError.missingTransitionValue("my-ref");
+    expect(error.type).toBe("externalState");
+    expect(error.metadata).toStrictEqual({
+      ref: "my-ref",
+      reason: "missing-transition-value",
+    });
+    expect(error.message).toBe(
+      'Handler for external state with ref: "my-ref" did not return a transition value. Ensure the handler returns the name of a valid transition.',
+    );
+  });
+});
+
 describe("edge cases", () => {
   test("async action nodes not transitioning from navigation states with *", async () => {
     const player = new Player({
@@ -439,8 +590,29 @@ describe("edge cases", () => {
     });
   });
 
-  test("no handler registered for external state - no transition occurs", async () => {
-    // Create a player with NO handlers registered
+  test("no handler registered for external state - calls captureError with ExternalStateError", async () => {
+    const player = new Player({
+      plugins: [new ExternalStatePlugin([])],
+    });
+
+    const captureSpy = vitest.fn().mockReturnValue(false);
+    player.hooks.errorController.tap("test", (ec) => {
+      vitest.spyOn(ec, "captureError").mockImplementation(captureSpy);
+    });
+
+    player.start(externalFlow as Flow);
+
+    await waitFor(() => expect(captureSpy).toHaveBeenCalledOnce());
+
+    const error = captureSpy.mock.calls[0]?.[0] as ExternalStateError;
+    expect(error).toBeInstanceOf(ExternalStateError);
+    expect(error.metadata).toStrictEqual({
+      ref: "test-1",
+      reason: "missing-handler",
+    });
+  });
+
+  test("no handler for this ref (but other refs registered) - calls captureError", async () => {
     const player = new Player({
       plugins: [
         new ExternalStatePlugin([
@@ -450,33 +622,21 @@ describe("edge cases", () => {
       ],
     });
 
-    const started = player.start(externalFlow as Flow);
-
-    // Wait for player to reach the external state
-    await vitest.waitFor(() =>
-      expect(player.getState().status).toBe("in-progress"),
-    );
-
-    // Get the current state
-    const state = player.getState() as InProgressState;
-    const currentState = state.controllers.flow.current?.currentState;
-
-    // Should be stuck on the external state
-    expect(currentState?.name).toBe("EXT_1");
-    expect(currentState?.value.state_type).toBe("EXTERNAL");
+    const captureSpy = vitest.fn().mockReturnValue(false);
+    player.hooks.errorController.tap("test", (ec) => {
+      vitest.spyOn(ec, "captureError").mockImplementation(captureSpy);
+    });
 
-    // Wait a bit to ensure no transition occurs
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    player.start(externalFlow as Flow);
 
-    // Should still be on the external state (no transition occurred)
-    const laterState = player.getState() as InProgressState;
-    const laterCurrentState = laterState.controllers.flow.current?.currentState;
-    expect(laterCurrentState?.name).toBe("EXT_1");
-    expect(laterCurrentState?.value.state_type).toBe("EXTERNAL");
+    await waitFor(() => expect(captureSpy).toHaveBeenCalledOnce());
 
-    // Clean up - manually transition to end the flow
-    laterState.controllers.flow.transition("Next");
-    await started;
+    const error = captureSpy.mock.calls[0]?.[0] as ExternalStateError;
+    expect(error).toBeInstanceOf(ExternalStateError);
+    expect(error.metadata).toStrictEqual({
+      ref: "test-1",
+      reason: "missing-handler",
+    });
   });
 });
 

package/src/index.ts

@@ -5,9 +5,15 @@ import type {
   PlayerFlowState,
   NavigationFlowState,
   NavigationFlowExternalState,
+  ErrorController,
+  FlowInstance,
 } from "@player-ui/player";
 import { Registry } from "@player-ui/partial-match-registry";
 import { ExternalStatePluginSymbol } from "./symbols.js";
+import { ExternalStateError } from "./ExternalStateError.js";
+
+export { ExternalStateError } from "./ExternalStateError.js";
+export type { ExternalStateErrorMetadata } from "./ExternalStateError.js";
 
 export type ExternalStateHandlerMatch = Record<string, unknown>;
 
@@ -60,6 +66,11 @@ export class ExternalStatePlugin implements PlayerPlugin {
    */
   private readonly handlers: ExternalStateHandler[];
 
+  /** The error controller to use for this plugin.
+   * Only the first instance of the plugin should tap the error controller hook.
+   */
+  private errorController?: ErrorController;
+
   /** Creates a new ExternalStatePlugin */
   constructor(handlers: ExternalStateHandler[]) {
     this.handlers = handlers;
@@ -74,52 +85,103 @@ export class ExternalStatePlugin implements PlayerPlugin {
       return;
     }
 
+    player.hooks.errorController.tap(this.name, (errorController) => {
+      this.errorController = errorController;
+    });
+
     player.hooks.flowController.tap(this.name, (flowController) => {
       flowController.hooks.flow.tap(this.name, (flow) => {
-        flow.hooks.afterTransition.tap(this.name, async (flowInstance) => {
-          const toState = flowInstance.currentState;
-          const currentState = player.getState();
-
-          if (
-            toState &&
-            toState.value &&
-            isExternal(toState.value) &&
-            isInProgress(currentState)
-          ) {
-            try {
-              const handler = this.registry?.get(toState.value);
-              const transitionValue = await handler?.(
-                toState.value,
-                currentState.controllers,
-              );
-
-              if (transitionValue !== undefined) {
-                const latestState = player.getState();
-
-                // Ensure the Player is still in the same state after waiting for transitionValue
-                if (
-                  isInProgress(latestState) &&
-                  latestState.controllers.flow.current?.currentState?.name ===
-                    toState.name
-                ) {
-                  latestState.controllers.flow.transition(transitionValue);
-                } else {
-                  player.logger.warn(
-                    `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`,
-                  );
-                }
-              }
-            } catch (error) {
-              if (error instanceof Error) {
-                currentState.fail(error);
-              }
-            }
-          }
+        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {
+          this.handleAfterTransition(player, flowInstance);
         });
       });
     });
   }
 
+  /**
+   * Resolve an EXTERNAL state transition.
+   */
+  private async handleAfterTransition(
+    player: Player,
+    flowInstance: FlowInstance,
+  ): Promise<void> {
+    const toState = flowInstance.currentState;
+    const currentState = player.getState();
+
+    if (
+      !toState ||
+      !toState.value ||
+      !isExternal(toState.value) ||
+      !isInProgress(currentState)
+    ) {
+      return;
+    }
+
+    try {
+      const handler = this.registry?.get(toState.value);
+
+      if (!handler) {
+        this.reportError(
+          player,
+          ExternalStateError.missingHandler(toState.value.ref),
+        );
+        return;
+      }
+
+      const transitionValue = await handler(
+        toState.value,
+        currentState.controllers,
+      );
+
+      if (!transitionValue) {
+        this.reportError(
+          player,
+          ExternalStateError.missingTransitionValue(toState.value.ref),
+        );
+        return;
+      }
+
+      const latestState = player.getState();
+
+      // Ensure the Player is still in the same state after waiting for transitionValue
+      if (
+        isInProgress(latestState) &&
+        latestState.controllers.flow.current?.currentState?.name ===
+          toState.name
+      ) {
+        latestState.controllers.flow.transition(transitionValue);
+      } else {
+        player.logger.warn(
+          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`,
+        );
+      }
+    } catch (error) {
+      // Thrown errors are treated as purposefully unrecoverable: fail the flow rather than
+      // routing through captureError.
+      if (error instanceof Error) {
+        currentState.fail(error);
+      }
+    }
+  }
+
+  /**
+   * Report an ExternalStateError via the errorController.
+   */
+  private reportError(player: Player, error: ExternalStateError): void {
+    // The compiler believes errorController could be nil, but in practice it should always
+    // be set by the time this method runs. The logger fallback exists only as defense
+    // against an unexpected lifecycle regression — if it ever fires, that's a bug to
+    // investigate, not normal operation.
+    if (!this.errorController) {
+      player.logger.error(
+        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`,
+      );
+      return;
+    }
+
+    this.errorController.captureError(error);
+  }
+
   /**
    * Create or share the registry for this plugin instance.
    *

package/types/ExternalStateError.d.ts

@@ -0,0 +1,20 @@
+import type { ErrorMetadata, PlayerErrorMetadata } from "@player-ui/player";
+import { ErrorSeverity } from "@player-ui/player";
+export type ExternalStateErrorReason = "missing-handler" | "missing-transition-value";
+export interface ExternalStateErrorMetadata extends ErrorMetadata {
+    /** The `ref` of the EXTERNAL state that produced the error */
+    ref: string;
+    /** Which failure mode this error represents */
+    reason: ExternalStateErrorReason;
+}
+export declare class ExternalStateError extends Error implements PlayerErrorMetadata<ExternalStateErrorMetadata> {
+    readonly type: string;
+    readonly severity: ErrorSeverity;
+    readonly metadata: ExternalStateErrorMetadata;
+    private constructor();
+    /** No handler was registered for the EXTERNAL state's ref. */
+    static missingHandler(ref: string): ExternalStateError;
+    /** A handler ran but returned no transition value. */
+    static missingTransitionValue(ref: string): ExternalStateError;
+}
+//# sourceMappingURL=ExternalStateError.d.ts.map

package/types/index.d.ts

@@ -1,4 +1,6 @@
 import type { Player, PlayerPlugin, InProgressState, NavigationFlowExternalState } from "@player-ui/player";
+export { ExternalStateError } from "./ExternalStateError.js";
+export type { ExternalStateErrorMetadata } from "./ExternalStateError.js";
 export type ExternalStateHandlerMatch = Record<string, unknown>;
 export type ExternalStateHandlerFunction = (state: NavigationFlowExternalState, options: InProgressState["controllers"]) => string | undefined | Promise<string | undefined>;
 export type ExternalStateHandler = {
@@ -30,9 +32,21 @@ export declare class ExternalStatePlugin implements PlayerPlugin {
      * The handlers for this plugin instance.
      */
     private readonly handlers;
+    /** The error controller to use for this plugin.
+     * Only the first instance of the plugin should tap the error controller hook.
+     */
+    private errorController?;
     /** Creates a new ExternalStatePlugin */
     constructor(handlers: ExternalStateHandler[]);
     apply(player: Player): void;
+    /**
+     * Resolve an EXTERNAL state transition.
+     */
+    private handleAfterTransition;
+    /**
+     * Report an ExternalStateError via the errorController.
+     */
+    private reportError;
     /**
      * Create or share the registry for this plugin instance.
      *