@bluxcc/core 0.3.1 → 0.3.3

package/README.md

@@ -6,27 +6,27 @@ Blux Core is a JavaScript/TypeScript SDK for adding authentication, Stellar wall
 
 ## Useful Links
 
-* **Website:** [blux.cc](https://blux.cc/)
-* **Documentation:** [docs.blux.cc](https://docs.blux.cc/)
-* **Live Demo:** [demo.blux.cc](https://demo.blux.cc/)
-* **Dashboard:** [dashboard.blux.cc](https://dashboard.blux.cc/)
+- **Website:** [blux.cc](https://blux.cc/)
+- **Documentation:** [docs.blux.cc](https://docs.blux.cc/)
+- **Live Demo:** [demo.blux.cc](https://demo.blux.cc/)
+- **Dashboard:** [dashboard.blux.cc](https://dashboard.blux.cc/)
 
 ## Features
 
-* **Framework-Agnostic**: Use Blux Core with vanilla JavaScript, TypeScript, or any frontend framework.
-* **Multi-Wallet Support**: Integrate Stellar wallets such as **Rabet, xBull, LOBSTR, Freighter, Albedo, HOT Wallet, Hana, and more**.
-* **Email, Passkey & Social Authentication**: Onboard users without requiring them to install or manage a traditional wallet.
-* **Transaction Signing**: Connect wallets and request transaction signatures through a consistent interface.
-* **Soroban Support**: Add Stellar smart contract interactions to your application.
-* **Customizable UI**: Adjust themes, fonts, backgrounds, logos, border radius, text colors, and other interface elements.
-* **Wallet Configuration**: Include or exclude individual wallets and control their display order.
-* **Configurable Networks**: Choose the Stellar networks supported by your application and set a default network.
-* **Custom Explorer**: Configure the block explorer used for account and transaction links.
-* **Localization**: Provide the authentication experience in multiple supported languages.
-* **User Management & Analytics**: Review authentication methods, login activity, timestamps, and associated wallet addresses through the Blux dashboard.
-* **Testing Tools**: Use predefined test accounts and reusable OTP credentials in configured testing environments.
-* **Multiple Projects**: Create and manage multiple applications from a single Blux account.
-* **Future-Proof**: More wallets and authentication methods will be added based on community feedback.
+- **Framework-Agnostic**: Use Blux Core with vanilla JavaScript, TypeScript, or any frontend framework.
+- **Multi-Wallet Support**: Integrate Stellar wallets such as **Rabet, xBull, LOBSTR, Freighter, Albedo, HOT Wallet, Hana, and more**.
+- **Email, Passkey & Social Authentication**: Onboard users without requiring them to install or manage a traditional wallet.
+- **Transaction Signing**: Connect wallets and request transaction signatures through a consistent interface.
+- **Soroban Support**: Add Stellar smart contract interactions to your application.
+- **Customizable UI**: Adjust themes, fonts, backgrounds, logos, border radius, text colors, and other interface elements.
+- **Wallet Configuration**: Include or exclude individual wallets and control their display order.
+- **Configurable Networks**: Choose the Stellar networks supported by your application and set a default network.
+- **Custom Explorer**: Configure the block explorer used for account and transaction links.
+- **Localization**: Provide the authentication experience in multiple supported languages.
+- **User Management & Analytics**: Review authentication methods, login activity, timestamps, and associated wallet addresses through the Blux dashboard.
+- **Testing Tools**: Use predefined test accounts and reusable OTP credentials in configured testing environments.
+- **Multiple Projects**: Create and manage multiple applications from a single Blux account.
+- **Future-Proof**: More wallets and authentication methods will be added based on community feedback.
 
 ## Installation
 
@@ -77,24 +77,73 @@ document.getElementById('loginBtn').onclick = async () => {
 
 Create a project through the [Blux Dashboard](https://dashboard.blux.cc/) to obtain your application ID. You can create and manage multiple projects from the same account.
 
+### Social Login
+
+Add any supported provider to `loginMethods`. The first enabled social is
+shown on the login screen; the rest appear on **Other socials**.
+
+```tsx
+createConfig({
+  appName: 'My App',
+  appId: 'GET_FROM_BLUX_DASHBOARD',
+  networks: [core.networks.mainnet],
+  loginMethods: [
+    'wallet',
+    'google',
+    'apple',
+    'discord',
+    'telegram',
+    'meta',
+    'github',
+    'farcaster',
+    'tiktok',
+    'linkedin',
+    'twitch',
+    'kick',
+    'spotify',
+    'instagram',
+    'microsoft',
+    'gitlab',
+    'twitter',
+    'steam',
+    'email',
+    'passkey',
+  ],
+});
+```
+
+Each provider is shown only when requested in `loginMethods` and returned in
+the app's enabled `socials` by `/auth/validate`. Most providers open
+`/auth/social/{provider}/start` on the Blux API (for example,
+`/auth/social/meta/start` or `/auth/social/github/start`) and use the
+shared social-login success, retry, and cancellation flow. Telegram uses
+the on-page [Login Widget](https://core.telegram.org/widgets/login) instead
+of a popup, because the bot is bound to the site's domain; Mini Apps can
+complete login via WebApp init data when that is enabled for the project.
+
+The backend must support each provider and have the project's credentials
+and callbacks configured. Private keys, client secrets, and bot tokens never
+belong in this browser configuration. Token verification is the backend's
+responsibility; the SDK accepts only the resulting Blux session.
+
 ## Customization
 
 Developers can customize various UI elements:
 
-* **Themes & Fonts**
-* **Backgrounds, Logos**
-* **Border Radius & Text Colors**
-* **Authentication Limits** (Free tier supports 500-1000 accounts per auth method)
+- **Themes & Fonts**
+- **Backgrounds, Logos**
+- **Border Radius & Text Colors**
+- **Authentication Limits** (Free tier supports 500-1000 accounts per auth method)
 
 Developers can also configure:
 
-* Enabled authentication methods
-* Included and excluded wallets
-* Wallet display order
-* Supported networks
-* Default network
-* Block explorer
-* Interface language
+- Enabled authentication methods
+- Included and excluded wallets
+- Wallet display order
+- Supported networks
+- Default network
+- Block explorer
+- Interface language
 
 Configuration options can be set via the `BluxProvider` config or environment variables.
 
@@ -104,11 +153,11 @@ The Blux dashboard provides information about the users who have connected to yo
 
 Available information includes:
 
-* Authentication method
-* Login and connection timestamps
-* Associated wallet addresses, when available
-* Recent authentication activity
-* Individual user information
+- Authentication method
+- Login and connection timestamps
+- Associated wallet addresses, when available
+- Recent authentication activity
+- Individual user information
 
 This information can help developers understand how their applications are being used and troubleshoot authentication or wallet connection issues.
 
@@ -124,57 +173,60 @@ These credentials are intended only for the configured testing environment. Refe
 
 Currently supported connection methods:
 
-* [x] **Freighter**
-* [x] **Rabet**
-* [x] **WalletConnect**
-* [x] **HOT Wallet**
-* [x] **Hana**
-* [x] **xBull**
-* [x] **LOBSTR**
-* [x] **Ledger**
-* [x] **Albedo**
-* [x] **Klever Wallet**
-* [x] **Bitget Wallet**
-* [x] **OneKey**
-* [x] **CactusLink**
-* [x] **Fordefi**
-* [x] **Trezor**
-* [x] **Email**
-* [x] **Google**
-* [x] **Passkey**
+- [x] **Freighter**
+- [x] **Rabet**
+- [x] **WalletConnect**
+- [x] **HOT Wallet**
+- [x] **Hana**
+- [x] **xBull**
+- [x] **LOBSTR**
+- [x] **Ledger**
+- [x] **Albedo**
+- [x] **Klever Wallet**
+- [x] **Bitget Wallet**
+- [x] **OneKey**
+- [x] **CactusLink**
+- [x] **Fordefi**
+- [x] **Trezor**
+- [x] **Email**
+- [x] **Google**
+- [x] **Apple**
+- [x] **Discord**
+- [x] **Telegram**
+- [x] **Passkey**
 
 ## Supported Languages
 
 Currently supported languages:
 
-* [x] **English**
-* [x] **Spanish**
-* [x] **Portuguese**
-* [x] **French**
-* [x] **German**
-* [x] **Russian**
-* [x] **Chinese**
-* [x] **Japanese**
-* [x] **Korean**
+- [x] **English**
+- [x] **Spanish**
+- [x] **Portuguese**
+- [x] **French**
+- [x] **German**
+- [x] **Russian**
+- [x] **Chinese**
+- [x] **Japanese**
+- [x] **Korean**
 
 ## License & Usage Restrictions
 
-* **No Forking or Unauthorized Modifications**: Removing references to **Blux Team** or forking without attribution is strictly prohibited.
-* **Custom Licensing Available**: Contact us at [support@blux.cc](mailto:support@blux.cc) to discuss licensing options.
+- **No Forking or Unauthorized Modifications**: Removing references to **Blux Team** or forking without attribution is strictly prohibited.
+- **Custom Licensing Available**: Contact us at [support@blux.cc](mailto:support@blux.cc) to discuss licensing options.
 
 ## Support & Contact
 
 For support, licensing, custom SMS authentication, or other inquiries, reach out via:
 
-* **Email**: [support@blux.cc](mailto:support@blux.cc)
-* **X**: [@BluxOfficial](https://x.com/bluxofficial)
+- **Email**: [support@blux.cc](mailto:support@blux.cc)
+- **X**: [@BluxOfficial](https://x.com/bluxofficial)
 
 ## Roadmap & Future Plans
 
 Blux is evolving. Follow our updates on [X](https://x.com/BluxOfficial) for:
 
-* **Additional OAuth and Social Authentication Methods**
-* **More Wallet Integrations**
-* **Enhanced Developer Hooks**
-* **Expanded Soroban Support**
-* **Enhanced Customization, Analytics, and Security Features**
+- **Additional OAuth and Social Authentication Methods**
+- **More Wallet Integrations**
+- **Enhanced Developer Hooks**
+- **Expanded Soroban Support**
+- **Enhanced Customization, Analytics, and Security Features**

package/dist/assets/AdditionalSocialLogos.d.ts

@@ -0,0 +1,15 @@
+export declare const FarcasterLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const TikTokLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const LinkedInLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const TwitchLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const KickLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const SpotifyLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const InstagramLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const MicrosoftLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const GitLabLogo: () => import("react/jsx-runtime").JSX.Element;
+export declare const XLogo: ({ fill }: {
+    fill?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const SteamLogo: ({ fill }: {
+    fill?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/AppleLogo.d.ts

@@ -0,0 +1,3 @@
+export declare const AppleLogo: ({ fill }: {
+    fill?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/DiscordLogo.d.ts

@@ -0,0 +1 @@
+export declare const DiscordLogo: () => import("react/jsx-runtime").JSX.Element;

package/dist/assets/GitHubLogo.d.ts

@@ -0,0 +1,3 @@
+export declare const GitHubLogo: ({ fill }: {
+    fill?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/MetaLogo.d.ts

@@ -0,0 +1 @@
+export declare const MetaLogo: () => import("react/jsx-runtime").JSX.Element;

package/dist/assets/TelegramLogo.d.ts

@@ -0,0 +1 @@
+export declare const TelegramLogo: () => import("react/jsx-runtime").JSX.Element;

package/dist/components/SocialProviderIcon.d.ts

@@ -0,0 +1,5 @@
+declare const SocialProviderIcon: ({ provider, fill, }: {
+    provider: string;
+    fill?: string;
+}) => import("react/jsx-runtime").JSX.Element | null;
+export default SocialProviderIcon;

package/dist/constants/assets.d.ts

@@ -23,4 +23,13 @@ export declare const MAINNET_EURC: {
     assetBalance: string;
     assetType: string;
 };
-export declare const getSuggestedAssets: (networkPassphrase: string) => IAsset[];
+export declare const isPublicNetwork: (network: string) => boolean;
+export declare const isTestnetNetwork: (network: string) => boolean;
+/** Circle USDC for the active network. Testnet uses Circle's test issuer. */
+export declare const usdcForNetwork: (network: string) => IAsset;
+/**
+ * Curated logos are pubnet-only. Map a well-known testnet (or same-network)
+ * issuer to the pubnet issuer whose icon we should reuse.
+ */
+export declare const pubnetLogoIssuer: (assetCode: string, assetIssuer: string) => string | undefined;
+export declare const getSuggestedAssets: (network: string) => IAsset[];

package/dist/enums.d.ts

@@ -26,7 +26,8 @@ export declare enum StellarNetwork {
 export declare enum Route {
     ONBOARDING = "ONBOARDING",// View for selecting a wallet
     PASSKEY_ONBOARDING = "PASSKEY_ONBOARDING",
-    SOCIALS_ONBOARDING = "SOCIALS_ONBOARDING",// Social (OAuth) login popup flow
+    SOCIALS_ONBOARDING = "SOCIALS_ONBOARDING",// Social login waiting / widget / popup flow
+    OTHER_SOCIALS = "OTHER_SOCIALS",// Remaining social providers after the primary one
     WRONG_NETWORK = "WRONG_NETWORK",// View for selecting a wallet
     WAITING = "WAITING",// View for connection process
     SUCCESSFUL = "SUCCESSFUL",// View for connection success process

package/dist/exports/blux.d.ts

@@ -1,18 +1,7 @@
-import { IUser } from '../store';
-/**
- * Internal login driver. Prefer the public {@link login}.
- *
- * @param isSilent - When `true`, tries to restore a recent session without opening the modal.
- * @returns A promise that resolves to the authenticated user.
- */
-export declare const _login: (isSilent: boolean) => Promise<IUser>;
-/**
- * Opens the Blux modal so the user can connect a wallet or sign in, resolving
- * once authenticated. Waits for the SDK to finish initializing first.
- *
- * @returns The authenticated user.
- */
-export declare const login: () => Promise<IUser>;
+import { loginWallet } from './loginMethods';
+export { _login } from './loginMethods';
+export { login, loginEmail, loginOAuth, loginPasskey, loginSms, loginWallet, } from './loginMethods';
+export type { LoginCodeApi, LoginCodeFn, LoginOAuthOptions, } from './loginMethods';
 /**
  * Signs a transaction XDR with the connected wallet, without submitting it.
  *
@@ -59,7 +48,12 @@ export declare const signAuthEntry: (authEntry: string, options?: {
  * Each method carries its own documentation; the getters expose live auth state.
  */
 export declare const blux: {
-    login: () => Promise<IUser>;
+    login: () => Promise<import("../store").IUser>;
+    loginEmail: import("./loginMethods").LoginCodeFn;
+    loginSms: import("./loginMethods").LoginCodeFn;
+    loginOAuth: (provider: import("../types").ISocialProvider | string, options?: import("./loginMethods").LoginOAuthOptions) => Promise<import("../store").IUser>;
+    loginPasskey: () => Promise<import("../store").IUser>;
+    loginWallet: typeof loginWallet;
     logout: () => void;
     fundMe: () => void;
     profile: () => void;
@@ -79,5 +73,5 @@ export declare const blux: {
     /** Whether a user is currently authenticated. */
     readonly isAuthenticated: boolean;
     /** The currently authenticated user, or `undefined` when logged out. */
-    readonly user: IUser | undefined;
+    readonly user: import("../store").IUser | undefined;
 };

package/dist/exports/exportedStore.d.ts

@@ -8,6 +8,10 @@ export interface IExportedStore {
         isAuthenticated: boolean;
     };
     stellar?: IStellarConfig;
+    /** Installed wallets currently offered in the picker. */
+    wallets: Array<{
+        name: string;
+    }>;
 }
 export declare const exportedStore: import("zustand").StoreApi<IExportedStore>;
 export declare const syncExportedStore: (mainStore: typeof store) => () => void;

package/dist/exports/index.d.ts

@@ -2,11 +2,12 @@ import { BluxEventMap, ReadOnlyEmitter } from '../utils/events';
 export type { IAppearance, IConfig, IExplorer, ILoginMethods, IServers, ISocialProvider, ITrezorMetaData, ITransports, IWalletConnectMetaData, IWalletNames, LanguageKey, } from '../types';
 export type { IUser } from '../store';
 export type { IExportedStore } from './exportedStore';
+export type { LoginCodeApi, LoginCodeFn, LoginOAuthOptions } from './blux';
 export { Asset } from '@stellar/stellar-sdk';
 export * as StellarSdk from '@stellar/stellar-sdk';
 export * from './core';
 export * as core from './core';
-export { blux } from './blux';
+export { blux, loginEmail, loginSms, loginOAuth, loginPasskey, loginWallet, } from './blux';
 export { BluxEvent } from '../utils/events';
 export { getState, subscribe, getInitialState, useExportedStore, } from './exportedStore';
 export declare const setAppearance: (newAppearance: Partial<import("../types").IAppearance>) => void;

package/dist/exports/loginMethods.d.ts

@@ -0,0 +1,93 @@
+import { ISocialProvider } from '../types';
+import { IUser } from '../store';
+/** sendCode + loginWithCode pair returned by {@link loginEmail} / {@link loginSms}. */
+export type LoginCodeApi = {
+    /** Send a one-time code to the identifier (email address or phone number). */
+    sendCode: (identifier: string) => Promise<void>;
+    /**
+     * Verify the one-time code and complete login.
+     *
+     * @returns The authenticated user.
+     */
+    loginWithCode: (identifier: string, code: string) => Promise<IUser>;
+};
+/** {@link loginEmail} / {@link loginSms}: call it for the hook-shaped pair, or use the methods directly. */
+export type LoginCodeFn = (() => LoginCodeApi) & LoginCodeApi;
+/**
+ * Internal login driver. Prefer the public {@link login}.
+ *
+ * @param isSilent - When `true`, tries to restore a recent session without opening the modal.
+ * @returns A promise that resolves to the authenticated user.
+ */
+export declare const _login: (isSilent: boolean) => Promise<IUser>;
+/**
+ * Opens the Blux modal so the user can connect a wallet or sign in, resolving
+ * once authenticated. Waits for the SDK to finish initializing first.
+ *
+ * @returns The authenticated user.
+ */
+export declare const login: () => Promise<IUser>;
+/**
+ * Headless email login. Mirrors Privy's `sendCode` + `loginWithCode` so a React
+ * hook can wrap this directly:
+ *
+ * ```ts
+ * const { sendCode, loginWithCode } = blux.loginEmail();
+ * await sendCode('user@example.com');
+ * const user = await loginWithCode('user@example.com', '123456');
+ * ```
+ *
+ * `blux.loginEmail.sendCode(...)` works the same way without calling the function.
+ * Does not open the Blux modal; render your own email / OTP UI.
+ */
+export declare const loginEmail: LoginCodeFn;
+/**
+ * Headless SMS login. Same shape as {@link loginEmail}:
+ *
+ * ```ts
+ * const { sendCode, loginWithCode } = blux.loginSms();
+ * await sendCode('+15555555555');
+ * const user = await loginWithCode('+15555555555', '123456');
+ * ```
+ *
+ * Does not open the Blux modal. SMS must be in `loginMethods` and the app must
+ * be on a paid plan (`smsEnabled` from `/auth/validate`).
+ */
+export declare const loginSms: LoginCodeFn;
+export type LoginOAuthOptions = {
+    /**
+     * Telegram Login Widget user object, or `{ init_data }` from a Telegram Mini
+     * App. Required for Telegram unless Mini App init data is already on `window`.
+     */
+    telegramUser?: Record<string, unknown>;
+};
+/**
+ * Headless social login. Opens the provider popup (must run from a click
+ * handler so the browser does not block it) and resolves with the user.
+ *
+ * Telegram cannot use that popup (the bot is bound to this origin). Pass the
+ * widget payload as `options.telegramUser`, or call this from a Mini App where
+ * init data is present. To show Blux's Telegram widget instead, use {@link login}.
+ *
+ * @param provider - A social name from {@link ISocialProvider} (`'google'`, `'apple'`, ...).
+ * @param options - Telegram-only extras.
+ */
+export declare const loginOAuth: (provider: ISocialProvider | string, options?: LoginOAuthOptions) => Promise<IUser>;
+/**
+ * Headless passkey login. Triggers the WebAuthn ceremony (register on first
+ * visit, assert on later visits) and resolves with the user. Must run from a
+ * user gesture. Does not open the Blux modal.
+ */
+export declare const loginPasskey: () => Promise<IUser>;
+/**
+ * Wallet login.
+ *
+ * - No argument: opens the Blux onboarding modal showing only the scrollable
+ *   wallet list (email / SMS / social / passkey rows are hidden).
+ * - With a wallet name (`'freighter'`, `'rabet'`, ...): opens that wallet's
+ *   own prompt and never the Blux modal. WalletConnect is the exception and
+ *   still uses the Blux QR screen.
+ *
+ * @returns The authenticated user.
+ */
+export declare function loginWallet(walletName?: string): Promise<IUser>;