decane-connect-kit 2.29.3 → 2.31.0

package/dist/index.d.cts

@@ -94,11 +94,8 @@ interface DecaneConnectConfig {
     chains: Chain[];
     authMethods: Array<'google' | 'email' | 'phone' | 'kingschat' | 'x'>;
     /**
-     * Scopes requested from KingsChat at sign-in. Defaults to
-     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
-     * enough to establish identity. Widen only if the app actually calls
-     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
-     * so asking for more than you use costs conversions.
+     * @deprecated Ignored since 2.31.0. KingsChat scopes are now set on the
+     * KingsChat project in its developer portal, not per login request.
      */
     kingsChatScopes?: string[];
     apiBaseUrl?: string;
@@ -431,6 +428,31 @@ interface DecaneConnect {
     connectWithToken(token: string, opts?: {
         providerId?: string;
     }): Promise<ConnectResult>;
+    /**
+     * Attach a login from your own auth system to the account that is signed in
+     * now, so that login opens this same wallet from then on. The usual case:
+     * someone signed up by email adds a phone number your backend verified, and
+     * can then sign in with either. Needs a signed-in session.
+     *
+     * The token must be fresh (it carries `exp` and `iat`, and was issued in the
+     * last ten minutes). A login that already opens a different account throws
+     * LoginInUseError: accounts are never merged. Linking one that is already
+     * on this account is a no-op (`alreadyLinked: true`). Since 2.30.0.
+     */
+    linkWithToken(token: string, opts?: {
+        providerId?: string;
+    }): Promise<{
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    /** The logins linked to the signed-in account with linkWithToken(). Since 2.30.0. */
+    listLinkedLogins(): Promise<LinkedLogin[]>;
+    /**
+     * Remove a linked login, for "change my number": sign in, unlink the old one,
+     * link the new one. The login the account was created with cannot be removed.
+     * Since 2.30.0.
+     */
+    unlinkLogin(id: string): Promise<void>;
     /**
      * Adopt a Decane access token another app of the same project handed over
      * (in a URL, say): signed in at once, unlocked on the first signature.
@@ -700,6 +722,16 @@ interface AuthResult {
      */
     providerSubject?: string;
 }
+/** A login attached to an account with linkWithToken(). */
+interface LinkedLogin {
+    id: string;
+    providerId: string | null;
+    /** The provider's name as set in the dashboard, e.g. "World Street phone". */
+    providerName: string | null;
+    /** Masked, for display: never the full identifier. */
+    identifier: string | null;
+    linkedAt: string;
+}
 
 declare class ApiClient {
     private readonly baseUrl;
@@ -730,9 +762,14 @@ declare class ApiClient {
         authorizationUrl: string;
     }>;
     /**
-     * Exchange a KingsChat access token for a Decane session. The backend spends
-     * the token against KingsChat's own API to establish the identity — it is
-     * never trusted on its face, and never stored.
+     * Exchange a KingsChat authorization code for a Decane session. The backend
+     * trades it with KingsChat for an access token, verifies that token (it must
+     * have been issued to this project's KingsChat app), and never stores it.
+     */
+    authKingsChatCode(code: string): Promise<AuthResult>;
+    /**
+     * Exchange a KingsChat access token the app already holds for a Decane
+     * session. Verified the same way as a code's token, and never stored.
      */
     authKingsChat(accessToken: string): Promise<AuthResult>;
     authEmailStart(email: string): Promise<void>;
@@ -782,6 +819,16 @@ declare class ApiClient {
      * provider configured.
      */
     authExternal(token: string, providerId?: string): Promise<AuthResult>;
+    /** Attach a login from the project's own provider to the signed-in account. */
+    linkExternal(jwt: string, token: string, providerId?: string): Promise<{
+        linked: true;
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    listLinkedLogins(jwt: string): Promise<{
+        logins: LinkedLogin[];
+    }>;
+    unlinkLogin(jwt: string, id: string): Promise<void>;
     /**
      * Returns null when this user has no server-registered passkey, which is the
      * expected answer for wallets created before passkey sign-in existed or for
@@ -944,8 +991,8 @@ interface SocialConfig {
     apiKey: string;
     authMethods?: ("google" | "email" | "phone" | "kingschat" | "x")[];
     /**
-     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
-     * is what KingsChat's own SDK asks for and is enough to establish identity.
+     * @deprecated Ignored since 2.31.0. KingsChat scopes are now set on the
+     * KingsChat project in its developer portal, not per login request.
      */
     kingsChatScopes?: string[];
     promptPin?: () => Promise<string>;
@@ -1149,19 +1196,18 @@ declare function startEmailAuth(api: ApiClient, email: string): Promise<void>;
  */
 declare function verifyEmailCode(api: ApiClient, email: string, code: string): Promise<AuthResult>;
 
+/** @deprecated KingsChat no longer issues tokens to a popup. */
 interface KingsChatTokens {
     accessToken: string;
     refreshToken?: string;
     expiresInMillis?: number;
 }
 /**
- * Open the KingsChat consent popup and resolve with the tokens it returns.
- *
- * Must be called synchronously from a user gesture (a click handler) — popup
- * blockers reject a window.open that happens after an await, which is why the
- * clientId is fetched by the caller *before* this runs.
+ * @deprecated Since 2.31.0. KingsChat retired the popup login; use
+ * `connectWithKingsChat()`, which redirects to KingsChat and finishes on the
+ * page registered as the KingsChat application's Redirect URL.
  */
-declare function loginWithKingsChatPopup(opts: {
+declare function loginWithKingsChatPopup(_opts?: {
     clientId: string;
     scopes?: string[];
     timeoutMs?: number;
@@ -1292,6 +1338,14 @@ declare class ExportNotAuthorizedError extends DecaneConnectError {
  * The client discards what it generated and provisions instead; nothing for
  * the caller to do, which is why this never reaches them.
  */
+/**
+ * linkWithToken(): that login already opens a different account (someone signed
+ * up with that phone number on its own, say). Decane never merges two accounts,
+ * because each is its own key and its own addresses, so it was not linked.
+ */
+declare class LoginInUseError extends DecaneConnectError {
+    constructor(message?: string);
+}
 declare class WalletExistsError extends DecaneConnectError {
     constructor();
 }
@@ -1597,6 +1651,14 @@ declare function useSocialAuth(): {
         providerId?: string;
     }) => Promise<void>;
     signInWithAccessToken: (token: string) => Promise<void>;
+    linkWithToken: (token: string, opts?: {
+        providerId?: string;
+    }) => Promise<{
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    listLinkedLogins: () => Promise<LinkedLogin[]>;
+    unlinkLogin: (id: string) => Promise<void>;
     signInWithCustomAuth: (() => Promise<void>) | undefined;
     signInWithPasskey: () => Promise<void>;
     unlock: () => Promise<void>;
@@ -1772,4 +1834,4 @@ declare class WeakPasswordError extends Error {
  */
 declare function validateUnlockPassword(password: string): void;
 
-export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletEnrolmentError, WalletExistsError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, type LinkedLogin, LoginInUseError, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletEnrolmentError, WalletExistsError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };

package/dist/index.d.ts

@@ -94,11 +94,8 @@ interface DecaneConnectConfig {
     chains: Chain[];
     authMethods: Array<'google' | 'email' | 'phone' | 'kingschat' | 'x'>;
     /**
-     * Scopes requested from KingsChat at sign-in. Defaults to
-     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
-     * enough to establish identity. Widen only if the app actually calls
-     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
-     * so asking for more than you use costs conversions.
+     * @deprecated Ignored since 2.31.0. KingsChat scopes are now set on the
+     * KingsChat project in its developer portal, not per login request.
      */
     kingsChatScopes?: string[];
     apiBaseUrl?: string;
@@ -431,6 +428,31 @@ interface DecaneConnect {
     connectWithToken(token: string, opts?: {
         providerId?: string;
     }): Promise<ConnectResult>;
+    /**
+     * Attach a login from your own auth system to the account that is signed in
+     * now, so that login opens this same wallet from then on. The usual case:
+     * someone signed up by email adds a phone number your backend verified, and
+     * can then sign in with either. Needs a signed-in session.
+     *
+     * The token must be fresh (it carries `exp` and `iat`, and was issued in the
+     * last ten minutes). A login that already opens a different account throws
+     * LoginInUseError: accounts are never merged. Linking one that is already
+     * on this account is a no-op (`alreadyLinked: true`). Since 2.30.0.
+     */
+    linkWithToken(token: string, opts?: {
+        providerId?: string;
+    }): Promise<{
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    /** The logins linked to the signed-in account with linkWithToken(). Since 2.30.0. */
+    listLinkedLogins(): Promise<LinkedLogin[]>;
+    /**
+     * Remove a linked login, for "change my number": sign in, unlink the old one,
+     * link the new one. The login the account was created with cannot be removed.
+     * Since 2.30.0.
+     */
+    unlinkLogin(id: string): Promise<void>;
     /**
      * Adopt a Decane access token another app of the same project handed over
      * (in a URL, say): signed in at once, unlocked on the first signature.
@@ -700,6 +722,16 @@ interface AuthResult {
      */
     providerSubject?: string;
 }
+/** A login attached to an account with linkWithToken(). */
+interface LinkedLogin {
+    id: string;
+    providerId: string | null;
+    /** The provider's name as set in the dashboard, e.g. "World Street phone". */
+    providerName: string | null;
+    /** Masked, for display: never the full identifier. */
+    identifier: string | null;
+    linkedAt: string;
+}
 
 declare class ApiClient {
     private readonly baseUrl;
@@ -730,9 +762,14 @@ declare class ApiClient {
         authorizationUrl: string;
     }>;
     /**
-     * Exchange a KingsChat access token for a Decane session. The backend spends
-     * the token against KingsChat's own API to establish the identity — it is
-     * never trusted on its face, and never stored.
+     * Exchange a KingsChat authorization code for a Decane session. The backend
+     * trades it with KingsChat for an access token, verifies that token (it must
+     * have been issued to this project's KingsChat app), and never stores it.
+     */
+    authKingsChatCode(code: string): Promise<AuthResult>;
+    /**
+     * Exchange a KingsChat access token the app already holds for a Decane
+     * session. Verified the same way as a code's token, and never stored.
      */
     authKingsChat(accessToken: string): Promise<AuthResult>;
     authEmailStart(email: string): Promise<void>;
@@ -782,6 +819,16 @@ declare class ApiClient {
      * provider configured.
      */
     authExternal(token: string, providerId?: string): Promise<AuthResult>;
+    /** Attach a login from the project's own provider to the signed-in account. */
+    linkExternal(jwt: string, token: string, providerId?: string): Promise<{
+        linked: true;
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    listLinkedLogins(jwt: string): Promise<{
+        logins: LinkedLogin[];
+    }>;
+    unlinkLogin(jwt: string, id: string): Promise<void>;
     /**
      * Returns null when this user has no server-registered passkey, which is the
      * expected answer for wallets created before passkey sign-in existed or for
@@ -944,8 +991,8 @@ interface SocialConfig {
     apiKey: string;
     authMethods?: ("google" | "email" | "phone" | "kingschat" | "x")[];
     /**
-     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
-     * is what KingsChat's own SDK asks for and is enough to establish identity.
+     * @deprecated Ignored since 2.31.0. KingsChat scopes are now set on the
+     * KingsChat project in its developer portal, not per login request.
      */
     kingsChatScopes?: string[];
     promptPin?: () => Promise<string>;
@@ -1149,19 +1196,18 @@ declare function startEmailAuth(api: ApiClient, email: string): Promise<void>;
  */
 declare function verifyEmailCode(api: ApiClient, email: string, code: string): Promise<AuthResult>;
 
+/** @deprecated KingsChat no longer issues tokens to a popup. */
 interface KingsChatTokens {
     accessToken: string;
     refreshToken?: string;
     expiresInMillis?: number;
 }
 /**
- * Open the KingsChat consent popup and resolve with the tokens it returns.
- *
- * Must be called synchronously from a user gesture (a click handler) — popup
- * blockers reject a window.open that happens after an await, which is why the
- * clientId is fetched by the caller *before* this runs.
+ * @deprecated Since 2.31.0. KingsChat retired the popup login; use
+ * `connectWithKingsChat()`, which redirects to KingsChat and finishes on the
+ * page registered as the KingsChat application's Redirect URL.
  */
-declare function loginWithKingsChatPopup(opts: {
+declare function loginWithKingsChatPopup(_opts?: {
     clientId: string;
     scopes?: string[];
     timeoutMs?: number;
@@ -1292,6 +1338,14 @@ declare class ExportNotAuthorizedError extends DecaneConnectError {
  * The client discards what it generated and provisions instead; nothing for
  * the caller to do, which is why this never reaches them.
  */
+/**
+ * linkWithToken(): that login already opens a different account (someone signed
+ * up with that phone number on its own, say). Decane never merges two accounts,
+ * because each is its own key and its own addresses, so it was not linked.
+ */
+declare class LoginInUseError extends DecaneConnectError {
+    constructor(message?: string);
+}
 declare class WalletExistsError extends DecaneConnectError {
     constructor();
 }
@@ -1597,6 +1651,14 @@ declare function useSocialAuth(): {
         providerId?: string;
     }) => Promise<void>;
     signInWithAccessToken: (token: string) => Promise<void>;
+    linkWithToken: (token: string, opts?: {
+        providerId?: string;
+    }) => Promise<{
+        alreadyLinked: boolean;
+        id?: string;
+    }>;
+    listLinkedLogins: () => Promise<LinkedLogin[]>;
+    unlinkLogin: (id: string) => Promise<void>;
     signInWithCustomAuth: (() => Promise<void>) | undefined;
     signInWithPasskey: () => Promise<void>;
     unlock: () => Promise<void>;
@@ -1772,4 +1834,4 @@ declare class WeakPasswordError extends Error {
  */
 declare function validateUnlockPassword(password: string): void;
 
-export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletEnrolmentError, WalletExistsError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, type LinkedLogin, LoginInUseError, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletEnrolmentError, WalletExistsError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };