@dimrev4/files-core SDK

TypeScript SDK for Files Core API - Comprehensive client for file storage, bucket management, and metadata operations in fitness applications.

🚀 Features

• 📂 File upload, update, upsert, list, download, and delete
• 🪣 Bucket management (create, list, delete)
• 🔐 JWT authentication via Users Core proxy
• 🌍 Three storage scopes: user-private, group, and public
• 📊 File metadata tracked in PostgreSQL; objects stored in MinIO
• 🔗 Presigned GET/POST URLs for direct MinIO access
• 💪 100% TypeScript with full type safety
• ⚡ Axios-based with interceptors support

📦 Installation

npm install @dimrev4/files-core
# or
yarn add @dimrev4/files-core
# or
pnpm add @dimrev4/files-core

🔑 Authentication Requirements

All API requests require two headers:

| Header | Value | Notes | | --------------- | -------------------- | --------------------------------------------- | | x-api-key | Your API key | Required on all routes (global ApiKeyGuard) | | Authorization | Bearer <jwt-token> | Required on protected routes (AuthGuard) |

Public download/inline endpoints (/download/:id, /inline/:id) skip the JWT check but still require x-api-key.

🔧 Quick Start

1. Setup

import {
  Configuration,
  FilesUserV1Api,
  FilesPublicV1Api,
  FilesGroupV1Api,
  BucketsV1Api,
} from '@dimrev4/files-core';

const config = new Configuration({
  basePath: 'https://api.yourdomain.com',
  apiKey: process.env.FILES_CORE_API_KEY, // sent as x-api-key header
  accessToken: jwtToken, // sent as Authorization: Bearer
});

const userFilesApi = new FilesUserV1Api(config);
const publicFilesApi = new FilesPublicV1Api(config);
const groupFilesApi = new FilesGroupV1Api(config);
const bucketsApi = new BucketsV1Api(config);

2. Upload a file to user's private storage

const file = new File(['content'], 'filename.txt', { type: 'text/plain' });

const uploadResponse = await userFilesApi.filesUserV1ControllerUpload(
  dto,
  file,
);
console.log('File uploaded:', uploadResponse.data.id);

3. Upload a file to public storage

const publicUploadResponse = await publicFilesApi.filesPublicV1ControllerUpload(
  dto,
  file,
);
console.log('Public file id:', publicUploadResponse.data.id);

4. Upload a file to a group bucket

const groupUploadResponse = await groupFilesApi.filesGroupV1ControllerUpload(
  'group-id',
  dto,
  file,
);
console.log('Group file id:', groupUploadResponse.data.id);

5. Bucket management (system-only)

// Create a new bucket
const bucket = await bucketsApi.bucketsV1ControllerCreate({
  name: 'new-bucket',
});

// List all buckets
const buckets = await bucketsApi.bucketsV1ControllerFindAll();
console.log('Buckets:', buckets.data);

// Delete a bucket
await bucketsApi.bucketsV1ControllerDelete('bucket-name');

🏗️ API Overview

Get Me (AuthV1Api)

• POST /api/v1/get-me - Validate JWT via Users Core and return current user

User Files (FilesUserV1Api) — /api/user/v1

All endpoints require a valid JWT (Authorization: Bearer).

• GET /api/user/v1/presigned-get-url/:fileId - Get presigned GET URL
• GET /api/user/v1/presigned-post-url - Get presigned POST URL
• POST /api/user/v1/upload - Upload file (multipart)
• PUT /api/user/v1/update/:fileId - Update (replace) file
• PUT /api/user/v1/upsert - Create or update by subject
• GET /api/user/v1/list - List user's files
• GET /api/user/v1/download/:fileId - Download as attachment
• GET /api/user/v1/inline/:fileId - Serve inline (browser preview)
• DELETE /api/user/v1/delete/:fileId - Soft-delete file record

Public Files (FilesPublicV1Api) — /api/public/v1

Download/inline endpoints are fully public; all others require x-api-key.

• GET /api/public/v1/presigned-get-url/:fileId - Get presigned GET URL
• GET /api/public/v1/presigned-post-url - Get presigned POST URL
• POST /api/public/v1/upload - Upload file
• PUT /api/public/v1/update/:fileId - Update file
• PUT /api/public/v1/upsert - Create or update by subject
• GET /api/public/v1/list - List public files
• GET /api/public/v1/download/:fileId - Download as attachment (no auth)
• GET /api/public/v1/inline/:fileId - Serve inline (no auth)
• DELETE /api/public/v1/delete/:fileId - Delete file

