@touchcastllc/napster-companion-api-dev 1.6.0-alpha.0 → 1.6.0-alpha.3

package/lib/services/micGate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Handle returned by {@link gateOnMicrophone}. Lets the caller tear down an
+ * active recovery card (e.g. on session destroy) independent of whether the
+ * user ever retries.
+ */
+export interface MicGateController {
+    /** Force-hide the recovery card, if one is mounted. Safe to call unconditionally. */
+    dismiss(): void;
+}
+export interface MicGateOptions {
+    /** Element the recovery card mounts into on denial. */
+    root: HTMLElement;
+    /**
+     * The microphone is available. Fires once for an immediate grant, and
+     * again after each successful "Check again" retry. May return a promise —
+     * {@link gateOnMicrophone}'s own promise waits for it, so a caller that
+     * awaits the gate call also waits for whatever `onGranted` kicks off.
+     */
+    onGranted: () => void | Promise<void>;
+    /** Reported once, on the FIRST failure only — never on a refused retry. */
+    onError?: (error: Error) => void;
+    /** Fires immediately before the recovery card mounts. */
+    onBeforeRecovery?: () => void;
+    /**
+     * Staleness probe, checked after every await before the gate touches the DOM
+     * or calls back. A session destroyed — or superseded by a new init() — while
+     * the browser prompt was open must not mount a recovery card into its own
+     * detached root, and must not drive the session that replaced it.
+     */
+    isStale?: () => boolean;
+}
+/**
+ * Gate a session on microphone access (CA-622): try once, and on denial keep
+ * the widget mounted with a recovery card ("Check again", CA-774) instead of
+ * tearing it down.
+ */
+export declare function gateOnMicrophone(opts: MicGateOptions): Promise<MicGateController>;

package/lib/services/webrtc.d.ts

@@ -3,9 +3,7 @@ import type { MediaCapture } from "../utils/MediaCapture";
 export interface WebRTCController {
     startWithToken: (token: string) => Promise<void>;
     close: () => void;
-    forceReconnect: () => Promise<void>;
     getConnectionStatus: () => string;
-    getReconnectAttempts: () => number;
     getError: () => Error | null;
     updateAudioDevice: (deviceId: string) => Promise<void>;
 }
@@ -19,9 +17,6 @@ interface WebRTCParams {
         videoStream?: MediaStream | null;
         audioStream?: MediaStream | null;
     }) => void;
