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

package/lib/services/micGate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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;
+}
+/**
+ * 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. */
@@ -405,6 +404,19 @@ export interface PersistenceOptions {
  * All fields are optional; sensible defaults are used by the SDK.
  */
 export interface NapsterCompanionApiConfig {
+    /**
+     * Connection transport. Only `"webrtc"` exists today — any other value is a
+     * compile-time error. Reserved for future transports (e.g. WebSocket); until
+     * then the SDK defaults to `"webrtc"` and there is no reason to set this.
+     */
+    transport?: "webrtc";
+    /**
+     * Connection modality. Only `"video"` exists today — any other value is a
+     * compile-time error. Reserved for future modalities (e.g. audio-only,
+     * text); until then the SDK defaults to `"video"` and there is no reason to
+     * set this.
+     */
+    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 +473,10 @@ 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;
-    };
     /** Lifecycle callbacks. All are optional. */
     /** Called when the SDK has finished initialization and is ready to render. */
     onReady?: () => void;
@@ -585,42 +587,17 @@ 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.
-     */
-    initWithButton(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): import("../button").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);
-     * ```
-     *
-     * 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.
+     * Initialize the SDK. `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 — minting it before the mic
+     * prompt lets it go stale while the user is deciding.
      */
-    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.2",
   "keywords": [
     "napster",
     "companion-api",

package/lib/button/element.d.ts

@@ -1,6 +0,0 @@
-export interface ButtonElementOptions {
-    label: string;
-    avatarUrl?: string;
-    onClick: () => void;
-}
-export declare function createButtonElement(options: ButtonElementOptions): HTMLButtonElement;

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;