squarefi-bff-api-module 1.24.35 → 1.25.1

package/CHANGELOG.md

@@ -4,35 +4,228 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+ƒ
 
-## [1.25.2] - 2025-07-28
+## [1.25.0] - 2025-08-19
+
+### Added
+
+- Real-time functionality with Supabase integration
+
+## [1.24.35] - 2025-08-19
+
+### Changed
+
+- Updated CSV export functionality for wallet transactions to use apiClientV2 and enhanced request type
+
+## [1.24.34] - 2025-08-14
+
+### Changed
+
+- Enhanced TransactionList request type by adding pagination and filtering options
+
+## [1.24.33] - 2025-08-14
+
+### Changed
+
+- Updated response type for WalletsTransactionsController to include total and data fields
+
+## [1.24.32] - 2025-08-14
+
+### Changed
+
+- Updated response type for WalletsTransactionsController to include JSON content structure
+
+## [1.24.31] - 2025-08-14
+
+### Changed
+
+- Streamlined TransactionList request type by integrating existing operations and removing redundant fields
+
+## [1.24.30] - 2025-08-14
+
+### Changed
+
+- Removed unused UserData types and enforced required fields for transaction list request
+
+## [1.24.29] - 2025-08-11
+
+### Added
+
+- PURCHASE type to CardTransactionType enum
+
+## [1.24.28] - 2025-08-11
+
+### Fixed
+
+- Enforced required fields for transaction list request parameters
+
+## [1.24.27] - 2025-08-11
+
+### Changed
+
+- Updated transaction list API types and simplified transaction retrieval parameters
+
+## [1.24.26] - 2025-08-08
+
+### Added
+
+- Terms confirmation endpoint and types for KYC process
+
+## [1.24.25] - 2025-08-08
+
+### Added
+
+- PAYMENT type to CardTransactionType enum
+
+## [1.24.24] - 2025-08-08
+
+### Added
+
+- DECLINED status to CardTransactionStatus enum
+
+## [1.24.23] - 2025-08-08
+
+### Added
+
+- COMPLETED status to CardTransactionStatus enum
+
+## [1.24.22] - 2025-08-06
+
+### Fixed
+
+- Updated tenant config endpoint and added optional limits property to API types
+
+## [1.24.21] - 2025-08-01
+
+### Changed
+
+- Introduced ExtendedKey interface to enhance key management types in API
+
+## [1.24.20] - 2025-08-01
+
+### Added
+
+- Integrated frontend module into API structure for enhanced functionality
+
+## [1.24.19] - 2025-08-01
+
+### Added
+
+- Frontend access key management types for creating, listing, regenerating, and revoking API keys
+
+## [1.24.18] - 2025-08-01
+
+### Changed
+
+- Made is_subtract and is_reverse fields mandatory in API types for consistency
+
+## [1.24.17] - 2025-08-01
+
+### Fixed
+
+- Corrected spelling of is_subsctract to is_subtract in API types and updated related calculations in useCalc hook
+
+## [1.24.16] - 2025-08-01
+
+### Added
+
+- Optional is_subsctract and is_reverse fields to various transaction types for improved flexibility
+
+## [1.24.15] - 2025-07-31
+
+### Added
+
+- Extended account details with optional ACH, RTP, wire, and SWIFT structures for enhanced payment processing
+
+## [1.24.14] - 2025-07-31
+
+### Changed
+
+- Enhanced issuing API methods to return ExtendedSubAccountResponse with sub_account_id
+
+## [1.24.13] - 2025-07-30
+
+### Changed
+
+- Updated SubAccountResponse type and enhanced balance method to return sub_account_id
+
+## [1.24.12] - 2025-07-29
+
+### Added
+
+- consent_text field to card details type for enhanced data handling
+
+## [1.24.11] - 2025-07-28
 
 ### Added
 
 - New wallet transaction record types for card transfers
 
-## [1.25.1] - 2025-07-28
+## [1.24.10] - 2025-07-28
 
 ### Added
 
 - RN_CARDS_OFFRAMP order type and corresponding API request/response structures
 
-## [1.25.0] - 2025-07-23
+## [1.24.9] - 2025-07-23
 
 ### Changed
 
-- Enhanced refresh token handling for Telegram sign-in methods in TMA
-- Updated Telegram auth types to use request/response structures for improved type safety with optional refresh_token
+- Removed unnecessary console logs from apiClientFactory and tokensFactory for cleaner code
+
+## [1.24.8] - 2025-07-23
+
+### Changed
+
+- Streamlined refreshTokens by removing miniApp logs and integrating initData restoration
+
+## [1.24.7] - 2025-07-23
+
+### Fixed
+
+- Awaited miniApp.mount() in refreshTokens to ensure proper initialization of the SDK
+
+## [1.24.6] - 2025-07-23
 
 ### Added
 
