@rpallas/outcrop-runtime

Lambda runtime helpers for services built with @rpallas/outcrop: structured logging, config and secret resolution through the platform SSM contract, EventBridge envelopes and thin handler wrappers for HTTP, SQS and EventBridge.

The package is CDK-free and depends only on Powertools for AWS Lambda and the AWS SDK v3 clients it wraps.

npm install @rpallas/outcrop-runtime

Environment

The platform constructs inject PLATFORM_PROJECT, PLATFORM_SERVICE, PLATFORM_ENV, PLATFORM_PREVIEW_ID, PLATFORM_SSM_ROOT, PLATFORM_FUNCTION and LOG_LEVEL.

import { platformEnv, requireEnv } from "@rpallas/outcrop-runtime";

const env = platformEnv(); // throws if PLATFORM_SERVICE / PLATFORM_ENV are missing
env.service; // "orders"
env.isPreview; // true inside a preview stack
const table = requireEnv("TABLE_NAME");

Logger

createLogger() returns a Powertools Logger whose service name and persistent keys (env, previewId, functionName) come from the platform environment. getLogger() is a lazy module singleton.

import { getLogger } from "@rpallas/outcrop-runtime";

const logger = getLogger();
logger.info("order created", { orderId });

Parameters

Cached (5 minutes by default) reads of the SSM contract written by @rpallas/outcrop-account.

import { getParameter, platformParams } from "@rpallas/outcrop-runtime";

const params = platformParams();
const accountId = await params.account.id();
const busName = await params.env().eventBusName(); // env defaults to PLATFORM_ENV
const topic = await params.env("prod").alertTopicArn("critical");
const flag = await params.config("feature-flags");
const apiUrl = await params.service("billing", "api-url");

const raw = await getParameter("/my/own/parameter", { maxAge: 60, decrypt: true });

PlatformParameterPaths (also exported) builds the same paths without reading them.

Secrets

import { getSecret, getSecretJson, getConfig } from "@rpallas/outcrop-runtime";

// A full ARN is read directly; a short name is resolved via /platform/secrets/{name}/arn.
const apiKey = await getSecret("third-party-api-key");
const db = await getSecretJson("database", { parse: DbCredentials.parse }); // e.g. a zod schema
const region = await getConfig("primary-region"); // /platform/config/primary-region

Events

Events are published to EventBridge with detail-type = eventName, source = PLATFORM_SERVICE and a { eventName, eventBody } envelope as detail. The bus comes from EVENT_BUS_NAME unless busName is passed.

import { publishEvent, publishEvents, parseEnvelope } from "@rpallas/outcrop-runtime";

await publishEvent("OrderCreated", { orderId, total });
await publishEvents(items.map((item) => ({ eventName: "ItemShipped", eventBody: item })));

// Bodies larger than 200 KB can be offloaded to S3; consumers use resolveEnvelope().
await publishEvent("ReportGenerated", report, { offload: { bucket: process.env.EVENTS_BUCKET } });

parseEnvelope / parseSqsEnvelope validate inline envelopes synchronously; resolveEnvelope / resolveSqsEnvelope also download offloaded bodies.

HTTP handler

import {
  withHttpHandler,
  json,
  parseJsonBody,
  pathParam,
  notFound,
} from "@rpallas/outcrop-runtime";

export const handler = withHttpHandler(async (event) => {
  const id = pathParam(event, "id");
  const body = parseJsonBody(event, UpdateOrder.parse); // 400 on invalid JSON or schema failure
  const order = await orders.update(id, body);
  if (!order) throw notFound("Order not found", { id });
  return json(200, order);
});

HttpErrors become { error, details } JSON responses with their status code; anything else is logged with its stack and returned as a 500. Every response carries an x-correlation-id header (taken from the request header, the API Gateway request id or the Lambda request id).

SQS handler

import { withSqsHandler, parseSqsEnvelope } from "@rpallas/outcrop-runtime";

export const handler = withSqsHandler(
  async (record) => {
    const { eventName, eventBody } = parseSqsEnvelope(record);
    await process(eventName, eventBody);
  },
  { concurrency: 5 },
);

Failed records are logged and returned as batchItemFailures; enable ReportBatchItemFailures on the event source mapping.

EventBridge handler

import { withEventHandler } from "@rpallas/outcrop-runtime";

export const handler = withEventHandler<OrderCreated>(
  async ({ eventName, eventBody }) => {
    await fulfil(eventBody);
  },
  { parse: OrderCreated.parse },
);

Generic wrapper

withHandler(fn, { logger?, logEvent?, onError? }) is the building block used by the wrappers above: it attaches the Lambda context (including cold start) to the logger, logs the event (debug, or info when POWERTOOLS_LOGGER_LOG_EVENT=true), adds a per-invocation correlationId key, logs and rethrows errors and resets the temporary keys afterwards.

Telemetry layer

@rpallas/outcrop-runtime/layer exports TELEMETRY_LAYER_DIR, TELEMETRY_REQUIRE_PATH and TELEMETRY_NODE_OPTIONS for building an opt-in Lambda layer that writes JSON log lines straight to the Lambda Telemetry API file descriptor. See layer/README.md for the mechanism.

import { TELEMETRY_LAYER_DIR, TELEMETRY_NODE_OPTIONS } from "@rpallas/outcrop-runtime/layer";

const layer = new lambda.LayerVersion(this, "Telemetry", {
  code: lambda.Code.fromAsset(TELEMETRY_LAYER_DIR),
});
fn.addLayers(layer);
fn.addEnvironment("NODE_OPTIONS", TELEMETRY_NODE_OPTIONS);
fn.addEnvironment("PLATFORM_TELEMETRY_FD", "1");

