@human.tech/waap-sdk 2.0.0 → 2.1.0-staging-fb27bb

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @human.tech/waap-sdk
 
+## 2.1.0
+
+### Minor Changes
+
+- Add multichain initializers (`initWaaPMulti`, `initWaaPSquid`), subpath entry
+  points (`/evm`, `/sui`, `/solana`, `/react`, `/walletconnect`), Solana Wallet
+  Standard support, `WaaPError`, and explicit wallet-environment selection.
+
+  Restores the published `asyncTxs` contract: `eth_sendTransaction` resolves with
+  the deterministic signed transaction hash, and every lifecycle event is keyed by
+  that same hash. The deprecated `asyncSigning` wire mode keeps returning
+  `{ pendingTxId, status: 'pending' }`.
+
+  `@human.tech/waap-interface-core` and `@human.tech/waap-constants` are runtime
+  dependencies of the SDK rather than bundled, so they must be published together
+  with it.
+
+### Patch Changes
+
+- Updated dependencies
+  - @human.tech/waap-interface-core@1.1.0
+  - @human.tech/waap-constants@1.1.0
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -1,257 +1,208 @@
 # WaaP SDK
 
-[npm link](https://www.npmjs.com/package/@human.tech/waap-sdk)
+`@human.tech/waap-sdk` is a browser bridge to the WaaP wallet iframe. It does
+not contain keys, policy-engine clients, transaction preparation, or signing
+material. The wallet reviews, gates, signs, and broadcasts requests.
 
-## Installation
+## Install
 
 ```bash
-npm install @human.tech/waap-sdk
-# or
-yarn add @human.tech/waap-sdk
-# or
 pnpm add @human.tech/waap-sdk
 ```
 
-## Usage
+## EVM
 
-### Basic Integration (Default Modal Mode)
-
-By default, the wallet renders as a centered modal with a backdrop overlay:
-
-```javascript
+```ts
 import { initWaaP } from '@human.tech/waap-sdk'
 
-// Initialize Human Wallet. This will set window.waap with all necessary methods
-initWaaP()
-
-// Request accounts (prompts user to connect)
-const accounts = await window.waap.request({ method: 'eth_requestAccounts' })
-console.log('Connected accounts:', accounts)
-
-// Send a transaction
-const txHash = await window.waap.request({
-  method: 'eth_sendTransaction',
-  params: [
-    {
-      from: accounts[0],
-      to: '0xRecipientAddress',
-      value: '0x123' // hex value in wei
-    }
-  ]
+const wallet = initWaaP({ environment: 'production' }) // `chains` defaults to ['evm']
+const [address] = (await wallet.request({
+  method: 'eth_requestAccounts'
+})) as string[]
+const signature = await wallet.request({
+  method: 'personal_sign',
+  params: ['0x68656c6c6f', address]
 })
-```
 
-### Basic Integration
+// Always release the public facade when the owning UI unmounts.
+wallet.destroy()
+```
 
-```javascript
-import { initWaap } from '@human.tech/waap-sdk'
+For a local wallet iframe use `{ environment: 'development' }`; for a preview
+host use `{ walletOrigin: 'https://wallet-preview.example' }`. An origin must
+be HTTPS, except loopback development hosts. `useStaging` remains an alias for
+`environment: 'staging'`.
 
-// Initialize Human Wallet. This will set window.silk with all necessary methods
-initWaap()
+## Sui
 
-// Request accounts (prompts user to connect)
-const accounts = await window.waap.request({ method: 'eth_requestAccounts' })
-console.log('Connected accounts:', accounts)
+```ts
+import { initWaaP } from '@human.tech/waap-sdk'
 
-// Send a transaction
-const txHash = await window.waap.request({
-  method: 'eth_sendTransaction',
-  params: [
-    {
-      from: accounts[0],
-      to: '0xRecipientAddress',
-      value: '0x123' // hex value in wei
-    }
-  ]
+const { sui: wallet } = initWaaP({
+  environment: 'production',
+  chains: ['sui']
 })
-```
-
-### Configuration Options
-
-`initWaaP` accepts the following configuration options:
-
-````javascript
-// WaaP (recommended)
-initWaaP({
-  // Optional: Your WalletConnect project ID (REQUIRED for WalletConnect functionality)
-  walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
-
-  // Optional: Human Wallet points referral code
-  referralCode: 'YOUR_REFERRAL_CODE',
-
-  // Optional: Custom UI configuration
-  config: {
-    // See documentation or the Developer Portal for more style options
-    authenticationMethods: [],
-    allowedSocials: [],
-    styles: {
-      darkMode: true
-    },
-    showSecured: true // Controls the display of 'Secured by human.tech' at the footer
-  },
-
-  // Optional: Project configuration
-  project: {
-    name: 'Your App Name', // Project name used throughout the SDK
-    entryTitle: 'Log in to Your App', // Optional: Custom title (defaults to "Sign In")
-    logo: 'Your app logo in base64 (see docs or portal)',
-    authSuccessUrl: '' // The URL to redirect to after a successfull oauth login
-    termsOfServiceUrl: '' // Terms of Service URL (will display at the footer)
-    privacyPolicyUrl: '' // Privacy Policy URL (will display at the footer)
-    projectId: '' // See documentation or the Developer Portal to learn how to set up a gastank for your users
-  },
-
-  // Optional: If you want to accept external wallets (by passing 'wallet' to the authenticationMethods array)
-  walletConnectProjectId: ''
+const { accounts } = await wallet.connect()
+const signed = await wallet.signPersonalMessage({
+  account: accounts[0],
+  message: new TextEncoder().encode('hello')
 })
+wallet.destroy()
+```
 
+## Solana
 
-### WalletConnect Support
-
-To use WalletConnect functionality, you **must** provide a WalletConnect project ID. This ID can be obtained from [WalletConnect Cloud](https://cloud.walletconnect.com/).
-
-You can provide the project ID in several ways (in order of precedence):
-
-1. **Pass it directly when initializing** (recommended):
-
-   ```javascript
-   // WaaP
-   initWaaP({
-     walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID'
-   })
-````
-
-2. **Set it programmatically**:
-
-   ```javascript
-   // WaaP
-   import { initWaaP, WaaPWalletConnect } from '@silk-wallet/silk-wallet-sdk'
-
-   WaaPWalletConnect.setProjectId('YOUR_WALLETCONNECT_PROJECT_ID')
-   initWaaP()
-   ```
-
-3. **Set it as an environment variable**:
-   - Set `NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID` in your .env.local file (Next.js)
-   - Or set `WALLET_CONNECT_PROJECT_ID` for other environments
-
-### API Reference
-
-The SDK implements the standard Ethereum Provider API (EIP-1193) with some additional methods. `window.waap` provides the following interface:
-
-- `enable()`: Alias for `request({ method: 'eth_requestAccounts' })`
-- `isConnected()`: Returns whether the provider is connected
-- `login()`: Prompt the user to connect an external wallet
-- `logout()`: Disconnect the current session
-- `getLoginMethod()`: Returns the current login method ('waap', 'injected', 'walletconnect', or null)
-- `requestEmail()`: Request the user's email address
-- `requestSBT(type)`: Request a Soulbound Token of the specified type
-- `toggleDarkMode()`: Toggle between light and dark mode
-
-### Auto-Connect Functionality
-
-The SDK automatically attempts to reconnect users when they refresh the page or return to your application. This works seamlessly in the background when you call `eth_requestAccounts`.
-
-#### How Auto-Connect Works
-
-1. When a user successfully logs in via `login()`, their choice is remembered
-2. On subsequent page loads, calling `eth_requestAccounts` (before `login()`) will automatically attempt to reconnect using their previous method
-3. If the previous method is no longer available or connected, the auto-connect will fail gracefully
-
-#### Checking the Current Login Method
-
-You can check which login method is currently active without triggering a connection:
-
-```javascript
-// WaaP
-const loginMethod = window.waap.getLoginMethod()
+```ts
+import { initWaaP } from '@human.tech/waap-sdk'
 
-if (loginMethod === 'waap') {
-  console.log('User is connected via WaaP')
-} else if (loginMethod === 'injected') {
-  console.log('User is connected via injected wallet (e.g., MetaMask)')
-} else if (loginMethod === 'walletconnect') {
-  console.log('User is connected via WalletConnect')
-} else {
-  console.log('User is not connected')
-}
+const { solana: wallet } = initWaaP({
+  environment: 'production',
+  chains: ['solana']
+})
+const { accounts } = await wallet.connect()
+const signed = await wallet.signMessage({
+  account: accounts[0],
+  message: new TextEncoder().encode('hello')
+})
+wallet.destroy()
 ```
 
-**Note**: `getLoginMethod()` verifies that the connection is actually still valid. If the wallet extension is disabled, WalletConnect session expired, or any other connection issue exists, it will return `null` and automatically clean up the stored state.
-
-#### Implementing Auto-Connect
+`features` implements `standard:connect`, `standard:disconnect`,
+`standard:events`, `solana:signMessage`, `solana:signTransaction`, and
+`solana:signAndSendTransaction`. The direct `signTransaction`,
+and `signAndSendTransaction` helpers remain available for wallet-adapter-style
+consumers. They accept
+serialized bytes (or a serializable transaction object). Dapp-built Solana
+transactions retain their exact bytes; obtain a fresh blockhash near approval
+to avoid expiry.
 
-```javascript
-// WaaP
-import { initWaaP } from '@silk-wallet/silk-wallet-sdk'
+`signAllTransactions` is temporarily unsupported while WaaP completes a
+batch-specific review and lifecycle controller. Submit transactions through
+`signTransaction` individually until that capability is restored.
 
-initWaaP()
+## Squid multichain
 
-try {
-  const accounts = await window.waap.request({
-    method: 'eth_requestAccounts'
-  })
-  console.log('Auto-connected with accounts:', accounts)
+```ts
+import { initWaaPSquid, useWaapAuth, WAAP_EVENTS } from '@human.tech/waap-sdk'
 
-  if (accounts.length === 0) {
-    await window.waap.login()
-  }
-} catch (error) {
-  console.log('Auto-connect failed, user needs to login again')
-}
+const waap = initWaaPSquid({ environment: 'production' })
+await waap.ethereum.login()
+waap.auth.on(WAAP_EVENTS.squidReady, ({ evm, sui, solana }) => {
+  console.log(evm, sui, solana)
+})
+// In React: const auth = useWaapAuth(waap.auth); auth.squidReady
+waap.destroy()
 ```
 
-#### Logout and Cleanup
+`login()` is safe to call on startup: it first checks the existing WaaP iframe
+session without showing wallet UI. The login screen opens only when there is
+no valid session.
 
-When you call `logout()`, the stored login method is automatically cleared:
+## Advanced integration
 
-```javascript
-// WaaP
-await window.waap.logout()
-console.log(window.waap.getLoginMethod()) // Returns null
-```
+### SDK session protection
 
-## Error Handling
+The wallet iframe uses DPoP by default. It keeps the Better Auth bearer and
+non-extractable proof key inside the wallet-origin iframe, scoped to the
+observed host origin. Use the explicit bearer fallback only where browser
+WebCrypto or IndexedDB cannot support DPoP:
 
-```javascript
-// WaaP
-try {
-  const accounts = await window.waap.request({ method: 'eth_requestAccounts' })
-} catch (error) {
-  console.error('Error connecting:', error)
-}
+```ts
+const waap = initWaaP({ sessionProtection: 'bearer' })
 ```
 
-## Events
-
-Both providers emit the same events you can listen to:
-
-```javascript
-// WaaP
-window.waap.on('connect', () => {
-  console.log('Connected')
+The host dapp never receives either credential. `legacy` is not a supported
+session-protection mode.
+
+Permission-token requests are available on EVM, Sui, and Solana facades.
+Request a token first, then opt into its use through `withPT: true` on a
+transaction call. This applies consistently to TAP and Squid transaction,
+sign-and-send, and sign-only transaction methods. The wallet resolves only a
+stored token matching the requesting origin, chain, wallet mode, and selected
+signer; otherwise the transaction follows the ordinary approval / 2FA flow.
+`withPT` never applies to personal-message or typed-data signing, and it is
+not a browser-side authorization bypass.
+
+For EVM background transaction status, use `useWaapTransaction(provider,
+callbacks)`. The old one-argument hook form remains supported, but depends on
+the global provider and is unsuitable for multiple wallets.
+
+Runtime event names are exported as `WAAP_EVENTS`: `waap_squid_pending`,
+`waap_squid_ready`, and `waap_squid_failed`. `squidReady` is the React-hook
+readiness field.
+
+## Completion and lifecycle
+
+The SDK bridge does not make every chain method mean the same thing:
+
+- EVM message and sign-only methods resolve with a signature. With `asyncTxs`,
+  `eth_sendTransaction` resolves with a transaction hash and later lifecycle
+  events report pending/confirmed/failed status.
+- Sui `signTransaction` returns signed bytes. `signAndExecuteTransaction`
+  returns a submitted digest; applications that require finality must query the
+  chain independently.
+- Solana `signTransaction` returns signed bytes and `signAndSendTransaction`
+  returns the cluster signature. A caller-built transaction retains its exact
+  blockhash and can expire during a human approval.
+
+Own and destroy the initializer at the same lifetime as the embedding UI. For
+advanced layout control, `initWaaP({ deferIframe: true })` delays iframe mount
+until the first request; adding `<waap-wallet>` before initialization uses
+component rather than modal presentation.
+
+### Startup performance
+
+The public iframe URL and `postMessage` protocol are stable: an already
+released SDK continues to use `/iframe` without any host-app change. Current
+SDK versions wait for the iframe's real navigation before posting their ready
+ping, then use a bounded retry handshake. This avoids posting to the transient
+`about:blank` document, which can otherwise produce target-origin warnings.
+
+Initialize a facade once for the lifetime of the embedding UI; do not create
+and destroy it for each Connect or Sign click. For a page where wallet
+interaction is not above the fold, defer mounting and warm it after the host
+page's LCP. `preload()` mounts the iframe and completes its non-interactive
+setup; it never opens wallet UI or creates a Squid account.
+
+```ts
+import { initWaaP, preloadWaaPOnIdle } from '@human.tech/waap-sdk'
+
+// Omitted chains retain the original EVM EIP-1193 provider behavior.
+const ethereum = initWaaP({ deferIframe: true })
+
+// Select one or more native Wallet Standard facades through the same TAP API.
+const { sui: suiWallet } = initWaaP({ chains: ['sui'] })
+const { solana: solanaWallet } = initWaaP({ chains: ['solana'] })
+
+// Call after LCP / from a post-LCP effect. The returned fn cancels warmup when
+// the owning route unmounts.
+const cancelPreload = preloadWaaPOnIdle(ethereum)
+
+// Upgrade likely user intent to an immediate warmup. `preload()` is shared and
+// idempotent, so this is safe if the idle callback is already pending.
+connectButton.addEventListener('pointerenter', () => void ethereum.preload(), {
+  once: true
 })
-
-window.waap.on('accountsChanged', (accounts) => {
-  console.log('Active account changed:', accounts[0])
-})
-
-window.waap.on('chainChanged', (chainId) => {
-  console.log('Chain changed to:', chainId)
+connectButton.addEventListener('focus', () => void ethereum.preload(), {
+  once: true
 })
-```
-
-## TypeScript Support
-
-The SDK includes TypeScript definitions. You can import them like this:
 
-```typescript
-// WaaP
-import { initWaaP, WaaPProvider } from '@silk-wallet/silk-wallet-sdk'
-
-const waap: WaaPProvider = initWaaP()
+// UI teardown:
+cancelPreload()
+ethereum.destroy()
 ```
 
-## Support
-
-If you encounter any issues or have questions, please reach out to our support team or file an issue in our GitHub repository.
+The EVM, Sui, Solana, and Squid facades expose the same `preload()` method.
+Squid coalesces their shared setup into one iframe request. For troubleshooting
+an embed, `getWaaPIframeDiagnostics()` reports navigation, visual render, and
+modal timings without exposing request payloads. `subscribeWaaPIframeLifecycle`
+can feed partner telemetry with `modal_requested`, `modal_visible`, and
+`modal_hidden` events. The EVM provider's
+`walletMessageManager.getHandshakeDiagnostics()` additionally reports ready-ping
+retries and the last readiness error.
+
+The SDK intentionally does not expose CLI-only account conversion, portable
+signed-artifact/broadcast workflows, raw-digest signing, policy administration,
+or headless automation. See
+[the capability matrix](../../wiki/architecture/client-capabilities.md) for the supported
+surface and test tiers.

package/dist/WaaPError-C5nPcaKk.d.mts

@@ -0,0 +1,168 @@
+import { A as SILK_METHOD, E as SilkResponse, T as SilkRequestCancellation, j as SilkNotificationData, w as SilkRequest } from "./types-DexmJNke.mjs";
+//#region src/lib/WalletMessageManager.d.ts
+type PostSilkRequestArgs = {
+  method: keyof typeof SILK_METHOD;
+  params: any[];
+  interactionRequired: boolean;
+  silkOptions?: {
+    async?: boolean;
+  };
+};
+/**
+ * Async transaction notification from iframe
+ */
+interface AsyncTxNotification {
+  type: string;
+  payload: any;
+}
+/**
+ * Squid lifecycle notification from iframe
+ */
+interface SquidLifecycleNotification {
+  type: string;
+  payload: any;
+}
+/**
+ * Listener interface for WalletMessageManager
+ */
+interface MessageListenerConfig {
+  handleResponse: (response: SilkResponse) => void;
+  handleRequest: (request: SilkRequest) => void;
+  onReceiveConnectNotif?: () => void;
+  onAccountChanged?: (newAccount: string) => void;
+  onAsyncTxNotification?: (notification: AsyncTxNotification) => void;
+  onSquidLifecycleNotification?: (notification: SquidLifecycleNotification) => void;
+}
+type WalletHandshakeDiagnostics = {
+  walletOrigin: string;
+  iframeNavigationStartedAt: number | null;
+  iframeLoadedAt: number | null;
+  readyPingStartedAt: number | null;
+  readyAt: number | null;
+  readyAttempts: number;
+  visualReadySupported: boolean | null;
+  navigationGeneration: number | null;
+  lastError: string | null;
+};
+declare class WalletMessageManager {
+  private iframeWindow;
+  private unregisterListeners;
+  private readonly terminalResponseDeduper;
+  private unsubscribeIframeNavigation;
+  private disposed;
+  /** Public so the shared window-listener dispatcher can origin-filter per manager. */
+  readonly walletOrigin: string;
+  constructor(iframeWindow: Window | null, walletOrigin?: string | boolean);
+  private observeIframeNavigation;
+  /**
+   * Rebind the target iframe window. Used by `deferIframe` mode, where the
+   * iframe is created on first use rather than at init, so the manager starts
+   * with a null window and is pointed at the real one once it exists.
+   */
+  setIframeWindow(iframeWindow: Window): void;
+  getIframeWindow(): Window | null;
+  isDisposed(): boolean;
+  shouldHandleTerminalResponse(id: string): boolean;
+  getHandshakeDiagnostics(): WalletHandshakeDiagnostics;
+  /**
+   * Post a Silk notification to the given iframeWindow
+   */
+  postSilkNotification(data: SilkNotificationData | SilkRequestCancellation): void;
+  postReadyNotification(): void;
+  postConnectNotification(): void;
+  /** Tell the iframe to drop a request the SDK has already abandoned locally. */
+  cancelSilkRequest(requestId: string, method: string): void;
+  /**
+   * Post a 'ready' notification to the iframe, and wait
+   * for the iframe to respond with a 'ready' notification.
+   */
+  pingIframe(): Promise<void>;
+  /**
+   * Post a SilkRequest to the iframeWindow. Don't wait for a response.
+   */
+  postSilkRequest(req: PostSilkRequestArgs): Promise<string>;
+  /**
+   * Register this manager's callbacks with the shared window `message`
+   * listener (top frame). All managers share ONE global listener; each is
+   * still origin-filtered and id-routed independently. Returns an unregister
+   * function.
+   * @param config - Configuration that includes callbacks for handling specific messages.
+   */
+  addListener(config: MessageListenerConfig): () => void;
+  dispose(): void;
+}
+//#endregion
+//#region src/lib/WalletModalController.d.ts
+type WaaPIframeLifecyclePhase = 'modal_requested' | 'modal_visible' | 'modal_hidden' | 'modal_cancelled';
+type WaaPIframeLifecycleEvent = {
+  phase: WaaPIframeLifecyclePhase;
+  at: number;
+  visualRevision: number;
+  fallback?: boolean;
+};
+type WaaPIframeDiagnostics = {
+  walletOrigin: string | null;
+  iframeNavigationStartedAt: number | null;
+  iframeLoadedAt: number | null;
+  visualRevision: number;
+  visualReadyAt: number | null;
+  modalPhase: 'idle' | 'pending' | 'visible' | 'hidden';
+  modalRequestedAt: number | null;
+  modalVisibleAt: number | null;
+  usedVisualFallback: boolean;
+  /** Redacted request-readiness timing, when an SDK facade has mounted. */
+  handshake: WalletHandshakeDiagnostics | null;
+};
+/** Subscribe to presentation-only iframe lifecycle timing events. */
+declare const subscribeWaaPIframeLifecycle: (listener: (event: WaaPIframeLifecycleEvent) => void) => (() => void);
+/**
+ * Snapshot startup and presentation timings without exposing message payloads,
+ * account data, or signing material. Useful for partner telemetry and support.
+ */
+declare const getWaaPIframeDiagnostics: () => WaaPIframeDiagnostics;
+//#endregion
+//#region src/lib/preload.d.ts
+/** Any public WaaP facade that can warm the shared wallet iframe. */
+interface WaaPPreloadTarget {
+  preload(): Promise<void>;
+}
+interface WaaPIdlePreloadOptions {
+  /** Browser deadline for an idle callback. Default: 2 seconds. */
+  timeoutMs?: number;
+  /** Observes a best-effort warmup failure without making page startup fail. */
+  onError?: (error: unknown) => void;
+}
+type CancelWaaPPreload = () => void;
+/**
+ * Warm an already-created WaaP facade when the browser is idle. It never opens
+ * wallet UI, and cancellation is useful when the embedding route unmounts.
+ *
+ * Use this after the host page's LCP. For a likely immediate action (for
+ * example Connect button hover/focus), call `target.preload()` directly.
+ */
+declare const preloadWaaPOnIdle: (target: WaaPPreloadTarget, options?: WaaPIdlePreloadOptions) => CancelWaaPPreload;
+//#endregion
+//#region src/lib/WaaPError.d.ts
+/** Stable, safe error vocabulary for non-EIP-1193 SDK facades. */
+type WaaPErrorCode = 'cancelled' | 'timeout' | 'user_rejected' | 'policy_rejected' | 'not_authenticated' | 'not_connected' | 'unsupported_input' | 'wallet_error' | 'unknown';
+type WaaPOperationMetadata = {
+  /**
+   * The chain the failed operation targeted. Declared structurally rather than
+   * as `WaaPChain` so the error vocabulary stays free of the initializer graph.
+   */
+  chain?: 'evm' | 'sui' | 'solana';
+  method?: string;
+  requestId?: string;
+};
+declare class WaaPError extends Error {
+  readonly code: WaaPErrorCode;
+  readonly operation?: WaaPOperationMetadata;
+  readonly cause?: unknown;
+  constructor(code: WaaPErrorCode, message: string, options?: {
+    cause?: unknown;
+    operation?: WaaPOperationMetadata;
+  });
+}
+declare function normalizeWaaPError(error: unknown, operation?: WaaPOperationMetadata): WaaPError;
+//#endregion
+export { CancelWaaPPreload as a, preloadWaaPOnIdle as c, WaaPIframeLifecyclePhase as d, getWaaPIframeDiagnostics as f, WalletMessageManager as h, normalizeWaaPError as i, WaaPIframeDiagnostics as l, PostSilkRequestArgs as m, WaaPErrorCode as n, WaaPIdlePreloadOptions as o, subscribeWaaPIframeLifecycle as p, WaaPOperationMetadata as r, WaaPPreloadTarget as s, WaaPError as t, WaaPIframeLifecycleEvent as u };