@jordanalec/dtk 1.0.0

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

@@ -0,0 +1,28 @@
+export interface S3Config {
+  region: string;
+}
+
+export interface UploadOptions {
+  contentType?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface UploadFileResult {
+  bucket: string;
+  key: string;
+  etag: string | null;
+}
+
+export interface DownloadFileResult {
+  bucket: string;
+  key: string;
+  localPath: string;
+  contentType: string | undefined;
+}
+
+export interface PresignedUrlResult {
+  url: string;
+  expiresIn: number;
+  bucket: string;
+  key: string;
+}

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

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

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

@@ -0,0 +1,18 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .sns({
+    topicArn: process.env.SNS_TOPIC_ARN!,
+    region: process.env.AWS_REGION!,
+  })
+  .step("publish-message", async (ctx) => {
+    const result = await ctx.services.sns.publish(
+      "Hello from dtk",
+      "dtk example notification",
+      { source: "dtk-example" }
+    );
+    console.log("messageId:", result.messageId);
+    return result;
+  })
+  .run("throwOnError");

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

@@ -0,0 +1,37 @@
+{
+  "name": "aws-sns",
+  "description": "AWS SNS -- publish messages to a topic",
+  "dependencies": {
+    "@aws-sdk/client-sns": "^3.300.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/sns.ts" },
+    { "src": "types.ts", "dest": "src/types/aws-sns.ts" },
+    { "src": "service.test.ts", "dest": "src/services/sns.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/aws-sns.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./sns.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createSnsService } from \"./services/sns.js\";",
+        "import type { SnsConfig } from \"./types/aws-sns.js\";"
+      ],
+      "configs": "  private snsConfig?: SnsConfig;",
+      "methods": "  sns(config: SnsConfig): this { this.snsConfig = config; return this; }",
+      "services": "        sns: createSnsService(this.snsConfig),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { SnsConfig, PublishResult } from \"./aws-sns.js\";",
+      "service-types": "    sns: { publish(message: string, subject?: string, attributes?: Record<string, string>): Promise<PublishResult>; };"
+    }
+  }
+}

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

@@ -0,0 +1,79 @@
+import { createSnsService } from './service.js';
+
+jest.mock('@aws-sdk/client-sns');
+import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+
+const mockSend = jest.fn();
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (SNSClient as jest.Mock).mockImplementation(() => ({ send: mockSend }));
+});
+
+describe('createSnsService', () => {
+  const config = { topicArn: 'arn:aws:sns:us-east-1:123:my-topic', region: 'us-east-1' };
+
+  it('returns the messageId from the SNS response', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'pub-abc-123' });
+    const sns = createSnsService(config);
+    const result = await sns.publish('hello');
+    expect(result).toEqual({ messageId: 'pub-abc-123' });
+  });
+
+  it('returns null messageId when not present in the response', async () => {
+    mockSend.mockResolvedValue({});
+    const sns = createSnsService(config);
+    const result = await sns.publish('hello');
+    expect(result.messageId).toBeNull();
+  });
+
+  it('sends the message and topic ARN in the command', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sns = createSnsService(config);
+    await sns.publish('my notification');
+    const commandArg = (PublishCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.Message).toBe('my notification');
+    expect(commandArg.TopicArn).toBe(config.topicArn);
+  });
+
+  it('includes Subject in the command when provided', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sns = createSnsService(config);
+    await sns.publish('body', 'Alert: something happened');
+    const commandArg = (PublishCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.Subject).toBe('Alert: something happened');
+  });
+
+  it('omits Subject when not provided', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sns = createSnsService(config);
+    await sns.publish('body');
+    const commandArg = (PublishCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.Subject).toBeUndefined();
+  });
+
+  it('maps string attributes to the SNS MessageAttribute format', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sns = createSnsService(config);
+    await sns.publish('body', undefined, { source: 'my-runbook', tier: 'prod' });
+    const commandArg = (PublishCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.MessageAttributes).toEqual({
+      source: { DataType: 'String', StringValue: 'my-runbook' },
+      tier:   { DataType: 'String', StringValue: 'prod' },
+    });
+  });
+
+  it('omits MessageAttributes when none are provided', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sns = createSnsService(config);
+    await sns.publish('body');
+    const commandArg = (PublishCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.MessageAttributes).toBeUndefined();
+  });
+
+  it('throws error when publish is called without config', async () => {
+    const sns = createSnsService();
+    await expect(sns.publish('hello')).rejects.toThrow('sns service is not configured');
+  });
+
+});

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

