@redseat/api 0.0.11 → 0.0.12

package/client.md

@@ -1,288 +1,318 @@
-# RedseatClient
-
-The `RedseatClient` class is the low-level HTTP client that handles all communication with Redseat servers. It provides automatic token management, local server detection, and request/response interceptors.
-
-## Overview
-
-`RedseatClient` wraps Axios and adds:
-- Automatic token refresh before expiration
-- Local server detection (for development)
-- 401 error handling with automatic retry
-- Request/response interceptors for authentication
-
-## Constructor
-
-```typescript
-new RedseatClient(options: ClientOptions)
-```
-
-### ClientOptions Interface
-
-```typescript
-interface ClientOptions {
-    server: IServer;
-    getIdToken: () => Promise<string>;
-    refreshThreshold?: number; // milliseconds before expiration to refresh (default: 5 minutes)
-}
-```
-
-**Parameters:**
-- `server`: Server configuration object with `id`, `url`, and optional `port`
-- `getIdToken`: Async function that returns the current ID token from your auth provider
-- `refreshThreshold`: Optional. Milliseconds before token expiration to trigger refresh (default: 300000 = 5 minutes)
-
-**Example:**
-```typescript
-const client = new RedseatClient({
-    server: {
-        id: 'server-123',
-        url: 'example.com',
-        port: 443
-    },
-    getIdToken: async () => {
-        // Get ID token from your auth provider (Firebase, Auth0, etc.)
-        return await getCurrentUserToken();
-    },
-    refreshThreshold: 5 * 60 * 1000 // 5 minutes
-});
-```
-
-## Features
-
-### Automatic Token Refresh
-
-The client automatically refreshes tokens before they expire. The refresh happens:
-- Before each request if the token is expired or expiring soon
-- When a 401 error is received (with automatic retry)
-
-### Local Server Detection
-
-The client automatically detects if a local development server is available by checking `local.{server.url}`. If detected, it uses the local URL instead of the production URL.
-
-### Request Interceptor
-
-All requests are intercepted to:
-1. Check if token needs refresh
-2. Add `Authorization: Bearer {token}` header
-
-### Response Interceptor
-
-All responses are intercepted to:
-1. Handle 401 errors by refreshing token and retrying the request
-2. Prevent infinite retry loops with `_retry` flag
-
-## Methods
-
-### `get<T>(url: string, config?: AxiosRequestConfig)`
-
-Performs a GET request.
-
-**Parameters:**
-- `url`: The endpoint URL (relative to base URL)
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.get<IFile[]>('/libraries/123/medias');
-const medias = response.data;
-```
-
-### `post<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a POST request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.post<ITag>('/libraries/123/tags', {
-    name: 'Vacation'
-});
-const tag = response.data;
-```
-
-### `put<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a PUT request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const formData = new FormData();
-formData.append('file', fileBlob);
-const response = await client.put('/libraries/123/medias/transfert', formData);
-```
-
-### `patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a PATCH request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.patch<ITag>('/libraries/123/tags/tag-id', {
-    rename: 'New Tag Name'
-});
-const updatedTag = response.data;
-```
-
-### `delete<T>(url: string, config?: AxiosRequestConfig)`
-
-Performs a DELETE request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `config`: Optional Axios request configuration (can include `data` for request body)
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-// Simple delete
-await client.delete('/libraries/123/tags/tag-id');
-
-// Delete with body
-await client.delete('/libraries/123/medias', {
-    data: { ids: ['media-1', 'media-2'] }
-});
-```
-
-### `request<T>(method: Method, url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a custom HTTP request.
-
-**Parameters:**
-- `method`: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', etc.)
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.request<IFile>(
-    'GET',
-    '/libraries/123/medias/media-id',
-    undefined,
-    { responseType: 'blob' }
-);
-```
-
-### `setToken(token: string | IToken)`
-
-Manually set the authentication token. Useful when you already have a valid token.
-
-**Parameters:**
-- `token`: Either a token string or an `IToken` object with `token` and `expires` properties
-
-**Example:**
-```typescript
-// Set as string (will be treated as expiring soon)
-client.setToken('your-token-string');
-
-// Set as IToken object with expiration
-client.setToken({
-    token: 'your-token-string',
-    expires: Date.now() + 3600000 // 1 hour from now
-});
-```
-
-## Error Handling
-
-The client automatically handles:
-- **401 Unauthorized**: Refreshes token and retries the request once
-- **Token expiration**: Refreshes token before making requests
-- **Network errors**: Passes through to caller
-
-**Example error handling:**
-```typescript
-try {
-    const response = await client.get('/libraries/123/medias');
-} catch (error) {
-    if (error.response?.status === 401) {
-        // Token refresh failed or invalid credentials
-        console.error('Authentication failed');
-    } else if (error.response?.status === 404) {
-        // Resource not found
-        console.error('Resource not found');
-    } else {
-        // Other error
-        console.error('Request failed:', error.message);
-    }
-}
-```
-
-## Usage with Response Types
-
-The client supports specifying response types for binary data:
-
-```typescript
-// Get as stream
-const stream = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'stream'
-});
-
-// Get as ArrayBuffer
-const buffer = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'arraybuffer'
-});
-
-// Get as Blob
-const blob = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'blob'
-});
-```
-
-## Progress Tracking
-
-For file uploads, you can track progress:
-
-```typescript
-const formData = new FormData();
-formData.append('file', fileBlob);
-
-await client.post('/libraries/123/medias', formData, {
-    onUploadProgress: (progressEvent) => {
-        if (progressEvent.total) {
-            const percent = (progressEvent.loaded / progressEvent.total) * 100;
-            console.log(`Upload progress: ${percent}%`);
-        }
-    }
-});
-```
-
-## Internal Methods (Private)
-
-The following methods are used internally and should not be called directly:
-- `refreshToken()` - Refreshes the authentication token
-- `ensureValidToken()` - Ensures token is valid before requests
-- `isTokenExpiredOrExpiringSoon()` - Checks if token needs refresh
-- `detectLocalUrl()` - Detects local development server
-- `getRegularServerUrl()` - Gets production server URL
-
-## See Also
-
-- [ServerApi Documentation](server.md) - Uses RedseatClient for server operations
-- [LibraryApi Documentation](libraries.md) - Uses RedseatClient for library operations
-- [README](README.md) - Package overview
-
+# RedseatClient
+
+The `RedseatClient` class is the low-level HTTP client that handles all communication with Redseat servers. It provides automatic token management, local server detection, and request/response interceptors.
+
+## Overview
+
+`RedseatClient` wraps Axios and adds:
+- Automatic token refresh before expiration
+- Local server detection (for development)
+- 401 error handling with automatic retry
+- Request/response interceptors for authentication
+
+## Constructor
+
+```typescript
+new RedseatClient(options: ClientOptions)
+```
+
+### ClientOptions Interface
+
+```typescript
+interface ClientOptions {
+    server: IServer;
+    getIdToken: () => Promise<string>;
+    refreshThreshold?: number; // milliseconds before expiration to refresh (default: 5 minutes)
+}
+```
+
+**Parameters:**
+- `server`: Server configuration object with `id`, `url`, and optional `port`
+- `getIdToken`: Async function that returns the current ID token from your auth provider
+- `refreshThreshold`: Optional. Milliseconds before token expiration to trigger refresh (default: 300000 = 5 minutes)
+
+**Example:**
+```typescript
+const client = new RedseatClient({
+    server: {
+        id: 'server-123',
+        url: 'example.com',
+        port: 443
+    },
+    getIdToken: async () => {
+        // Get ID token from your auth provider (Firebase, Auth0, etc.)
+        return await getCurrentUserToken();
+    },
+    refreshThreshold: 5 * 60 * 1000 // 5 minutes
+});
+```
+
+## Features
+
+### Automatic Token Refresh
+
+The client automatically refreshes tokens before they expire. The refresh happens:
+- Before each request if the token is expired or expiring soon
+- When a 401 error is received (with automatic retry)
+
+### Local Server Detection
+
+The client automatically detects if a local development server is available by checking `local.{server.url}`. If detected, it uses the local URL instead of the production URL.
+
+### Request Interceptor
+
+All requests are intercepted to:
+1. Check if token needs refresh
+2. Add `Authorization: Bearer {token}` header
+
+### Response Interceptor
+
+All responses are intercepted to:
+1. Handle 401 errors by refreshing token and retrying the request
+2. Prevent infinite retry loops with `_retry` flag
+
+## Methods
+
+### `get<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a GET request.
+
+**Parameters:**
+- `url`: The endpoint URL (relative to base URL)
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.get<IFile[]>('/libraries/123/medias');
+const medias = response.data;
+```
+
+### `post<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a POST request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.post<ITag>('/libraries/123/tags', {
+    name: 'Vacation'
+});
+const tag = response.data;
+```
+
+### `postForm<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a POST request with FormData. This method is specifically designed for multipart/form-data uploads and provides better compatibility with React Native environments compared to using `post` with FormData.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: FormData object or data to send as form data
+- `config`: Optional Axios request configuration (supports `onUploadProgress` for progress tracking)
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const formData = new FormData();
+formData.append('info', JSON.stringify({ name: 'photo.jpg', size: 1024 }));
+formData.append('file', fileBlob, 'photo.jpg');
+
+const response = await client.postForm<IFile>('/libraries/123/medias', formData, {
+    onUploadProgress: (progressEvent) => {
+        if (progressEvent.total) {
+            const percent = (progressEvent.loaded / progressEvent.total) * 100;
+            console.log(`Upload progress: ${percent}%`);
+        }
+    }
+});
+const uploadedFile = response.data;
+```
+
+**Note:** Use `postForm` instead of `post` when sending FormData, especially in React Native applications, as it properly handles multipart/form-data headers and encoding.
+
+### `put<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PUT request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+const response = await client.put('/libraries/123/medias/transfert', formData);
+```
+
+### `patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PATCH request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.patch<ITag>('/libraries/123/tags/tag-id', {
+    rename: 'New Tag Name'
+});
+const updatedTag = response.data;
+```
+
+### `delete<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a DELETE request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `config`: Optional Axios request configuration (can include `data` for request body)
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+// Simple delete
+await client.delete('/libraries/123/tags/tag-id');
+
+// Delete with body
+await client.delete('/libraries/123/medias', {
+    data: { ids: ['media-1', 'media-2'] }
+});
+```
+
+### `request<T>(method: Method, url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a custom HTTP request.
+
+**Parameters:**
+- `method`: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', etc.)
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.request<IFile>(
+    'GET',
+    '/libraries/123/medias/media-id',
+    undefined,
+    { responseType: 'blob' }
+);
+```
+
+### `setToken(token: string | IToken)`
+
+Manually set the authentication token. Useful when you already have a valid token.
+
+**Parameters:**
+- `token`: Either a token string or an `IToken` object with `token` and `expires` properties
+
+**Example:**
+```typescript
+// Set as string (will be treated as expiring soon)
+client.setToken('your-token-string');
+
+// Set as IToken object with expiration
+client.setToken({
+    token: 'your-token-string',
+    expires: Date.now() + 3600000 // 1 hour from now
+});
+```
+
+## Error Handling
+
+The client automatically handles:
+- **401 Unauthorized**: Refreshes token and retries the request once
+- **Token expiration**: Refreshes token before making requests
+- **Network errors**: Passes through to caller
+
+**Example error handling:**
+```typescript
+try {
+    const response = await client.get('/libraries/123/medias');
+} catch (error) {
+    if (error.response?.status === 401) {
+        // Token refresh failed or invalid credentials
+        console.error('Authentication failed');
+    } else if (error.response?.status === 404) {
+        // Resource not found
+        console.error('Resource not found');
+    } else {
+        // Other error
+        console.error('Request failed:', error.message);
+    }
+}
+```
+
+## Usage with Response Types
+
+The client supports specifying response types for binary data:
+
+```typescript
+// Get as stream
+const stream = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'stream'
+});
+
+// Get as ArrayBuffer
+const buffer = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'arraybuffer'
+});
+
+// Get as Blob
+const blob = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'blob'
+});
+```
+
+## Progress Tracking
+
+For file uploads, you can track progress. Use `postForm` for FormData uploads (recommended for React Native compatibility):
+
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+
+await client.postForm('/libraries/123/medias', formData, {
+    onUploadProgress: (progressEvent) => {
+        if (progressEvent.total) {
+            const percent = (progressEvent.loaded / progressEvent.total) * 100;
+            console.log(`Upload progress: ${percent}%`);
+        }
+    }
+});
+```
+
+## Internal Methods (Private)
+
+The following methods are used internally and should not be called directly:
+- `refreshToken()` - Refreshes the authentication token
+- `ensureValidToken()` - Ensures token is valid before requests
+- `isTokenExpiredOrExpiringSoon()` - Checks if token needs refresh
+- `detectLocalUrl()` - Detects local development server
+- `getRegularServerUrl()` - Gets production server URL
+
+## See Also
+
+- [ServerApi Documentation](server.md) - Uses RedseatClient for server operations
+- [LibraryApi Documentation](libraries.md) - Uses RedseatClient for library operations
+- [README](README.md) - Package overview
+

