squarefi-bff-api-module 1.30.10 → 1.31.0

package/CHANGELOG.md

@@ -4,7 +4,302 @@ 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.31] - 2025-11-19
+
+### Changed
+
+- Updated useFileUpload hook to require bucket and support folder structure for file uploads
+- Removed useUserFiles hook
+
+## [1.30.10] - 2025-11-19
+
+### Added
+
+- Added balance and total_balance fields to wallet API response
+
+## [1.30.9] - 2025-11-17
+
+### Changed
+
+- Updated wallets API to accept query parameters and renamed type generation script in package.json
+
+## [1.30.8] - 2025-11-14
+
+### Changed
+
+- Removed outdated HIFI transaction types and added new L2F transaction types for deposits and withdrawals
+- Updated OrderType enum to include new deposit and withdrawal types for HIFI and L2F
+
+## [1.30.7] - 2025-11-14
+
+### Added
+
+- Added HIFI_ACH_WITHDRAWAL and HIFI_ACH_DEPOSIT to OrderType enum
+- Added check-types script to package.json
+
+## [1.30.6] - 2025-11-14
+
+### Changed
+
+- Removed DepositInstruction interface and updated deposit_instructions type in VirtualAccountAccountDetails
+
+## [1.30.5] - 2025-11-14
+
+### Added
+
+- Added from_crypto_address field to order request parameters in API types
+
+## [1.30.4] - 2025-11-14
+
+### Added
+
+- Added OrderTypeKycRail type and updated OrderInfo interface to include order_types_kyc_rails and is_trusted fields
+
+## [1.30.3] - 2025-11-14
+
+### Added
+
+- Added OrderPaymentMethod enum and updated OrderInfo interface to use it
+
+## [1.30.2] - 2025-11-12
+
+### Changed
+
+- Removed unused OrderMetaExtended type and simplified OrderDetails type definition
+
+## [1.30.1] - 2025-11-12
+
+### Added
+
+- Introduced new interfaces for simplified currency and wallet, renamed payment originator types, and extended order meta with additional fields
+
+## [1.30.0] - 2025-11-10
+
+### Added
+
+- Added new endpoints for listing orders by wallet and retrieving order details by ID, along with corresponding request/response types
+
+## [1.29.3] - 2025-11-07
+
+### Added
+
+- Extended DepositInstruction with CHAPS and FPS instruction types and added sort_code field
+
+## [1.29.2] - 2025-11-07
+
+### Added
+
+- Added iban field to ACH interface in API types
+
+## [1.29.1] - 2025-11-07
+
+### Added
+
+- Added SEPA_CT instruction type and corresponding SEPA interface to DepositInstruction
+
+## [1.29.0] - 2025-10-29
+
+### Added
+
+- Introduced EXCHANGE_OMNI order type and updated related API request/response types
+- Added Supabase Storage integration with user-level security and file management features
+
+## [1.28.0] - 2025-10-27
+
+### Added
+
+- Added new order types for card withdrawals and updated API types accordingly
+
+## [1.27.8] - 2025-10-24
+
+### Fixed
+
+- Corrected typo in WITHDRAWAL_CRYPTO request type by changing 'is_substract' to 'is_subsctract'
+
+## [1.27.7] - 2025-10-24
+
+### Fixed
+
+- Corrected typo in WITHDRAWAL_CRYPTO request type by changing 'is_subtract' to 'is_substract'
+
+## [1.27.6] - 2025-10-24
+
+### Changed
+
+- Enhanced tenant config type definition and removed deprecated endpoints for improved clarity and type safety
+
+## [1.27.5] - 2025-10-23
+
+### Fixed
+
+- Made virtual_account_id optional in OrderWithVirtualAccountParams for improved flexibility
+
+## [1.27.4] - 2025-10-23
+
+### Changed
+
+- Version bump for latest changes
+
+## [1.27.3] - 2025-10-23
+
+### Fixed
+
+- Simplified SEGREGATED_CRYPTO_TRANSFER request type by using Omit to exclude to_currency_id for better type safety
+
+## [1.27.2] - 2025-10-23
+
+### Fixed
+
+- Updated SEGREGATED_CRYPTO_TRANSFER request type to disallow to_currency_id for improved type safety
+
+## [1.27.1] - 2025-10-23
+
+### Added
+
+- Added is_reverse flag to transfer order parameters and refined order type definitions for improved clarity
+
+## [1.27.0] - 2025-10-23
+
+### Changed
+
+- Removed HIFI_CRYPTO_TRANSFER order type and consolidated order request/response structures for improved maintainability
+
+### Added
+
+- Added new off-ramp order types and corresponding request/response structures for ACH, Wire, SWIFT, and SEPA transactions
+- Added Prettier for code formatting and enhanced OrderType enum with new onramp/offramp types
+
+## [1.26.14] - 2025-10-22
+
+### Fixed
+
+- Made deposit_instructions optional in VirtualAccount and VirtualAccountDetailItem interfaces
+
+## [1.26.13] - 2025-10-22
+
+### Changed
+
+- Enhanced DepositInstruction types with ACH, FEDWIRE, and SWIFT interfaces and restructured related account information
+
+## [1.26.12] - 2025-10-03
+
+### Changed
+
+- Version bump for latest changes
+
+## [1.26.11] - 2025-10-03
+
+### Changed
+
+- Version bump for latest changes
+
+## [1.26.10] - 2025-10-03
+
+### Changed
+
+- Updated VirtualAccount types to include VirtualAccountDetailItem and renamed VirtualAccountListItem
+
+## [1.26.9] - 2025-10-03
+
+### Added
+
+- Added VirtualAccountDetailItem type
+
+### Changed
+
+- Formatted type definitions for clarity and added is_enabled field to APIKey interface
+
+## [1.26.8] - 2025-09-19
+
+### Fixed
+
+- Corrected type definition for bank data response and updated request field name for consistency
+
+## [1.26.7] - 2025-09-18
+
+### Changed
+
+- Version bump for latest changes
+
+## [1.26.6] - 2025-09-18
+
+### Changed
+
+- Updated bank data retrieval method to use GET with params for improved clarity and consistency
+
+## [1.26.5] - 2025-09-18
+
+### Fixed
+
+- Changed bank data retrieval method from GET to POST for improved data handling
+
+## [1.26.4] - 2025-09-18
+
+### Added
+
+- Integrated bank data module and defined TypeScript types for bank data retrieval
+
+## [1.26.3] - 2025-09-16
+
+### Added
+
+- Added resume inquiry endpoint and corresponding TypeScript types for enhanced inquiry management
+
+## [1.26.2] - 2025-09-16
+
+### Changed
+
+- Deprecated card_limit in favor of max_cards for improved clarity in card management
+
+## [1.26.1] - 2025-09-11
+
+### Fixed
+
+- Enhanced unauthorized error handling by adding context check to bypass handler
+
+## [1.26.0] - 2025-09-11
+
+### Fixed
+
+- Added context to authentication requests and updated TypeScript configuration to include type definitions
+
+## [1.25.6] - 2025-09-10
+
+### Added
+
+- Added new sign-in and sign-up endpoints
+
+## [1.25.5] - 2025-09-05
+
+### Added
+
+- Added TOTP status endpoint and response type for improved status tracking
+
+## [1.25.4] - 2025-08-22
+
+### Changed
+
+- Updated wallet transaction filter types to use Partial for improved flexibility
+
+## [1.25.3] - 2025-08-22
+
+### Changed
+
+- Streamlined wallet transaction filter types by utilizing shared schema for consistency
+- Enhanced ExportCsv request type to include comprehensive filter options for wallet transactions
+
+## [1.25.2] - 2025-08-20
+
+### Fixed
+
+- Updated channel initialization to use key prop if provided in subscription hooks
+
+## [1.25.1] - 2025-08-20
+
+### Changed
+
+- Simplified useWalletTransactionsSubscription and enhanced useSupabaseSubscription with key prop
 
 ## [1.25.0] - 2025-08-19
 

