krisspy-sdk 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -26,6 +26,20 @@ interface KrisspyClientOptions {
      * When false, uses legacy /data/* endpoints which require backend owner auth.
      */
     useRLS?: boolean;
+    /**
+     * Custom storage adapter for session persistence.
+     * Use this in React Native with AsyncStorage or MMKV.
+     * Falls back to localStorage (browser) or in-memory storage.
+     *
+     * @example
+     * import AsyncStorage from '@react-native-async-storage/async-storage'
+     * const krisspy = createClient({ ..., storage: AsyncStorage })
+     */
+    storage?: {
+        getItem(key: string): string | null | Promise<string | null>;
+        setItem(key: string, value: string): void | Promise<void>;
+        removeItem(key: string): void | Promise<void>;
+    };
 }
 interface User {
     id: string;
@@ -184,8 +198,24 @@ declare class HttpClient {
     delete<T>(path: string, params?: Record<string, any>): Promise<HttpResponse<T>>;
 }
 
+/**
+ * Platform detection and cross-platform utilities
+ * Safe to evaluate in any JS environment (browser, Node, React Native, Expo Snack)
+ */
+/** Storage adapter interface - allows custom storage (AsyncStorage, MMKV, etc.) */
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Check if running in a browser with DOM APIs */
+declare function isBrowser(): boolean;
+/** Check if running in React Native */
+declare function isReactNative(): boolean;
+
 /**
  * Auth Module - User authentication for Krisspy backends
+ * Compatible with Browser, React Native, and Node.js
  */
 
 declare class KrisspyAuth {
@@ -195,11 +225,13 @@ declare class KrisspyAuth {
     private currentUser;
     private listeners;
     private refreshInterval?;
-    constructor(http: HttpClient, backendId: string);
+    private storage;
+    constructor(http: HttpClient, backendId: string, storage?: StorageAdapter);
     /**
      * Get current session from storage
      */
     private restoreSession;
+    private hydrateSession;
     /**
      * Store session
      */
@@ -299,6 +331,7 @@ declare class KrisspyAuth {
     };
     /**
      * Set session from external source (e.g., OAuth callback)
+     * Browser-only: parses tokens from URL hash
      */
     setSessionFromUrl(): Promise<AuthResponse>;
 }
@@ -699,6 +732,80 @@ declare class KrisspyRealtime {
     private log;
 }
 
+/**
+ * Krisspy Analytics - Lightweight event tracking module
+ *
+ * Tracks page views, sessions, custom events. Sends batched events
+ * to the analytics ingest endpoint. Works with SPAs (intercepts pushState).
+ * Browser-only module - safely no-ops in React Native / Node.js.
+ *
+ * @example
+ * const krisspy = createClient({ backendId: '...', anonKey: '...' })
+ * krisspy.analytics.init({ autoTrackPageViews: true })
+ * krisspy.analytics.track('button_click', { label: 'signup' })
+ */
+
+interface AnalyticsInitOptions {
+    /** Auto-track page views on init + navigation (default: true) */
+    autoTrackPageViews?: boolean;
+    /** Auto-track SPA navigation via pushState/popstate (default: true) */
+    autoTrackNavigation?: boolean;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface AnalyticsEvent {
+    eventName: string;
+    sessionId: string;
+    userId?: string;
+    properties?: Record<string, any>;
+    timestamp: string;
+}
+declare class KrisspyAnalytics {
+    private http;
+    private backendId;
+    private queue;
+    private sessionId;
+    private userId;
+    private userTraits;
+    private initialized;
+    private flushTimer;
+    private options;
+    private originalPushState;
+    private popstateHandler;
+    private unloadHandler;
+    constructor(http: HttpClient, backendId: string);
+    /**
+     * Initialize analytics tracking
+     * No-ops in non-browser environments (React Native, Node.js)
+     */
+    init(options?: AnalyticsInitOptions): void;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: Record<string, any>): void;
+    /**
+     * Identify a user (attach userId + traits to all future events)
+     */
+    identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Flush event queue to the server (async)
+     */
+    flush(): Promise<void>;
+    /**
+     * Synchronous flush using sendBeacon (for page unload)
+     */
+    private flushSync;
+    /**
+     * Stop tracking and cleanup all listeners/timers
+     */
+    destroy(): void;
+    private getOrCreateSessionId;
+    private getIngestUrl;
+    private setupNavigationTracking;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -850,6 +957,7 @@ declare class KrisspyClient {
     private _auth;
     private _storage;
     private _realtime;
+    private _analytics;
     private useRLS;
     private debug;
     constructor(options: KrisspyClientOptions);
@@ -898,6 +1006,23 @@ declare class KrisspyClient {
      * const { error } = await krisspy.storage.from('uploads').remove(['old.jpg'])
      */
     get storage(): KrisspyStorage;
+    /**
+     * Analytics module for event tracking
+     *
+     * @example
+     * // Initialize tracking
+     * krisspy.analytics.init()
+     *
+     * // Track custom events
+     * krisspy.analytics.track('button_click', { label: 'signup' })
+     *
+     * // Identify a user
+     * krisspy.analytics.identify('user_123', { plan: 'pro' })
+     *
+     * // Cleanup
+     * krisspy.analytics.destroy()
+     */
+    get analytics(): KrisspyAnalytics;
     /**
      * Create a realtime channel for subscribing to database changes
      *
@@ -1081,4 +1206,4 @@ declare class KrisspyClient {
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, 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, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient };
+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 };

package/dist/index.d.ts

@@ -26,6 +26,20 @@ interface KrisspyClientOptions {
      * When false, uses legacy /data/* endpoints which require backend owner auth.
      */
     useRLS?: boolean;
+    /**
+     * Custom storage adapter for session persistence.
+     * Use this in React Native with AsyncStorage or MMKV.
+     * Falls back to localStorage (browser) or in-memory storage.
+     *
+     * @example
+     * import AsyncStorage from '@react-native-async-storage/async-storage'
+     * const krisspy = createClient({ ..., storage: AsyncStorage })
+     */
+    storage?: {
+        getItem(key: string): string | null | Promise<string | null>;
+        setItem(key: string, value: string): void | Promise<void>;
+        removeItem(key: string): void | Promise<void>;
+    };
 }
 interface User {
     id: string;
@@ -184,8 +198,24 @@ declare class HttpClient {
     delete<T>(path: string, params?: Record<string, any>): Promise<HttpResponse<T>>;
 }
 
+/**
+ * Platform detection and cross-platform utilities
+ * Safe to evaluate in any JS environment (browser, Node, React Native, Expo Snack)
+ */
+/** Storage adapter interface - allows custom storage (AsyncStorage, MMKV, etc.) */
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Check if running in a browser with DOM APIs */
+declare function isBrowser(): boolean;
+/** Check if running in React Native */
+declare function isReactNative(): boolean;
+
 /**
  * Auth Module - User authentication for Krisspy backends
+ * Compatible with Browser, React Native, and Node.js
  */
 
 declare class KrisspyAuth {
@@ -195,11 +225,13 @@ declare class KrisspyAuth {
     private currentUser;
     private listeners;
     private refreshInterval?;
-    constructor(http: HttpClient, backendId: string);
+    private storage;
+    constructor(http: HttpClient, backendId: string, storage?: StorageAdapter);
     /**
      * Get current session from storage
      */
     private restoreSession;
+    private hydrateSession;
     /**
      * Store session
      */
@@ -299,6 +331,7 @@ declare class KrisspyAuth {
     };
     /**
      * Set session from external source (e.g., OAuth callback)
+     * Browser-only: parses tokens from URL hash
      */
     setSessionFromUrl(): Promise<AuthResponse>;
 }
@@ -699,6 +732,80 @@ declare class KrisspyRealtime {
     private log;
 }
 
+/**
+ * Krisspy Analytics - Lightweight event tracking module
+ *
+ * Tracks page views, sessions, custom events. Sends batched events
+ * to the analytics ingest endpoint. Works with SPAs (intercepts pushState).
+ * Browser-only module - safely no-ops in React Native / Node.js.
+ *
+ * @example
+ * const krisspy = createClient({ backendId: '...', anonKey: '...' })
+ * krisspy.analytics.init({ autoTrackPageViews: true })
+ * krisspy.analytics.track('button_click', { label: 'signup' })
+ */
+
+interface AnalyticsInitOptions {
+    /** Auto-track page views on init + navigation (default: true) */
+    autoTrackPageViews?: boolean;
+    /** Auto-track SPA navigation via pushState/popstate (default: true) */
+    autoTrackNavigation?: boolean;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface AnalyticsEvent {
+    eventName: string;
+    sessionId: string;
+    userId?: string;
+    properties?: Record<string, any>;
+    timestamp: string;
+}
+declare class KrisspyAnalytics {
+    private http;
+    private backendId;
+    private queue;
+    private sessionId;
+    private userId;
+    private userTraits;
+    private initialized;
+    private flushTimer;
+    private options;
+    private originalPushState;
+    private popstateHandler;
+    private unloadHandler;
+    constructor(http: HttpClient, backendId: string);
+    /**
+     * Initialize analytics tracking
+     * No-ops in non-browser environments (React Native, Node.js)
+     */
+    init(options?: AnalyticsInitOptions): void;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: Record<string, any>): void;
+    /**
+     * Identify a user (attach userId + traits to all future events)
+     */
+    identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Flush event queue to the server (async)
+     */
+    flush(): Promise<void>;
+    /**
+     * Synchronous flush using sendBeacon (for page unload)
+     */
+    private flushSync;
+    /**
+     * Stop tracking and cleanup all listeners/timers
+     */
+    destroy(): void;
+    private getOrCreateSessionId;
+    private getIngestUrl;
+    private setupNavigationTracking;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -850,6 +957,7 @@ declare class KrisspyClient {
     private _auth;
     private _storage;
     private _realtime;
+    private _analytics;
     private useRLS;
     private debug;
     constructor(options: KrisspyClientOptions);
@@ -898,6 +1006,23 @@ declare class KrisspyClient {
      * const { error } = await krisspy.storage.from('uploads').remove(['old.jpg'])
      */
     get storage(): KrisspyStorage;
+    /**
+     * Analytics module for event tracking
+     *
+     * @example
+     * // Initialize tracking
+     * krisspy.analytics.init()
+     *
+     * // Track custom events
+     * krisspy.analytics.track('button_click', { label: 'signup' })
+     *
+     * // Identify a user
+     * krisspy.analytics.identify('user_123', { plan: 'pro' })
+     *
+     * // Cleanup
+     * krisspy.analytics.destroy()
+     */
+    get analytics(): KrisspyAnalytics;
     /**
      * Create a realtime channel for subscribing to database changes
      *
@@ -1081,4 +1206,4 @@ declare class KrisspyClient {
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, 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, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient };
+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 };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   HttpClient: () => HttpClient,
+  KrisspyAnalytics: () => KrisspyAnalytics,
   KrisspyAuth: () => KrisspyAuth,
   KrisspyClient: () => KrisspyClient,
   KrisspyRealtime: () => KrisspyRealtime,
@@ -28,7 +29,9 @@ __export(index_exports, {
   QueryBuilder: () => QueryBuilder,
   RealtimeChannel: () => RealtimeChannel,
   StorageBucket: () => StorageBucket,
-  createClient: () => createClient
+  createClient: () => createClient,
+  isBrowser: () => isBrowser,
+  isReactNative: () => isReactNative
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -161,43 +164,136 @@ var HttpClient = class {
   }
 };
 
+// src/platform.ts
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.document !== "undefined" && typeof window.document.createElement === "function";
+}
+function isReactNative() {
+  return typeof navigator !== "undefined" && typeof navigator.product === "string" && navigator.product === "ReactNative";
+}
+function getLocalStorage() {
+  if (!isBrowser()) return null;
+  try {
+    const testKey = "__krisspy_test__";
+    window.localStorage.setItem(testKey, "1");
+    window.localStorage.removeItem(testKey);
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+var MemoryStorage = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+};
+function resolveStorage(custom) {
+  if (custom) return custom;
+  return getLocalStorage() ?? new MemoryStorage();
+}
+function base64Encode(input) {
+  if (typeof btoa === "function") {
+    return btoa(input);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "binary").toString("base64");
+  }
+  return manualBase64Encode(input);
+}
+function base64Decode(input) {
+  if (typeof atob === "function") {
+    return atob(input);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "base64").toString("binary");
+  }
+  return manualBase64Decode(input);
+}
+var CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
+function manualBase64Encode(input) {
+  let output = "";
+  for (let i = 0; i < input.length; i += 3) {
+    const a = input.charCodeAt(i);
+    const b = i + 1 < input.length ? input.charCodeAt(i + 1) : 0;
+    const c = i + 2 < input.length ? input.charCodeAt(i + 2) : 0;
+    output += CHARS[a >> 2];
+    output += CHARS[(a & 3) << 4 | b >> 4];
+    output += i + 1 < input.length ? CHARS[(b & 15) << 2 | c >> 6] : "=";
+    output += i + 2 < input.length ? CHARS[c & 63] : "=";
+  }
+  return output;
+}
+function manualBase64Decode(input) {
+  let output = "";
+  const str = input.replace(/=+$/, "");
+  for (let i = 0; i < str.length; i += 4) {
+    const a = CHARS.indexOf(str[i]);
+    const b = CHARS.indexOf(str[i + 1]);
+    const c = CHARS.indexOf(str[i + 2]);
+    const d = CHARS.indexOf(str[i + 3]);
+    output += String.fromCharCode(a << 2 | b >> 4);
+    if (c !== -1) output += String.fromCharCode((b & 15) << 4 | c >> 2);
+    if (d !== -1) output += String.fromCharCode((c & 3) << 6 | d);
+  }
+  return output;
+}
+
 // src/auth.ts
 var STORAGE_KEY = "krisspy-auth-session";
 var KrisspyAuth = class {
-  constructor(http, backendId) {
+  constructor(http, backendId, storage) {
     this.currentSession = null;
     this.currentUser = null;
     this.listeners = [];
     this.http = http;
     this.backendId = backendId;
+    this.storage = resolveStorage(storage);
     this.restoreSession();
   }
   /**
    * Get current session from storage
    */
   restoreSession() {
-    if (typeof window === "undefined") return;
     try {
-      const stored = localStorage.getItem(`${STORAGE_KEY}-${this.backendId}`);
-      if (stored) {
-        const session = JSON.parse(stored);
-        if (session.expires_at && Date.now() > session.expires_at * 1e3) {
-          this.clearSession();
-          return;
-        }
-        this.setSession(session);
+      const result = this.storage.getItem(`${STORAGE_KEY}-${this.backendId}`);
+      if (result instanceof Promise) {
+        result.then((stored) => {
+          if (stored) this.hydrateSession(stored);
+        }).catch(() => {
+        });
+      } else if (result) {
+        this.hydrateSession(result);
       }
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to restore session:", err);
     }
   }
+  hydrateSession(stored) {
+    try {
+      const session = JSON.parse(stored);
+      if (session.expires_at && Date.now() > session.expires_at * 1e3) {
+        this.clearSession();
+        return;
+      }
+      this.setSession(session);
+    } catch {
+    }
+  }
   /**
    * Store session
    */
   saveSession(session) {
-    if (typeof window === "undefined") return;
     try {
-      localStorage.setItem(`${STORAGE_KEY}-${this.backendId}`, JSON.stringify(session));
+      this.storage.setItem(`${STORAGE_KEY}-${this.backendId}`, JSON.stringify(session));
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to save session:", err);
     }
@@ -213,8 +309,9 @@ var KrisspyAuth = class {
       clearInterval(this.refreshInterval);
       this.refreshInterval = void 0;
     }
-    if (typeof window !== "undefined") {
-      localStorage.removeItem(`${STORAGE_KEY}-${this.backendId}`);
+    try {
+      this.storage.removeItem(`${STORAGE_KEY}-${this.backendId}`);
+    } catch {
     }
   }
   /**
@@ -319,7 +416,7 @@ var KrisspyAuth = class {
     if (response.error) {
       return { data: null, error: response.error };
     }
-    if (typeof window !== "undefined" && response.data?.url) {
+    if (isBrowser() && response.data?.url) {
       window.location.href = response.data.url;
     }
     return { data: response.data, error: null };
@@ -442,9 +539,10 @@ var KrisspyAuth = class {
   }
   /**
    * Set session from external source (e.g., OAuth callback)
+   * Browser-only: parses tokens from URL hash
    */
   async setSessionFromUrl() {
-    if (typeof window === "undefined") {
+    if (!isBrowser()) {
       return { data: { user: null, session: null }, error: { message: "Not in browser" } };
     }
     const hash = window.location.hash.substring(1);
@@ -455,7 +553,7 @@ var KrisspyAuth = class {
       return { data: { user: null, session: null }, error: { message: "No access token in URL" } };
     }
     try {
-      const payload = JSON.parse(atob(accessToken.split(".")[1]));
+      const payload = JSON.parse(base64Decode(accessToken.split(".")[1]));
       const session = {
         access_token: accessToken,
         refresh_token: refreshToken ?? void 0,
@@ -763,27 +861,31 @@ var StorageBucket = class {
       };
     }
   }
-  // Helper: Convert Blob to base64
-  blobToBase64(blob) {
-    return new Promise((resolve, reject) => {
-      const reader = new FileReader();
-      reader.onloadend = () => {
-        const result = reader.result;
-        const base64 = result.includes(",") ? result.split(",")[1] : result;
-        resolve(base64);
-      };
-      reader.onerror = reject;
-      reader.readAsDataURL(blob);
-    });
+  // Helper: Convert Blob to base64 (cross-platform)
+  async blobToBase64(blob) {
+    if (typeof FileReader !== "undefined") {
+      return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onloadend = () => {
+          const result = reader.result;
+          const base64 = result.includes(",") ? result.split(",")[1] : result;
+          resolve(base64);
+        };
+        reader.onerror = reject;
+        reader.readAsDataURL(blob);
+      });
+    }
+    const buffer = await blob.arrayBuffer();
+    return this.arrayBufferToBase64(buffer);
   }
-  // Helper: Convert ArrayBuffer to base64
+  // Helper: Convert ArrayBuffer to base64 (cross-platform)
   arrayBufferToBase64(buffer) {
-    let binary = "";
     const bytes = new Uint8Array(buffer);
+    let binary = "";
     for (let i = 0; i < bytes.length; i++) {
       binary += String.fromCharCode(bytes[i]);
     }
-    return btoa(binary);
+    return base64Encode(binary);
   }
   // Helper: Detect MIME type from file extension
   detectMimeType(path) {
@@ -1144,6 +1246,188 @@ var KrisspyRealtime = class {
   }
 };
 
+// src/analytics.ts
+var KrisspyAnalytics = class {
+  constructor(http, backendId) {
+    this.queue = [];
+    this.sessionId = null;
+    this.userId = null;
+    this.userTraits = {};
+    this.initialized = false;
+    this.flushTimer = null;
+    this.options = {};
+    this.originalPushState = null;
+    this.popstateHandler = null;
+    this.unloadHandler = null;
+    this.http = http;
+    this.backendId = backendId;
+  }
+  /**
+   * Initialize analytics tracking
+   * No-ops in non-browser environments (React Native, Node.js)
+   */
+  init(options) {
+    if (this.initialized) return;
+    if (!isBrowser()) return;
+    this.options = {
+      autoTrackPageViews: true,
+      autoTrackNavigation: true,
+      flushInterval: 5e3,
+      debug: false,
+      ...options
+    };
+    this.sessionId = this.getOrCreateSessionId();
+    this.initialized = true;
+    if (this.options.autoTrackPageViews) {
+      this.track("session_start", {});
+      this.track("page_view", { url: window.location.href, referrer: document.referrer });
+    }
+    if (this.options.autoTrackNavigation) {
+      this.setupNavigationTracking();
+    }
+    this.unloadHandler = () => {
+      this.track("session_end", {});
+      this.flushSync();
+    };
+    window.addEventListener("beforeunload", this.unloadHandler);
+    this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Initialized", { backendId: this.backendId, sessionId: this.sessionId });
+    }
+  }
+  /**
+   * Track a custom event
+   */
+  track(eventName, properties) {
+    if (!this.initialized) return;
+    const event = {
+      eventName,
+      sessionId: this.sessionId,
+      userId: this.userId || void 0,
+      properties: {
+        ...properties,
+        ...this.userId ? { _user_traits: this.userTraits } : {}
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.queue.push(event);
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Tracked:", eventName, properties);
+    }
+  }
+  /**
+   * Identify a user (attach userId + traits to all future events)
+   */
+  identify(userId, traits) {
+    this.userId = userId;
+    this.userTraits = traits || {};
+    if (this.initialized) {
+      this.track("identify", { userId, ...traits });
+    }
+  }
+  /**
+   * Flush event queue to the server (async)
+   */
+  async flush() {
+    if (!this.queue.length) return;
+    const events = this.queue.splice(0, 50);
+    const payload = { appId: this.backendId, events };
+    try {
+      await this.http.post("/api/v1/analytics/events", payload);
+      if (this.options.debug) {
+        console.log(`[Krisspy Analytics] Flushed ${events.length} events`);
+      }
+    } catch {
+      this.queue.unshift(...events);
+    }
+  }
+  /**
+   * Synchronous flush using sendBeacon (for page unload)
+   */
+  flushSync() {
+    if (!this.queue.length) return;
+    if (!isBrowser()) return;
+    const events = this.queue.splice(0, 50);
+    const payload = JSON.stringify({ appId: this.backendId, events });
+    try {
+      if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+        const blob = new Blob([payload], { type: "application/json" });
+        navigator.sendBeacon(this.getIngestUrl(), blob);
+      } else {
+        fetch(this.getIngestUrl(), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: payload,
+          keepalive: true
+        }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Stop tracking and cleanup all listeners/timers
+   */
+  destroy() {
+    if (!this.initialized) return;
+    this.flushSync();
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (isBrowser()) {
+      if (this.originalPushState) {
+        history.pushState = this.originalPushState;
+        this.originalPushState = null;
+      }
+      if (this.popstateHandler) {
+        window.removeEventListener("popstate", this.popstateHandler);
+        this.popstateHandler = null;
+      }
+      if (this.unloadHandler) {
+        window.removeEventListener("beforeunload", this.unloadHandler);
+        this.unloadHandler = null;
+      }
+    }
+    this.initialized = false;
+    this.queue = [];
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Destroyed");
+    }
+  }
+  // -- Private helpers --------------------------------------------------------
+  getOrCreateSessionId() {
+    const key = "_ka_sid";
+    if (isBrowser()) {
+      try {
+        const existing = window.localStorage.getItem(key);
+        if (existing) return existing;
+        const id = Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+        window.localStorage.setItem(key, id);
+        return id;
+      } catch {
+      }
+    }
+    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+  }
+  getIngestUrl() {
+    return `${this.http.baseUrl}/api/v1/analytics/events`;
+  }
+  setupNavigationTracking() {
+    if (!isBrowser()) return;
+    this.originalPushState = history.pushState.bind(history);
+    const self = this;
+    history.pushState = function(...args) {
+      self.originalPushState(...args);
+      self.track("page_view", { url: window.location.href });
+    };
+    this.popstateHandler = () => {
+      this.track("page_view", { url: window.location.href });
+    };
+    window.addEventListener("popstate", this.popstateHandler);
+  }
+};
+
 // src/query-builder.ts
 var QueryBuilder = class {
   constructor(http, backendId, tableName, useRLS = true) {
@@ -1435,9 +1719,10 @@ var KrisspyClient = class {
       },
       debug: options.debug
     });
-    this._auth = new KrisspyAuth(this.http, this.backendId);
+    this._auth = new KrisspyAuth(this.http, this.backendId, options.storage);
     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._auth.onAuthStateChange((event) => {
       if (event === "SIGNED_IN") {
         const session = this._auth.session();
@@ -1498,6 +1783,25 @@ var KrisspyClient = class {
   get storage() {
     return this._storage;
   }
+  /**
+   * Analytics module for event tracking
+   *
+   * @example
+   * // Initialize tracking
+   * krisspy.analytics.init()
+   *
+   * // Track custom events
+   * krisspy.analytics.track('button_click', { label: 'signup' })
+   *
+   * // Identify a user
+   * krisspy.analytics.identify('user_123', { plan: 'pro' })
+   *
+   * // Cleanup
+   * krisspy.analytics.destroy()
+   */
+  get analytics() {
+    return this._analytics;
+  }
   /**
    * Create a realtime channel for subscribing to database changes
    *
@@ -1666,6 +1970,7 @@ function createClient(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HttpClient,
+  KrisspyAnalytics,
   KrisspyAuth,
   KrisspyClient,
   KrisspyRealtime,
@@ -1673,5 +1978,7 @@ function createClient(options) {
   QueryBuilder,
   RealtimeChannel,
   StorageBucket,
-  createClient
+  createClient,
+  isBrowser,
+  isReactNative
 });

package/dist/index.mjs

@@ -127,43 +127,136 @@ var HttpClient = class {
   }
 };
 
+// src/platform.ts
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.document !== "undefined" && typeof window.document.createElement === "function";
+}
+function isReactNative() {
+  return typeof navigator !== "undefined" && typeof navigator.product === "string" && navigator.product === "ReactNative";
+}
+function getLocalStorage() {
+  if (!isBrowser()) return null;
+  try {
+    const testKey = "__krisspy_test__";
+    window.localStorage.setItem(testKey, "1");
+    window.localStorage.removeItem(testKey);
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+var MemoryStorage = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+};
+function resolveStorage(custom) {
+  if (custom) return custom;
+  return getLocalStorage() ?? new MemoryStorage();
+}
+function base64Encode(input) {
+  if (typeof btoa === "function") {
+    return btoa(input);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "binary").toString("base64");
+  }
+  return manualBase64Encode(input);
+}
+function base64Decode(input) {
+  if (typeof atob === "function") {
+    return atob(input);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "base64").toString("binary");
+  }
+  return manualBase64Decode(input);
+}
+var CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
+function manualBase64Encode(input) {
+  let output = "";
+  for (let i = 0; i < input.length; i += 3) {
+    const a = input.charCodeAt(i);
+    const b = i + 1 < input.length ? input.charCodeAt(i + 1) : 0;
+    const c = i + 2 < input.length ? input.charCodeAt(i + 2) : 0;
+    output += CHARS[a >> 2];
+    output += CHARS[(a & 3) << 4 | b >> 4];
+    output += i + 1 < input.length ? CHARS[(b & 15) << 2 | c >> 6] : "=";
+    output += i + 2 < input.length ? CHARS[c & 63] : "=";
+  }
+  return output;
+}
+function manualBase64Decode(input) {
+  let output = "";
+  const str = input.replace(/=+$/, "");
+  for (let i = 0; i < str.length; i += 4) {
+    const a = CHARS.indexOf(str[i]);
+    const b = CHARS.indexOf(str[i + 1]);
+    const c = CHARS.indexOf(str[i + 2]);
+    const d = CHARS.indexOf(str[i + 3]);
+    output += String.fromCharCode(a << 2 | b >> 4);
+    if (c !== -1) output += String.fromCharCode((b & 15) << 4 | c >> 2);
+    if (d !== -1) output += String.fromCharCode((c & 3) << 6 | d);
+  }
+  return output;
+}
+
 // src/auth.ts
 var STORAGE_KEY = "krisspy-auth-session";
 var KrisspyAuth = class {
-  constructor(http, backendId) {
+  constructor(http, backendId, storage) {
     this.currentSession = null;
     this.currentUser = null;
     this.listeners = [];
     this.http = http;
     this.backendId = backendId;
+    this.storage = resolveStorage(storage);
     this.restoreSession();
   }
   /**
    * Get current session from storage
    */
   restoreSession() {
-    if (typeof window === "undefined") return;
     try {
-      const stored = localStorage.getItem(`${STORAGE_KEY}-${this.backendId}`);
-      if (stored) {
-        const session = JSON.parse(stored);
-        if (session.expires_at && Date.now() > session.expires_at * 1e3) {
-          this.clearSession();
-          return;
-        }
-        this.setSession(session);
+      const result = this.storage.getItem(`${STORAGE_KEY}-${this.backendId}`);
+      if (result instanceof Promise) {
+        result.then((stored) => {
+          if (stored) this.hydrateSession(stored);
+        }).catch(() => {
+        });
+      } else if (result) {
+        this.hydrateSession(result);
       }
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to restore session:", err);
     }
   }
+  hydrateSession(stored) {
+    try {
+      const session = JSON.parse(stored);
+      if (session.expires_at && Date.now() > session.expires_at * 1e3) {
+        this.clearSession();
+        return;
+      }
+      this.setSession(session);
+    } catch {
+    }
+  }
   /**
    * Store session
    */
   saveSession(session) {
-    if (typeof window === "undefined") return;
     try {
-      localStorage.setItem(`${STORAGE_KEY}-${this.backendId}`, JSON.stringify(session));
+      this.storage.setItem(`${STORAGE_KEY}-${this.backendId}`, JSON.stringify(session));
     } catch (err) {
       console.warn("[Krisspy Auth] Failed to save session:", err);
     }
@@ -179,8 +272,9 @@ var KrisspyAuth = class {
       clearInterval(this.refreshInterval);
       this.refreshInterval = void 0;
     }
-    if (typeof window !== "undefined") {
-      localStorage.removeItem(`${STORAGE_KEY}-${this.backendId}`);
+    try {
+      this.storage.removeItem(`${STORAGE_KEY}-${this.backendId}`);
+    } catch {
     }
   }
   /**
@@ -285,7 +379,7 @@ var KrisspyAuth = class {
     if (response.error) {
       return { data: null, error: response.error };
     }
-    if (typeof window !== "undefined" && response.data?.url) {
+    if (isBrowser() && response.data?.url) {
       window.location.href = response.data.url;
     }
     return { data: response.data, error: null };
@@ -408,9 +502,10 @@ var KrisspyAuth = class {
   }
   /**
    * Set session from external source (e.g., OAuth callback)
+   * Browser-only: parses tokens from URL hash
    */
   async setSessionFromUrl() {
-    if (typeof window === "undefined") {
+    if (!isBrowser()) {
       return { data: { user: null, session: null }, error: { message: "Not in browser" } };
     }
     const hash = window.location.hash.substring(1);
@@ -421,7 +516,7 @@ var KrisspyAuth = class {
       return { data: { user: null, session: null }, error: { message: "No access token in URL" } };
     }
     try {
-      const payload = JSON.parse(atob(accessToken.split(".")[1]));
+      const payload = JSON.parse(base64Decode(accessToken.split(".")[1]));
       const session = {
         access_token: accessToken,
         refresh_token: refreshToken ?? void 0,
@@ -729,27 +824,31 @@ var StorageBucket = class {
       };
     }
   }
-  // Helper: Convert Blob to base64
-  blobToBase64(blob) {
-    return new Promise((resolve, reject) => {
-      const reader = new FileReader();
-      reader.onloadend = () => {
-        const result = reader.result;
-        const base64 = result.includes(",") ? result.split(",")[1] : result;
-        resolve(base64);
-      };
-      reader.onerror = reject;
-      reader.readAsDataURL(blob);
-    });
+  // Helper: Convert Blob to base64 (cross-platform)
+  async blobToBase64(blob) {
+    if (typeof FileReader !== "undefined") {
+      return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onloadend = () => {
+          const result = reader.result;
+          const base64 = result.includes(",") ? result.split(",")[1] : result;
+          resolve(base64);
+        };
+        reader.onerror = reject;
+        reader.readAsDataURL(blob);
+      });
+    }
+    const buffer = await blob.arrayBuffer();
+    return this.arrayBufferToBase64(buffer);
   }
-  // Helper: Convert ArrayBuffer to base64
+  // Helper: Convert ArrayBuffer to base64 (cross-platform)
   arrayBufferToBase64(buffer) {
-    let binary = "";
     const bytes = new Uint8Array(buffer);
+    let binary = "";
     for (let i = 0; i < bytes.length; i++) {
       binary += String.fromCharCode(bytes[i]);
     }
-    return btoa(binary);
+    return base64Encode(binary);
   }
   // Helper: Detect MIME type from file extension
   detectMimeType(path) {
@@ -1110,6 +1209,188 @@ var KrisspyRealtime = class {
   }
 };
 
+// src/analytics.ts
+var KrisspyAnalytics = class {
+  constructor(http, backendId) {
+    this.queue = [];
+    this.sessionId = null;
+    this.userId = null;
+    this.userTraits = {};
+    this.initialized = false;
+    this.flushTimer = null;
+    this.options = {};
+    this.originalPushState = null;
+    this.popstateHandler = null;
+    this.unloadHandler = null;
+    this.http = http;
+    this.backendId = backendId;
+  }
+  /**
+   * Initialize analytics tracking
+   * No-ops in non-browser environments (React Native, Node.js)
+   */
+  init(options) {
+    if (this.initialized) return;
+    if (!isBrowser()) return;
+    this.options = {
+      autoTrackPageViews: true,
+      autoTrackNavigation: true,
+      flushInterval: 5e3,
+      debug: false,
+      ...options
+    };
+    this.sessionId = this.getOrCreateSessionId();
+    this.initialized = true;
+    if (this.options.autoTrackPageViews) {
+      this.track("session_start", {});
+      this.track("page_view", { url: window.location.href, referrer: document.referrer });
+    }
+    if (this.options.autoTrackNavigation) {
+      this.setupNavigationTracking();
+    }
+    this.unloadHandler = () => {
+      this.track("session_end", {});
+      this.flushSync();
+    };
+    window.addEventListener("beforeunload", this.unloadHandler);
+    this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Initialized", { backendId: this.backendId, sessionId: this.sessionId });
+    }
+  }
+  /**
+   * Track a custom event
+   */
+  track(eventName, properties) {
+    if (!this.initialized) return;
+    const event = {
+      eventName,
+      sessionId: this.sessionId,
+      userId: this.userId || void 0,
+      properties: {
+        ...properties,
+        ...this.userId ? { _user_traits: this.userTraits } : {}
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.queue.push(event);
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Tracked:", eventName, properties);
+    }
+  }
+  /**
+   * Identify a user (attach userId + traits to all future events)
+   */
+  identify(userId, traits) {
+    this.userId = userId;
+    this.userTraits = traits || {};
+    if (this.initialized) {
+      this.track("identify", { userId, ...traits });
+    }
+  }
+  /**
+   * Flush event queue to the server (async)
+   */
+  async flush() {
+    if (!this.queue.length) return;
+    const events = this.queue.splice(0, 50);
+    const payload = { appId: this.backendId, events };
+    try {
+      await this.http.post("/api/v1/analytics/events", payload);
+      if (this.options.debug) {
+        console.log(`[Krisspy Analytics] Flushed ${events.length} events`);
+      }
+    } catch {
+      this.queue.unshift(...events);
+    }
+  }
+  /**
+   * Synchronous flush using sendBeacon (for page unload)
+   */
+  flushSync() {
+    if (!this.queue.length) return;
+    if (!isBrowser()) return;
+    const events = this.queue.splice(0, 50);
+    const payload = JSON.stringify({ appId: this.backendId, events });
+    try {
+      if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+        const blob = new Blob([payload], { type: "application/json" });
+        navigator.sendBeacon(this.getIngestUrl(), blob);
+      } else {
+        fetch(this.getIngestUrl(), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: payload,
+          keepalive: true
+        }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Stop tracking and cleanup all listeners/timers
+   */
+  destroy() {
+    if (!this.initialized) return;
+    this.flushSync();
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (isBrowser()) {
+      if (this.originalPushState) {
+        history.pushState = this.originalPushState;
+        this.originalPushState = null;
+      }
+      if (this.popstateHandler) {
+        window.removeEventListener("popstate", this.popstateHandler);
+        this.popstateHandler = null;
+      }
+      if (this.unloadHandler) {
+        window.removeEventListener("beforeunload", this.unloadHandler);
+        this.unloadHandler = null;
+      }
+    }
+    this.initialized = false;
+    this.queue = [];
+    if (this.options.debug) {
+      console.log("[Krisspy Analytics] Destroyed");
+    }
+  }
+  // -- Private helpers --------------------------------------------------------
+  getOrCreateSessionId() {
+    const key = "_ka_sid";
+    if (isBrowser()) {
+      try {
+        const existing = window.localStorage.getItem(key);
+        if (existing) return existing;
+        const id = Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+        window.localStorage.setItem(key, id);
+        return id;
+      } catch {
+      }
+    }
+    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+  }
+  getIngestUrl() {
+    return `${this.http.baseUrl}/api/v1/analytics/events`;
+  }
+  setupNavigationTracking() {
+    if (!isBrowser()) return;
+    this.originalPushState = history.pushState.bind(history);
+    const self = this;
+    history.pushState = function(...args) {
+      self.originalPushState(...args);
+      self.track("page_view", { url: window.location.href });
+    };
+    this.popstateHandler = () => {
+      this.track("page_view", { url: window.location.href });
+    };
+    window.addEventListener("popstate", this.popstateHandler);
+  }
+};
+
 // src/query-builder.ts
 var QueryBuilder = class {
   constructor(http, backendId, tableName, useRLS = true) {
@@ -1401,9 +1682,10 @@ var KrisspyClient = class {
       },
       debug: options.debug
     });
-    this._auth = new KrisspyAuth(this.http, this.backendId);
+    this._auth = new KrisspyAuth(this.http, this.backendId, options.storage);
     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._auth.onAuthStateChange((event) => {
       if (event === "SIGNED_IN") {
         const session = this._auth.session();
@@ -1464,6 +1746,25 @@ var KrisspyClient = class {
   get storage() {
     return this._storage;
   }
+  /**
+   * Analytics module for event tracking
+   *
+   * @example
+   * // Initialize tracking
+   * krisspy.analytics.init()
+   *
+   * // Track custom events
+   * krisspy.analytics.track('button_click', { label: 'signup' })
+   *
+   * // Identify a user
+   * krisspy.analytics.identify('user_123', { plan: 'pro' })
+   *
+   * // Cleanup
+   * krisspy.analytics.destroy()
+   */
+  get analytics() {
+    return this._analytics;
+  }
   /**
    * Create a realtime channel for subscribing to database changes
    *
@@ -1631,6 +1932,7 @@ function createClient(options) {
 }
 export {
   HttpClient,
+  KrisspyAnalytics,
   KrisspyAuth,
   KrisspyClient,
   KrisspyRealtime,
@@ -1638,5 +1940,7 @@ export {
   QueryBuilder,
   RealtimeChannel,
   StorageBucket,
-  createClient
+  createClient,
+  isBrowser,
+  isReactNative
 };

package/package.json

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