squarefi-bff-api-module 1.32.1 → 1.32.2

package/docs/AUTH_TOKEN_USAGE.md

@@ -1,290 +0,0 @@
-# Using Storage Module with Authentication
-
-## Problem
-When you see error: **"new row violates row-level security policy"**
-
-This means:
-- ✅ RLS policies are working (good!)
-- ❌ User is not authenticated
-
-## Solution: Pass authToken
-
-All storage functions now accept an optional `authToken` parameter.
-
-## How to Get Auth Token
-
-### From Supabase Auth
-
-```typescript
-import { supabaseClient } from 'squarefi-bff-api-module';
-
-// After user login
-const { data: { session } } = await supabaseClient.auth.getSession();
-const authToken = session?.access_token;
-```
-
-### From Your Own Auth System
-
-```typescript
-// From JWT token in localStorage/cookies
-const authToken = localStorage.getItem('access_token');
-
-// Or from your auth context
-const { accessToken } = useAuth();
-```
-
-## Usage Examples
-
-### Direct API Usage
-
-```typescript
-import { uploadFile } from 'squarefi-bff-api-module';
-
-const authToken = 'your-jwt-token-here';
-
-const result = await uploadFile({
-  file: myFile,
-  fileName: 'document.pdf',
-  userId: 'user-123',
-  authToken, // ← Передаем токен здесь!
-});
-
-if (result.success) {
-  console.log('Uploaded:', result.path);
-}
-```
-
-### With React Hooks
-
-```typescript
-import { useFileUpload, useUserFiles } from 'squarefi-bff-api-module';
-
-function MyComponent() {
-  // Get token from your auth
-  const { accessToken } = useAuth(); // your auth hook
-  
-  const { upload, uploading } = useFileUpload({
-    userId: 'user-123',
-    authToken: accessToken, // ← Передаем токен здесь!
-  });
-  
-  const { files } = useUserFiles({
-    userId: 'user-123',
-    authToken: accessToken, // ← И здесь!
-    autoLoad: true,
-  });
-  
-  return (
-    <div>
-      <input type="file" onChange={(e) => upload(e.target.files[0])} />
-      {files.map(f => <div key={f.id}>{f.name}</div>)}
-    </div>
-  );
-}
-```
-
-### Complete Example with Supabase Auth
-
-```typescript
-import React, { useEffect, useState } from 'react';
-import { supabaseClient, useFileUpload } from 'squarefi-bff-api-module';
-
-function AuthenticatedFileUpload() {
-  const [authToken, setAuthToken] = useState<string | null>(null);
-  const [userId, setUserId] = useState<string | null>(null);
-  
-  useEffect(() => {
-    // Get current session
-    supabaseClient?.auth.getSession().then(({ data: { session } }) => {
-      setAuthToken(session?.access_token || null);
-      setUserId(session?.user?.id || null);
-    });
-    
-    // Listen for auth changes
-    const { data: authListener } = supabaseClient?.auth.onAuthStateChange(
-      (_event, session) => {
-        setAuthToken(session?.access_token || null);
-        setUserId(session?.user?.id || null);
-      }
-    ) || {};
-    
-    return () => {
-      authListener?.subscription.unsubscribe();
-    };
-  }, []);
-  
-  const { upload, uploading, error } = useFileUpload({
-    userId: userId || '',
-    authToken: authToken || undefined,
-    onSuccess: (result) => {
-      console.log('File uploaded:', result.path);
-    },
-  });
-  
-  if (!authToken) {
-    return <div>Please log in first</div>;
-  }
-  
-  return (
-    <div>
-      <input 
-        type="file" 
-        onChange={(e) => upload(e.target.files?.[0])} 
-        disabled={uploading}
-      />
-      {error && <p style={{color: 'red'}}>{error}</p>}
-    </div>
-  );
-}
-```
-
-## All Functions Support authToken
-
-### Upload
-
-```typescript
-uploadFile({ file, fileName, userId, authToken });
-```
-
-### Get Signed URL
-
-```typescript
-getSignedUrl({ path, expiresIn, authToken });
-```
-
-### List Files
-
-```typescript
-listUserFiles(userId, bucket, authToken);
-```
-
-### Delete File
-
-```typescript
-deleteFile(filePath, bucket, authToken);
-```
-
-### Delete Multiple Files
-
-```typescript
-deleteFiles(filePaths, bucket, authToken);
-```
-
-### Download File
-
-```typescript
-downloadFile(filePath, bucket, authToken);
-```
-
-## Testing in Browser
-
-Update `test-storage.html`:
-
-```javascript
-// Add auth token input
-<input type="text" id="authToken" placeholder="Auth Token (JWT)" style="margin: 10px 0;">
-
-// In upload function:
-const authToken = document.getElementById('authToken').value;
-
-const { data, error } = await supabaseClient.storage
-  .from(DEFAULT_BUCKET)
-  .upload(filePath, file);
-
-// Or create authenticated client:
-if (authToken) {
-  const { createClient } = window.supabase;
-  const authenticatedClient = createClient(SUPABASE_URL, SUPABASE_PUBLIC_KEY, {
-    global: {
-      headers: {
-        Authorization: `Bearer ${authToken}`
-      }
-    }
-  });
-  
-  // Use authenticatedClient for upload
-}
-```
-
-## How to Get Test Token
-
-### Option 1: From Browser Console
-
-```javascript
-// After logging in to your app
-const session = await supabaseClient.auth.getSession();
-console.log('Token:', session.data.session.access_token);
-// Copy this token and use it in test
-```
-
-### Option 2: Create Test User
-
-```sql
--- In Supabase SQL Editor
--- Get user ID after signup
-SELECT id FROM auth.users WHERE email = 'test@example.com';
-```
-
-Then login via API and get token.
-
-## RLS Policies Explanation
-
-The policies check `auth.uid()` which comes from the JWT token:
-
-```sql
--- User can upload to their own folder
-CREATE POLICY "Users can upload" ON storage.objects
-FOR INSERT TO authenticated
-WITH CHECK (
-  bucket_id = 'user-files' 
-  AND (storage.foldername(name))[1] = auth.uid()::text
-);
-```
-
-Without `authToken`, `auth.uid()` is NULL → policy fails.
-
-With `authToken`, `auth.uid()` returns user ID from token → policy passes if user ID matches folder.
-
-## Common Issues
-
-### Still getting RLS error?
-
-1. ✅ Check token is valid (not expired)
-2. ✅ Check userId matches token's user ID
-3. ✅ Check file path starts with correct userId: `{userId}/filename`
-4. ✅ Verify SQL policies are correctly set up
-
-### Token expired?
-
-```typescript
-// Refresh token
-const { data, error } = await supabaseClient.auth.refreshSession();
-if (data.session) {
-  const newToken = data.session.access_token;
-  // Use new token
-}
-```
-
-### Wrong user ID?
-
-```typescript
-// Get user ID from token
-const { data: { user } } = await supabaseClient.auth.getUser();
-console.log('User ID:', user?.id);
-// Use this ID for file paths
-```
-
-## Summary
-
-✅ **Always pass `authToken` when using private buckets**
-✅ **Token must match the user ID in file path**
-✅ **Get token from Supabase Auth or your auth system**
-✅ **All functions support optional `authToken` parameter**
-
-## Related Files
-
-- `src/utils/fileStorage.ts` - Core functions with authToken support
-- `src/hooks/useFileUpload.ts` - React hook with authToken
-- `src/hooks/useUserFiles.ts` - React hook with authToken
-
-

