@3lineas/grooveskills 1.5.0 → 1.6.0

package/skills/env-feature-flags/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: env-feature-flags
+description: Architectural standards for fail-fast environment validation with Valibot and decoupled Feature Flags wrappers with swappable adapters (PostHog, LaunchDarkly, Unleash, In-Memory). Guarantees that applications crash at boot time on invalid config and allows toggling features without coupling code to vendor SDKs. TRIGGER when reading environment variables, structuring process.env, configuring feature flags, or running A/B experiments.
+---
+
+# Fail-Fast Environment Validation & Feature Flags Adapters
+
+Opinionated architectural standard combining **Fail-Fast Environment Schema Validation** (using Valibot) and **Feature Flags Adapters** (PostHog, LaunchDarkly, In-Memory).
+
+---
+
+## 1. Architectural Invariants
+
+1. **Fail-Fast at Startup**:
+   - Environment variables must be validated on application boot. If a required secret or URL is missing or malformed, the process exits immediately with a clean diagnostic message.
+   - Raw `process.env` is NEVER accessed directly inside business actions or controllers. All code imports the strongly typed `env` singleton.
+2. **Feature Flags as a Domain Port**:
+   - Business actions evaluate feature availability through `FeatureFlagPort`.
+   - Vendor SDKs (PostHog, LaunchDarkly, Unleash) remain isolated inside infrastructure adapters.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── config/
+│   └── env.ts                              # Fail-fast Valibot environment parser (<70 lines)
+├── domains/
+│   └── feature-flags/
+│       ├── feature-flag.port.ts            # Domain interface for flags (<40 lines)
+│       └── flag-keys.ts                    # Strongly typed flag registry (<30 lines)
+└── infrastructure/
+    └── adapters/
+        └── feature-flags/
+            ├── posthog-flags.adapter.ts    # PostHog implementation (<70 lines)
+            ├── launchdarkly-flags.adapter.ts # LaunchDarkly implementation (<70 lines)
+            └── memory-flags.adapter.ts     # In-memory testing flags fake (<50 lines)
+```
+
+---
+
+## 3. Fail-Fast Environment Config (`src/config/env.ts`)
+
+```ts
+import * as v from "valibot";
+
+const EnvSchema = v.object({
+  NODE_ENV: v.fallback(v.picklist(["development", "production", "test"]), "development"),
+  PORT: v.fallback(v.pipe(v.string(), v.transform(Number)), 3000),
+  DATABASE_URL: v.pipe(v.string(), v.url("DATABASE_URL debe ser una URL válida.")),
+  API_SECRET_KEY: v.pipe(v.string(), v.minLength(32, "API_SECRET_KEY requiere al menos 32 caracteres.")),
+});
+
+function loadEnv() {
+  const result = v.safeParse(EnvSchema, process.env);
+  if (!result.success) {
+    console.error("❌ Error fatal en variables de entorno:");
+    for (const issue of result.issues) {
+      console.error(`  - ${issue.path?.[0]?.key}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+  return result.output;
+}
+
+export const env = loadEnv();
+```
+
+---
+
+## 4. Feature Flag Port (`src/domains/feature-flags/feature-flag.port.ts`)
+
+```ts
+export type FeatureFlagKey = "new-checkout-flow" | "ai-copilot" | "export-pdf";
+
+export interface FeatureFlagEvaluationContext {
+  distinctId: string;
+  organizationId?: string;
+  properties?: Record<string, unknown>;
+}
+
+export interface FeatureFlagPort {
+  isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean>;
+  getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null>;
+}
+```
+
+---
+
+## 5. Detailed Adapters Reference
+
+For real implementations of PostHog, LaunchDarkly, and In-Memory Feature Flag adapters, see:
+- `references/env-feature-flags-examples.md`

package/skills/env-feature-flags/references/env-feature-flags-examples.md

@@ -0,0 +1,93 @@
+# Implementation Reference: Env & Feature Flag Adapters
+
+Production implementations of PostHog, LaunchDarkly, and In-Memory testing feature flag adapters.
+
+---
+
+## 1. PostHog Feature Flags Adapter (`posthog-node`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/posthog-flags.adapter.ts
+import { PostHog } from "posthog-node";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class PostHogFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: PostHog) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const res = await this.client.isFeatureEnabled(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return Boolean(res);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const variant = await this.client.getFeatureFlag(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return (variant as T) ?? null;
+  }
+}
+```
+
+---
+
+## 2. LaunchDarkly Feature Flags Adapter (`@launchdarkly/node-server-sdk`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/launchdarkly-flags.adapter.ts
+import type { LDClient } from "@launchdarkly/node-server-sdk";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class LaunchDarklyFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: LDClient) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, false);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, null);
+  }
+}
+```
+
+---
+
+## 3. In-Memory Testing Flags Adapter
+
+```ts
+// src/infrastructure/adapters/feature-flags/memory-flags.adapter.ts
+import type { FeatureFlagPort, FeatureFlagKey } from "@/domains/feature-flags/feature-flag.port";
+
+export class MemoryFeatureFlagAdapter implements FeatureFlagPort {
+  private flags = new Map<string, boolean>();
+  private variants = new Map<string, unknown>();
+
+  setFlag(key: FeatureFlagKey, enabled: boolean): void {
+    this.flags.set(key, enabled);
+  }
+
+  setVariant(key: FeatureFlagKey, variant: unknown): void {
+    this.variants.set(key, variant);
+  }
+
+  async isEnabled(key: FeatureFlagKey): Promise<boolean> {
+    return this.flags.get(key) ?? false;
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey): Promise<T | null> {
+    return (this.variants.get(key) as T) ?? null;
+  }
+}
+```

package/skills/external-service-adapters/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: external-service-adapters
+description: Standardized wrapper & adapter architecture for external third-party services (payment gateways, transactional email, SMS, storage, AI providers). Enforces pure domain ports, isolated vendor SDK wrappers, unified input/output contracts, and interchangeable adapters. TRIGGER when integrating or refactoring any external API, payment provider (Stripe, MercadoPago), email service (Resend, SES, SMTP, Cloudflare), webhook, or cloud provider.
+---
+
+# External Service Adapters & Wrappers
+
+Architectural pattern for standardizing third-party integrations (payments, emails, SMS, cloud storage, AI models) using the **Adapter Pattern** and **SDK Wrappers** to prevent vendor lock-in and keep business actions decoupled.
+
+---
+
+## 1. Architectural Distinction: Wrapper vs. Adapter
+
+| Component | Responsibility | Location | Dependencies |
+| :--- | :--- | :--- | :--- |
+| **Domain Port (Interface)** | Defines the contract needed by our business domain (pure domain types). | `src/domains/<domain>/` | Zero external SDKs |
+| **Vendor Wrapper (Client)** | Encapsulates vendor SDK initialization, raw authentication, and direct API calls. | `src/infrastructure/<vendor>/` | Vendor SDK / HTTP client |
+| **Service Adapter** | Implements the Domain Port by calling the Vendor Wrapper and translating inputs/outputs. | `src/infrastructure/adapters/` | Port + Vendor Wrapper |
+| **Business Action** | Executes use case logic depending ONLY on the Domain Port. | `src/actions/<domain>/` | Domain Port only |
+
+---
+
+## 2. The 4 Non-Negotiable Rules
+
+1. **Actions Depend on Ports, Never Vendors**:
+   - Business actions must type-hint the domain port interface (`EmailSender`, `PaymentGateway`), never `Stripe`, `Resend`, or `aws-sdk`.
+2. **Standardized Domain Contracts**:
+   - Input payloads and return values must use application domain types (e.g., `SendEmailInput`, `SendEmailResult`, `PaymentChargeResult`).
+   - Third-party SDK response shapes must never leak into actions or domain modules.
+3. **Isolate SDK Quirks in Wrappers**:
+   - HTTP errors, retries, header formatting, and API keys stay inside the vendor wrapper.
+   - Exceptions are converted into standardized application errors (`AppError`) or `ActionResponse` failures.
+4. **Interchangeability via Factory or Dependency Injection**:
+   - Swapping from `Resend` to `AWS SES` or `SMTP` requires only injecting a different adapter without altering a single line of business logic.
+
+---
+
+## 3. Directory Layout
+
+```text
+src/
+├── actions/
+│   └── billing/
+│       └── process-payment.action.ts       # Consumes PaymentGateway port (<80 lines)
+├── domains/
+│   ├── billing/
+│   │   ├── payment-gateway.port.ts         # Domain interface contract (<40 lines)
+│   │   └── billing.types.ts                # ChargeInput, ChargeResult (<50 lines)
+│   └── email/
+│       ├── email-sender.port.ts            # Domain interface contract (<40 lines)
+│       └── email.types.ts                  # SendEmailInput, SendEmailResult (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   ├── email/
+    │   │   ├── resend-email.adapter.ts     # Implements EmailSender (<80 lines)
+    │   │   ├── ses-email.adapter.ts        # Implements EmailSender (<80 lines)
+    │   │   └── smtp-email.adapter.ts       # Implements EmailSender (<80 lines)
+    │   └── payment/
+    │       ├── stripe-payment.adapter.ts   # Implements PaymentGateway (<90 lines)
+    │       └── mercadopago-payment.adapter.ts # Implements PaymentGateway (<90 lines)
+    └── wrappers/
+        ├── aws/
+        │   └── ses-client.wrapper.ts       # Raw AWS SES client wrapper (<70 lines)
+        ├── resend/
+        │   └── resend-client.wrapper.ts    # Raw Resend SDK wrapper (<60 lines)
+        └── stripe/
+            └── stripe-client.wrapper.ts    # Raw Stripe SDK wrapper (<60 lines)
+```
+
+---
+
+## 4. Implementation Blueprint (Email Example)
+
+### Step 1: Pure Domain Port (`src/domains/email/email-sender.port.ts`)
+```ts
+export interface SendEmailPayload {
+  to: string | string[];
+  subject: string;
+  htmlContent: string;
+  from?: string;
+  replyTo?: string;
+}
+
+export interface SendEmailOutput {
+  id: string;
+  delivered: boolean;
+  timestamp: Date;
+}
+
+export interface EmailSenderPort {
+  sendEmail(payload: SendEmailPayload): Promise<SendEmailOutput>;
+}
+```
+
+### Step 2: Vendor Wrapper (`src/infrastructure/wrappers/resend/resend.wrapper.ts`)
+```ts
+import { Resend } from "resend";
+
+export class ResendWrapper {
+  private readonly client: Resend;
+
+  constructor(apiKey: string) {
+    this.client = new Resend(apiKey);
+  }
+
+  async send(params: { from: string; to: string[]; subject: string; html: string }) {
+    return this.client.emails.send(params);
+  }
+}
+```
+
+### Step 3: Domain Adapter (`src/infrastructure/adapters/email/resend-email.adapter.ts`)
+```ts
+import type { EmailSenderPort, SendEmailPayload, SendEmailOutput } from "@/domains/email/email-sender.port";
+import type { ResendWrapper } from "@/infrastructure/wrappers/resend/resend.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class ResendEmailAdapter implements EmailSenderPort {
+  constructor(
+    private readonly wrapper: ResendWrapper,
+    private readonly defaultFrom: string
+  ) {}
+
+  async sendEmail(payload: SendEmailPayload): Promise<SendEmailOutput> {
+    const recipients = Array.isArray(payload.to) ? payload.to : [payload.to];
+    const { data, error } = await this.wrapper.send({
+      from: payload.from ?? this.defaultFrom,
+      to: recipients,
+      subject: payload.subject,
+      html: payload.htmlContent,
+    });
+
+    if (error || !data) {
+      throw new AppError({
+        message: `Error al enviar correo vía Resend: ${error?.message ?? "desconocido"}`,
+        statusCode: 502,
+      });
+    }
+
+    return { id: data.id, delivered: true, timestamp: new Date() };
+  }
+}
+```
+
+---
+
+## 5. Reference Guides
+- Detailed concrete implementations for **Email** (SMTP, Resend, AWS SES, Cloudflare Email) and **Payment Gateways** (Stripe, MercadoPago) can be found in `references/email-and-payment-examples.md`.

package/skills/external-service-adapters/references/email-and-payment-examples.md

@@ -0,0 +1,198 @@
+# Implementation Reference: Email & Payment Adapters
+
+Reference implementations illustrating the Wrapper + Adapter pattern across email providers and payment gateways with strict typing and guard clauses.
+
+---
+
+## 1. Transactional Email System
+
+### 1.1 Pure Domain Port (`src/domains/email/email-sender.port.ts`)
+```ts
+export interface EmailRecipient {
+  email: string;
+  name?: string;
+}
+
+export interface SendEmailInput {
+  to: EmailRecipient[];
+  subject: string;
+  html: string;
+  text?: string;
+  from?: EmailRecipient;
+  replyTo?: string;
+}
+
+export interface SendEmailResult {
+  messageId: string;
+  provider: "smtp" | "resend" | "aws-ses" | "cloudflare";
+  sentAt: Date;
+}
+
+export interface EmailSenderPort {
+  send(input: SendEmailInput): Promise<SendEmailResult>;
+}
+```
+
+### 1.2 SMTP Adapter (`nodemailer`)
+```ts
+// src/infrastructure/adapters/email/smtp-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { SmtpWrapper } from "@/infrastructure/wrappers/smtp/smtp.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class SmtpEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: SmtpWrapper, private defaultSender: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    try {
+      const from = input.from ? `${input.from.name ?? ""} <${input.from.email}>`.trim() : this.defaultSender;
+      const info = await this.wrapper.sendMail({
+        from,
+        to: input.to.map((r) => r.email).join(", "),
+        subject: input.subject,
+        html: input.html,
+        text: input.text,
+      });
+      return { messageId: info.messageId, provider: "smtp", sentAt: new Date() };
+    } catch (err) {
+      throw new AppError({ message: "Fallo al enviar correo SMTP.", statusCode: 502, cause: err });
+    }
+  }
+}
+```
+
+### 1.3 AWS SES Adapter (`@aws-sdk/client-ses`)
+```ts
+// src/infrastructure/adapters/email/ses-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { SesWrapper } from "@/infrastructure/wrappers/aws/ses.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class SesEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: SesWrapper, private defaultSource: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const res = await this.wrapper.send({
+      Source: input.from?.email ?? this.defaultSource,
+      Destination: { ToAddresses: input.to.map((t) => t.email) },
+      Message: {
+        Subject: { Data: input.subject, Charset: "UTF-8" },
+        Body: { Html: { Data: input.html, Charset: "UTF-8" } },
+      },
+    });
+
+    if (!res.MessageId) {
+      throw new AppError({ message: "Fallo al enviar correo con AWS SES.", statusCode: 502 });
+    }
+    return { messageId: res.MessageId, provider: "aws-ses", sentAt: new Date() };
+  }
+}
+```
+
+### 1.4 Cloudflare Email Routing Adapter
+```ts
+// src/infrastructure/adapters/email/cloudflare-email.adapter.ts
+import type { EmailSenderPort, SendEmailInput, SendEmailResult } from "@/domains/email/email-sender.port";
+import type { CloudflareEmailWrapper } from "@/infrastructure/wrappers/cloudflare/cloudflare-email.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class CloudflareEmailAdapter implements EmailSenderPort {
+  constructor(private wrapper: CloudflareEmailWrapper, private defaultSender: string) {}
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const res = await this.wrapper.postEmail({
+      from: input.from?.email ?? this.defaultSender,
+      to: input.to.map((t) => t.email),
+      subject: input.subject,
+      content: input.html,
+    });
+    if (!res.ok) {
+      throw new AppError({ message: "Error al enviar correo con Cloudflare Email.", statusCode: 502 });
+    }
+    const data = await res.json() as { result?: { id?: string } };
+    return { messageId: data.result?.id ?? `cf_${Date.now()}`, provider: "cloudflare", sentAt: new Date() };
+  }
+}
+```
+
+---
+
+## 2. Payment Gateways (Stripe & MercadoPago)
+
+### 2.1 Domain Port (`src/domains/billing/payment-gateway.port.ts`)
+```ts
+export interface ChargeInput {
+  amountInCents: number;
+  currency: "usd" | "clp" | "mxn" | "eur";
+  customerId: string;
+  sourceToken?: string;
+  idempotencyKey: string;
+}
+
+export interface ChargeResult {
+  transactionId: string;
+  status: "succeeded" | "pending" | "failed";
+  provider: "stripe" | "mercadopago";
+}
+
+export interface PaymentGatewayPort {
+  createCharge(input: ChargeInput): Promise<ChargeResult>;
+}
+```
+
+### 2.2 Stripe & MercadoPago Adapters
+```ts
+// src/infrastructure/adapters/payment/stripe-payment.adapter.ts
+import type { PaymentGatewayPort, ChargeInput, ChargeResult } from "@/domains/billing/payment-gateway.port";
+import type Stripe from "stripe";
+import { AppError } from "@/errors/app-error";
+
+export class StripePaymentAdapter implements PaymentGatewayPort {
+  constructor(private stripe: Stripe) {}
+
+  async createCharge(input: ChargeInput): Promise<ChargeResult> {
+    try {
+      const intent = await this.stripe.paymentIntents.create(
+        { amount: input.amountInCents, currency: input.currency, customer: input.customerId, confirm: true },
+        { idempotencyKey: input.idempotencyKey }
+      );
+      return {
+        transactionId: intent.id,
+        status: intent.status === "succeeded" ? "succeeded" : "pending",
+        provider: "stripe",
+      };
+    } catch (err) {
+      throw new AppError({ message: "Fallo en Stripe.", statusCode: 402, cause: err });
+    }
+  }
+}
+```
+```ts
+// src/infrastructure/adapters/payment/mercadopago-payment.adapter.ts
+import type { PaymentGatewayPort, ChargeInput, ChargeResult } from "@/domains/billing/payment-gateway.port";
+import { Payment, type MercadoPagoConfig } from "mercadopago";
+import { AppError } from "@/errors/app-error";
+
+export class MercadoPagoPaymentAdapter implements PaymentGatewayPort {
+  private client: Payment;
+  constructor(cfg: MercadoPagoConfig) {
+    this.client = new Payment(cfg);
+  }
+
+  async createCharge(input: ChargeInput): Promise<ChargeResult> {
+    try {
+      const res = await this.client.create({
+        body: { transaction_amount: input.amountInCents / 100, token: input.sourceToken, payer: { id: input.customerId } },
+        requestOptions: { idempotencyKey: input.idempotencyKey },
+      });
+      return {
+        transactionId: String(res.id),
+        status: res.status === "approved" ? "succeeded" : "pending",
+        provider: "mercadopago",
+      };
+    } catch (err) {
+      throw new AppError({ message: "Fallo en MercadoPago.", statusCode: 402, cause: err });
+    }
+  }
+}
+```

package/skills/storage-file-adapters/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: storage-file-adapters
+description: Standardized wrapper & adapter architecture for object storage, uploads, presigned URLs, and streaming (AWS S3, Cloudflare R2, Supabase Storage, In-Memory). Discards repository abstractions in favor of direct ports and isolated vendor clients. TRIGGER when implementing file uploads, asset storage, cloud buckets, multipart uploads, or presigned download/upload URLs.
+---
+
+# Object Storage & File Adapters (Wrappers + Ports)
+
+Opinionated architectural pattern for object storage and file management (AWS S3, Cloudflare R2, Supabase Storage, In-Memory) utilizing the **Wrapper + Adapter** pattern instead of generic repositories.
+
+---
+
+## 1. Core Principles
+
+1. **Storage is an I/O Port, Not a Repository**:
+   - Files are blobs with metadata and URLs, not relational entities. We define `StoragePort`, not `FileRepository`.
+2. **Standardized Domain Payload**:
+   - Operations consume and return pure domain contracts (`PutFileInput`, `PutFileOutput`, `PresignedUrlInput`).
+   - Vendor response shapes (S3 `PutObjectCommandOutput`, Supabase `StorageError`) never escape the adapter boundary.
+3. **Vendor Wrappers Isolate Credentials & SDK Quirks**:
+   - SDK clients, endpoint URLs, region configs, and multipart batching logic remain strictly inside `src/infrastructure/wrappers/storage/`.
+4. **Zero-Change Provider Portability**:
+   - Switching between AWS S3, Cloudflare R2, Supabase Storage, or an In-Memory mock during local testing requires swapping only the adapter instance.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── actions/
+│   └── media/
+│       └── upload-avatar.action.ts         # Consumes StoragePort (<80 lines)
+├── domains/
+│   └── storage/
+│       ├── storage.port.ts                 # Domain interface contract (<50 lines)
+│       └── storage.types.ts                # Pure domain payloads (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   └── storage/
+    │       ├── s3-storage.adapter.ts       # AWS S3 implementation (<90 lines)
+    │       ├── r2-storage.adapter.ts       # Cloudflare R2 implementation (<90 lines)
+    │       ├── supabase-storage.adapter.ts # Supabase Storage implementation (<90 lines)
+    │       └── memory-storage.adapter.ts   # In-memory testing adapter (<70 lines)
+    └── wrappers/
+        └── storage/
+            ├── s3-client.wrapper.ts        # AWS SDK client wrapper (<70 lines)
+            ├── r2-client.wrapper.ts        # Cloudflare S3-compatible client (<70 lines)
+            └── supabase-storage.wrapper.ts # Supabase storage client (<60 lines)
+```
+
+---
+
+## 3. Implementation Contract (`src/domains/storage/storage.port.ts`)
+
+```ts
+export interface StorageFile {
+  buffer: Uint8Array | Buffer;
+  contentType: string;
+  sizeBytes: number;
+}
+
+export interface PutFileInput {
+  bucket: string;
+  key: string;
+  file: StorageFile;
+  isPublic?: boolean;
+}
+
+export interface PutFileOutput {
+  key: string;
+  bucket: string;
+  publicUrl?: string;
+  etag?: string;
+}
+
+export interface PresignedUrlInput {
+  bucket: string;
+  key: string;
+  operation: "getObject" | "putObject";
+  expiresInSeconds: number;
+}
+
+export interface StoragePort {
+  putFile(input: PutFileInput): Promise<PutFileOutput>;
+  getFile(bucket: string, key: string): Promise<StorageFile>;
+  deleteFile(bucket: string, key: string): Promise<void>;
+  createPresignedUrl(input: PresignedUrlInput): Promise<string>;
+}
+```
+
+---
+
+## 4. Usage in Business Actions
+
+```ts
+import type { StoragePort } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export async function uploadAvatarAction(
+  storage: StoragePort,
+  userId: string,
+  rawFile: Uint8Array,
+  mimeType: string
+): Promise<{ avatarUrl: string }> {
+  if (rawFile.byteLength > 5 * 1024 * 1024) {
+    throw new AppError({ message: "La imagen excede el límite de 5 MB.", statusCode: 400 });
+  }
+
+  const result = await storage.putFile({
+    bucket: "avatars",
+    key: `users/${userId}/avatar.webp`,
+    file: { buffer: rawFile, contentType: mimeType, sizeBytes: rawFile.byteLength },
+    isPublic: true,
+  });
+
+  return { avatarUrl: result.publicUrl ?? result.key };
+}
+```
+
+---
+
+## 5. Detailed Provider Blueprints
+
+For complete production adapters (AWS S3, Cloudflare R2, Supabase Storage, and In-Memory testing fake), consult:
+- `references/storage-adapters-examples.md`