@johnmmackey/app-toolkit 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# app-toolkit
+
+A collection of shared utility functions for common application tasks.
+
+## Installation
+
+```bash
+npm install @johnmmackey/app-toolkit
+```
+
+## Usage
+
+```ts
+import { } from '@johnmmackey/app-toolkit';
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18
+- npm >= 9
+
+### Setup
+
+```bash
+npm install
+```
+
+### Scripts
+
+| Command | Description |
+|---|---|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run dev` | Build in watch mode |
+| `npm test` | Run tests |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run typecheck` | Type-check without emitting |
+| `npm run lint` | Lint source files |
+
+### Project Structure
+
+```
+app-toolkit/
+├── src/
+│   └── index.ts       # Public API entry point
+├── dist/              # Compiled output (generated)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## API
+
+### `getLogger(label: string): Logger`
+
+Returns a [Winston](https://github.com/winstonjs/winston) child logger bound to the given module label.
+
+Every log entry is emitted as structured JSON with a `timestamp` and `label` field, ready to be ingested by any log aggregator.
+
+```ts
+import { getLogger } from '@johnmmackey/app-toolkit';
+
+const log = getLogger('my-module');
+
+log.info('server started', { port: 3000 });
+// → {"level":"info","label":"my-module","port":3000,"timestamp":"..."}
+
+log.error('unexpected failure', new Error('oops'));
+// → {"level":"error","label":"my-module","message":"oops","stack":"...","timestamp":"..."}
+```
+
+**Environment variables**
+
+| Variable | Default | Description |
+|---|---|---|
+| `LOG_LEVEL` | `"info"` | Global log level (`error` \| `warn` \| `info` \| `debug`) |
+| `APP_DEBUG_MODULES` | — | Space-separated list of [micromatch](https://github.com/micromatch/micromatch) glob patterns. Any logger whose `label` matches is promoted to `debug` level regardless of `LOG_LEVEL`. |
+
+```bash
+# promote only the "db" and "auth-*" loggers to debug
+APP_DEBUG_MODULES="db auth-*" node dist/server.js
+```
+
+---
+
+### `getAssumedRoleCredentials(roleArn: string, region?: string): Promise<AwsCredentialIdentity>`
+
+Assumes an AWS IAM role via STS and returns temporary credentials. Results are cached in-process and automatically refreshed 5 minutes before expiry.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `roleArn` | `string` | — | ARN of the role to assume (required) |
+| `region` | `string` | `"us-east-1"` | AWS region for the STS API call |
+
+```ts
+import { getAssumedRoleCredentials } from '@johnmmackey/app-toolkit';
+
+const creds = await getAssumedRoleCredentials(
+  'arn:aws:iam::123456789012:role/MyRole',
+  'eu-west-1',
+);
+
+// Pass credentials to any AWS SDK client
+import { S3Client } from '@aws-sdk/client-s3';
+const s3 = new S3Client({ credentials: creds, region: 'eu-west-1' });
+```
+
+**Credential resolution (STS client)**
+- **Dev**: relies on environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) or a shared credentials file.
+- **Prod / ECS / Lambda**: relies on the instance / task metadata service (IMDSv2).
+
+---
+
+### Types
+
+Named types used by this package are re-exported from the `/types` sub-path and also via the `AppToolkitTypes` namespace for convenience.
+
+```ts
+// Individual type imports
+import type { AppLogger, AwsCredentialIdentity } from '@johnmmackey/app-toolkit';
+
+// Namespace import
+import type { AppToolkitTypes } from '@johnmmackey/app-toolkit';
+type MyLogger = AppToolkitTypes.AppLogger;
+```
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes with tests
+3. Run `npm test` and `npm run typecheck` to verify
+4. Open a pull request
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,42 @@
+import * as winston from 'winston';
+import winston__default from 'winston';
+import * as _aws_sdk_types from '@aws-sdk/types';
+import { AwsCredentialIdentity } from '@aws-sdk/types';
+
+/**
+ * Application-wide Winston logger.
+ *
+ * Usage:
+ *   import { getLogger } from "@/lib/logger";
+ *   const log = getLogger("my-module");
+ *   log.info("something happened", { extra: "metadata" });
+ *
+ * Log level is controlled by the LOG_LEVEL environment variable (default: "info").
+ * Valid values: error | warn | info | debug
+ *
+ * All output is JSON with a timestamp, making it trivial to ingest into any
+ * log aggregator. The `label` field identifies the originating module.
+ */
+
+/**
+ * Returns a child logger bound to the given label.
+ * The label is included in every log entry as `{ label: "..." }`.
+ */
+declare function getLogger(label: string): winston__default.Logger;
+
+declare function getAssumedRoleCredentials(roleArn: string, region?: string): Promise<AwsCredentialIdentity>;
+
+/**
+ * Convenience namespace — import everything from here to avoid multiple
+ * type-only imports:
+ *
+ * @example
+ * import type { AppToolkitTypes } from '@common-modules/app-toolkit';
+ * type MyLogger = AppToolkitTypes.AppLogger;
+ */
+declare namespace AppToolkitTypes {
+    type AppLogger = winston.Logger;
+    type AwsCredentialIdentity = _aws_sdk_types.AwsCredentialIdentity;
+}
+
+export { AppToolkitTypes, getAssumedRoleCredentials, getLogger };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import * as winston from 'winston';
+import winston__default from 'winston';
+import * as _aws_sdk_types from '@aws-sdk/types';
+import { AwsCredentialIdentity } from '@aws-sdk/types';
+
+/**
+ * Application-wide Winston logger.
+ *
+ * Usage:
+ *   import { getLogger } from "@/lib/logger";
+ *   const log = getLogger("my-module");
+ *   log.info("something happened", { extra: "metadata" });
+ *
+ * Log level is controlled by the LOG_LEVEL environment variable (default: "info").
+ * Valid values: error | warn | info | debug
+ *
+ * All output is JSON with a timestamp, making it trivial to ingest into any
+ * log aggregator. The `label` field identifies the originating module.
+ */
+
+/**
+ * Returns a child logger bound to the given label.
+ * The label is included in every log entry as `{ label: "..." }`.
+ */
+declare function getLogger(label: string): winston__default.Logger;
+
+declare function getAssumedRoleCredentials(roleArn: string, region?: string): Promise<AwsCredentialIdentity>;
+
+/**
+ * Convenience namespace — import everything from here to avoid multiple
+ * type-only imports:
+ *
+ * @example
+ * import type { AppToolkitTypes } from '@common-modules/app-toolkit';
+ * type MyLogger = AppToolkitTypes.AppLogger;
+ */
+declare namespace AppToolkitTypes {
+    type AppLogger = winston.Logger;
+    type AwsCredentialIdentity = _aws_sdk_types.AwsCredentialIdentity;
+}
+
+export { AppToolkitTypes, getAssumedRoleCredentials, getLogger };

package/dist/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getAssumedRoleCredentials: () => getAssumedRoleCredentials,
+  getLogger: () => getLogger
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/logger.ts
+var import_winston = __toESM(require("winston"));
+var import_micromatch = __toESM(require("micromatch"));
+var { combine, timestamp, json, errors } = import_winston.default.format;
+var baseLogger = import_winston.default.createLogger({
+  level: process.env.LOG_LEVEL ?? "info",
+  format: combine(
+    errors({ stack: true }),
+    timestamp(),
+    json()
+  ),
+  transports: [new import_winston.default.transports.Console()]
+});
+function getLogger(label) {
+  return baseLogger.child({
+    label,
+    level: process.env.APP_DEBUG_MODULES && import_micromatch.default.isMatch(label, process.env.APP_DEBUG_MODULES.split(" ")) ? "debug" : baseLogger.level
+  });
+}
+
+// src/aws-role-credentials.ts
+var import_client_sts = require("@aws-sdk/client-sts");
+var DEFAULT_REGION = "us-east-1";
+var cachedCredentials = null;
+var credentialsExpiration = null;
+async function getAssumedRoleCredentials(roleArn, region = DEFAULT_REGION) {
+  if (cachedCredentials && credentialsExpiration && /* @__PURE__ */ new Date() < credentialsExpiration) {
+    return cachedCredentials;
+  }
+  if (!roleArn) {
+    throw new Error("roleArn is required to assume role");
+  }
+  const stsClient = new import_client_sts.STSClient({
+    region
+  });
+  const command = new import_client_sts.AssumeRoleCommand({
+    RoleArn: roleArn,
+    RoleSessionName: `app-${Date.now()}`,
+    DurationSeconds: 3600
+    // 1 hour
+  });
+  const response = await stsClient.send(command);
+  if (!response.Credentials) {
+    throw new Error("Failed to assume role: no credentials returned");
+  }
+  cachedCredentials = {
+    accessKeyId: response.Credentials.AccessKeyId,
+    secretAccessKey: response.Credentials.SecretAccessKey,
+    sessionToken: response.Credentials.SessionToken
+  };
+  credentialsExpiration = new Date(response.Credentials.Expiration.getTime() - 5 * 60 * 1e3);
+  return cachedCredentials;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAssumedRoleCredentials,
+  getLogger
+});

