@jordanalec/dtk 1.0.0

package/templates/plugins/aws-dynamo/example.ts

@@ -0,0 +1,75 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .dynamo({
+    region: process.env.AWS_REGION!,
+  })
+  .step("create-item", async (ctx) => {
+    const result = await ctx.services.dynamo.putItem(
+      process.env.DYNAMO_TABLE_NAME!,
+      {
+        id: "user-123",
+        name: "John Doe",
+        email: "john@example.com",
+        timestamp: new Date().toISOString(),
+      }
+    );
+    console.log("Item created:", result);
+    return result;
+  })
+  .step("retrieve-item", async (ctx) => {
+    const result = await ctx.services.dynamo.getItem(
+      process.env.DYNAMO_TABLE_NAME!,
+      { id: "user-123" }
+    );
+    console.log("Item retrieved:", result);
+    return result;
+  })
+  .step("update-item", async (ctx) => {
+    const result = await ctx.services.dynamo.updateItem(
+      process.env.DYNAMO_TABLE_NAME!,
+      { id: "user-123" },
+      {
+        UpdateExpression: "SET #n = :n, #e = :e",
+        ExpressionAttributeNames: { "#n": "name", "#e": "email" },
+        ExpressionAttributeValues: {
+          ":n": { S: "Jane Doe" },
+          ":e": { S: "jane@example.com" },
+        },
+      }
+    );
+    console.log("Item updated:", result);
+    return result;
+  })
+  .step("query-items", async (ctx) => {
+    const result = await ctx.services.dynamo.queryItems(
+      process.env.DYNAMO_TABLE_NAME!,
+      {
+        KeyConditionExpression: "#pk = :pk",
+        ExpressionAttributeNames: { "#pk": "id" },
+        ExpressionAttributeValues: { ":pk": { S: "user-123" } },
+      }
+    );
+    console.log("Items found:", result.count);
+    console.log("Items:", result.items);
+    return result;
+  })
+  .step("scan-items", async (ctx) => {
+    const result = await ctx.services.dynamo.scanItems(
+      process.env.DYNAMO_TABLE_NAME!,
+      { Limit: 10 }
+    );
+    console.log("Items scanned:", result.count);
+    console.log("Items:", result.items);
+    return result;
+  })
+  .step("delete-item", async (ctx) => {
+    const result = await ctx.services.dynamo.deleteItem(
+      process.env.DYNAMO_TABLE_NAME!,
+      { id: "user-123" }
+    );
+    console.log("Item deleted:", result);
+    return result;
+  })
+  .run("throwOnError");

package/templates/plugins/aws-dynamo/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "aws-dynamo",
+  "description": "AWS DynamoDB -- create and query items in DynamoDB tables",
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.300.0",
+    "@aws-sdk/util-dynamodb": "^3.300.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/dynamo.ts" },
+    { "src": "types.ts", "dest": "src/types/aws-dynamo.ts" },
+    { "src": "service.test.ts", "dest": "src/services/dynamo.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/aws-dynamo.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./dynamo.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createDynamoService } from \"./services/dynamo.js\";",
+        "import type { DynamoConfig } from \"./types/aws-dynamo.js\";"
+      ],
+      "configs": "  private dynamoConfig?: DynamoConfig;",
+      "methods": "  dynamo(config: DynamoConfig): this { this.dynamoConfig = config; return this; }",
+      "services": "        dynamo: createDynamoService(this.dynamoConfig),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { DynamoConfig, PutItemResult, GetItemResult, QueryResult, DeleteItemResult, UpdateItemResult } from \"./aws-dynamo.js\";",
+      "service-types": "    dynamo: { putItem(tableName: string, item: Record<string, any>): Promise<PutItemResult>; getItem(tableName: string, key: Record<string, any>): Promise<GetItemResult>; queryItems(tableName: string, params: Record<string, any>): Promise<QueryResult>; updateItem(tableName: string, key: Record<string, any>, params: Record<string, any>): Promise<UpdateItemResult>; deleteItem(tableName: string, key: Record<string, any>): Promise<DeleteItemResult>; scanItems(tableName: string, params?: Record<string, any>): Promise<QueryResult>; };"
+    }
+  }
+}

package/templates/plugins/aws-dynamo/service.test.ts

