@kryptos_connect/mobile-sdk 1.0.0 → 1.0.2

package/README.md

@@ -77,6 +77,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
 };
 
 export default function App() {
@@ -96,19 +97,35 @@ import { KryptosConnectButton } from "@kryptos_connect/mobile-sdk";
 function YourComponent() {
   const generateLinkToken = async () => {
     // Call your backend API to generate a link token
-    const response = await fetch("https://your-api.com/generate-link-token");
+    const response = await fetch("https://your-api.com/generate-link-token", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        // Optional: Include access_token for authenticated users
+        // access_token: userAccessToken
+      }),
+    });
     const data = await response.json();
-    return data.link_token;
+    // Return link_token and isAuthorized flag
+    return {
+      link_token: data.link_token,
+      isAuthorized: data.isAuthorized, // pass true if access_token was provided
+    };
   };
 
   const handleSuccess = (userConsent) => {
     console.log("Connection successful!", userConsent);
-    // Handle the public_token
-    const publicToken = userConsent?.public_token;
+    // For new users, exchange the public token for an access token
+    // For authorized users, userConsent might be null
+    if (userConsent?.public_token) {
+      exchangePublicToken(userConsent.public_token);
+    }
   };
 
-  const handleError = () => {
-    console.log("Connection failed");
+  const handleError = (error) => {
+    console.error("Connection failed:", error);
   };
 
   return (
@@ -121,6 +138,59 @@ function YourComponent() {
 }
 ```
 
+## 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)
+
+```
+INIT → AUTH (Login) → OTP → INTEGRATION → PERMISSIONS → 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
+
+### Flow 2: Authenticated User (`isAuthorized: true`)
+
+```
+INIT → INTEGRATION → STATUS
+```
+
+- Skips login/OTP (already authenticated)
+- Skips permissions (already consented)
+- User directly selects integrations
+- Returns `null` in `onSuccess` callback (no new token needed)
+
+### Implementation Example
+
+```tsx
+const generateLinkToken = async () => {
+  const user = getCurrentUser(); // Your auth logic
+
+  const response = await fetch("/api/kryptos/create-link-token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      // Include access_token if user is logged in
+      access_token: user?.kryptosAccessToken || undefined,
+    }),
+  });
+
+  const data = await response.json();
+
+  return {
+    link_token: data.link_token,
+    // isAuthorized will be true if access_token was valid
+    isAuthorized: !!user?.kryptosAccessToken,
+  };
+};
+```
+
 ## WalletConnect / Reown AppKit configuration
 
 Passing a `walletConnectProjectId` to `KryptosConnectProvider` enables the built-in AppKit (WalletConnect v2) flow used by the `WalletConnectComponent`:
@@ -148,13 +218,47 @@ export default function App() {
 
 Behind the scenes the SDK creates an AppKit instance (see `src/wallet-connect/AppKitConfig.ts`) with Ethers adapter, common EVM chains, and persistent storage. If you need to customize chains, metadata, or features, copy that file into your app and adjust it following the Reown AppKit guide: https://docs.reown.com/appkit/overview
 
+### Environment Configuration
+
+You can configure different environments (dev/prod) by passing the `baseUrl` option:
+
+```tsx
+import { KryptosConnectProvider } from "@kryptos_connect/mobile-sdk";
+
+// Development Environment
+const devConfig = {
+  appName: "Your App",
+  clientId: "your-client-id",
+  theme: "light",
+  walletConnectProjectId: "your-project-id",
+};
+
+// Production Environment
+const prodConfig = {
+  appName: "Your App",
+  clientId: "your-client-id",
+  theme: "light",
+  walletConnectProjectId: "your-project-id",
+};
+
+export default function App() {
+  const config = __DEV__ ? devConfig : prodConfig;
+
+  return (
+    <KryptosConnectProvider config={config}>
+      <YourApp />
+    </KryptosConnectProvider>
+  );
+}
+```
+
 ### 3. Custom Button (Optional)
 
 You can also use a custom button:
 
 ```tsx
 import { KryptosConnectButton } from "@kryptos_connect/mobile-sdk";
-import { Text, View } from "react-native";
+import { Text, View, StyleSheet } from "react-native";
 
 function CustomButton() {
   return (
@@ -164,13 +268,38 @@ function CustomButton() {
       onError={handleError}
     >
       <View style={styles.customButton}>
-        <Text style={styles.customText}>Connect Your Wallet</Text>
+        <Text style={styles.customText}>🔐 Connect Your Wallet</Text>
       </View>
     </KryptosConnectButton>
   );
 }
+
+const styles = StyleSheet.create({
+  customButton: {
+    backgroundColor: "#00C693",
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    borderRadius: 8,
+    alignItems: "center",
+  },
+  customText: {
+    color: "#FFFFFF",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+});
 ```
 
+## Features
+
+### Sandbox Mode Indicator
+
+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:
+
+- The client's project stage is not "production"
+
+This indicator is automatically managed by the SDK and requires no additional configuration.
+
 ## API Reference
 
 ### KryptosConnectProvider
@@ -189,7 +318,7 @@ The provider component that wraps your app and provides the Kryptos context.
 ```typescript
 type KryptosConfig = {
   appName: string; // Your app name
-  appLogo?: ReactNode | string; // Logo URL or React Native Image source
+  appLogo?: ReactNode | string | ImageSourcePropType; // Logo URL, React Native Image source, or require()
   theme?: "light" | "dark"; // Theme mode (default: 'light')
   clientId: string; // Your Kryptos client ID
   walletConnectProjectId?: string; // Optional WalletConnect project ID
@@ -202,44 +331,216 @@ The main button component that triggers the connection flow.
 
 #### Props
 
-| Prop                | Type                             | Required | Description                       |
-| ------------------- | -------------------------------- | -------- | --------------------------------- |
-| `generateLinkToken` | `() => Promise<string>`          | Yes      | Function to generate a link token |
-| `onSuccess`         | `(consent: UserConsent) => void` | No       | Called on successful connection   |
-| `onError`           | `() => void`                     | No       | Called on connection failure      |
-| `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` 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                                                                                                 |
 
-### KryptosConnectModal
+#### TypeScript Types
 
-If you need more control, you can use the modal component directly:
+```typescript
+interface KryptosConnectButtonProps {
+  generateLinkToken: () => Promise<{
+    link_token: string;
+    isAuthorized?: boolean;
+  }>;
+  onSuccess?: (data: UserConsent | null) => void;
+  onError?: (error?: Error) => void;
+  children?: ReactNode;
+  style?: ViewStyle;
+  textStyle?: TextStyle;
+}
 
-```tsx
-import { KryptosConnectModal } from "@kryptos_connect/mobile-sdk";
-import { useState } from "react";
+interface UserConsent {
+  public_token: string;
+  // Additional consent data
+}
 
-function YourComponent() {
-  const [open, setOpen] = useState(false);
+// Note: onSuccess receives:
+// - UserConsent with public_token for new users (isAuthorized: false)
+// - null for authenticated users (isAuthorized: true)
+```
 
-  return (
-    <>
-      <TouchableOpacity onPress={() => setOpen(true)}>
-        <Text>Open Modal</Text>
-      </TouchableOpacity>
-
-      <KryptosConnectModal
-        open={open}
-        setOpen={setOpen}
-        generateLinkToken={generateLinkToken}
-        onSuccess={handleSuccess}
-        onError={handleError}
-      />
-    </>
-  );
-}
+## Backend Integration
+
+You'll need to implement two backend endpoints to complete the integration.
+
+### Base URLs
+
+| 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.
+
+#### 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:
+
+```javascript
+// Example: Node.js/Express
+app.post("/api/kryptos/create-link-token", async (req, res) => {
+  try {
+    const response = await fetch(`${KRYPTOS_BASE_URL}/link-token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Client-Id": YOUR_CLIENT_ID,
+        "X-Client-Secret": YOUR_CLIENT_SECRET,
+      },
+      body: JSON.stringify({
+        scopes:
+          "openid profile offline_access email portfolios:read transactions:read integrations:read tax:read accounting:read reports:read workspace:read users:read",
+      }),
+    });
+
+    const data = await response.json();
+    res.json({
+      link_token: data.data.link_token,
+      isAuthorized: false, // No access token provided
+    });
+  } catch (error) {
+    res.status(500).json({ error: "Failed to create link token" });
+  }
+});
+```
+
+**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
+
+#### Option B: With Access Token (Authenticated User)
+
+Use this approach for **existing authenticated users** to skip the login flow:
+
+```javascript
+// Example: Node.js/Express
+app.post("/api/kryptos/create-link-token", async (req, res) => {
+  try {
+    // Get the user's stored access token from your database
+    const userAccessToken = await getUserAccessToken(req.user.id);
+
+    const response = await fetch(`${KRYPTOS_BASE_URL}/link-token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Client-Id": YOUR_CLIENT_ID,
+        "X-Client-Secret": YOUR_CLIENT_SECRET,
+      },
+      body: JSON.stringify({
+        scopes:
+          "openid profile offline_access integrations:read integrations:write",
+        access_token: userAccessToken, // Pass the user's access token
+      }),
+    });
+
+    const data = await response.json();
+    res.json({
+      link_token: data.data.link_token,
+      isAuthorized: true, // Access token provided, user is authenticated
+    });
+  } catch (error) {
+    res.status(500).json({ error: "Failed to create link token" });
+  }
+});
 ```
 
+**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)
+
+#### 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                |
+
+**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
+
+### 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).
+
+```javascript
+// Example: Node.js/Express
+app.post("/api/kryptos/exchange-token", async (req, res) => {
+  try {
+    const { public_token } = req.body;
+
+    const response = await fetch(`${KRYPTOS_BASE_URL}/token/exchange`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        public_token,
+        client_id: YOUR_CLIENT_ID,
+        client_secret: YOUR_CLIENT_SECRET,
+      }),
+    });
+
+    const data = await response.json();
+
+    // IMPORTANT: Store the access_token securely in your database
+    // You'll need this token to:
+    // 1. Create authenticated link tokens (skip login flow)
+    // 2. Make API calls on behalf of the user
+    await saveUserAccessToken(req.user.id, data.data.access_token);
+
+    res.json({ success: true });
+  } catch (error) {
+    res.status(500).json({ error: "Failed to exchange token" });
+  }
+});
+```
+
+**Complete Integration Flow:**
+
+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: "..." }
+   → Backend exchanges public_token for access_token
+   → Store access_token in database ← IMPORTANT
+   ```
+
+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
+   ```
+
 ## Supported Platforms
 
 - ✅ iOS 12.0+

package/dist/index.d.mts

@@ -7,27 +7,23 @@ type KryptosConfig = {
     theme?: "light" | "dark";
     clientId: string;
     walletConnectProjectId?: string;
+    baseUrl?: string;
+};
+type ClientInfo = {
+    name: string;
+    description: string | null;
+    scopes: string;
+    project_stage: string;
 };
 type KryptosUser = {
-    message: string;
+    is_anonymous: boolean;
     user: {
-        uid: string;
-        email: string;
-        baseCurrency: string;
-        costbasisType: string;
-        country: string;
-        userType: string;
-        isConnect: boolean;
-        timezone: string;
-        createdAt: number;
-        updatedAt: number;
-        lastUsage: number;
-        connectMeta: {
-            lastUsage: number;
-            isAnonymous: boolean;
-            clientId: string;
-        };
+        email: string | null;
+        first_name: string | null;
     };
+    user_id: string;
+    workspace_id: string;
+    workspace_name: string;
 };
 type UserConsent = {
     public_token: string;
@@ -68,6 +64,9 @@ type KryptosContextType = KryptosConfig & {
     setEmail: (value: string) => void;
     userConsent: UserConsent | null;
     setUserConsent: (value: UserConsent | null) => void;
+    clientInfo: ClientInfo | null;
+    isAuthorized: boolean;
+    setIsAuthorized: (value: boolean) => void;
 };
 declare const KryptosConnectProvider: React.FC<{
     children: React.ReactNode;

package/dist/index.d.ts

@@ -7,27 +7,23 @@ type KryptosConfig = {
     theme?: "light" | "dark";
     clientId: string;
     walletConnectProjectId?: string;
+    baseUrl?: string;
+};
+type ClientInfo = {
+    name: string;
+    description: string | null;
+    scopes: string;
+    project_stage: string;
 };
 type KryptosUser = {
-    message: string;
+    is_anonymous: boolean;
     user: {
-        uid: string;
-        email: string;
-        baseCurrency: string;
-        costbasisType: string;
-        country: string;
-        userType: string;
-        isConnect: boolean;
-        timezone: string;
-        createdAt: number;
-        updatedAt: number;
-        lastUsage: number;
-        connectMeta: {
-            lastUsage: number;
-            isAnonymous: boolean;
-            clientId: string;
-        };
+        email: string | null;
+        first_name: string | null;
     };
+    user_id: string;
+    workspace_id: string;
+    workspace_name: string;
 };
 type UserConsent = {
     public_token: string;
@@ -68,6 +64,9 @@ type KryptosContextType = KryptosConfig & {
     setEmail: (value: string) => void;
     userConsent: UserConsent | null;
     setUserConsent: (value: UserConsent | null) => void;
+    clientInfo: ClientInfo | null;
+    isAuthorized: boolean;
+    setIsAuthorized: (value: boolean) => void;
 };
 declare const KryptosConnectProvider: React.FC<{
     children: React.ReactNode;