� Penguin File Uploader

A lightweight SDK for uploading, downloading, and managing files via the Penguin Embrace Files API with presigned URL support.

Built for Node.js and browser environments.

🚀 Installation

npm install penguin-file-uploader

📖 Quick Start

import { PenguinFiles } from 'penguin-file-uploader';

const client = new PenguinFiles({
  apiKey: 'pk_live_xxx',
  tenantId: 'tenant_123',
});

const result = await client.uploadFile(file);
console.log(result.objectKey);

📦 API Reference

new PenguinFiles(options)

Creates a new client instance.

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | API key (starts with pk_) | | tenantId | string | Yes | Your tenant ID | | baseUrl | string | No | Base URL (defaults to https://rs.penguinembrace.com) |

client.uploadFile(file, options?)

Uploads a file using the presigned URL pattern.

Parameters:

• file - File (browser) or Buffer (Node.js)
• options - Optional: filename, mimeType, metadata

Returns UploadResult with: uploadId, objectKey, presignedUrl, expiresAt

client.downloadFile(objectKey, options?)

Gets a presigned URL for downloading a file.

Parameters:

• objectKey - The object key from uploadFile result
• options - Optional: expires (default 900, max 3600), filename

Returns DownloadResult with: presignedUrl, expiresAt

client.deleteFile(objectKey)

Deletes a file from storage.

client.listFiles(options?)

Lists files with optional filtering.

Parameters:

• options - Optional: prefix, status (pending/confirmed/failed/deleted), limit, cursor

Returns ListResult with: items (FileItem[]), nextCursor, totalCount

client.getUsage()

Gets storage usage statistics.

Returns UsageResult with: tenantId, totalFiles, totalBytes, totalBytesHuman, updatedAt

⚠️ Error Handling

import { PenguinFiles, PenguinFilesError } from 'penguin-file-uploader';

try {
  await client.uploadFile(file);
} catch (error) {
  if (error instanceof PenguinFilesError) {
    console.log(error.code);
    console.log(error.statusCode);
  }
}

Error Codes: BAD_REQUEST (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), QUOTA_EXCEEDED (422), NETWORK_ERROR (0)

🔄 Migration from v3

Old v3:

import { addFile } from 'penguin-file-uploader';
const result = await addFile('apiKey', file);

New v4:

import { PenguinFiles } from 'penguin-file-uploader';
const client = new PenguinFiles({ apiKey: 'pk_xxx', tenantId: 'tenant_123' });
const result = await client.uploadFile(file);

📄 License

MIT © Rodrigo Barrocas