@@ -0,0 +1,180 @@
+import { createDynamoService } from './service.js';
+
+jest.mock('@aws-sdk/client-dynamodb');
+jest.mock('@aws-sdk/util-dynamodb');
+import { DynamoDBClient, PutItemCommand, GetItemCommand, QueryCommand, DeleteItemCommand, ScanCommand, UpdateItemCommand } from '@aws-sdk/client-dynamodb';
+import type { QueryCommandInput, ScanCommandInput, UpdateItemCommandInput } from '@aws-sdk/client-dynamodb';
+import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
+
+const mockSend = jest.fn();
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (DynamoDBClient as jest.Mock).mockImplementation(() => ({ send: mockSend }));
+  (marshall as jest.Mock).mockImplementation((obj) => obj);
+  (unmarshall as jest.Mock).mockImplementation((obj) => obj);
+});
+
+describe('createDynamoService', () => {
+  const config = { region: 'us-east-1' };
+
+  describe('putItem', () => {
+    it('sends a PutItemCommand with the table name and marshalled item', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const item = { id: 'abc', name: 'test' };
+      await dynamo.putItem('my-table', item);
+      const commandArg = (PutItemCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.Item).toEqual(item);
+    });
+
+    it('returns success with the table name and item field count', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.putItem('my-table', { id: '1', name: 'test' });
+      expect(result).toEqual({ success: true, tableName: 'my-table', itemCount: 2 });
+    });
+
+  });
+
+  describe('getItem', () => {
+    it('sends a GetItemCommand with the table name and marshalled key', async () => {
+      mockSend.mockResolvedValue({ Item: { id: 'abc' } });
+      const dynamo = createDynamoService(config);
+      await dynamo.getItem('my-table', { id: 'abc' });
+      const commandArg = (GetItemCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.Key).toEqual({ id: 'abc' });
+    });
+
+    it('returns the unmarshalled item and found: true when item exists', async () => {
+      const rawItem = { id: 'abc', name: 'test' };
+      mockSend.mockResolvedValue({ Item: rawItem });
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.getItem('my-table', { id: 'abc' });
+      expect(result).toEqual({ item: rawItem, found: true });
+    });
+
+    it('returns null and found: false when item does not exist', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.getItem('my-table', { id: 'missing' });
+      expect(result).toEqual({ item: null, found: false });
+    });
+
+  });
+
+  describe('queryItems', () => {
+    const params: Omit<QueryCommandInput, 'TableName'> = {
+      KeyConditionExpression: '#pk = :pk',
+      ExpressionAttributeNames: { '#pk': 'userId' },
+      ExpressionAttributeValues: { ':pk': { S: 'user-123' } },
+    };
+
+    it('sends a QueryCommand with the table name and provided params', async () => {
+      mockSend.mockResolvedValue({ Items: [] });
+      const dynamo = createDynamoService(config);
+      await dynamo.queryItems('my-table', params);
+      const commandArg = (QueryCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.KeyConditionExpression).toBe('#pk = :pk');
+    });
+
+    it('returns unmarshalled items and count', async () => {
+      const raw = [{ userId: 'user-123', sk: 'order-1' }];
+      mockSend.mockResolvedValue({ Items: raw });
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.queryItems('my-table', params);
+      expect(result).toEqual({ items: raw, count: 1 });
+    });
+
+    it('returns empty items when response has no Items', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.queryItems('my-table', params);
+      expect(result).toEqual({ items: [], count: 0 });
+    });
+
+  });
+
+  describe('updateItem', () => {
+    const key = { id: 'abc' };
+    const params: Omit<UpdateItemCommandInput, 'TableName' | 'Key'> = {
+      UpdateExpression: 'SET #n = :n',
+      ExpressionAttributeNames: { '#n': 'name' },
+      ExpressionAttributeValues: { ':n': { S: 'Jane Doe' } },
+    };
+
+    it('sends an UpdateItemCommand with the table name, marshalled key, and params', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      await dynamo.updateItem('my-table', key, params);
+      const commandArg = (UpdateItemCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.Key).toEqual(key);
+      expect(commandArg.UpdateExpression).toBe('SET #n = :n');
+    });
+
+    it('returns success and the table name', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.updateItem('my-table', key, params);
+      expect(result).toEqual({ success: true, tableName: 'my-table' });
+    });
+
+  });
+
+  describe('deleteItem', () => {
+    it('sends a DeleteItemCommand with the table name and marshalled key', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      await dynamo.deleteItem('my-table', { id: 'abc' });
+      const commandArg = (DeleteItemCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.Key).toEqual({ id: 'abc' });
+    });
+
+    it('returns success and the table name', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.deleteItem('my-table', { id: 'abc' });
+      expect(result).toEqual({ success: true, tableName: 'my-table' });
+    });
+
+  });
+
+  describe('scanItems', () => {
+    it('sends a ScanCommand with the table name and provided params', async () => {
+      mockSend.mockResolvedValue({ Items: [] });
+      const dynamo = createDynamoService(config);
+      const scanParams: Omit<ScanCommandInput, 'TableName'> = { Limit: 10 };
+      await dynamo.scanItems('my-table', scanParams);
+      const commandArg = (ScanCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.TableName).toBe('my-table');
+      expect(commandArg.Limit).toBe(10);
+    });
+
+    it('returns unmarshalled items and count', async () => {
+      const raw = [{ id: 'a' }, { id: 'b' }];
+      mockSend.mockResolvedValue({ Items: raw });
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.scanItems('my-table');
+      expect(result).toEqual({ items: raw, count: 2 });
+    });
+
+    it('returns empty items when response has no Items', async () => {
+      mockSend.mockResolvedValue({});
+      const dynamo = createDynamoService(config);
+      const result = await dynamo.scanItems('my-table');
+      expect(result).toEqual({ items: [], count: 0 });
+    });
+
+  });
+
+  it('throws error when a method is called without config', async () => {
+    const dynamo = createDynamoService();
+    await expect(dynamo.putItem('my-table', { id: '1' })).rejects.toThrow('dynamo service is not configured');
+  });
+
+});

