@kryptos_connect/mobile-sdk 1.0.6-dev.0 → 1.0.6-dev.1

package/README.md

@@ -1,6 +1,6 @@
 # @kryptos_connect/mobile-sdk
 
-Kryptos Connect Mobile SDK for React Native - Works with both **Expo** and **React Native CLI**. Simplifies Web3 finance integration for mobile apps.
+Kryptos Connect Mobile SDK for React Native – works with **Expo** and **React Native CLI**. Seamless Kryptos integration with built-in authentication, theme support, and wallet connectivity. Connect your users to the complete Web3 finance ecosystem with support for 5000+ DeFi protocols, 200+ exchanges and wallets, and 100+ blockchains.
 
 ## Installation
 
@@ -28,6 +28,13 @@ npx expo install @kryptos_connect/mobile-sdk react-native-svg
 cd ios && pod install
 ```
 
+## Prerequisites
+
+Before using this package, you'll need:
+
+1. **Client ID**: Obtain from [Kryptos Developer Portal](https://dashboard.kryptos.io)
+2. **WalletConnect Project ID**: Get from [WalletConnect Cloud](https://cloud.walletconnect.com) (optional, for wallet connectivity)
+
 ## Core library (all-in-one)
 
 For Expo or bare React Native, install the core WalletConnect/AppKit deps together:
@@ -77,7 +84,7 @@ const config = {
   appLogo: "https://your-logo-url.com/logo.png", // or require('./logo.png')
   clientId: "your-client-id",
   theme: "light", // or 'dark'
-  walletConnectProjectId: "your-walletconnect-project-id", // optional
+  walletConnectProjectId: "your-walletconnect-project-id",
 };
 
 export default function App() {
@@ -89,6 +96,16 @@ export default function App() {
 }
 ```
 
+### Configuration Options
+
+| Property                 | Type                                       | Required | Description                                                                 |
+| ------------------------ | ------------------------------------------ | -------- | --------------------------------------------------------------------------- |
+| `appName`                | `string`                                   | Yes      | Your application name                                                       |
+| `appLogo`                | `React.ReactNode \| string \| ImageSource` | No       | Your app logo (URL, `require()`, or React Native image source)              |
+| `clientId`               | `string`                                   | Yes      | Your Kryptos client ID                                                      |
+| `theme`                  | `"light" \| "dark"`                        | No       | Default theme mode (defaults to `"light"` if not set)                       |
+| `walletConnectProjectId` | `string`                                   | No       | Your WalletConnect project ID (enables built-in AppKit / wallet connection) |
+
 ### 2. Add the Connect Button
 
 ```tsx
@@ -138,29 +155,27 @@ function YourComponent() {
 }
 ```
 
-## User Flow Variations
+#### User Flow Variations
 
 The SDK automatically handles two different user flows based on the `isAuthorized` flag returned from `generateLinkToken`:
 
-### Flow 1: New/Anonymous User (`isAuthorized: false` or undefined)
+**Flow 1: New User** (`isAuthorized: false` or undefined)
 
 ```
-INIT → AUTH (Login) → OTP → INTEGRATION → PERMISSIONS → STATUS
+INIT → Connect → INTEGRATION → STATUS
 ```
 
-- User enters email and verifies OTP (or continues as guest)
-- User selects integrations to connect
-- User grants permissions/consent
-- Returns `public_token` in `onSuccess` callback
+- **INIT (Connect)**: Fetches link token and initializes the session & an account is created for them on the backend
+- **INTEGRATION**: User selects and connects integrations (wallets, exchanges, blockchains)
+- **STATUS**: Success or error result; returns `public_token` in `onSuccess` when consent is given, or `null` when user was already authorized
 
-### Flow 2: Authenticated User (`isAuthorized: true`)
+**Flow 2: Authenticated User** (`isAuthorized: true`)
 
 ```
 INIT → INTEGRATION → STATUS
 ```
 
-- Skips login/OTP (already authenticated)
-- Skips permissions (already consented)
+- Skips Connect (an account already exists for the user on the backend)
 - User directly selects integrations
 - Returns `null` in `onSuccess` callback (no new token needed)
 