@@ -0,0 +1,28 @@
+import { SNSClient, PublishCommand } from "@aws-sdk/client-sns";
+import type { SnsConfig, PublishResult } from "./types.js";
+
+export function createSnsService(config?: SnsConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("sns service is not configured -- call .sns(config) on the suite");
+  };
+  const client = config ? new SNSClient({ region: config.region }) : null;
+
+  return {
+    publish: async (message: string, subject?: string, attributes?: Record<string, string>): Promise<PublishResult> => {
+      ensureConfig();
+      const response = await client!.send(
+        new PublishCommand({
+          TopicArn: config!.topicArn,
+          Message: message,
+          ...(subject && { Subject: subject }),
+          ...(attributes && {
+            MessageAttributes: Object.fromEntries(
+              Object.entries(attributes).map(([k, v]) => [k, { DataType: "String", StringValue: v }])
+            ),
+          }),
+        })
+      );
+      return { messageId: response.MessageId ?? null };
+    },
+  };
+}

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

@@ -0,0 +1,8 @@
+export interface SnsConfig {
+  topicArn: string;
+  region: string;
+}
+
+export interface PublishResult {
+  messageId: string | null;
+}

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

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

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

@@ -0,0 +1,16 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .sqs({
+    queueUrl: process.env.SQS_QUEUE_URL!,
+    region: process.env.AWS_REGION!,
+  })
+  .step("send-message", async (ctx) => {
+    const result = await ctx.services.sqs.sendMessage("Hello from dtk", {
+      source: "dtk-example",
+    });
+    console.log("messageId:", result.messageId);
+    return result;
+  })
+  .run("throwOnError");

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

@@ -0,0 +1,37 @@
+{
+  "name": "aws-sqs",
+  "description": "AWS SQS -- send messages to a queue",
+  "dependencies": {
+    "@aws-sdk/client-sqs": "^3.300.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/sqs.ts" },
+    { "src": "types.ts", "dest": "src/types/aws-sqs.ts" },
+    { "src": "service.test.ts", "dest": "src/services/sqs.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/aws-sqs.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./sqs.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createSqsService } from \"./services/sqs.js\";",
+        "import type { SqsConfig } from \"./types/aws-sqs.js\";"
+      ],
+      "configs": "  private sqsConfig?: SqsConfig;",
+      "methods": "  sqs(config: SqsConfig): this { this.sqsConfig = config; return this; }",
+      "services": "        sqs: createSqsService(this.sqsConfig),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { SqsConfig, SendMessageResult } from \"./aws-sqs.js\";",
+      "service-types": "    sqs: { sendMessage(body: string, attributes?: Record<string, string>): Promise<SendMessageResult>; };"
+    }
+  }
+}

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

@@ -0,0 +1,63 @@
+import { createSqsService } from './service.js';
+
+jest.mock('@aws-sdk/client-sqs');
+import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
+
+const mockSend = jest.fn();
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (SQSClient as jest.Mock).mockImplementation(() => ({ send: mockSend }));
+});
+
+describe('createSqsService', () => {
+  const config = { queueUrl: 'https://sqs.us-east-1.amazonaws.com/123/my-queue', region: 'us-east-1' };
+
+  it('returns the messageId from the SQS response', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'msg-abc-123' });
+    const sqs = createSqsService(config);
+    const result = await sqs.sendMessage('hello');
+    expect(result).toEqual({ messageId: 'msg-abc-123' });
+  });
+
+  it('returns null messageId when not present in the response', async () => {
+    mockSend.mockResolvedValue({});
+    const sqs = createSqsService(config);
+    const result = await sqs.sendMessage('hello');
+    expect(result.messageId).toBeNull();
+  });
+
+  it('sends the message body and queue URL in the command', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sqs = createSqsService(config);
+    await sqs.sendMessage('my message body');
+    const commandArg = (SendMessageCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.MessageBody).toBe('my message body');
+    expect(commandArg.QueueUrl).toBe(config.queueUrl);
+  });
+
+  it('maps string attributes to the SQS MessageAttribute format', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sqs = createSqsService(config);
+    await sqs.sendMessage('body', { source: 'my-runbook', env: 'test' });
+    const commandArg = (SendMessageCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.MessageAttributes).toEqual({
+      source: { DataType: 'String', StringValue: 'my-runbook' },
+      env:    { DataType: 'String', StringValue: 'test' },
+    });
+  });
+
+  it('omits MessageAttributes when none are provided', async () => {
+    mockSend.mockResolvedValue({ MessageId: 'id' });
+    const sqs = createSqsService(config);
+    await sqs.sendMessage('body');
+    const commandArg = (SendMessageCommand as unknown as jest.Mock).mock.calls[0][0];
+    expect(commandArg.MessageAttributes).toBeUndefined();
+  });
+
+  it('throws error when sendMessage is called without config', async () => {
+    const sqs = createSqsService();
+    await expect(sqs.sendMessage('hello')).rejects.toThrow('sqs service is not configured');
+  });
+
+});

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