package/templates/plugins/aws-dynamo/service.ts

@@ -0,0 +1,73 @@
+import { DynamoDBClient, PutItemCommand, GetItemCommand, QueryCommand, DeleteItemCommand, ScanCommand, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
+import type { QueryCommandInput, ScanCommandInput, UpdateItemCommandInput } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import type { DynamoConfig, PutItemResult, GetItemResult, QueryResult, DeleteItemResult, UpdateItemResult } from "./types.js";
+
+export function createDynamoService(config?: DynamoConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("dynamo service is not configured -- call .dynamo(config) on the suite");
+  };
+  const client = config ? new DynamoDBClient({ region: config.region }) : null;
+
+  return {
+    putItem: async (tableName: string, item: Record<string, any>): Promise<PutItemResult> => {
+      ensureConfig();
+      const marshalledItem = marshall(item);
+      await client!.send(
+        new PutItemCommand({
+          TableName: tableName,
+          Item: marshalledItem,
+        })
+      );
+      return {
+        success: true,
+        tableName,
+        itemCount: Object.keys(item).length,
+      };
+    },
+
+    getItem: async (tableName: string, key: Record<string, any>): Promise<GetItemResult> => {
+      ensureConfig();
+      const marshalledKey = marshall(key);
+      const response = await client!.send(
+        new GetItemCommand({
+          TableName: tableName,
+          Key: marshalledKey,
+        })
+      );
+
+      if (!response.Item) {
+        return { item: null, found: false };
+      }
+
+      const unmarshalledItem = unmarshall(response.Item);
+      return { item: unmarshalledItem, found: true };
+    },
+
+    queryItems: async (tableName: string, params: Omit<QueryCommandInput, 'TableName'>): Promise<QueryResult> => {
+      ensureConfig();
+      const response = await client!.send(new QueryCommand({ TableName: tableName, ...params }));
+      const items = (response.Items ?? []).map((item) => unmarshall(item));
+      return { items, count: items.length };
+    },
+
+    deleteItem: async (tableName: string, key: Record<string, any>): Promise<DeleteItemResult> => {
+      ensureConfig();
+      await client!.send(new DeleteItemCommand({ TableName: tableName, Key: marshall(key) }));
+      return { success: true, tableName };
+    },
+
+    updateItem: async (tableName: string, key: Record<string, any>, params: Omit<UpdateItemCommandInput, 'TableName' | 'Key'>): Promise<UpdateItemResult> => {
+      ensureConfig();
+      await client!.send(new UpdateItemCommand({ TableName: tableName, Key: marshall(key), ...params }));
+      return { success: true, tableName };
+    },
+
+    scanItems: async (tableName: string, params: Omit<ScanCommandInput, 'TableName'> = {}): Promise<QueryResult> => {
+      ensureConfig();
+      const response = await client!.send(new ScanCommand({ TableName: tableName, ...params }));
+      const items = (response.Items ?? []).map((item) => unmarshall(item));
+      return { items, count: items.length };
+    },
+  };
+}