Classes

HttpError

Defined in: http.ts:4

An error that maps directly to an HTTP response.

Extends

Error

Constructors

Constructor

new HttpError(
   statusCode, 
   message, 
   details?
): HttpError;

Defined in: http.ts:5

Parameters

Parameter	Type
`statusCode`	`number`
`message`	`string`
`details?`	`unknown`

Returns

HttpError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Defined in
`details?`	`readonly`	`unknown`	http.ts:8
`statusCode`	`readonly`	`number`	http.ts:6

PlatformParameterPaths

Defined in: paths.ts:19

Builds the well-known SSM parameter paths of the platform contract. Written by @rpallas/outcrop-account, read by the @rpallas/outcrop constructs at synth time and by this package at runtime.

This is a CDK-free mirror of PlatformParameterPaths in @rpallas/outcrop.

Constructors

Constructor

new PlatformParameterPaths(rootPrefix?): PlatformParameterPaths;

Defined in: paths.ts:22

Parameters

Parameter	Type	Default value
`rootPrefix`	`string`	`"/platform"`

Returns

PlatformParameterPaths

Properties

Property	Modifier	Type	Defined in
`account`	`readonly`	`object`	paths.ts:30
`account.accessLogsBucketName`	`public`	() => `string`	paths.ts:48
`account.cloudTrailBucketName`	`public`	() => `string`	paths.ts:47
`account.deployRoleArn`	`public`	(`repo`) => `string`	paths.ts:43
`account.id`	`public`	() => `string`	paths.ts:31
`account.kmsKeyArn`	`public`	() => `string`	paths.ts:33
`account.kmsKeyId`	`public`	() => `string`	paths.ts:34
`account.logRetentionDays`	`public`	() => `string`	paths.ts:46
`account.name`	`public`	() => `string`	paths.ts:32
`account.oidcProviderArn`	`public`	() => `string`	paths.ts:42
`account.readonlyRoleArn`	`public`	(`repo`) => `string`	paths.ts:44
`account.vpcAvailabilityZones`	`public`	() => `string`	paths.ts:40
`account.vpcCidr`	`public`	() => `string`	paths.ts:36
`account.vpcId`	`public`	() => `string`	paths.ts:35
`account.vpcIsolatedSubnetIds`	`public`	() => `string`	paths.ts:39
`account.vpcLambdaSecurityGroupId`	`public`	() => `string`	paths.ts:41
`account.vpcPrivateSubnetIds`	`public`	() => `string`	paths.ts:37
`account.vpcPublicSubnetIds`	`public`	() => `string`	paths.ts:38
`root`	`readonly`	`string`	paths.ts:20

Methods

config()

config(key): string;

Defined in: paths.ts:66

Shared plain configuration value.

Parameters

Parameter	Type
`key`	`string`

Returns

string

env()

readonly env(env): EnvironmentParameterPaths;

Defined in: paths.ts:51

Parameters

Parameter	Type
`env`	`string`

Returns

EnvironmentParameterPaths

secretArn()

secretArn(name): string;

Defined in: paths.ts:71

ARN of a shared Secrets Manager secret.

Parameters

Parameter	Type
`name`	`string`

Returns

string

service()

service(service, key): string;

Defined in: paths.ts:76

Values a service publishes about itself, e.g. /platform/services/orders/api-url.

Parameters

Parameter	Type
`service`	`string`
`key`	`string`

Returns

string

Interfaces

CreateLoggerOptions

Defined in: logger.ts:7

Properties

Property	Type	Description	Defined in
`logLevel?`	`LogLevel`	Log level; defaults to `LOG_LEVEL` / `POWERTOOLS_LOG_LEVEL`, then `info`.	logger.ts:11
`persistentKeys?`	`Record`<`string`, `unknown`>	Additional keys added to every log record.	logger.ts:13
`sampleRateValue?`	`number`	Debug sampling rate between 0 and 1.	logger.ts:15
`serviceName?`	`string`	Service name; defaults to `POWERTOOLS_SERVICE_NAME`, then `PLATFORM_SERVICE`.	logger.ts:9

EnvironmentParameterPaths

Defined in: paths.ts:81

Methods

alertTopicArn()

alertTopicArn(severity): string;

Defined in: paths.ts:88

Parameters

Parameter	Type
`severity`	`"critical"` \| `"high"` \| `"medium"` \| `"low"`

Returns

string

certRegionalArn()

certRegionalArn(): string;

Defined in: paths.ts:86

Returns

string

certUsEast1Arn()

certUsEast1Arn(): string;

Defined in: paths.ts:87

Returns

string

dnsZoneId()

dnsZoneId(): string;

Defined in: paths.ts:84

Returns

string

dnsZoneName()

dnsZoneName(): string;

Defined in: paths.ts:85

Returns

string

domain()

domain(): string;

Defined in: paths.ts:83

Returns

string

eventBusArn()

eventBusArn(): string;

Defined in: paths.ts:90

Returns

string

eventBusName()

eventBusName(): string;

Defined in: paths.ts:89

Returns

string

name()

name(): string;

Defined in: paths.ts:82

Returns

string

root()

root(): string;

Defined in: paths.ts:91

Returns

string

EventToPublish

Defined in: events.ts:63

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Properties

Property	Type	Defined in
`eventBody`	`T`	events.ts:65
`eventName`	`string`	events.ts:64

GetConfigOptions

Defined in: secrets.ts:116

Properties

