krisspy-sdk 0.6.0 → 0.8.0

package/README.md

@@ -17,14 +17,37 @@ pnpm add @krisspy/sdk
 ## Quick Start
 
 ```typescript
-import { createClient } from '@krisspy/sdk'
+import { createClient } from 'krisspy-sdk'
 
 const krisspy = createClient({
   backendId: 'your-backend-id',
-  apiKey: 'your-api-key', // optional for public access
+  apiKey: 'your-api-key',
 })
 ```
 
+### React Native / Expo
+
+When using AsyncStorage, call `initialize()` before accessing auth state:
+
+```typescript
+import { createClient } from 'krisspy-sdk'
+import AsyncStorage from '@react-native-async-storage/async-storage'
+
+const krisspy = createClient({
+  backendId: 'your-backend-id',
+  apiKey: 'your-api-key',
+  storage: AsyncStorage,
+})
+
+// Required — waits for cached session to load from AsyncStorage
+await krisspy.initialize()
+
+// Now safe to use
+const user = krisspy.auth.user()
+```
+
+On web (localStorage is synchronous), `initialize()` resolves instantly — calling it is optional but harmless.
+
 ## Authentication
 
 ### Sign Up
@@ -227,15 +250,19 @@ console.log('Products:', data)
 const krisspy = createClient({
   // Required
   backendId: 'your-backend-id',
+  apiKey: 'your-api-key',
 
   // Optional
   url: 'https://api.krisspy.ai', // Custom API URL
-  apiKey: 'your-api-key',        // For authenticated requests
+  storage: AsyncStorage,          // React Native: session persistence
   headers: {                      // Custom headers
     'X-Custom-Header': 'value'
   },
   debug: true,                    // Enable debug logging
 })