-- Improved Telegram authentication workflow with better token management
+- Telegram SDK initialization in tokensFactory
+
+## [1.24.4] - 2025-07-23
+
+### Added
+
+- Console logs in tokensFactory for enhanced debugging of initData and miniApp
+
+## [1.24.3] - 2025-07-23
+
+### Added
+
+- Additional console logs in refreshTokens for improved debugging of token handling
+
+## [1.24.2] - 2025-07-23
+
+### Changed
+
+- Improved error handling in refreshTokens function and added debug logs for better traceability
+
+## [1.24.1] - 2025-07-23
+
+### Added
+
+- Console logs for token refresh handling and authentication flow insights
 
 ## [1.24.0] - 2025-07-23
 
 ### Changed
 
-- Version release for accumulated features
+- Enhanced refresh token handling for Telegram sign-in methods in TMA
+- Updated Telegram auth types to use request/response structures for improved type safety with optional refresh_token
+
+### Added
+
+- Improved Telegram authentication workflow with better token management
 
 ## [1.23.5] - 2025-07-22
 

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, ...props }: UseWalletTransactionsSubscriptionProps) => {
+    isConnected: boolean;
+    isClientAvailable: boolean;
+};

package/dist/hooks/useSupabaseSubscription/specialized.js

@@ -0,0 +1,21 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWalletTransactionsSubscription = void 0;
+const config_1 = require("./config");
+const useSupabaseSubscription_1 = require("./useSupabaseSubscription");
+const useWalletTransactionsSubscription = (_a) => {
+    var { walletId } = _a, props = __rest(_a, ["walletId"]);
+    return (0, useSupabaseSubscription_1.useSupabaseSubscription)(Object.assign(Object.assign({}, props), { config: (0, config_1.createWalletTransactionsConfig)(walletId || '') }));
+};
+exports.useWalletTransactionsSubscription = useWalletTransactionsSubscription;

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

@@ -0,0 +1,16 @@
+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;
+    key?: string;
+}
+export interface UseWalletTransactionsSubscriptionProps extends Omit<UseSupabaseSubscriptionProps, 'config'> {
+    walletId: string | undefined;
+}

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, key }: UseSupabaseSubscriptionProps) => {
+    isConnected: boolean;
+    isClientAvailable: boolean;
+};

package/dist/hooks/useSupabaseSubscription/useSupabaseSubscription.js

@@ -0,0 +1,36 @@
+"use strict";
+'use client';
+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, key }) => {
+    const subscriptionRef = (0, react_1.useRef)(null);
+    const callbackRef = (0, react_1.useRef)(callback);
+    callbackRef.current = callback;
+    (0, react_1.useEffect)(() => {
+        if (!enabled || !supabase_1.supabaseClient) {
+            return;
+        }
+        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, supabase_1.supabaseClient, key]);
+    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,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supabaseClient = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+// Создаем клиент только если есть необходимые environment переменные
+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.1",
   "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,9 @@
+import { createWalletTransactionsConfig } from './config';
+import { UseWalletTransactionsSubscriptionProps } from './types';
+import { useSupabaseSubscription } from './useSupabaseSubscription';
+
+export const useWalletTransactionsSubscription = ({ walletId, ...props }: UseWalletTransactionsSubscriptionProps) =>
+  useSupabaseSubscription({
+    ...props,
+    config: createWalletTransactionsConfig(walletId || ''),
+  });

package/src/hooks/useSupabaseSubscription/types.ts

@@ -0,0 +1,18 @@
+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;
+  key?: string;
+}
+
+export interface UseWalletTransactionsSubscriptionProps extends Omit<UseSupabaseSubscriptionProps, 'config'> {
+  walletId: string | undefined;
+}

package/src/hooks/useSupabaseSubscription/useSupabaseSubscription.ts

@@ -0,0 +1,53 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import { UseSupabaseSubscriptionProps } from './types';
+
+import { supabaseClient } from '../../utils/supabase';
+
+export const useSupabaseSubscription = ({ config, callback, enabled = true, key }: UseSupabaseSubscriptionProps) => {
+  const subscriptionRef = useRef<any>(null);
+  const callbackRef = useRef(callback);
+
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled || !supabaseClient) {
+      return;
+    }
+
+    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, supabaseClient, key]);
+
+  return {
+    isConnected: !!subscriptionRef.current,
+    isClientAvailable: !!supabaseClient,
+  };
+};

package/src/utils/supabase.ts

@@ -0,0 +1,16 @@
+import { createClient } from '@supabase/supabase-js';
+
+// Создаем клиент только если есть необходимые environment переменные
+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();