@jordanalec/dtk 1.0.0

package/templates/init/GUIDE.md

@@ -0,0 +1,543 @@
+# Project Guide
+
+Everything you need to know about working with this project, extending it, and adding new services.
+
+---
+
+## Table of Contents
+
+1. [How it works](#how-it-works)
+2. [Environment variables](#environment-variables)
+3. [Writing a runbook](#writing-a-runbook)
+4. [Auth patterns](#auth-patterns)
+5. [Passing data between steps](#passing-data-between-steps)
+6. [Adding a plugin](#adding-a-plugin)
+7. [Available plugins](#available-plugins)
+8. [Writing a custom service](#writing-a-custom-service)
+9. [File reference](#file-reference)
+
+---
+
+## How it works
+
+Each runbook creates a suite, configures auth and services via builder methods, chains steps, then calls `.run()`.
+
+Steps execute in sequence. Each step receives a shared context (`ctx`) containing auth helpers, an HTTP client, and any wired service instances. The return value of each step is stored in `ctx.outputs` and available to all subsequent steps.
+
+```ts
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .oauth({ clientId, clientSecret, tokenUrl })
+  .step("get-token", async (ctx) => {
+    return ctx.auth.clientCredentials();
+  })
+  .step("use-token", async (ctx) => {
+    const token = ctx.outputs["get-token"] as { access_token: string };
+    return ctx.http.get("https://api.example.com/data", {
+      headers: { Authorization: `Bearer ${token.access_token}` },
+    });
+  })
+  .run("throwOnError");
+```
+
+### Run options
+
+| Option | Behaviour |
+|---|---|
+| `"throwOnError"` | Stops on first failure and throws |
+| `"stopOnError"` | Logs the failure and stops without throwing |
+
+---
+
+## Environment variables
+
+Copy `.env.template` to `.env` and fill in values. `.env.local` overrides `.env` if present. Neither file should be committed -- both are in `.gitignore`.
+
+```bash
+cp .env.template .env
+```
+
+`load-env.ts` handles loading. Import it as the first line of every runbook:
+
+```ts
+import "../load-env.js";
+```
+
+---
+
+## Writing a runbook
+
+Create a `.ts` file in `src/runbooks/`. Import `load-env.js` first, then import `suite` from `suite.js`.
+
+```ts
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .step("fetch", async (ctx) => {
+    const data = await ctx.http.get<{ name: string }>("https://api.example.com/thing/1");
+    console.log(data.name);
+    return data;
+  })
+  .run("throwOnError");
+```
+
+Add a script to `package.json` so you can run it with `npm run`:
+
+```json
+"runbook:my-workflow": "tsx src/runbooks/my-workflow.ts"
+```
+
+Or run it directly:
+
+```bash
+npx tsx src/runbooks/my-workflow.ts
+```
+
+---
+
+## Auth patterns
+
+### OAuth client credentials
+
+```ts
+await suite()
+  .oauth({
+    clientId: process.env.CLIENT_ID!,
+    clientSecret: process.env.CLIENT_SECRET!,
+    tokenUrl: process.env.TOKEN_URL!,
+    scope: "openid",             // optional
+  })
+  .step("fetch", async (ctx) => {
+    const token = await ctx.auth.clientCredentials();
+    return ctx.http.get("https://api.example.com/data", {
+      headers: { Authorization: `Bearer ${token.access_token}` },
+    });
+  })
+  .run("throwOnError");
+```
+
+### Basic auth
+
+```ts
+await suite()
+  .basicAuth({
+    username: process.env.API_USER!,
+    password: process.env.API_PASS!,
+  })
+  .step("fetch", async (ctx) => {
+    const header = await ctx.auth.basicAuth();
+    return ctx.http.get("https://api.example.com/data", {
+      headers: { Authorization: header },
+    });
+  })
+  .run("throwOnError");
+```
+
+### Bearer token
+
+```ts
+await suite()
+  .bearerToken({
+    token: process.env.API_TOKEN!,
+    prefix: "Bearer",
+  })
+  .step("fetch", async (ctx) => {
+    const header = await ctx.auth.bearerToken();
+    return ctx.http.get("https://api.example.com/data", {
+      headers: { Authorization: header },
+    });
+  })
+  .run("throwOnError");
+```
+
+### JWT claim extraction
+
+```ts
+const claims = ctx.auth.getClaimValues(token.access_token);
+console.log(claims.sub);
+```
+
+---
+
+## Passing data between steps
+
+Every step's return value is stored in `ctx.outputs` under the step name. Cast to the type you expect:
+
+```ts
+await suite()
+  .step("get-user", async (ctx) => {
+    return ctx.http.get<{ id: number; name: string }>("https://api.example.com/user/1");
+  })
+  .step("get-orders", async (ctx) => {
+    const user = ctx.outputs["get-user"] as { id: number; name: string };
+    return ctx.http.get(`https://api.example.com/orders?userId=${user.id}`);
+  })
+  .run("throwOnError");
+```
+
+---
+
+## Adding a plugin
+
+Requires the dtk CLI to be installed globally. From this project directory:
+
+```bash
+dtk add <plugin>
+```
+
+This will automatically:
+- Copy the service and types files into `src/`
+- Patch `src/suite.ts` to wire the service in
+- Patch `src/types/suite.ts` to add the service types to the step context
+- Append the required env vars to `.env.template`
+- Create an example runbook in `src/runbooks/`
+- Add a `runbook:<plugin>` script to `package.json`
+- Run `npm install` for any required dependencies
+
+Running `dtk add` on an already-added plugin is safe -- nothing is duplicated.
+
+---
+
+## Available plugins
+
+### aws-sqs
+
+Sends messages to an AWS SQS queue.
+
+```bash
+dtk add aws-sqs
+```
+
+Required env vars:
+
+```
+SQS_QUEUE_URL=
+AWS_REGION=
+```
+
+Usage:
+
+```ts
+await suite()
+  .sqs({
+    queueUrl: process.env.SQS_QUEUE_URL!,
+    region: process.env.AWS_REGION!,
+  })
+  .step("send", async (ctx) => {
+    const result = await ctx.services.sqs.sendMessage("hello world");
+    console.log("messageId:", result.messageId);
+    return result;
+  })
+  .run("throwOnError");
+```
+
+AWS credentials are picked up automatically from `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment.
+
+---
+
+### aws-sns
+
+Publishes messages to an AWS SNS topic.
+
+```bash
+dtk add aws-sns
+```
+
+Required env vars:
+
+```
+SNS_TOPIC_ARN=
+AWS_REGION=
+```
+
+Usage:
+
+```ts
+await suite()
+  .sns({
+    topicArn: process.env.SNS_TOPIC_ARN!,
+    region: process.env.AWS_REGION!,
+  })
+  .step("publish", async (ctx) => {
+    const result = await ctx.services.sns.publish("hello world", "optional subject");
+    console.log("messageId:", result.messageId);
+    return result;
+  })
+  .run("throwOnError");
+```
+
+---
+
+### aws-dynamo
+
+Reads and writes items in AWS DynamoDB tables.
+
+```bash
+dtk add aws-dynamo
+```
+
+Required env vars:
+
+```
+AWS_REGION=
+DYNAMO_TABLE_NAME=
+```
+
+Usage:
+
+```ts
+await suite()
+  .dynamo({ region: process.env.AWS_REGION! })
+  .step("put", async (ctx) => {
+    return ctx.services.dynamo.putItem(process.env.DYNAMO_TABLE_NAME!, {
+      id: "user-123",
+      name: "John Doe",
+    });
+  })
+  .step("get", async (ctx) => {
+    return ctx.services.dynamo.getItem(process.env.DYNAMO_TABLE_NAME!, { id: "user-123" });
+  })
+  .step("update", async (ctx) => {
+    return ctx.services.dynamo.updateItem(
+      process.env.DYNAMO_TABLE_NAME!,
+      { id: "user-123" },
+      {
+        UpdateExpression: "SET #n = :n",
+        ExpressionAttributeNames: { "#n": "name" },
+        ExpressionAttributeValues: { ":n": { S: "Jane Doe" } },
+      }
+    );
+  })
+  .step("query", async (ctx) => {
+    return ctx.services.dynamo.queryItems(process.env.DYNAMO_TABLE_NAME!, {
+      KeyConditionExpression: "#pk = :pk",
+      ExpressionAttributeNames: { "#pk": "id" },
+      ExpressionAttributeValues: { ":pk": { S: "user-123" } },
+    });
+  })
+  .step("scan", async (ctx) => {
+    return ctx.services.dynamo.scanItems(process.env.DYNAMO_TABLE_NAME!, { Limit: 10 });
+  })
+  .step("delete", async (ctx) => {
+    return ctx.services.dynamo.deleteItem(process.env.DYNAMO_TABLE_NAME!, { id: "user-123" });
+  })
+  .run("throwOnError");
+```
+
+AWS credentials are picked up automatically from `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment.
+
+---
+
+### aws-s3
+
+Uploads files, downloads files, and generates presigned URLs for AWS S3.
+
+```bash
+dtk add aws-s3
+```
+
+Required env vars:
+
+```
+AWS_REGION=
+S3_BUCKET_NAME=
+```
+
+Usage:
+
+```ts
+await suite()
+  .s3({ region: process.env.AWS_REGION! })
+  .step("upload", async (ctx) => {
+    return ctx.services.s3.uploadFile(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      "./example.txt",
+      { contentType: "text/plain", metadata: { source: "my-runbook" } }
+    );
+  })
+  .step("presign", async (ctx) => {
+    const result = await ctx.services.s3.getPresignedUrl(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      300
+    );
+    console.log("url:", result.url);
+    return result;
+  })
+  .step("download", async (ctx) => {
+    return ctx.services.s3.downloadFile(
+      process.env.S3_BUCKET_NAME!,
+      "uploads/example.txt",
+      "./downloaded.txt"
+    );
+  })
+  .run("throwOnError");
+```
+
+AWS credentials are picked up automatically from `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment.
+
+---
+
+### open-ai
+
+Lists models and sends responses via the OpenAI API.
+
+```bash
+dtk add open-ai
+```
+
+Required env vars:
+
+```
+OPENAI_API_KEY=
+```
+
+Usage:
+
+```ts
+await suite()
+  .openAi({ baseUrl: "https://api.openai.com" })
+  .step("respond", async (ctx) => {
+    const token = `Bearer ${process.env.OPENAI_API_KEY!}`;
+    return ctx.services.openAi.response(token, "gpt-4o-mini", "text", "Say hello.");
+  })
+  .run("throwOnError");
+```
+
+---
+
+## Writing a custom service
+
+If there is no plugin for the service you need, wire one in manually. Four files are involved.
+
+### 1. Create the service factory
+
+`src/services/my-service.ts`:
+
+```ts
+import { httpGet, httpPost, httpPut, httpDelete } from "../lib/http.js";
+
+export interface MyServiceConfig {
+  baseUrl: string;
+}
+
+export function createMyService(config?: MyServiceConfig) {
+  return {
+    getItem: async (id: number): Promise<{ id: number; name: string }> => {
+      return httpGet(`${config!.baseUrl}/items/${id}`);
+    },
+    createItem: async (name: string): Promise<{ id: number }> => {
+      return httpPost(`${config!.baseUrl}/items`, { name });
+    },
+  };
+}
+```
+
+### 2. Add the type shape to `src/types/suite.ts`
+
+Add your config type and service shape. Place them above the `// dtk:service-types` sentinel:
+
+```ts
+export interface MyServiceConfig { baseUrl: string; }
+
+// inside StepContext.services:
+services: {
+  myService: {
+    getItem(id: number): Promise<{ id: number; name: string }>;
+    createItem(name: string): Promise<{ id: number }>;
+  };
+  // dtk:service-types  <-- do not remove this line
+};
+```
+
+### 3. Wire the service into `src/suite.ts`
+
+Add the import before `// dtk:imports`:
+
+```ts
+import { createMyService } from "./services/my-service.js";
+import type { MyServiceConfig } from "./services/my-service.js";
+```
+
+Add a private field before `// dtk:configs`:
+
+```ts
+private myServiceConfig?: MyServiceConfig;
+```
+
+Add a builder method before `// dtk:methods`:
+
+```ts
+myService(config: MyServiceConfig): this { this.myServiceConfig = config; return this; }
+```
+
+Add the service instance before `// dtk:services`:
+
+```ts
+myService: createMyService(this.myServiceConfig),
+```
+
+### 4. Use it in a runbook
+
+```ts
+await suite()
+  .myService({ baseUrl: process.env.MY_SERVICE_BASE_URL! })
+  .step("get-item", async (ctx) => {
+    const item = await ctx.services.myService.getItem(1);
+    console.log(item.name);
+    return item;
+  })
+  .run("throwOnError");
+```
+
+---
+
+## File reference
+
+### `src/suite.ts`
+
+The core of the project. The `TestSuite` class holds service configs, collects steps, builds the step context, and runs steps in sequence. The sentinel comments (`// dtk:imports`, `// dtk:configs`, `// dtk:methods`, `// dtk:services`) are injection points used by `dtk add` -- do not remove them.
+
+### `src/types/suite.ts`
+
+All shared type definitions: `StepContext`, `StepFn`, `Step`, the `SuiteRunOption` string union, and auth config types. The sentinels (`// dtk:type-imports`, `// dtk:service-types`) are also injection points -- do not remove them.
+
+### `src/types/oauth.ts`
+
+`OAuthConfig` and `TokenResponse` -- the input and output types for the OAuth client credentials flow.
+
+### `src/lib/http.ts`
+
+Axios wrapper. Provides `httpGet`, `httpPost`, `httpPut`, and `httpDelete`. Normalises errors into plain `Error` objects with readable messages. Use this inside service factories instead of calling axios directly.
+
+### `src/lib/oauth.ts`
+
+Implements the OAuth 2.0 client credentials flow. Posts to the token URL with `application/x-www-form-urlencoded` and returns a `TokenResponse`.
+
+### `src/lib/basic-auth.ts`
+
+Base64-encodes `username:password` and returns a `Basic <token>` string ready to use as an `Authorization` header.
+
+### `src/lib/bearer-token.ts`
+
+Returns `<prefix> <token>` (e.g. `Bearer sk-abc123`) ready to use as an `Authorization` header.
+
+### `src/lib/token.ts`
+
+`getClaimValues(token)` decodes the payload of a JWT and returns the claims as a plain object. Does not verify the signature.
+
+### `src/load-env.ts`
+
+Loads `.env` then `.env.local` (local overrides). Import this as the very first line of every runbook.
+
+### `.env.template`
+
+Lists all environment variables the project needs. Copy to `.env` and fill in real values. Never commit `.env`.
+
+### `tsconfig.json`
+
+TypeScript config. `module: NodeNext` means all imports must use `.js` extensions even though the source files are `.ts`. `strict: true` is enabled.

package/templates/init/README.md

@@ -0,0 +1,59 @@
+# My dtk Project
+
+A TypeScript runbook project for orchestrating multi-step API workflows. Uses a fluent builder API to chain authentication, HTTP calls, and service interactions into readable, repeatable scripts.
+
+---
+
+## Quick Start
+
+```bash
+npm install
+cp .env.template .env
+# fill in .env with your credentials
+npm run runbook:example
+```
+
+---
+
+## Running Runbooks
+
+```bash
+npm run runbook:example    # unauthenticated HTTP call (GitHub API)
+```
+
+Add your own runbook scripts to `package.json` as you create them:
+
+```json
+"runbook:my-workflow": "tsx src/runbooks/my-workflow.ts"
+```
+
+---
+
+## Adding a Plugin
+
+Install the dtk CLI if you haven't already, then run from this directory:
+
+```bash
+dtk add <plugin>
+```
+
+Available plugins: `aws-sqs`, `aws-sns`, `aws-dynamo`, `aws-s3`, `open-ai`
+
+Each plugin adds a service, wires it into the suite, appends env vars to `.env.template`, creates an example runbook, and installs dependencies automatically.
+
+See `GUIDE.md` for full details.
+
+---
+
+## Project Structure
+
+```
+src/
+  suite.ts          # core runner -- extend this with custom services
+  load-env.ts       # dotenv bootstrap -- import first in every runbook
+  lib/              # HTTP client, OAuth, auth helpers
+  types/            # type definitions
+  services/         # service factories added by plugins or custom code
+  runbooks/         # your runbook scripts
+.env.template       # list of required env vars -- copy to .env
+```

package/templates/init/jest.config.ts

@@ -0,0 +1,19 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  moduleNameMapper: {
+    // source files use .js extensions in imports; map them to .ts for jest
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.test.json',
+      diagnostics: { ignoreCodes: [151002] },
+    }],
+  },
+  testMatch: ['**/*.test.ts'],
+};
+
+export default config;

package/templates/init/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "my-dtk-project",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "runbook:example": "tsx src/runbooks/example.ts",
+    "test": "node node_modules/jest/bin/jest.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/init/src/lib/auth.test.ts

@@ -0,0 +1,48 @@
+import { basicAuth } from './basic-auth.js';
+import { bearerToken } from './bearer-token.js';
+import { getClaimValues } from './token.js';
+
+describe('basicAuth', () => {
+  it('returns a Base64-encoded Basic auth header', async () => {
+    const result = await basicAuth({ username: 'user', password: 'pass' });
+    const expected = `Basic ${Buffer.from('user:pass').toString('base64')}`;
+    expect(result).toBe(expected);
+  });
+
+  it('correctly encodes special characters in credentials', async () => {
+    const result = await basicAuth({ username: 'user@domain.com', password: 'p@ss:word!' });
+    const decoded = Buffer.from(result.replace('Basic ', ''), 'base64').toString('utf-8');
+    expect(decoded).toBe('user@domain.com:p@ss:word!');
+  });
+});
+
+describe('bearerToken', () => {
+  it('combines prefix and token with a space', async () => {
+    const result = await bearerToken({ token: 'abc123', prefix: 'Bearer' });
+    expect(result).toBe('Bearer abc123');
+  });
+
+  it('uses whatever prefix is supplied', async () => {
+    const result = await bearerToken({ token: 'tok', prefix: 'Token' });
+    expect(result).toBe('Token tok');
+  });
+});
+
+describe('getClaimValues', () => {
+  function makeJwt(payload: object): string {
+    const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+    return `header.${encoded}.signature`;
+  }
+
+  it('decodes the payload section of a JWT', () => {
+    const claims = getClaimValues(makeJwt({ sub: 'user-123', name: 'Test User' }));
+    expect(claims.sub).toBe('user-123');
+    expect(claims.name).toBe('Test User');
+  });
+
+  it('returns all claims present in the token', () => {
+    const payload = { sub: '1', role: 'admin', org: 'acme', exp: '9999999999' };
+    const claims = getClaimValues(makeJwt(payload));
+    expect(claims).toMatchObject(payload);
+  });
+});

package/templates/init/src/lib/basic-auth.ts

@@ -0,0 +1,6 @@
+import type { BasicAuthConfig } from "../types/suite.js";
+
+export async function basicAuth(config: BasicAuthConfig): Promise<string> {
+  const token = Buffer.from(`${config!.username}:${config!.password}`).toString("base64");
+  return `Basic ${token}`;
+}

package/templates/init/src/lib/bearer-token.ts

@@ -0,0 +1,5 @@
+import type { BearerTokenConfig } from "../types/suite.js";
+
+export async function bearerToken(config: BearerTokenConfig): Promise<string> {
+  return `${config.prefix} ${config.token}`;
+}