@quatrain/cloudwrapper-supabase 1.1.19 → 1.1.21

package/README.md

@@ -0,0 +1,54 @@
+# @quatrain/cloudwrapper-supabase
+
+This package provides a Cloud Wrapper adapter for Supabase Edge Functions. It allows you to invoke serverless functions in a consistent way across different BaaS providers.
+This package provides a Cloud Wrapper for Supabase, enabling real-time database and storage triggers. It handles the WebSocket connection to Supabase's Realtime service, providing robust connection monitoring and configurable automatic reconnection logic.
+
+## Features
+
+- Listens to database changes (`INSERT`, `UPDATE`, `DELETE`) on your Supabase Postgres database.
+- Listens to storage changes in Supabase Storage.
+- Monitors connection health with a heartbeat mechanism.
+- Provides a configurable strategy for handling disconnections (exit process or attempt to reconnect).
+- Consistent interface provided by `@quatrain/cloudwrapper`.
+- Works with both SaaS and self-hosted Supabase instances.
+
+## Installation
+
+```bash
+# With npm
+npm install @quatrain/cloudwrapper-supabase @supabase/supabase-js
+
+# With yarn
+yarn add @quatrain/cloudwrapper-supabase @supabase/supabase-js
+```
+
+## Usage
+
+```typescript
+import { CloudWrapper } from '@quatrain/cloudwrapper'
+import { SupabaseCloudWrapperAdapter } from '@quatrain/cloudwrapper-supabase'
+import { SupabaseCloudWrapper } from '@quatrain/cloudwrapper-supabase'
+import { BackendAction } from '@quatrain/backend'
+
+// Setup and use the adapter with the CloudWrapper singleton.
+const wrapper = new SupabaseCloudWrapper({
+   url: process.env.SUPABASE_URL,
+   key: process.env.SUPABASE_KEY,
+   // Optional: Determines behavior on disconnection.
+   // - true (default): Exits the process. Ideal for containerized environments
+   //   (e.g., Kubernetes) that will automatically restart the service.
+   // - false: Attempts to reconnect internally.
+   exitOnDisconnect: true,
+})
+
+// Example: Set up a trigger for new rows in a 'profiles' table
+wrapper.databaseTrigger({
+   name: 'new-profile-trigger',
+   model: 'profiles',
+   event: BackendAction.CREATE,
+   script: async ({ after }) => {
+      console.log(`A new profile was created:`, after)
+      // Add your business logic here
+   },
+})
+```

package/lib/SupabaseCloudWrapper.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { AbstractCloudWrapper, DatabaseTriggerType, StorageTriggerType } from '@quatrain/cloudwrapper';
 import { SupabaseClient, RealtimeChannel } from '@supabase/supabase-js';
 import { FileType } from '@quatrain/storage';