@@ -0,0 +1,27 @@
+import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
+import type { SqsConfig, SendMessageResult } from "./types.js";
+
+export function createSqsService(config?: SqsConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("sqs service is not configured -- call .sqs(config) on the suite");
+  };
+  const client = config ? new SQSClient({ region: config.region }) : null;
+
+  return {
+    sendMessage: async (body: string, attributes?: Record<string, string>): Promise<SendMessageResult> => {
+      ensureConfig();
+      const response = await client!.send(
+        new SendMessageCommand({
+          QueueUrl: config!.queueUrl,
+          MessageBody: body,
+          ...(attributes && {
+            MessageAttributes: Object.fromEntries(
+              Object.entries(attributes).map(([k, v]) => [k, { DataType: "String", StringValue: v }])
+            ),
+          }),
+        })
+      );
+      return { messageId: response.MessageId ?? null };
+    },
+  };
+}

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

@@ -0,0 +1,8 @@
+export interface SqsConfig {
+  queueUrl: string;
+  region: string;
+}
+
+export interface SendMessageResult {
+  messageId: string | null;
+}

package/templates/plugins/open-ai/env.txt

@@ -0,0 +1 @@
+OPENAI_API_KEY=

package/templates/plugins/open-ai/example.ts

@@ -0,0 +1,27 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .openAi({
+    baseUrl: "https://api.openai.com",
+  })
+  .step("list-models", async (ctx) => {
+    const token = `Bearer ${process.env.OPENAI_API_KEY!}`;
+    const result = await ctx.services.openAi.listModels(token);
+    console.log(`Available models (${result.data.length}):`);
+    result.data.slice(0, 5).forEach((m) => console.log(" -", m.id));
+    return result;
+  })
+  .step("send-response", async (ctx) => {
+    const token = `Bearer ${process.env.OPENAI_API_KEY!}`;
+    const result = await ctx.services.openAi.response(
+      token,
+      "gpt-4o-mini",
+      "text",
+      "Say hello in one sentence."
+    );
+    const text = result.output[0]?.content[0]?.text;
+    console.log("response:", text);
+    return result;
+  })
+  .run("throwOnError");

package/templates/plugins/open-ai/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "open-ai",
+  "description": "OpenAI -- list models and send responses",
+  "files": [
+    { "src": "service.ts", "dest": "src/services/open-ai.ts" },
+    { "src": "types.ts", "dest": "src/types/open-ai.ts" },
+    { "src": "service.test.ts", "dest": "src/services/open-ai.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/open-ai.js" },
+      { "from": "../../init/src/lib/http.js", "to": "../lib/http.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./open-ai.js" },
+      { "from": "../../init/src/lib/http.js", "to": "../lib/http.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createOpenAIService } from \"./services/open-ai.js\";",
+        "import type { OpenAiConfig } from \"./types/open-ai.js\";"
+      ],
+      "configs": "  private openAiConfig?: OpenAiConfig;",
+      "methods": "  openAi(config: OpenAiConfig): this { this.openAiConfig = config; return this; }",
+      "services": "        openAi: createOpenAIService(this.openAiConfig),"
+    },
+    "src/types/suite.ts": {
+      "type-imports": "import type { OpenAiConfig, OpenAiListModels, OpenAiResponse } from \"./open-ai.js\";",
+      "service-types": "    openAi: { listModels(bearerToken: string): Promise<OpenAiListModels>; response(bearerToken: string, model: string, format: string, message: string): Promise<OpenAiResponse>; };"
+    }
+  }
+}

package/templates/plugins/open-ai/service.test.ts

