algoflows · webbrain-one · Aug 5, 2026
diff --git a/README.es-ES.md b/README.es-ES.md
@@ -0,0 +1,224 @@
+
+
+# 🚧 En construcción
+
+Este proyecto está actualmente en construcción y sujeto a cambios.
+
+# Cliente S3 para Zig 🚀
+
+[![Zig](https://img.shields.io/badge/Zig-0.13.0-orange.svg)](https://ziglang.org)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](https://github.com/algoflows/zig-s3)
+
+Una biblioteca simple y eficiente de cliente S3 para Zig, que soporta AWS S3 y servicios compatibles con S3.
+
+## 📑 Tabla de contenidos
+
+- [Características](#features)
+- [Prerrequisitos](#prerequisites)
+- [Instalación](#installation)
+- [Inicio rápido](#quick-start)
+- [Referencia de la API](#api-reference)
+- [Manejo de errores](#error-handling)
+- [Pruebas](#testing)
+- [Desarrollo](#development)
+- [Contribuir](#contributing)
+- [Comunidad](#community)
+- [Licencia](#license)
+
+## ✨ Características
+
+- ✅ Operaciones básicas de S3 (crear/eliminar buckets, subir/descargar objetos)
+- 🔐 Autenticación AWS Signature V4
+- 🔌 Soporte para endpoints personalizados (MinIO, LocalStack, etc.)
+- 📝 Soporte de paginación para listar objetos
+- 📦 Ayudas de subida convenientes para diferentes tipos de contenido:
+  - Subida de contenido como cadena de texto
+  - Serialización y subida de JSON
+  - Subida de archivos del sistema de archivos
+- 🛡️ Implementación segura en memoria usando la biblioteca estándar de Zig
+- 🧪 Conjunto de pruebas exhaustivo:
+  - Pruebas unitarias para todos los componentes
+  - Pruebas de integración con MinIO
+  - Activos de prueba para escenarios del mundo real
+
+## 🔧 Prerrequisitos
+
+- Zig 0.13.0 o más reciente
+- Para pruebas de integración: Docker (opcional, para ejecutar MinIO)
+
+## 📥 Instalación
+
+Agrega el paquete a tu `build.zig.zon`:
+
+```zig
+.{
+    .name = "your-project",
+    .version = "0.1.0",
+    .dependencies = .{
+        .s3 = .{
+            .url = "https://github.com/algoflows/zig-s3/archive/v0.2.0.tar.gz",
+            // Don't forget to update hash after publishing
+            .hash = "...",
+        },
+    },
+}
+```
+
+Luego en tu `build.zig`:
+
+```zig
+const s3_dep = b.dependency("s3", .{
+    .target = target,
+    .optimize = optimize,
+});
+exe.addModule("s3", s3_dep.module("s3"));
+```
+
+## 🚀 Inicio rápido
+
+```zig
+const std = @import("std");
+const s3 = @import("s3");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    // Initialize client
+    var client = try s3.S3Client.init(allocator, .{
+        .access_key_id = "your-key",
+        .secret_access_key = "your-secret",
+        .region = "us-east-1",
+        // Optional: Use with MinIO or other S3-compatible services
+        // .endpoint = "http://localhost:9000",
+    });
+    defer client.deinit();
+
+    // Create bucket
+    try client.createBucket("my-bucket");
+
+    // Upload string content
+    var uploader = client.uploader();
+    try uploader.uploadString("my-bucket", "hello.txt", "Hello, S3!");
+}
+```
+
+## 📚 Referencia de la API
+
+### S3Client
+
+La interfaz principal del cliente para operaciones S3.
+
+```zig
+const client = try s3.S3Client.init(allocator, .{
+    .access_key_id = "your-key",
+    .secret_access_key = "your-secret",
+    .region = "us-east-1",
+    .endpoint = "http://localhost:9000", // Optional, for S3-compatible services
+});
+```
+
+### 🪣 Operaciones de Buckets
+
+- `createBucket(bucket_name: []const u8) !void`
+- `deleteBucket(bucket_name: []const u8) !void`
+- `listBuckets() ![]BucketInfo`
+
+### 📦 Operaciones de Objetos
+
+- `putObject(bucket_name: []const u8, key: []const u8, data: []const u8) !void`
+- `getObject(bucket_name: []const u8, key: []const u8) ![]const u8`
+- `deleteObject(bucket_name: []const u8, key: []const u8) !void`
+- `listObjects(bucket_name: []const u8, options: ListObjectsOptions) ![]ObjectInfo`
+
+### 📤 ObjectUploader
+
+Un asistente para subir diferentes tipos de contenido:
+
+```zig
+var uploader = client.uploader();
+
+// Upload string content
+try uploader.uploadString("my-bucket", "hello.txt", "Hello, World!");
+
+// Upload JSON data
+const data = .{ .name = "example", .value = 42 };
+try uploader.uploadJson("my-bucket", "data.json", data);
+
+// Upload file from filesystem
+try uploader.uploadFile("my-bucket", "image.jpg", "path/to/local/image.jpg");
+```
+
+## ⚠️ Manejo de errores
+
+La biblioteca utiliza el tipo unión de errores de Zig para un manejo robusto de errores:
+
+| Error Type                   | Descripción                         |
+| ---------------------------- | ----------------------------------- |
+| `S3Error.InvalidCredentials` | Credenciales de AWS inválidas             |
+| `S3Error.BucketNotFound`     | El bucket solicitado no existe      |
+| `S3Error.ObjectNotFound`     | El objeto solicitado no existe      |
+| `S3Error.ConnectionFailed`   | Problemas de red o de conexión        |
+| `S3Error.InvalidResponse`    | Respuesta inesperada del servicio S3 |
+
+## 🧪 Pruebas
+
+### Pruebas unitarias
+
+Ejecuta el conjunto de pruebas unitarias:
+
+```bash
+zig build test
+```
+
+### Pruebas de integración
+
+Las pruebas de integración requieren una instancia de MinIO en ejecución:
+
+1. Inicia MinIO:
+
+```bash
+docker run -p 9000:9000 minio/minio server /data
+```
+
+2. Ejecuta las pruebas de integración:
+
+```bash
+zig build integration-test
+```
+
+Consulta `tests/integration/README.md` para obtener información detallada sobre las pruebas de integración.
+
+## 🛠️ Desarrollo
+
+- Escrito en Zig 0.13.0
+- Utiliza solo la biblioteca estándar (sin dependencias externas)
+- Seguro en memoria con asignación y limpieza adecuadas
+- Sigue la guía de estilo de Zig y las mejores prácticas
+
+## 🤝 Contribuir
+
+1. Haz un fork del repositorio
+2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
+3. Realiza tus cambios
+4. Agrega pruebas para tus cambios
+5. Ejecuta el conjunto de pruebas
+6. Crea una solicitud de extracción (pull request)
+
+## 👥 Comunidad
+
+- 📫 Reporta problemas en [GitHub Issues](https://github.com/algoflows/zig-s3/issues)
+- 💬 Únete a las discusiones en [GitHub Discussions](https://github.com/algoflows/zig-s3/discussions)
+- 🌟 ¡Dale una estrella al repositorio si te resulta útil!
+
+## 📄 Licencia
+
+Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.
+
+## 🙏 Agradecimientos
+
+- Documentación de AWS S3
+- Documentación de MinIO
+- Biblioteca estándar de Zig