@keystrokehq/dynamodb

Amazon DynamoDB integration for Keystroke workflows: tables, items, batch APIs, transactions, PartiQL, backups, imports, exports, global tables, PITR, resource policies, tags, Kinesis streaming destinations, and DynamoDB Streams polling triggers.

Credential sets live under src/credential-sets. Operations live under src/operations. Shared Zod schemas live under src/schemas. Stream trigger modules live under src/triggers.

Installation

pnpm add @keystrokehq/dynamodb

Credentials

DynamoDB has no consumer-style OAuth; access is IAM-based. The dynamodb credential set accepts a long-lived access-key pair and optional STS AssumeRole configuration.

import { dynamodbCredentialSet } from '@keystrokehq/dynamodb/credential-sets';

dynamodbCredentialSet.id; // 'dynamodb'

Required vault keys:

| Key | Required | Description | |-----|----------|-------------| | AWS_ACCESS_KEY_ID | yes | Long-lived access key id, or base key for AssumeRole. | | AWS_SECRET_ACCESS_KEY | yes | Paired secret. | | AWS_REGION | yes | e.g. us-east-1. | | AWS_SESSION_TOKEN | no | Provide when passing temporary credentials directly. | | AWS_DYNAMODB_ENDPOINT | no | Full endpoint override (VPC, FIPS, DynamoDB Local). | | AWS_ASSUME_ROLE_ARN | no | If set, the base keys are used only to sign STS AssumeRole. | | AWS_ASSUME_ROLE_SESSION_NAME | no | Defaults to keystroke-dynamodb-{timestamp}. | | AWS_ASSUME_ROLE_EXTERNAL_ID | no | For cross-account trust. | | AWS_ASSUME_ROLE_DURATION_SECONDS | no | 900–43200. Default 3600. |

Operations

Import operations from the canonical barrel. Each export also has a *Tool alias for agent tooling.

import {
  createTableOperation,
  getItemOperation,
  putItemOperation,
  queryOperation,
} from '@keystrokehq/dynamodb/operations';

await putItemOperation.run(
  {
    TableName: 'Orders',
    Item: { pk: { S: 'user#1' }, sk: { S: 'order#1' }, total: { N: '99.50' } },
  },
  { credentials: { dynamodb: { AWS_ACCESS_KEY_ID: '...', AWS_SECRET_ACCESS_KEY: '...', AWS_REGION: 'us-east-1' } } }
);

const page = await queryOperation.run(
  {
    TableName: 'Orders',
    KeyConditionExpression: '#pk = :pk',
    ExpressionAttributeNames: { '#pk': 'pk' },
    ExpressionAttributeValues: { ':pk': { S: 'user#1' } },
  },
  { credentials: { dynamodb: { AWS_ACCESS_KEY_ID: '...', AWS_SECRET_ACCESS_KEY: '...', AWS_REGION: 'us-east-1' } } }
);

Schemas

import { attributeValueSchema, streamRecordSchema } from '@keystrokehq/dynamodb/schemas';

Triggers

Stream polling triggers are authored from internal modules under src/triggers/ (for example streamRecordInserted, itemPolled). Curated event payload schemas live in src/events.ts and are re-used by trigger configs.

License

MIT.