Property	Type	Description	Defined in
`client?`	`SSMClient`	Custom SSM client, mainly for tests.	secrets.ts:122
`maxAge?`	`number`	Maximum age of the cached value in seconds (default 300).	secrets.ts:118
`rootPrefix?`	`string`	SSM root prefix; defaults to `PLATFORM_SSM_ROOT` or `/platform`.	secrets.ts:120

GetParameterOptions

Defined in: params.ts:13

Extended by

GetParametersOptions

Properties

Property	Type	Description	Defined in
`client?`	`SSMClient`	Custom SSM client, mainly for tests.	params.ts:21
`decrypt?`	`boolean`	Decrypt `SecureString` parameters (default false).	params.ts:17
`forceFetch?`	`boolean`	Bypass the cache for this call.	params.ts:19
`maxAge?`	`number`	Maximum age of the cached value in seconds (default 300).	params.ts:15

GetParametersOptions

Defined in: params.ts:24

Extends

GetParameterOptions

Properties

Property	Type	Description	Inherited from	Defined in
`client?`	`SSMClient`	Custom SSM client, mainly for tests.	`GetParameterOptions`.`client`	params.ts:21
`decrypt?`	`boolean`	Decrypt `SecureString` parameters (default false).	`GetParameterOptions`.`decrypt`	params.ts:17
`forceFetch?`	`boolean`	Bypass the cache for this call.	`GetParameterOptions`.`forceFetch`	params.ts:19
`maxAge?`	`number`	Maximum age of the cached value in seconds (default 300).	`GetParameterOptions`.`maxAge`	params.ts:15
`recursive?`	`boolean`	Fetch parameters below the prefix recursively (default true).	-	params.ts:26

GetSecretJsonOptions

Defined in: secrets.ts:27

Extends

GetSecretOptions

Type Parameters

Type Parameter
`T`

Properties

Property	Type	Description	Inherited from	Defined in
`client?`	`SecretsManagerClient`	Custom Secrets Manager client, mainly for tests.	`GetSecretOptions`.`client`	secrets.ts:20
`forceFetch?`	`boolean`	Bypass the cache for this call.	`GetSecretOptions`.`forceFetch`	secrets.ts:18
`maxAge?`	`number`	Maximum age of the cached value in seconds (default 300).	`GetSecretOptions`.`maxAge`	secrets.ts:16
`parse?`	(`value`) => `T`	Validates / narrows the parsed JSON, e.g. `schema.parse` from zod.	-	secrets.ts:29
`rootPrefix?`	`string`	SSM root prefix used to resolve secret names; defaults to `PLATFORM_SSM_ROOT` or `/platform`.	`GetSecretOptions`.`rootPrefix`	secrets.ts:24
`ssmClient?`	`SSMClient`	Custom SSM client used to resolve `/{root}/secrets/{name}/arn`, mainly for tests.	`GetSecretOptions`.`ssmClient`	secrets.ts:22

GetSecretOptions

Defined in: secrets.ts:14

Extended by

GetSecretJsonOptions

Properties

Property	Type	Description	Defined in
`client?`	`SecretsManagerClient`	Custom Secrets Manager client, mainly for tests.	secrets.ts:20
`forceFetch?`	`boolean`	Bypass the cache for this call.	secrets.ts:18
`maxAge?`	`number`	Maximum age of the cached value in seconds (default 300).	secrets.ts:16
`rootPrefix?`	`string`	SSM root prefix used to resolve secret names; defaults to `PLATFORM_SSM_ROOT` or `/platform`.	secrets.ts:24
`ssmClient?`	`SSMClient`	Custom SSM client used to resolve `/{root}/secrets/{name}/arn`, mainly for tests.	secrets.ts:22

OffloadedPointer

Defined in: events.ts:12

Location of an event body that was too large for EventBridge and was stored in S3.

Properties

Property	Type	Defined in
`bucket`	`string`	events.ts:13
`key`	`string`	events.ts:14

OffloadOptions

Defined in: events.ts:33

Properties

Property	Type	Description	Defined in
`bucket`	`string`	Bucket that receives large event bodies.	events.ts:35
`client?`	`S3Client`	Custom S3 client, mainly for tests.	events.ts:39
`keyPrefix?`	`string`	Key prefix inside the bucket (default `events`).	events.ts:41
`thresholdBytes?`	`number`	Detail size (in bytes) above which the body is offloaded (default 200 000).	events.ts:37

PlatformAccountParams

Defined in: params.ts:106

Methods

accessLogsBucketName()

accessLogsBucketName(): Promise<string>;

Defined in: params.ts:113

Returns

Promise<string>

cloudTrailBucketName()

cloudTrailBucketName(): Promise<string>;

Defined in: params.ts:114

Returns

Promise<string>

deployRoleArn()

deployRoleArn(repo): Promise<string>;

Defined in: params.ts:116

Parameters

Parameter	Type
`repo`	`string`

Returns

Promise<string>

id()

id(): Promise<string>;

Defined in: params.ts:107

Returns

Promise<string>

kmsKeyArn()

kmsKeyArn(): Promise<string>;

Defined in: params.ts:109

Returns

Promise<string>

kmsKeyId()

kmsKeyId(): Promise<string>;

Defined in: params.ts:110

Returns

Promise<string>

logRetentionDays()

logRetentionDays(): Promise<string>;

Defined in: params.ts:112

Returns

Promise<string>

name()

name(): Promise<string>;

Defined in: params.ts:108

Returns

Promise<string>

oidcProviderArn()

oidcProviderArn(): Promise<string>;

Defined in: params.ts:115

Returns

Promise<string>

readonlyRoleArn()

readonlyRoleArn(repo): Promise<string>;

Defined in: params.ts:117

Parameters

Parameter	Type
`repo`	`string`