package/FIXED_RLS_ERROR.md

@@ -0,0 +1,146 @@
+# ✅ Fixed: RLS Policy Error
+
+## ❌ Problem
+```
+new row violates row-level security policy
+```
+
+## ✅ Solution
+All functions now accept `authToken` parameter!
+
+## 🚀 Quick Fix
+
+### Before (Error):
+```typescript
+const result = await uploadFile({
+  file: myFile,
+  fileName: 'test.pdf',
+  userId: 'user-123',
+});
+// ❌ Error: RLS policy violation
+```
+
+### After (Works):
+```typescript
+const authToken = 'your-jwt-token'; // From Supabase Auth
+
+const result = await uploadFile({
+  file: myFile,
+  fileName: 'test.pdf',
+  userId: 'user-123',
+  authToken, // ← Add this!
+});
+// ✅ Success!
+```
+
+## 📱 React Hook Usage
+
+```typescript
+import { useFileUpload } from 'squarefi-bff-api-module';
+
+function MyComponent() {
+  const authToken = 'your-jwt-token'; // Get from your auth
+  
+  const { upload } = useFileUpload({
+    userId: 'user-123',
+    authToken, // ← Add this!
+  });
+  
+  return <input type="file" onChange={(e) => upload(e.target.files[0])} />;
+}
+```
+
+## 🔑 How to Get Auth Token
+
+### Option 1: From Supabase
+
+```typescript
+import { supabaseClient } from 'squarefi-bff-api-module';
+
+const { data: { session } } = await supabaseClient.auth.getSession();
+const authToken = session?.access_token;
+```
+
+### Option 2: From Browser (for testing)
+
+1. Login to your app
+2. Open Console (F12)
+3. Run:
+```javascript
+const session = await supabaseClient.auth.getSession();
+console.log(session.data.session.access_token);
+```
+4. Copy the token
+
+### Option 3: From Your Auth System
+
+```typescript
+// From localStorage
+const authToken = localStorage.getItem('access_token');
+
+// From auth context
+const { accessToken } = useAuth();
+```
+
+## 📝 Updated API
+
+All these functions now accept `authToken`:
+
+| Function | Signature |
+|----------|-----------|
+| `uploadFile` | `uploadFile({..., authToken})` |
+| `getSignedUrl` | `getSignedUrl({..., authToken})` |
+| `deleteFile` | `deleteFile(path, bucket, authToken)` |
+| `deleteFiles` | `deleteFiles(paths, bucket, authToken)` |
+| `listUserFiles` | `listUserFiles(userId, bucket, authToken)` |
+| `downloadFile` | `downloadFile(path, bucket, authToken)` |
+
+## 🧪 Test Example
+
+```typescript
+// 1. Get auth token
+const authToken = 'eyJhbGci...'; // Your JWT token
+
+// 2. Upload with token
+const result = await uploadFile({
+  file: myFile,
+  fileName: 'test.pdf',
+  userId: 'user-123',
+  authToken,
+});
+
+console.log(result.success); // true
+console.log(result.path); // user-123/test.pdf
+```
+
+## 🔒 Why This Works
+
+RLS policies check `auth.uid()` from JWT token:
+
+```sql
+-- Policy requires authenticated user
+WITH CHECK (
+  (storage.foldername(name))[1] = auth.uid()::text
+)
+```
+
+- ❌ **Without token**: `auth.uid()` = NULL → Policy fails
+- ✅ **With token**: `auth.uid()` = user ID → Policy passes
+
+## 📚 Full Documentation
+
+- **AUTH_TOKEN_USAGE.md** - Complete guide with examples
+- **FRONTEND_STORAGE_GUIDE.md** - React usage
+- **STORAGE_MODULE.md** - Full API reference
+
+## ✅ Changes Summary
+
+- ✅ Added `authToken` parameter to all storage functions
+- ✅ Updated hooks (`useFileUpload`, `useUserFiles`)
+- ✅ Backward compatible (token is optional)
+- ✅ Creates authenticated client when token provided
+- ✅ Project builds successfully
+
+Now you can upload files from authenticated users! 🎉
+
+