+
+// React Native only — wait for cached session
+await krisspy.initialize()
 ```
 
 ## License

package/dist/index.d.mts

@@ -238,7 +238,16 @@ declare class KrisspyAuth {
     private listeners;
     private refreshInterval?;
     private storage;
+    /** Resolves when session restoration is complete (including async storage) */
+    private _initialized;
+    private _resolveInit;
     constructor(http: HttpClient, backendId: string, storage?: StorageAdapter);
+    /**
+     * Wait until session has been restored from storage.
+     * On web (localStorage), this resolves immediately.
+     * On React Native (AsyncStorage), this waits for the async read to complete.
+     */
+    initialize(): Promise<void>;
     /**
      * Get current session from storage
      */
@@ -818,6 +827,114 @@ declare class KrisspyAnalytics {
     private setupNavigationTracking;
 }
 
+/**
+ * Notifications Module - Expo Push Notifications for Krisspy backends
+ * Compatible with Expo Go, EAS builds, and bare React Native.
+ */
+
+interface PushToken {
+    id: string;
+    token: string;
+    platform?: string;
+    device_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface NotificationTicket {
+    id?: string;
+    status: 'ok' | 'error';
+    message?: string;
+    details?: {
+        error?: string;
+    };
+}
+interface SendNotificationParams {
+    /** Target user ID (required for send, omit for broadcast) */
+    userId?: string;
+    /** Notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Custom data payload (available in notification handler) */
+    data?: Record<string, any>;
+    /** Sound: 'default' or null to disable */
+    sound?: 'default' | null;
+    /** iOS badge count */
+    badge?: number;
+    /** Priority: 'default', 'normal', or 'high' */
+    priority?: 'default' | 'normal' | 'high';
+}
+declare class KrisspyNotifications {
+    private http;
+    private backendId;
+    constructor(http: HttpClient, backendId: string);
+    /**
+     * Register a push token for the current user.
+     * Call this after getting the ExpoPushToken from expo-notifications.
+     *
+     * @example
+     * import * as Notifications from 'expo-notifications'
+     * const { data: token } = await Notifications.getExpoPushTokenAsync()
+     * await krisspy.notifications.register(token, 'ios')
+     */
+    register(token: string, platform?: 'ios' | 'android' | 'web'): Promise<{
+        data: PushToken | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Unregister a push token (e.g., on sign out or when user disables notifications).
+     */
+    unregister(token: string): Promise<{
+        error: KrisspyError | null;
+    }>;
+    /**
+     * List all push tokens registered for the current user.
+     */
+    getTokens(): Promise<{
+        data: PushToken[] | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Send a push notification to a specific user.
+     * Requires service key (server-side only).
+     *
+     * @example
+     * // In an Azure Function / serverless function:
+     * const krisspy = createClient({ backendId: '...', apiKey: '...', serviceKey: process.env.SERVICE_KEY })
+     * await krisspy.notifications.send({
+     *   userId: 'user123',
+     *   title: 'New message',
+     *   body: 'You have a new message from Alice',
+     *   data: { screen: 'chat', chatId: '456' },
+     * })
+     */
+    send(params: SendNotificationParams & {
+        userId: string;
+    }): Promise<{
+        data: {
+            tickets: NotificationTicket[];
+        } | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Broadcast a push notification to all registered users.
+     * Requires service key (server-side only).
+     *
+     * @example
+     * await krisspy.notifications.broadcast({
+     *   title: 'App Update',
+     *   body: 'Version 2.0 is now available!',
+     * })
+     */
+    broadcast(params: SendNotificationParams): Promise<{
+        data: {
+            tickets: NotificationTicket[];
+            count: number;
+        } | null;
+        error: KrisspyError | null;
+    }>;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -972,9 +1089,21 @@ declare class KrisspyClient {
     private _storage;
     private _realtime;
     private _analytics;
+    private _notifications;
     private dataMode;
     private debug;
     constructor(options: KrisspyClientOptions);
+    /**
+     * Wait until the client is fully initialized (session restored from storage).
+     * **Required on React Native / Expo** when using AsyncStorage.
+     * On web (localStorage), this resolves instantly.
+     *
+     * @example
+     * const krisspy = createClient({ backendId: '...', apiKey: '...' });
+     * await krisspy.initialize(); // wait for cached session to load
+     * const user = krisspy.auth.user(); // now safe to use
+     */
+    initialize(): Promise<void>;
     /**
      * Auth module for user authentication
      *
@@ -1037,6 +1166,27 @@ declare class KrisspyClient {
      * krisspy.analytics.destroy()
      */
     get analytics(): KrisspyAnalytics;
+    /**
+     * Notifications module for Expo push notifications
+     *
+     * @example
+     * // Register push token (client-side, after getting token from expo-notifications)
+     * await krisspy.notifications.register(expoPushToken, 'ios')
+     *
+     * // Unregister on sign out
+     * await krisspy.notifications.unregister(expoPushToken)
+     *
+     * // Send to user (server-side, requires serviceKey)
+     * await krisspy.notifications.send({
+     *   userId: 'user123',
+     *   title: 'Hello',
+     *   body: 'You have a new message',
+     * })
+     *
+     * // Broadcast to all (server-side, requires serviceKey)
+     * await krisspy.notifications.broadcast({ title: 'Update', body: 'v2.0 released!' })
+     */
+    get notifications(): KrisspyNotifications;
     /**
      * Create a realtime channel for subscribing to database changes
      *
@@ -1213,12 +1363,20 @@ declare class KrisspyClient {
  * @returns KrisspyClient instance
  *
  * @example
+ * // Web (localStorage is sync — works immediately)
+ * const krisspy = createClient({
+ *   backendId: 'abc123',
+ *   apiKey: 'your-api-key',
+ * })
+ *
+ * // React Native / Expo (AsyncStorage is async — call initialize())
  * const krisspy = createClient({
  *   backendId: 'abc123',
  *   apiKey: 'your-api-key',
- *   url: 'https://krisspy-cloud-backend.thankfulhill-66fc9e74.westeurope.azurecontainerapps.io', // optional
+ *   storage: AsyncStorage,
  * })
+ * await krisspy.initialize() // wait for cached session to load
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AnalyticsEvent, type AnalyticsInitOptions, type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAnalytics, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyRealtime, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, type PostgresChangesConfig, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, type StorageAdapter, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient, isBrowser, isReactNative };
+export { type AnalyticsEvent, type AnalyticsInitOptions, type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAnalytics, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyNotifications, KrisspyRealtime, KrisspyStorage, type MutationResponse, type NotificationTicket, type OAuthProvider, type OrderBy, type PostgresChangesConfig, type PushToken, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type SendNotificationParams, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, type StorageAdapter, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient, isBrowser, isReactNative };

package/dist/index.d.ts

@@ -238,7 +238,16 @@ declare class KrisspyAuth {
     private listeners;
     private refreshInterval?;
     private storage;
+    /** Resolves when session restoration is complete (including async storage) */
+    private _initialized;
+    private _resolveInit;
     constructor(http: HttpClient, backendId: string, storage?: StorageAdapter);
+    /**
+     * Wait until session has been restored from storage.
+     * On web (localStorage), this resolves immediately.
+     * On React Native (AsyncStorage), this waits for the async read to complete.
+     */
+    initialize(): Promise<void>;
     /**
      * Get current session from storage
      */
@@ -818,6 +827,114 @@ declare class KrisspyAnalytics {
     private setupNavigationTracking;
 }
 
+/**
+ * Notifications Module - Expo Push Notifications for Krisspy backends
+ * Compatible with Expo Go, EAS builds, and bare React Native.
+ */
+
+interface PushToken {
+    id: string;
+    token: string;
+    platform?: string;
+    device_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface NotificationTicket {
+    id?: string;
+    status: 'ok' | 'error';
+    message?: string;
+    details?: {
+        error?: string;
+    };
+}
+interface SendNotificationParams {
+    /** Target user ID (required for send, omit for broadcast) */
+    userId?: string;
+    /** Notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Custom data payload (available in notification handler) */
+    data?: Record<string, any>;
+    /** Sound: 'default' or null to disable */
+    sound?: 'default' | null;
+    /** iOS badge count */
+    badge?: number;
+    /** Priority: 'default', 'normal', or 'high' */
+    priority?: 'default' | 'normal' | 'high';
+}
+declare class KrisspyNotifications {
+    private http;
+    private backendId;
+    constructor(http: HttpClient, backendId: string);
+    /**
+     * Register a push token for the current user.
+     * Call this after getting the ExpoPushToken from expo-notifications.
+     *
+     * @example
+     * import * as Notifications from 'expo-notifications'
+     * const { data: token } = await Notifications.getExpoPushTokenAsync()
+     * await krisspy.notifications.register(token, 'ios')
+     */
+    register(token: string, platform?: 'ios' | 'android' | 'web'): Promise<{
+        data: PushToken | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Unregister a push token (e.g., on sign out or when user disables notifications).
+     */
+    unregister(token: string): Promise<{
+        error: KrisspyError | null;
+    }>;
+    /**
+     * List all push tokens registered for the current user.
+     */
+    getTokens(): Promise<{
+        data: PushToken[] | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Send a push notification to a specific user.
+     * Requires service key (server-side only).
+     *
+     * @example
+     * // In an Azure Function / serverless function:
+     * const krisspy = createClient({ backendId: '...', apiKey: '...', serviceKey: process.env.SERVICE_KEY })
+     * await krisspy.notifications.send({
+     *   userId: 'user123',
+     *   title: 'New message',
+     *   body: 'You have a new message from Alice',
+     *   data: { screen: 'chat', chatId: '456' },
+     * })
+     */
+    send(params: SendNotificationParams & {
+        userId: string;
+    }): Promise<{
+        data: {
+            tickets: NotificationTicket[];
+        } | null;
+        error: KrisspyError | null;
+    }>;
+    /**
+     * Broadcast a push notification to all registered users.
+     * Requires service key (server-side only).
+     *
+     * @example
+     * await krisspy.notifications.broadcast({
+     *   title: 'App Update',
+     *   body: 'Version 2.0 is now available!',
+     * })
+     */
+    broadcast(params: SendNotificationParams): Promise<{
+        data: {
+            tickets: NotificationTicket[];
+            count: number;
+        } | null;
+        error: KrisspyError | null;
+    }>;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -972,9 +1089,21 @@ declare class KrisspyClient {
     private _storage;
     private _realtime;
     private _analytics;
+    private _notifications;
     private dataMode;
     private debug;
     constructor(options: KrisspyClientOptions);
+    /**
+     * Wait until the client is fully initialized (session restored from storage).
+     * **Required on React Native / Expo** when using AsyncStorage.
+     * On web (localStorage), this resolves instantly.
+     *
+     * @example
+     * const krisspy = createClient({ backendId: '...', apiKey: '...' });
+     * await krisspy.initialize(); // wait for cached session to load
+     * const user = krisspy.auth.user(); // now safe to use
+     */
+    initialize(): Promise<void>;
     /**
      * Auth module for user authentication
      *
@@ -1037,6 +1166,27 @@ declare class KrisspyClient {
      * krisspy.analytics.destroy()
      */
     get analytics(): KrisspyAnalytics;
+    /**
+     * Notifications module for Expo push notifications
+     *
+     * @example
+     * // Register push token (client-side, after getting token from expo-notifications)
+     * await krisspy.notifications.register(expoPushToken, 'ios')
+     *
+     * // Unregister on sign out
+     * await krisspy.notifications.unregister(expoPushToken)
+     *
+     * // Send to user (server-side, requires serviceKey)
+     * await krisspy.notifications.send({
+     *   userId: 'user123',
+     *   title: 'Hello',
+     *   body: 'You have a new message',
+     * })
+     *
+     * // Broadcast to all (server-side, requires serviceKey)
+     * await krisspy.notifications.broadcast({ title: 'Update', body: 'v2.0 released!' })
+     */
+    get notifications(): KrisspyNotifications;
     /**
      * Create a realtime channel for subscribing to database changes
      *
@@ -1213,12 +1363,20 @@ declare class KrisspyClient {
  * @returns KrisspyClient instance
  *
  * @example
+ * // Web (localStorage is sync — works immediately)
+ * const krisspy = createClient({
+ *   backendId: 'abc123',
+ *   apiKey: 'your-api-key',
+ * })
+ *
+ * // React Native / Expo (AsyncStorage is async — call initialize())
  * const krisspy = createClient({
  *   backendId: 'abc123',
  *   apiKey: 'your-api-key',
- *   url: 'https://krisspy-cloud-backend.thankfulhill-66fc9e74.westeurope.azurecontainerapps.io', // optional
+ *   storage: AsyncStorage,
  * })
+ * await krisspy.initialize() // wait for cached session to load
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AnalyticsEvent, type AnalyticsInitOptions, type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAnalytics, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyRealtime, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, type PostgresChangesConfig, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, type StorageAdapter, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient, isBrowser, isReactNative };
+export { type AnalyticsEvent, type AnalyticsInitOptions, type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAnalytics, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyNotifications, KrisspyRealtime, KrisspyStorage, type MutationResponse, type NotificationTicket, type OAuthProvider, type OrderBy, type PostgresChangesConfig, type PushToken, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type SendNotificationParams, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, type StorageAdapter, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient, isBrowser, isReactNative };

package/dist/index.js

@@ -41,6 +41,7 @@ __export(index_exports, {
   KrisspyAnalytics: () => KrisspyAnalytics,
   KrisspyAuth: () => KrisspyAuth,
   KrisspyClient: () => KrisspyClient,
+  KrisspyNotifications: () => KrisspyNotifications,
   KrisspyRealtime: () => KrisspyRealtime,
   KrisspyStorage: () => KrisspyStorage,
   QueryBuilder: () => QueryBuilder,
@@ -273,8 +274,19 @@ var KrisspyAuth = class {
     this.http = http;
     this.backendId = backendId;
     this.storage = resolveStorage(storage);
+    this._initialized = new Promise((resolve) => {
+      this._resolveInit = resolve;
+    });
     this.restoreSession();
   }
+  /**
+   * Wait until session has been restored from storage.
+   * On web (localStorage), this resolves immediately.
+   * On React Native (AsyncStorage), this waits for the async read to complete.
+   */
+  async initialize() {
+    return this._initialized;
+  }
   /**
    * Get current session from storage
    */
@@ -285,12 +297,18 @@ var KrisspyAuth = class {
         result.then((stored) => {
           if (stored) this.hydrateSession(stored);
         }).catch(() => {
+        }).finally(() => {
+          this._resolveInit();
         });
-      } else if (result) {
-        this.hydrateSession(result);
+      } else {
+        if (result) {
+          this.hydrateSession(result);
+        }
+        this._resolveInit();
       }
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to restore session:", err);
+      this._resolveInit();
     }
   }
   hydrateSession(stored) {
@@ -1454,6 +1472,96 @@ var KrisspyAnalytics = class {
   }
 };
 
+// src/notifications.ts
+var KrisspyNotifications = class {
+  constructor(http, backendId) {
+    this.http = http;
+    this.backendId = backendId;
+  }
+  // ── Client-side methods (app user JWT) ──
+  /**
+   * Register a push token for the current user.
+   * Call this after getting the ExpoPushToken from expo-notifications.
+   *
+   * @example
+   * import * as Notifications from 'expo-notifications'
+   * const { data: token } = await Notifications.getExpoPushTokenAsync()
+   * await krisspy.notifications.register(token, 'ios')
+   */
+  async register(token, platform) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/token`;
+    const response = await this.http.post(path, { token, platform });
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : null, error: null };
+  }
+  /**
+   * Unregister a push token (e.g., on sign out or when user disables notifications).
+   */
+  async unregister(token) {
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/unregister`;
+    const response = await this.http.post(path, { token });
+    return { error: response.error };
+  }
+  /**
+   * List all push tokens registered for the current user.
+   */
+  async getTokens() {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/tokens`;
+    const response = await this.http.get(path);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : [], error: null };
+  }
+  // ── Server-side methods (service key required) ──
+  /**
+   * Send a push notification to a specific user.
+   * Requires service key (server-side only).
+   *
+   * @example
+   * // In an Azure Function / serverless function:
+   * const krisspy = createClient({ backendId: '...', apiKey: '...', serviceKey: process.env.SERVICE_KEY })
+   * await krisspy.notifications.send({
+   *   userId: 'user123',
+   *   title: 'New message',
+   *   body: 'You have a new message from Alice',
+   *   data: { screen: 'chat', chatId: '456' },
+   * })
+   */
+  async send(params) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/send`;
+    const response = await this.http.post(path, params);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : { tickets: [] }, error: null };
+  }
+  /**
+   * Broadcast a push notification to all registered users.
+   * Requires service key (server-side only).
+   *
+   * @example
+   * await krisspy.notifications.broadcast({
+   *   title: 'App Update',
+   *   body: 'Version 2.0 is now available!',
+   * })
+   */
+  async broadcast(params) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/send-broadcast`;
+    const response = await this.http.post(path, params);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : { tickets: [], count: 0 }, error: null };
+  }
+};
+
 // src/query-builder.ts
 var QueryBuilder = class {
   constructor(http, backendId, tableName, dataMode = "rls") {
@@ -1769,6 +1877,7 @@ var KrisspyClient = class {
     this._storage = new KrisspyStorage(this.http, this.backendId);
     this._realtime = new KrisspyRealtime(this.baseUrl, this.backendId, this.debug);
     this._analytics = new KrisspyAnalytics(this.http, this.backendId);
+    this._notifications = new KrisspyNotifications(this.http, this.backendId);
     this._auth.onAuthStateChange((event) => {
       if (event === "SIGNED_IN") {
         const session = this._auth.session();
@@ -1780,6 +1889,19 @@ var KrisspyClient = class {
       }
     });
   }
+  /**
+   * Wait until the client is fully initialized (session restored from storage).
+   * **Required on React Native / Expo** when using AsyncStorage.
+   * On web (localStorage), this resolves instantly.
+   *
+   * @example
+   * const krisspy = createClient({ backendId: '...', apiKey: '...' });
+   * await krisspy.initialize(); // wait for cached session to load
+   * const user = krisspy.auth.user(); // now safe to use
+   */
+  async initialize() {
+    await this._auth.initialize();
+  }
   /**
    * Auth module for user authentication
    *
@@ -1848,6 +1970,29 @@ var KrisspyClient = class {
   get analytics() {
     return this._analytics;
   }
+  /**
+   * Notifications module for Expo push notifications
+   *
+   * @example
+   * // Register push token (client-side, after getting token from expo-notifications)
+   * await krisspy.notifications.register(expoPushToken, 'ios')
+   *
+   * // Unregister on sign out
+   * await krisspy.notifications.unregister(expoPushToken)
+   *
+   * // Send to user (server-side, requires serviceKey)
+   * await krisspy.notifications.send({
+   *   userId: 'user123',
+   *   title: 'Hello',
+   *   body: 'You have a new message',
+   * })
+   *
+   * // Broadcast to all (server-side, requires serviceKey)
+   * await krisspy.notifications.broadcast({ title: 'Update', body: 'v2.0 released!' })
+   */
+  get notifications() {
+    return this._notifications;
+  }
   /**
    * Create a realtime channel for subscribing to database changes
    *

package/dist/index.mjs

@@ -239,8 +239,19 @@ var KrisspyAuth = class {
     this.http = http;
     this.backendId = backendId;
     this.storage = resolveStorage(storage);
+    this._initialized = new Promise((resolve) => {
+      this._resolveInit = resolve;
+    });
     this.restoreSession();
   }
+  /**
+   * Wait until session has been restored from storage.
+   * On web (localStorage), this resolves immediately.
+   * On React Native (AsyncStorage), this waits for the async read to complete.
+   */
+  async initialize() {
+    return this._initialized;
+  }
   /**
    * Get current session from storage
    */
@@ -251,12 +262,18 @@ var KrisspyAuth = class {
         result.then((stored) => {
           if (stored) this.hydrateSession(stored);
         }).catch(() => {
+        }).finally(() => {
+          this._resolveInit();
         });
-      } else if (result) {
-        this.hydrateSession(result);
+      } else {
+        if (result) {
+          this.hydrateSession(result);
+        }
+        this._resolveInit();
       }
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to restore session:", err);
+      this._resolveInit();
     }
   }
   hydrateSession(stored) {
@@ -1420,6 +1437,96 @@ var KrisspyAnalytics = class {
   }
 };
 
+// src/notifications.ts
+var KrisspyNotifications = class {
+  constructor(http, backendId) {
+    this.http = http;
+    this.backendId = backendId;
+  }
+  // ── Client-side methods (app user JWT) ──
+  /**
+   * Register a push token for the current user.
+   * Call this after getting the ExpoPushToken from expo-notifications.
+   *
+   * @example
+   * import * as Notifications from 'expo-notifications'
+   * const { data: token } = await Notifications.getExpoPushTokenAsync()
+   * await krisspy.notifications.register(token, 'ios')
+   */
+  async register(token, platform) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/token`;
+    const response = await this.http.post(path, { token, platform });
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : null, error: null };
+  }
+  /**
+   * Unregister a push token (e.g., on sign out or when user disables notifications).
+   */
+  async unregister(token) {
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/unregister`;
+    const response = await this.http.post(path, { token });
+    return { error: response.error };
+  }
+  /**
+   * List all push tokens registered for the current user.
+   */
+  async getTokens() {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/tokens`;
+    const response = await this.http.get(path);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : [], error: null };
+  }
+  // ── Server-side methods (service key required) ──
+  /**
+   * Send a push notification to a specific user.
+   * Requires service key (server-side only).
+   *
+   * @example
+   * // In an Azure Function / serverless function:
+   * const krisspy = createClient({ backendId: '...', apiKey: '...', serviceKey: process.env.SERVICE_KEY })
+   * await krisspy.notifications.send({
+   *   userId: 'user123',
+   *   title: 'New message',
+   *   body: 'You have a new message from Alice',
+   *   data: { screen: 'chat', chatId: '456' },
+   * })
+   */
+  async send(params) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/send`;
+    const response = await this.http.post(path, params);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : { tickets: [] }, error: null };
+  }
+  /**
+   * Broadcast a push notification to all registered users.
+   * Requires service key (server-side only).
+   *
+   * @example
+   * await krisspy.notifications.broadcast({
+   *   title: 'App Update',
+   *   body: 'Version 2.0 is now available!',
+   * })
+   */
+  async broadcast(params) {
+    var _a, _b;
+    const path = `/api/v1/cloud-backends/${this.backendId}/notifications/send-broadcast`;
+    const response = await this.http.post(path, params);
+    if (response.error) {
+      return { data: null, error: response.error };
+    }
+    return { data: (_b = (_a = response.data) == null ? void 0 : _a.data) != null ? _b : { tickets: [], count: 0 }, error: null };
+  }
+};
+
 // src/query-builder.ts
 var QueryBuilder = class {
   constructor(http, backendId, tableName, dataMode = "rls") {
@@ -1735,6 +1842,7 @@ var KrisspyClient = class {
     this._storage = new KrisspyStorage(this.http, this.backendId);
     this._realtime = new KrisspyRealtime(this.baseUrl, this.backendId, this.debug);
     this._analytics = new KrisspyAnalytics(this.http, this.backendId);
+    this._notifications = new KrisspyNotifications(this.http, this.backendId);
     this._auth.onAuthStateChange((event) => {
       if (event === "SIGNED_IN") {
         const session = this._auth.session();
@@ -1746,6 +1854,19 @@ var KrisspyClient = class {
       }
     });
   }
+  /**
+   * Wait until the client is fully initialized (session restored from storage).
+   * **Required on React Native / Expo** when using AsyncStorage.
+   * On web (localStorage), this resolves instantly.
+   *
+   * @example
+   * const krisspy = createClient({ backendId: '...', apiKey: '...' });
+   * await krisspy.initialize(); // wait for cached session to load
+   * const user = krisspy.auth.user(); // now safe to use
+   */
+  async initialize() {
+    await this._auth.initialize();
+  }
   /**
    * Auth module for user authentication
    *
@@ -1814,6 +1935,29 @@ var KrisspyClient = class {
   get analytics() {
     return this._analytics;
   }
+  /**
+   * Notifications module for Expo push notifications
+   *
+   * @example
+   * // Register push token (client-side, after getting token from expo-notifications)
+   * await krisspy.notifications.register(expoPushToken, 'ios')
+   *
+   * // Unregister on sign out
+   * await krisspy.notifications.unregister(expoPushToken)
+   *
+   * // Send to user (server-side, requires serviceKey)
+   * await krisspy.notifications.send({
+   *   userId: 'user123',
+   *   title: 'Hello',
+   *   body: 'You have a new message',
+   * })
+   *
+   * // Broadcast to all (server-side, requires serviceKey)
+   * await krisspy.notifications.broadcast({ title: 'Update', body: 'v2.0 released!' })
+   */
+  get notifications() {
+    return this._notifications;
+  }
   /**
    * Create a realtime channel for subscribing to database changes
    *
@@ -2014,6 +2158,7 @@ export {
   KrisspyAnalytics,
   KrisspyAuth,
   KrisspyClient,
+  KrisspyNotifications,
   KrisspyRealtime,
   KrisspyStorage,
   QueryBuilder,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "krisspy-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Krisspy Cloud SDK - Database, Auth, Storage, and Functions for your apps",
   "main": "dist/index.js",
   "module": "dist/index.mjs",