import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import {
consumeBusEvents,
type EventRecord,
type EventRouteProps,
} from "../EventBridge/EventSource.ts";
/**
* The `detail` payload EventBridge delivers for a CloudTrail-recorded API
* call (`AWS API Call via CloudTrail`). The shape mirrors the CloudTrail
* event record.
*/
export interface ApiCallDetail {
/** The service endpoint the call was made to, e.g. `s3.amazonaws.com`. */
eventSource: string;
/** The API operation name, e.g. `PutBucketTagging`. */
eventName: string;
/** The region the call was made in. */
awsRegion?: string;
/** Unique id of the CloudTrail event record. */
eventID?: string;
/** ISO timestamp of the call. */
eventTime?: string;
/** Version of the CloudTrail event schema. */
eventVersion?: string;
/** Identity that made the call (IAM user, role session, service, …). */
userIdentity?: Record<string, unknown>;
/** The request parameters of the call, as recorded by CloudTrail. */
requestParameters?: Record<string, any>;
/** The response elements of the call (mutating calls only). */
responseElements?: Record<string, any> | null;
/** Error code when the recorded call failed. */
errorCode?: string;
/** Error message when the recorded call failed. */
errorMessage?: string;
/** Additional event fields (the schema grows over time). */
[key: string]: unknown;
}
/** A CloudTrail API-call EventBridge event delivered to the handler. */
export type ApiCallEvent = EventRecord<ApiCallDetail>;
export interface ApiCallEventsProps extends EventRouteProps {
/**
* Logical id for the backing EventBridge rule.
* @default "CloudTrailApiCallEvents"
*/
id?: string;
/**
* Only deliver calls made to these service endpoints (the CloudTrail
* `eventSource`, e.g. `["s3.amazonaws.com"]`).
* @default all services
*/
eventSources?: string[];
/**
* Only deliver these API operations (the CloudTrail `eventName`, e.g.
* `["PutBucketTagging"]`).
* @default all operations
*/
eventNames?: string[];
}
/**
* Event source connecting CloudTrail-recorded API calls to the hosting
* compute. EventBridge receives every **mutating** management API call
* CloudTrail records (detail-type `AWS API Call via CloudTrail`) on the
* account's default bus — read-only calls (`Get*`/`List*`/`Describe*`) and
* data events are not delivered. This subscribes the host Function to those
* events so it can react to control-plane changes (security automation,
* config auditing) without polling.
*
* EventBridge receives these events automatically — no trail is required and
* no additional resource is created besides the EventBridge rule targeting
* the host. Provide the host-specific implementation layer (e.g.
* `AWS.Lambda.EventSource`) on the Function effect.
*
* ### Consuming API Call Events
* **Example:** React to S3 Bucket Configuration Changes
* ```typescript
* import * as AWS from "@alchemy.run/aws";
*
* export default AuditFunction.make(
* { main: import.meta.url },
* Effect.gen(function* () {
* yield* AWS.CloudTrail.consumeApiCallEvents(
* {
* eventSources: ["s3.amazonaws.com"],
* eventNames: ["PutBucketPolicy", "PutBucketAcl"],
* },
* (events) =>
* Stream.runForEach(events, (event) =>
* Effect.log(
* `${event.detail.eventName} on ${JSON.stringify(
* event.detail.requestParameters,
* )}`,
* ),
* ),
* );
* return {};
* }).pipe(Effect.provide(AWS.Lambda.EventSource)),
* );
* ```
*/
export const consumeApiCallEvents = <StreamReq = never, Req = never>(
props: ApiCallEventsProps,
process: (
events: Stream.Stream<ApiCallEvent, never, StreamReq>,
) => Effect.Effect<void, never, Req>,
) =>
consumeBusEvents(
props.id ?? "CloudTrailApiCallEvents",
{
"detail-type": ["AWS API Call via CloudTrail"],
...(props.eventSources || props.eventNames
? {
detail: {
...(props.eventSources ? { eventSource: [...props.eventSources] } : {}),
...(props.eventNames ? { eventName: [...props.eventNames] } : {}),
},
}
: {}),
},
{ description: props.description, state: props.state },
process,
);