@chainsaws/ssm

Typed Systems Manager wrapper for Node.js with a Python-style API for Parameter Store, Run Command, and Automation.

Requirements

• Node.js >= 22
• AWS credentials available through the normal AWS SDK resolution chain, or explicit static credentials in config

Installation

npm install @chainsaws/ssm
yarn add @chainsaws/ssm
pnpm add @chainsaws/ssm

This package is ESM-only.

Quick Start

import { SSMAPI } from "@chainsaws/ssm";

const ssm = new SSMAPI({
  region: "ap-northeast-2",
});

await ssm.put_parameter({
  name: "/demo/key",
  value: "secret",
  type: "SecureString",
  tier: "Advanced",
  overwrite: true,
});

const parameter = await ssm.get_parameter("/demo/key", true);
console.log(parameter.Value);

Package Surface

Most applications only need:

• SSMAPI
• create_ssm_api_config(...)
• ParameterConfig
• CommandConfig
• AutomationExecutionConfig

The package also exports:

• LowLevelSSM
• filtered response types such as GetParameterResult
• structural compatibility types such as SessionConfig, MaintenanceWindowConfig, and PatchBaselineConfig

Creating the Client

All config fields are optional.

import { SSMAPI, create_ssm_api_config } from "@chainsaws/ssm";

const config = create_ssm_api_config({
  region: "ap-northeast-2",
  endpoint: process.env.SSM_ENDPOINT,
  max_pool_connections: 100,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    sessionToken: process.env.AWS_SESSION_TOKEN,
  },
});

const ssm = new SSMAPI(config);

When fields are omitted, the AWS SDK falls back to its normal credential and region resolution chain.

SSMAPI intentionally covers the currently ported Python surface:

• Parameter Store put/get/delete
• Run Command send/get invocation
• Automation start/get execution

Parameter Store

put_parameter

const result = await ssm.put_parameter({
  name: "/prod/db/password",
  value: "secret123",
  type: "SecureString",
  description: "database password",
  tier: "Advanced",
  overwrite: true,
  tags: {
    env: "prod",
  },
  key_id: "alias/app",
  data_type: "text",
});

console.log(result.Version);

get_parameter

const parameter = await ssm.get_parameter("/prod/db/password", true);

console.log(parameter.Name);
console.log(parameter.Value);

Object-style requests are also supported:

const parameter = await ssm.get_parameter({
  name: "/prod/db/password",
  decrypt: true,
});

The high-level method filters the raw AWS payload down to:

• Name
• Type
• Value
• Version
• Selector
• SourceResult
• LastModifiedDate
• ARN
• DataType

This keeps the public contract stable even if the AWS SDK returns additional fields in the nested Parameter object.

delete_parameter

await ssm.delete_parameter("/prod/db/password");

Run Command

send_command

const commandId = await ssm.send_command(
  [
    {
      Key: ["tag:Environment"],
      Values: ["Production"],
    },
  ],
  "AWS-RunShellScript",
  {
    commands: ["echo hello"],
  },
  "Deploy step",
  3600
);

Arguments are positional for parity with the Python API:

1. targets
2. document_name
3. parameters
4. comment
5. timeout_seconds

timeout_seconds is validated to be between 60 and 172800.

const commandId = await ssm.send_command({
  targets: [
    {
      Key: ["tag:Environment"],
      Values: ["Production"],
    },
  ],
  document_name: "AWS-RunShellScript",
  parameters: {
    commands: ["echo hello"],
  },
  comment: "Deploy step",
  timeout_seconds: 3600,
});

get_command_invocation

const invocation = await ssm.get_command_invocation("cmd-123", "i-123");

console.log(invocation.status);
console.log(invocation.standard_output_content);

Automation

start_automation

const executionId = await ssm.start_automation(
  "AWS-RestartEC2Instance",
  {
    InstanceId: ["i-123"],
  },
  undefined,
  undefined,
  "2",
  "1"
);

Arguments:

1. document_name
2. parameters
3. target_parameter_name
4. targets
5. max_concurrency
6. max_errors

const executionId = await ssm.start_automation({
  document_name: "AWS-RestartEC2Instance",
  parameters: {
    InstanceId: ["i-123"],
  },
  max_concurrency: "2",
  max_errors: "1",
});

get_automation_execution

const execution = await ssm.get_automation_execution(executionId);

console.log(execution.status);
console.log(execution.failure_message);

Low-Level Adapter

LowLevelSSM is also exported for advanced callers who want the thin AWS SDK adapter directly.

import { LowLevelSSM } from "@chainsaws/ssm";

const low = new LowLevelSSM({ region: "ap-northeast-2" });

const commandId = await low.send_command({
  targets: [{ Key: ["InstanceIds"], Values: ["i-123"] }],
  document_name: "AWS-RunShellScript",
  parameters: {
    commands: ["echo hello"],
  },
});

The low-level adapter is useful when you want AWS-shaped requests without the smaller filtered high-level response contracts.

Exported Models

The package exports the currently useful SSM model types, including:

• SSMAPIConfig
• ParameterConfig
• ParameterDetails
• PutParameterResult
• GetParameterResult
• CommandConfig
• CommandInvocation
• AutomationExecutionConfig
• AutomationExecution

It also exports additional structural types mirroring the Python package surface:

• Parameter
• ParameterHistory
• ParameterLabel
• ParameterTier
• ParameterPolicy
• ParameterSearch
• SessionConfig
• SessionDetails
• PatchBaselineConfig
• PatchSummary
• StateConfig
• StateAssociation
• InventoryConfig
• MaintenanceWindowConfig
• MaintenanceWindow
• MaintenanceTask

Compatibility Notes

The package intentionally stops at the surface already ported from Python. It does not yet implement the broader Systems Manager feature set implied by every structural type exported from models.ts.

Development

pnpm --filter @chainsaws/ssm check-types
pnpm --filter @chainsaws/ssm test
pnpm --filter @chainsaws/ssm lint
pnpm --filter @chainsaws/ssm build

License

MIT