-    onDataChannel?: (dc: RTCDataChannel) => void;
-    maxReconnectAttempts?: number;
-    reconnectInterval?: number;
     /**
      * ICE servers for the peer connection. When omitted, servers from the
      * connection token are used, else {@link DEFAULT_ICE_SERVERS}. Provide this to

package/lib/types/index.d.ts

@@ -303,8 +303,7 @@ export interface NavigationProgressOptions {
     height?: string;
 }
 /**
- * Cross-page persistence options. Works with BOTH entry points — `init` and
- * `initWithButton` share the same persistence engine.
+ * Cross-page persistence options.
  */
 export interface PersistenceOptions {
     /** Turn persistence on. Required — there is no boolean shorthand. */
@@ -401,10 +400,75 @@ export interface PersistenceOptions {
     trapBackNavigation?: boolean;
 }
 /**
- * Main configuration object passed to `init(token, config)`.
+ * Click-to-start configuration. Opt in with `enabled: true`; without it `init()`
+ * connects immediately, exactly as it does with no `button` block at all.
+ */
+export interface ButtonConfig {
+    /** Opt in to click-to-start. Default `false`. */
+    enabled?: boolean;
+    /**
+     * Host-owned trigger — an element, or a selector resolved once at `init()`.
+     * When set the SDK renders no card of its own and `label`, `avatarUrl` and
+     * `description` are ignored. The SDK never moves or reparents the node; it
+     * sets `data-np-state`, toggles `disabled`, and hides it while a session is
+     * live, restoring it on end.
+     */
+    element?: HTMLElement | string;
+    /** Card text. Default: `"Talk to an agent"`. Ignored when `element` is set. */
+    label?: string;
+    /** Optional companion picture on the card. Ignored when `element` is set. */
+    avatarUrl?: string;
+    /** Supporting line under the label (Figma entry-point card). Ignored when `element` is set. */
+    description?: string;
+}
+/**
+ * Returned by `init()` in button mode. Nothing is connected when you receive it:
+ * the session starts on a click, or on `start()`.
+ */
+export interface NapsterCompanionApiController {
+    /**
+     * The current session's instance: `null` before the first `start()` and after
+     * `end()`/`destroy()`, non-null from the moment an attempt gets past the
+     * microphone gate. Non-null does **not** mean the avatar is live — a denied
+     * microphone leaves the attempt parked behind the recovery card with an
+     * instance already handed back. Use `onAvatarReady` for "the session is up".
+     */
+    getInstance(): NapsterCompanionApiInstance | null;
+    /**
+     * Start a session, as if the trigger was clicked. Resolves with the instance once
+     * connected, or `null` if the attempt failed — the failure is reported through
+     * `onError` — or if the controller has already been destroyed. It never rejects:
+     * the click path has no caller to catch one.
+     */
+    start(): Promise<NapsterCompanionApiInstance | null>;
+    /** End the session. The trigger returns to idle and can start another. */
+    end(): void;
+    /** Remove the SDK card (or release the host's node) and tear down any session. */
+    destroy(): void;
+}
+/**
+ * Main configuration object passed to `init(getToken, config)`.
  * All fields are optional; sensible defaults are used by the SDK.
  */
 export interface NapsterCompanionApiConfig {
+    /**
+     * Connection transport. Optional — the SDK defaults to `"webrtc"`, which is
+     * the only transport that exists today, so there is no reason to set this
+     * yet. Any other value is a compile-time error, and an unsupported
+     * transport/modality combination is rejected at init() with a clear error.
+     *
+     * Reserved for future transports (e.g. WebSocket).
+     */
+    transport?: "webrtc";
+    /**
+     * Connection modality. Optional — the SDK defaults to `"video"`, the only
+     * modality that exists today. Paired with {@link transport}: see that field
+     * for how invalid combinations are handled.
+     *
+     * Note this is the *connection* modality, not the UI being shown — how the
+     * session presents is a separate, runtime-changeable axis.
+     */
+    modality?: "video";
     /** Position of the avatar on screen. See `Position` enum. */
     position?: Position;
     /** CSS class name(s) to add to the SDK root container. Useful for theming. */
@@ -461,20 +525,12 @@ export interface NapsterCompanionApiConfig {
     /**
      * Keep the session alive across page navigation. When enabled, the page is wrapped in
      * a same-origin iframe so navigation happens inside it while the avatar stays in the
-     * top document, which never reloads. Works with both `init` and `initWithButton`.
+     * top document, which never reloads.
      * When on, `mountContainer` is ignored — the avatar must live in the top document.
      */
     persistence?: PersistenceOptions;
-    /**
-     * The click-to-start button's appearance. **Only used by `initWithButton()`** —
-     * passing it to `init()` (which connects immediately, with no button) throws.
-     */
-    button?: {
-        /** Button text. Default: `"Talk to an agent"`. */
-        label?: string;
-        /** Optional companion picture shown on the button. */
-        avatarUrl?: string;
-    };
+    /** Click-to-start configuration. Omit for the default connect-immediately behaviour. */
+    button?: ButtonConfig;
     /** Lifecycle callbacks. All are optional. */
     /** Called when the SDK has finished initialization and is ready to render. */
     onReady?: () => void;
@@ -585,42 +641,33 @@ export interface NapsterCompanionApiInstance {
     readonly isUserTalking: boolean;
 }
 /**
- * Top-level SDK object exposed by the package. Call `init(token, config)` to
+ * Top-level SDK object exposed by the package. Call `init(getToken, config)` to
  * bootstrap the SDK and receive a `NapsterCompanionApiInstance` for runtime control.
  */
 export interface NapsterCompanionApiSDK {
     /**
-     * Initialize the SDK using the provided connection token and optional config.
-     * Returns a Promise that resolves to a controllable `NapsterCompanionApiInstance`.
-     */
-    init(token: string, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
-    /**
-     * Render a button and connect on click (instead of connecting immediately like
-     * `init`). Returns a `NapsterCompanionApiController` synchronously — nothing connects
-     * until the user clicks. With `persistence`, the session survives navigation. No-op
-     * when run inside the persistence site frame.
+     * Initialize the SDK in click-to-start mode: resolves with a controller, and
+     * nothing connects until `start()` or a click on the entry point.
+     *
+     * `getToken` is called by the SDK itself once the microphone permission has
+     * settled — on every attempt, including a "Check again" retry — so the
+     * connection token is always fresh when signaling starts. A pre-minted token
+     * string is not accepted: minting it before the mic prompt lets it go stale
+     * while the user is deciding.
      */
-    initWithButton(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): import("../button").NapsterCompanionApiController;
+    init(getToken: () => Promise<string>, config: Partial<NapsterCompanionApiConfig> & {
+        button: ButtonConfig & {
+            enabled: true;
+        };
+    }): Promise<NapsterCompanionApiController>;
     /**
-     * Prompt for the microphone WITHOUT starting a session, so permission is settled
-     * before a connection token exists. A connection's lifetime starts the moment the
-     * backend creates it, and a prompt the user leaves open for seconds spends that
-     * budget before signaling runs — the session then fails to come up.
-     *
-     * `initWithButton` does this internally. Use it on the `init` path, where the host
-     * app owns when the token is minted:
-     *
-     * ```js
-     * await SDK.requestMicrophoneAccess();
-     * const token = await mintConnectionToken();
-     * await SDK.init(token, config);
-     * ```
+     * Initialize the SDK and connect immediately: resolves once the session is up.
      *
-     * Rejects with a `ConnectionError` whose `context.name` is the underlying
-     * DOMException — `"NotAllowedError"` (refused) or `"NotFoundError"` (no device).
-     * Calling it is free once granted: the stream is cached and reused by the session.
+     * `getToken` is called by the SDK itself once the microphone permission has
+     * settled, so the connection token is always fresh when signaling starts. A
+     * pre-minted token string is not accepted.
      */
-    requestMicrophoneAccess(): Promise<void>;
+    init(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
     /** The SDK version string (useful for diagnostics). */
     version: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "1.6.0-alpha.0",
+  "version": "1.6.0-alpha.3",
   "keywords": [
     "napster",
     "companion-api",

package/lib/button/index.d.ts

@@ -1,46 +0,0 @@
-import "./Button.css";
-import type { NapsterCompanionApiConfig, NapsterCompanionApiInstance } from "../types";
-/**
- * Returned by {@link initWithButton}. A session controller: start/end the agent session,
- * reach the live instance, or tear the button down. Created synchronously — nothing
- * connects until `start()` (or a button click).
- *
- * Inside the SDK's own persistence frame (and during SSR) the call no-ops and every
- * method here is a harmless no-op — `getInstance()` stays `null`. With
- * `debug: true` the skip is logged.
- */
-export interface NapsterCompanionApiController {
-    /** The live avatar instance once connected, else `null`. */
-    getInstance(): NapsterCompanionApiInstance | null;
-    /** Start the session (as if the button was clicked). */
-    start(): Promise<void>;
-    /** End the session (and, if persisted, unwrap back to the plain site). The button reappears. */
-    end(): void;
-    /** Remove the button and any active session/iframe. */
-    destroy(): void;
-}
-/**
- * What the button entry point needs from the SDK. Wired by the SDK's `initWithButton`
- * method so this module never reaches into the singleton's internals.
- */
-export interface ButtonDeps {
-    /** Connect a session; mounts the avatar into the button-owned root. */
-    init: (token: string, config?: Partial<NapsterCompanionApiConfig>) => Promise<NapsterCompanionApiInstance>;
-    /** Create + position the persistent, button-owned `#np_companion-sdk-root` and return it. */
-    mountRoot: (config: Partial<NapsterCompanionApiConfig>) => HTMLElement;
-    /** Remove the button-owned root and release SDK ownership (on destroy). */
-    unmountRoot: () => void;
-    /**
-     * Tear down any live session AND its persisted iframe WITHOUT navigating — reveal the
-     * page in place. Called when the whole widget is being removed (`destroy()`), where a
-     * page reload would be the wrong response. Private to the SDK↔button seam.
-     */
-    disposeSession: () => void;
-}
-/**
- * Build the button entry point. Returns a {@link NapsterCompanionApiController}.
- *
- * A no-op (returns an inert controller) when run inside the persistence site frame,
- * so the same snippet is safe on every page.
- */
-export declare function createButton(deps: ButtonDeps, getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): NapsterCompanionApiController;