package/templates/plugins/aws-dynamo/types.ts

@@ -0,0 +1,29 @@
+export interface DynamoConfig {
+  region: string;
+}
+
+export interface PutItemResult {
+  success: boolean;
+  tableName: string;
+  itemCount: number;
+}
+
+export interface GetItemResult {
+  item: Record<string, any> | null;
+  found: boolean;
+}
+
+export interface QueryResult {
+  items: Record<string, any>[];
+  count: number;
+}
+
+export interface DeleteItemResult {
+  success: boolean;
+  tableName: string;
+}
+
+export interface UpdateItemResult {
+  success: boolean;
+  tableName: string;
+}

package/templates/plugins/aws-s3/env.txt

@@ -0,0 +1,2 @@
+S3_BUCKET_NAME=
+AWS_REGION=

package/templates/plugins/aws-s3/example.ts

@@ -0,0 +1,41 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .s3({
+    region: process.env.AWS_REGION!,
+  })
+  .step("upload-file", async (ctx) => {
+    const result = await ctx.services.s3.uploadFile(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      "./example.txt",
+      {
+        contentType: "text/plain",
+        metadata: { source: "dtk-example" },
+      }
+    );
+    console.log("Uploaded:", result);
+    return result;
+  })
+  .step("get-presigned-url", async (ctx) => {
+    const result = await ctx.services.s3.getPresignedUrl(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      300
+    );
+    console.log("Presigned URL:", result.url);
+    console.log("Expires in:", result.expiresIn, "seconds");
+    return result;
+  })
+  .step("download-file", async (ctx) => {
+    const result = await ctx.services.s3.downloadFile(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      "./downloaded-example.txt"
+    );
+    console.log("Downloaded to:", result.localPath);
+    console.log("Content type:", result.contentType);
+    return result;
+  })
+  .run("throwOnError");

package/templates/plugins/aws-s3/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "aws-s3",
+  "description": "AWS S3 -- upload files, download files, and generate presigned URLs",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.300.0",
+    "@aws-sdk/s3-request-presigner": "^3.300.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/s3.ts" },
+    { "src": "types.ts", "dest": "src/types/aws-s3.ts" },
+    { "src": "service.test.ts", "dest": "src/services/s3.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/aws-s3.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./s3.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createS3Service } from \"./services/s3.js\";",
+        "import type { S3Config } from \"./types/aws-s3.js\";"
+      ],
+      "configs": "  private s3Config?: S3Config;",
+      "methods": "  s3(config: S3Config): this { this.s3Config = config; return this; }",
+      "services": "        s3: createS3Service(this.s3Config),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { S3Config, UploadOptions, UploadFileResult, DownloadFileResult, PresignedUrlResult } from \"./aws-s3.js\";",
+      "service-types": "    s3: { uploadFile(bucket: string, key: string, filePath: string, options?: UploadOptions): Promise<UploadFileResult>; downloadFile(bucket: string, key: string, localPath: string): Promise<DownloadFileResult>; getPresignedUrl(bucket: string, key: string, expiresIn?: number): Promise<PresignedUrlResult>; };"
+    }
+  }
+}

package/templates/plugins/aws-s3/service.test.ts

