diff --git a/README.md b/README.md index e0b5d92..6251ca9 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,39 @@ - - - - - - - - -
-
- - SmooAI Logo - -
- - - -## About Smoo AI - -**[Smoo AI](https://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](https://smoo.ai) โ€” the product -- ๐Ÿ“ฆ [smoo.ai/open-source](https://smoo.ai/open-source) โ€” every open-source package we ship -- ๐Ÿ™ [github.com/SmooAI](https://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. - -![NPM Version](https://img.shields.io/npm/v/%40smooai%2Ffile?style=for-the-badge) -![NPM Downloads](https://img.shields.io/npm/dw/%40smooai%2Ffile?style=for-the-badge) -![NPM Last Update](https://img.shields.io/npm/last-update/%40smooai%2Ffile?style=for-the-badge) - -![GitHub License](https://img.shields.io/github/license/SmooAI/file?style=for-the-badge) -![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/SmooAI/file/release.yml?style=for-the-badge) -![GitHub Repo stars](https://img.shields.io/github/stars/SmooAI/file?style=for-the-badge) - -### Install +

+ Smoo AI +

-```sh -pnpm add @smooai/file -``` +

@smooai/file

-### Multi-Language Support +

+ File operations that don't lie โ€” magic-byte MIME detection, built-in validation, and one-call presigned S3 uploads, all stream-first. +

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

+ npm + downloads + Smoo AI + license + TypeScript + Python + Rust + Go + .NET +