@@ -290,15 +305,39 @@ const styles = StyleSheet.create({
 });
 ```
 
-## Features
+#### Direct Integration Flow
 
-### Sandbox Mode Indicator
+You can use the `integrationName` prop to direct users to a specific integration, bypassing the general integration selection. Useful for dedicated buttons for specific exchanges or wallets.
 
-The SDK automatically displays a "Sandbox Mode" badge when using the development environment. This helps distinguish between development and production environments visually. The badge appears at the bottom of the authentication modal and only shows when:
+**Getting supported integration IDs:** Fetch from the public Kryptos API:
 
-- The client's project stage is not "production"
+```bash
+GET {BASE_URL}/integrations/public/list
+```
 
-This indicator is automatically managed by the SDK and requires no additional configuration.
+**Usage example:**
+
+```tsx
+// Direct connection to a specific integration (e.g. Binance)
+<KryptosConnectButton
+  generateLinkToken={generateLinkToken}
+  integrationName="binance"
+  onSuccess={(userConsent) => {
+    console.log("Binance connected:", userConsent);
+  }}
+>
+  Connect Binance Account
+</KryptosConnectButton>
+
+// Default button text when integrationName is set: "Connect {Integration} Account"
+<KryptosConnectButton
+  generateLinkToken={generateLinkToken}
+  integrationName="metamask"
+  onSuccess={(userConsent) => console.log("MetaMask connected:", userConsent)}
+/>
+```
+
+**Use cases:** Dedicated integration buttons, contextual integration (e.g. exchange-focused screens), onboarding steps (e.g. connect wallet then exchange). The `integrationName` value must match an integration ID from the supported providers list.
 
 ## API Reference
 
@@ -331,14 +370,15 @@ The main button component that triggers the connection flow.
 
 #### Props
 
-| Prop                | Type                                                            | Required | Description                                                                                                              |
-| ------------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `generateLinkToken` | `() => Promise<{ link_token: string; isAuthorized?: boolean }>` | Yes      | Function that returns link token and authorization status. `isAuthorized: true` skips login flow for authenticated users |
-| `onSuccess`         | `(consent: UserConsent \| null) => void`                        | No       | Callback fired when connection succeeds. Receives `public_token` for new users, `null` for authorized users              |
-| `onError`           | `(error?: Error) => void`                                       | No       | Callback fired when connection fails                                                                                     |
-| `children`          | `ReactNode`                                                     | No       | Custom button content                                                                                                    |
-| `style`             | `ViewStyle`                                                     | No       | Custom button container style                                                                                            |
-| `textStyle`         | `TextStyle`                                                     | No       | Custom button text style                                                                                                 |
+| Prop                | Type                                                            | Required | Description                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateLinkToken` | `() => Promise<{ link_token: string; isAuthorized?: boolean }>` | Yes      | Function that returns link token and authorization status. `isAuthorized: true` indicates the user is already authorized (consent API may be skipped; `onSuccess` receives `null`) |
+| `onSuccess`         | `(data: UserConsent \| null) => void`                           | No       | Callback invoked when connection succeeds. Receives `public_token` for new users, `null` for authorized users                                                                      |
+| `onError`           | `(error?: Error) => void`                                       | No       | Callback invoked when connection fails                                                                                                                                             |
+| `integrationName`   | `string`                                                        | No       | Integration ID from the supported providers list. When provided, skips the integration list and goes directly to that integration                                                  |
+| `children`          | `ReactNode`                                                     | No       | Custom button content. Defaults to "Connect With Kryptos", or "Connect {Integration} Account" when `integrationName` is set                                                        |
+| `style`             | `ViewStyle`                                                     | No       | Custom button container style                                                                                                                                                      |
+| `textStyle`         | `TextStyle`                                                     | No       | Custom button text style                                                                                                                                                           |
 
 #### TypeScript Types
 
@@ -350,6 +390,7 @@ interface KryptosConnectButtonProps {
   }>;
   onSuccess?: (data: UserConsent | null) => void;
   onError?: (error?: Error) => void;
+  integrationName?: string; // Integration ID from the supported providers list
   children?: ReactNode;
   style?: ViewStyle;
   textStyle?: TextStyle;
