create-stb 1.0.6 → 1.2.0

package/serverless/package.json

@@ -1,39 +0,0 @@
-{
-  "name": "create-stb",
-  "version": "1.0.0",
-  "description": "create-stb boilerplate template",
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf .build",
-    "deploy": "serverless deploy",
-    "dynamo:destroy": "docker compose down -v",
-    "dynamo:down": "docker compose down",
-    "dynamo:up": "docker compose up -d",
-    "format": "prettier --write .",
-    "offline": "serverless offline --stage dev",
-    "tables:create": "ts-node src/scripts/create-tables.ts",
-    "tables:seed": "ts-node src/scripts/seed-tables.ts"
-  },
-  "dependencies": {
-    "@aws-sdk/client-dynamodb": "3.910.0",
-    "@aws-sdk/util-dynamodb": "3.910.0",
-    "@faker-js/faker": "10.1.0",
-    "axios": "1.13.2",
-    "dotenv": "17.2.3"
-  },
-  "devDependencies": {
-    "@types/aws-lambda": "8.10.158",
-    "@types/dotenv": "6.1.1",
-    "@types/node": "24.7.2",
-    "prettier": "3.6.2",
-    "serverless": "4.20.2",
-    "serverless-offline": "14.4.0",
-    "typescript": "5.9.3"
-  },
-  "author": "Sam Newhouse",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/SamNewhouse/create-stb.git"
-  }
-}

package/serverless/serverless.yml

@@ -1,52 +0,0 @@
-service: create-stb
-
-provider:
-  name: aws
-  runtime: nodejs20.x
-  region: eu-west-2
-  stage: ${opt:stage, 'dev'}
-  environment:
-    DYNAMODB_EXAMPLE: Example
-    JWT_SECRET: ${env:JWT_SECRET, 'dev-secret-change-in-production'}
-    DYNAMODB_ENDPOINT: ${env:DYNAMODB_ENDPOINT, ''}
-    STAGE: ${self:provider.stage}
-
-package:
-  individually: true
-  patterns:
-    - "!src/scripts/**"
-
-plugins:
-  - serverless-offline
-
-custom:
-  dynamodb:
-    stages:
-      - dev
-    start:
-      port: 8000
-      inMemory: true
-      migrate: true
-
-functions:
-  example-get:
-    handler: src/handlers/example/get.handler
-    events:
-      - http:
-          path: example/{id}
-          method: get
-          cors: true
-
-resources:
-  Resources:
-    ExampleTable:
-      Type: AWS::DynamoDB::Table
-      Properties:
-        TableName: Example
-        AttributeDefinitions:
-          - AttributeName: id
-            AttributeType: S
-        KeySchema:
-          - AttributeName: id
-            KeyType: HASH
-        BillingMode: PAY_PER_REQUEST

package/serverless/src/config/variables.ts

@@ -1,11 +0,0 @@
-import * as dotenv from "dotenv";
-
-dotenv.config();
-
-export const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID;
-export const AWS_REGION = process.env.AWS_REGION;
-export const AWS_REGION_FALLBACK = process.env.AWS_REGION_FALLBACK;
-export const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY;
-export const DYNAMODB_ENDPOINT = process.env.DYNAMODB_ENDPOINT;
-export const JWT_SECRET = process.env.JWT_SECRET;
-export const STAGE = process.env.STAGE;

package/serverless/src/env.ts

@@ -1,6 +0,0 @@
-export const ENV: string = process.env.ENV!;
-
-export const AWS_REGION: string = process.env.AWS_REGION!;
-
-export const AWS_ACCESS_KEY_ID: string = process.env.AWS_ACCESS_KEY_ID!;
-export const AWS_ACCESS_SECRET_KEY: string = process.env.AWS_ACCESS_SECRET_KEY!;

package/serverless/src/functions/example.ts

