krisspy-sdk 0.5.6 → 0.7.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

@@ -12,18 +12,30 @@ interface KrisspyClientOptions {
      * Get it from your backend settings in the Krisspy dashboard.
      */
     apiKey: string;
+    /**
+     * Service key for server-side access (bypasses RLS).
+     * NEVER expose this in frontend code. Use only in server-side code (Azure Functions, Node.js, etc.)
+     * When provided, uses /service/data/* endpoints which bypass row-level security.
+     */
+    serviceKey?: string;
+    /**
+     * Base URL of your Azure Function App.
+     * When set, functions.invoke() calls the Azure Function directly
+     * instead of going through the Krisspy backend.
+     *
+     * @example 'https://krisspy-kb-abc123.azurewebsites.net'
+     */
+    functionsUrl?: string;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Enable debug logging */
     debug?: boolean;
     /**
      * Use RLS (Row Level Security) endpoints for data access
-     * Default: true
+     * Default: true (uses /rls/data/* with apiKey)
      *
-     * When true, uses /rls/data/* endpoints which require app user authentication
-     * and enforce row-level security policies.
-     *
-     * When false, uses legacy /data/* endpoints which require backend owner auth.
+     * Automatically set to false when serviceKey is provided
+     * (uses /service/data/* which bypasses RLS).
      */
     useRLS?: boolean;
     /**
@@ -226,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
      */
@@ -820,12 +841,13 @@ declare class QueryBuilder<T = any> {
     private limitValue?;
     private offsetValue?;
     private isSingle;
-    private useRLS;
-    constructor(http: HttpClient, backendId: string, tableName: string, useRLS?: boolean);
+    private dataMode;
+    constructor(http: HttpClient, backendId: string, tableName: string, dataMode?: 'rls' | 'service' | 'legacy');
     /**
      * Get the base path for data endpoints
-     * Uses /rls/data for RLS-enabled queries (requires auth)
-     * Uses /data for legacy queries (admin/owner only)
+     * - rls: /rls/data (requires apiKey + optional JWT, enforces RLS)
+     * - service: /service/data (requires serviceKey, bypasses RLS)
+     * - legacy: /data (requires backend owner auth)
      */
     private getBasePath;
     /**
@@ -954,13 +976,25 @@ declare class KrisspyClient {
     private http;
     private backendId;
     private baseUrl;
+    private functionsUrl;
     private _auth;
     private _storage;
     private _realtime;
     private _analytics;
-    private useRLS;
+    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
      *
@@ -1199,11 +1233,19 @@ 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;
 

package/dist/index.d.ts

@@ -12,18 +12,30 @@ interface KrisspyClientOptions {
      * Get it from your backend settings in the Krisspy dashboard.
      */
     apiKey: string;
+    /**
+     * Service key for server-side access (bypasses RLS).
+     * NEVER expose this in frontend code. Use only in server-side code (Azure Functions, Node.js, etc.)
+     * When provided, uses /service/data/* endpoints which bypass row-level security.
+     */
+    serviceKey?: string;
+    /**
+     * Base URL of your Azure Function App.
+     * When set, functions.invoke() calls the Azure Function directly
+     * instead of going through the Krisspy backend.
+     *
+     * @example 'https://krisspy-kb-abc123.azurewebsites.net'
+     */
+    functionsUrl?: string;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Enable debug logging */
     debug?: boolean;
     /**
      * Use RLS (Row Level Security) endpoints for data access
-     * Default: true
+     * Default: true (uses /rls/data/* with apiKey)
      *
-     * When true, uses /rls/data/* endpoints which require app user authentication
-     * and enforce row-level security policies.
-     *
-     * When false, uses legacy /data/* endpoints which require backend owner auth.
+     * Automatically set to false when serviceKey is provided
+     * (uses /service/data/* which bypasses RLS).
      */
     useRLS?: boolean;
     /**
@@ -226,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
      */
@@ -820,12 +841,13 @@ declare class QueryBuilder<T = any> {
     private limitValue?;
     private offsetValue?;
     private isSingle;
-    private useRLS;
-    constructor(http: HttpClient, backendId: string, tableName: string, useRLS?: boolean);
+    private dataMode;
+    constructor(http: HttpClient, backendId: string, tableName: string, dataMode?: 'rls' | 'service' | 'legacy');
     /**
      * Get the base path for data endpoints
-     * Uses /rls/data for RLS-enabled queries (requires auth)
-     * Uses /data for legacy queries (admin/owner only)
+     * - rls: /rls/data (requires apiKey + optional JWT, enforces RLS)
+     * - service: /service/data (requires serviceKey, bypasses RLS)
+     * - legacy: /data (requires backend owner auth)
      */
     private getBasePath;
     /**
@@ -954,13 +976,25 @@ declare class KrisspyClient {
     private http;
     private backendId;
     private baseUrl;
+    private functionsUrl;
     private _auth;
     private _storage;
     private _realtime;
     private _analytics;
-    private useRLS;
+    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
      *
@@ -1199,11 +1233,19 @@ 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;
 

package/dist/index.js

@@ -273,8 +273,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 +296,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) {
@@ -1456,7 +1473,7 @@ var KrisspyAnalytics = class {
 
 // src/query-builder.ts
 var QueryBuilder = class {
-  constructor(http, backendId, tableName, useRLS = true) {
+  constructor(http, backendId, tableName, dataMode = "rls") {
     this.queryParams = {};
     this.selectColumns = [];
     this.orderClauses = [];
@@ -1464,18 +1481,23 @@ var QueryBuilder = class {
     this.http = http;
     this.backendId = backendId;
     this.tableName = tableName;
-    this.useRLS = useRLS;
+    this.dataMode = dataMode;
   }
   /**
    * Get the base path for data endpoints
-   * Uses /rls/data for RLS-enabled queries (requires auth)
-   * Uses /data for legacy queries (admin/owner only)
+   * - rls: /rls/data (requires apiKey + optional JWT, enforces RLS)
+   * - service: /service/data (requires serviceKey, bypasses RLS)
+   * - legacy: /data (requires backend owner auth)
    */
   getBasePath() {
-    if (this.useRLS) {
-      return `/api/v1/cloud-backends/${this.backendId}/rls/data/${this.tableName}`;
+    const base = `/api/v1/cloud-backends/${this.backendId}`;
+    if (this.dataMode === "service") {
+      return `${base}/service/data/${this.tableName}`;
+    }
+    if (this.dataMode === "legacy") {
+      return `${base}/data/${this.tableName}`;
     }
-    return `/api/v1/cloud-backends/${this.backendId}/data/${this.tableName}`;
+    return `${base}/rls/data/${this.tableName}`;
   }
   /**
    * Select specific columns
@@ -1737,15 +1759,27 @@ var QueryBuilder = class {
 // src/client.ts
 var KrisspyClient = class {
   constructor(options) {
+    var _a;
     this.baseUrl = options.url || "https://krisspy-cloud-backend.thankfulhill-66fc9e74.westeurope.azurecontainerapps.io";
     this.backendId = options.backendId;
     this.debug = options.debug || false;
-    this.useRLS = options.useRLS !== false;
+    this.functionsUrl = ((_a = options.functionsUrl) == null ? void 0 : _a.replace(/\/$/, "")) || null;
+    if (options.serviceKey) {
+      this.dataMode = "service";
+    } else if (options.useRLS === false) {
+      this.dataMode = "legacy";
+    } else {
+      this.dataMode = "rls";
+    }
+    const keyHeaders = {
+      "apikey": options.apiKey
+    };
+    if (options.serviceKey) {
+      keyHeaders["servicekey"] = options.serviceKey;
+    }
     this.http = new HttpClient({
       baseUrl: this.baseUrl,
-      headers: __spreadProps(__spreadValues({}, options.headers), {
-        "apikey": options.apiKey
-      }),
+      headers: __spreadValues(__spreadValues({}, options.headers), keyHeaders),
       debug: options.debug
     });
     this._auth = new KrisspyAuth(this.http, this.backendId, options.storage);
@@ -1763,6 +1797,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
    *
@@ -1913,7 +1960,7 @@ var KrisspyClient = class {
    *   .eq('id', 123)
    */
   from(table) {
-    return new QueryBuilder(this.http, this.backendId, table, this.useRLS);
+    return new QueryBuilder(this.http, this.backendId, table, this.dataMode);
   }
   /**
    * Execute raw SQL query
@@ -1923,7 +1970,8 @@ var KrisspyClient = class {
    */
   async rpc(sql, params) {
     var _a, _b;
-    const path = `/api/v1/cloud-backends/${this.backendId}/sql`;
+    const suffix = this.dataMode === "service" ? "/service/sql" : "/sql";
+    const path = `/api/v1/cloud-backends/${this.backendId}${suffix}`;
     const response = await this.http.post(path, { sql, params });
     if (response.error) {
       return { data: null, error: response.error };
@@ -1941,6 +1989,31 @@ var KrisspyClient = class {
   get functions() {
     return {
       invoke: async (functionName, options) => {
+        if (this.functionsUrl) {
+          const url = `${this.functionsUrl}/api/${functionName}`;
+          try {
+            const res = await fetch(url, {
+              method: "POST",
+              headers: __spreadValues({
+                "Content-Type": "application/json"
+              }, options == null ? void 0 : options.headers),
+              body: (options == null ? void 0 : options.body) ? JSON.stringify(options.body) : void 0
+            });
+            const contentType = res.headers.get("content-type");
+            let data = null;
+            if (contentType == null ? void 0 : contentType.includes("application/json")) {
+              data = await res.json();
+            } else {
+              data = await res.text();
+            }
+            if (!res.ok) {
+              return { data: null, error: { message: (data == null ? void 0 : data.error) || (data == null ? void 0 : data.message) || `Request failed with status ${res.status}`, status: res.status } };
+            }
+            return { data, error: null };
+          } catch (err) {
+            return { data: null, error: { message: err.message || "Network error", code: "NETWORK_ERROR", status: 0 } };
+          }
+        }
         const path = `/api/v1/cloud-backends/${this.backendId}/functions/${functionName}/invoke`;
         const response = await this.http.post(path, options == null ? void 0 : options.body, void 0);
         if (response.error) {

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) {
@@ -1422,7 +1439,7 @@ var KrisspyAnalytics = class {
 
 // src/query-builder.ts
 var QueryBuilder = class {
-  constructor(http, backendId, tableName, useRLS = true) {
+  constructor(http, backendId, tableName, dataMode = "rls") {
     this.queryParams = {};
     this.selectColumns = [];
     this.orderClauses = [];
@@ -1430,18 +1447,23 @@ var QueryBuilder = class {
     this.http = http;
     this.backendId = backendId;
     this.tableName = tableName;
-    this.useRLS = useRLS;
+    this.dataMode = dataMode;
   }
   /**
    * Get the base path for data endpoints
-   * Uses /rls/data for RLS-enabled queries (requires auth)
-   * Uses /data for legacy queries (admin/owner only)
+   * - rls: /rls/data (requires apiKey + optional JWT, enforces RLS)
+   * - service: /service/data (requires serviceKey, bypasses RLS)
+   * - legacy: /data (requires backend owner auth)
    */
   getBasePath() {
-    if (this.useRLS) {
-      return `/api/v1/cloud-backends/${this.backendId}/rls/data/${this.tableName}`;
+    const base = `/api/v1/cloud-backends/${this.backendId}`;
+    if (this.dataMode === "service") {
+      return `${base}/service/data/${this.tableName}`;
+    }
+    if (this.dataMode === "legacy") {
+      return `${base}/data/${this.tableName}`;
     }
-    return `/api/v1/cloud-backends/${this.backendId}/data/${this.tableName}`;
+    return `${base}/rls/data/${this.tableName}`;
   }
   /**
    * Select specific columns
@@ -1703,15 +1725,27 @@ var QueryBuilder = class {
 // src/client.ts
 var KrisspyClient = class {
   constructor(options) {
+    var _a;
     this.baseUrl = options.url || "https://krisspy-cloud-backend.thankfulhill-66fc9e74.westeurope.azurecontainerapps.io";
     this.backendId = options.backendId;
     this.debug = options.debug || false;
-    this.useRLS = options.useRLS !== false;
+    this.functionsUrl = ((_a = options.functionsUrl) == null ? void 0 : _a.replace(/\/$/, "")) || null;
+    if (options.serviceKey) {
+      this.dataMode = "service";
+    } else if (options.useRLS === false) {
+      this.dataMode = "legacy";
+    } else {
+      this.dataMode = "rls";
+    }
+    const keyHeaders = {
+      "apikey": options.apiKey
+    };
+    if (options.serviceKey) {
+      keyHeaders["servicekey"] = options.serviceKey;
+    }
     this.http = new HttpClient({
       baseUrl: this.baseUrl,
-      headers: __spreadProps(__spreadValues({}, options.headers), {
-        "apikey": options.apiKey
-      }),
+      headers: __spreadValues(__spreadValues({}, options.headers), keyHeaders),
       debug: options.debug
     });
     this._auth = new KrisspyAuth(this.http, this.backendId, options.storage);
@@ -1729,6 +1763,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
    *
@@ -1879,7 +1926,7 @@ var KrisspyClient = class {
    *   .eq('id', 123)
    */
   from(table) {
-    return new QueryBuilder(this.http, this.backendId, table, this.useRLS);
+    return new QueryBuilder(this.http, this.backendId, table, this.dataMode);
   }
   /**
    * Execute raw SQL query
@@ -1889,7 +1936,8 @@ var KrisspyClient = class {
    */
   async rpc(sql, params) {
     var _a, _b;
-    const path = `/api/v1/cloud-backends/${this.backendId}/sql`;
+    const suffix = this.dataMode === "service" ? "/service/sql" : "/sql";
+    const path = `/api/v1/cloud-backends/${this.backendId}${suffix}`;
     const response = await this.http.post(path, { sql, params });
     if (response.error) {
       return { data: null, error: response.error };
@@ -1907,6 +1955,31 @@ var KrisspyClient = class {
   get functions() {
     return {
       invoke: async (functionName, options) => {
+        if (this.functionsUrl) {
+          const url = `${this.functionsUrl}/api/${functionName}`;
+          try {
+            const res = await fetch(url, {
+              method: "POST",
+              headers: __spreadValues({
+                "Content-Type": "application/json"
+              }, options == null ? void 0 : options.headers),
+              body: (options == null ? void 0 : options.body) ? JSON.stringify(options.body) : void 0
+            });
+            const contentType = res.headers.get("content-type");
+            let data = null;
+            if (contentType == null ? void 0 : contentType.includes("application/json")) {
+              data = await res.json();
+            } else {
+              data = await res.text();
+            }
+            if (!res.ok) {
+              return { data: null, error: { message: (data == null ? void 0 : data.error) || (data == null ? void 0 : data.message) || `Request failed with status ${res.status}`, status: res.status } };
+            }
+            return { data, error: null };
+          } catch (err) {
+            return { data: null, error: { message: err.message || "Network error", code: "NETWORK_ERROR", status: 0 } };
+          }
+        }
         const path = `/api/v1/cloud-backends/${this.backendId}/functions/${functionName}/invoke`;
         const response = await this.http.post(path, options == null ? void 0 : options.body, void 0);
         if (response.error) {

package/package.json

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