@mitway/sdk 0.2.4 → 0.4.0

package/dist/index.d.cts

@@ -70,6 +70,7 @@ declare class TokenManager {
  */
 
 type PostgresChangesEventSelector = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+/** Filter for any event (including the `*` catch-all). */
 interface PostgresChangesFilter {
     event: PostgresChangesEventSelector;
     schema?: string;
@@ -77,8 +78,8 @@ interface PostgresChangesFilter {
     /** PostgREST-style filter: `column=op.value` or `column=in.(a,b,c)`. */
     filter?: string;
 }
-interface PostgresChangesPayload<T = Record<string, unknown>> {
-    type: 'INSERT' | 'UPDATE' | 'DELETE';
+/** Common shape shared by every postgres_changes payload variant. */
+interface PostgresChangesPayloadBase {
     schema: string;
     table: string;
     commit_timestamp: string;
@@ -86,10 +87,33 @@ interface PostgresChangesPayload<T = Record<string, unknown>> {
         name: string;
         type: string;
     }>;
-    record?: T;
-    old_record?: T;
     errors?: string[];
 }
+/** INSERT: the new row is in `new`. `old` is kept as an empty object so
+ *  code that accesses both fields never needs optional chaining. */
+interface PostgresChangesInsertPayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'INSERT';
+    new: T;
+    old: Record<string, never>;
+}
+/** UPDATE: both `new` and `old` are populated. `old` is `Partial<T>`
+ *  because RLS / REPLICA IDENTITY may strip columns the subscriber can't
+ *  see. */
+interface PostgresChangesUpdatePayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'UPDATE';
+    new: T;
+    old: Partial<T>;
+}
+/** DELETE: the deleted row is in `old`. On RLS-enabled tables only
+ *  primary-key columns are populated. `new` is always an empty object. */
+interface PostgresChangesDeletePayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'DELETE';
+    new: Record<string, never>;
+    old: Partial<T>;
+}
+/** Discriminated union — what the `'*'` overload of `on('postgres_changes',
+ *  ...)` passes to the callback. */
+type PostgresChangesPayload<T = Record<string, unknown>> = PostgresChangesInsertPayload<T> | PostgresChangesUpdatePayload<T> | PostgresChangesDeletePayload<T>;
 interface BroadcastFilter {
     event: string;
 }