package/docs/BACKEND_SERVICE_URL.md

@@ -1,334 +0,0 @@
-# Backend Public URL Usage
-
-Guide for superadmin backend access to user files using permanent public URLs with service role key.
-
-## Overview
-
-For backend applications that need permanent access to files (e.g., admin dashboards, automated processing), use **Public URLs** from `getPublicUrl()` with Supabase service role key.
-
-## Quick Example
-
-```typescript
-import { getPublicUrl, DEFAULT_BUCKET } from 'squarefi-bff-api-module';
-
-// 1. Get permanent URL (can be done on frontend or backend)
-const filePath = 'user-123/document.pdf';
-const publicUrl = getPublicUrl(filePath, DEFAULT_BUCKET);
-
-console.log(publicUrl);
-// Output: https://xxx.supabase.co/storage/v1/object/public/user-files/user-123/document.pdf
-
-// 2. Access file on backend with service role key
-const response = await fetch(publicUrl, {
-  headers: {
-    'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-  }
-});
-
-if (response.ok) {
-  const fileBlob = await response.blob();
-  // Process file...
-}
-```
-
-## Key Differences
-
-### Signed URL vs Public URL
-
-```typescript
-// Signed URL - expires after 1 hour, no auth required
-const signedUrl = await getSignedUrl({ 
-  path: 'user-123/file.pdf',
-  expiresIn: 3600 
-});
-// Use case: temporary link for end user
-
-// Public URL - permanent, requires service role key
-const publicUrl = getPublicUrl('user-123/file.pdf');
-// Use case: backend processing, admin access
-// Must use: fetch(publicUrl, { headers: { Authorization: Bearer SERVICE_KEY } })
-```
-
-## Security Requirements
-
-### ⚠️ Critical: Service Role Key
-
-- **NEVER expose** `SUPABASE_SERVICE_ROLE_KEY` on frontend
-- Store in secure environment variables
-- Use only on backend/server
-- This key **bypasses all RLS policies**
-
-### Environment Setup
-
-```bash
-# Copy env.example to .env and fill in your values
-# See env.example in repository root for all available variables
-
-# Backend only - NEVER commit to git
-SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-## Usage Examples
-
-### Node.js/Express Backend
-
-```javascript
-import express from 'express';
-import { getPublicUrl, DEFAULT_BUCKET } from 'squarefi-bff-api-module';
-
-const app = express();
-
-// Admin endpoint to access any user file
-app.get('/admin/files/:userId/:fileName', async (req, res) => {
-  const { userId, fileName } = req.params;
-  const filePath = `${userId}/${fileName}`;
-  
-  // Get permanent URL
-  const publicUrl = getPublicUrl(filePath, DEFAULT_BUCKET);
-  
-  // Fetch with service key
-  const response = await fetch(publicUrl, {
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-    }
-  });
-  
-  if (!response.ok) {
-    return res.status(404).json({ error: 'File not found' });
-  }
-  
-  // Stream file to client
-  const buffer = await response.arrayBuffer();
-  res.setHeader('Content-Type', response.headers.get('content-type'));
-  res.send(Buffer.from(buffer));
-});
-```
-
-### Next.js API Route
-
-```typescript
-// pages/api/admin/file/[userId]/[fileName].ts
-import { NextApiRequest, NextApiResponse } from 'next';
-import { getPublicUrl, DEFAULT_BUCKET } from 'squarefi-bff-api-module';
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  const { userId, fileName } = req.query;
-  const filePath = `${userId}/${fileName}`;
-  
-  const publicUrl = getPublicUrl(filePath, DEFAULT_BUCKET);
-  
-  const response = await fetch(publicUrl, {
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-    }
-  });
-  
-  if (!response.ok) {
-    return res.status(404).json({ error: 'File not found' });
-  }
-  
-  const buffer = await response.arrayBuffer();
-  res.setHeader('Content-Type', response.headers.get('content-type') || 'application/octet-stream');
-  res.send(Buffer.from(buffer));
-}
-```
-
-### Background Job/Worker
-
-```typescript
-import { getPublicUrl, DOCUMENTS_BUCKET } from 'squarefi-bff-api-module';
-
-async function processUserDocument(userId: string, fileName: string) {
-  const filePath = `${userId}/${fileName}`;
-  const publicUrl = getPublicUrl(filePath, DOCUMENTS_BUCKET);
-  
-  // Download file
-  const response = await fetch(publicUrl, {
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-    }
-  });
-  
-  if (!response.ok) {
-    throw new Error(`Failed to download file: ${response.statusText}`);
-  }
-  
-  const fileContent = await response.text();
-  
-  // Process file...
-  console.log('Processing document for user:', userId);
-  
-  // Your processing logic here
-}
-
-// Run in worker/cron job
-await processUserDocument('user-123', 'invoice.pdf');
-```
-
-### Admin Dashboard
-
-```typescript
-// Frontend gets the URL, backend fetches the file
-import { getPublicUrl, DEFAULT_BUCKET } from 'squarefi-bff-api-module';
-
-// Frontend component
-function AdminFileViewer({ userId, fileName }) {
-  const [fileUrl, setFileUrl] = useState(null);
-  
-  useEffect(() => {
-    // Get the URL (can be done on frontend)
-    const publicUrl = getPublicUrl(`${userId}/${fileName}`, DEFAULT_BUCKET);
-    
-    // Call your backend to proxy the request
-    fetch('/api/admin/proxy-file', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ publicUrl })
-    })
-    .then(res => res.blob())
-    .then(blob => {
-      const url = URL.createObjectURL(blob);
-      setFileUrl(url);
-    });
-  }, [userId, fileName]);
-  
-  return fileUrl ? <img src={fileUrl} alt="File" /> : <p>Loading...</p>;
-}
-
-// Backend proxy endpoint (keeps service key secure)
-app.post('/api/admin/proxy-file', async (req, res) => {
-  const { publicUrl } = req.body;
-  
-  const response = await fetch(publicUrl, {
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-    }
-  });
-  
-  const buffer = await response.arrayBuffer();
-  res.setHeader('Content-Type', response.headers.get('content-type'));
-  res.send(Buffer.from(buffer));
-});
-```
-
-## Best Practices
-
-### ✅ DO
-
-- Store service role key in secure environment variables
-- Access public URLs with service key only on backend
-- Validate user permissions before accessing files
-- Log all admin file access for audit trail
-- Use proper error handling
-
-### ❌ DON'T
-
-- Never expose service role key on frontend
-- Don't commit service key to version control
-- Don't use service key on client-side (URL itself is fine, but don't add auth header)
-- Don't skip audit logging
-- Don't share service key across environments (use different keys for dev/prod)
-
-## Error Handling
-
-```typescript
-async function downloadFileWithServiceKey(publicUrl: string) {
-  try {
-    const response = await fetch(publicUrl, {
-      headers: {
-        'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-      }
-    });
-    
-    if (!response.ok) {
-      if (response.status === 404) {
-        throw new Error('File not found');
-      }
-      if (response.status === 401) {
-        throw new Error('Invalid service key');
-      }
-      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-    }
-    
-    return await response.blob();
-  } catch (error) {
-    console.error('Failed to download file:', error);
-    throw error;
-  }
-}
-```
-
-## Audit Logging Example
-
-```typescript
-import { getPublicUrl } from 'squarefi-bff-api-module';
-
-async function auditedFileAccess(
-  adminUserId: string,
-  targetUserId: string,
-  fileName: string
-) {
-  // Log access
-  await logAudit({
-    action: 'FILE_ACCESS',
-    adminId: adminUserId,
-    targetUserId,
-    fileName,
-    timestamp: new Date(),
-    ip: req.ip
-  });
-  
-  // Get and access file
-  const publicUrl = getPublicUrl(`${targetUserId}/${fileName}`);
-  
-  const response = await fetch(publicUrl, {
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}`
-    }
-  });
-  
-  return response;
-}
-```
-
-## Troubleshooting
-
-### File Not Found (404)
-
-```typescript
-// Check if file path is correct
-const correctPath = `${userId}/${fileName}`;  // ✅
-const wrongPath = `${fileName}`;              // ❌
-```
-
-### Unauthorized (401)
-
-- Verify `SUPABASE_SERVICE_ROLE_KEY` is set correctly
-- Check if key is valid in Supabase Dashboard → Settings → API
-
-### CORS Issues
-
-If accessing from browser (not recommended but possible):
-
-```typescript
-// In Supabase Dashboard → Storage → Policies
-// Make sure CORS is configured if needed
-```
-
-## Summary
-
-| Aspect | Details |
-|--------|---------|
-| **Function** | `getPublicUrl(path, bucket)` |
-| **Returns** | Permanent URL string |
-| **Authentication** | Required: `Authorization: Bearer SERVICE_ROLE_KEY` (for private buckets) |
-| **Expiration** | Never expires |
-| **Use Case** | Backend/admin access to private buckets |
-| **Security** | ⚠️ NEVER expose service key on frontend |
-
-## Related Documentation
-
-- [Full Storage Module Docs](./STORAGE_MODULE.md)
-- [Frontend Guide](./FRONTEND_STORAGE_GUIDE.md)
-- [Quick Start](./STORAGE_QUICK_START.md)
-