@b3dotfun/sdk 0.0.47-alpha.1 → 0.0.47-alpha.2

package/README.md

@@ -8,6 +8,7 @@ The SDK is organized into focused modules:
 
 - **`anyspend/`** - Cross-chain execution engine functionality
 - **`global-account/`** - B3 Global Accounts authentication and user management
+- **`notifications/`** - Multi-channel notification management
 - **`shared/`** - Common utilities, types, and components
 - **`others/`** - Additional features and utilities
 
@@ -25,6 +26,7 @@ Each module contains:
 | ----------------- | --------- | ------------ |
 | AnySpend          | ✅        | ❌           |
 | Global Accounts   | ✅        | ✅           |
+| Notifications     | ✅        | ✅           |
 | Headless Services | ✅        | ✅           |
 
 ## Installation
@@ -155,9 +157,7 @@ const order = await anyspendService.createOrder({
 import { anyspendService } from "@b3dotfun/sdk/anyspend/services/anyspend";
 
 // Get order details and transactions
-const orderDetails = await anyspendService.getOrderAndTransactions(
-  "order-id",
-);
+const orderDetails = await anyspendService.getOrderAndTransactions("order-id");
 
 // Get order history for an address
 const history = await anyspendService.getOrderHistory(
@@ -323,6 +323,206 @@ import { serverFunction } from "@b3dotfun/sdk/global-account/server";
 // (Implementation depends on your specific needs)
 ```
 
+# Notifications
+
+B3 Notifications provides multi-channel notification management for your users with support for email, Telegram, Discord, SMS, WhatsApp, and in-app notifications.
+
+## Features
+
+- ✅ **Zero Config** - Automatically uses authenticated user's ID from JWT
+- 🎯 **Type Safe** - Full TypeScript support
+- ⚡ **React Hooks** - Easy integration with `useNotifications()` hook
+- 🔐 **Secure** - JWT-based authentication
+- 📱 **Multi-Channel** - Email, Telegram, Discord, SMS, WhatsApp, In-app
+- 🚀 **Lightweight** - Minimal dependencies
+
+## React Hook
+
+### Basic Usage
+
+```tsx
+import { useNotifications } from "@b3dotfun/sdk/notifications/react";
+
+function NotificationSettings() {
+  const { user, loading, connectEmail, connectTelegram, isEmailConnected } = useNotifications();
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {!isEmailConnected && <button onClick={() => connectEmail("user@example.com")}>Connect Email</button>}
+
+      <button onClick={connectTelegram}>Connect Telegram</button>
+    </div>
+  );
+}
+```
+
+### Full Hook API
+
+```tsx
+const {
+  user, // User data with channels and settings
+  loading, // Loading state
+  error, // Error if any
+  refresh, // Manually refresh user data
+  connectEmail, // Connect email channel
+  connectTelegram, // Connect Telegram channel
+  updateChannel, // Update a channel
+  deleteChannel, // Delete a channel
+  // Convenience helpers
+  isEmailConnected,
+  isTelegramConnected,
+  isDiscordConnected,
+} = useNotifications();
+```
+
+## Headless API Client
+
+### Authentication
+
+The notifications API automatically uses the B3 auth token from cookies. The token is managed by the B3 Global Account authentication system - you don't need to set it manually.
+
+```typescript
+import { getAuthToken, notificationsAPI } from "@b3dotfun/sdk/notifications";
+// Or import from shared utils
+// import { getAuthToken } from "@b3dotfun/sdk/shared/utils";
+
+// Get the current auth token (from b3-auth cookie)
+const token = getAuthToken();
+
+// API calls automatically use the auth token
+const userData = await notificationsAPI.getUser();
+```
+
+### User Management
+
+```typescript
+import { notificationsAPI } from "@b3dotfun/sdk/notifications";
+
+// Register current user
+await notificationsAPI.registerUser();
+
+// Get current user's profile
+const userData = await notificationsAPI.getUser();
+
+// Get notification history
+const history = await notificationsAPI.getHistory("my-app-id", 50);
+```
+
+### Channel Management
+
+```typescript
+// Add any channel
+await notificationsAPI.addChannel("email", "user@example.com");
+
+// Connect email (shorthand)
+await notificationsAPI.connectEmail("user@example.com");
+
+// Update channel
+await notificationsAPI.updateChannel("channel-id", {
+  enabled: true,
+});
+
+// Delete channel
+await notificationsAPI.deleteChannel("channel-id");
+```
+
+### Telegram Integration
+
+```typescript
+// Get Telegram deep link
+const { deepLink, verificationCode, botUsername } = await notificationsAPI.getTelegramLink();
+window.open(deepLink, "_blank");
+
+// Check connection status
+const { connected, chatId } = await notificationsAPI.checkTelegramStatus();
+```
+
+### App Preferences
+
+```typescript
+// Save notification preferences for an app (enabled by default)
+await notificationsAPI.savePreferences("my-app", {
+  notificationType: "transaction",
+  channels: ["email", "telegram", "in_app"],
+});
+
+// Save disabled preferences
+await notificationsAPI.savePreferences("my-app", {
+  notificationType: "transaction",
+  channels: ["email", "telegram"],
+  enabled: false,
+});
+
+// Get app settings
+const settings = await notificationsAPI.getAppSettings("my-app");
+```
+
+### In-App Notifications
+
+```typescript
+// Get in-app notifications
+const { notifications } = await notificationsAPI.getInAppNotifications();
+
+// Mark notification as read
+await notificationsAPI.markNotificationAsRead("notification-id");
+```
+
+### Send Notifications
+
+```typescript
+// Send a notification
+await notificationsAPI.sendNotification({
+  userId: "user-123",
+  appId: "my-app",
+  notificationType: "transaction",
+  message: "Your transaction was successful!",
+  title: "Transaction Complete",
+  data: { transactionId: "tx-123" },
+});
+```
+
+## Next.js Example
+
+```tsx
+"use client";
+
+import { useNotifications } from "@b3dotfun/sdk/notifications/react";
+
+export default function NotificationsPage() {
+  const { user, loading, connectEmail, connectTelegram, isEmailConnected, isTelegramConnected } = useNotifications();
+
+  if (loading) {
+    return <div>Loading notification settings...</div>;
+  }
+
+  return (
+    <div className="space-y-4">
+      <h1>Notification Settings</h1>
+
+      <div className="rounded-lg border p-4">
+        <h2>Email</h2>
+        {isEmailConnected ? (
+          <p className="text-green-600">✓ Connected</p>
+        ) : (
+          <button onClick={() => connectEmail("user@example.com")}>Connect Email</button>
+        )}
+      </div>
+
+      <div className="rounded-lg border p-4">
+        <h2>Telegram</h2>
+        {isTelegramConnected ? (
+          <p className="text-green-600">✓ Connected</p>
+        ) : (
+          <button onClick={connectTelegram}>Connect Telegram</button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
 # Shared Utilities
 
 ## Chain Management
@@ -338,6 +538,25 @@ console.log(supportedChains);
 console.log(b3Chain);
 ```
 
+## Authentication Token Management
+
+Read-only access to the B3 authentication token. The token is managed by the B3 Global Account authentication system.
+
+```typescript
+import { getAuthToken } from "@b3dotfun/sdk/shared/utils";
+
+// Get the current auth token from the b3-auth cookie
+const token = getAuthToken();
+
+if (token) {
+  console.log("User is authenticated");
+} else {
+  console.log("User is not authenticated");
+}
+```
+
+The auth token is automatically set by the B3 Global Account authentication system (see the Global Accounts section above). All SDK modules that require authentication will automatically use this token.
+
 ## Utility Functions
 
 ```typescript

package/dist/cjs/notifications/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./services";
+export { getAuthToken } from "../shared/utils/auth-token";

package/dist/cjs/notifications/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuthToken = void 0;
+// Export types
+__exportStar(require("./types"), exports);
+// Export services
+__exportStar(require("./services"), exports);
+// Re-export auth token getter from shared for convenience
+// Note: Auth token is managed by B3 Global Account authentication
+var auth_token_1 = require("../shared/utils/auth-token");
+Object.defineProperty(exports, "getAuthToken", { enumerable: true, get: function () { return auth_token_1.getAuthToken; } });

package/dist/cjs/notifications/react/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from "./useNotifications";

package/dist/cjs/notifications/react/hooks/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./useNotifications"), exports);

package/dist/cjs/notifications/react/hooks/useNotifications.d.ts

@@ -0,0 +1,42 @@
+import type { UserData } from "../../types";
+/**
+ * React hook for managing B3 notifications
+ * Automatically uses the authenticated user's ID from JWT
+ *
+ * @example
+ * ```tsx
+ * import { useNotifications } from '../../../notifications/react';
+ *
+ * function NotificationSettings() {
+ *   const { user, loading, connectEmail, connectTelegram, isEmailConnected } = useNotifications();
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {!isEmailConnected && (
+ *         <button onClick={() => connectEmail('user@example.com')}>
+ *           Connect Email
+ *         </button>
+ *       )}
+ *       <button onClick={connectTelegram}>Connect Telegram</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useNotifications(): {
+    user: UserData | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    connectEmail: (email: string) => Promise<void>;
+    connectTelegram: () => Promise<void>;
+    updateChannel: (channelId: string, updates: {
+        enabled?: boolean;
+    }) => Promise<void>;
+    deleteChannel: (channelId: string) => Promise<void>;
+    isEmailConnected: boolean;
+    isTelegramConnected: boolean;
+    isDiscordConnected: boolean;
+};

package/dist/cjs/notifications/react/hooks/useNotifications.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useNotifications = useNotifications;
+const react_1 = require("react");
+const api_1 = require("../../services/api");
+/**
+ * React hook for managing B3 notifications
+ * Automatically uses the authenticated user's ID from JWT
+ *
+ * @example
+ * ```tsx
+ * import { useNotifications } from '../../../notifications/react';
+ *
+ * function NotificationSettings() {
+ *   const { user, loading, connectEmail, connectTelegram, isEmailConnected } = useNotifications();
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {!isEmailConnected && (
+ *         <button onClick={() => connectEmail('user@example.com')}>
+ *           Connect Email
+ *         </button>
+ *       )}
+ *       <button onClick={connectTelegram}>Connect Telegram</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useNotifications() {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Refs to track polling timers for cleanup
+    const telegramPollIntervalRef = (0, react_1.useRef)(null);
+    const telegramPollTimeoutRef = (0, react_1.useRef)(null);
+    // Cleanup function for Telegram polling
+    const cleanupTelegramPolling = () => {
+        if (telegramPollIntervalRef.current) {
+            clearInterval(telegramPollIntervalRef.current);
+            telegramPollIntervalRef.current = null;
+        }
+        if (telegramPollTimeoutRef.current) {
+            clearTimeout(telegramPollTimeoutRef.current);
+            telegramPollTimeoutRef.current = null;
+        }
+    };
+    // Load user data on mount
+    (0, react_1.useEffect)(() => {
+        loadUser();
+    }, []);
+    // Cleanup polling on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            cleanupTelegramPolling();
+        };
+    }, []);
+    const loadUser = async () => {
+        try {
+            setLoading(true);
+            setError(null);
+            const userData = await api_1.notificationsAPI.getUser();
+            setUser(userData);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error("Failed to load user"));
+            console.error("Failed to load user:", err);
+        }
+        finally {
+            setLoading(false);
+        }
+    };
+    const connectEmail = async (email) => {
+        try {
+            await api_1.notificationsAPI.connectEmail(email);
+            await loadUser(); // Refresh user data
+        }
+        catch (err) {
+            console.error("Failed to connect email:", err);
+            throw err;
+        }
+    };
+    const connectTelegram = async () => {
+        try {
+            // Clear any existing polling before starting new one
+            cleanupTelegramPolling();
+            const { deepLink } = await api_1.notificationsAPI.getTelegramLink();
+            window.open(deepLink, "_blank");
+            // Poll for connection status
+            telegramPollIntervalRef.current = setInterval(async () => {
+                try {
+                    const { connected } = await api_1.notificationsAPI.checkTelegramStatus();
+                    if (connected) {
+                        cleanupTelegramPolling();
+                        await loadUser(); // Refresh user data
+                    }
+                }
+                catch (err) {
+                    console.error("Failed to check Telegram status:", err);
+                }
+            }, 2000);
+            // Stop polling after 2 minutes
+            telegramPollTimeoutRef.current = setTimeout(() => {
+                cleanupTelegramPolling();
+            }, 120000);
+        }
+        catch (err) {
+            console.error("Failed to connect Telegram:", err);
+            throw err;
+        }
+    };
+    const updateChannel = async (channelId, updates) => {
+        try {
+            await api_1.notificationsAPI.updateChannel(channelId, updates);
+            await loadUser(); // Refresh user data
+        }
+        catch (err) {
+            console.error("Failed to update channel:", err);
+            throw err;
+        }
+    };
+    const deleteChannel = async (channelId) => {
+        try {
+            await api_1.notificationsAPI.deleteChannel(channelId);
+            await loadUser(); // Refresh user data
+        }
+        catch (err) {
+            console.error("Failed to delete channel:", err);
+            throw err;
+        }
+    };
+    return {
+        user,
+        loading,
+        error,
+        refresh: loadUser,
+        connectEmail,
+        connectTelegram,
+        updateChannel,
+        deleteChannel,
+        // Convenience helpers
+        isEmailConnected: user?.channels?.find(c => c.channel_type === "email")?.enabled === 1,
+        isTelegramConnected: user?.channels?.find(c => c.channel_type === "telegram")?.enabled === 1,
+        isDiscordConnected: user?.channels?.find(c => c.channel_type === "discord")?.enabled === 1,
+    };
+}

package/dist/cjs/notifications/react/index.d.ts

@@ -0,0 +1 @@
+export * from "./hooks";

package/dist/cjs/notifications/react/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./hooks"), exports);

package/dist/cjs/notifications/services/api.d.ts

@@ -0,0 +1,67 @@
+import type { NotificationHistory, NotificationPreferences, SendNotificationRequest, TelegramLinkResponse, TelegramStatusResponse, UserData } from "../types";
+export declare function setApiUrl(url: string): void;
+export declare function getApiUrl(): string;
+export declare const notificationsAPI: {
+    /**
+     * Register the current user (userId extracted from JWT)
+     */
+    registerUser(): Promise<any>;
+    /**
+     * Get current user's profile and preferences
+     */
+    getUser(): Promise<UserData>;
+    /**
+     * Get current user's notification history
+     */
+    getHistory(appId?: string, limit?: number): Promise<NotificationHistory[]>;
+    /**
+     * Add a notification channel for current user
+     */
+    addChannel(channelType: string, channelIdentifier: string, metadata?: Record<string, any>): Promise<any>;
+    /**
+     * Connect email for current user
+     */
+    connectEmail(email: string): Promise<any>;
+    /**
+     * Update a notification channel
+     */
+    updateChannel(channelId: string, updates: {
+        enabled?: boolean;
+        channelIdentifier?: string;
+        metadata?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * Delete a notification channel
+     */
+    deleteChannel(channelId: string): Promise<any>;
+    /**
+     * Get Telegram deep link for current user
+     */
+    getTelegramLink(): Promise<TelegramLinkResponse>;
+    /**
+     * Check current user's Telegram connection status
+     */
+    checkTelegramStatus(): Promise<TelegramStatusResponse>;
+    /**
+     * Save notification preferences for an app
+     * @param appId - The application ID
+     * @param settings - Notification preferences including channels, type, and enabled status (defaults to true)
+     */
+    savePreferences(appId: string, settings: NotificationPreferences): Promise<any>;
+    /**
+     * Get notification settings for an app
+     */
+    getAppSettings(appId: string): Promise<any>;
+    /**
+     * Get current user's in-app notifications
+     */
+    getInAppNotifications(): Promise<any>;
+    /**
+     * Mark a notification as read
+     */
+    markNotificationAsRead(notificationId: string): Promise<any>;
+    /**
+     * Send a notification (requires auth)
+     */
+    sendNotification(data: SendNotificationRequest): Promise<any>;
+};