@parity/product-sdk-signer 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as polkadot_api from 'polkadot-api';
 import { PolkadotSigner } from 'polkadot-api';
 import { SS58String } from '@parity/product-sdk-address';
+import { AllocatableResource, AllocationOutcome } from '@parity/product-sdk-host';
 
 /** Function that unsubscribes a listener when called. */
 type Unsubscribe = () => void;
@@ -139,7 +140,60 @@ interface SignerManagerOptions {
      * Set to `null` to disable persistence entirely.
      */
     persistence?: AccountPersistence | null;
+    /**
+     * Callback fired exactly when the manager transitions to `connected`
+     * with a selected account — not on subsequent state mutations while
+     * still connected. Fires again after auto-reconnect, so a fresh host
+     * session re-runs the callback.
+     *
+     * Common use: request product resource allocations once per session.
+     * The `ctx` exposes a pre-bound `requestResourceAllocation` helper
+     * plus an `AbortSignal` that fires if the user disconnects or
+     * destroys the manager mid-flight.
+     *
+     * `requestResourceAllocation` throws on failure (matches the
+     * `@parity/product-sdk-host` export of the same name); errors thrown
+     * from `onConnect` are logged but do not affect the connected state —
+     * the next reconnect retries.
+     *
+     * @example
+     * ```ts
+     * new SignerManager({
+     *   onConnect: async (_account, { requestResourceAllocation, signal }) => {
+     *     try {
+     *       const outcomes = await requestResourceAllocation([
+     *         { tag: "AutoSigning", value: undefined },
+     *       ]);
+     *       if (signal.aborted) return;
+     *       if (outcomes.some((o) => o.tag !== "Allocated")) {
+     *         logWarning("partial permissions", outcomes);
+     *       }
+     *     } catch (cause) {
+     *       logWarning("resource allocation failed", cause);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    onConnect?: OnConnect;
 }
+/** Context passed to the `onConnect` callback. */
+interface ConnectContext {
+    /**
+     * Aborted when the manager disconnects or is destroyed while the
+     * callback is still running. Pass through to `fetch` / cancellation
+     * primitives so mid-flight work stops promptly.
+     */
+    signal: AbortSignal;
+    /**
+     * Request a batch of host resource allocations. Bound shorthand for
+     * `requestResourceAllocation` from `@parity/product-sdk-host` —
+     * throws on failure, returns the unwrapped outcomes on success.
+     */
+    requestResourceAllocation: (resources: AllocatableResource[]) => Promise<AllocationOutcome[]>;
+}
+/** Callback signature for {@link SignerManagerOptions.onConnect}. */
+type OnConnect = (account: SignerAccount, ctx: ConnectContext) => void | Promise<void>;
 
 /** Base class for all signer errors. Use `instanceof SignerError` to catch any signer-related error. */
 declare class SignerError extends Error {
@@ -367,22 +421,69 @@ declare class HostProvider implements SignerProvider {
  * Core orchestrator for signer management.
  *
  * Manages account discovery and signer creation via the Host API.
- * Framework-agnostic — use the subscribe() pattern to integrate with
+ * Framework-agnostic — use the `subscribe()` pattern to integrate with
  * React, Vue, or any framework.
  *
+ * ## Lifecycle
+ *
+ * ```
+ *   disconnected → connecting → connected ──── selectAccount / signRaw / …
+ *        ▲             │           │
+ *        │             ▼           ▼
+ *        └── disconnect()  provider drops → auto-reconnect → connected
+ *                                                    (onConnect re-fires)
+ *
+ *                              ┌─ destroy() ──► (terminal — manager unusable)
+ *                              ▼
+ * ```
+ *
+ * ## Callbacks
+ *
+ * - **`subscribe(cb)`** fires synchronously on every state mutation, in
+ *   registration order, inside the call stack that mutated state. It does
+ *   **not** fire with the initial state — call `getState()` if you need a
+ *   priming read. Multiple mutations during the same operation produce
+ *   multiple notifications.
+ *
+ * - **`onConnect(account, ctx)`** (from `SignerManagerOptions`) fires
+ *   exactly when the manager transitions from non-connected to
+ *   `"connected"` with a selected account. It fires on a microtask
+ *   *after* the `subscribe` notification, so subscribers always observe
+ *   `state.status === "connected"` before `onConnect`'s side effects run.
+ *   It re-fires after auto-reconnect (the SDK reconnects automatically
+ *   when the provider drops), and re-fires after a fresh `connect()`.
+ *
+ * - **Internal `onAccountsChange` wiring** is worth a behavioral note:
+ *   when the provider reports an updated account list, the manager
+ *   preserves the current selection if its address is still present, or
+ *   sets `selectedAccount` to `null` if it isn't — it does **not** fall
+ *   back to `accounts[0]`. The fallback-to-first only applies on
+ *   connect-success, where there is no prior selection to preserve.
+ *
+ * ## `disconnect()` vs `destroy()`
+ *
+ * - `disconnect()` resets state to initial. Subsequent `connect()` calls
+ *   work normally. Reversible.
+ * - `destroy()` is **terminal**: the instance is marked unusable, all
+ *   subscribers are cleared, and any further call returns `DestroyedError`.
+ *   Use in framework teardown (React `useEffect` cleanup, HMR dispose).
+ *
+ * Both methods cancel any in-flight `connect`, reconnect attempt, and
+ * `onConnect` callback (the `ctx.signal` becomes aborted).
+ *
  * @example
  * ```ts
- * const manager = new SignerManager();
+ * const manager = new SignerManager({
+ *   onConnect: async (_account, { requestResourceAllocation }) => {
+ *     await requestResourceAllocation([{ tag: "AutoSigning", value: undefined }]);
+ *   },
+ * });
  * manager.subscribe(state => console.log(state.status));
  *
- * // Connect to the host provider
- * await manager.connect();
+ * await manager.connect();        // host provider (default)
+ * await manager.connect("dev");   // Alice / Bob / … for testing
  *
- * // Or use dev accounts for testing
- * await manager.connect("dev");
- *
- * // Select account and get signer
- * manager.selectAccount("5GrwvaEF...");
+ * manager.selectAccount("5GrwvaEF…");
  * const signer = manager.getSigner();
  * ```
  */
@@ -401,13 +502,26 @@ declare class SignerManager {
     private readonly dappName;
     private readonly persistenceOption;
     private resolvedPersistence;
+    private readonly onConnectCallback;
+    private onConnectController;
     constructor(options?: SignerManagerOptions);
     private getPersistence;
     /** Get a snapshot of the current state. */
     getState(): SignerState;
     /**
-     * Subscribe to state changes. The callback fires on every state mutation.
-     * Returns an unsubscribe function.
+     * Subscribe to state changes.
+     *
+     * The callback fires synchronously on every state mutation, in
+     * registration order, inside the call stack that mutated state. It
+     * does **not** fire with the current state at subscription time —
+     * call {@link getState} if you need a priming read.
+     *
+     * For "fired once when the user connects" semantics, prefer the
+     * {@link SignerManagerOptions.onConnect} option instead of gating on
+     * `state.status` inside this callback — `subscribe` will fire many
+     * times while connected (`selectAccount`, account swaps, etc.).
+     *
+     * @returns an unsubscribe function.
      */
     subscribe(callback: (state: SignerState) => void): () => void;
     /**
@@ -421,7 +535,13 @@ declare class SignerManager {
      * - `"dev"`: Connect using dev accounts (for testing)
      */
     connect(providerType?: ProviderType): Promise<Result<SignerAccount[], SignerError>>;
-    /** Disconnect from the current provider and reset state. */
+    /**
+     * Disconnect from the current provider and reset state to initial.
+     *
+     * Reversible — subsequent `connect()` calls work normally. Cancels
+     * any in-flight `connect`, reconnect attempt, or `onConnect` callback
+     * (`ctx.signal` becomes aborted).
+     */
     disconnect(): void;
     /**
      * Select an account by address.
@@ -477,7 +597,12 @@ declare class SignerManager {
     createRingVRFProof(dotNsIdentifier: string, derivationIndex: number, location: RingLocation, message: Uint8Array): Promise<Result<Uint8Array, SignerError>>;
     /**
      * Destroy the manager and release all resources.
-     * After calling destroy(), the manager is unusable.
+     *
+     * **Terminal** — clears all subscribers, cancels in-flight work, and
+     * marks the instance unusable. Any subsequent method returns
+     * `DestroyedError`. Idempotent. Use in framework teardown (React
+     * `useEffect` cleanup, HMR dispose). For a reversible reset, use
+     * {@link disconnect} instead.
      */
     destroy(): void;
     private connectToProvider;
@@ -488,6 +613,8 @@ declare class SignerManager {
     private getHostProvider;
     private cancelConnect;
     private cancelReconnect;
+    private cancelOnConnect;
+    private fireOnConnect;
     private disconnectInternal;
     private persistAccount;
     private loadPersistedAccount;
@@ -561,4 +688,4 @@ declare class DevProvider implements SignerProvider {
     onAccountsChange(_callback: (accounts: SignerAccount[]) => void): Unsubscribe;
 }
 
-export { AccountNotFoundError, type AccountPersistence, type ConnectionStatus, type ContextualAlias, DestroyedError, type DevAccountName, type DevKeyType, DevProvider, type DevProviderOptions, HostDisconnectedError, HostProvider, type HostProviderOptions, HostRejectedError, HostUnavailableError, NoAccountsError, type ProductAccount, type ProviderFactory, type ProviderType, type Result, type RetryOptions, type RingLocation, type SignerAccount, SignerError, SignerManager, type SignerManagerOptions, type SignerProvider, type SignerState, SigningFailedError, TimeoutError, type Unsubscribe, err, isHostError, ok, sleep, withRetry };
+export { AccountNotFoundError, type AccountPersistence, type ConnectContext, type ConnectionStatus, type ContextualAlias, DestroyedError, type DevAccountName, type DevKeyType, DevProvider, type DevProviderOptions, HostDisconnectedError, HostProvider, type HostProviderOptions, HostRejectedError, HostUnavailableError, NoAccountsError, type OnConnect, type ProductAccount, type ProviderFactory, type ProviderType, type Result, type RetryOptions, type RingLocation, type SignerAccount, SignerError, SignerManager, type SignerManagerOptions, type SignerProvider, type SignerState, SigningFailedError, TimeoutError, type Unsubscribe, err, isHostError, ok, sleep, withRetry };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createLogger } from '@parity/product-sdk-logger';
-import { getHostLocalStorage } from '@parity/product-sdk-host';
+import { requestResourceAllocation, getHostLocalStorage } from '@parity/product-sdk-host';
 import { seedToAccount } from '@parity/product-sdk-keys';
 import { ss58Encode, deriveH160 } from '@parity/product-sdk-address';
 
@@ -517,6 +517,13 @@ function initialState() {
     error: null
   };
 }
+function resolveSelectedAccount(accounts, preferredAddress) {
+  if (preferredAddress) {
+    const found = accounts.find((a) => a.address === preferredAddress);
+    if (found) return found;
+  }
+  return accounts[0] ?? null;
+}
 var SignerManager = class {
   state;
   provider = null;
@@ -532,6 +539,8 @@ var SignerManager = class {
   dappName;
   persistenceOption;
   resolvedPersistence;
+  onConnectCallback;
+  onConnectController = null;
   constructor(options) {
     this.ss58Prefix = options?.ss58Prefix ?? DEFAULT_SS58_PREFIX;
     this.hostTimeout = options?.hostTimeout ?? DEFAULT_HOST_TIMEOUT;
@@ -540,6 +549,7 @@ var SignerManager = class {
     this.dappName = options?.dappName ?? DEFAULT_DAPP_NAME;
     this.persistenceOption = options?.persistence;
     this.resolvedPersistence = options?.persistence;
+    this.onConnectCallback = options?.onConnect;
     this.state = initialState();
   }
   async getPersistence() {
@@ -555,8 +565,19 @@ var SignerManager = class {
     return this.state;
   }
   /**
-   * Subscribe to state changes. The callback fires on every state mutation.
-   * Returns an unsubscribe function.
+   * Subscribe to state changes.
+   *
+   * The callback fires synchronously on every state mutation, in
+   * registration order, inside the call stack that mutated state. It
+   * does **not** fire with the current state at subscription time —
+   * call {@link getState} if you need a priming read.
+   *
+   * For "fired once when the user connects" semantics, prefer the
+   * {@link SignerManagerOptions.onConnect} option instead of gating on
+   * `state.status` inside this callback — `subscribe` will fire many
+   * times while connected (`selectAccount`, account swaps, etc.).
+   *
+   * @returns an unsubscribe function.
    */
   subscribe(callback) {
     this.subscribers.add(callback);
@@ -580,6 +601,7 @@ var SignerManager = class {
     }
     this.cancelConnect();
     this.cancelReconnect();
+    this.cancelOnConnect();
     this.connectController = new AbortController();
     const signal = this.connectController.signal;
     this.disconnectInternal();
@@ -587,10 +609,17 @@ var SignerManager = class {
     const targetProvider = providerType ?? "host";
     return this.connectToProvider(targetProvider, signal);
   }
-  /** Disconnect from the current provider and reset state. */
+  /**
+   * Disconnect from the current provider and reset state to initial.
+   *
+   * Reversible — subsequent `connect()` calls work normally. Cancels
+   * any in-flight `connect`, reconnect attempt, or `onConnect` callback
+   * (`ctx.signal` becomes aborted).
+   */
   disconnect() {
     this.cancelConnect();
     this.cancelReconnect();
+    this.cancelOnConnect();
     this.disconnectInternal();
     this.setState(initialState());
     log3.info("disconnected");
@@ -709,13 +738,19 @@ var SignerManager = class {
   }
   /**
    * Destroy the manager and release all resources.
-   * After calling destroy(), the manager is unusable.
+   *
+   * **Terminal** — clears all subscribers, cancels in-flight work, and
+   * marks the instance unusable. Any subsequent method returns
+   * `DestroyedError`. Idempotent. Use in framework teardown (React
+   * `useEffect` cleanup, HMR dispose). For a reversible reset, use
+   * {@link disconnect} instead.
    */
   destroy() {
     if (this.isDestroyed) return;
     this.isDestroyed = true;
     this.cancelConnect();
     this.cancelReconnect();
+    this.cancelOnConnect();
     this.disconnectInternal();
     this.subscribers.clear();
     this.state = initialState();
@@ -745,8 +780,7 @@ var SignerManager = class {
     this.cleanups.push(accountUnsub);
     const accounts = result.value;
     const persisted = await this.loadPersistedAccount();
-    const restoredAccount = persisted ? accounts.find((a) => a.address === persisted) : null;
-    const selectedAccount = restoredAccount ?? (accounts.length > 0 ? accounts[0] : null);
+    const selectedAccount = resolveSelectedAccount(accounts, persisted);
     this.setState({
       status: "connected",
       accounts,
@@ -756,6 +790,7 @@ var SignerManager = class {
     });
     if (selectedAccount) {
       this.persistAccount(selectedAccount.address);
+      this.fireOnConnect(selectedAccount);
     }
     log3.info("connected", { provider: type, accounts: accounts.length });
     return result;
@@ -821,13 +856,20 @@ var SignerManager = class {
         });
         this.cleanups.push(accountUnsub);
         const accounts = result.value;
+        const selectedAccount = resolveSelectedAccount(
+          accounts,
+          this.state.selectedAccount?.address
+        );
         this.setState({
           status: "connected",
           accounts,
           activeProvider: providerType,
-          selectedAccount: accounts.find((a) => a.address === this.state.selectedAccount?.address) ?? (accounts.length > 0 ? accounts[0] : null),
+          selectedAccount,
           error: null
         });
+        if (selectedAccount) {
+          this.fireOnConnect(selectedAccount);
+        }
         log3.info("reconnected", { provider: providerType });
         return result;
       },
@@ -861,16 +903,38 @@ var SignerManager = class {
     return null;
   }
   cancelConnect() {
-    if (this.connectController) {
-      this.connectController.abort();
-      this.connectController = null;
-    }
+    this.connectController?.abort();
+    this.connectController = null;
   }
   cancelReconnect() {
-    if (this.reconnectController) {
-      this.reconnectController.abort();
-      this.reconnectController = null;
-    }
+    this.reconnectController?.abort();
+    this.reconnectController = null;
+  }
+  cancelOnConnect() {
+    this.onConnectController?.abort();
+    this.onConnectController = null;
+  }
+  fireOnConnect(account) {
+    const callback = this.onConnectCallback;
+    if (!callback) return;
+    this.cancelOnConnect();
+    const controller = new AbortController();
+    this.onConnectController = controller;
+    const ctx = {
+      signal: controller.signal,
+      requestResourceAllocation
+    };
+    queueMicrotask(async () => {
+      try {
+        await callback(account, ctx);
+      } catch (cause) {
+        log3.warn("onConnect callback threw", { cause });
+      } finally {
+        if (this.onConnectController === controller) {
+          this.onConnectController = null;
+        }
+      }
+    });
   }
   disconnectInternal() {
     for (const cleanup of this.cleanups) {