@baasix/sdk 0.1.18 → 0.1.20

package/README.md

@@ -9,7 +9,7 @@ Official JavaScript/TypeScript SDK for [Baasix](https://www.baasix.com) Backend-
 ## Features
 
 - 🌐 **Universal** - Works in browsers, Node.js, and React Native
-- 🔐 **Flexible Auth** - JWT tokens, HTTP-only cookies, OAuth (Google, Facebook, Apple, GitHub)
+- 🔐 **Flexible Auth** - JWT tokens, HTTP-only cookies, 35+ OAuth providers (Google, GitHub, Discord, Microsoft, Slack, and more), passkeys (WebAuthn), and 2FA (TOTP + backup codes)
 - 💾 **Customizable Storage** - LocalStorage, AsyncStorage, or custom adapters
 - 📝 **Type-Safe** - Full TypeScript support with generics
 - 🔄 **Auto Token Refresh** - Seamless token management
@@ -23,6 +23,7 @@ Official JavaScript/TypeScript SDK for [Baasix](https://www.baasix.com) Backend-
 - 🔔 **Notifications** - User notification system with realtime delivery
 - 🗃️ **Migrations** - Database schema migration management
 - 🔃 **Sort/Reorder** - Drag-and-drop style item reordering
+- 🧩 **App Builder** - Create and manage pages & blocks via the items API
 
 ## Installation
 
@@ -416,6 +417,65 @@ const results = await baasix.items('orders').aggregate({
 });
 ```
 
+## App Builder (Pages & Blocks)
+
+The Baasix [App Builder](https://baasix.dev/docs/guides/app-builder) lets admins compose internal
+tools from 27 data-bound block types (tables, wizard forms, kanban, charts, tabs, modals, reports,
+and more) with cross-block reactivity on a 12-column grid. Pages and blocks are stored in the
+`baasix_Page` and `baasix_Block` system collections, so you manage them with the **same `items()`
+API** — no special client. Block `config` is validated server-side on every create and update.
+
+```typescript
+// Create a page
+const page = await baasix.items('baasix_Page').create({
+  name: 'Operations',
+  slug: 'operations', // unique per tenant; used in /pages/?slug=operations
+  icon: 'gauge',
+});
+
+// Add a table block bound to the orders collection
+await baasix.items('baasix_Block').create({
+  page_Id: page.id,
+  type: 'table',
+  collection: 'orders',
+  position: { row: 0, col: 0, span: 8 }, // 12-column grid: row, col, span
+  config: {
+    columns: [{ field: 'id' }, { field: 'customer' }, { field: 'total' }],
+    filter: { status: { eq: 'open' } },
+    sort: 'createdAt:desc',
+    actions: { create: true, edit: true, view: true },
+  },
+});
+
+// Add a status chart beside it
+await baasix.items('baasix_Block').create({
+  page_Id: page.id,
+  type: 'chart',
+  collection: 'orders',
+  position: { row: 0, col: 8, span: 4 },
+  config: {
+    chartType: 'doughnut',
+    aggregate: { count: { function: 'count', field: 'id' } },
+    groupBy: ['status'],
+  },
+});
+
+// List all blocks on a page
+const blocks = await baasix.items('baasix_Block')
+  .filter({ page_Id: { eq: page.id } })
+  .get();
+```
+
+> **Block types (27):** data — `table`, `form`, `details`, `kanban`, `calendar`, `chart`, `cardlist`,
+> `map` (Leaflet or Google Maps), `geochart`, `media`, `feed`, `timeline`, `progress`, `repeater`,
+> `report`, `filter`; layout — `tabs`, `container`, `modal`, `divider` (children carry
+> `parentBlock_Id` + `slot`); content & input — `markdown`, `richtext`, `buttons`, `input`,
+> `iframe`, `upload`, `code`.
+> Filters in any block config use the same filter DSL as the items API, plus the runtime
+> placeholders `"$param.<name>"`, `"$selection.<blockId>.<field>"` and `"$input.<name>"` for
+> master-detail wiring. See the
+> [App Builder guide](https://baasix.dev/docs/guides/app-builder) for the full config reference.
+
 ## Filter Operators
 
 Baasix supports 50+ filter operators:
@@ -1181,24 +1241,107 @@ baasix.realtime.disconnect();
 
 ## OAuth / Social Login
 
+35 social providers are supported via the `SOCIAL_PROVIDERS` constant — `google`, `github`, `discord`, `microsoft`, `slack`, `apple`, `facebook`, `gitlab`, `linkedin`, `twitter`, … 35 total. `getOAuthUrl`'s `provider` option is typed as `OAuthProvider`, the union of all 35 ids — import `SOCIAL_PROVIDERS` if you need the list at runtime (e.g. to render login buttons).
+
+End-to-end browser flow: `getOAuthUrl()` builds the provider redirect URL → the browser navigates there and completes the provider's login → the provider redirects back to your app's callback page with a `token` (or `error`) query param → your callback page calls `handleOAuthCallback(token)` to finish signing in.
+
 ```typescript
-// Redirect to OAuth provider
+import { SOCIAL_PROVIDERS, type OAuthProvider } from '@baasix/sdk';
+
+// SOCIAL_PROVIDERS: readonly array of all 35 provider ids, e.g. for rendering buttons
+SOCIAL_PROVIDERS.forEach((provider) => renderSocialButton(provider));
+
+// 1. Redirect to the OAuth provider
 const url = baasix.auth.getOAuthUrl({
-  provider: 'google', // 'google' | 'facebook' | 'apple' | 'github'
+  provider: 'github', // OAuthProvider — one of SOCIAL_PROVIDERS (35 total)
   redirectUrl: 'https://myapp.com/auth/callback',
 });
 window.location.href = url;
 
-// In your callback page
+// 2. Provider redirects back to your callback page with ?token=... (or ?error=...)
+// In your callback page:
 const params = new URLSearchParams(window.location.search);
 const token = params.get('token');
+const error = params.get('error');
 
 if (token) {
   const { user } = await baasix.auth.handleOAuthCallback(token);
   console.log('Logged in as:', user.email);
+} else if (error) {
+  console.error('OAuth sign-in failed:', error);
+}
+```
+
+## Auth Method Discovery
+
+Ask the server which login methods are actually enabled (registration, email/password, magic link, passkey, 2FA, and the list of configured social providers) so your login UI only shows what's available. The result is cached per client instance — pass `force: true` to bypass the cache.
+
+```typescript
+const methods = await baasix.auth.getAuthMethods();
+// {
+//   registration: true,
+//   emailPassword: true,
+//   magicLink: false,
+//   passkey: true,
+//   twoFactor: true,
+//   socialProviders: ['google', 'github', 'discord'],
+// }
+
+if (methods.socialProviders.includes('google')) {
+  // show "Sign in with Google"
+}
+if (methods.passkey) {
+  // show "Sign in with a passkey"
 }
 ```
 
+## Two-Factor Authentication
+
+TOTP-based 2FA (SHA1, 6-digit codes, 30s window) with 10 single-use backup codes. 2FA gates **password login only** — social, magic-link, and passkey sign-ins bypass the 2FA challenge (they're already a possession/federated factor). Enabling 2FA requires the account to already have a password credential.
+
+```typescript
+// Enable 2FA (while logged in) — returns a secret, otpauth:// URL (render as a QR code), and backup codes
+const setup = await baasix.auth.twoFactor.enable();
+// { secret, otpauthUrl, backupCodes: [10 codes] }
+
+// Confirm setup with a code from the authenticator app
+await baasix.auth.twoFactor.verifySetup('123456');
+// { enabled: true }
+
+// Disable 2FA (requires the account password)
+await baasix.auth.twoFactor.disable('currentPassword');
+// { disabled: true }
+
+// Login flow with 2FA enabled
+const result = await baasix.auth.login({ email, password });
+
+if ('twoFactorRequired' in result && result.twoFactorRequired) {
+  // Prompt for a TOTP code or an unused backup code
+  const { user, token } = await baasix.auth.twoFactor.verify(result.twoFactorToken, '123456');
+} else {
+  // Logged in directly — 2FA not enabled for this account
+  const { user, token } = result;
+}
+```
+
+## Passkeys
+
+WebAuthn-based, usernameless passkey sign-in with per-user credential management. **Browser-only** — `baasix.auth.passkey.*` methods dynamically import `@simplewebauthn/browser` and throw a `BaasixError` when called outside a browser (e.g. Node.js or React Native).
+
+```typescript
+// Register a passkey for the currently logged-in user
+await baasix.auth.passkey.register('MacBook Touch ID'); // name is optional
+
+// Authenticate with a passkey (no prior login required)
+const { user, token } = await baasix.auth.passkey.authenticate();
+
+// List the current user's registered passkeys (no key material returned)
+const passkeys = await baasix.auth.passkey.list();
+
+// Remove one of your own passkeys
+await baasix.auth.passkey.remove(passkeys[0].id);
+```
+
 ## Invitation System (Multi-tenant)
 
 ```typescript

package/dist/index.cjs

@@ -192,7 +192,7 @@ var HttpClient = class {
     } catch {
     }
     const message = errorData.error?.message || errorData.message || response.statusText || "Request failed";
-    const code = errorData.error?.code;
+    const code = errorData.error?.code ?? errorData.code;
     const details = errorData.details;
     return new BaasixError(message, response.status, code, details);
   }
@@ -476,17 +476,123 @@ var MemoryStorageAdapter = class {
 };
 
 // src/modules/auth.ts
+var SOCIAL_PROVIDERS = ["apple", "atlassian", "cognito", "discord", "dropbox", "facebook", "figma", "github", "gitlab", "google", "huggingface", "kakao", "kick", "line", "linear", "linkedin", "microsoft", "naver", "notion", "paybin", "paypal", "polar", "railway", "reddit", "roblox", "salesforce", "slack", "spotify", "tiktok", "twitch", "twitter", "vercel", "vk", "wechat", "zoom"];
 var AuthModule = class {
   client;
   storage;
   authMode;
   onAuthStateChange;
   currentUser = null;
+  authMethodsCache = null;
+  /**
+   * Two-factor authentication (TOTP) helpers.
+   *
+   * @example
+   * ```typescript
+   * const result = await baasix.auth.login({ email, password });
+   * if ("twoFactorRequired" in result && result.twoFactorRequired) {
+   *   const { user, token } = await baasix.auth.twoFactor.verify(result.twoFactorToken, code);
+   * }
+   * ```
+   */
+  twoFactor;
+  /**
+   * Passkey (WebAuthn) registration and authentication helpers.
+   * Browser-only: throws a `BaasixError` when called outside a browser
+   * environment (no `window`/`PublicKeyCredential`).
+   *
+   * @example
+   * ```typescript
+   * // Register a passkey for the currently logged-in user
+   * await baasix.auth.passkey.register("My Laptop");
+   *
+   * // Authenticate with a passkey (no prior login required)
+   * const { user, token } = await baasix.auth.passkey.authenticate();
+   *
+   * // List and remove registered passkeys
+   * const passkeys = await baasix.auth.passkey.list();
+   * await baasix.auth.passkey.remove(passkeys[0].id);
+   * ```
+   */
+  passkey = {
+    register: async (name) => {
+      this.assertBrowser();
+      const { startRegistration } = await import('@simplewebauthn/browser');
+      const options = await this.client.post("/auth/passkey/register/options", {});
+      const attestation = await startRegistration({ optionsJSON: options });
+      await this.client.post("/auth/passkey/register/verify", {
+        response: attestation,
+        name: name || null
+      });
+      return { verified: true };
+    },
+    authenticate: async (opts) => {
+      this.assertBrowser();
+      const { startAuthentication } = await import('@simplewebauthn/browser');
+      const { options, challengeId } = await this.client.post(
+        "/auth/passkey/authenticate/options",
+        {},
+        { skipAuth: true }
+      );
+      const assertion = await startAuthentication({ optionsJSON: options });
+      const response = await this.client.post(
+        "/auth/passkey/authenticate/verify",
+        { challengeId, response: assertion, authMode: opts?.authMode },
+        { skipAuth: true }
+      );
+      await this.storeTokens(response);
+      this.emitAuthStateChange("SIGNED_IN", response.user);
+      return response;
+    },
+    list: async () => (await this.client.get("/auth/passkey")).passkeys,
+    remove: async (id) => {
+      await this.client.delete(`/auth/passkey/${encodeURIComponent(id)}`);
+    }
+  };
   constructor(config) {
     this.client = config.client;
     this.storage = config.storage;
     this.authMode = config.authMode;
     this.onAuthStateChange = config.onAuthStateChange;
+    this.twoFactor = {
+      verify: async (twoFactorToken, code, opts) => {
+        const response = await this.client.post(
+          "/auth/2fa/verify",
+          {
+            twoFactorToken,
+            code,
+            authMode: opts?.authMode,
+            authType: opts?.authType
+          },
+          { skipAuth: true }
+        );
+        await this.storeTokens(response);
+        this.emitAuthStateChange("SIGNED_IN", response.user);
+        return response;
+      },
+      enable: () => {
+        return this.client.post("/auth/2fa/enable");
+      },
+      verifySetup: (code) => {
+        return this.client.post("/auth/2fa/verify-setup", {
+          code
+        });
+      },
+      disable: (password) => {
+        return this.client.post("/auth/2fa/disable", {
+          password
+        });
+      }
+    };
+  }
+  /**
+   * Assert that we're running in a browser environment with WebAuthn support.
+   * Throws a `BaasixError` otherwise.
+   */
+  assertBrowser() {
+    if (typeof window === "undefined" || !window.PublicKeyCredential) {
+      throw new BaasixError("Passkeys are only available in a browser", 400);
+    }
   }
   /**
    * Emit an authentication state change event
@@ -583,9 +689,39 @@ var AuthModule = class {
       },
       { skipAuth: true }
     );
-    await this.storeTokens(response);
-    this.emitAuthStateChange("SIGNED_IN", response.user);
-    return response;
+    if ("twoFactorRequired" in response && response.twoFactorRequired) {
+      return response;
+    }
+    const authResponse = response;
+    await this.storeTokens(authResponse);
+    this.emitAuthStateChange("SIGNED_IN", authResponse.user);
+    return authResponse;
+  }
+  /**
+   * Discover which authentication methods are enabled for this project
+   * (registration, email/password, magic link, passkey, 2FA, and the list
+   * of configured social/OAuth providers). Result is cached per instance;
+   * pass `force: true` to bypass the cache and refetch.
+   *
+   * @example
+   * ```typescript
+   * const methods = await baasix.auth.getAuthMethods();
+   * if (methods.socialProviders.includes("google")) {
+   *   // show "Sign in with Google"
+   * }
+   * ```
+   */
+  async getAuthMethods(force = false) {
+    if (this.authMethodsCache && !force) {
+      return this.authMethodsCache;
+    }
+    const response = await this.client.get(
+      "/",
+      { skipAuth: true }
+    );
+    const authMethods = response?.project?.auth;
+    this.authMethodsCache = authMethods;
+    return authMethods;
   }
   /**
    * Logout the current user
@@ -2406,6 +2542,42 @@ var NotificationsModule = class {
     );
     return { count: response.count };
   }
+  /**
+   * Mark notifications as unseen (unread)
+   *
+   * @example
+   * ```typescript
+   * // Mark specific notifications as unseen
+   * await baasix.notifications.markAsUnseen(['id1', 'id2']);
+   *
+   * // Mark all notifications as unseen
+   * await baasix.notifications.markAsUnseen();
+   * ```
+   */
+  async markAsUnseen(notificationIds) {
+    const response = await this.client.post(
+      "/notifications/mark-unseen",
+      { notificationIds }
+    );
+    return { count: response.count };
+  }
+  /**
+   * Get the per-type notification link templates configured in settings
+   * (`metadata.notificationLinks`). Templates may contain `{{field}}`
+   * placeholders resolved from the notification (including `data.*` paths).
+   *
+   * @example
+   * ```typescript
+   * const links = await baasix.notifications.getLinks();
+   * // { task_assigned: '/pages/?slug=tasks&id={{data.taskId}}' }
+   * ```
+   */
+  async getLinks() {
+    const response = await this.client.get(
+      "/notifications/links"
+    );
+    return response.data ?? {};
+  }
   /**
    * Delete notifications for the current user
    *
@@ -2712,10 +2884,11 @@ var SettingsModule = class {
    * });
    * ```
    */
-  async update(settings) {
+  async update(settings, options) {
     const response = await this.client.patch(
       "/settings",
-      settings
+      settings,
+      options?.tenantId !== void 0 && options?.tenantId !== null ? { params: { tenant_id: options.tenantId } } : void 0
     );
     return response.data;
   }
@@ -4721,15 +4894,23 @@ var ServerModule = class {
   /**
    * Get server information including project settings
    *
+   * @param tenantId - Optional tenant ID to fetch tenant-merged project settings
+   *
    * @example
    * ```typescript
    * const info = await baasix.server.info();
    * console.log('Project:', info.project?.name);
    * console.log('Version:', info.version);
+   *
+   * // Tenant-aware: settings merged for the given tenant
+   * const tenantInfo = await baasix.server.info("tenant-uuid");
    * ```
    */
-  async info() {
-    return this.client.get("/");
+  async info(tenantId) {
+    return this.client.get(
+      "/",
+      tenantId ? { params: { tenant_id: tenantId } } : void 0
+    );
   }
   /**
    * Check server health
@@ -5060,6 +5241,7 @@ exports.RealtimeChannel = RealtimeChannel;
 exports.RealtimeModule = RealtimeModule;
 exports.ReportsModule = ReportsModule;
 exports.RolesModule = RolesModule;
+exports.SOCIAL_PROVIDERS = SOCIAL_PROVIDERS;
 exports.STORAGE_KEYS = STORAGE_KEYS;
 exports.SchemasModule = SchemasModule;
 exports.SettingsModule = SettingsModule;