![\"@smooai/file](\".github/banner.png\")
\n\n \n
\n ![\"npm\"](\"https://img.shields.io/npm/v/@smooai/file?style=for-the-badge&color=00A6A6&label=npm&logo=npm&logoColor=white&labelColor=020618\")
![\"PyPI\"](\"https://img.shields.io/pypi/v/smooai-file?style=for-the-badge&color=F49F0A&label=PyPI&logo=python&logoColor=white&labelColor=020618\")
![\"crates.io\"](\"https://img.shields.io/crates/v/smooai-file?style=for-the-badge&color=FF6B6C&label=crates.io&logo=rust&logoColor=white&labelColor=020618\")
![\"NuGet\"](\"https://img.shields.io/nuget/v/SmooAI.File?style=for-the-badge&color=00A6A6&label=NuGet&logo=nuget&logoColor=white&labelColor=020618\")
\n ![\"Smoo](\"https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618\"){kind=icon}
![\"license\"](\"https://img.shields.io/badge/license-MIT-F49F0A?style=for-the-badge&labelColor=020618\"){kind=icon}
![\"CI\"](\"https://github.com/SmooAI/file/actions/workflows/release.yml/badge.svg\"){kind=icon}
\n
\n ![\"downloads\"](\"https://img.shields.io/npm/dw/@smooai/file?style=flat-square&color=F49F0A&label=downloads\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Python\"](\"https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white\"){kind=icon}
![\"Rust\"](\"https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white\"){kind=icon}
![\"Go\"](\"https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white\"){kind=icon}
![\".NET\"](\"https://img.shields.io/badge/.NET-512BD4?style=flat-square&logo=dotnet&logoColor=white\"){kind=icon}
\n Features · \n Install · \n Language status · \n Usage · \n Platform\n
\n\n---\n\n> **A file abstraction that trusts the bytes, not the extension.** Built for backends that take uploads from the open internet: magic-byte MIME detection, size and content validation, and presigned S3 uploads — one `File` API over local files, URLs, streams, S3 objects, and browser uploads, ported natively to **five languages**: TypeScript, Python, Rust, Go, and .NET.\n\n## ✨ Features \n\n| | Capability | What you get |\n| --- | ---------------------------------------------------------- | -------------------------------------------------------------------- |\n| 🔒 | [**Trust the bytes**](#-trust-the-bytes-not-the-extension) | Magic-byte MIME detection catches spoofed uploads, in all five ports |\n| ☁️ | [**S3 in one call**](#️-s3-in-one-call) | Upload, download, signed URLs, presigned uploads with size caps |\n| 🌐 | [**One API, many sources**](#-one-api-many-sources) | Local · URL · bytes · stream · S3 · multipart, one `File` type |\n| 🌊 | [**Lazy streaming**](#-lazy-streaming) | Streams ingest without full buffering — all five ports |\n| 📝 | [**Rich metadata**](#-rich-metadata) | Detected MIME, size, timestamps, hash — on one object |\n\n#### 🔒 Trust the bytes, not the extension\n\nMagic-byte MIME detection catches spoofed uploads. A `.php` renamed to `avatar.png` fails validation because the bytes disagree with the claim.\n\n- Magic-byte detection across 100+ file types — in every port\n- Validation fails with a **typed error** when the client-claimed MIME disagrees with the bytes, when the file is oversize, or when the type isn't allowed\n- One `validate()` call; the errors map cleanly to HTTP 400\n\nThe error shape is idiomatic per language: TypeScript and Python throw `FileContentMismatchError` / `FileSizeError` / `FileMimeError` (all extending `FileValidationError`); .NET throws the same three as exceptions; Rust has a `FileValidationError` enum; Go returns one `FileValidationError` with a `Kind` field. Because catch-by-type doesn't survive that, **all five also carry the same `kind` string** (`size` · `mime` · `content_mismatch`) — the discriminant portable code branches on.\n\n#### ☁️ S3 in one call\n\n- Stream a file into S3 and pull S3 objects back through the same validation pipeline — all five ports\n- Presigned upload URLs with `maxSize` baked into the signature, so oversized uploads are rejected by S3 before they hit you — all five ports\n- Signed download URLs — all five ports\n- In .NET, S3 support is the separate [`SmooAI.File.S3`](https://www.nuget.org/packages/SmooAI.File.S3) package, so .NET consumers who only need detection/validation skip the AWS SDK dependency (the TypeScript package currently ships its AWS SDK dependencies unconditionally)\n\n#### 🌐 One API, many sources\n\nLocal filesystem, URL download, S3 object, raw bytes, streams, multipart form uploads, or a browser `File`/`Blob` — all resolve to the same `File` instance with the same validation and metadata surface.\n\n#### 🌊 Lazy streaming\n\n**All five ports** ingest streams lazily — only a 64 KiB head is read for MIME sniffing, and the rest of the bytes flow through without buffering the whole file (`createFromStreamLazy` · `from_stream(lazy=True)` · `from_stream_lazy` · `NewFromStreamLazy` · `CreateFromStreamLazyAsync`). The semantics are identical because all five test suites load one shared fixture, [`spec/lazy-stream-contract.json`](./spec/lazy-stream-contract.json) — head size, what stays lazy, what triggers a full read, and what a read after a full iteration does. The honest per-port breakdown is in the [capability matrix](#five-languages-honestly).\n\n#### 📝 Rich metadata\n\nFile name, real (detected) MIME type, size, created/modified timestamps, hash/checksum, source type — all on one object.\n\n### How it fits together\n\n```mermaid\n%%{init: {'theme':'base','themeVariables':{\n 'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',\n 'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',\n 'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%\nflowchart LR\n SRC[\"local file · URL · bytes\n Built by Smoo AI — AI built into every product.\n
\n","readmeFilename":"README.md"}