@@ -0,0 +1,150 @@
+import { createS3Service } from './service.js';
+
+jest.mock('@aws-sdk/client-s3');
+jest.mock('@aws-sdk/s3-request-presigner');
+jest.mock('fs/promises');
+
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { readFile, writeFile } from 'fs/promises';
+
+const mockSend = jest.fn();
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (S3Client as jest.Mock).mockImplementation(() => ({ send: mockSend }));
+});
+
+describe('createS3Service', () => {
+  const config = { region: 'us-east-1' };
+
+  describe('uploadFile', () => {
+    it('reads the local file and sends a PutObjectCommand with bucket, key, and body', async () => {
+      const fileContent = Buffer.from('hello world');
+      (readFile as jest.Mock).mockResolvedValue(fileContent);
+      mockSend.mockResolvedValue({ ETag: '"abc123"' });
+      const s3 = createS3Service(config);
+      await s3.uploadFile('my-bucket', 'uploads/file.txt', './file.txt');
+      const commandArg = (PutObjectCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.Bucket).toBe('my-bucket');
+      expect(commandArg.Key).toBe('uploads/file.txt');
+      expect(commandArg.Body).toBe(fileContent);
+    });
+
+    it('includes ContentType when provided in options', async () => {
+      (readFile as jest.Mock).mockResolvedValue(Buffer.from(''));
+      mockSend.mockResolvedValue({ ETag: '"abc123"' });
+      const s3 = createS3Service(config);
+      await s3.uploadFile('my-bucket', 'key', './file.txt', { contentType: 'text/plain' });
+      const commandArg = (PutObjectCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.ContentType).toBe('text/plain');
+    });
+
+    it('includes Metadata when provided in options', async () => {
+      (readFile as jest.Mock).mockResolvedValue(Buffer.from(''));
+      mockSend.mockResolvedValue({ ETag: '"abc123"' });
+      const s3 = createS3Service(config);
+      await s3.uploadFile('my-bucket', 'key', './file.txt', { metadata: { source: 'dtk' } });
+      const commandArg = (PutObjectCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.Metadata).toEqual({ source: 'dtk' });
+    });
+
+    it('omits ContentType and Metadata when no options are provided', async () => {
+      (readFile as jest.Mock).mockResolvedValue(Buffer.from(''));
+      mockSend.mockResolvedValue({ ETag: '"abc123"' });
+      const s3 = createS3Service(config);
+      await s3.uploadFile('my-bucket', 'key', './file.txt');
+      const commandArg = (PutObjectCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.ContentType).toBeUndefined();
+      expect(commandArg.Metadata).toBeUndefined();
+    });
+
+    it('returns the bucket, key, and etag from the response', async () => {
+      (readFile as jest.Mock).mockResolvedValue(Buffer.from(''));
+      mockSend.mockResolvedValue({ ETag: '"abc123"' });
+      const s3 = createS3Service(config);
+      const result = await s3.uploadFile('my-bucket', 'uploads/file.txt', './file.txt');
+      expect(result).toEqual({ bucket: 'my-bucket', key: 'uploads/file.txt', etag: '"abc123"' });
+    });
+
+    it('returns null etag when not present in the response', async () => {
+      (readFile as jest.Mock).mockResolvedValue(Buffer.from(''));
+      mockSend.mockResolvedValue({});
+      const s3 = createS3Service(config);
+      const result = await s3.uploadFile('my-bucket', 'key', './file.txt');
+      expect(result.etag).toBeNull();
+    });
+  });
+
+  describe('downloadFile', () => {
+    it('sends a GetObjectCommand with the bucket and key', async () => {
+      const mockBody = { transformToByteArray: jest.fn().mockResolvedValue(new Uint8Array()) };
+      mockSend.mockResolvedValue({ Body: mockBody, ContentType: 'text/plain' });
+      (writeFile as jest.Mock).mockResolvedValue(undefined);
+      const s3 = createS3Service(config);
+      await s3.downloadFile('my-bucket', 'uploads/file.txt', './local.txt');
+      const commandArg = (GetObjectCommand as unknown as jest.Mock).mock.calls[0][0];
+      expect(commandArg.Bucket).toBe('my-bucket');
+      expect(commandArg.Key).toBe('uploads/file.txt');
+    });
+
+    it('writes the response body to the local path', async () => {
+      const bytes = new Uint8Array([104, 101, 108, 108, 111]);
+      const mockBody = { transformToByteArray: jest.fn().mockResolvedValue(bytes) };
+      mockSend.mockResolvedValue({ Body: mockBody, ContentType: 'text/plain' });
+      (writeFile as jest.Mock).mockResolvedValue(undefined);
+      const s3 = createS3Service(config);
+      await s3.downloadFile('my-bucket', 'uploads/file.txt', './local.txt');
+      expect(writeFile).toHaveBeenCalledWith('./local.txt', bytes);
+    });
+
+    it('returns bucket, key, localPath, and contentType', async () => {
+      const mockBody = { transformToByteArray: jest.fn().mockResolvedValue(new Uint8Array()) };
+      mockSend.mockResolvedValue({ Body: mockBody, ContentType: 'application/json' });
+      (writeFile as jest.Mock).mockResolvedValue(undefined);
+      const s3 = createS3Service(config);
+      const result = await s3.downloadFile('my-bucket', 'uploads/file.txt', './local.txt');
+      expect(result).toEqual({ bucket: 'my-bucket', key: 'uploads/file.txt', localPath: './local.txt', contentType: 'application/json' });
+    });
+
+    it('returns undefined contentType when not present in the response', async () => {
+      const mockBody = { transformToByteArray: jest.fn().mockResolvedValue(new Uint8Array()) };
+      mockSend.mockResolvedValue({ Body: mockBody });
+      (writeFile as jest.Mock).mockResolvedValue(undefined);
+      const s3 = createS3Service(config);
+      const result = await s3.downloadFile('my-bucket', 'key', './local.txt');
+      expect(result.contentType).toBeUndefined();
+    });
+  });
+
+  describe('getPresignedUrl', () => {
+    it('defaults expiresIn to 3600 when not provided', async () => {
+      (getSignedUrl as jest.Mock).mockResolvedValue('https://s3.example.com/presigned');
+      const s3 = createS3Service(config);
+      const result = await s3.getPresignedUrl('my-bucket', 'uploads/file.txt');
+      expect(getSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), { expiresIn: 3600 });
+      expect(result.expiresIn).toBe(3600);
+    });
+
+    it('uses the provided expiresIn value', async () => {
+      (getSignedUrl as jest.Mock).mockResolvedValue('https://s3.example.com/presigned');
+      const s3 = createS3Service(config);
+      const result = await s3.getPresignedUrl('my-bucket', 'key', 300);
+      expect(getSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), { expiresIn: 300 });
+      expect(result.expiresIn).toBe(300);
+    });
+
+    it('returns bucket and key alongside url and expiresIn', async () => {
+      (getSignedUrl as jest.Mock).mockResolvedValue('https://s3.example.com/presigned');
+      const s3 = createS3Service(config);
+      const result = await s3.getPresignedUrl('my-bucket', 'uploads/file.txt', 300);
+      expect(result).toEqual({ url: 'https://s3.example.com/presigned', expiresIn: 300, bucket: 'my-bucket', key: 'uploads/file.txt' });
+    });
+  });
+
+  it('throws error when a method is called without config', async () => {
+    const s3 = createS3Service();
+    await expect(s3.uploadFile('bucket', 'key', './file.txt')).rejects.toThrow('s3 service is not configured');
+  });
+
+});