@@ -0,0 +1,55 @@
+import { createOpenAIService } from './service.js';
+
+jest.mock('../../init/src/lib/http.js');
+import { httpGet, httpPost } from '../../init/src/lib/http.js';
+
+const mockHttpGet = jest.mocked(httpGet);
+const mockHttpPost = jest.mocked(httpPost);
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('createOpenAIService', () => {
+  const config = { baseUrl: 'https://api.openai.com' };
+  const bearerToken = 'Bearer sk-test-token';
+
+  describe('listModels', () => {
+    it('calls the correct models endpoint with the bearer token', async () => {
+      mockHttpGet.mockResolvedValue({ object: 'list', data: [] });
+      const openAi = createOpenAIService(config);
+      await openAi.listModels(bearerToken);
+      expect(mockHttpGet).toHaveBeenCalledWith(
+        'https://api.openai.com/v1/models',
+        { headers: { Authorization: bearerToken } }
+      );
+    });
+
+  });
+
+  describe('response', () => {
+    it('calls the correct responses endpoint', async () => {
+      mockHttpPost.mockResolvedValue({ id: 'resp-1' });
+      const openAi = createOpenAIService(config);
+      await openAi.response(bearerToken, 'gpt-4o-mini', 'text', 'Say hello.');
+      expect(mockHttpPost).toHaveBeenCalledWith(
+        'https://api.openai.com/v1/responses',
+        expect.any(Object),
+        { headers: { Authorization: bearerToken } }
+      );
+    });
+
+    it('sends the correct request body', async () => {
+      mockHttpPost.mockResolvedValue({ id: 'resp-1' });
+      const openAi = createOpenAIService(config);
+      await openAi.response(bearerToken, 'gpt-4o-mini', 'json_object', 'Return JSON.');
+      const body = mockHttpPost.mock.calls[0][1];
+      expect(body).toMatchObject({
+        model: 'gpt-4o-mini',
+        input: 'Return JSON.',
+        text: { format: { type: 'json_object' } },
+      });
+    });
+
+  });
+});

package/templates/plugins/open-ai/service.ts

@@ -0,0 +1,26 @@
+import type { OpenAiConfig, OpenAiListModels, OpenAiResponse, OpenAiResponseBody, OpenAiResponseFormat } from "./types.js";
+import { httpGet, httpPost } from "../../init/src/lib/http.js";
+
+export function createOpenAIService(config?: OpenAiConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("openAi service is not configured -- call .openAi(config) on the suite");
+  };
+
+  return {
+    listModels: async (bearerToken: string): Promise<OpenAiListModels> => {
+      ensureConfig();
+      const headers: Record<string, string> = { Authorization: bearerToken };
+      return httpGet<OpenAiListModels>(`${config!.baseUrl}/v1/models`, { headers });
+    },
+    response: async (bearerToken: string, model: string, format: OpenAiResponseFormat, message: string): Promise<OpenAiResponse> => {
+      ensureConfig();
+      const headers: Record<string, string> = { Authorization: bearerToken };
+      const body: OpenAiResponseBody = {
+        model,
+        input: message,
+        text: { format: { type: format } },
+      };
+      return httpPost<OpenAiResponseBody, OpenAiResponse>(`${config!.baseUrl}/v1/responses`, body, { headers });
+    },
+  };
+}

package/templates/plugins/open-ai/types.ts

@@ -0,0 +1,61 @@
+export interface OpenAiConfig {
+  baseUrl: string;
+}
+
+export interface OpenAiListModels {
+  object: string;
+  data: OpenAiModel[];
+}
+
+export interface OpenAiModel {
+  id: string;
+  object: string;
+  created: number;
+  owned_by: string;
+}
+
+export type OpenAiResponseFormat = "text" | "json_object";
+
+export interface OpenAiResponseBody {
+  model: string;
+  input: string;
+  text?: {
+    format: {
+      type: OpenAiResponseFormat;
+    };
+  };
+}
+
+export interface OpenAiResponse {
+  id: string;
+  object: string;
+  created_at: number;
+  status: string;
+  background: boolean;
+  billing: {
+    payer: string;
+  };
+  error: unknown;
+  incomplete_details: unknown;
+  instructions: unknown;
+  max_output_tokens: unknown;
+  max_tool_calls: unknown;
+  model: string;
+  output: [
+    {
+      id: string;
+      type: string;
+      status: string;
+      content: [
+        {
+          type: string;
+          annotations: unknown;
+          logprobs: unknown;
+          text: string;
+        }
+      ];
+      role: string;
+    }
+  ];
+  parallel_tool_calls: boolean;
+}

package/templates/plugins/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["jest", "node"]
+  }
+}