Returns

Promise<string>

vpcId()

vpcId(): Promise<string>;

Defined in: params.ts:111

Returns

Promise<string>

PlatformEnv

Defined in: env.ts:5

Platform environment variables injected into every Lambda function by the @rpallas/outcrop constructs.

Properties

Property	Type	Description	Defined in
`env`	`string`	Deployment environment such as `dev`, `staging`, `prod` (`PLATFORM_ENV`).	env.ts:11
`functionName?`	`string`	Logical function name within the service (`PLATFORM_FUNCTION`).	env.ts:17
`isPreview`	`boolean`	True when `previewId` is set.	env.ts:21
`logLevel`	`PlatformLogLevel`	Log level (`LOG_LEVEL`, default `info`).	env.ts:19
`previewId?`	`string`	Preview identifier when running inside a preview stack (`PLATFORM_PREVIEW_ID`).	env.ts:13
`project`	`string`	Project name (`PLATFORM_PROJECT`, defaults to the service name).	env.ts:7
`service`	`string`	Service name (`PLATFORM_SERVICE`).	env.ts:9
`ssmRoot`	`string`	SSM root prefix of the platform contract (`PLATFORM_SSM_ROOT`, default `/platform`).	env.ts:15

PlatformEnvironmentParams

Defined in: params.ts:120

Methods

alertTopicArn()

alertTopicArn(severity): Promise<string>;

Defined in: params.ts:127

Parameters

Parameter	Type
`severity`	`"critical"` \| `"high"` \| `"medium"` \| `"low"`

Returns

Promise<string>

certRegionalArn()

certRegionalArn(): Promise<string>;

Defined in: params.ts:125

Returns

Promise<string>

certUsEast1Arn()

certUsEast1Arn(): Promise<string>;

Defined in: params.ts:126

Returns

Promise<string>

dnsZoneId()

dnsZoneId(): Promise<string>;

Defined in: params.ts:123

Returns

Promise<string>

dnsZoneName()

dnsZoneName(): Promise<string>;

Defined in: params.ts:124

Returns

Promise<string>

domain()

domain(): Promise<string>;

Defined in: params.ts:122

Returns

Promise<string>

eventBusArn()

eventBusArn(): Promise<string>;

Defined in: params.ts:129

Returns

Promise<string>

eventBusName()

eventBusName(): Promise<string>;

Defined in: params.ts:128

Returns

Promise<string>

name()

name(): Promise<string>;

Defined in: params.ts:121

Returns

Promise<string>

PlatformEvent

Defined in: events.ts:21

Envelope stored in the EventBridge detail field. eventBody is undefined while the body lives in S3 (see OffloadedPointer).

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Properties

Property	Type	Defined in
`eventBody`	`T`	events.ts:23
`eventName`	`string`	events.ts:22
`offloaded?`	`OffloadedPointer`	events.ts:24

PlatformParams

Defined in: params.ts:132

Properties

Property	Type	Description	Defined in
`account`	`PlatformAccountParams`	Account-level contract values.	params.ts:138
`paths`	`PlatformParameterPaths`	Path builder used by the getters.	params.ts:134

Methods

config()

config(key): Promise<string>;

Defined in: params.ts:142

Shared plain configuration value /{root}/config/{key}.

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<string>

env()

env(envName?): PlatformEnvironmentParams;

Defined in: params.ts:140

Environment-level contract values; envName defaults to PLATFORM_ENV.

Parameters

Parameter	Type
`envName?`	`string`

Returns

PlatformEnvironmentParams

get()

get(path, options?): Promise<string>;

Defined in: params.ts:136

Reads an arbitrary parameter path.

Parameters

Parameter	Type
`path`	`string`
`options?`	`GetParameterOptions`

Returns

Promise<string>

secretArn()

secretArn(name): Promise<string>;

Defined in: params.ts:144

ARN of the shared secret /{root}/secrets/{name}/arn.

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<string>

service()

service(service, key): Promise<string>;

Defined in: params.ts:146

Value published by another service /{root}/services/{service}/{key}.

Parameters

Parameter	Type
`service`	`string`
`key`	`string`

Returns

Promise<string>

PlatformParamsOptions

Defined in: params.ts:95

Properties

Property	Type	Description	Defined in
`client?`	`SSMClient`	Custom SSM client, mainly for tests.	params.ts:103
`env?`	`string`	Environment name used by `env()`; defaults to `PLATFORM_ENV`.	params.ts:99
`maxAge?`	`number`	Cache duration in seconds for every read (default 300).	params.ts:101
`rootPrefix?`	`string`	SSM root prefix; defaults to `PLATFORM_SSM_ROOT` or `/platform`.	params.ts:97

PublishEventOptions

Defined in: events.ts:44

Properties

Property	Type	Description	Defined in
`busName?`	`string`	Event bus name; defaults to `EVENT_BUS_NAME`.	events.ts:46
`client?`	`EventBridgeClient`	Custom EventBridge client, mainly for tests.	events.ts:50
`offload?`	`OffloadOptions`	Store large bodies in S3 and publish a pointer instead.	events.ts:56
`resources?`	`string`[]	ARNs the event relates to.	events.ts:52
`source?`	`string`	Event source; defaults to `PLATFORM_SERVICE`.	events.ts:48
`time?`	`Date`	Event time; defaults to now.	events.ts:54

PublishEventResult

Defined in: events.ts:59

Properties

Property	Type	Defined in
`eventId?`	`string`	events.ts:60

ResolveEnvelopeOptions

Defined in: events.ts:299

Type Parameters

Type Parameter
`T`

Properties