@@ -140,11 +164,6 @@ interface ChannelOptions {
          *  requested on a private channel. Default: `false` (open topic). */
         private?: boolean;
         broadcast?: {
-            /** When true, `channel.send(...)` resolves only after the server
-             *  ack'd the publish — useful if the app wants to know the
-             *  message_id assigned by the server. Default: `false`
-             *  (fire-and-forget). */
-            ack?: boolean;
             /** When `false`, the sending socket is excluded from the fan-out.
              *  Default: `true` (sender also receives its own broadcasts). */
             self?: boolean;
@@ -158,9 +177,13 @@ interface ChannelOptions {
     };
 }
 type ChannelStatus = 'SUBSCRIBED' | 'CHANNEL_ERROR' | 'TIMED_OUT' | 'CLOSED';
-type ChannelStatusCallback = (status: ChannelStatus, error?: {
-    code: string;
-    message: string;
+/** Callback invoked for every channel status transition. The second
+ *  argument is a standard `Error` (so consumers can annotate it as
+ *  `err: Error` out of the box) with a non-standard `.code` string
+ *  attached for programmatic discrimination (`SUBSCRIBE_FAILED`,
+ *  `CONNECT_FAILED`, `REJOIN_FAILED`, …). */
+type ChannelStatusCallback = (status: ChannelStatus, error?: Error & {
+    code?: string;
 }) => void;
 interface RealtimeOptions {
     path?: string;
@@ -168,9 +191,10 @@ interface RealtimeOptions {
     timeoutMs?: number;
     extraAuth?: Record<string, string>;
 }
-type PostgresChangesCallback<T = Record<string, unknown>> = (payload: PostgresChangesPayload<T>) => void;
 type BroadcastCallback<T = Record<string, unknown>> = (payload: BroadcastPayload<T>) => void;
-type PresenceCallback<T = Record<string, unknown>> = (payload: PresencePayload<T>) => void;
+type PresenceSyncCallback = () => void;
+type PresenceJoinCallback<T = Record<string, unknown>> = (payload: PresenceJoinPayload<T>) => void;
+type PresenceLeaveCallback<T = Record<string, unknown>> = (payload: PresenceLeavePayload<T>) => void;
 declare class RealtimeChannel {
     readonly topic: string;
     private readonly realtime;
@@ -204,9 +228,40 @@ declare class RealtimeChannel {
      *  statusCallback (from the original subscribe()) fires again with
      *  'SUBSCRIBED' or 'CHANNEL_ERROR' so the app can reflect state. */
     _rejoinAfterReconnect(): Promise<void>;
-    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: PostgresChangesFilter, callback: PostgresChangesCallback<T>): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'INSERT';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesInsertPayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'UPDATE';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesUpdatePayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'DELETE';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesDeletePayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: '*';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesPayload<T>) => void): this;
     on<T = Record<string, unknown>>(type: 'broadcast', filter: BroadcastFilter, callback: BroadcastCallback<T>): this;
-    on<T = Record<string, unknown>>(type: 'presence', filter: PresenceFilter, callback: PresenceCallback<T>): this;
+    on(type: 'presence', filter: {
+        event: 'sync';
+    }, callback: PresenceSyncCallback): this;
+    on<T = Record<string, unknown>>(type: 'presence', filter: {
+        event: 'join';
+    }, callback: PresenceJoinCallback<T>): this;
+    on<T = Record<string, unknown>>(type: 'presence', filter: {
+        event: 'leave';
+    }, callback: PresenceLeaveCallback<T>): this;
     /**
      * Register or refresh this client's presence entry on the channel. Safe
      * to call many times — state replaces (not merges). Starts a heartbeat
@@ -248,21 +303,27 @@ declare class RealtimeChannel {
      * events, write to your own application table and enable
      * `postgres_changes` on it; the SDK will surface the INSERT as a
      * `postgres_changes` event without a separate channel.send call.
+     *
+     * The returned promise always resolves with the server ack, so callers
+     * can `await channel.send(...)` to confirm delivery + get the server-
+     * assigned `message_id`. There's no performance cost — Socket.IO piggy-
+     * backs the ack on the same frame. Callers that don't need it just
+     * don't await.
      */
     send<T extends Record<string, unknown>>(args: {
         type: 'broadcast';
         event: string;
         payload: T;
     }): Promise<{
-        ok: true;
+        status: 'ok';
         message_id: string;
     } | {
-        ok: false;
+        status: 'error';
         error: {
             code: string;
             message: string;
         };
-    } | void>;
+    }>;
     /**
      * Replay SQL-originated broadcasts on this topic since the given
      * timestamp. Delivered only to this socket (same envelope format as
@@ -301,13 +362,14 @@ declare class Realtime {
      * The optional `opts` argument lets the caller configure the channel:
      *   * `config.private` — enable subscribe-side authorization against
      *     `realtime.authorize_subscribe(...)` on the tenant DB.
-     *   * `config.broadcast.ack` — `channel.send()` resolves with the
-     *     server's ack (message_id) instead of fire-and-forget.
      *   * `config.broadcast.self` — `false` excludes the sender from the
      *     fan-out (defaults to `true`).
      *   * `config.presence.key` — stable presence key to group multiple
      *     tabs of the same user under one entry.
      *
+     * `channel.send()` always resolves with the server ack (see its own
+     * docstring); there is no separate opt-in needed.
+     *
      * Options are locked in when the channel is first created; subsequent
      * `.channel('same')` calls with different opts are ignored. Pass a
      * different topic to get a different-configured channel.
@@ -486,6 +548,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>;
@@ -656,6 +730,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.
  *
@@ -689,6 +893,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
@@ -729,4 +934,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 PostgresChangesEventSelector, type PostgresChangesFilter, type PostgresChangesPayload, 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 };