@giaeulate/baas-sdk 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -45,18 +45,43 @@ type RealtimeCallback<T = any> = (payload: RealtimePayload<T>) => void;
  * Base class providing HTTP request infrastructure for all SDK modules
  */
 
+/** Privilege class of the API key. anon = RLS applies (safe for browsers);
+ *  service_role = RLS bypass / admin (server-side only). Both share the
+ *  `baas_sk_` prefix, so the type cannot be inferred — it must be declared. */
+type KeyType = 'anon' | 'service_role';
+interface ClientOptions {
+    /** Defaults to 'service_role' for backward-compat. Set 'anon' in any client
+     *  bundle (browser / mobile app) — see warnIfUnsafeKey. */
+    keyType?: KeyType;
+}
 declare class HttpClient {
     url: string;
     apiKey: string;
+    keyType: KeyType;
     token: string | null;
+    refreshToken: string | null;
     private environment;
     private _onForceLogout;
-    constructor(url?: string, apiKey?: string);
+    private _refreshing;
+    constructor(url?: string, apiKey?: string, options?: ClientOptions);
+    /** SECURITY: a service_role key bypasses RLS and grants admin over every
+     *  tenant. If it ends up in a browser bundle, anyone can extract it. Warn
+     *  loudly when a non-anon key is constructed in a browser context. */
+    private warnIfUnsafeKey;
     /**
      * Set the auth token manually (e.g. restoring from SecureStore in React Native).
      * Persists to both the in-memory property and localStorage so getDynamicToken() works.
      */
     setToken(token: string | null): void;
+    /** Persist the rotating refresh token (used by auto-refresh on 401). In the
+     *  browser the server also sets an HttpOnly `baas_refresh` cookie, so storing
+     *  it here is mainly for non-cookie clients (React Native). */
+    setRefreshToken(token: string | null): void;
+    private getRefreshToken;
+    /** Attempts a single token refresh, deduped across concurrent 401s. Sends the
+     *  stored refresh token (falls back to the HttpOnly cookie in browsers). */
+    private tryRefresh;
+    private doRefresh;
     /**
      * Register a callback invoked on forced logout (401).
      * Use this in React Native instead of the default window.location redirect.
@@ -71,7 +96,7 @@ declare class HttpClient {
     /**
      * Core HTTP request method - DRY principle
      */
-    protected request<T = any>(endpoint: string, options?: RequestOptions): Promise<T>;
+    protected request<T = any>(endpoint: string, options?: RequestOptions, _isRetry?: boolean): Promise<T>;
     protected get<T = any>(endpoint: string): Promise<T>;
     protected post<T = any>(endpoint: string, body?: unknown): Promise<T>;
     protected put<T = any>(endpoint: string, body?: unknown): Promise<T>;
@@ -133,7 +158,23 @@ declare class QueryBuilder {
     is(column: string, value: any): this;
     in(column: string, values: any[]): this;
     not(column: string, operator: string, value: any): this;
+    /** Array/jsonb/range contains (@>). Arrays become a `{a,b}` literal. */
+    contains(column: string, values: any): this;
+    /** Array/jsonb/range contained-by (<@). */
+    containedBy(column: string, values: any): this;
+    /** Array/range overlap (&&). */
+    overlaps(column: string, values: any): this;
+    /** Full-text search (@@). type: fts|plfts|phfts|wfts (tsquery flavour). */
+    textSearch(column: string, query: string, type?: 'fts' | 'plfts' | 'phfts' | 'wfts'): this;
+    private arrayLiteral;
+    /** OR group: `or=(c1,c2)`. Members are dotted `col.op.value` strings. */
     or(filters: string): this;
+    /** AND group: `and=(c1,c2)` — e.g. a range `qty.gt.5,qty.lt.20`. */
+    and(filters: string): this;
+    /** Negated AND group: `not.and=(...)`. */
+    notAnd(filters: string): this;
+    /** Negated OR group: `not.or=(...)`. */
+    notOr(filters: string): this;
     order(column: string, { ascending }?: {
         ascending?: boolean | undefined;
     }): this;
@@ -177,6 +218,26 @@ declare class QueryBuilder {
     } | {
         success: boolean;
     }>;
+    /** Insert-or-update on conflict. [onConflict] is the conflict-target column(s). */
+    upsert(data: any, onConflict: string): Promise<{
+        data: null;
+        error: any;
+        status: number;
+    } | {
+        data: any;
+        error: null;
+        status: number;
+    }>;
+    /**
+     * Count rows matching the current filters (PostgREST parity). Sends
+     * `Prefer: count=exact` and parses the total from the `Content-Range`
+     * response header. Returns `{ count, error, status }`.
+     */
+    count(): Promise<{
+        count: number;
+        error: string | null;
+        status: number;
+    }>;
     private getHeaders;
     private handleResponse;
 }
@@ -192,6 +253,7 @@ interface MFASetupResponse {
 }
 interface AuthModule {
     login(email: string, password: string): Promise<any>;
+    refresh(): Promise<any>;
     logout(): Promise<void>;
     verifyMFA(mfaToken: string, code: string): Promise<any>;
     verifyMFAWithRecoveryCode(mfaToken: string, recoveryCode: string): Promise<any>;
@@ -205,6 +267,10 @@ interface AuthModule {
     validateResetToken(token: string): Promise<any>;
     verifyEmail(token: string): Promise<any>;
     requestEmailVerification(): Promise<any>;
+    signInAnonymous(): Promise<any>;
+    requestOtp(email: string, createUser?: boolean): Promise<any>;
+    verifyOtp(type: 'email_otp' | 'magic_link', email: string, token: string): Promise<any>;
+    upgradeAnonymous(email: string, password: string): Promise<any>;
     getAuthProviders(): Promise<any>;
     getAuthProvider(provider: string): Promise<any>;
     configureAuthProvider(provider: string, clientID: string, clientSecret: string, enabled: boolean): Promise<any>;
@@ -303,6 +369,8 @@ interface StorageBucket {
     id: string;
     name: string;
     is_public: boolean;
+    /** Per-bucket upload cap in bytes (absent = no bucket-specific cap). */
+    max_bytes?: number;
     created_at: string;
 }
 interface StorageModule {
@@ -310,12 +378,22 @@ interface StorageModule {
     upload(file: File, bucketId?: string): Promise<StorageFile>;
     /** List all files across buckets. */
     listFiles(): Promise<StorageFile[]>;
-    /** Get file metadata + a 15-min presigned download URL. */
-    getFile(fileId: string): Promise<StorageFileWithUrl>;
+    /** Get file metadata + a presigned download URL. expiresIn (seconds) controls
+     *  the URL lifetime (default 15m, server cap 7d). */
+    getFile(fileId: string, expiresIn?: number): Promise<StorageFileWithUrl>;
+    /** Create a time-limited signed download URL (Supabase createSignedUrl parity). */
+    createSignedUrl(fileId: string, expiresIn?: number): Promise<{
+        signedUrl: string;
+    }>;
     /** Delete a file by ID. */
     deleteFile(fileId: string): Promise<void>;
-    /** Create a new bucket. */
-    createBucket(name: string, isPublic?: boolean): Promise<StorageBucket>;
+    /** Create a new bucket. maxBytes sets a per-bucket upload cap (omit for none). */
+    createBucket(name: string, isPublic?: boolean, maxBytes?: number): Promise<StorageBucket>;
+    /** Update mutable bucket fields (is_public, max_bytes). */
+    updateBucket(bucketId: string, opts: {
+        isPublic?: boolean;
+        maxBytes?: number;
+    }): Promise<StorageBucket>;
     /** List all buckets. */
     listBuckets(): Promise<StorageBucket[]>;
     /** Get bucket info by ID. */
@@ -324,6 +402,10 @@ interface StorageModule {
     deleteBucket(bucketId: string): Promise<void>;
     /** List files inside a specific bucket. */
     listBucketFiles(bucketId: string): Promise<StorageFile[]>;
+    /** Download a file's bytes via the backend download route (streams + enforces
+     *  the bucket's public/RLS rules; the Bearer is sent so private files work).
+     *  Returns a Blob. */
+    download(fileId: string): Promise<Blob>;
     /** @deprecated Use upload(file, bucketId?) instead. */
     upload(table: string, file: File): Promise<any>;
 }
@@ -450,21 +532,26 @@ interface EnvVarsModule {
  */
 
 interface EmailConfig {
+    id?: string;
     provider: string;
     smtp_host?: string;
     smtp_port?: number;
     smtp_user?: string;
     smtp_password?: string;
+    smtp_secure?: boolean;
     sendgrid_api_key?: string;
     resend_api_key?: string;
     from_email: string;
     from_name?: string;
+    label?: string;
+    is_default?: boolean;
 }
 interface EmailTemplate {
     name: string;
     subject: string;
     text_body?: string;
     html_body?: string;
+    email_config_id?: string | null;
 }
 interface SendEmailInput {
     to: string[];
@@ -472,12 +559,16 @@ interface SendEmailInput {
     text_body?: string;
     html_body?: string;
     template_id?: string;
+    config_id?: string;
     template_data?: Record<string, any>;
 }
 interface EmailModule {
     send(input: SendEmailInput): Promise<any>;
     getConfig(): Promise<any>;
+    listConfigs(): Promise<any>;
     saveConfig(config: EmailConfig): Promise<any>;
+    setDefaultConfig(id: string): Promise<any>;
+    deleteConfig(id: string): Promise<any>;
     createTemplate(template: EmailTemplate): Promise<any>;
     listTemplates(): Promise<any>;
     getTemplate(id: string): Promise<any>;
@@ -562,6 +653,10 @@ interface AuditLogsOptions {
 interface AuditModule {
     list(options?: AuditLogsOptions): Promise<any>;
     getActions(): Promise<any>;
+    exportLogs(format: 'csv' | 'json', options?: AuditLogsOptions): Promise<any>;
+    purgePreview(olderThanDays: number): Promise<any>;
+    purge(olderThanDays: number): Promise<any>;
+    clearAll(): Promise<any>;
 }
 
 /**
@@ -639,14 +734,26 @@ interface BranchesModule {
 }
 
 /**
- * Realtime Module - WebSocket subscriptions
+ * Realtime Module - WebSocket subscriptions (CDC tables, Broadcast, Presence)
  */
 
 interface Subscription {
     unsubscribe: () => void;
 }
+interface PresenceHandle {
+    leave: () => void;
+}
 interface RealtimeModule {
-    subscribe<T = any>(table: string, action: RealtimeAction, callback: RealtimeCallback<T>): Promise<Subscription>;
+    /** Subscribe to table changes. `filter` narrows delivery per-subscription
+     *  (PostgREST-style "op.value" specs, e.g. { status: 'eq.pending' }). */
+    subscribe<T = any>(table: string, action: RealtimeAction, callback: RealtimeCallback<T>, filter?: Record<string, string>): Promise<Subscription>;
+    /** Subscribe to an ephemeral Broadcast channel (no DB, no RLS). */
+    subscribeBroadcast(channel: string, callback: (payload: any) => void): Promise<Subscription>;
+    /** Publish a message to a Broadcast channel. */
+    broadcast(channel: string, payload: unknown): void;
+    /** Join a Presence channel with an arbitrary state object. The callback
+     *  receives sync/join/leave events with the member list. */
+    subscribePresence(channel: string, state: unknown, callback: (msg: any) => void): Promise<PresenceHandle>;
 }
 
 /**
@@ -658,6 +765,7 @@ interface ApiKeysModule {
     list(): Promise<any>;
     revoke(keyId: string): Promise<any>;
     delete(keyId: string): Promise<any>;
+    setBrand(keyId: string, emailConfigId: string): Promise<any>;
     getInstanceToken(): Promise<any>;
     regenerateInstanceToken(): Promise<any>;
 }
@@ -712,6 +820,69 @@ interface IPWhitelistModule {
     delete(id: string): Promise<any>;
 }
 
+/**
+ * Cache Management Module
+ */
+
+type CacheStrategy = 'no_cache' | 'ttl_only' | 'cdc_invalidation' | 'write_through';
+interface CacheStatus {
+    connected: boolean;
+    backend: string;
+    version: string;
+    ping_latency_ms: number;
+    circuit_state: string;
+    cdc_lag_seconds: number;
+}
+interface CacheStats {
+    memory_used: string;
+    memory_used_bytes: number;
+    db_size: number;
+    uptime_seconds: number;
+    ops_per_sec: number;
+    namespaces_total: number;
+}
+interface CachePolicy {
+    namespace: string;
+    strategy: CacheStrategy;
+    ttl_seconds: number;
+    use_versioning: boolean;
+    is_default: boolean;
+}
+interface CacheKey {
+    key: string;
+    ttl_seconds: number;
+}
+interface CacheKeysResponse {
+    keys: CacheKey[];
+    next_cursor: number;
+    has_more: boolean;
+}
+interface CacheKeyInspect {
+    key: string;
+    exists: boolean;
+    ttl_seconds: number;
+    size_bytes: number;
+    value_preview: string;
+    value_truncated: boolean;
+}
+interface CacheModule {
+    getStatus(): Promise<CacheStatus>;
+    getStats(): Promise<CacheStats>;
+    listPolicies(): Promise<{
+        policies: CachePolicy[];
+    }>;
+    updatePolicy(namespace: string, body: {
+        strategy: CacheStrategy;
+        ttl_seconds: number;
+        use_versioning: boolean;
+    }): Promise<any>;
+    removePolicy(namespace: string): Promise<any>;
+    invalidateNamespace(namespace: string): Promise<any>;
+    invalidateAll(): Promise<any>;
+    listKeys(prefix: string, cursor?: number, count?: number): Promise<CacheKeysResponse>;
+    inspectKey(key: string): Promise<CacheKeyInspect>;
+}
+
 /**
  * Main BaaS Client - Composes all feature modules
  *
@@ -753,11 +924,20 @@ declare class BaasClient extends HttpClient {
     readonly corsOrigins: CorsOriginsModule;
     readonly policies: PoliciesModule;
     readonly ipWhitelist: IPWhitelistModule;
-    constructor(url?: string, apiKey?: string);
+    readonly cache: CacheModule;
+    constructor(url?: string, apiKey?: string, options?: ClientOptions);
     /**
      * Create a query builder for fluent data queries
      */
     from(table: string): QueryBuilder;
+    /**
+     * Invoke a PL/pgSQL function (PostgREST `.rpc()` parity). Runs under the
+     * caller's RLS context; args bind by name and are $N-safe. Pass [params] for
+     * POST (named args in the body) or set `opts.get = true` for the GET variant.
+     */
+    rpc(fn: string, params?: Record<string, any>, opts?: {
+        get?: boolean;
+    }): Promise<any>;
     login(email: string, password: string): Promise<any>;
     verifyMFA(mfaToken: string, code: string): Promise<any>;
     getProfile(): Promise<any>;
@@ -795,7 +975,7 @@ declare class BaasClient extends HttpClient {
     listStorageFiles(): Promise<StorageFile[]>;
     getStorageFile(fileId: string): Promise<StorageFileWithUrl>;
     deleteStorageFile(fileId: string): Promise<void>;
-    createStorageBucket(name: string, isPublic?: boolean): Promise<StorageBucket>;
+    createStorageBucket(name: string, isPublic?: boolean, maxBytes?: number): Promise<StorageBucket>;
     listStorageBuckets(): Promise<StorageBucket[]>;
     getStorageBucket(bucketId: string): Promise<StorageBucket>;
     deleteStorageBucket(bucketId: string): Promise<void>;
@@ -805,6 +985,7 @@ declare class BaasClient extends HttpClient {
     listApiKeys(): Promise<any>;
     revokeApiKey(keyId: string): Promise<any>;
     deleteApiKey(keyId: string): Promise<any>;
+    setApiKeyBrand(keyId: string, emailConfigId: string): Promise<any>;
     getInstanceToken(): Promise<any>;
     regenerateInstanceToken(): Promise<any>;
     createBackup(options?: any): Promise<any>;
@@ -828,7 +1009,10 @@ declare class BaasClient extends HttpClient {
     generateMigration(tableName: string, changes: any[]): Promise<any>;
     sendEmail(input: any): Promise<any>;
     getEmailConfig(): Promise<any>;
+    listEmailConfigs(): Promise<any>;
     saveEmailConfig(config: any): Promise<any>;
+    setDefaultEmailConfig(id: string): Promise<any>;
+    deleteEmailConfig(id: string): Promise<any>;
     createEmailTemplate(template: any): Promise<any>;
     listEmailTemplates(): Promise<any>;
     getEmailTemplate(id: string): Promise<any>;
@@ -873,7 +1057,11 @@ declare class BaasClient extends HttpClient {
     testWebhook(id: string): Promise<any>;
     listAuditLogs(options?: any): Promise<any>;
     getAuditActions(): Promise<any>;
-    subscribe<T = any>(table: string, action: RealtimeAction, callback: RealtimeCallback<T>): Promise<Subscription>;
+    exportAuditLogs(format: 'csv' | 'json', options?: any): Promise<any>;
+    previewPurgeAuditLogs(olderThanDays: number): Promise<any>;
+    purgeAuditLogs(olderThanDays: number): Promise<any>;
+    clearAllAuditLogs(): Promise<any>;
+    subscribe<T = any>(table: string, action: RealtimeAction, callback: RealtimeCallback<T>, filter?: Record<string, string>): Promise<Subscription>;
     getEnvironmentStatus(): Promise<EnvironmentStatus>;
     initTestEnvironment(): Promise<any>;
     promoteTestToProd(): Promise<PromoteResult>;
@@ -889,4 +1077,4 @@ declare class BaasClient extends HttpClient {
     deleteIPWhitelistEntry(id: string): Promise<any>;
 }
 
-export { type ApiKeysModule, type ApiResponse, type ApplicationLogsOptions, type AuditLogsOptions, type AuditModule, type AuthModule, BaasClient, type BackupsModule, type BranchesModule, type CorsOriginsModule, type CreatePolicyInput, type DatabaseModule, type EmailConfig, type EmailModule, type EmailTemplate, type EnvVarsModule, type EnvironmentsModule, type FunctionsModule, type GraphQLModule, HttpClient, type HttpMethod, type IPWhitelistEntry, type IPWhitelistModule, type JobInput, type JobUpdateInput, type JobsModule, type LogDrainInput, type LogDrainUpdateInput, type LogDrainsModule, type MetricsModule, type MigrationsModule, type PaginationOptions, type PoliciesModule, type Policy, QueryBuilder, type QueryFilter, type RealtimeModule, type RequestLogsOptions, type RequestOptions, type SearchModule, type SearchOptions, type SendEmailInput, type StorageBucket, type StorageFile, type StorageFileWithUrl, type StorageModule, type Subscription, type TimeseriesOptions, type UsersModule, type WebhookInput, type WebhookUpdateInput, type WebhooksModule };
+export { type ApiKeysModule, type ApiResponse, type ApplicationLogsOptions, type AuditLogsOptions, type AuditModule, type AuthModule, BaasClient, type BackupsModule, type BranchesModule, type CacheKey, type CacheKeyInspect, type CacheKeysResponse, type CacheModule, type CachePolicy, type CacheStats, type CacheStatus, type CacheStrategy, type CorsOriginsModule, type CreatePolicyInput, type DatabaseModule, type EmailConfig, type EmailModule, type EmailTemplate, type EnvVarsModule, type EnvironmentsModule, type FunctionsModule, type GraphQLModule, HttpClient, type HttpMethod, type IPWhitelistEntry, type IPWhitelistModule, type JobInput, type JobUpdateInput, type JobsModule, type LogDrainInput, type LogDrainUpdateInput, type LogDrainsModule, type MetricsModule, type MigrationsModule, type PaginationOptions, type PoliciesModule, type Policy, QueryBuilder, type QueryFilter, type RealtimeModule, type RequestLogsOptions, type RequestOptions, type SearchModule, type SearchOptions, type SendEmailInput, type StorageBucket, type StorageFile, type StorageFileWithUrl, type StorageModule, type Subscription, type TimeseriesOptions, type UsersModule, type WebhookInput, type WebhookUpdateInput, type WebhooksModule };