squarefi-bff-api-module 1.24.35 → 1.25.0

package/README.md

@@ -49,9 +49,19 @@ const cards = await api.issuing.cards.byWalletUuid.getAll({
 
 // 3) Exchange rates helper
 await api.exchange.byOrderType[OrderType.DEPOSIT_FIAT_SEPA].getByFromCurrency(firstWalletUuid);
-```
 
-See the [Examples](#examples) section below for more real-life snippets.
+// 4) Real-time subscriptions (React only)
+import { useSupabaseSubscription } from 'squarefi-bff-api-module';
+
+const { isConnected } = useSupabaseSubscription({
+  config: {
+    channelName: 'my-channel',
+    table: 'transactions',
+    event: '*',
+  },
+  callback: (payload) => console.log('Real-time update:', payload),
+});
+```
 
 ---
 
@@ -59,19 +69,59 @@ See the [Examples](#examples) section below for more real-life snippets.
 
 The SDK reads connection details from process-level variables. When bundling for the browser, tools like **Vite**, **Webpack DefinePlugin**, or **Next.js** can safely inline those values at build time.
 
-| Name                       | Description                                                          | Required                      | Example                       |
-| -------------------------- | -------------------------------------------------------------------- | ----------------------------- | ----------------------------- |
-| `API_URL`                  | Base URL of the BFF **v1** service                                   | ✅                            | `https://api-v1.squarefi.com` |
-| `API_V2_URL`               | Base URL of the BFF **v2** service                                   | ✅                            | `https://api-v2.squarefi.com` |
-| `API_TOTP_URL`             | Base URL of the **TOTP / OTP** micro-service                         | ⚠️ _If you use TOTP features_ | `https://totp.squarefi.com`   |
-| `TENANT_ID`                | Your tenant / organisation identifier                                | ✅                            | `tenant_12345`                |
-| `LOGOUT_URL`               | Frontend route where the user is redirected when refresh token fails | ❌                            | `/auth/logout`                |
-| `SERVER_PUBLIC_KEY_BASE64` | PEM encoded key (base64) used for request signing                    | ✅                            | `MIIBIjANBgkqh…`              |
+| Name                       | Description                                                          | Required                       | Example                       |
+| -------------------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------------------- |
+| `API_URL`                  | Base URL of the BFF **v1** service                                   | ✅                             | `https://api-v1.squarefi.com` |
+| `API_V2_URL`               | Base URL of the BFF **v2** service                                   | ✅                             | `https://api-v2.squarefi.com` |
+| `API_TOTP_URL`             | Base URL of the **TOTP / OTP** micro-service                         | ⚠️ _If you use TOTP features_  | `https://totp.squarefi.com`   |
+| `TENANT_ID`                | Your tenant / organisation identifier                                | ✅                             | `tenant_12345`                |
+| `LOGOUT_URL`               | Frontend route where the user is redirected when refresh token fails | ❌                             | `/auth/logout`                |
+| `SERVER_PUBLIC_KEY_BASE64` | PEM encoded key (base64) used for request signing                    | ✅                             | `MIIBIjANBgkqh…`              |
+| `SUPABASE_URL`             | Supabase project URL for real-time subscriptions                     | ⚠️ _If you use Supabase hooks_ | `https://xyz.supabase.co`     |
+| `SUPABASE_PUBLIC_KEY`      | Supabase public anon key for client authentication                   | ⚠️ _If you use Supabase hooks_ | `eyJhbGciOiJIUzI1NiIs…`       |
 
 > ℹ️ When running in Node.js you can place these variables in a `.env` file and load them with [dotenv](https://npmjs.com/package/dotenv).
 
 ---
 
+## 🔄 React Hooks
+
+The SDK includes React hooks for real-time functionality powered by Supabase:
+
+### useSupabaseSubscription
+
+A hook for subscribing to real-time database changes via Supabase.
+
+```tsx
+import { useSupabaseSubscription } from 'squarefi-bff-api-module';
+
+function MyComponent() {
+  const { isConnected, isClientAvailable } = useSupabaseSubscription({
+    config: {
+      channelName: 'wallet-transactions',
+      table: 'transactions',
+      schema: 'public',
+      event: 'INSERT', // 'INSERT' | 'UPDATE' | 'DELETE' | '*'
+      filter: 'wallet_id=eq.123',
+    },
+    callback: (payload) => {
+      console.log('New transaction:', payload);
+    },
+    enabled: true,
+  });
+
+  if (!isClientAvailable) {
+    return <div>Supabase not configured</div>;
+  }
+
+  return <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>;
+}
+```
+
+> ⚠️ **Important**: The hook will throw an error if Supabase environment variables are missing and you attempt to use it. Make sure to set `SUPABASE_URL` and `SUPABASE_PUBLIC_KEY` environment variables.
+
+---
+
 ## 🗺️ API surface
 
 `squarefi_bff_api_client` is a plain object where every property is a namespaced group of operations. The list below reflects the current SDK version (v1.18.13).

package/dist/hooks/index.d.ts

@@ -1 +1,2 @@
 export * from './useCalc';
+export * from './useSupabaseSubscription';

package/dist/hooks/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./useCalc"), exports);
+__exportStar(require("./useSupabaseSubscription"), exports);

package/dist/hooks/useSupabaseSubscription/config.d.ts

@@ -0,0 +1,2 @@
+import { SubscriptionConfig } from './types';
+export declare const createWalletTransactionsConfig: (walletId: string) => SubscriptionConfig;

package/dist/hooks/useSupabaseSubscription/config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWalletTransactionsConfig = void 0;
+const createWalletTransactionsConfig = (walletId) => ({
+    channelName: `wallet-transactions-${walletId}`,
+    table: 'transactions',
+    filter: `wallet_id=eq.${walletId}`,
+});
+exports.createWalletTransactionsConfig = createWalletTransactionsConfig;

package/dist/hooks/useSupabaseSubscription/index.d.ts

@@ -0,0 +1,3 @@
+export { useSupabaseSubscription } from './useSupabaseSubscription';
+export { useWalletTransactionsSubscription } from './specialized';
+export type { SubscriptionConfig, UseSupabaseSubscriptionProps, UseWalletTransactionsSubscriptionProps } from './types';

package/dist/hooks/useSupabaseSubscription/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWalletTransactionsSubscription = exports.useSupabaseSubscription = void 0;
+var useSupabaseSubscription_1 = require("./useSupabaseSubscription");
+Object.defineProperty(exports, "useSupabaseSubscription", { enumerable: true, get: function () { return useSupabaseSubscription_1.useSupabaseSubscription; } });
+var specialized_1 = require("./specialized");
+Object.defineProperty(exports, "useWalletTransactionsSubscription", { enumerable: true, get: function () { return specialized_1.useWalletTransactionsSubscription; } });

package/dist/hooks/useSupabaseSubscription/specialized.d.ts

@@ -0,0 +1,5 @@
+import { UseWalletTransactionsSubscriptionProps } from './types';
+export declare const useWalletTransactionsSubscription: ({ walletId, callback, enabled, }: UseWalletTransactionsSubscriptionProps) => {
+    isConnected: boolean;
+    isClientAvailable: boolean;
+};

package/dist/hooks/useSupabaseSubscription/specialized.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWalletTransactionsSubscription = void 0;
+const config_1 = require("./config");
+const useSupabaseSubscription_1 = require("./useSupabaseSubscription");
+const useWalletTransactionsSubscription = ({ walletId, callback, enabled = true, }) => (0, useSupabaseSubscription_1.useSupabaseSubscription)({
+    config: (0, config_1.createWalletTransactionsConfig)(walletId || ''),
+    callback,
+    enabled: enabled && !!walletId,
+});
+exports.useWalletTransactionsSubscription = useWalletTransactionsSubscription;

package/dist/hooks/useSupabaseSubscription/types.d.ts

@@ -0,0 +1,17 @@
+export interface SubscriptionConfig {
+    channelName: string;
+    table: string;
+    schema?: string;
+    event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+    filter?: string;
+}
+export interface UseSupabaseSubscriptionProps {
+    config: SubscriptionConfig;
+    callback: (payload?: unknown) => void;
+    enabled?: boolean;
+}
+export interface UseWalletTransactionsSubscriptionProps {
+    walletId: string | undefined;
+    callback: () => void;
+    enabled?: boolean;
+}

package/dist/hooks/useSupabaseSubscription/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/hooks/useSupabaseSubscription/useSupabaseSubscription.d.ts

@@ -0,0 +1,5 @@
+import { UseSupabaseSubscriptionProps } from './types';
+export declare const useSupabaseSubscription: ({ config, callback, enabled }: UseSupabaseSubscriptionProps) => {
+    isConnected: boolean;
+    isClientAvailable: boolean;
+};

package/dist/hooks/useSupabaseSubscription/useSupabaseSubscription.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSupabaseSubscription = void 0;
+const react_1 = require("react");
+const supabase_1 = require("../../utils/supabase");
+const useSupabaseSubscription = ({ config, callback, enabled = true }) => {
+    const subscriptionRef = (0, react_1.useRef)(null);
+    const callbackRef = (0, react_1.useRef)(callback);
+    callbackRef.current = callback;
+    (0, react_1.useEffect)(() => {
+        if (!enabled) {
+            return;
+        }
+        if (!supabase_1.supabaseClient) {
+            throw new Error('Supabase client is not available');
+        }
+        if (subscriptionRef.current) {
+            supabase_1.supabaseClient.removeChannel(subscriptionRef.current);
+            subscriptionRef.current = null;
+        }
+        const subscription = supabase_1.supabaseClient
+            .channel(config.channelName)
+            .on('postgres_changes', Object.assign({ event: config.event || '*', schema: config.schema || 'public', table: config.table }, (config.filter && { filter: config.filter })), (payload) => callbackRef.current(payload))
+            .subscribe();
+        subscriptionRef.current = subscription;
+        return () => {
+            if (subscriptionRef.current && supabase_1.supabaseClient) {
+                supabase_1.supabaseClient.removeChannel(subscriptionRef.current);
+                subscriptionRef.current = null;
+            }
+        };
+    }, [enabled, config.channelName, config.table, config.schema, config.event, config.filter]);
+    return {
+        isConnected: !!subscriptionRef.current,
+        isClientAvailable: !!supabase_1.supabaseClient,
+    };
+};
+exports.useSupabaseSubscription = useSupabaseSubscription;

package/dist/utils/supabase.d.ts

@@ -0,0 +1 @@
+export declare const supabaseClient: import("@supabase/supabase-js").SupabaseClient<any, "public", any> | null;

package/dist/utils/supabase.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supabaseClient = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+const createSupabaseClient = () => {
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabasePublicKey = process.env.SUPABASE_PUBLIC_KEY;
+    if (!supabaseUrl || !supabasePublicKey) {
+        console.warn('Supabase environment variables are missing. Client will not be created.');
+        return null;
+    }
+    return (0, supabase_js_1.createClient)(supabaseUrl, supabasePublicKey);
+};
+exports.supabaseClient = createSupabaseClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.24.35",
+  "version": "1.25.0",
   "description": "Squarefi BFF API client module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,6 +23,7 @@
   "author": "Your Name",
   "license": "MIT",
   "dependencies": {
+    "@supabase/supabase-js": "^2.55.0",
     "@telegram-apps/sdk-react": "^3.1.2",
     "axios": "^1.6.7",
     "lodash.debounce": "^4.0.8",

package/src/hooks/index.ts

@@ -1 +1,2 @@
 export * from './useCalc';
+export * from './useSupabaseSubscription';

package/src/hooks/useSupabaseSubscription/config.ts

@@ -0,0 +1,7 @@
+import { SubscriptionConfig } from './types';
+
+export const createWalletTransactionsConfig = (walletId: string): SubscriptionConfig => ({
+  channelName: `wallet-transactions-${walletId}`,
+  table: 'transactions',
+  filter: `wallet_id=eq.${walletId}`,
+});

package/src/hooks/useSupabaseSubscription/index.ts

@@ -0,0 +1,3 @@
+export { useSupabaseSubscription } from './useSupabaseSubscription';
+export { useWalletTransactionsSubscription } from './specialized';
+export type { SubscriptionConfig, UseSupabaseSubscriptionProps, UseWalletTransactionsSubscriptionProps } from './types';

package/src/hooks/useSupabaseSubscription/specialized.ts

@@ -0,0 +1,14 @@
+import { createWalletTransactionsConfig } from './config';
+import { UseWalletTransactionsSubscriptionProps } from './types';
+import { useSupabaseSubscription } from './useSupabaseSubscription';
+
+export const useWalletTransactionsSubscription = ({
+  walletId,
+  callback,
+  enabled = true,
+}: UseWalletTransactionsSubscriptionProps) =>
+  useSupabaseSubscription({
+    config: createWalletTransactionsConfig(walletId || ''),
+    callback,
+    enabled: enabled && !!walletId,
+  });

package/src/hooks/useSupabaseSubscription/types.ts

@@ -0,0 +1,19 @@
+export interface SubscriptionConfig {
+  channelName: string;
+  table: string;
+  schema?: string;
+  event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+  filter?: string;
+}
+
+export interface UseSupabaseSubscriptionProps {
+  config: SubscriptionConfig;
+  callback: (payload?: unknown) => void;
+  enabled?: boolean;
+}
+
+export interface UseWalletTransactionsSubscriptionProps {
+  walletId: string | undefined;
+  callback: () => void;
+  enabled?: boolean;
+}

package/src/hooks/useSupabaseSubscription/useSupabaseSubscription.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef } from 'react';
+
+import { UseSupabaseSubscriptionProps } from './types';
+
+import { supabaseClient } from '../../utils/supabase';
+
+export const useSupabaseSubscription = ({ config, callback, enabled = true }: UseSupabaseSubscriptionProps) => {
+  const subscriptionRef = useRef<any>(null);
+  const callbackRef = useRef(callback);
+
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    if (!supabaseClient) {
+      throw new Error('Supabase client is not available');
+    }
+
+    if (subscriptionRef.current) {
+      supabaseClient.removeChannel(subscriptionRef.current);
+      subscriptionRef.current = null;
+    }
+
+    const subscription = supabaseClient
+      .channel(config.channelName)
+      .on(
+        'postgres_changes' as any,
+        {
+          event: config.event || '*',
+          schema: config.schema || 'public',
+          table: config.table,
+          ...(config.filter && { filter: config.filter }),
+        },
+        (payload) => callbackRef.current(payload)
+      )
+      .subscribe();
+
+    subscriptionRef.current = subscription;
+
+    return () => {
+      if (subscriptionRef.current && supabaseClient) {
+        supabaseClient.removeChannel(subscriptionRef.current);
+        subscriptionRef.current = null;
+      }
+    };
+  }, [enabled, config.channelName, config.table, config.schema, config.event, config.filter]);
+
+  return {
+    isConnected: !!subscriptionRef.current,
+    isClientAvailable: !!supabaseClient,
+  };
+};

package/src/utils/supabase.ts

@@ -0,0 +1,15 @@
+import { createClient } from '@supabase/supabase-js';
+
+const createSupabaseClient = () => {
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const supabasePublicKey = process.env.SUPABASE_PUBLIC_KEY;
+
+  if (!supabaseUrl || !supabasePublicKey) {
+    console.warn('Supabase environment variables are missing. Client will not be created.');
+    return null;
+  }
+
+  return createClient(supabaseUrl, supabasePublicKey);
+};
+
+export const supabaseClient = createSupabaseClient();