package/dist/client.d.ts

@@ -25,6 +25,7 @@ export declare class RedseatClient {
     setToken(token: string | IToken): void;
     get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;
     post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;
+    postForm<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;
     put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;
     patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;
     delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<import("axios").AxiosResponse<T, any>>;

package/dist/client.js

@@ -137,6 +137,9 @@ export class RedseatClient {
     async post(url, data, config) {
         return this.axios.post(url, data, config);
     }
+    async postForm(url, data, config) {
+        return this.axios.postForm(url, data, config);
+    }
     async put(url, data, config) {
         return this.axios.put(url, data, config);
     }

package/dist/library.d.ts

@@ -60,6 +60,9 @@ export interface LibraryHttpClient {
     post<T = unknown>(url: string, data?: unknown, config?: any): Promise<{
         data: T;
     }>;
+    postForm<T = unknown>(url: string, data?: unknown, config?: any): Promise<{
+        data: T;
+    }>;
     put<T = unknown>(url: string, data?: unknown, config?: any): Promise<{
         data: T;
     }>;

package/dist/library.js

@@ -588,7 +588,7 @@ export class LibraryApi {
                 }
             };
         }
-        const res = await this.client.post(this.getUrl('/medias'), formData, config);
+        const res = await this.client.postForm(this.getUrl('/medias'), formData, config);
         return res.data;
     }
 }