About Smoo AI

Smoo AI is an AI platform that helps businesses multiply their customer, employee, and developer experience — conversational AI for support and sales, paired with the production-grade developer tooling we use to build it.

This library is part of a small family of open-source packages we maintain to keep our own stack honest: contextual logging, typed HTTP, file storage, and agent orchestration. Use them in your stack, or take them as a reference for how we build.

• 🌐 smoo.ai — the product
• 📦 smoo.ai/open-source — every open-source package we ship
• 🐙 github.com/SmooAI — the source

About @smooai/file

File operations that don't lie — magic-byte MIME detection catches spoofed extensions, size + content validation is built in, and presigned S3 uploads are one call away. Stream-first so a 2 GB upload doesn't blow your Lambda memory.

Install

pnpm add @smooai/file

Multi-Language Support

@smooai/file is available as native implementations in TypeScript, Python, Rust, Go, and .NET (C#) — each built with idiomatic patterns for its ecosystem.

| Language | Package | Install | | ----------- | ----------------------------------------------------------------- | --------------------------------------- | | TypeScript | @smooai/file | pnpm add @smooai/file | | Python | smooai-file | pip install smooai-file | | Rust | smooai-file | cargo add smooai-file | | Go | github.com/SmooAI/file/go/file | go get github.com/SmooAI/file/go/file | | .NET (core) | SmooAI.File | dotnet add package SmooAI.File | | .NET (S3) | SmooAI.File.S3 | dotnet add package SmooAI.File.S3 |

Language-specific source code lives in the python/, rust/, go/, and dotnet/ directories.

The .NET port uses Mime-Detective for magic-byte MIME sniffing and splits S3 helpers into a sub-package so consumers who don't need AWS avoid pulling in the AWS SDK.

What you get

🔒 Trust the bytes, not the extension

Magic-byte MIME detection catches spoofed uploads. A .php renamed to avatar.png fails validation because the bytes disagree with the claim.

• Magic-byte detection across 100+ file types
• FileContentMismatchError when client-claimed MIME disagrees with the bytes
• FileSizeError / FileMimeError for oversize or disallowed uploads
• One validate() call, typed error types, map cleanly to HTTP 400

☁️ S3 in one call

• Stream any file (local, URL, Blob) straight into S3
• Pull S3 objects back through the same validation pipeline
• Presigned upload URLs with maxSize baked into the signature, so oversized uploads are rejected by S3 before they hit you

🌐 One API, many sources

Local filesystem, URL download, S3 object, multipart FormData, or a browser File/Blob — all resolve to the same File instance with the same validation and metadata surface.

🚀 Stream-first under the hood

Bytes load lazily so a 2 GB upload doesn't buffer into memory. Automatic handling across Node.js and Web streams — you never have to pick the right pipe.

📝 Rich metadata

File name, real (detected) MIME type, size, created/modified timestamps, hash/checksum, source type — all on one object.

Examples

• Basic Usage
• Streaming Operations
• S3 Integration
• File Type Detection
• FormData Support
• Web File / Blob (Hono, Next.js, Browser)
• Validation (size, mime, content-vs-claim)
• Base64 Encoding
• Presigned Upload URL

Basic Usage

import File from '@smooai/file';

// Create a file from a local path
const file = await File.createFromFile('path/to/file.txt');

// Read file contents (streams automatically)
const content = await file.readFileString();
console.log(content);

// Get file metadata
console.log(file.metadata);
// {
//   name: 'file.txt',
//   mimeType: 'text/plain',
//   size: 1234,
//   extension: 'txt',
//   path: 'path/to/file.txt',
//   lastModified: Date,
//   createdAt: Date
// }

Streaming Operations

import File from '@smooai/file';

// Create a file from a URL (streams automatically)
const file = await File.createFromUrl('https://example.com/large-file.zip');

// Pipe to a destination (streams without loading entire file)
await file.pipeTo(someWritableStream);

// Read as bytes (streams in chunks)
const bytes = await file.readFileBytes();

// Save to filesystem (streams directly)
const { original, newFile } = await file.saveToFile('downloads/file.zip');

S3 Integration

import File from '@smooai/file';

// Create from S3 (streams automatically)
const file = await File.createFromS3('my-bucket', 'path/to/file.jpg');

// Upload to S3 (streams directly)
await file.uploadToS3('my-bucket', 'remote/file.jpg');

// Save to S3 (creates new file instance)
const { original, newFile } = await file.saveToS3('my-bucket', 'remote/file.jpg');

// Move to S3 (deletes local file if source was local)
const s3File = await file.moveToS3('my-bucket', 'remote/file.jpg');

// Generate signed URL
const signedUrl = await s3File.getSignedUrl(3600); // URL expires in 1 hour

File Type Detection

import File from '@smooai/file';

const file = await File.createFromFile('document.xml');

// Get file type information (detected via magic numbers)
console.log(file.mimeType); // 'application/xml'
console.log(file.extension); // 'xml'

// File type is automatically detected from:
// - Magic numbers (via file-type)
// - MIME type headers
// - File extension
// - Custom detectors

FormData Support

import File from '@smooai/file';

const file = await File.createFromFile('document.pdf');

// Convert to FormData for uploads
const formData = await file.toFormData('document');

// Use with fetch or other HTTP clients
await fetch('https://api.example.com/upload', {
    method: 'POST',
    body: formData,
});

Web File / Blob (Hono, Next.js, Browser)

import File from '@smooai/file';

// Hono multipart route
app.post('/upload', async (c) => {
    const form = await c.req.formData();
    const webFile = form.get('file') as globalThis.File;

    // Preserves the web File's name and type hints.
    const file = await File.createFromWebFile(webFile);
    // …validate, upload, etc.
});

Validation (size, mime, content-vs-claim)

import File, { FileValidationError } from '@smooai/file';

const file = await File.createFromWebFile(webFile);

try {
    await file.validate({
        maxSize: 5 * 1024 * 1024, // 5MB
        allowedMimes: ['image/png', 'image/jpeg', 'image/webp'],
        expectedMimeType: webFile.type, // compares magic-byte detection vs claimed Content-Type
    });
} catch (err) {
    if (err instanceof FileValidationError) {
        // FileSizeError | FileMimeError | FileContentMismatchError — map to HTTP 400
        throw new HTTPException(400, { message: err.message });
    }
    throw err;
}

expectedMimeType is the primary defense against mime-spoofing: a .php file uploaded with Content-Type: image/png will fail because magic-byte detection doesn't match the claim.

Base64 Encoding (email attachments, data URLs)

import File from '@smooai/file';

const file = await File.createFromUrl('https://s3.example.com/invoice.pdf');

await sendEmail({
    attachments: [
        {
            filename: 'invoice.pdf',
            content: await file.toBase64(),
            encoding: 'base64',
        },
    ],
});

Presigned Upload URL (server signs, client uploads direct to S3)

import File from '@smooai/file';

// Server issues a time-limited signed URL the client uploads bytes to directly.
// `maxSize` is baked into the signature so oversized uploads are rejected by S3.
const url = await File.createPresignedUploadUrl({
    bucket: Resource.Bucket.name,
    key: `avatars/${userId}.png`,
    contentType: 'image/png',
    expiresIn: 600,
    maxSize: 2 * 1024 * 1024,
});

Built With

• TypeScript
• Node.js File System API
• AWS SDK v3
• file-type for magic number-based MIME type detection
• @smooai/fetch for URL downloads
• @smooai/logger for structured logging

Contributing

Contributions are welcome! This project uses changesets to manage versions and releases.

Development Workflow

1. Fork the repository

2. Create your branch (git checkout -b amazing-feature)

3. Make your changes

4. Add a changeset to document your changes:

   pnpm changeset

   This will prompt you to:

   • Choose the type of version bump (patch, minor, or major)
   • Provide a description of the changes

5. Commit your changes (git commit -m 'Add some amazing feature')

6. Push to the branch (git push origin feature/amazing-feature)

7. Open a Pull Request

Pull Request Guidelines

• Reference any related issues in your PR description

The maintainers will review your PR and may request changes before merging.

Contact

Brent Rager

• Email
• LinkedIn
• BlueSky
• TikTok
• Instagram

Smoo Github: https://github.com/SmooAI