@@ -1,24 +0,0 @@
-import * as Dynamodb from "../lib/dynamodb";
-import { Example, Tables } from "../types";
-import { shortUUID } from "../utils/helpers";
-
-/**
- * Retrieves a single Example item by its unique identifier (id).
- * @param id - The primary key value to look up.
- * @returns The Example object if found, or null if not found.
- */
-export async function get(id: string): Promise<Example> {
-  const client = Dynamodb.getClient();
-  return Dynamodb.getItem(client, Tables.Example, { id });
-}
-
-/**
- * Generates a generic set of Example records with random short ids.
- * Uses shortUUID() for unique 8-character values.
- * @returns An array of 10 Example objects, each with a random id.
- */
-export function generatePlainExamples(): Example[] {
-  return Array.from({ length: 10 }, () => ({
-    id: shortUUID(),
-  }));
-}

package/serverless/src/handlers/example/get.ts

@@ -1,17 +0,0 @@
-import { APIGatewayProxyHandler } from "aws-lambda";
-import { get } from "../../functions/example";
-import { success, handleError, badRequest, notFound } from "../../lib/http";
-
-export const handler: APIGatewayProxyHandler = async (event) => {
-  try {
-    const id = event.pathParameters?.id;
-    if (!id) return badRequest("id is required");
-
-    const example = await get(id);
-    if (!example) return notFound("Example not found");
-
-    return success(example);
-  } catch (err) {
-    return handleError(err);
-  }
-};

package/serverless/src/lib/dynamodb.ts