package/QUICK_TEST.md

@@ -0,0 +1,127 @@
+# Quick Test Guide ⚡
+
+## ✅ Исправлено!
+
+HTML тест был исправлен. Основные проблемы:
+- Неправильная инициализация Supabase клиента
+- Незакрытый тег script
+- Неправильные ссылки на клиент
+
+## 🧪 Как протестировать СЕЙЧАС
+
+### 1. Откройте test-storage.html в браузере
+
+Просто двойной клик на файл или:
+```bash
+open test-storage.html  # macOS
+```
+
+### 2. Что вы должны увидеть
+
+✅ **Зеленый статус** вверху: "✅ Connected to Supabase"
+
+❌ Если видите **красный статус** - проверьте консоль браузера (F12)
+
+### 3. Нажмите "Test Connection"
+
+Должно показать:
+```
+✅ Connection successful!
+
+Available buckets:
+[...список бакетов...]
+```
+
+### 4. Попробуйте загрузить файл
+
+❌ **Если получите ошибку** типа:
+- "Bucket not found" → Нужно создать бакет (см. ниже)
+- "Permission denied" → Нужно настроить RLS (см. ниже)
+
+## ⚠️ Перед загрузкой файлов
+
+Нужно выполнить SQL скрипт в Supabase:
+
+1. Откройте: https://dpwavvgrlklpuoddutdp.supabase.co
+2. Перейдите в **SQL Editor**
+3. Скопируйте весь файл `scripts/supabase-storage-setup.sql`
+4. Вставьте и нажмите **RUN**
+
+Это создаст:
+- ✅ Бакеты: user-files, documents, images
+- ✅ RLS политики для безопасности
+- ✅ Функцию is_super_admin()
+
+## 🔍 Ожидаемые результаты
+
+### ✅ Если SQL выполнен:
+- "Test Connection" → Показывает 3 бакета
+- "Upload File" → Файл загружается успешно
+- "List Files" → Показывает загруженные файлы
+- "Get Signed URL" → Генерирует рабочую ссылку
+
+### ❌ Если SQL НЕ выполнен:
+- "Test Connection" → Может показать пустой список бакетов
+- "Upload File" → Ошибка "Bucket not found"
+- "List Files" → Ошибка
+
+## 🚀 Node.js тест (альтернатива)
+
+```bash
+node test-storage.js
+```
+
+Покажет:
+```
+🔍 Testing Supabase Storage Module...
+
+1. Testing Supabase client initialization...
+   ✅ Supabase client initialized successfully
+   
+2. Testing getPublicUrl function...
+   ✅ getPublicUrl works
+   
+✨ Basic tests completed!
+```
+
+## 🐛 Troubleshooting
+
+### Консоль показывает "supabase is not defined"
+- Проблема с CDN загрузкой
+- Попробуйте обновить страницу (F5)
+- Проверьте интернет-соединение
+
+### "Failed to fetch"
+- Проверьте URL и ключ в test-storage.html
+- Убедитесь, что Supabase проект активен
+
+### "Bucket not found"  
+- Выполните SQL скрипт
+- Проверьте название бакета (должно быть 'user-files')
+
+### Files не загружаются
+- SQL скрипт не выполнен
+- RLS политики не настроены
+- Неправильный формат user ID
+
+## 📊 Что дальше?
+
+После успешного теста:
+
+1. ✅ Используйте модуль в React:
+```tsx
+import { useFileUpload } from 'squarefi-bff-api-module';
+```
+
+2. ✅ Прочитайте документацию:
+- `docs/FRONTEND_STORAGE_GUIDE.md` - Для React
+- `docs/STORAGE_MODULE.md` - Полное API
+- `docs/STORAGE_QUICK_START.md` - Быстрый старт
+
+3. ✅ Настройте `is_super_admin()` под вашу схему пользователей
+
+## ✨ Готово!
+
+Модуль протестирован и готов к использованию!
+
+