Property	Type	Description	Defined in
`parse?`	(`body`) => `T`	Validates / narrows the body, e.g. `schema.parse` from zod.	events.ts:303
`s3Client?`	`S3Client`	Custom S3 client used to download offloaded bodies, mainly for tests.	events.ts:301

WithEventHandlerOptions

Defined in: handler.ts:220

Type Parameters

Type Parameter
`T`

Properties

Property	Type	Description	Defined in
`logEvent?`	`boolean`	Log the incoming event at `info` level.	handler.ts:224
`logger?`	`Logger`	Logger to use; defaults to getLogger.	handler.ts:222
`parse?`	(`body`) => `T`	Validates / narrows the event body, e.g. `schema.parse` from zod.	handler.ts:226
`s3Client?`	`S3Client`	Custom S3 client used to download offloaded bodies.	handler.ts:228

WithHandlerOptions

Defined in: handler.ts:21

Type Parameters

Type Parameter
`TEvent`
`TResult`

Properties

Property	Type	Description	Defined in
`logEvent?`	`boolean`	Log the incoming event at `info` level (default: honour `POWERTOOLS_LOGGER_LOG_EVENT`).	handler.ts:25
`logger?`	`Logger`	Logger to use; defaults to getLogger.	handler.ts:23
`onError?`	(`error`, `event`, `context`) => `TResult` \| `Promise`<`TResult`>	Called instead of rethrowing when the handler fails.	handler.ts:27

WithSqsHandlerOptions

Defined in: handler.ts:159

Properties

Property	Type	Description	Defined in
`concurrency?`	`number`	Maximum number of records processed concurrently (default 1 = sequential).	handler.ts:165
`logEvent?`	`boolean`	Log the incoming event at `info` level.	handler.ts:163
`logger?`	`Logger`	Logger to use; defaults to getLogger.	handler.ts:161

Type Aliases

AlertSeverity

type AlertSeverity = typeof ALERT_SEVERITIES[number];

Defined in: paths.ts:7

Alert severity. Each severity maps to one SNS topic per environment so that routing (pager, chat channel, email digest) is an account-level decision.

HttpHandler

type HttpHandler = LambdaHandler<APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2>;

Defined in: handler.ts:103

HttpHeaders

type HttpHeaders = Record<string, string>;

Defined in: http.ts:32

LambdaHandler

type LambdaHandler<TEvent, TResult> = (event, context) => Promise<TResult>;

Defined in: handler.ts:17

Type Parameters

Type Parameter
`TEvent`
`TResult`

Parameters

Parameter	Type
`event`	`TEvent`
`context`	`Context`

Returns

Promise<TResult>

PlatformEventHandler

type PlatformEventHandler<T> = (envelope, event, context) => Promise<void>;

Defined in: handler.ts:214

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`envelope`	`PlatformEvent`<`T`>
`event`	`EventBridgeEvent`<`string`, `unknown`>
`context`	`Context`

Returns

Promise<void>

PlatformLogLevel

type PlatformLogLevel = "debug" | "info" | "warn" | "error";

Defined in: env.ts:24

SqsRecordHandler

type SqsRecordHandler = (record, context) => Promise<void>;

Defined in: handler.ts:157

Parameters

Parameter	Type
`record`	`SQSRecord`
`context`	`Context`

Returns

Promise<void>

WithHttpHandlerOptions

type WithHttpHandlerOptions = WithHandlerOptions<APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2>;

Defined in: handler.ts:105

Variables

ALERT_SEVERITIES

const ALERT_SEVERITIES: readonly ["critical", "high", "medium", "low"];

Defined in: paths.ts:1

CORRELATION_ID_HEADER

const CORRELATION_ID_HEADER: "x-correlation-id" = "x-correlation-id";

Defined in: handler.ts:19

DEFAULT_OFFLOAD_THRESHOLD_BYTES

const DEFAULT_OFFLOAD_THRESHOLD_BYTES: 200000 = 200_000;

Defined in: events.ts:28

Default maximum detail size before the body is offloaded to S3 (EventBridge allows 256 KiB per entry).

DEFAULT_PARAMETER_MAX_AGE

const DEFAULT_PARAMETER_MAX_AGE: 300 = 300;

Defined in: params.ts:11

Default cache duration for parameters, in seconds.

DEFAULT_SECRET_MAX_AGE

const DEFAULT_SECRET_MAX_AGE: 300 = 300;

Defined in: secrets.ts:12

Default cache duration for secrets, in seconds.

DEFAULT_SSM_ROOT

const DEFAULT_SSM_ROOT: "/platform" = "/platform";

Defined in: env.ts:28

PUT_EVENTS_BATCH_SIZE

const PUT_EVENTS_BATCH_SIZE: 10 = 10;

Defined in: events.ts:31

Maximum number of entries in a single PutEvents call.

TELEMETRY_ENABLE_ENV

const TELEMETRY_ENABLE_ENV: "PLATFORM_TELEMETRY_FD" = "PLATFORM_TELEMETRY_FD";

Defined in: layer.ts:16

Environment variable that opts a function into the telemetry shim.

TELEMETRY_LAYER_DIR

const TELEMETRY_LAYER_DIR: string;

Defined in: layer.ts:7

Directory containing the Lambda layer content (nodejs/platform-telemetry.js). Point lambda.Code.fromAsset() at it when building the layer.

TELEMETRY_NODE_OPTIONS

const TELEMETRY_NODE_OPTIONS: "--require /opt/nodejs/platform-telemetry.js";

Defined in: layer.ts:13

Value for NODE_OPTIONS that pre-loads the telemetry shim.

TELEMETRY_REQUIRE_PATH