package/templates/plugins/aws-s3/service.ts

@@ -0,0 +1,43 @@
+import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { readFile, writeFile } from "fs/promises";
+import type { S3Config, UploadOptions, UploadFileResult, DownloadFileResult, PresignedUrlResult } from "./types.js";
+
+export function createS3Service(config?: S3Config) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("s3 service is not configured -- call .s3(config) on the suite");
+  };
+  const client = config ? new S3Client({ region: config.region }) : null;
+
+  return {
+    uploadFile: async (bucket: string, key: string, filePath: string, options: UploadOptions = {}): Promise<UploadFileResult> => {
+      ensureConfig();
+      const body = await readFile(filePath);
+      const response = await client!.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: body,
+          ...(options.contentType && { ContentType: options.contentType }),
+          ...(options.metadata && { Metadata: options.metadata }),
+        })
+      );
+      return { bucket, key, etag: response.ETag ?? null };
+    },
+
+    downloadFile: async (bucket: string, key: string, localPath: string): Promise<DownloadFileResult> => {
+      ensureConfig();
+      const response = await client!.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+      const body = await response.Body!.transformToByteArray();
+      await writeFile(localPath, body);
+      return { bucket, key, localPath, contentType: response.ContentType };
+    },
+
+    getPresignedUrl: async (bucket: string, key: string, expiresIn: number = 3600): Promise<PresignedUrlResult> => {
+      ensureConfig();
+      const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+      const url = await getSignedUrl(client!, command, { expiresIn });
+      return { url, expiresIn, bucket, key };
+    },
+  };
+}