package/README.md

@@ -10,6 +10,7 @@ A fully-typed TypeScript / JavaScript SDK for effortless interaction with the Sq
 • Strict TypeScript types generated from the OpenAPI contract.  
 • Axios-powered HTTP client with automatic tenant & environment headers.  
 • First-class support for **Telegram Mini-Apps** as well as Web.  
+• **Supabase Storage integration** with automatic user-level security policies.  
 • Batteries included: constants, helpers & cryptography utilities.  
 • Zero-config – just provide your API URLs and tenant id.
 
@@ -69,18 +70,22 @@ const { isConnected } = useSupabaseSubscription({
 
 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…`              |
-| `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…`       |
+| 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 encrypted sensitive data requests (e.g., card secret keys) | ✅                                        | `MIIBIjANBgkqh…`              |
+| `SUPABASE_URL`             | Supabase project URL for real-time subscriptions and file storage                            | ⚠️ _If you use Supabase hooks or Storage_ | `https://xyz.supabase.co`     |
+| `SUPABASE_PUBLIC_KEY`      | Supabase public anon key for client authentication                                           | ⚠️ _If you use Supabase hooks or Storage_ | `eyJhbGciOiJIUzI1NiIs…`       |
+
+> ⚠️ **Backend Only**: `SUPABASE_SERVICE_ROLE_KEY` is used for backend file access (see [Backend Service URL Guide](./docs/BACKEND_SERVICE_URL.md)). **Never expose this key on frontend/client-side code.**
 
 > ℹ️ When running in Node.js you can place these variables in a `.env` file and load them with [dotenv](https://npmjs.com/package/dotenv).
+>
+> 📝 See `env.example` file in the repository root for a complete template with all available environment variables.
 
 ---
 
@@ -122,6 +127,78 @@ function MyComponent() {
 
 ---
 
+## 📦 Supabase Storage Module
+
+The SDK includes a complete file storage solution powered by Supabase Storage with automatic user-level security policies. Files are automatically organized by user ID and protected with Row Level Security (RLS).
+
+### Quick Start
+
+```ts
+import { uploadFile, getSignedUrl, DEFAULT_BUCKET } from 'squarefi-bff-api-module';
+
+// Upload a file
+const result = await uploadFile({
+  file: myFile, // File or Blob
+  fileName: 'document.pdf',
+  userId: 'user-uuid',
+  bucket: DEFAULT_BUCKET,
+});
+
+if (result.success) {
+  console.log('File uploaded:', result.path);
+  console.log('Signed URL:', result.signedUrl); // Use this for secure access
+}
+
+// Get a signed URL for accessing the file
+const signedUrl = await getSignedUrl({
+  path: result.path,
+  expiresIn: 3600, // 1 hour
+});
+```
+
+### Features
+
+- ✅ Automatic file organization by user ID (`{userId}/{fileName}`)
+- ✅ Row Level Security (RLS) - users can only access their own files
+- ✅ Superadmin access to all files (configurable)
+- ✅ Multiple storage buckets: `user-files`, `documents`, `images`
+- ✅ Signed URLs for temporary secure access
+- ✅ Service URLs for permanent backend access (with service role key)
+- ✅ File listing, deletion, and download support
+
+### URL Types
+
+| Type           | Expires                 | Use Case                    | Authentication                 |
+| -------------- | ----------------------- | --------------------------- | ------------------------------ |
+| **Signed URL** | ✅ Yes (1 hour default) | End users, temporary access | ❌ Not required                |
+| **Public URL** | ❌ Never                | Backend/Superadmin access   | ✅ Required (service role key) |
+
+```typescript
+// For end users (temporary, no auth needed)
+const signedUrl = await getSignedUrl({ path, expiresIn: 3600 });
+
+// For superadmin backend (permanent, requires service key)
+const publicUrl = getPublicUrl(path);
+// On backend: fetch(publicUrl, { headers: { 'Authorization': 'Bearer SERVICE_KEY' } })
+```
+
+### Setup
+
+1. Set required environment variables (see table above)
+2. Run the SQL setup script in your Supabase project:
+   ```bash
+   # Execute scripts/supabase-storage-setup.sql in Supabase SQL Editor
+   ```
+3. Customize the `is_super_admin()` function according to your user schema
+
+📖 **Documentation**:
+
+- **Frontend Guide** (React): [docs/FRONTEND_STORAGE_GUIDE.md](./docs/FRONTEND_STORAGE_GUIDE.md) - Quick start with ready-to-use components
+- **Full Documentation**: [docs/STORAGE_MODULE.md](./docs/STORAGE_MODULE.md) - Detailed API description
+- **Quick Start**: [docs/STORAGE_QUICK_START.md](./docs/STORAGE_QUICK_START.md) - Get started in 5 minutes
+
+---
+
 ## 🗺️ 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).