@bluxcc/core 0.2.18 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/README.md +130 -15
  2. package/dist/assets/index.d.ts +13 -0
  3. package/dist/components/CardItem/index.d.ts +3 -2
  4. package/dist/components/CardItem/variants/input.d.ts +3 -2
  5. package/dist/components/Modal/index.d.ts +3 -1
  6. package/dist/components/Provider.d.ts +2 -1
  7. package/dist/exports/blux.d.ts +4 -8
  8. package/dist/exports/core/helpers/account.d.ts +0 -8
  9. package/dist/exports/core/swap.d.ts +9 -0
  10. package/dist/exports/createConfig.d.ts +8 -1
  11. package/dist/exports/index.d.ts +4 -0
  12. package/dist/hooks/useTransactions.d.ts +5 -0
  13. package/dist/index.cjs.js +14 -14
  14. package/dist/index.esm.js +14 -14
  15. package/dist/stellar/getTransactionDetails.d.ts +1 -1
  16. package/dist/stellar/handleSignMessage.d.ts +1 -1
  17. package/dist/stellar/moneygram.d.ts +26 -0
  18. package/dist/stellar/paymentTransaction.d.ts +3 -3
  19. package/dist/stellar/processes/continueLoginProcess.d.ts +1 -0
  20. package/dist/store.d.ts +4 -4
  21. package/dist/tailwind.css.d.ts +2 -0
  22. package/dist/types.d.ts +26 -10
  23. package/dist/utils/api.d.ts +10 -5
  24. package/dist/utils/appValidity.d.ts +4 -3
  25. package/dist/utils/helpers.d.ts +4 -3
  26. package/dist/utils/networkRpc.d.ts +7 -0
  27. package/package.json +2 -2
package/README.md CHANGED
@@ -1,26 +1,44 @@
1
- # Blux Wallet Kit - The Missing Piece for Stellar dApps
1
+ # Blux Core: Authentication & Wallet Infrastructure for Stellar dApps
2
2
 
