Merge pull request #143 from NianJiuZst/feat/sdk-file-module

feat: add FileSDK module for file storage operations

Author: RyanLee-Dev

src/sdk/file/index.ts

@@ -0,0 +1,77 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve, basename } from 'node:path';
+import { Client } from '../client';
+import {
+  fileUploadEndpoint,
+  fileListEndpoint,
+  fileDeleteEndpoint,
+  fileRetrieveEndpoint,
+} from '../../client/endpoints';
+import type {
+  FileUploadResponse,
+  FileListResponse,
+  FileDeleteResponse,
+  FileRetrieveResponse,
+} from '../../types/api';
+import { SDKError } from '../../errors/base';
+import { ExitCode } from '../../errors/codes';
+
+export class FileSDK extends Client {
+  /**
+   * Upload a file to MiniMax storage.
+   *
+   * @param filePath - Absolute or relative path to the file on disk.
+   * @param purpose  - File purpose, defaults to `"retrieval"`.
+   */
+  async upload(filePath: string, purpose = 'retrieval'): Promise<FileUploadResponse> {
+    const fullPath = resolve(filePath);
+    if (!existsSync(fullPath)) {
+      throw new SDKError(`File not found: ${fullPath}`, ExitCode.USAGE);
+    }
+
+    const fileData = await readFile(fullPath);
+    const fileName = basename(fullPath);
+
+    const formData = new FormData();
+    formData.append('file', new Blob([fileData]), fileName);
+    formData.append('purpose', purpose);
+
+    const url = fileUploadEndpoint(this.config.baseUrl);
+    return this.requestJson<FileUploadResponse>({
+      url,
+      method: 'POST',
+      body: formData,
+    });
+  }
+
+  /** List all files in MiniMax storage. */
+  async list(): Promise<FileListResponse> {
+    const url = fileListEndpoint(this.config.baseUrl);
+    return this.requestJson<FileListResponse>({ url, method: 'GET' });
+  }
+
+  /**
+   * Delete a file from MiniMax storage by its file ID.
+   *
+   * @param fileId - The ID of the file to delete (string or number).
+   */
+  async delete(fileId: string | number): Promise<FileDeleteResponse> {
+    const url = fileDeleteEndpoint(this.config.baseUrl);
+    return this.requestJson<FileDeleteResponse>({
+      url,
+      method: 'POST',
+      body: { file_id: Number(fileId) },
+    });
+  }
+
+  /**
+   * Retrieve metadata (and optional download URL) for a file.
+   *
+   * @param fileId - The ID of the file to retrieve.
+   */
+  async retrieve(fileId: string): Promise<FileRetrieveResponse> {
+    const url = fileRetrieveEndpoint(this.config.baseUrl, fileId);
+    return this.requestJson<FileRetrieveResponse>({ url, method: 'GET' });
+  }
+}

src/sdk/index.ts

@@ -6,6 +6,7 @@ import { MusicSDK } from "./music";
 import { SearchSDK } from "./search";
 import { VisionSDK } from "./vision";
 import { QuotaSDK } from "./quota";
+import { FileSDK } from "./file";
 import { Client } from "./client";
 import { MiniMaxSDKOptions } from "./types";
 
@@ -18,6 +19,7 @@ export class MiniMaxSDK extends Client {
   readonly search: SearchSDK;
   readonly vision: VisionSDK;
   readonly quota: QuotaSDK;
+  readonly file: FileSDK;
 
   constructor(options: MiniMaxSDKOptions) {
     super(options);
@@ -29,5 +31,6 @@ export class MiniMaxSDK extends Client {
     this.search = new SearchSDK(options);
     this.vision = new VisionSDK(options);
     this.quota = new QuotaSDK(options);
+    this.file = new FileSDK(options);
   }
 }

test/sdk/file.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'bun:test';
+import { FileSDK } from '../../src/sdk/file';
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('FileSDK', () => {
+  it('throws SDKError when file does not exist', async () => {
+    const sdk = new FileSDK({ apiKey: 'sk-test', region: 'global' });
+    await expect(sdk.upload('/tmp/nonexistent-file-xxxxx.bin', 'retrieval'))
+      .rejects
+      .toThrow('File not found');
+  });
+
+  it('gets past file existence check for a valid file', async () => {
+    const tmpFile = join(tmpdir(), 'mmx-sdk-test-upload.txt');
+    writeFileSync(tmpFile, 'hello world');
+
+    try {
+      const sdk = new FileSDK({ apiKey: 'sk-test', region: 'global' });
+      await sdk.upload(tmpFile, 'retrieval');
+      // Should not reach here (no mock server), but if it does, fail informatively
+    } catch (err) {
+      // Must NOT be "File not found" — proves file existence check passed
+      expect((err as Error).message).not.toContain('File not found');
+    } finally {
+      if (existsSync(tmpFile)) unlinkSync(tmpFile);
+    }
+  });
+});