@mitway/sdk 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -33,22 +33,42 @@ interface User {
 /**
  * Token Manager for the MITWAY-BaaS SDK.
  *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
+ * 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.
  */
 
+interface TokenManagerOptions {
+    /** Persist session to localStorage so it survives page reloads. Default: true. */
+    persistSession?: boolean;
+    /** localStorage key. Default: 'mitway_baas_session'. */
+    storageKey?: string;
+}
 declare class TokenManager {
     private accessToken;
+    private refreshToken;
     private user;
+    private readonly persistSession;
+    private readonly storageKey;
     /** Fired when the access token changes (used by long-lived consumers). */
     onTokenChange: (() => void) | null;
+    constructor(opts?: TokenManagerOptions);
     saveSession(session: AuthSession): void;
     getSession(): AuthSession | null;
     getAccessToken(): string | null;
     setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
     getUser(): User | null;
     setUser(user: User): void;
     clearSession(): void;
+    /**
+     * Restore the session from localStorage. Returns true if a persisted
+     * session was found and loaded into memory.
+     */
+    restoreSession(): boolean;
+    private persist;
+    private removePersisted;
 }
 
 /**
@@ -451,6 +471,18 @@ interface MitwayBaasConfig {
      * Realtime transport options. See `RealtimeOptions`.
      */
     realtime?: RealtimeOptions;
+    /**
+     * Persist the auth session to `localStorage` so it survives page reloads.
+     * Set to `false` for SSR / Node.js environments where `localStorage` is
+     * not available.
+     * @default true
+     */
+    persistSession?: boolean;
+    /**
+     * `localStorage` key used to persist the session.
+     * @default "mitway_baas_session"
+     */
+    storageKey?: string;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -458,6 +490,7 @@ interface MitwayBaasConfig {
 interface AuthSession {
     user: User;
     accessToken: string;
+    refreshToken?: string;
     expiresAt?: Date;
 }
 /**
@@ -548,6 +581,18 @@ declare class HttpClient {
     private computeRetryDelay;
     private handleRequest;
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Low-level fetch helper for binary bodies (uploads) and streamed responses
+     * (downloads). Applies the current Bearer token (user session → anon key
+     * fallback) plus any configured default headers, resolves `path` against
+     * `baseUrl`, and returns the raw `Response` — it does NOT unwrap the
+     * `{ data, error }` envelope, so the caller is responsible for status
+     * checking and parsing.
+     *
+     * Used by the storage module for object upload/download paths where the
+     * body or response is not JSON.
+     */
+    rawFetch(path: string, init?: RequestInit): Promise<Response>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
     post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
     put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
@@ -642,6 +687,23 @@ declare class Auth {
      * not need to call it directly.
      */
     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).
+     *
+     * 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
+     *        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.
+     */
+    initialize(): Promise<AuthResult<AuthResponse>>;
     /**
      * Get the current in-memory session, or null if the user is not signed in.
      * Synchronous — does not hit the network.
@@ -718,6 +780,136 @@ declare class Database {
     getUrl(): string;
 }
 
+/**
+ * Storage types — kept in sync manually with the MITWAY-BaaS shared-schemas
+ * definitions at
+ * `MITWAY-BaaS/packages/shared-schemas/src/storage.schema.ts`.
+ *
+ * All SDK-facing fields are camelCase. The wire format is snake_case; the
+ * storage module maps between the two.
+ */
+interface StorageBucket {
+    id: string;
+    name: string;
+    public: boolean;
+    fileSizeLimitBytes: number | null;
+    allowedMimeTypes: string[] | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface StorageObject {
+    id: string;
+    bucket: string;
+    key: string;
+    size: number;
+    mimeType: string | null;
+    etag: string;
+    cacheControl: string | null;
+    contentDisposition: string | null;
+    uploadedBy: string | null;
+    uploadedAt: string;
+    updatedAt: string;
+}
+interface StorageConfig {
+    defaultFileSizeLimitBytes: number;
+    maxFileSizeLimitBytes: number;
+    tenantStorageQuotaBytes: number;
+    reservedSpaceBytes: number;
+    signedUrlDefaultTtlSec: number;
+    signedUrlMaxTtlSec: number;
+}
+interface CreateBucketOptions {
+    public?: boolean;
+    fileSizeLimitBytes?: number | null;
+    allowedMimeTypes?: string[] | null;
+}
+interface UpdateBucketOptions {
+    public?: boolean;
+    fileSizeLimitBytes?: number | null;
+    allowedMimeTypes?: string[] | null;
+}
+interface UploadOptions {
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    /** Defaults to false (POST, fails on duplicate). If true, uses PUT (upsert). */
+    upsert?: boolean;
+    abortSignal?: AbortSignal;
+}
+interface DownloadOptions {
+    range?: {
+        start: number;
+        end: number;
+    };
+    abortSignal?: AbortSignal;
+}
+interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    startAfter?: string;
+}
+interface SignedUrlOptions {
+    expiresIn?: number;
+}
+interface SignedUrlResult {
+    url: string;
+    token: string;
+    expiresAt: string;
+}
+type UploadBody = Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | string;
+
+/**
+ * Storage module — thin wrapper over the /api/storage/* REST endpoints
+ * exposed by MITWAY-BaaS.
+ *
+ * Surface mirrors what coding agents expect from a Supabase-style storage
+ * SDK but routes through the Mitway backend (no direct S3 calls). Binary
+ * upload/download uses `HttpClient.rawFetch`; JSON operations use the
+ * standard typed `request<T>` path.
+ */
+
+type StorageResult<T> = {
+    data: T | null;
+    error: MitwayBaasError | null;
+};
+declare class StorageBucketClient {
+    private readonly http;
+    private readonly bucketName;
+    constructor(http: HttpClient, bucketName: string);
+    private bucketBase;
+    private objectPath;
+    upload(key: string, body: UploadBody, opts?: UploadOptions): Promise<StorageResult<StorageObject>>;
+    download(key: string, opts?: DownloadOptions): Promise<StorageResult<Blob>>;
+    getStream(key: string, opts?: DownloadOptions): Promise<StorageResult<ReadableStream<Uint8Array>>>;
+    remove(keys: string[]): Promise<StorageResult<{
+        removed: string[];
+    }>>;
+    list(opts?: ListOptions): Promise<StorageResult<StorageObject[]>>;
+    copy(fromKey: string, toKey: string, toBucket?: string): Promise<StorageResult<StorageObject>>;
+    move(fromKey: string, toKey: string, toBucket?: string): Promise<StorageResult<StorageObject>>;
+    createSignedUrl(key: string, opts?: SignedUrlOptions): Promise<StorageResult<SignedUrlResult>>;
+    getPublicUrl(key: string): {
+        data: {
+            url: string;
+        };
+    };
+}
+declare class Storage {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Scope subsequent operations to a single bucket. */
+    from(bucketName: string): StorageBucketClient;
+    listBuckets(): Promise<StorageResult<StorageBucket[]>>;
+    getBucket(name: string): Promise<StorageResult<StorageBucket>>;
+    createBucket(name: string, opts?: CreateBucketOptions): Promise<StorageResult<StorageBucket>>;
+    updateBucket(name: string, opts: UpdateBucketOptions): Promise<StorageResult<StorageBucket>>;
+    deleteBucket(name: string): Promise<StorageResult<null>>;
+    emptyBucket(name: string): Promise<StorageResult<{
+        removed: number;
+    }>>;
+    getConfig(): Promise<StorageResult<StorageConfig>>;
+}
+
 /**
  * MITWAY-BaaS SDK client.
  *
@@ -751,6 +943,7 @@ declare class MitwayBaasClient {
     readonly auth: Auth;
     readonly database: Database;
     readonly realtime: Realtime;
+    readonly storage: Storage;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -791,4 +984,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, Database, HttpClient, 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, TokenManager, type User, createClient, MitwayBaasClient as default };
+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 };

package/dist/index.d.ts

@@ -33,22 +33,42 @@ interface User {
 /**
  * Token Manager for the MITWAY-BaaS SDK.
  *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
+ * 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.
  */
 
+interface TokenManagerOptions {
+    /** Persist session to localStorage so it survives page reloads. Default: true. */
+    persistSession?: boolean;
+    /** localStorage key. Default: 'mitway_baas_session'. */
+    storageKey?: string;
+}
 declare class TokenManager {
     private accessToken;
+    private refreshToken;
     private user;
+    private readonly persistSession;
+    private readonly storageKey;
     /** Fired when the access token changes (used by long-lived consumers). */
     onTokenChange: (() => void) | null;
+    constructor(opts?: TokenManagerOptions);
     saveSession(session: AuthSession): void;
     getSession(): AuthSession | null;
     getAccessToken(): string | null;
     setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
     getUser(): User | null;
     setUser(user: User): void;
     clearSession(): void;
+    /**
+     * Restore the session from localStorage. Returns true if a persisted
+     * session was found and loaded into memory.
+     */
+    restoreSession(): boolean;
+    private persist;
+    private removePersisted;
 }
 
 /**
@@ -451,6 +471,18 @@ interface MitwayBaasConfig {
      * Realtime transport options. See `RealtimeOptions`.
      */
     realtime?: RealtimeOptions;
+    /**
+     * Persist the auth session to `localStorage` so it survives page reloads.
+     * Set to `false` for SSR / Node.js environments where `localStorage` is
+     * not available.
+     * @default true
+     */
+    persistSession?: boolean;
+    /**
+     * `localStorage` key used to persist the session.
+     * @default "mitway_baas_session"
+     */
+    storageKey?: string;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -458,6 +490,7 @@ interface MitwayBaasConfig {
 interface AuthSession {
     user: User;
     accessToken: string;
+    refreshToken?: string;
     expiresAt?: Date;
 }
 /**
@@ -548,6 +581,18 @@ declare class HttpClient {
     private computeRetryDelay;
     private handleRequest;
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Low-level fetch helper for binary bodies (uploads) and streamed responses
+     * (downloads). Applies the current Bearer token (user session → anon key
+     * fallback) plus any configured default headers, resolves `path` against
+     * `baseUrl`, and returns the raw `Response` — it does NOT unwrap the
+     * `{ data, error }` envelope, so the caller is responsible for status
+     * checking and parsing.
+     *
+     * Used by the storage module for object upload/download paths where the
+     * body or response is not JSON.
+     */
+    rawFetch(path: string, init?: RequestInit): Promise<Response>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
     post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
     put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
@@ -642,6 +687,23 @@ declare class Auth {
      * not need to call it directly.
      */
     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).
+     *
+     * 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
+     *        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.
+     */
+    initialize(): Promise<AuthResult<AuthResponse>>;
     /**
      * Get the current in-memory session, or null if the user is not signed in.
      * Synchronous — does not hit the network.
@@ -718,6 +780,136 @@ declare class Database {
     getUrl(): string;
 }
 
+/**
+ * Storage types — kept in sync manually with the MITWAY-BaaS shared-schemas
+ * definitions at
+ * `MITWAY-BaaS/packages/shared-schemas/src/storage.schema.ts`.
+ *
+ * All SDK-facing fields are camelCase. The wire format is snake_case; the
+ * storage module maps between the two.
+ */
+interface StorageBucket {
+    id: string;
+    name: string;
+    public: boolean;
+    fileSizeLimitBytes: number | null;
+    allowedMimeTypes: string[] | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface StorageObject {
+    id: string;
+    bucket: string;
+    key: string;
+    size: number;
+    mimeType: string | null;
+    etag: string;
+    cacheControl: string | null;
+    contentDisposition: string | null;
+    uploadedBy: string | null;
+    uploadedAt: string;
+    updatedAt: string;
+}
+interface StorageConfig {
+    defaultFileSizeLimitBytes: number;
+    maxFileSizeLimitBytes: number;
+    tenantStorageQuotaBytes: number;
+    reservedSpaceBytes: number;
+    signedUrlDefaultTtlSec: number;
+    signedUrlMaxTtlSec: number;
+}
+interface CreateBucketOptions {
+    public?: boolean;
+    fileSizeLimitBytes?: number | null;
+    allowedMimeTypes?: string[] | null;
+}
+interface UpdateBucketOptions {
+    public?: boolean;
+    fileSizeLimitBytes?: number | null;
+    allowedMimeTypes?: string[] | null;
+}
+interface UploadOptions {
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    /** Defaults to false (POST, fails on duplicate). If true, uses PUT (upsert). */
+    upsert?: boolean;
+    abortSignal?: AbortSignal;
+}
+interface DownloadOptions {
+    range?: {
+        start: number;
+        end: number;
+    };
+    abortSignal?: AbortSignal;
+}
+interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    startAfter?: string;
+}
+interface SignedUrlOptions {
+    expiresIn?: number;
+}
+interface SignedUrlResult {
+    url: string;
+    token: string;
+    expiresAt: string;
+}
+type UploadBody = Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | string;
+
+/**
+ * Storage module — thin wrapper over the /api/storage/* REST endpoints
+ * exposed by MITWAY-BaaS.
+ *
+ * Surface mirrors what coding agents expect from a Supabase-style storage
+ * SDK but routes through the Mitway backend (no direct S3 calls). Binary
+ * upload/download uses `HttpClient.rawFetch`; JSON operations use the
+ * standard typed `request<T>` path.
+ */
+
+type StorageResult<T> = {
+    data: T | null;
+    error: MitwayBaasError | null;
+};
+declare class StorageBucketClient {
+    private readonly http;
+    private readonly bucketName;
+    constructor(http: HttpClient, bucketName: string);
+    private bucketBase;
+    private objectPath;
+    upload(key: string, body: UploadBody, opts?: UploadOptions): Promise<StorageResult<StorageObject>>;
+    download(key: string, opts?: DownloadOptions): Promise<StorageResult<Blob>>;
+    getStream(key: string, opts?: DownloadOptions): Promise<StorageResult<ReadableStream<Uint8Array>>>;
+    remove(keys: string[]): Promise<StorageResult<{
+        removed: string[];
+    }>>;
+    list(opts?: ListOptions): Promise<StorageResult<StorageObject[]>>;
+    copy(fromKey: string, toKey: string, toBucket?: string): Promise<StorageResult<StorageObject>>;
+    move(fromKey: string, toKey: string, toBucket?: string): Promise<StorageResult<StorageObject>>;
+    createSignedUrl(key: string, opts?: SignedUrlOptions): Promise<StorageResult<SignedUrlResult>>;
+    getPublicUrl(key: string): {
+        data: {
+            url: string;
+        };
+    };
+}
+declare class Storage {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Scope subsequent operations to a single bucket. */
+    from(bucketName: string): StorageBucketClient;
+    listBuckets(): Promise<StorageResult<StorageBucket[]>>;
+    getBucket(name: string): Promise<StorageResult<StorageBucket>>;
+    createBucket(name: string, opts?: CreateBucketOptions): Promise<StorageResult<StorageBucket>>;
+    updateBucket(name: string, opts: UpdateBucketOptions): Promise<StorageResult<StorageBucket>>;
+    deleteBucket(name: string): Promise<StorageResult<null>>;
+    emptyBucket(name: string): Promise<StorageResult<{
+        removed: number;
+    }>>;
+    getConfig(): Promise<StorageResult<StorageConfig>>;
+}
+
 /**
  * MITWAY-BaaS SDK client.
  *
@@ -751,6 +943,7 @@ declare class MitwayBaasClient {
     readonly auth: Auth;
     readonly database: Database;
     readonly realtime: Realtime;
+    readonly storage: Storage;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -791,4 +984,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, Database, HttpClient, 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, TokenManager, type User, createClient, MitwayBaasClient as default };
+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 };