3
- ![image](https://blux.cc/bluxIntro.jpg)
3
+ ![Blux](https://blux.cc/bluxIntro.jpg)
4
4
 
5
- Blux is a **comprehensive authentication and wallet connect kit** designed for Stellar dApps.
6
- It simplifies onboarding by integrating multiple authentication methods, including **wallets, email, passkey, and socials**.
5
+ Blux Core is a JavaScript/TypeScript SDK for adding authentication, Stellar wallet connections, transaction signing, and Soroban interactions to web applications. Users can onboard through supported Stellar wallets, email, passkeys, and social login, while developers get a consistent API and customizable authentication experience.
6
+
7
+ ## Useful Links
8
+
9
+ * **Website:** [blux.cc](https://blux.cc/)
10
+ * **Documentation:** [docs.blux.cc](https://docs.blux.cc/)
11
+ * **Live Demo:** [demo.blux.cc](https://demo.blux.cc/)
12
+ * **Dashboard:** [dashboard.blux.cc](https://dashboard.blux.cc/)
7
13
 
8
14
  ## Features
9
15
 
10
- - **Multi-Wallet Support**: Easily integrate Stellar wallets such as **Rabet, xBull, Lobstr, Freighter, Albedo, Hot Wallet, Hana Wallet, and more**.
11
- - **Social Login** _(Coming Soon)_: Support for **Apple, Meta, Google, and more**.
12
- - **Email & Passkey** _(Coming Soon)_: Securely onboard users with non-crypto credentials.
13
- - **Customizable UI**: Adjust themes, fonts, backgrounds, logos, border radius, and text colors.
14
- - **Configurable Networks**: Set up and modify network preferences via API keys.
15
- - **Future-Proof**: More wallets and authentication methods will be added based on community feedback.
16
+ * **Framework-Agnostic**: Use Blux Core with vanilla JavaScript, TypeScript, or any frontend framework.
17
+ * **Multi-Wallet Support**: Integrate Stellar wallets such as **Rabet, xBull, LOBSTR, Freighter, Albedo, HOT Wallet, Hana, and more**.
18
+ * **Email, Passkey & Social Authentication**: Onboard users without requiring them to install or manage a traditional wallet.
19
+ * **Transaction Signing**: Connect wallets and request transaction signatures through a consistent interface.
20
+ * **Soroban Support**: Add Stellar smart contract interactions to your application.
21
+ * **Customizable UI**: Adjust themes, fonts, backgrounds, logos, border radius, text colors, and other interface elements.
22
+ * **Wallet Configuration**: Include or exclude individual wallets and control their display order.
23
+ * **Configurable Networks**: Choose the Stellar networks supported by your application and set a default network.
24
+ * **Custom Explorer**: Configure the block explorer used for account and transaction links.
25
+ * **Localization**: Provide the authentication experience in multiple supported languages.
26
+ * **User Management & Analytics**: Review authentication methods, login activity, timestamps, and associated wallet addresses through the Blux dashboard.
27
+ * **Testing Tools**: Use predefined test accounts and reusable OTP credentials in configured testing environments.
28
+ * **Multiple Projects**: Create and manage multiple applications from a single Blux account.
29
+ * **Future-Proof**: More wallets and authentication methods will be added based on community feedback.
16
30
 
17
31
  ## Installation
18
32
 
33
+ Install Blux Core through npm:
34
+
19
35
  ```sh
20
36
  npm i @bluxcc/core
21
37
  ```
22
38
 
23
- ## Usage
39
+ Blux Core can also be loaded directly in the browser through a CDN.
40
+
41
+ ## Browser Usage
24
42
 
25
43
  ```html
26
44
  <!DOCTYPE html>
@@ -41,6 +59,8 @@ npm i @bluxcc/core
41
59
  </script>
42
60
  ```
43
61
 
62
+ ## JavaScript and TypeScript Usage
63
+
44
64
  ```tsx
45
65
  import { blux, core, createConfig } from '@bluxcc/core';
46
66
 
@@ -55,11 +75,106 @@ document.getElementById('loginBtn').onclick = async () => {
55
75
  };
56
76
  ```
57
77
 
78
+ 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.
79
+
80
+ ## Customization
81
+
82
+ Developers can customize various UI elements:
83
+
84
+ * **Themes & Fonts**
85
+ * **Backgrounds, Logos**
86
+ * **Border Radius & Text Colors**
87
+ * **Authentication Limits** (Free tier supports 500-1000 accounts per auth method)
88
+
89
+ Developers can also configure:
90
+
91
+ * Enabled authentication methods
92
+ * Included and excluded wallets
93
+ * Wallet display order
94
+ * Supported networks
95
+ * Default network
96
+ * Block explorer
97
+ * Interface language
98
+
99
+ Configuration options can be set via the `BluxProvider` config or environment variables.
100
+
101
+ ## Dashboard & User Analytics
102
+
103
+ The Blux dashboard provides information about the users who have connected to your application.
104
+
105
+ Available information includes:
106
+
107
+ * Authentication method
108
+ * Login and connection timestamps
109
+ * Associated wallet addresses, when available
110
+ * Recent authentication activity
111
+ * Individual user information
112
+
113
+ This information can help developers understand how their applications are being used and troubleshoot authentication or wallet connection issues.
114
+
115
+ ## Development & Testing
116
+
117
+ Blux provides predefined accounts for development and quality assurance.
118
+
119
+ Developers can use preset email identities together with a reusable testing OTP. This makes it possible to test the complete login process repeatedly without waiting for real email delivery or using personal user information.
120
+
121
+ These credentials are intended only for the configured testing environment. Refer to the [Blux documentation](https://docs.blux.cc/) for the current testing credentials and setup instructions.
122
+
123
+ ## Supported Wallets
124
+
125
+ Currently supported connection methods:
126
+
127
+ * [x] **Freighter**
128
+ * [x] **Rabet**
129
+ * [x] **WalletConnect**
130
+ * [x] **HOT Wallet**
131
+ * [x] **Hana**
132
+ * [x] **xBull**
133
+ * [x] **LOBSTR**
134
+ * [x] **Ledger**
135
+ * [x] **Albedo**
136
+ * [x] **Klever Wallet**
137
+ * [x] **Bitget Wallet**
138
+ * [x] **OneKey**
139
+ * [x] **CactusLink**
140
+ * [x] **Fordefi**
141
+ * [x] **Trezor**
142
+ * [x] **Email**
143
+ * [x] **Google**
144
+ * [x] **Passkey**
145
+
146
+ ## Supported Languages
147
+
148
+ Currently supported languages:
149
+
150
+ * [x] **English**
151
+ * [x] **Spanish**
152
+ * [x] **Portuguese**
153
+ * [x] **French**
154
+ * [x] **German**
155
+ * [x] **Russian**
156
+ * [x] **Chinese**
157
+ * [x] **Japanese**
158
+ * [x] **Korean**
159
+
160
+ ## License & Usage Restrictions
161
+
162
+ * **No Forking or Unauthorized Modifications**: Removing references to **Blux Team** or forking without attribution is strictly prohibited.
163
+ * **Custom Licensing Available**: Contact us at [support@blux.cc](mailto:support@blux.cc) to discuss licensing options.
164
+
58
165
  ## Support & Contact
59
166
 
60
- For support, licensing, or inquiries, reach out via:
167
+ For support, licensing, custom SMS authentication, or other inquiries, reach out via:
168
+
169
+ * **Email**: [support@blux.cc](mailto:support@blux.cc)
170
+ * **X**: [@BluxOfficial](https://x.com/bluxofficial)
171
+
172
+ ## Roadmap & Future Plans
61
173
 
62
- - **Email**: [support@blux.cc](mailto:support@blux.cc)
63
- - **X (Twitter)**: [@BluxOfficial](https://twitter.com/BluxOfficial)
174
+ Blux is evolving. Follow our updates on [X](https://x.com/BluxOfficial) for:
64
175
 
65
- Follow for more updates at [X (Twitter)](https://twitter.com/BluxOfficial).
176
+ * **Additional OAuth and Social Authentication Methods**
177
+ * **More Wallet Integrations**
178
+ * **Enhanced Developer Hooks**
179
+ * **Expanded Soroban Support**
180
+ * **Enhanced Customization, Analytics, and Security Features**
package/dist/assets/index.d.ts CHANGED
@@ -1,3 +1,12 @@
1
+ export declare const CurrencyExchange: ({ fill }: {
2
+ fill?: string;
3
+ }) => import("react/jsx-runtime").JSX.Element;
4
+ export declare const BuyIcon: ({ fill }: {
5
+ fill?: string;
6
+ }) => import("react/jsx-runtime").JSX.Element;
7
+ export declare const SellIcon: ({ fill }: {
8
+ fill?: string;
9
+ }) => import("react/jsx-runtime").JSX.Element;
1
10
  export declare const ArrowOutward: ({ fill }: {
2
11
  fill?: string;
3
12
  }) => import("react/jsx-runtime").JSX.Element;
@@ -15,5 +24,9 @@ export declare const FordefiLogo: () => import("react/jsx-runtime").JSX.Element;
15
24
  export declare const TrezorLogo: ({ fill }: {
16
25
  fill?: string;
17
26
  }) => import("react/jsx-runtime").JSX.Element;
27
+ export declare const MoneyGramLogo: () => import("react/jsx-runtime").JSX.Element;
18
28
  export declare const MoonPayLogo: () => import("react/jsx-runtime").JSX.Element;
19
29
  export declare const PasskeyFingerLogo: () => import("react/jsx-runtime").JSX.Element;
30
+ export declare const PhoneIcon: ({ fill }: {
31
+ fill?: string;
32
+ }) => import("react/jsx-runtime").JSX.Element;
package/dist/components/CardItem/index.d.ts CHANGED
@@ -10,7 +10,8 @@ type CardItemProps = {
10
10
  onChange?: (value: string) => void;
11
11
  onEnter?: (value: string) => void;
12
12
  onSubmit?: (value: string) => void;
13
- inputType?: 'text' | 'password' | 'number' | 'email' | string;
13
+ inputType?: 'text' | 'password' | 'number' | 'email' | 'tel' | string;
14
+ placeholder?: string;
14
15
  };
15
- declare const CardItem: ({ variant, size, startIcon, endArrow, isRecent, label, onClick, onChange, onEnter, onSubmit, inputType, }: CardItemProps) => import("react/jsx-runtime").JSX.Element;
16
+ declare const CardItem: ({ variant, size, startIcon, endArrow, isRecent, label, onClick, onChange, onEnter, onSubmit, inputType, placeholder, }: CardItemProps) => import("react/jsx-runtime").JSX.Element;
16
17
  export default CardItem;
package/dist/components/CardItem/variants/input.d.ts CHANGED
@@ -4,7 +4,8 @@ type InputCardProps = {
4
4
  onChange?: (value: string) => void;
5
5
  onEnter?: (value: string) => void;
6
6
  onSubmit?: (value: string) => void;
7
- inputType?: 'text' | 'password' | 'number' | 'email' | string;
7
+ inputType?: 'text' | 'password' | 'number' | 'email' | 'tel' | string;
8
+ placeholder?: string;
8
9
  };
9
- declare const InputCard: ({ startIcon, onChange, onEnter, onSubmit, inputType, }: InputCardProps) => import("react/jsx-runtime").JSX.Element;
10
+ declare const InputCard: ({ startIcon, onChange, onEnter, onSubmit, inputType, placeholder, }: InputCardProps) => import("react/jsx-runtime").JSX.Element;
10
11
  export default InputCard;
package/dist/components/Modal/index.d.ts CHANGED
@@ -8,6 +8,8 @@ interface ModalProps {
8
8
  appearance: IAppearance;
9
9
  isPersistent: boolean;
10
10
  isBodyMount: boolean;
11
+ /** Parent passed to createConfig. Used to pin horizontal placement. */
12
+ mountElement?: HTMLElement;
11
13
  }
12
- declare const Modal: ({ isOpen, onClose, children, isSticky, appearance, isPersistent, isBodyMount, }: ModalProps) => import("react/jsx-runtime").JSX.Element | null;
14
+ declare const Modal: ({ isOpen, onClose, children, isSticky, appearance, isPersistent, isBodyMount, mountElement, }: ModalProps) => import("react/jsx-runtime").JSX.Element | null;
13
15
  export default Modal;
package/dist/components/Provider.d.ts CHANGED
@@ -1,3 +1,4 @@
1
- export declare const Provider: ({ isBodyMount }: {
1
+ export declare const Provider: ({ isBodyMount, mountElement, }: {
2
2
  isBodyMount: boolean;
3
+ mountElement?: HTMLElement;
3
4
  }) => import("react/jsx-runtime").JSX.Element;
package/dist/exports/blux.d.ts CHANGED
@@ -39,13 +39,10 @@ export declare const sendTransaction: (xdr: string, options?: {
39
39
  * Signs an arbitrary message with the connected wallet.
40
40
  *
41
41
  * @param message - The message to sign.
42
- * @param options - Optional network passphrase override.
43
42
  * @returns The signature.
44
43
  * @throws If the user is not authenticated or the Blux modal is open elsewhere.
45
44
  */
46
- export declare const signMessage: (message: string, options?: {
47
- network: string;
48
- }) => Promise<unknown>;
45
+ export declare const signMessage: (message: string) => Promise<unknown>;
49
46
  /**
50
47
  * Signs a Soroban authorization entry with the connected wallet.
51
48
  *
@@ -66,9 +63,7 @@ export declare const blux: {
66
63
  logout: () => void;
67
64
  fundMe: () => void;
68
65
  profile: () => void;
69
- signMessage: (message: string, options?: {
70
- network: string;
71
- }) => Promise<unknown>;
66
+ signMessage: (message: string) => Promise<unknown>;
72
67
  signAuthEntry: (authEntry: string, options?: {
73
68
  network: string;
74
69
  }) => Promise<unknown>;
@@ -78,7 +73,8 @@ export declare const blux: {
78
73
  sendTransaction: (xdr: string, options?: {
79
74
  network: string;
80
75
  }) => Promise<unknown>;
81
- /** Whether the SDK has finished initializing and is ready to use. */
76
+ /** Whether the SDK has finished initializing and is ready to use. Wallet
77
+ * availability is not part of this wait when `loginMethods` omits `'wallet'`. */
82
78
  readonly isReady: boolean;
83
79
  /** Whether a user is currently authenticated. */
84
80
  readonly isAuthenticated: boolean;
package/dist/exports/core/helpers/account.d.ts CHANGED
@@ -1,12 +1,4 @@
1
1
  import { Asset, Horizon } from '@stellar/stellar-sdk';
2
- /**
3
- * Loads an account from Horizon, returning `null` instead of throwing when the
4
- * account does not exist on the network yet.
5
- *
6
- * @param horizon - The Horizon server to query.
7
- * @param address - The account id (`G...`) to load.
8
- * @returns The account, or `null` if it is not found.
9
- */
10
2
  export declare const loadAccount: (horizon: Horizon.Server, address: string) => Promise<Horizon.AccountResponse | null>;
11
3
  /**
12
4
  * Reports whether `account` can receive `asset` directly: always true for the
package/dist/exports/core/swap.d.ts CHANGED
@@ -38,6 +38,15 @@ export type SwapOptions = {
38
38
  /** Network passphrase to swap on. Defaults to the active network. */
39
39
  network?: string;
40
40
  };
41
+ /**
42
+ * Builds the unsigned swap transaction XDR. {@link swap} signs and submits this
43
+ * envelope; the profile Swap page uses it so it can close the modal before
44
+ * opening the signing flow.
45
+ *
46
+ * @param options - What to swap and how — see {@link SwapOptions}.
47
+ * @returns The unsigned transaction envelope as XDR.
48
+ */
49
+ export declare const buildSwapTransaction: (options: SwapOptions) => Promise<string>;
41
50
  /**
42
51
  * Swaps one asset for another through the Stellar DEX / liquidity pools using a
43
52
  * path payment, picking the best available path automatically. Routes of at
package/dist/exports/createConfig.d.ts CHANGED
@@ -1,12 +1,19 @@
1
1
  import { IConfig } from '../types';
2
- import '../tailwind.css';
2
+ export type { IAppearance, IConfig, IExplorer, ILoginMethods, IServers, ITrezorMetaData, ITransports, IWalletConnectMetaData, IWalletNames, LanguageKey, } from '../types';
3
3
  /**
4
4
  * Initializes the Blux SDK: validates the config, mounts the Blux UI, loads
5
5
  * available wallets, wires up integrations (WalletConnect, Trezor), and
6
6
  * authenticates the app id. Call this once before any other Blux function.
7
7
  *
8
+ * Wallet availability is always scanned in the background. `isReady` waits on
9
+ * that scan only when `loginMethods` includes `'wallet'`; apps that omit
10
+ * wallet login (email/SMS/social/passkey only) become ready as soon as the config
11
+ * is applied, so they are not blocked by extension detection or `window.load`.
12
+ *
8
13
  * @param config - The app configuration — see {@link IConfig}.
9
14
  * @param element - DOM element to mount the Blux UI into. Defaults to `document.body`.
15
+ * When set, the modal is centered horizontally in this element and vertically
16
+ * in the viewport, so a sidebar layout can offset it without it scrolling away.
10
17
  * @throws If `config` is empty or missing `appId`, `appName`, or `networks`, or if the network options are invalid.
11
18
  */
12
19
  export declare function createConfig(config: IConfig, element?: HTMLElement): void;
package/dist/exports/index.d.ts CHANGED
@@ -1,7 +1,11 @@
1
1
  import { BluxEventMap, ReadOnlyEmitter } from '../utils/events';
2
+ export type { IAppearance, IConfig, IExplorer, ILoginMethods, IServers, ISocialProvider, ITrezorMetaData, ITransports, IWalletConnectMetaData, IWalletNames, LanguageKey, } from '../types';
3
+ export type { IUser } from '../store';
4
+ export type { IExportedStore } from './exportedStore';
2
5
  export { Asset } from '@stellar/stellar-sdk';
3
6
  export * as StellarSdk from '@stellar/stellar-sdk';
4
7
  export * from './core';
8
+ export * as core from './core';
5
9
  export { blux } from './blux';
6
10
  export { BluxEvent } from '../utils/events';
7
11
  export { getState, subscribe, getInitialState, useExportedStore, } from './exportedStore';
package/dist/hooks/useTransactions.d.ts CHANGED
@@ -7,5 +7,10 @@ export type UseTransactionsResult = {
7
7
  error: Error | null;
8
8
  transactions: TransactionRecordWithOperations[];
9
9
  };
10
+ /**
11
+ * Horizon activity for the signed-in account. Mount this only from the
12
+ * Activity page — listing txs and then fetching each one's operations is
13
+ * expensive and should not run in the background.
14
+ */
10
15
  declare const useTransactions: () => UseTransactionsResult;
11
16
  export default useTransactions;