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

package/lib/services/micGate.d.ts

@@ -21,6 +21,13 @@ export interface MicGateOptions {
     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

package/lib/types/index.d.ts

@@ -400,21 +400,73 @@ 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. 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.
+     * 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. 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.
+     * 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. */
@@ -477,6 +529,8 @@ export interface NapsterCompanionApiConfig {
      * When on, `mountContainer` is ignored — the avatar must live in the top document.
      */
     persistence?: PersistenceOptions;
+    /** 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;
@@ -592,10 +646,26 @@ export interface NapsterCompanionApiInstance {
  */
 export interface NapsterCompanionApiSDK {
     /**
-     * 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.
+     * 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.
+     */
+    init(getToken: () => Promise<string>, config: Partial<NapsterCompanionApiConfig> & {
+        button: ButtonConfig & {
+            enabled: true;
+        };
+    }): Promise<NapsterCompanionApiController>;
+    /**
+     * Initialize the SDK and connect immediately: resolves once the session is up.
+     *
+     * `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.
      */
     init(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
     /** The SDK version string (useful for diagnostics). */

package/package.json

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