@@ -1,203 +0,0 @@
-import {
-  DynamoDBClient,
-  ListTablesCommand,
-  CreateTableCommand,
-  PutItemCommand,
-  GetItemCommand,
-  BatchGetItemCommand,
-  ScanCommand,
-  QueryCommand,
-  UpdateItemCommand,
-  DeleteItemCommand,
-} from "@aws-sdk/client-dynamodb";
-import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
-import { DYNAMODB_ENDPOINT, AWS_SECRET_ACCESS_KEY, AWS_REGION_FALLBACK } from "../config/variables";
-import { AWS_ACCESS_KEY_ID, AWS_REGION } from "../env";
-
-/**
- * Returns a singleton DynamoDBClient configured for this environment.
- */
-let dynamoClient: DynamoDBClient | null = null;
-
-export function getClient(): DynamoDBClient {
-  if (!dynamoClient) {
-    const config: any = {};
-    if (DYNAMODB_ENDPOINT) {
-      config.endpoint = DYNAMODB_ENDPOINT;
-      config.credentials = {
-        accessKeyId: AWS_ACCESS_KEY_ID || "dummy",
-        secretAccessKey: AWS_SECRET_ACCESS_KEY || "dummy",
-      };
-    }
-    config.region = AWS_REGION || AWS_REGION_FALLBACK || "eu-west-2";
-    dynamoClient = new DynamoDBClient(config);
-  }
-  return dynamoClient;
-}
-
-/**
- * Lists all DynamoDB tables for the provided client.
- */
-export async function listTables(client: DynamoDBClient = getClient()): Promise<string[]> {
-  const result = await client.send(new ListTablesCommand({}));
-  return result.TableNames ?? [];
-}
-
-/**
- * Creates a new DynamoDB table using the given configuration.
- */
-export async function createTable(
-  client: DynamoDBClient = getClient(),
-  tableConfig: any,
-): Promise<void> {
-  await client.send(new CreateTableCommand(tableConfig));
-}
-
-/**
- * Checks if a table exists.
- */
-export async function tableExists(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-): Promise<boolean> {
-  try {
-    const tables = await listTables(client);
-    return tables.includes(tableName);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Inserts (puts) a single item into a DynamoDB table.
- */
-export async function putItem(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  item: any,
-): Promise<void> {
-  await client.send(
-    new PutItemCommand({
-      TableName: tableName,
-      Item: marshall(item),
-    }),
-  );
-}
-
-/**
- * Retrieves a single item by its primary key.
- */
-export async function getItem(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  key: Record<string, any>,
-): Promise<any | null> {
-  const result = await client.send(
-    new GetItemCommand({
-      TableName: tableName,
-      Key: marshall(key),
-      ConsistentRead: true,
-    }),
-  );
-  return result.Item ? unmarshall(result.Item) : null;
-}
-
-/**
- * Batch gets multiple items by keys.
- */
-export async function getBatch(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  ids: string[],
-): Promise<any[]> {
-  if (!ids.length) return [];
-  const keys = ids.map((id) => marshall({ id }));
-  const params = {
-    RequestItems: {
-      [tableName]: {
-        Keys: keys,
-      },
-    },
-  };
-  const result = await client.send(new BatchGetItemCommand(params));
-  const items = result.Responses?.[tableName] || [];
-  return items.map((item) => unmarshall(item));
-}
-
-/**
- * Scans a table, with optional filter expression and values.
- */
-export async function scan(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  filterExpression?: string,
-  expressionAttributeValues?: Record<string, any>,
-): Promise<any[]> {
-  const params: any = { TableName: tableName };
-  if (filterExpression) params.FilterExpression = filterExpression;
-  if (expressionAttributeValues)
-    params.ExpressionAttributeValues = marshall(expressionAttributeValues);
-
-  const result = await client.send(new ScanCommand(params));
-  return result.Items ? result.Items.map((item) => unmarshall(item)) : [];
-}
-
-/**
- * Queries a table with the given key condition and optional index.
- */
-export async function query(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  keyConditionExpression: string,
-  expressionAttributeValues: Record<string, any>,
-  indexName?: string,
-): Promise<any[]> {
-  const params: any = {
-    TableName: tableName,
-    KeyConditionExpression: keyConditionExpression,
-    ExpressionAttributeValues: marshall(expressionAttributeValues),
-  };
-  if (indexName) params.IndexName = indexName;
-
-  const result = await client.send(new QueryCommand(params));
-  return result.Items ? result.Items.map((item) => unmarshall(item)) : [];
-}
-
-/**
- * Updates an item by key with a given update expression.
- */
-export async function update(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  key: Record<string, any>,
-  updateExpression: string,
-  expressionAttributeValues: Record<string, any>,
-  expressionAttributeNames?: Record<string, string>,
-): Promise<any> {
-  const params: any = {
-    TableName: tableName,
-    Key: marshall(key),
-    UpdateExpression: updateExpression,
-    ExpressionAttributeValues: marshall(expressionAttributeValues),
-    ReturnValues: "ALL_NEW",
-  };
-  if (expressionAttributeNames) params.ExpressionAttributeNames = expressionAttributeNames;
-  const result = await client.send(new UpdateItemCommand(params));
-  return result.Attributes ? unmarshall(result.Attributes) : null;
-}
-
-/**
- * Deletes an item by key.
- */
-export async function deleteItem(
-  client: DynamoDBClient = getClient(),
-  tableName: string,
-  key: Record<string, any>,
-): Promise<void> {
-  await client.send(
-    new DeleteItemCommand({
-      TableName: tableName,
-      Key: marshall(key),
-    }),
-  );
-}

package/serverless/src/lib/http.ts

@@ -1,261 +0,0 @@
-import { APIGatewayProxyResult } from "aws-lambda";
-import axios, { AxiosResponse, AxiosError } from "axios";
-
-/**
- * Standardized API response body structure
- */
-export interface ApiResponse<T = any> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-}
-
-/**
- * Default CORS headers applied to all HTTP responses
- */
-const defaultHeaders = {
-  "Content-Type": "application/json",
-  "Access-Control-Allow-Origin": "*",
-  "Access-Control-Allow-Headers": "Content-Type,Authorization",
-  "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,OPTIONS",
-};
-
-/**
- * Default Axios instance with common configuration
- */
-const httpClient = axios.create({
-  timeout: 30000, // 30 second timeout
-  headers: {
-    "Content-Type": "application/json",
-  },
-});
-
-/**
- * Creates a successful HTTP response with data
- * @param data - The response data payload
- * @param statusCode - HTTP status code (defaults to 200)
- * @param message - Optional success message
- * @returns Formatted HTTP response as APIGatewayProxyResult
- */
-export function success<T>(data: T, statusCode = 200, message?: string): APIGatewayProxyResult {
-  const response: ApiResponse<T> = {
-    success: true,
-    data,
-    ...(message && { message }),
-  };
-
-  return {
-    statusCode,
-    headers: defaultHeaders,
-    body: JSON.stringify(response),
-  };
-}
-
-/**
- * Creates an error HTTP response
- * @param errorMessage - Error message to return
- * @param statusCode - HTTP status code (defaults to 500)
- * @returns Formatted HTTP error response as APIGatewayProxyResult
- */
-export function error(errorMessage: string, statusCode = 500): APIGatewayProxyResult {
-  const response: ApiResponse = {
-    success: false,
-    error: errorMessage,
-  };
-
-  return {
-    statusCode,
-    headers: defaultHeaders,
-    body: JSON.stringify(response),
-  };
-}
-
-/**
- * Creates a 400 Bad Request response
- * @param errorMessage - Error message describing what was invalid
- * @returns HTTP 400 response as APIGatewayProxyResult
- */
-export function badRequest(errorMessage: string): APIGatewayProxyResult {
-  return error(errorMessage, 400);
-}
-
-/**
- * Creates a 401 Unauthorized response
- * @param errorMessage - Error message (defaults to "Unauthorized")
- * @returns HTTP 401 response as APIGatewayProxyResult
- */
-export function unauthorized(errorMessage: string = "Unauthorized"): APIGatewayProxyResult {
-  return error(errorMessage, 401);
-}
-
-/**
- * Creates a 403 Forbidden response
- * @param errorMessage - Error message (defaults to "Forbidden")
- * @returns HTTP 403 response as APIGatewayProxyResult
- */
-export function forbidden(errorMessage: string = "Forbidden"): APIGatewayProxyResult {
-  return error(errorMessage, 403);
-}
-
-/**
- * Creates a 404 Not Found response
- * @param errorMessage - Error message (defaults to "Not Found")
- * @returns HTTP 404 response as APIGatewayProxyResult
- */
-export function notFound(errorMessage: string = "Not Found"): APIGatewayProxyResult {
-  return error(errorMessage, 404);
-}
-
-/**
- * Creates a 409 Conflict response
- * @param errorMessage - Error message describing the conflict
- * @returns HTTP 409 response as APIGatewayProxyResult
- */
-export function conflict(errorMessage: string): APIGatewayProxyResult {
-  return error(errorMessage, 409);
-}
-
-/**
- * Safely parses JSON request body with error handling
- * @param body - Raw request body string from API Gateway event
- * @returns Parsed JSON object
- * @throws Error if body is null/empty or contains invalid JSON
- */
-export function parseBody<T = any>(body: string | null): T {
-  if (!body) {
-    throw new Error("Request body is required");
-  }
-
-  try {
-    return JSON.parse(body);
-  } catch {
-    throw new Error("Invalid JSON in request body");
-  }
-}
-
-/**
- * Makes an HTTP GET request using Axios
- * @param url - The URL to make the GET request to
- * @param headers - Optional additional headers
- * @returns Promise resolving to the response data
- */
-export async function get<T = any>(url: string, headers?: Record<string, string>): Promise<T> {
-  try {
-    const response: AxiosResponse<T> = await httpClient.get(url, { headers });
-    return response.data;
-  } catch (err) {
-    throw handleAxiosError(err);
-  }
-}
-
-/**
- * Makes an HTTP POST request using Axios
- * @param url - The URL to make the POST request to
- * @param data - The data to send in the request body
- * @param headers - Optional additional headers
- * @returns Promise resolving to the response data
- */
-export async function post<T = any>(
-  url: string,
-  data?: any,
-  headers?: Record<string, string>,
-): Promise<T> {
-  try {
-    const response: AxiosResponse<T> = await httpClient.post(url, data, { headers });
-    return response.data;
-  } catch (err) {
-    throw handleAxiosError(err);
-  }
-}
-
-/**
- * Makes an HTTP PUT request using Axios
- * @param url - The URL to make the PUT request to
- * @param data - The data to send in the request body
- * @param headers - Optional additional headers
- * @returns Promise resolving to the response data
- */
-export async function put<T = any>(
-  url: string,
-  data?: any,
-  headers?: Record<string, string>,
-): Promise<T> {
-  try {
-    const response: AxiosResponse<T> = await httpClient.put(url, data, { headers });
-    return response.data;
-  } catch (err) {
-    throw handleAxiosError(err);
-  }
-}
-
-/**
- * Makes an HTTP DELETE request using Axios
- * @param url - The URL to make the DELETE request to
- * @param headers - Optional additional headers
- * @returns Promise resolving to the response data
- */
-export async function del<T = any>(url: string, headers?: Record<string, string>): Promise<T> {
-  try {
-    const response: AxiosResponse<T> = await httpClient.delete(url, { headers });
-    return response.data;
-  } catch (err) {
-    throw handleAxiosError(err);
-  }
-}
-
-/**
- * Handles Axios errors and converts them to standardized Error objects
- * @param err - The Axios error or unknown error
- * @returns A standardized Error object
- */
-function handleAxiosError(err: unknown): Error {
-  if (axios.isAxiosError(err)) {
-    const axiosError = err as AxiosError;
-
-    if (axiosError.response) {
-      // Server responded with error status
-      return new Error(`HTTP ${axiosError.response.status}: ${axiosError.response.statusText}`);
-    } else if (axiosError.request) {
-      // Request was made but no response received
-      return new Error("Network error: No response received");
-    } else {
-      // Something else happened
-      return new Error(`Request error: ${axiosError.message}`);
-    }
-  }
-  return new Error("Unknown HTTP error");
-}
-
-/**
- * Converts caught errors into standardized HTTP error responses
- * Automatically maps common error types to appropriate status codes
- * @param err - The caught error (unknown type for safety)
- * @returns Formatted HTTP error response as APIGatewayProxyResult
- */
-export function handleError(err: unknown): APIGatewayProxyResult {
-  let errorMessage = "Unknown error";
-  let statusCode = 500;
-
-  if (err instanceof Error) {
-    errorMessage = err.message;
-
-    // Map specific error messages to appropriate status codes
-    if (err.message.includes("required") || err.message.includes("Invalid JSON")) {
-      statusCode = 400;
-    } else if (err.message.includes("HTTP 401")) {
-      statusCode = 401;
-    } else if (err.message.includes("HTTP 403")) {
-      statusCode = 403;
-    } else if (err.message.includes("HTTP 404")) {
-      statusCode = 404;
-    } else if (err.message.includes("Network error")) {
-      statusCode = 503; // Service Unavailable
-    }
-  }
-
-  return error(errorMessage, statusCode);
-}
-
-// Export the configured Axios instance for advanced usage
-export { httpClient };

package/serverless/src/lib/seed.ts

@@ -1,57 +0,0 @@
-/**
- * Seeds a DynamoDB table with the provided data array.
- * Logs errors for each failed item insert but continues seeding.
- *
- * @param put - Function to perform the insert (e.g. yourTablePutFn(tableName, item))
- * @param tableName - The table to seed
- * @param data - Array of items to insert; can be any shape
- */
-export async function seedTable(
-  put: (tableName: string, item: any) => Promise<void>,
-  tableName: string,
-  data: any[],
-): Promise<void> {
-  console.log(`Seeding ${tableName} with ${data.length} items...`);
-  for (const item of data) {
-    try {
-      await put(tableName, item);
-    } catch (error) {
-      console.error(`  ❌ Error seeding ${tableName}:`, error);
-    }
-  }
-}
-
-/**
- * Generates a data array, optionally post-processes it, and seeds it into a DynamoDB table.
- * Returns the data array after processing.
- *
- * @param put - Function to perform the insert (e.g. yourTablePutFn(tableName, item))
- * @param tableName - The table to seed
- * @param generator - Function generating the raw seed data array
- * @param postProcess - Optional transformation or filtering to apply to the generated data
- */
-export async function generateAndSeed<T>(
-  put: (tableName: string, item: T) => Promise<void>,
-  tableName: string,
-  generator: () => T[],
-  postProcess?: (data: T[]) => T[] | void
-): Promise<T[]> {
-  const start = performance.now();
-  let data = generator();
-  if (postProcess) {
-    const result = postProcess(data);
-    if (result) data = result;
-  }
-  // Seed with dependency-injected put
-  for (const item of data) {
-    try {
-      await put(tableName, item);
-    } catch (error) {
-      console.error(`  ❌ Error seeding ${tableName}:`, error);
-    }
-  }
-  const end = performance.now();
-
-  console.log(`✅ ${tableName} generated & seeded in ${((end - start) / 1000).toFixed(3)}s (${data.length} items)\n`);
-  return data;
-}