Group Files (FilesGroupV1Api) — /api/group/v1

All endpoints require a valid JWT + group membership for the given groupId.

• GET /api/group/v1/:groupId/presigned-get-url/:fileId - Get presigned GET URL
• GET /api/group/v1/:groupId/presigned-post-url - Get presigned POST URL
• POST /api/group/v1/:groupId/upload - Upload file
• PUT /api/group/v1/:groupId/update/:fileId - Update file
• PUT /api/group/v1/:groupId/upsert - Create or update by subject
• GET /api/group/v1/:groupId/list - List group files
• GET /api/group/v1/:groupId/download/:fileId - Download as attachment
• GET /api/group/v1/:groupId/inline/:fileId - Serve inline
• DELETE /api/group/v1/:groupId/delete/:fileId - Delete file

Buckets (BucketsV1Api) — /api/v1/buckets

System-only endpoints.

• POST /api/v1/buckets - Create bucket
• GET /api/v1/buckets - List buckets
• GET /api/v1/buckets/:bucketName - Get bucket info
• DELETE /api/v1/buckets/:bucketName - Delete bucket

🧪 Error Handling

import { AxiosError } from 'axios';

try {
  await userFilesApi.filesUserV1ControllerUpload(dto, file);
} catch (error) {
  if (error instanceof AxiosError) {
    switch (error.response?.status) {
      case 400:
        console.error('Validation failed:', error.response.data.message);
        break;
      case 401:
        console.error('Unauthorized:', error.response.data.message);
        break;
      case 403:
        console.error('Forbidden: Insufficient permissions');
        break;
      case 404:
        console.error('Resource not found');
        break;
      case 409:
        console.error('Conflict:', error.response.data.message);
        break;
      default:
        console.error('API Error:', error.message);
    }
  }
}

⚙️ Advanced Configuration

Custom Axios Instance

import axios from 'axios';
import { Configuration, FilesUserV1Api } from '@dimrev4/files-core';

const axiosInstance = axios.create({
  timeout: 30000, // file uploads may take longer
});

// Inject both auth headers automatically
axiosInstance.interceptors.request.use((config) => {
  const token = getStoredToken();
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  config.headers['x-api-key'] = process.env.FILES_CORE_API_KEY;
  return config;
});

const config = new Configuration({});
const filesApi = new FilesUserV1Api(config, undefined, axiosInstance);

Environment Setup

const config = new Configuration({
  basePath:
    process.env.NODE_ENV === 'production'
      ? 'https://api.yourdomain.com'
      : 'http://localhost:42071',
  apiKey: process.env.FILES_CORE_API_KEY,
  accessToken: process.env.ACCESS_TOKEN,
});

🚨 Common Issues

| Issue | Solution | | ---------------------- | ----------------------------------------------------------- | | 401 Unauthorized | Set accessToken in Configuration or custom headers | | 403 Forbidden | Check JWT is valid; check group membership for group routes | | 400 Missing API key | Set apiKey in Configuration (sent as x-api-key) | | CORS Error | Configure API CORS or use proxy in dev | | Validation Error (400) | Check request body against DTO schema |

📊 TypeScript Types

Key interfaces for type safety:

interface FileRecordDto {
  id: string;
  file_name: string;
  file_extension: string;
  file_subject: string;
  file_type: 'image' | 'video' | 'audio' | 'document';
  existing_in_buckets: ('users' | 'groups' | 'public')[];
  user_id: string | null;
  group_id: string | null;
  processed_at: string | null;
  created_at: string;
  updated_at: string;
}

interface CreateBucketRequestDto {
  name: string;
}

🔗 Resources

• API Docs: Available at http://localhost:42071/api (Swagger UI)
• Repository: GitHub
• Issues: GitHub Issues
• License: Unlicense

🤝 Contributing

1. Fork the repository
2. Update OpenAPI spec for new features
3. Run pnpm run sdk:generate to rebuild SDK
4. Submit pull request with tests

Auto-generated from Files Core API v0.0.13 | Last Updated: Mar 2026