@oasis-path/gamma-sdk 1.0.0

package/README.md

@@ -0,0 +1,285 @@
+# Gamma Files SDK
+
+TypeScript/JavaScript SDK for interacting with the Gamma Files API.
+
+## Installation
+
+```bash
+pnpm install @gamma/files-sdk
+```
+
+Or if you're developing locally:
+
+```bash
+cd sdk
+pnpm install
+pnpm run build
+```
+
+Then in your project:
+
+```bash
+pnpm install ../sdk
+```
+
+## Configuration
+
+Create a client instance with your API key and base URL:
+
+```typescript
+import { GammaFilesClient } from '@gamma/files-sdk';
+
+const client = new GammaFilesClient({
+  baseUrl: 'http://localhost:3000',
+  apiKey: 'your-api-key-here'
+});
+```
+
+## Usage Examples
+
+### Upload a File
+
+```typescript
+import * as fs from 'fs';
+
+// Upload from Node.js Buffer
+const fileBuffer = fs.readFileSync('./document.pdf');
+const result = await client.uploadFile({
+  file: fileBuffer,
+  filename: 'document.pdf',
+  mimeType: 'application/pdf',
+  folderId: 'folder-id-here' // optional, uploads to root if not specified
+});
+
+console.log('Uploaded file:', result.file);
+```
+
+In browser environment:
+
+```typescript
+// Upload from File input
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+const result = await client.uploadFile({
+  file: file,
+  filename: file.name,
+  mimeType: file.type,
+  folderId: 'folder-id-here' // optional
+});
+```
+
+### Download a File
+
+```typescript
+const fileData = await client.downloadFile('file-id-here');
+
+// In Node.js, save to disk
+const buffer = Buffer.from(fileData);
+fs.writeFileSync('./downloaded-file.pdf', buffer);
+
+// In browser, create a download link
+const blob = new Blob([fileData]);
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'file.pdf';
+a.click();
+```
+
+### List Files in a Folder
+
+```typescript
+const result = await client.listFiles('folder-id-here');
+
+console.log('Files:', result.files);
+result.files.forEach(file => {
+  console.log(`- ${file.originalName} (${file.size} bytes)`);
+});
+```
+
+### Get File Metadata
+
+```typescript
+const result = await client.getFileMetadata('file-id-here');
+
+console.log('File metadata:', result.file);
+console.log('Name:', result.file.originalName);
+console.log('Size:', result.file.size);
+console.log('Type:', result.file.mimeType);
+console.log('Uploaded:', result.file.createdAt);
+```
+
+### Delete a File
+
+```typescript
+const result = await client.deleteFile('file-id-here');
+console.log(result.message); // "File deleted successfully"
+```
+
+### Generate Presigned URL
+
+Generate a temporary URL for file access without requiring API key authentication:
+
+```typescript
+const result = await client.generatePresignedUrl({
+  fileId: 'file-id-here',
+  expiresIn: 3600 // optional, defaults to 3600 seconds (1 hour)
+});
+
+console.log('Presigned URL:', result.url);
+console.log('Token:', result.token);
+console.log('Expires at:', result.expiresAt);
+
+// Share this URL with anyone - no API key needed
+```
+
+### View File by Token
+
+Access a file using a presigned token (no API key required):
+
+```typescript
+const fileData = await client.viewFileByToken('presigned-token-here');
+
+// Handle the file data as needed
+const buffer = Buffer.from(fileData);
+fs.writeFileSync('./viewed-file.pdf', buffer);
+```
+
+## API Reference
+
+### `GammaFilesClient`
+
+#### Constructor
+
+```typescript
+new GammaFilesClient(config: GammaFilesClientConfig)
+```
+
+**Parameters:**
+- `config.baseUrl` - Base URL of the Gamma API
+- `config.apiKey` - Your API key (must have appropriate permissions)
+
+#### Methods
+
+##### `uploadFile(options: UploadFileOptions): Promise<UploadFileResponse>`
+
+Upload a file to the server.
+
+**Parameters:**
+- `options.file` - File data (Buffer, Blob, or File object)
+- `options.filename` - Name of the file
+- `options.mimeType` - MIME type (optional, will be detected if not provided)
+- `options.folderId` - Target folder ID (optional, uploads to root folder if not specified)
+
+**Returns:** Upload response with file metadata
+
+**API Key Permissions Required:** `write` or `admin`
+
+##### `downloadFile(fileId: string): Promise<ArrayBuffer>`
+
+Download a file by ID.
+
+**Parameters:**
+- `fileId` - ID of the file to download
+
+**Returns:** File data as ArrayBuffer
+
+**API Key Permissions Required:** `read`, `write`, or `admin`
+
+##### `listFiles(folderId: string): Promise<ListFilesResponse>`
+
+List all files in a folder.
+
+**Parameters:**
+- `folderId` - ID of the folder
+
+**Returns:** List of files with metadata
+
+**API Key Permissions Required:** `read`, `write`, or `admin`
+
+##### `deleteFile(fileId: string): Promise<DeleteFileResponse>`
+
+Delete a file by ID.
+
+**Parameters:**
+- `fileId` - ID of the file to delete
+
+**Returns:** Deletion confirmation message
+
+**API Key Permissions Required:** `write` or `admin`
+
+##### `getFileMetadata(fileId: string): Promise<FileMetadataResponse>`
+
+Get metadata for a specific file.
+
+**Parameters:**
+- `fileId` - ID of the file
+
+**Returns:** File metadata
+
+**API Key Permissions Required:** `read`, `write`, or `admin`
+
+##### `generatePresignedUrl(options: PresignedUrlOptions): Promise<PresignedUrlResponse>`
+
+Generate a presigned URL for temporary file access.
+
+**Parameters:**
+- `options.fileId` - ID of the file
+- `options.expiresIn` - Expiration time in seconds (min: 60, max: 86400, default: 3600)
+
+**Returns:** Presigned URL information including token, full URL, and expiration time
+
+**API Key Permissions Required:** `read`, `write`, or `admin`
+
+##### `viewFileByToken(token: string): Promise<ArrayBuffer>`
+
+Access a file using a presigned token (no API key required).
+
+**Parameters:**
+- `token` - Presigned token from `generatePresignedUrl`
+
+**Returns:** File data as ArrayBuffer
+
+**API Key Permissions Required:** None (uses token authentication)
+
+## Types
+
+All TypeScript types are exported from the package:
+
+```typescript
+import {
+  GammaFilesClient,
+  GammaFilesClientConfig,
+  FileMetadata,
+  UploadFileOptions,
+  UploadFileResponse,
+  ListFilesResponse,
+  FileMetadataResponse,
+  DeleteFileResponse,
+  PresignedUrlOptions,
+  PresignedUrlResponse,
+  DownloadFileResult,
+  ApiErrorResponse
+} from '@gamma/files-sdk';
+```
+
+## Error Handling
+
+All methods throw errors when requests fail:
+
+```typescript
+try {
+  const result = await client.uploadFile({
+    file: buffer,
+    filename: 'test.pdf'
+  });
+  console.log('Success:', result);
+} catch (error) {
+  console.error('Upload failed:', error.message);
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { GammaFilesClientConfig, UploadFileOptions, UploadFileResponse, ListFilesResponse, FileMetadataResponse, DeleteFileResponse, PresignedUrlOptions, PresignedUrlResponse } from './types';
+export declare class GammaFilesClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: GammaFilesClientConfig);
+    /**
+     * Upload a file to a folder
+     * @param options Upload options including file buffer/blob, filename, and optional folderId
+     * @returns Upload response with file metadata
+     */
+    uploadFile(options: UploadFileOptions): Promise<UploadFileResponse>;
+    /**
+     * Download a file by ID
+     * @param fileId File ID to download
+     * @returns File metadata and data buffer
+     */
+    downloadFile(fileId: string): Promise<ArrayBuffer>;
+    /**
+     * List all files in a folder
+     * @param folderId Folder ID to list files from
+     * @returns List of files in the folder
+     */
+    listFiles(folderId: string): Promise<ListFilesResponse>;
+    /**
+     * Delete a file by ID
+     * @param fileId File ID to delete
+     * @returns Deletion confirmation
+     */
+    deleteFile(fileId: string): Promise<DeleteFileResponse>;
+    /**
+     * Get file metadata by ID
+     * @param fileId File ID to get metadata for
+     * @returns File metadata
+     */
+    getFileMetadata(fileId: string): Promise<FileMetadataResponse>;
+    /**
+     * Generate a presigned URL for temporary file access
+     * @param options Options including fileId and optional expiresIn (seconds)
+     * @returns Presigned URL token and expiration info
+     */
+    generatePresignedUrl(options: PresignedUrlOptions): Promise<PresignedUrlResponse>;
+    /**
+     * Access a file using a presigned token (no API key required)
+     * @param token Presigned token
+     * @returns File data as ArrayBuffer
+     */
+    viewFileByToken(token: string): Promise<ArrayBuffer>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,224 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GammaFilesClient = void 0;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const url_1 = require("url");
+const form_data_1 = __importDefault(require("form-data"));
+class GammaFilesClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.apiKey = config.apiKey;
+    }
+    /**
+     * Upload a file to a folder
+     * @param options Upload options including file buffer/blob, filename, and optional folderId
+     * @returns Upload response with file metadata
+     */
+    async uploadFile(options) {
+        const { file, filename, mimeType, folderId } = options;
+        const form = new form_data_1.default();
+        // Handle different file types
+        let fileBuffer;
+        let contentType = mimeType || 'application/octet-stream';
+        if (Buffer.isBuffer(file)) {
+            fileBuffer = file;
+        }
+        else if (typeof Blob !== 'undefined' && file instanceof Blob) {
+            // Browser environment
+            const arrayBuffer = await file.arrayBuffer();
+            fileBuffer = Buffer.from(arrayBuffer);
+            contentType = mimeType || file.type || 'application/octet-stream';
+        }
+        else if (typeof File !== 'undefined' && file instanceof File) {
+            // Browser File object
+            const arrayBuffer = await file.arrayBuffer();
+            fileBuffer = Buffer.from(arrayBuffer);
+            contentType = mimeType || file.type || 'application/octet-stream';
+        }
+        else {
+            throw new Error('Unsupported file type');
+        }
+        form.append('file', fileBuffer, {
+            filename,
+            contentType,
+        });
+        const url = folderId
+            ? `/api/files/upload/${folderId}`
+            : '/api/files/upload';
+        return this.request('POST', url, {
+            body: form,
+            headers: form.getHeaders(),
+        });
+    }
+    /**
+     * Download a file by ID
+     * @param fileId File ID to download
+     * @returns File metadata and data buffer
+     */
+    async downloadFile(fileId) {
+        const url = `/api/files/download/${fileId}`;
+        return this.request('GET', url, { binary: true });
+    }
+    /**
+     * List all files in a folder
+     * @param folderId Folder ID to list files from
+     * @returns List of files in the folder
+     */
+    async listFiles(folderId) {
+        const url = `/api/files/list/${folderId}`;
+        return this.request('GET', url);
+    }
+    /**
+     * Delete a file by ID
+     * @param fileId File ID to delete
+     * @returns Deletion confirmation
+     */
+    async deleteFile(fileId) {
+        const url = `/api/files/${fileId}`;
+        return this.request('DELETE', url);
+    }
+    /**
+     * Get file metadata by ID
+     * @param fileId File ID to get metadata for
+     * @returns File metadata
+     */
+    async getFileMetadata(fileId) {
+        const url = `/api/files/${fileId}/metadata`;
+        return this.request('GET', url);
+    }
+    /**
+     * Generate a presigned URL for temporary file access
+     * @param options Options including fileId and optional expiresIn (seconds)
+     * @returns Presigned URL token and expiration info
+     */
+    async generatePresignedUrl(options) {
+        const url = '/api/files/presigned-url';
+        return this.request('POST', url, {
+            body: JSON.stringify(options),
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Access a file using a presigned token (no API key required)
+     * @param token Presigned token
+     * @returns File data as ArrayBuffer
+     */
+    async viewFileByToken(token) {
+        const url = `/api/files/view/${token}`;
+        return this.request('GET', url, {
+            binary: true,
+            skipAuth: true
+        });
+    }
+    async request(method, path, options = {}) {
+        const url = new url_1.URL(path, this.baseUrl);
+        const isHttps = url.protocol === 'https:';
+        const lib = isHttps ? https : http;
+        return new Promise((resolve, reject) => {
+            const headers = {
+                ...options.headers,
+            };
+            if (!options.skipAuth) {
+                headers['X-API-Key'] = this.apiKey;
+            }
+            // If body is not FormData, set content-length
+            if (options.body && !(options.body instanceof form_data_1.default)) {
+                if (typeof options.body === 'string') {
+                    headers['Content-Length'] = Buffer.byteLength(options.body).toString();
+                }
+            }
+            const reqOptions = {
+                method,
+                headers,
+            };
+            const req = lib.request(url, reqOptions, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => {
+                    chunks.push(chunk);
+                });
+                res.on('end', () => {
+                    const buffer = Buffer.concat(chunks);
+                    if (res.statusCode && res.statusCode >= 400) {
+                        let errorMessage = `HTTP ${res.statusCode}`;
+                        try {
+                            const errorBody = JSON.parse(buffer.toString());
+                            errorMessage = errorBody.error || errorMessage;
+                        }
+                        catch {
+                            errorMessage = buffer.toString() || errorMessage;
+                        }
+                        reject(new Error(errorMessage));
+                        return;
+                    }
+                    if (options.binary) {
+                        resolve(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+                    }
+                    else {
+                        try {
+                            const data = JSON.parse(buffer.toString());
+                            resolve(data);
+                        }
+                        catch (err) {
+                            reject(new Error('Failed to parse response JSON'));
+                        }
+                    }
+                });
+            });
+            req.on('error', (err) => {
+                reject(err);
+            });
+            if (options.body) {
+                if (options.body instanceof form_data_1.default) {
+                    options.body.pipe(req);
+                }
+                else {
+                    req.write(options.body);
+                    req.end();
+                }
+            }
+            else {
+                req.end();
+            }
+        });
+    }
+}
+exports.GammaFilesClient = GammaFilesClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { GammaFilesClient } from './client';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GammaFilesClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "GammaFilesClient", { enumerable: true, get: function () { return client_1.GammaFilesClient; } });
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+export interface GammaFilesClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface FileMetadata {
+    id: string;
+    name: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    folderId: string;
+    uploadedBy: string;
+    createdAt: string;
+}
+export interface UploadFileOptions {
+    file: Buffer | Blob | File;
+    filename: string;
+    mimeType?: string;
+    folderId?: string;
+}
+export interface UploadFileResponse {
+    success: true;
+    file: FileMetadata;
+}
+export interface ListFilesResponse {
+    success: true;
+    files: FileMetadata[];
+}
+export interface FileMetadataResponse {
+    success: true;
+    file: FileMetadata;
+}
+export interface DeleteFileResponse {
+    success: true;
+    message: string;
+}
+export interface PresignedUrlOptions {
+    fileId: string;
+    expiresIn?: number;
+}
+export interface PresignedUrlResponse {
+    success: true;
+    token: string;
+    url: string;
+    expiresAt: string;
+}
+export interface DownloadFileResult {
+    file: FileMetadata;
+    data: ArrayBuffer;
+}
+export interface ApiErrorResponse {
+    success: false;
+    error: string;
+    details?: any;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oasis-path/gamma-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for Gamma Files API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "gamma",
+    "files",
+    "sdk",
+    "api-client",
+    "file-management",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "form-data": "^4.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  }
+}