@@ -365,23 +406,40 @@ interface UserConsent {
 // - null for authenticated users (isAuthorized: true)
 ```
 
+### TypeScript
+
+The package includes type definitions. You can import types from the package:
+
+```typescript
+import type {
+  KryptosConnectButtonProps,
+  KryptosConfig,
+  UserConsent,
+} from "@kryptos_connect/mobile-sdk";
+```
+
 ## Backend Integration
 
-You'll need to implement two backend endpoints to complete the integration.
+You need to implement two backend endpoints. The same API is used for web and mobile.
 
 ### Base URLs
 
-| Environment    | URL                               |
-| -------------- | --------------------------------- |
-| **Production** | `https://connect-api.kryptos.io/` |
+| Environment    | URL                              |
+| -------------- | -------------------------------- |
+| **Production** | `https://connect-api.kryptos.io` |
 
 ### 1. Create Link Token
 
-The link token can be created in two ways, depending on whether you want to authenticate an existing user or create a new session.
+A link token can be created in two ways: to authenticate an existing user or to create a new session.
+
+| Approach | When to use                      |
+| -------- | -------------------------------- |
+| Option A | New user, no access token        |
+| Option B | Returning user, has access token |
 
 #### Option A: Without Access Token (New/Anonymous User)
 
-Use this approach for **new users** or when you want users to go through the login/OTP flow:
+Use this approach for **new users** (no access token):
 
 ```javascript
 // Example: Node.js/Express
@@ -402,7 +460,7 @@ app.post("/api/kryptos/create-link-token", async (req, res) => {
 
     const data = await response.json();
     res.json({
-      link_token: data.data.link_token,
+      link_token: data.link_token,
       isAuthorized: false, // No access token provided
     });
   } catch (error) {
@@ -411,18 +469,16 @@ app.post("/api/kryptos/create-link-token", async (req, res) => {
 });
 ```
 
-**User Experience Flow**:
+**User experience flow:**
 
-1. User clicks "Connect to Kryptos"
-2. **Login screen appears**
-3. User enters email → Verifies OTP (OR continues as guest)
-4. User selects integrations
-5. User grants permissions
-6. `onSuccess` receives `public_token` to exchange
+1. User taps "Connect to Kryptos"
+2. Connect (INIT) screen initializes, then integration selection is shown
+3. User selects and connects integrations
+4. `onSuccess` receives `public_token` to exchange
 
 #### Option B: With Access Token (Authenticated User)
 
-Use this approach for **existing authenticated users** to skip the login flow:
+Use this approach for **existing authenticated users**:
 
 ```javascript
 // Example: Node.js/Express
@@ -447,7 +503,7 @@ app.post("/api/kryptos/create-link-token", async (req, res) => {
 
     const data = await response.json();
     res.json({
-      link_token: data.data.link_token,
+      link_token: data.link_token,
       isAuthorized: true, // Access token provided, user is authenticated
     });
   } catch (error) {
@@ -456,32 +512,30 @@ app.post("/api/kryptos/create-link-token", async (req, res) => {
 });
 ```
 
-**User Experience Flow**:
+**User experience flow:**
 
-1. User clicks "Connect to Kryptos"
-2. **Directly shows integration selection** (no login screen)
-3. User selects integrations
-4. `onSuccess` receives `null` (no new token needed)
+1. User taps "Connect to Kryptos"
+2. Connect (INIT) then integration selection is shown
+3. User selects integrations; `onSuccess` receives `null` (no new token needed)
 
 #### Choosing the Right Approach
 
-| Scenario                                   | Use Option        | isAuthorized | User Flow                               | Returns public_token |
-| ------------------------------------------ | ----------------- | ------------ | --------------------------------------- | -------------------- |
-| First-time user connecting to Kryptos      | A (Without Token) | `false`      | LOGIN → OTP → INTEGRATION → PERMISSIONS | ✅ Yes               |
-| User doesn't have an access token yet      | A (Without Token) | `false`      | LOGIN → OTP → INTEGRATION → PERMISSIONS | ✅ Yes               |
-| Returning user with stored access token    | B (With Token)    | `true`       | INTEGRATION only (skip login)           | ❌ No                |
-| Adding more integrations for existing user | B (With Token)    | `true`       | INTEGRATION only (skip login)           | ❌ No                |
+| Scenario                                   | Use Option        | isAuthorized | User Flow (mobile)                                                         | Returns public_token |
+| ------------------------------------------ | ----------------- | ------------ | -------------------------------------------------------------------------- | -------------------- |
+| First-time user connecting to Kryptos      | A (Without Token) | `false`      | INIT → Connect(account created for user on backend) → INTEGRATION → STATUS | ✅ Yes               |
+| User doesn't have an access token yet      | A (Without Token) | `false`      | INIT → Connect(account created for user on backend) → INTEGRATION → STATUS | ✅ Yes               |
+| Returning user with stored access token    | B (With Token)    | `true`       | INIT → INTEGRATION → STATUS                                                | ❌ No                |
+| Adding more integrations for existing user | B (With Token)    | `true`       | INIT → INTEGRATION → STATUS                                                | ❌ No                |
 
-**Important Notes**:
+**Important notes:**
 
-- After the first successful connection (using Option A), store the `access_token` you receive from the token exchange
-- Use the stored `access_token` for subsequent connections (Option B) to provide a seamless experience
-- For authorized users (`isAuthorized: true`), the `onSuccess` callback receives `null` instead of a `public_token`
-- Authorized users skip both the login/OTP and permissions steps
+- After the first successful connection (Option A), store the `access_token` from the token exchange.
+- Use the stored `access_token` for subsequent connections (Option B).
+- For authorized users (`isAuthorized: true`), `onSuccess` receives `null`.
 
 ### 2. Exchange Public Token
 
-After a successful connection, exchange the `public_token` for an `access_token`. **Important**: Store this `access_token` securely in your database - you'll use it to create link tokens for authenticated users (Option B above).
+After a successful connection, exchange the `public_token` for an `access_token`. **Important:** Store this `access_token` securely in your database. You will use it to create link tokens for authenticated users (Option B above).
 
 ```javascript
 // Example: Node.js/Express
@@ -493,11 +547,11 @@ app.post("/api/kryptos/exchange-token", async (req, res) => {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        "X-Client-Id": YOUR_CLIENT_ID,
+        "X-Client-Secret": YOUR_CLIENT_SECRET,
       },
       body: JSON.stringify({
         public_token,
-        client_id: YOUR_CLIENT_ID,
-        client_secret: YOUR_CLIENT_SECRET,
       }),
     });
 
@@ -505,9 +559,9 @@ app.post("/api/kryptos/exchange-token", async (req, res) => {
 
     // IMPORTANT: Store the access_token securely in your database
     // You'll need this token to:
-    // 1. Create authenticated link tokens (skip login flow)
+    // 1. Create authenticated link tokens (Option B)
     // 2. Make API calls on behalf of the user
-    await saveUserAccessToken(req.user.id, data.data.access_token);
+    await saveUserAccessToken(req.user.id, data.access_token);
 
     res.json({ success: true });
   } catch (error) {
@@ -516,29 +570,26 @@ app.post("/api/kryptos/exchange-token", async (req, res) => {
 });
 ```
 
-**Complete Integration Flow:**
+**Complete integration flow:**
 
-1. **First Connection** (New User - `isAuthorized: false`):
+1. **First connection** (new user – `isAuthorized: false`):
 
    ```
    App → generateLinkToken() [returns { link_token, isAuthorized: false }]
-   → SDK Flow: INIT → AUTH → OTP → INTEGRATION → PERMISSIONS → STATUS
-   → User logs in with email/OTP (or as guest)
-   → User connects integrations
-   → User grants permissions
-   → onSuccess receives { public_token: "..." }
+   → SDK: INIT → Connect → INTEGRATION → STATUS
+   → User selects and connects integrations
+   → onSuccess receives { public_token }
    → Backend exchanges public_token for access_token
    → Store access_token in database ← IMPORTANT
    ```
 
-2. **Subsequent Connections** (Returning User - `isAuthorized: true`):
+2. **Subsequent connections** (returning user – `isAuthorized: true`):
    ```
    App → generateLinkToken() [returns { link_token, isAuthorized: true }]
-   → SDK Flow: INIT → INTEGRATION → STATUS (skip AUTH, OTP)
-   → User directly sees integrations (no login)
-   → User connects more integrations
-   → onSuccess receives null (no new token needed)
-   → Integrations are added to user's existing account
+   → SDK: INIT → INTEGRATION → STATUS
+   → User sees integrations directly → connects more
+   → onSuccess receives null
+   → Integrations added to existing account
    ```
 
 ## Supported Platforms
@@ -558,12 +609,17 @@ app.post("/api/kryptos/exchange-token", async (req, res) => {
 }
 ```
 
+## Support
+
+- 📧 Email: [support@kryptos.io](mailto:support@kryptos.io)
+- 📚 Documentation: [https://docs.kryptos.io](https://docs.kryptos.io)
+- 💬 Discord: [Join our community](https://discord.gg/kryptos)
+- 🐛 Issues: [GitHub Issues](https://github.com/kryptos/connect-npm-package/issues)
+
 ## License
 
-MIT © Kryptos
+MIT © [Kryptos](https://kryptos.io)
 
-## Support
+---
 
-- 📧 Email: support@kryptos.io
-- 📚 Documentation: https://dashboard.kryptos.io
-- 🐛 Issues: https://github.com/Kryptoskatt/kryptos-connect-mobile-package/issues
+Made with ❤️ by the Kryptos team

package/dist/index.js

@@ -1644,7 +1644,7 @@ var Auth = ({
       const err = error;
       console.error(error);
       setErrorMessage(
-        err?.response?.data?.message || "Failed to continue as guest"
+        err?.response?.data?.error || err?.response?.data?.message || "Failed to continue as guest"
       );
     } finally {
       setIsLoading(false);
@@ -2306,12 +2306,13 @@ var WalletConnectComponent = ({
   modalOpen,
   setAddIntegrationMode,
   providersList,
-  errorMessage
+  errorMessage,
+  showBackButton
 }) => {
   const { walletConnectProjectId } = useKryptosConnect();
   const theme = useTheme();
   if (!walletConnectProjectId) {
-    return /* @__PURE__ */ import_react32.default.createElement(Modal, { isOpen: modalOpen, onClose: handleClose, size: "full" }, /* @__PURE__ */ import_react32.default.createElement(ModalHeader, { onClose: handleClose }, /* @__PURE__ */ import_react32.default.createElement(import_react_native16.View, { style: styles14.headerContent }, /* @__PURE__ */ import_react32.default.createElement(
+    return /* @__PURE__ */ import_react32.default.createElement(Modal, { isOpen: modalOpen, onClose: handleClose, size: "full" }, /* @__PURE__ */ import_react32.default.createElement(ModalHeader, { onClose: handleClose }, /* @__PURE__ */ import_react32.default.createElement(import_react_native16.View, { style: styles14.headerContent }, showBackButton && /* @__PURE__ */ import_react32.default.createElement(
       import_react_native16.TouchableOpacity,
       {
         onPress: () => {
@@ -2356,7 +2357,8 @@ var WalletConnectComponent = ({
       modalOpen,
       setAddIntegrationMode,
       providersList,
-      errorMessage
+      errorMessage,
+      showBackButton
     }
   ));
 };
@@ -2367,7 +2369,8 @@ function ConnectButton({
   modalOpen,
   setAddIntegrationMode,
   providersList,
-  errorMessage: errorMessageProp
+  errorMessage: errorMessageProp,
+  showBackButton
 }) {
   const theme = useTheme();
   const { open, disconnect } = (0, import_appkit_react_native3.useAppKit)();
@@ -2609,7 +2612,7 @@ function ConnectButton({
     }
     handleClose();
   };
-  return /* @__PURE__ */ import_react32.default.createElement(Modal, { isOpen: modalOpen, onClose, size: "full" }, /* @__PURE__ */ import_react32.default.createElement(ModalHeader, { onClose }, /* @__PURE__ */ import_react32.default.createElement(import_react_native16.View, { style: styles14.headerContent }, /* @__PURE__ */ import_react32.default.createElement(
+  return /* @__PURE__ */ import_react32.default.createElement(Modal, { isOpen: modalOpen, onClose, size: "full" }, /* @__PURE__ */ import_react32.default.createElement(ModalHeader, { onClose }, /* @__PURE__ */ import_react32.default.createElement(import_react_native16.View, { style: styles14.headerContent }, showBackButton && /* @__PURE__ */ import_react32.default.createElement(
     import_react_native16.TouchableOpacity,
     {
       onPress: () => {
@@ -3652,7 +3655,8 @@ var IntegrationForm = ({
       setAddIntegrationMode,
       handleClose,
       providersList,
-      errorMessage: errorMessageProp
+      errorMessage: errorMessageProp,
+      showBackButton
     }
   ));
 };

package/dist/index.mjs

@@ -1642,7 +1642,7 @@ var Auth = ({
       const err = error;
       console.error(error);
       setErrorMessage(
-        err?.response?.data?.message || "Failed to continue as guest"
+        err?.response?.data?.error || err?.response?.data?.message || "Failed to continue as guest"
       );
     } finally {
       setIsLoading(false);
@@ -2321,12 +2321,13 @@ var WalletConnectComponent = ({
   modalOpen,
   setAddIntegrationMode,
   providersList,
-  errorMessage
+  errorMessage,
+  showBackButton
 }) => {
   const { walletConnectProjectId } = useKryptosConnect();
   const theme = useTheme();
   if (!walletConnectProjectId) {
-    return /* @__PURE__ */ React32.createElement(Modal, { isOpen: modalOpen, onClose: handleClose, size: "full" }, /* @__PURE__ */ React32.createElement(ModalHeader, { onClose: handleClose }, /* @__PURE__ */ React32.createElement(View14, { style: styles14.headerContent }, /* @__PURE__ */ React32.createElement(
+    return /* @__PURE__ */ React32.createElement(Modal, { isOpen: modalOpen, onClose: handleClose, size: "full" }, /* @__PURE__ */ React32.createElement(ModalHeader, { onClose: handleClose }, /* @__PURE__ */ React32.createElement(View14, { style: styles14.headerContent }, showBackButton && /* @__PURE__ */ React32.createElement(
       TouchableOpacity4,
       {
         onPress: () => {
@@ -2371,7 +2372,8 @@ var WalletConnectComponent = ({
       modalOpen,
       setAddIntegrationMode,
       providersList,
-      errorMessage
+      errorMessage,
+      showBackButton
     }
   ));
 };
@@ -2382,7 +2384,8 @@ function ConnectButton({
   modalOpen,
   setAddIntegrationMode,
   providersList,
-  errorMessage: errorMessageProp
+  errorMessage: errorMessageProp,
+  showBackButton
 }) {
   const theme = useTheme();
   const { open, disconnect } = useAppKit();
@@ -2624,7 +2627,7 @@ function ConnectButton({
     }
     handleClose();
   };
-  return /* @__PURE__ */ React32.createElement(Modal, { isOpen: modalOpen, onClose, size: "full" }, /* @__PURE__ */ React32.createElement(ModalHeader, { onClose }, /* @__PURE__ */ React32.createElement(View14, { style: styles14.headerContent }, /* @__PURE__ */ React32.createElement(
+  return /* @__PURE__ */ React32.createElement(Modal, { isOpen: modalOpen, onClose, size: "full" }, /* @__PURE__ */ React32.createElement(ModalHeader, { onClose }, /* @__PURE__ */ React32.createElement(View14, { style: styles14.headerContent }, showBackButton && /* @__PURE__ */ React32.createElement(
     TouchableOpacity4,
     {
       onPress: () => {
@@ -3673,7 +3676,8 @@ var IntegrationForm = ({
       setAddIntegrationMode,
       handleClose,
       providersList,
-      errorMessage: errorMessageProp
+      errorMessage: errorMessageProp,
+      showBackButton
     }
   ));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kryptos_connect/mobile-sdk",
-  "version": "1.0.6-dev.0",
+  "version": "1.0.6-dev.1",
   "publishConfig": {
     "access": "public"
   },