@@ -5,6 +6,7 @@ export type SupabaseParams = {
     useEmulator?: boolean;
     url?: string;
     key?: string;
+    exitOnDisconnect?: boolean;
 };
 export type Channel = {
     name: string;
@@ -24,6 +26,8 @@ export declare class SupabaseCloudWrapper extends AbstractCloudWrapper {
     protected _supabaseClient: SupabaseClient | undefined;
     protected _realtimeClient: RealtimeChannel | undefined;
     protected _isInitialized: boolean;
+    protected _heartbeatOkReceived: boolean;
+    protected _connectionTimeout: NodeJS.Timeout | undefined;
     protected _channels: Channels;
     constructor(params: SupabaseParams);
     databaseTrigger(trigger: DatabaseTriggerType): void | {
@@ -37,7 +41,6 @@ export declare class SupabaseCloudWrapper extends AbstractCloudWrapper {
         table: string;
     };
     protected _initialize(): void;
-    poll(): void;
     protected _payload2File(payload: {
         [x: string]: any;
     }): FileType | undefined;

package/lib/SupabaseCloudWrapper.js

@@ -33,6 +33,7 @@ class SupabaseCloudWrapper extends cloudwrapper_1.AbstractCloudWrapper {
     constructor(params) {
         super(params);
         this._isInitialized = false;
+        this._heartbeatOkReceived = false;
         this._channels = { database: [], storage: [] };
         this._initialize();
     }
@@ -86,7 +87,7 @@ class SupabaseCloudWrapper extends cloudwrapper_1.AbstractCloudWrapper {
         var _a;
         this._initialize();
         if (typeof trigger.script !== 'function') {
-            throw new Error(`Passed script value is not a function`);
+            throw new TypeError(`Passed script value is not a function`);
         }
         if (Array.isArray(trigger.event)) {
             const params = trigger.event.forEach((event) => {
@@ -131,21 +132,60 @@ class SupabaseCloudWrapper extends cloudwrapper_1.AbstractCloudWrapper {
     }
     _initialize() {
         if (this._isInitialized === false) {
-            this._supabaseClient = (0, supabase_js_1.createClient)(this._params.url, this._params.key);
+            cloudwrapper_1.CloudWrapper.info(`Starting Supabase client with heartbeat monitoring`);
+            if (this._connectionTimeout) {
+                clearTimeout(this._connectionTimeout);
+            }
+            this._supabaseClient = (0, supabase_js_1.createClient)(this._params.url, this._params.key, {
+                realtime: {
+                    heartbeatIntervalMs: 5000,
+                    heartbeatCallback: (status) => {
+                        console.log('status received', status);
+                        switch (status) {
+                            case 'ok':
+                                if (!this._heartbeatOkReceived) {
+                                    cloudwrapper_1.CloudWrapper.info(`🛜 Supabase Realtime connection established`);
+                                    if (this._connectionTimeout) {
+                                        clearTimeout(this._connectionTimeout);
+                                    }
+                                    this._heartbeatOkReceived = true;
+                                }
+                                break;
+                            case 'timeout':
+                                cloudwrapper_1.CloudWrapper.warn(`⚠️ Supabase Realtime connection timed out`);
+                                break;
+                            case 'disconnected':
+                                // Reconnect only if exitOnDisconnect is explicitly set to false.
+                                if (this._params.exitOnDisconnect === false) {
+                                    cloudwrapper_1.CloudWrapper.warn(`❌ Supabase connection lost. Attempting to reconnect...`);
+                                    this._isInitialized = false;
+                                    this._heartbeatOkReceived = false;
+                                    this._initialize();
+                                }
+                                else {
+                                    // Default behavior: exit to allow for a clean restart by the orchestrator.
+                                    cloudwrapper_1.CloudWrapper.error(`❌ Supabase connection lost. Exiting to allow for a clean restart.`);
+                                    process.exit(1);
+                                }
+                                break;
+                            default:
+                                // do nothing
+                                break;
+                        }
+                    },
+                },
+            });
             this._isInitialized = true;
             cloudwrapper_1.CloudWrapper.info(`Supabase App initialized`);
+            cloudwrapper_1.CloudWrapper.info(`🕘 Supabase Realtime connection is being established`);
+            this._connectionTimeout = setTimeout(() => {
+                if (!this._heartbeatOkReceived) {
+                    cloudwrapper_1.CloudWrapper.error(`❌ Supabase Realtime connection failed to establish after 30 seconds. Exiting.`);
+                    process.exit(1);
+                }
+            }, 30000);
         }
     }
-    poll() {
-        var _a;
-        cloudwrapper_1.CloudWrapper.info(`Supabase client status: ${(_a = this._supabaseClient) === null || _a === void 0 ? void 0 : _a.channel}`);
-        this._channels.storage.forEach((channel) => {
-            var _a;
-            cloudwrapper_1.CloudWrapper.info(`${channel.name}: ${channel.state}`);
-            console.log((_a = channel.channel) === null || _a === void 0 ? void 0 : _a.params);
-        });
-        setTimeout(() => this.poll(), 10000);
-    }
     _payload2File(payload) {
         if (!payload.metadata) {
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/cloudwrapper-supabase",
-  "version": "1.1.19",
+  "version": "1.1.21",
   "license": "MIT",
   "description": "Cloud Wrapper adapter for Supabase",
   "repository": {
@@ -20,9 +20,9 @@
     "@quatrain/core": "^1.1.22"
   },
   "dependencies": {
-    "@quatrain/backend": "^1.1.21",
+    "@quatrain/backend": "^1.1.22",
     "@quatrain/cloudwrapper": "^1.1.14",
-    "@supabase/supabase-js": "2.53.0"
+    "@supabase/supabase-js": "^2.82.0"
   },
   "devDependencies": {
     "@tsconfig/recommended": "^1.0.1",

package/src/SupabaseCloudWrapper.ts

@@ -11,12 +11,14 @@ import {
    SupabaseClient,
    RealtimeChannel,
 } from '@supabase/supabase-js'
+import { HeartbeatStatus } from '@supabase/realtime-js/dist/module/RealtimeClient'
 import { FileType } from '@quatrain/storage'
 
 export type SupabaseParams = {
    useEmulator?: boolean
    url?: string
    key?: string
+   exitOnDisconnect?: boolean
 }
 
 export type Channel = {
@@ -40,6 +42,8 @@ export class SupabaseCloudWrapper extends AbstractCloudWrapper {
    protected _supabaseClient: SupabaseClient | undefined
    protected _realtimeClient: RealtimeChannel | undefined
    protected _isInitialized = false
+   protected _heartbeatOkReceived = false
+   protected _connectionTimeout: NodeJS.Timeout | undefined
    protected _channels: Channels = { database: [], storage: [] }
 
    constructor(params: SupabaseParams) {
@@ -114,7 +118,7 @@ export class SupabaseCloudWrapper extends AbstractCloudWrapper {
       this._initialize()
 
       if (typeof trigger.script !== 'function') {
-         throw new Error(`Passed script value is not a function`)
+         throw new TypeError(`Passed script value is not a function`)
       }
 
       if (Array.isArray(trigger.event)) {
@@ -175,21 +179,77 @@ export class SupabaseCloudWrapper extends AbstractCloudWrapper {
 
    protected _initialize() {
       if (this._isInitialized === false) {
-         this._supabaseClient = createClient(this._params.url, this._params.key)
+         CloudWrapper.info(`Starting Supabase client with heartbeat monitoring`)
+
+         if (this._connectionTimeout) {
+            clearTimeout(this._connectionTimeout)
+         }
+
+         this._supabaseClient = createClient(
+            this._params.url,
+            this._params.key,
+            {
+               realtime: {
+                  heartbeatIntervalMs: 5000,
+                  heartbeatCallback: (status: HeartbeatStatus) => {
+                     console.log('status received', status)
+                     switch (status) {
+                        case 'ok':
+                           if (!this._heartbeatOkReceived) {
+                              CloudWrapper.info(
+                                 `🛜 Supabase Realtime connection established`
+                              )
+                              if (this._connectionTimeout) {
+                                 clearTimeout(this._connectionTimeout)
+                              }
+                              this._heartbeatOkReceived = true
+                           }
+                           break
+                        case 'timeout':
+                           CloudWrapper.warn(
+                              `⚠️ Supabase Realtime connection timed out`
+                           )
+                           break
+                        case 'disconnected':
+                           // Reconnect only if exitOnDisconnect is explicitly set to false.
+                           if (this._params.exitOnDisconnect === false) {
+                              CloudWrapper.warn(
+                                 `❌ Supabase connection lost. Attempting to reconnect...`
+                              )
+                              this._isInitialized = false
+                              this._heartbeatOkReceived = false
+                              this._initialize()
+                           } else {
+                              // Default behavior: exit to allow for a clean restart by the orchestrator.
+                              CloudWrapper.error(
+                                 `❌ Supabase connection lost. Exiting to allow for a clean restart.`
+                              )
+                              process.exit(1)
+                           }
+                           break
+                        default:
+                           // do nothing
+                           break
+                     }
+                  },
+               },
+            }
+         )
          this._isInitialized = true
          CloudWrapper.info(`Supabase App initialized`)
-      }
-   }
+         CloudWrapper.info(
+            `🕘 Supabase Realtime connection is being established`
+         )
 
-   public poll() {
-      CloudWrapper.info(
-         `Supabase client status: ${this._supabaseClient?.channel}`
-      )
-      this._channels.storage.forEach((channel) => {
-         CloudWrapper.info(`${channel.name}: ${channel.state}`)
-         console.log(channel.channel?.params)
-      })
-      setTimeout(() => this.poll(), 10000)
+         this._connectionTimeout = setTimeout(() => {
+            if (!this._heartbeatOkReceived) {
+               CloudWrapper.error(
+                  `❌ Supabase Realtime connection failed to establish after 30 seconds. Exiting.`
+               )
+               process.exit(1)
+            }
+         }, 30000)
+      }
    }
 
    protected _payload2File(payload: {