-| Language | Package | Install | -| ----------- | ----------------------------------------------------------------- | --------------------------------------- | -| TypeScript | [`@smooai/file`](https://www.npmjs.com/package/@smooai/file) | `pnpm add @smooai/file` | -| Python | [`smooai-file`](https://pypi.org/project/smooai-file/) | `pip install smooai-file` | -| Rust | [`smooai-file`](https://crates.io/crates/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`](https://www.nuget.org/packages/SmooAI.File) | `dotnet add package SmooAI.File` | -| .NET (S3) | [`SmooAI.File.S3`](https://www.nuget.org/packages/SmooAI.File.S3) | `dotnet add package SmooAI.File.S3` | +

+ Features ยท + Install ยท + Usage ยท + Platform +

-Language-specific source code lives in the [`python/`](./python/), [`rust/`](./rust/), [`go/`](./go/), and [`dotnet/`](./dotnet/) directories. +--- -The .NET port uses [Mime-Detective](https://github.com/MediatedCommunications/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. +> 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 โ€” all stream-first, so a 2 GB upload never buffers into your Lambda memory. -### What you get +## โœจ Features #### ๐Ÿ”’ Trust the bytes, not the extension @@ -103,19 +62,44 @@ Bytes load lazily so a 2 GB upload doesn't buffer into memory. Automatic handlin File name, real (detected) MIME type, size, created/modified timestamps, hash/checksum, source type โ€” all on one object. -### Examples +## ๐Ÿ“ฆ Install -- [Basic Usage](#basic-usage) -- [Streaming Operations](#streaming-operations) -- [S3 Integration](#s3-integration) -- [File Type Detection](#file-type-detection) -- [FormData Support](#formdata-support) +```sh +pnpm add @smooai/file +``` + +### Multi-language support + +@smooai/file ships 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`](https://www.npmjs.com/package/@smooai/file) | `pnpm add @smooai/file` | +| Python | [`smooai-file`](https://pypi.org/project/smooai-file/) | `pip install smooai-file` | +| Rust | [`smooai-file`](https://crates.io/crates/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`](https://www.nuget.org/packages/SmooAI.File) | `dotnet add package SmooAI.File` | +| .NET (S3) | [`SmooAI.File.S3`](https://www.nuget.org/packages/SmooAI.File.S3) | `dotnet add package SmooAI.File.S3` | + +Language-specific source lives in the [`python/`](./python/), [`rust/`](./rust/), [`go/`](./go/), and [`dotnet/`](./dotnet/) directories. + +The .NET port uses [Mime-Detective](https://github.com/MediatedCommunications/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. + +## ๐Ÿš€ Usage + +Jump to a pattern: + +- [Basic usage](#basic-usage) +- [Streaming operations](#streaming-operations) +- [S3 integration](#s3-integration) +- [File type detection](#file-type-detection) +- [FormData support](#formdata-support) - [Web File / Blob (Hono, Next.js, Browser)](#web-file) - [Validation (size, mime, content-vs-claim)](#validation) -- [Base64 Encoding](#base64) -- [Presigned Upload URL](#presigned-upload) +- [Base64 encoding](#base64) +- [Presigned upload URL](#presigned-upload) -#### Basic Usage +#### Basic usage ```typescript import File from '@smooai/file'; @@ -140,9 +124,9 @@ console.log(file.metadata); // } ``` -

(back to examples)

+

(back to usage)

-#### Streaming Operations +#### Streaming operations ```typescript import File from '@smooai/file'; @@ -160,9 +144,9 @@ const bytes = await file.readFileBytes(); const { original, newFile } = await file.saveToFile('downloads/file.zip'); ``` -

(back to examples)

+

(back to usage)

-#### S3 Integration +#### S3 integration ```typescript import File from '@smooai/file'; @@ -183,9 +167,9 @@ const s3File = await file.moveToS3('my-bucket', 'remote/file.jpg'); const signedUrl = await s3File.getSignedUrl(3600); // URL expires in 1 hour ``` -

(back to examples)

+

(back to usage)

-#### File Type Detection +#### File type detection ```typescript import File from '@smooai/file'; @@ -203,9 +187,9 @@ console.log(file.extension); // 'xml' // - Custom detectors ``` -

(back to examples)

+

(back to usage)

-#### FormData Support +#### FormData support ```typescript import File from '@smooai/file'; @@ -222,7 +206,7 @@ await fetch('https://api.example.com/upload', { }); ``` -

(back to examples)

+

(back to usage)

#### Web File / Blob (Hono, Next.js, Browser) @@ -240,7 +224,7 @@ app.post('/upload', async (c) => { }); ``` -

(back to examples)

+

(back to usage)

#### Validation (size, mime, content-vs-claim) @@ -266,9 +250,9 @@ try { `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. -

(back to examples)

+

(back to usage)

-#### Base64 Encoding (email attachments, data URLs) +#### Base64 encoding (email attachments, data URLs) ```typescript import File from '@smooai/file'; @@ -286,9 +270,9 @@ await sendEmail({ }); ``` -

(back to examples)

+

(back to usage)

-#### Presigned Upload URL (server signs, client uploads direct to S3) +#### Presigned upload URL (server signs, client uploads direct to S3) ```typescript import File from '@smooai/file'; @@ -304,9 +288,9 @@ const url = await File.createPresignedUploadUrl({ }); ``` -

(back to examples)

+

(back to usage)

-### Built With +## ๐Ÿ”ง Built with - TypeScript - Node.js File System API @@ -315,40 +299,45 @@ const url = await File.createPresignedUploadUrl({ - [@smooai/fetch](https://github.com/SmooAI/fetch) for URL downloads - [@smooai/logger](https://github.com/SmooAI/logger) for structured logging -## Contributing +## ๐Ÿงฉ Part of Smoo AI + +@smooai/file is part of the [Smoo AI](https://smoo.ai) platform โ€” an AI-powered business platform with AI built into every product. It's one of a small family of open-source packages we maintain to keep our own stack honest. Use them in your stack, or take them as a reference for how we build. + +- [@smooai/fetch](https://github.com/SmooAI/fetch) โ€” typed HTTP with retries and structured errors +- [@smooai/logger](https://github.com/SmooAI/logger) โ€” contextual structured logging +- [@smooai/config](https://github.com/SmooAI/config) โ€” typed config, secrets, and feature flags +- [smooth](https://github.com/SmooAI/smooth) โ€” the agent orchestration toolkit -Contributions are welcome! This project uses [changesets](https://github.com/changesets/changesets) to manage versions and releases. +Browse everything at [smoo.ai/open-source](https://smoo.ai/open-source) and [github.com/SmooAI](https://github.com/SmooAI). -### Development Workflow +## ๐Ÿค Contributing + +Contributions are welcome. This project uses [changesets](https://github.com/changesets/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: +4. Add a changeset to document them: ```sh pnpm changeset ``` - This will prompt you to: - - Choose the type of version bump (patch, minor, or major) - - Provide a description of the changes + You'll be prompted to choose a version bump (patch, minor, or major) and describe the change. 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 +7. Open a pull request โ€” reference any related issues in the description The maintainers will review your PR and may request changes before merging. - +## ๐Ÿ“„ License -

(back to top)

+MIT โ€” see [LICENSE](./LICENSE). -## Contact +## ๐Ÿ“ฌ Contact Brent Rager @@ -358,29 +347,12 @@ Brent Rager - [TikTok](https://www.tiktok.com/@brentragertech) - [Instagram](https://www.instagram.com/brentragertech/) -Smoo Github: [https://github.com/SmooAI](https://github.com/SmooAI) +Smoo GitHub: [https://github.com/SmooAI](https://github.com/SmooAI)

(back to top)

- - - -[sst.dev-url]: https://reactjs.org/ -[sst]: https://img.shields.io/badge/sst-EDE1DA?style=for-the-badge&logo=sst&logoColor=E27152 -[sst-url]: https://sst.dev/ -[next]: https://img.shields.io/badge/next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white -[next-url]: https://nextjs.org/ -[aws]: https://img.shields.io/badge/aws-232F3E?style=for-the-badge&logo=amazonaws&logoColor=white -[aws-url]: https://tailwindcss.com/ -[tailwindcss]: https://img.shields.io/badge/tailwind%20css-0B1120?style=for-the-badge&logo=tailwindcss&logoColor=#06B6D4 -[tailwindcss-url]: https://tailwindcss.com/ -[zod]: https://img.shields.io/badge/zod-3E67B1?style=for-the-badge&logoColor=3E67B1 -[zod-url]: https://zod.dev/ -[sanity]: https://img.shields.io/badge/sanity-F36458?style=for-the-badge -[sanity-url]: https://www.sanity.io/ -[vitest]: https://img.shields.io/badge/vitest-1E1E20?style=for-the-badge&logo=vitest&logoColor=#6E9F18 -[vitest-url]: https://vitest.dev/ -[pnpm]: https://img.shields.io/badge/pnpm-F69220?style=for-the-badge&logo=pnpm&logoColor=white -[pnpm-url]: https://pnpm.io/ -[turborepo]: https://img.shields.io/badge/turborepo-000000?style=for-the-badge&logo=turborepo&logoColor=#EF4444 -[turborepo-url]: https://turbo.build/ +--- + +

+ Built by Smoo AI โ€” AI built into every product. +