@3lineas/grooveskills 1.5.0 → 1.7.0

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`

package/skills/storage-file-adapters/references/storage-adapters-examples.md

@@ -0,0 +1,164 @@
+# Implementation Reference: Object Storage & File Adapters
+
+Reference implementations for S3, Cloudflare R2, Supabase Storage, and In-Memory testing fake under the Wrapper + Adapter architecture.
+
+---
+
+## 1. AWS S3 Adapter (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`)
+
+```ts
+// src/infrastructure/adapters/storage/s3-storage.adapter.ts
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class S3StorageAdapter implements StoragePort {
+  constructor(private client: S3Client, private publicBaseUrl?: string) {}
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    try {
+      const res = await this.client.send(
+        new PutObjectCommand({
+          Bucket: input.bucket,
+          Key: input.key,
+          Body: input.file.buffer,
+          ContentType: input.file.contentType,
+        })
+      );
+      const publicUrl = this.publicBaseUrl ? `${this.publicBaseUrl.replace(/\/$/, "")}/${input.key}` : undefined;
+      return { key: input.key, bucket: input.bucket, publicUrl, etag: res.ETag };
+    } catch (err) {
+      throw new AppError({ message: "Error al subir archivo a S3.", statusCode: 502, cause: err });
+    }
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const res = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    const bytes = await res.Body?.transformToByteArray();
+    if (!bytes) {
+      throw new AppError({ message: "Archivo no encontrado o vacío.", statusCode: 404 });
+    }
+    return { buffer: bytes, contentType: res.ContentType ?? "application/octet-stream", sizeBytes: res.ContentLength ?? bytes.byteLength };
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    const Command = input.operation === "getObject" ? GetObjectCommand : PutObjectCommand;
+    return getSignedUrl(this.client, new Command({ Bucket: input.bucket, Key: input.key }), { expiresIn: input.expiresInSeconds });
+  }
+}
+```
+
+---
+
+## 2. Cloudflare R2 Adapter (S3-Compatible)
+
+```ts
+// src/infrastructure/adapters/storage/r2-storage.adapter.ts
+import { S3Client } from "@aws-sdk/client-s3";
+import { S3StorageAdapter } from "./s3-storage.adapter";
+
+export function createR2StorageAdapter(accountId: string, accessKeyId: string, secretAccessKey: string, publicUrl?: string) {
+  const client = new S3Client({
+    region: "auto",
+    endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+    credentials: { accessKeyId, secretAccessKey },
+  });
+  return new S3StorageAdapter(client, publicUrl);
+}
+```
+
+---
+
+## 3. Supabase Storage Adapter (`@supabase/storage-js`)
+
+```ts
+// src/infrastructure/adapters/storage/supabase-storage.adapter.ts
+import type { StorageClient } from "@supabase/storage-js";
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class SupabaseStorageAdapter implements StoragePort {
+  constructor(private client: StorageClient) {}
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    const { data, error } = await this.client.from(input.bucket).upload(input.key, input.file.buffer, {
+      contentType: input.file.contentType,
+      upsert: true,
+    });
+    if (error || !data) {
+      throw new AppError({ message: "Error al almacenar archivo en Supabase.", statusCode: 502, cause: error });
+    }
+    const publicUrl = input.isPublic ? this.client.from(input.bucket).getPublicUrl(input.key).data.publicUrl : undefined;
+    return { key: input.key, bucket: input.bucket, publicUrl };
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const { data, error } = await this.client.from(bucket).download(key);
+    if (error || !data) {
+      throw new AppError({ message: "Archivo no encontrado.", statusCode: 404, cause: error });
+    }
+    const buffer = new Uint8Array(await data.arrayBuffer());
+    return { buffer, contentType: data.type || "application/octet-stream", sizeBytes: buffer.byteLength };
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    const { error } = await this.client.from(bucket).remove([key]);
+    if (error) {
+      throw new AppError({ message: "Error al eliminar archivo en Supabase.", statusCode: 502, cause: error });
+    }
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    if (input.operation !== "getObject") {
+      throw new AppError({ message: "Operación de presigned URL no soportada.", statusCode: 400 });
+    }
+    const { data, error } = await this.client.from(input.bucket).createSignedUrl(input.key, input.expiresInSeconds);
+    if (error || !data?.signedUrl) {
+      throw new AppError({ message: "No se pudo generar URL firmada.", statusCode: 502, cause: error });
+    }
+    return data.signedUrl;
+  }
+}
+```
+
+---
+
+## 4. In-Memory Storage Adapter (Testing Fake)
+
+```ts
+// src/infrastructure/adapters/storage/memory-storage.adapter.ts
+import type { StoragePort, PutFileInput, PutFileOutput, StorageFile, PresignedUrlInput } from "@/domains/storage/storage.port";
+import { AppError } from "@/errors/app-error";
+
+export class MemoryStorageAdapter implements StoragePort {
+  private files = new Map<string, StorageFile>();
+
+  private keyOf(bucket: string, key: string): string {
+    return `${bucket}:${key}`;
+  }
+
+  async putFile(input: PutFileInput): Promise<PutFileOutput> {
+    this.files.set(this.keyOf(input.bucket, input.key), input.file);
+    return { key: input.key, bucket: input.bucket, publicUrl: `https://mock.storage/${input.key}` };
+  }
+
+  async getFile(bucket: string, key: string): Promise<StorageFile> {
+    const file = this.files.get(this.keyOf(bucket, key));
+    if (!file) throw new AppError({ message: "Archivo inexistente en memoria.", statusCode: 404 });
+    return file;
+  }
+
+  async deleteFile(bucket: string, key: string): Promise<void> {
+    this.files.delete(this.keyOf(bucket, key));
+  }
+
+  async createPresignedUrl(input: PresignedUrlInput): Promise<string> {
+    return `https://mock.storage/presigned/${input.bucket}/${input.key}?expires=${input.expiresInSeconds}`;
+  }
+}
+```