@mitway/sdk 0.5.0 → 0.7.1

package/dist/index.d.ts

@@ -34,15 +34,56 @@ interface User {
  * Token Manager for the MITWAY-BaaS SDK.
  *
  * Stores the access token + user in memory and optionally persists them
- * to `localStorage` so sessions survive page reloads (F5). Browser CSRF
- * token lives in a cookie for the cookie-based refresh flow.
+ * via a pluggable `StorageAdapter`. By default, a browser-`localStorage`-
+ * backed adapter is used (with an SSR-safe noop when `localStorage` is not
+ * available). Consumers can inject a custom adapter to back the session
+ * with something else: cookies, a native secure store, an SSR cache, an
+ * in-memory stub for tests, etc. Browser CSRF token lives in a cookie
+ * for the cookie-based refresh flow.
  */
 
+/**
+ * Synchronous key/value contract consumed by the `TokenManager` to read
+ * and write persisted sessions. Intentionally narrow: the three methods
+ * are the only primitives the SDK calls. Adapters can freely decide
+ * where and how the value is stored (localStorage, cookie jar, native
+ * secure storage, in-memory, ...). All methods are sync to match what
+ * persisted-session consumers expect on the restore path (F5 reload).
+ */
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Default adapter that wraps browser `localStorage`. Degrades to a noop
+ * when `localStorage` is not available (Node, SSR, sandboxed iframes
+ * with storage access disabled). Exposed so consumers that want to
+ * compose on top of the default (e.g. dual-write to cookies) can import
+ * it rather than re-implement.
+ */
+declare function createLocalStorageAdapter(): StorageAdapter;
 interface TokenManagerOptions {
-    /** Persist session to localStorage so it survives page reloads. Default: true. */
+    /** Persist session so it survives page reloads. Default: true. */
     persistSession?: boolean;
-    /** localStorage key. Default: 'mitway_baas_session'. */
+    /** Storage key. Default: 'mitway_baas_session'. */
     storageKey?: string;
+    /**
+     * Storage backend. Default: browser `localStorage` (SSR-safe). Pass a
+     * custom adapter to back the session with cookies, native secure
+     * storage, or an in-memory stub for tests.
+     */
+    storage?: StorageAdapter;
+    /**
+     * Sync session state across browser tabs via the `storage` event.
+     * When enabled, a sign-in / sign-out / token-refresh performed in one
+     * tab is reflected in every other tab sharing the same origin. Only
+     * useful when the configured storage is (or wraps) `localStorage` —
+     * the browser `storage` event only fires on `localStorage` /
+     * `sessionStorage` mutations. Default: true in a browser context,
+     * no-op otherwise.
+     */
+    multiTab?: boolean;
 }
 declare class TokenManager {
     private accessToken;
@@ -50,9 +91,24 @@ declare class TokenManager {
     private user;
     private readonly persistSession;
     private readonly storageKey;
+    private readonly storage;
     /** Fired when the access token changes (used by long-lived consumers). */
     onTokenChange: (() => void) | null;
     constructor(opts?: TokenManagerOptions);
+    /**
+     * Cross-tab storage-event handler. Arrow-bound so `removeEventListener`
+     * with the same reference works if the host ever decides to dispose a
+     * TokenManager (the SDK itself does not today).
+     */
+    private handleStorageEvent;
+    /**
+     * Update in-memory state from a raw storage value (produced by another
+     * tab). Fires `onTokenChange` only when the access token actually
+     * differs from what we had, so a listener can map this transition onto
+     * `SIGNED_IN` / `SIGNED_OUT` / `TOKEN_REFRESHED` the same way it maps
+     * transitions from same-tab mutations.
+     */
+    private syncFromStorage;
     saveSession(session: AuthSession): void;
     getSession(): AuthSession | null;
     getAccessToken(): string | null;
@@ -63,8 +119,8 @@ declare class TokenManager {
     setUser(user: User): void;
     clearSession(): void;
     /**
-     * Restore the session from localStorage. Returns true if a persisted
-     * session was found and loaded into memory.
+     * Restore the session from the configured storage. Returns true if a
+     * persisted session was found and loaded into memory.
      */
     restoreSession(): boolean;
     private persist;
@@ -479,10 +535,26 @@ interface MitwayBaasConfig {
      */
     persistSession?: boolean;
     /**
-     * `localStorage` key used to persist the session.
+     * Storage key used to persist the session.
      * @default "mitway_baas_session"
      */
     storageKey?: string;
+    /**
+     * Custom persistence backend for the session. Must implement the
+     * synchronous `{ getItem, setItem, removeItem }` contract. Default:
+     * browser `localStorage` (SSR-safe). Pass a custom adapter to back
+     * sessions with cookies, native secure storage, or an in-memory stub
+     * for tests. Ignored when `persistSession: false`.
+     */
+    storage?: StorageAdapter;
+    /**
+     * Synchronise session state across browser tabs. When the user signs
+     * in, signs out, or refreshes their token in tab A, tabs B, C, D
+     * sharing the same origin see the change automatically. Only works
+     * when the active storage is (or wraps) `localStorage`. Default:
+     * true in a browser, no-op otherwise.
+     */
+    multiTab?: boolean;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -650,10 +722,59 @@ type AuthResult<T> = {
     data: T | null;
     error: MitwayBaasError | null;
 };
+/**
+ * Event names emitted by `auth.onAuthStateChange`. Mirrors
+ * `@supabase/supabase-js` event names so consumers that already know that
+ * contract do not have to re-learn ours.
+ *
+ *   - `INITIAL_SESSION` — emitted once per `auth.initialize()` call
+ *     regardless of whether a persisted session was found. `session` is
+ *     non-null when a valid session was restored, null otherwise.
+ *   - `SIGNED_IN` — a session transitioned from absent to present
+ *     (after `signUp`, `signInWithPassword`, or a cross-tab storage sync).
+ *   - `SIGNED_OUT` — a session transitioned from present to absent
+ *     (`signOut` or cross-tab storage sync).
+ *   - `TOKEN_REFRESHED` — the access token changed but the user did not
+ *     (explicit `refreshSession` or the HttpClient's auto-refresh on 401).
+ *   - `USER_UPDATED` — the user record changed without a token change
+ *     (`setProfile` or backend-side profile mutation).
+ */
+type AuthChangeEvent = 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED';
+type AuthStateChangeCallback = (event: AuthChangeEvent, session: AuthSession | null) => void;
+/** Return value of `onAuthStateChange` — call `unsubscribe()` to remove the listener. */
+interface Subscription {
+    unsubscribe: () => void;
+}
 declare class Auth {
     private http;
     private tokenManager;
+    /** Registered `onAuthStateChange` callbacks. */
+    private stateChangeListeners;
+    /**
+     * Last-emitted session snapshot — used by `_handleTokenChange` to decide
+     * which event to emit (SIGNED_IN vs TOKEN_REFRESHED vs SIGNED_OUT).
+     */
+    private lastEmittedUserId;
+    private lastEmittedAccessToken;
     constructor(http: HttpClient, tokenManager: TokenManager);
+    /**
+     * Register a listener for session state transitions. Returns a
+     * `Subscription` whose `unsubscribe()` removes the listener. Safe to
+     * register after login — the listener does NOT receive an initial
+     * replay of the current state; call `getSession()` separately if you
+     * need the current value on mount. `INITIAL_SESSION` is emitted once
+     * per `auth.initialize()` call and is the standard hook for the first
+     * render path.
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): Subscription;
+    /** Fan out an event to every registered listener. */
+    private emit;
+    /**
+     * Translate a `TokenManager.onTokenChange` signal into an
+     * AuthChangeEvent by diffing previous vs current state. No event is
+     * emitted if the net effect is a no-op (defensive — shouldn't happen).
+     */
+    private _emitFromTokenChange;
     /**
      * Persist the session in memory + HttpClient defaults so subsequent
      * requests carry the new bearer token automatically.
@@ -688,20 +809,29 @@ declare class Auth {
      */
     refreshSession(): Promise<AuthResult<AuthResponse>>;
     /**
-     * Restore the session from localStorage and validate it with the backend.
-     * Call this once on app startup (e.g. in a React AuthProvider useEffect).
+     * Validate the current session against the backend and emit
+     * `INITIAL_SESSION`. Call this once on app startup (e.g. in a React
+     * AuthProvider useEffect).
+     *
+     * The in-memory session is already populated at SDK construction time —
+     * `TokenManager`'s constructor reads persisted storage synchronously
+     * and `Auth`'s constructor seeds the `HttpClient` from it. This method
+     * adds the backend round-trip that guarantees the access token is
+     * still valid server-side, and fires `INITIAL_SESSION` so listeners
+     * registered before startup can transition out of their "checking"
+     * state.
      *
      * Flow:
-     *   1. Read persisted session from localStorage.
-     *   2. Populate in-memory state (TokenManager + HttpClient).
-     *   3. Validate with `GET /api/auth/sessions/current`.
-     *      - If the access token expired, the HttpClient auto-refresh kicks in
-     *        using the persisted refresh token (sent in the POST body, not
+     *   1. If no in-memory session → emit `INITIAL_SESSION(null)` + return
+     *      `NO_SESSION`. The app should show the login page.
+     *   2. `GET /api/auth/sessions/current`.
+     *      - If the access token expired, `HttpClient`'s auto-refresh
+     *        kicks in with the persisted refresh token (POST body, not
      *        cookies — works cross-site).
-     *   4. Return the validated user or an error.
-     *
-     * If no persisted session exists, returns `{ data: null, error }` — the
-     * app should show the login page.
+     *   3. Mirror the validated user into memory + emit
+     *      `INITIAL_SESSION(session)`.
+     *   4. On backend rejection, clear the session + emit
+     *      `INITIAL_SESSION(null)`.
      */
     initialize(): Promise<AuthResult<AuthResponse>>;
     /**
@@ -910,6 +1040,80 @@ declare class Storage {
     getConfig(): Promise<StorageResult<StorageConfig>>;
 }
 
+/**
+ * Functions module -- thin wrapper over the /api/functions/* and /api/invoke/*
+ * REST endpoints exposed by MITWAY-BaaS.
+ *
+ * Manages edge function CRUD, invocation, and secrets. Function invocation
+ * routes through `HttpClient.rawFetch` since `/api/invoke/:slug` is a
+ * transparent proxy that does NOT use the `{ data, error }` envelope.
+ */
+
+interface EdgeFunction {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    code: string;
+    status: 'draft' | 'active' | 'error';
+    createdAt: string;
+    updatedAt: string;
+    deployedAt: string | null;
+}
+interface CreateFunctionRequest {
+    name: string;
+    slug?: string;
+    code: string;
+    description?: string;
+    status?: 'draft' | 'active';
+}
+interface UpdateFunctionRequest {
+    name?: string;
+    code?: string;
+    description?: string;
+    status?: 'draft' | 'active';
+}
+interface FunctionSecret {
+    key: string;
+    digest: string;
+    updatedAt: string;
+}
+interface InvokeOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: BodyInit | Record<string, unknown> | null;
+}
+type FunctionsResult<T> = {
+    data: T | null;
+    error: MitwayBaasError | null;
+};
+declare class Functions {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<FunctionsResult<EdgeFunction[]>>;
+    get(slug: string): Promise<FunctionsResult<EdgeFunction>>;
+    create(req: CreateFunctionRequest): Promise<FunctionsResult<EdgeFunction>>;
+    update(slug: string, req: UpdateFunctionRequest): Promise<FunctionsResult<EdgeFunction>>;
+    remove(slug: string): Promise<FunctionsResult<{
+        deleted: true;
+    }>>;
+    /**
+     * Invoke an edge function. The `/api/invoke/:slug` route is a transparent
+     * proxy — no `{ data, error }` envelope. Returns the raw `Response`.
+     *
+     * If `opts.body` is a plain object it is JSON-stringified and
+     * `Content-Type: application/json` is set automatically.
+     */
+    invoke(slug: string, opts?: InvokeOptions): Promise<FunctionsResult<Response>>;
+    listSecrets(): Promise<FunctionsResult<FunctionSecret[]>>;
+    setSecrets(secrets: Record<string, string>): Promise<FunctionsResult<{
+        saved: true;
+    }>>;
+    deleteSecret(key: string): Promise<FunctionsResult<{
+        deleted: true;
+    }>>;
+}
+
 /**
  * MITWAY-BaaS SDK client.
  *
@@ -944,6 +1148,7 @@ declare class MitwayBaasClient {
     readonly database: Database;
     readonly realtime: Realtime;
     readonly storage: Storage;
+    readonly functions: Functions;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -956,13 +1161,13 @@ declare class MitwayBaasClient {
  * @mitway-baas/sdk — TypeScript SDK for the MITWAY-BaaS backend.
  *
  * Currently ships:
- *   - auth     (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
- *   - database (PostgREST-backed query builder via @supabase/postgrest-js)
- *   - realtime (Socket.IO transport: subscribe / unsubscribe / publish / on)
+ *   - auth      (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
+ *   - database  (PostgREST-backed query builder via @supabase/postgrest-js)
+ *   - realtime  (Socket.IO transport: subscribe / unsubscribe / publish / on)
+ *   - storage   (bucket admin + per-bucket object operations)
+ *   - functions (edge function CRUD, invoke, secrets management)
  *
  * Not yet included (no backend support):
- *   - storage
- *   - functions
  *   - email
  *   - ai
  *
@@ -984,4 +1189,4 @@ declare class MitwayBaasClient {
  */
 declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
 
-export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type BroadcastFilter, type BroadcastPayload, type ChannelOptions, type ChannelStatus, type ChannelStatusCallback, type CreateBucketOptions, Database, type DownloadOptions, HttpClient, type ListOptions, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type PostgresChangesDeletePayload, type PostgresChangesEventSelector, type PostgresChangesFilter, type PostgresChangesInsertPayload, type PostgresChangesPayload, type PostgresChangesUpdatePayload, type PresenceEventSelector, type PresenceFilter, type PresenceJoinPayload, type PresenceLeavePayload, type PresencePayload, type PresenceState, type PresenceSyncPayload, Realtime, RealtimeChannel, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, type SignedUrlOptions, type SignedUrlResult, Storage, type StorageBucket, StorageBucketClient, type StorageConfig, type StorageObject, type StorageResult, TokenManager, type UpdateBucketOptions, type UploadBody, type UploadOptions, type User, createClient, MitwayBaasClient as default };
+export { type ApiError, Auth, type AuthChangeEvent, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type AuthStateChangeCallback, type BroadcastFilter, type BroadcastPayload, type ChannelOptions, type ChannelStatus, type ChannelStatusCallback, type CreateBucketOptions, type CreateFunctionRequest, Database, type DownloadOptions, type EdgeFunction, type FunctionSecret, Functions, type FunctionsResult, HttpClient, type InvokeOptions, type ListOptions, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type PostgresChangesDeletePayload, type PostgresChangesEventSelector, type PostgresChangesFilter, type PostgresChangesInsertPayload, type PostgresChangesPayload, type PostgresChangesUpdatePayload, type PresenceEventSelector, type PresenceFilter, type PresenceJoinPayload, type PresenceLeavePayload, type PresencePayload, type PresenceState, type PresenceSyncPayload, Realtime, RealtimeChannel, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, type SignedUrlOptions, type SignedUrlResult, Storage, type StorageAdapter, type StorageBucket, StorageBucketClient, type StorageConfig, type StorageObject, type StorageResult, type Subscription, TokenManager, type UpdateBucketOptions, type UpdateFunctionRequest, type UploadBody, type UploadOptions, type User, createClient, createLocalStorageAdapter, MitwayBaasClient as default };