package/dist/index.mjs

@@ -0,0 +1,57 @@
+// src/logger.ts
+import winston from "winston";
+import micromatch from "micromatch";
+var { combine, timestamp, json, errors } = winston.format;
+var baseLogger = winston.createLogger({
+  level: process.env.LOG_LEVEL ?? "info",
+  format: combine(
+    errors({ stack: true }),
+    timestamp(),
+    json()
+  ),
+  transports: [new winston.transports.Console()]
+});
+function getLogger(label) {
+  return baseLogger.child({
+    label,
+    level: process.env.APP_DEBUG_MODULES && micromatch.isMatch(label, process.env.APP_DEBUG_MODULES.split(" ")) ? "debug" : baseLogger.level
+  });
+}
+
+// src/aws-role-credentials.ts
+import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
+var DEFAULT_REGION = "us-east-1";
+var cachedCredentials = null;
+var credentialsExpiration = null;
+async function getAssumedRoleCredentials(roleArn, region = DEFAULT_REGION) {
+  if (cachedCredentials && credentialsExpiration && /* @__PURE__ */ new Date() < credentialsExpiration) {
+    return cachedCredentials;
+  }
+  if (!roleArn) {
+    throw new Error("roleArn is required to assume role");
+  }
+  const stsClient = new STSClient({
+    region
+  });
+  const command = new AssumeRoleCommand({
+    RoleArn: roleArn,
+    RoleSessionName: `app-${Date.now()}`,
+    DurationSeconds: 3600
+    // 1 hour
+  });
+  const response = await stsClient.send(command);
+  if (!response.Credentials) {
+    throw new Error("Failed to assume role: no credentials returned");
+  }
+  cachedCredentials = {
+    accessKeyId: response.Credentials.AccessKeyId,
+    secretAccessKey: response.Credentials.SecretAccessKey,
+    sessionToken: response.Credentials.SessionToken
+  };
+  credentialsExpiration = new Date(response.Credentials.Expiration.getTime() - 5 * 60 * 1e3);
+  return cachedCredentials;
+}
+export {
+  getAssumedRoleCredentials,
+  getLogger
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@johnmmackey/app-toolkit",
+  "version": "0.1.0",
+  "description": "A collection of shared utility functions",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "utilities",
+    "toolkit",
+    "helpers"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sts": "^3.1009.0",
+    "@aws-sdk/types": "^3.973.6",
+    "micromatch": "^4.0.8",
+    "winston": "^3.19.0"
+  }
+}