const TELEMETRY_REQUIRE_PATH: "/opt/nodejs/platform-telemetry.js" = "/opt/nodejs/platform-telemetry.js";

Defined in: layer.ts:10

Path of the telemetry shim once the layer is mounted at /opt.

Functions

badRequest()

function badRequest(message?, details?): HttpError;

Defined in: http.ts:17

Parameters

Parameter	Type	Default value
`message`	`string`	`"Bad Request"`
`details?`	`unknown`	`undefined`

Returns

HttpError

conflict()

function conflict(message?, details?): HttpError;

Defined in: http.ts:25

Parameters

Parameter	Type	Default value
`message`	`string`	`"Conflict"`
`details?`	`unknown`	`undefined`

Returns

HttpError

createLogger()

function createLogger(options?): Logger;

Defined in: logger.ts:28

Creates a Powertools Logger pre-configured for the platform.

Persistent keys env, previewId and functionName are derived from the PLATFORM_* environment variables when they are available. Missing variables never cause an error so the logger keeps working in local scripts and tests.

Parameters

Parameter	Type
`options`	`CreateLoggerOptions`

Returns

Logger

eventFromSqsRecord()

function eventFromSqsRecord(record): EventBridgeEvent<string, unknown>;

Defined in: events.ts:284

Decodes the EventBridge event carried in an SQS record body.

Parameters

Parameter	Type
`record`	`SQSRecord`

Returns

EventBridgeEvent<string, unknown>

findHeader()

function findHeader(headers, name): string | undefined;

Defined in: http.ts:124

Case-insensitive lookup in a headers map.

Parameters

Parameter	Type
`headers`	`Record`<`string`, `string` \| `undefined`> \| `undefined`
`name`	`string`

Returns

string | undefined

forbidden()

function forbidden(message?, details?): HttpError;

Defined in: http.ts:21

Parameters

Parameter	Type	Default value
`message`	`string`	`"Forbidden"`
`details?`	`unknown`	`undefined`

Returns

HttpError

getConfig()

function getConfig(key, options?): Promise<string>;

Defined in: secrets.ts:126

Reads the shared configuration value /{root}/config/{key}.

Parameters

Parameter	Type
`key`	`string`
`options`	`GetConfigOptions`

Returns

Promise<string>

getLogger()

function getLogger(): Logger;

Defined in: logger.ts:66

Returns the module-level logger, creating it on first use.

Returns

Logger

getParameter()

function getParameter(name, options?): Promise<string>;

Defined in: params.ts:61

Reads a single SSM parameter, cached for maxAge seconds (default 300). Throws a descriptive error when the parameter does not exist.

Parameters

Parameter	Type
`name`	`string`
`options`	`GetParameterOptions`

Returns

Promise<string>

getParameters()

function getParameters(prefix, options?): Promise<Record<string, string>>;

Defined in: params.ts:79

Reads all parameters below prefix, keyed by the path relative to the prefix.

Parameters

Parameter	Type
`prefix`	`string`
`options`	`GetParametersOptions`

Returns

Promise<Record<string, string>>

getSecret()

function getSecret(nameOrArn, options?): Promise<string>;

Defined in: secrets.ts:73

Reads a secret string from Secrets Manager, cached for maxAge seconds (default 300).

nameOrArn may be a full ARN or the short name of a shared platform secret, in which case the ARN is looked up from SSM first.

Parameters

Parameter	Type
`nameOrArn`	`string`
`options`	`GetSecretOptions`

Returns

Promise<string>

getSecretJson()

function getSecretJson<T>(nameOrArn, options?): Promise<T>;

Defined in: secrets.ts:100

Reads a JSON secret and optionally validates it with parse.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`nameOrArn`	`string`
`options`	`GetSecretJsonOptions`<`T`>

Returns

Promise<T>

Example

const creds = await getSecretJson("database", { parse: DbSchema.parse });

function header(event, name): string | undefined;

Defined in: http.ts:119

Header value looked up case-insensitively, or undefined.

Parameters

Parameter	Type
`event`	`APIGatewayProxyEventV2`
`name`	`string`

Returns

string | undefined

internalError()

function internalError(message?, details?): HttpError;

Defined in: http.ts:29

Parameters

Parameter	Type	Default value
`message`	`string`	`"Internal Server Error"`
`details?`	`unknown`	`undefined`

Returns

HttpError

isAlertSeverity()

function isAlertSeverity(value): value is "critical" | "high" | "medium" | "low";

Defined in: paths.ts:9

Parameters

Parameter	Type
`value`	`string`

Returns

value is "critical" | "high" | "medium" | "low"

isHttpError()

function isHttpError(error): error is HttpError;

Defined in: http.ts:15

Parameters

Parameter	Type
`error`	`unknown`

Returns

error is HttpError

json()

function json(
   statusCode, 
   body, 
   headers?
): APIGatewayProxyStructuredResultV2;

Defined in: http.ts:35

JSON response with content-type: application/json.

Parameters

Parameter	Type
`statusCode`	`number`
`body`	`unknown`
`headers`	`HttpHeaders`

Returns

APIGatewayProxyStructuredResultV2

noContent()

function noContent(headers?): APIGatewayProxyStructuredResultV2;

Defined in: http.ts:48

Empty 204 No Content response.

Parameters

Parameter	Type
`headers`	`HttpHeaders`

Returns

APIGatewayProxyStructuredResultV2

notFound()

function notFound(message?, details?): HttpError;

Defined in: http.ts:23

Parameters

Parameter	Type	Default value
`message`	`string`	`"Not Found"`
`details?`	`unknown`	`undefined`

Returns

