@motherbase/client 1.0.1 → 1.1.1

package/README.md

@@ -1,121 +1,167 @@
-# @motherbase/client
-
-Typed, isomorphic client SDK for the Motherbase client. Works in the browser,
-Next.js (server & client), and Expo Go / React Native. Built on the global
-`fetch` with zero runtime dependencies (`socket.io-client` is an optional peer
-dependency, used only for realtime).
-
-## Install
-
-```bash
-npm i @motherbase/client
-# optional, only if you use realtime:
-npm i socket.io-client
-```
-
-## Quickstart
-
-```ts
-import { createClient, localStorageStorage } from '@motherbase/client';
-
-const client = createClient('http://localhost:5050', {
-  storage: localStorageStorage(), // omit for in-memory (SSR-safe) sessions
-});
-
-await client.hydrate(); // restore a persisted session (optional)
-
-// Auth
-await client.auth.register({ email: 'me@example.com', password: 'secret123' });
-const session = await client.auth.login({ email: 'me@example.com', password: 'secret123' });
-const user = await client.auth.getUser();
-
-// React to auth changes
-const unsubscribe = client.auth.onAuthStateChange((event, session) => {
-  console.log(event, session?.user.email);
-});
-
-// Storage
-const file = await client.storage.upload(myBlob, { visibility: 'public' });
-const url = await client.storage.getUrl(file.id);
-
-// Devices (push)
-await client.devices.register({ token: pushToken, platform: 'ios' });
-
-// REST API (policy-checked /rest/v1)
-const products = await client.rest.from<{ id: string; name: string; price: number }>('products').list({
-  filters: { price: { op: 'lt', value: 50 } },
-  order: [{ field: 'name' }],
-  limit: 20,
-});
-await client.rest.insert('products', { name: 'Tea', price: 12 });
-
-// Edge functions
-const result = await client.edge.invoke<{ ok: boolean }>('hello', { name: 'Ada' });
-
-// Realtime (requires socket.io-client)
-await client.realtime.connect();
-client.realtime.on('message', (msg) => console.log(msg));
-```
-
-The SDK attaches the access token automatically and transparently refreshes it on
-a 401 (single-flight: concurrent requests share one refresh). When the refresh
-token is invalid it clears the session and emits a `signOut` event.
-
-## Storage adapters
-
-| Runtime  | Adapter |
-| -------- | ------- |
-| Browser  | `localStorageStorage()` |
-| SSR/Node | `memoryStorage()` (default) |
-| Expo/RN  | custom `{ get, set }` backed by `AsyncStorage` |
-
-```ts
-import AsyncStorage from '@react-native-async-storage/async-storage';
-import { createClient } from '@motherbase/client';
-
-const client = createClient(API_URL, {
-  storage: {
-    async get() {
-      const raw = await AsyncStorage.getItem('session');
-      return raw ? JSON.parse(raw) : null;
-    },
-    async set(session) {
-      if (session) await AsyncStorage.setItem('session', JSON.stringify(session));
-      else await AsyncStorage.removeItem('session');
-    },
-  },
-});
-```
-
-## API surface
-
-- `client.auth` — register, login, loginWithEmail, validateEmail, refresh,
-  logout, forgotPassword, resetPassword, getUser, getSession, onAuthStateChange
-- `client.users` — updateUsername, updateImage, deleteAccount
-- `client.storage` — upload, presign, getUrl, remove
-- `client.devices` — register, unregister
-- `client.rest` — typed CRUD over `/rest/v1/:model` with policy checks
-- `client.edge` — invoke public edge routes exposed at `/api/edge/:route`
-- `client.realtime` — connect, on, off, emit, disconnect
-
-All methods reject with a `clientError` (`message`, `httpStatus`, `apiStatus`)
-on failure.
-
-More examples live in [`docs/sdk.md`](../../docs/sdk.md). Studio also exposes a
-project-specific Connect page with the exact API URL, WebSocket URL and project
-ID to paste into `.env`.
-
-### REST filters
-
-`client.rest` accepts the client query operators directly:
-
-```ts
-await client.rest.from('products').list({
-  select: ['id', 'name'],
-  filters: {
-    price: { op: 'lte', value: 100 },
-    status: { op: 'in', value: ['active', 'draft'] },
-  },
-  order: [{ field: 'createdAt', direction: 'desc' }],
-});
-```
+# @motherbase/client
+
+A **Supabase-js-compatible** client SDK for the Motherbase self-hosted backend.
+Migrating from Supabase is mostly a package swap — replace
+`@supabase/supabase-js` with `@motherbase/client` and keep the same
+`createClient`, `.from()`, `.auth`, `.storage`, `.channel()` and `.functions`
+shapes.
+
+Typed, isomorphic (browser, Next.js server & client, Expo / React Native), built
+on global `fetch` with zero runtime dependencies (`socket.io-client` is an
+optional peer dependency, used only for realtime).
+
+## Install
+
+```bash
+npm i @motherbase/client
+# optional, only if you use realtime:
+npm i socket.io-client
+```
+
+## Quickstart
+
+```ts
+import { createClient, localStorageStorage } from '@motherbase/client';
+
+const client = createClient(
+  'http://localhost:5001',
+  'your-anon-key', // optional; sent as an `apikey` header
+  { storage: localStorageStorage() } // omit for in-memory (SSR-safe) sessions
+);
+
+await client.hydrate(); // restore a persisted session (optional)
+
+// Auth
+await client.auth.signUp({ email: 'me@example.com', password: 'secret123' });
+const { data, error } = await client.auth.signInWithPassword({
+  email: 'me@example.com',
+  password: 'secret123',
+});
+
+// Query builder (awaitable, PostgREST-style)
+const { data: products } = await client
+  .from('products')
+  .select('id,name,price')
+  .lt('price', 50)
+  .order('name', { ascending: false })
+  .limit(20);
+
+// Storage
+const { data: uploaded } = await client.storage.from('avatars').upload('me.png', myBlob, {
+  visibility: 'public',
+});
+
+// Realtime — postgres_changes, broadcast, presence over one channel (Supabase-shaped)
+const room = client
+  .channel('room-1', { config: { broadcast: { self: true }, presence: { key: userId } } })
+  .on('postgres_changes', { event: '*', schema: 'public', table: 'messages', filter: 'room_id=eq.42' }, p => {
+    console.log(p.eventType, p.new, p.old);
+  })
+  .on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
+  .on('presence', { event: 'sync' }, () => console.log(room.presenceState()))
+  .subscribe();
+
+await room.send({ type: 'broadcast', event: 'cursor', payload: { x: 1, y: 2 } });
+await room.track({ online_at: Date.now() });
+
+// Edge functions
+const { data: result } = await client.functions.invoke('hello', { body: { name: 'Ada' } });
+```
+
+Every data/auth/storage call resolves to `{ data, error }` and **never throws**
+for expected API errors. `error` is `null` on success, otherwise
+`{ message, status?, code? }`.
+
+The SDK attaches the access token automatically and transparently refreshes it on
+a 401 (single-flight: concurrent requests share one refresh). When the refresh
+token is invalid it clears the session and emits `SIGNED_OUT`.
+
+## API surface (cheatsheet)
+
+```ts
+// Data
+client.from(table).select(cols).eq(col, v).in(col, [..]).order(col, { ascending }).limit(n).range(from, to)
+client.from(table).select(cols).single() | .maybeSingle()
+client.from(table).insert(rows) | .update(values).eq(..) | .upsert(rows) | .delete().eq(..)
+
+// Auth  → { data, error }
+client.auth.signUp({ email, password })
+client.auth.signInWithPassword({ email, password })
+client.auth.signOut()
+client.auth.getUser()          // { data: { user } }
+client.auth.getSession()       // { data: { session } }
+client.auth.refreshSession()
+client.auth.onAuthStateChange((event, session) => {})  // SIGNED_IN | SIGNED_OUT | TOKEN_REFRESHED
+
+// Storage → { data, error }
+client.storage.from(bucket).upload(path, file, { visibility })
+client.storage.from(bucket).download(path)
+client.storage.from(bucket).remove([path])
+client.storage.from(bucket).createSignedUrl(path, expiresIn)
+client.storage.from(bucket).getPublicUrl(path)   // sync
+
+// Realtime
+client.channel(name, { config: { broadcast: { self, ack }, presence: { key } } })
+  .on('postgres_changes', { event, schema, table, filter }, cb)
+  .on('broadcast', { event }, cb)
+  .on('presence', { event: 'sync' | 'join' | 'leave' }, cb)
+  .subscribe(status => {})            // SUBSCRIBED | TIMED_OUT | CLOSED | CHANNEL_ERROR
+channel.send({ type: 'broadcast', event, payload })
+channel.track(state); channel.untrack(); channel.presenceState()
+client.removeChannel(channel)
+
+// Edge functions → { data, error }
+client.functions.invoke(name, { body })
+```
+
+## Storage adapters
+
+| Runtime  | Adapter                                                       |
+| -------- | ------------------------------------------------------------- |
+| Browser  | `localStorageStorage()` or `cookieStorage()`                  |
+| SSR/Node | `memoryStorage()` (default) or `serverCookieStorage(adapter)` |
+| Expo/RN  | custom `{ get, set }` backed by `AsyncStorage`                |
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { createClient } from '@motherbase/client';
+
+const client = createClient(API_URL, ANON_KEY, {
+  storage: {
+    async get() {
+      const raw = await AsyncStorage.getItem('session');
+      return raw ? JSON.parse(raw) : null;
+    },
+    async set(session) {
+      if (session) await AsyncStorage.setItem('session', JSON.stringify(session));
+      else await AsyncStorage.removeItem('session');
+    },
+  },
+});
+```
+
+## Compatibility matrix
+
+| Area                                                          | Status        | Notes                                                   |
+| ------------------------------------------------------------- | ------------- | ------------------------------------------------------- |
+| `createClient(url, key, options)`                             | Supported     | `key` sent as `apikey` header.                          |
+| `from().select/insert/update/delete`                          | Supported     | Awaitable `{ data, error }`.                            |
+| filters `eq/neq/gt/gte/lt/lte/like/ilike/in/is`               | Supported     | Mapped to the `/rest/v1` PostgREST dialect.             |
+| `order/limit/range/single/maybeSingle`                        | Supported     | `range` → limit/offset.                                 |
+| `upsert()`                                                    | Partial       | Emulated as `insert` (no `onConflict`).                 |
+| relational embedding (`select('*, author(*)')`)               | Not supported | Backend blocks joins.                                   |
+| `.rpc()`                                                      | Not supported | No exposed Postgres functions — use `functions.invoke`. |
+| `.or/.not/.filter/.textSearch/.contains`                      | Not supported | Not in the backend dialect.                             |
+| `auth.signUp/signInWithPassword/signOut`                      | Supported     |                                                         |
+| `auth.getUser/getSession/refreshSession/onAuthStateChange`    | Supported     | Events: `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`.   |
+| OAuth / magic link / OTP                                      | Not supported | Email + password only.                                  |
+| `storage upload/download/remove/createSignedUrl/getPublicUrl` | Partial       | `path` == server file id returned by `upload`.          |
+| `storage.list()`                                              | Stub          | Returns an unsupported error instead of throwing.       |
+| `channel().on('postgres_changes').subscribe()`                | Supported     | INSERT/UPDATE/DELETE/`*`, RLS-filtered, column `filter`. |
+| `channel().on('broadcast')` + `.send()`                       | Supported     | `config.broadcast.self` / `.ack`.                       |
+| `channel().on('presence')` + `.track/.untrack/.presenceState` | Supported     | `sync`/`join`/`leave`, keyed by `config.presence.key`.  |
+| `functions.invoke(name, { body })`                            | Supported     | Maps to `/api/edge/:name`.                              |
+
+More examples live in [`docs/sdk.md`](../../docs/sdk.md). Project Studio also
+exposes a project-specific Connect page with the exact API URL, WebSocket URL and
+project ID to paste into `.env`.

package/dist/auth.d.ts

@@ -1,61 +1,66 @@
 import type { HttpClient } from './http.js';
 import type { SessionStore } from './session.js';
-import type { AuthListener, Session, User } from './types.js';
-interface RegisterParams {
+import type { AuthChangeListener, MotherbaseResponse, Session, User } from './types.js';
+export interface SignUpCredentials {
     email: string;
     password: string;
+    /** Optional extra profile field supported by the backend. */
     username?: string;
 }
-interface LoginParams {
+export interface SignInWithPasswordCredentials {
     email: string;
     password: string;
 }
-interface ResetPasswordParams {
-    email: string;
-    secretCode: string;
-    newPassword: string;
-}
-interface AppleAuthParams {
-    identityToken: string;
-    email?: string | null;
-    fullName?: {
-        givenName?: string | null;
-        familyName?: string | null;
-    } | null;
+export interface Subscription {
+    unsubscribe(): void;
 }
-export declare class AuthModule {
+/**
+ * Supabase-compatible auth client. Maps supabase-js method names onto the
+ * Motherbase auth endpoints and reuses the existing token/refresh/session-store
+ * machinery. Returns `{ data, error }` and never throws for expected failures.
+ */
+export declare class AuthClient {
     private readonly http;
     private readonly store;
     constructor(http: HttpClient, store: SessionStore);
-    register(params: RegisterParams): Promise<Session>;
-    login(params: LoginParams): Promise<Session>;
-    /** Passwordless email flow: requests a verification code. */
-    loginWithEmail(params: {
-        email: string;
-    }): Promise<unknown>;
-    validateEmail(params: {
-        emailVerificationId: string;
-        secretCode: string;
-    }): Promise<Session>;
-    forgotPassword(params: {
-        email: string;
-    }): Promise<unknown>;
-    resetPassword(params: ResetPasswordParams): Promise<unknown>;
-    loginWithGoogle(params: {
-        idToken: string;
-    }): Promise<Session>;
-    google(idToken: string): Promise<Session>;
-    loginWithApple(params: AppleAuthParams): Promise<Session>;
-    apple(params: AppleAuthParams): Promise<Session>;
-    /** Rotate tokens using the stored refresh token. Returns true on success. */
-    refresh(): Promise<boolean>;
-    logout(): Promise<void>;
-    /** Fetch the current user from the API (requires a valid session). */
-    getUser(): Promise<User>;
-    /** The locally-held session, if any. */
-    getSession(): Session | null;
-    onAuthStateChange(listener: AuthListener): () => void;
+    signUp(credentials: SignUpCredentials): Promise<MotherbaseResponse<{
+        user: User | null;
+        session: Session | null;
+    }>>;
+    signInWithPassword(credentials: SignInWithPasswordCredentials): Promise<MotherbaseResponse<{
+        user: User | null;
+        session: Session | null;
+    }>>;
+    signOut(): Promise<{
+        error: MotherbaseResponse<null>['error'];
+    }>;
+    /** Fetch the current user from Better Auth (requires a valid session). */
+    getUser(): Promise<MotherbaseResponse<{
+        user: User | null;
+    }>>;
+    /** The locally-held session, if any (no network call). */
+    getSession(): Promise<MotherbaseResponse<{
+        session: Session | null;
+    }>>;
+    /**
+     * Revalidate the current session against the server. Better Auth bearer
+     * sessions have no refresh token — if the session is still valid the user is
+     * refreshed; otherwise the local session is cleared.
+     */
+    refreshSession(): Promise<MotherbaseResponse<{
+        user: User | null;
+        session: Session | null;
+    }>>;
+    onAuthStateChange(callback: AuthChangeListener): {
+        data: {
+            subscription: Subscription;
+        };
+    };
+    /**
+     * Internal: refresh used by the HttpClient's 401 path. Returns true on success.
+     * Not part of the public Supabase surface.
+     */
+    _refresh(): Promise<boolean>;
     private persist;
 }
-export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE9D,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AACD,UAAU,eAAe;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7E;AAeD,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAc,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAxC,IAAI,EAAE,UAAU,EAAmB,KAAK,EAAE,YAAY;IAE7E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IASlD,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IASlD,6DAA6D;IAC7D,cAAc,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrD,aAAa,CAAC,MAAM,EAAE;QAAE,mBAAmB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IASlG,cAAc,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3D,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,eAAe,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IASpE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInC,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/D,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhD,6EAA6E;IACvE,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAgB3B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB7B,sEAAsE;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,wCAAwC;IACxC,UAAU,IAAI,OAAO,GAAG,IAAI;IAI5B,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;YAIvC,OAAO;CAKtB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAEV,kBAAkB,EAElB,kBAAkB,EAClB,OAAO,EACP,IAAI,EACL,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAyBD,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAc,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAxC,IAAI,EAAE,UAAU,EAAmB,KAAK,EAAE,YAAY;IAE7E,MAAM,CACV,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,kBAAkB,CAAC;QAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAexE,kBAAkB,CACtB,WAAW,EAAE,6BAA6B,GACzC,OAAO,CAAC,kBAAkB,CAAC;QAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAexE,OAAO,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;IAUtE,0EAA0E;IACpE,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;QAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IASnE,0DAA0D;IACpD,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;QAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAI5E;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,kBAAkB,CAAC;QAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAoBnG,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,YAAY,CAAA;SAAE,CAAA;KAAE;IAOzF;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;YAKpB,OAAO;CAKtB"}

package/dist/auth.js

@@ -1,110 +1,116 @@
-/** Split the flattened auth payload into a clean Session. */
+import { toError } from './http.js';
+import { HTTP_ROUTES } from '@motherbase/contracts';
+/** Build a clean Session from the Better Auth auth payload. */
 function toSession(payload) {
-    const { accessToken, refreshToken, userToken: _userToken, ...user } = payload;
-    return { accessToken, refreshToken, user: user };
+    return { accessToken: payload.token, user: payload.user };
 }
-export class AuthModule {
+const EVENT_MAP = {
+    signIn: 'SIGNED_IN',
+    signOut: 'SIGNED_OUT',
+    tokenRefreshed: 'TOKEN_REFRESHED',
+};
+/**
+ * Supabase-compatible auth client. Maps supabase-js method names onto the
+ * Motherbase auth endpoints and reuses the existing token/refresh/session-store
+ * machinery. Returns `{ data, error }` and never throws for expected failures.
+ */
+export class AuthClient {
     constructor(http, store) {
         this.http = http;
         this.store = store;
     }
-    async register(params) {
-        const payload = await this.http.request('/api/auth/register', {
-            method: 'POST',
-            body: params,
-            anonymous: true,
-        });
-        return this.persist(payload);
-    }
-    async login(params) {
-        const payload = await this.http.request('/api/auth/login', {
-            method: 'POST',
-            body: params,
-            anonymous: true,
-        });
-        return this.persist(payload);
-    }
-    /** Passwordless email flow: requests a verification code. */
-    loginWithEmail(params) {
-        return this.http.request('/api/auth/email', { method: 'PUT', body: params, anonymous: true });
-    }
-    async validateEmail(params) {
-        const payload = await this.http.request('/api/auth/validate-email', {
-            method: 'PUT',
-            body: params,
-            anonymous: true,
-        });
-        return this.persist(payload);
-    }
-    forgotPassword(params) {
-        return this.http.request('/api/auth/forgot-password', { method: 'POST', body: params, anonymous: true });
-    }
-    resetPassword(params) {
-        return this.http.request('/api/auth/reset-password', { method: 'POST', body: params, anonymous: true });
-    }
-    async loginWithGoogle(params) {
-        const payload = await this.http.request('/api/auth/google', {
-            method: 'PUT',
-            body: params,
-            anonymous: true,
-        });
-        return this.persist(payload);
-    }
-    google(idToken) {
-        return this.loginWithGoogle({ idToken });
-    }
-    async loginWithApple(params) {
-        const payload = await this.http.request('/api/auth/apple', {
-            method: 'PUT',
-            body: params,
-            anonymous: true,
-        });
-        return this.persist(payload);
-    }
-    apple(params) {
-        return this.loginWithApple(params);
+    async signUp(credentials) {
+        try {
+            const payload = await this.http.request(HTTP_ROUTES.authSignUp, {
+                method: 'POST',
+                body: { email: credentials.email, password: credentials.password, name: credentials.username ?? credentials.email },
+                anonymous: true,
+                raw: true,
+            });
+            const session = await this.persist(payload);
+            return { data: { user: session.user, session }, error: null };
+        }
+        catch (err) {
+            return { data: { user: null, session: null }, error: toError(err) };
+        }
     }
-    /** Rotate tokens using the stored refresh token. Returns true on success. */
-    async refresh() {
-        const session = this.store.get();
-        if (!session?.refreshToken)
-            return false;
+    async signInWithPassword(credentials) {
         try {
-            const tokens = await this.http.request('/api/auth/refresh', { method: 'POST', body: { refreshToken: session.refreshToken }, anonymous: true });
-            await this.store.setTokens(tokens.accessToken, tokens.refreshToken);
-            return true;
+            const payload = await this.http.request(HTTP_ROUTES.authSignIn, {
+                method: 'POST',
+                body: { email: credentials.email, password: credentials.password },
+                anonymous: true,
+                raw: true,
+            });
+            const session = await this.persist(payload);
+            return { data: { user: session.user, session }, error: null };
         }
-        catch {
-            await this.store.set(null, 'signOut');
-            return false;
+        catch (err) {
+            return { data: { user: null, session: null }, error: toError(err) };
         }
     }
-    async logout() {
-        const session = this.store.get();
-        if (session?.refreshToken) {
-            try {
-                await this.http.request('/api/auth/logout', {
-                    method: 'POST',
-                    body: { refreshToken: session.refreshToken },
-                    anonymous: true,
-                });
-            }
-            catch {
-                // best-effort; clear locally regardless
-            }
+    async signOut() {
+        try {
+            await this.http.request(HTTP_ROUTES.authSignOut, { method: 'POST', raw: true });
+        }
+        catch {
+            // best-effort; clear locally regardless
         }
         await this.store.set(null, 'signOut');
+        return { error: null };
     }
-    /** Fetch the current user from the API (requires a valid session). */
-    getUser() {
-        return this.http.request('/api/auth/');
+    /** Fetch the current user from Better Auth (requires a valid session). */
+    async getUser() {
+        try {
+            const payload = await this.http.request(HTTP_ROUTES.authSession, { raw: true });
+            return { data: { user: payload?.user ?? null }, error: null };
+        }
+        catch (err) {
+            return { data: { user: null }, error: toError(err) };
+        }
     }
-    /** The locally-held session, if any. */
-    getSession() {
-        return this.store.get();
+    /** The locally-held session, if any (no network call). */
+    async getSession() {
+        return { data: { session: this.store.get() }, error: null };
+    }
+    /**
+     * Revalidate the current session against the server. Better Auth bearer
+     * sessions have no refresh token — if the session is still valid the user is
+     * refreshed; otherwise the local session is cleared.
+     */
+    async refreshSession() {
+        const current = this.store.get();
+        if (!current?.accessToken) {
+            return { data: { user: null, session: null }, error: { message: 'Auth session missing!' } };
+        }
+        try {
+            const payload = await this.http.request(HTTP_ROUTES.authSession, { raw: true });
+            if (!payload?.user) {
+                await this.store.set(null, 'signOut');
+                return { data: { user: null, session: null }, error: { message: 'Session expired' } };
+            }
+            const session = { accessToken: current.accessToken, user: payload.user };
+            await this.store.set(session, 'tokenRefreshed');
+            return { data: { user: session.user, session }, error: null };
+        }
+        catch (err) {
+            await this.store.set(null, 'signOut');
+            return { data: { user: null, session: null }, error: toError(err) };
+        }
     }
-    onAuthStateChange(listener) {
-        return this.store.subscribe(listener);
+    onAuthStateChange(callback) {
+        const unsubscribe = this.store.subscribe((event, session) => {
+            callback(EVENT_MAP[event], session);
+        });
+        return { data: { subscription: { unsubscribe } } };
+    }
+    /**
+     * Internal: refresh used by the HttpClient's 401 path. Returns true on success.
+     * Not part of the public Supabase surface.
+     */
+    async _refresh() {
+        const result = await this.refreshSession();
+        return result.error === null;
     }
     async persist(payload) {
         const session = toSession(payload);