HttpError

parseEnvelope()

function parseEnvelope<T>(event, parse?): PlatformEvent<T>;

Defined in: events.ts:254

Extracts and validates the PlatformEvent envelope from an EventBridge event.

Throws when the detail is not an envelope. Offloaded envelopes (body stored in S3) cannot be parsed synchronously; use resolveEnvelope for those.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`event`	`EventBridgeEvent`<`string`, `unknown`>
`parse?`	(`body`) => `T`

Returns

PlatformEvent<T>

parseJsonBody()

function parseJsonBody<T>(event, parse?): T;

Defined in: http.ts:72

Parses the JSON request body, optionally validating it with parse (e.g. schema.parse from zod). Throws a 400 HttpError when the body is missing, is not valid JSON, or parse rejects it.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`event`	`APIGatewayProxyEventV2`
`parse?`	(`value`) => `T`

Returns

T

parseSqsEnvelope()

function parseSqsEnvelope<T>(record, parse?): PlatformEvent<T>;

Defined in: events.ts:276

Parses the platform envelope from an SQS record that was delivered by an EventBridge rule (the SQS body is the EventBridge event JSON).

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`record`	`SQSRecord`
`parse?`	(`body`) => `T`

Returns

PlatformEvent<T>

pathParam()

function pathParam(event, name): string;

Defined in: http.ts:105

Path parameter value; throws a 400 HttpError when missing.

Parameters

Parameter	Type
`event`	`APIGatewayProxyEventV2`
`name`	`string`

Returns

string

platformEnv()

function platformEnv(env?): PlatformEnv;

Defined in: env.ts:64

Resolves the PlatformEnv from the process environment.

Throws when PLATFORM_SERVICE or PLATFORM_ENV are missing.

Parameters

Parameter	Type	Default value
`env`	`ProcessEnv`	`process.env`

Returns

PlatformEnv

platformParams()

function platformParams(options?): PlatformParams;

Defined in: params.ts:161

Typed accessors for the platform SSM contract.

Parameters

Parameter	Type
`options`	`PlatformParamsOptions`

Returns

PlatformParams

Example

const params = platformParams();
const busName = await params.env().eventBusName();

publishEvent()

function publishEvent(
   eventName, 
   eventBody, 
   options?
): Promise<PublishEventResult>;

Defined in: events.ts:170

Publishes a single platform event to EventBridge.

The detail is a PlatformEvent envelope, detail-type is the event name and source is the publishing service.

Parameters

Parameter	Type
`eventName`	`string`
`eventBody`	`unknown`
`options`	`PublishEventOptions`

Returns

Promise<PublishEventResult>

publishEvents()

function publishEvents<T>(events, options?): Promise<PublishEventResult[]>;

Defined in: events.ts:186

Publishes several events, in batches of 10 (the PutEvents limit). Results are returned in the same order as events.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`events`	`EventToPublish`<`T`>[]
`options`	`PublishEventOptions`

Returns

Promise<PublishEventResult[]>

queryParam()

function queryParam(event, name): string | undefined;

Defined in: http.ts:114

Query string parameter value, or undefined.

Parameters

Parameter	Type
`event`	`APIGatewayProxyEventV2`
`name`	`string`

Returns

string | undefined

rawBody()

function rawBody(event): string | undefined;

Defined in: http.ts:62

Raw request body, decoded when API Gateway base64-encoded it.

Parameters

Parameter	Type
`event`	`APIGatewayProxyEventV2`

Returns

string | undefined

redirect()

function redirect(
   location, 
   statusCode?, 
   headers?
): APIGatewayProxyStructuredResultV2;

Defined in: http.ts:53

Redirect response (302 Found by default).

Parameters

Parameter	Type	Default value
`location`	`string`	`undefined`
`statusCode`	`number`	`302`
`headers`	`HttpHeaders`	`{}`

Returns

APIGatewayProxyStructuredResultV2

requireEnv()

function requireEnv(name, env?): string;

Defined in: env.ts:34

Reads an environment variable and throws a descriptive error when it is missing or empty.

Parameters

Parameter	Type	Default value
`name`	`string`	`undefined`
`env`	`ProcessEnv`	`process.env`

Returns

string

resetLogger()

function resetLogger(): void;

Defined in: logger.ts:72

Drops the module-level logger so the next getLogger call creates a fresh one.

Returns

void

resolveCorrelationId()

function resolveCorrelationId(event, context): string;

Defined in: handler.ts:47

Picks the correlation id for an invocation: the x-correlation-id header, then the HTTP API request id, then the EventBridge event id, then the Lambda request id.

Parameters

Parameter	Type
`event`	`unknown`
`context`	`Context`

Returns

string

resolveEnvelope()

function resolveEnvelope<T>(event, options?): Promise<PlatformEvent<T>>;

Defined in: events.ts:309

Like parseEnvelope but downloads the body from S3 when it was offloaded.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`event`	`EventBridgeEvent`<`string`, `unknown`>
`options`	`ResolveEnvelopeOptions`<`T`>

Returns

Promise<PlatformEvent<T>>

resolveSecretArn()

function resolveSecretArn(nameOrArn, options?): Promise<string>;

Defined in: secrets.ts:55

Resolves the Secrets Manager ARN for a shared platform secret name via the SSM contract path /{root}/secrets/{name}/arn. ARNs are returned unchanged.

Parameters

Parameter	Type
`nameOrArn`	`string`
`options`	`GetSecretOptions`

Returns

Promise<string>

resolveSqsEnvelope()

function resolveSqsEnvelope<T>(record, options?): Promise<PlatformEvent<T>>;

Defined in: events.ts:335

Like parseSqsEnvelope but downloads offloaded bodies from S3.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`record`	`SQSRecord`
`options`	`ResolveEnvelopeOptions`<`T`>

Returns

Promise<PlatformEvent<T>>

tooManyRequests()

function tooManyRequests(message?, details?): HttpError;

Defined in: http.ts:27

Parameters

Parameter	Type	Default value
`message`	`string`	`"Too Many Requests"`
`details?`	`unknown`	`undefined`

Returns

HttpError

tryPlatformEnv()

function tryPlatformEnv(env?): PlatformEnv | undefined;

Defined in: env.ts:88

Like platformEnv but returns undefined instead of throwing when the required variables are not present. Useful for helpers that must keep working outside of a platform-managed Lambda (e.g. local scripts and tests).

Parameters

Parameter	Type	Default value
`env`	`ProcessEnv`	`process.env`

Returns

PlatformEnv | undefined

unauthorized()

function unauthorized(message?, details?): HttpError;

Defined in: http.ts:19

Parameters

Parameter	Type	Default value
`message`	`string`	`"Unauthorized"`
`details?`	`unknown`	`undefined`

Returns

HttpError

withEventHandler()

function withEventHandler<T>(handler, options?): LambdaHandler<EventBridgeEvent<string, unknown>, void>;

Defined in: handler.ts:235

EventBridge handler wrapper: unwraps (and, when offloaded, downloads) the platform envelope before invoking handler. Adds eventName to the log keys.

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`handler`	`PlatformEventHandler`<`T`>
`options`	`WithEventHandlerOptions`<`T`>

Returns

LambdaHandler<EventBridgeEvent<string, unknown>, void>

withHandler()

function withHandler<TEvent, TResult>(handler, options?): LambdaHandler<TEvent, TResult>;

Defined in: handler.ts:72

Wraps a Lambda handler with logging boilerplate: Lambda context and cold start tracking, event logging, a per-invocation correlationId key, error logging and key cleanup.

Type Parameters

Type Parameter
`TEvent`
`TResult`

Parameters

Parameter	Type
`handler`	`LambdaHandler`<`TEvent`, `TResult`>
`options`	`WithHandlerOptions`<`TEvent`, `TResult`>

Returns

LambdaHandler<TEvent, TResult>

withHttpHandler()

function withHttpHandler(handler, options?): HttpHandler;

Defined in: handler.ts:123

HTTP API (payload v2) handler wrapper. HttpErrors become JSON error responses with their status code; anything else becomes a 500. Every response carries an x-correlation-id header.

Parameters

Parameter	Type
`handler`	`HttpHandler`
`options`	`WithHttpHandlerOptions`

Returns

HttpHandler

withSqsHandler()

function withSqsHandler(recordHandler, options?): LambdaHandler<SQSEvent, SQSBatchResponse>;

Defined in: handler.ts:173

SQS handler wrapper with partial batch responses: each record is handed to recordHandler; failures are logged and reported via batchItemFailures. Requires ReportBatchItemFailures on the event source mapping.

Parameters

Parameter	Type
`recordHandler`	`SqsRecordHandler`
`options`	`WithSqsHandlerOptions`

Returns

LambdaHandler<SQSEvent, SQSBatchResponse>

@rpallas/outcrop-runtime ​

Environment ​

Logger ​

Parameters ​

Secrets ​

Events ​

HTTP handler ​

SQS handler ​

EventBridge handler ​

Generic wrapper ​

Telemetry layer ​

Classes ​

HttpError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

PlatformParameterPaths ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Properties ​

Methods ​

config() ​

Parameters ​

Returns ​

env() ​

Parameters ​

Returns ​

secretArn() ​

Parameters ​

Returns ​

service() ​

Parameters ​

Returns ​

Interfaces ​

CreateLoggerOptions ​

Properties ​

EnvironmentParameterPaths ​

Methods ​

alertTopicArn() ​

Parameters ​

Returns ​

certRegionalArn() ​

Returns ​

certUsEast1Arn() ​

Returns ​

dnsZoneId() ​

Returns ​

dnsZoneName() ​

Returns ​

domain() ​

Returns ​

eventBusArn() ​

Returns ​

eventBusName() ​

Returns ​

name() ​

Returns ​

root() ​

Returns ​

EventToPublish ​

Type Parameters ​

Properties ​

GetConfigOptions ​

Properties ​

GetParameterOptions ​

Extended by ​

Properties ​

GetParametersOptions ​

Extends ​

Properties ​

GetSecretJsonOptions ​

Extends ​

Type Parameters ​

Properties ​

@rpallas/outcrop-runtime

Environment

Logger

Parameters

Secrets

Events

HTTP handler

SQS handler

EventBridge handler

Generic wrapper

Telemetry layer

Classes

HttpError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

PlatformParameterPaths

Constructors

Constructor

Parameters

Returns

Properties

Methods

config()

Parameters

Returns

env()

Parameters

Returns

secretArn()

Parameters

Returns

service()

Parameters

Returns

Interfaces

CreateLoggerOptions

Properties

EnvironmentParameterPaths

Methods

alertTopicArn()

Parameters

Returns

certRegionalArn()

Returns

certUsEast1Arn()

Returns

dnsZoneId()

Returns

dnsZoneName()

Returns

domain()

Returns

eventBusArn()

Returns

eventBusName()

Returns

name()

Returns

root()

Returns

EventToPublish

Type Parameters

Properties

GetConfigOptions

Properties

GetParameterOptions

Extended by

Properties

GetParametersOptions

Extends

Properties

GetSecretJsonOptions

Extends

Type Parameters

Properties