import * as contacts from "@distilled.cloud/aws/ssm-contacts";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import {
createInternalTags,
createTagsList,
diffTags,
hasAlchemyTags,
tagRecord,
} from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
export interface RotationProps {
/**
* The name of the rotation. Changing it replaces the rotation.
*
* @default ${app}-${id}-${stage}-${suffix}
*/
name?: string;
/**
* ARNs of the contacts on call, in shift order.
*/
contactIds: string[];
/**
* When the rotation goes into effect, as an ISO-8601 timestamp
* (e.g. `"2026-01-01T00:00:00Z"`).
*/
startTime?: string;
/**
* The IANA time zone the rotation's activity is based on
* (e.g. `"America/Los_Angeles"`).
*/
timeZoneId: string;
/**
* How often the rotation hands off between contacts: daily, weekly, or
* monthly hand-off settings plus the number of simultaneous on-calls and
* optional shift coverage windows.
*/
recurrence: contacts.RecurrenceSettings;
/**
* Tags applied to the rotation. Alchemy ownership tags are merged in
* automatically.
*/
tags?: Record<string, string>;
}
/** @resource */
export interface Rotation extends Resource<
"AWS.SSMContacts.Rotation",
RotationProps,
{
/** ARN of the rotation. */
rotationArn: string;
/** Name of the rotation. */
name: string;
/** When the rotation goes into effect (ISO-8601). */
startTime: string | undefined;
},
never,
Providers
> {}
/**
* An Incident Manager on-call rotation — a recurring schedule that rotates
* engagement duty between contacts. Attach rotations to an
* `ONCALL_SCHEDULE` contact via its engagement plan's `RotationIds`.
*
* ### Creating Rotations
* **Example:** Daily hand-off rotation
* ```typescript
* const rotation = yield* SSMContacts.Rotation("Primary", {
* contactIds: [alice.contactArn, bob.contactArn],
* timeZoneId: "America/Los_Angeles",
* startTime: "2026-01-01T00:00:00Z",
* recurrence: {
* NumberOfOnCalls: 1,
* RecurrenceMultiplier: 1,
* DailySettings: [{ HourOfDay: 9, MinuteOfHour: 0 }],
* },
* });
* ```
*/
const RotationResource = Resource<Rotation>("AWS.SSMContacts.Rotation");
export { RotationResource as Rotation };
const normalize = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(normalize);
if (value !== null && typeof value === "object") {
return Object.fromEntries(
Object.entries(value as Record<string, unknown>)
.filter(([, v]) => v !== undefined)
.sort(([l], [r]) => l.localeCompare(r))
.map(([k, v]) => [k, normalize(v)]),
);
}
return value;
};
const same = (l: unknown, r: unknown) =>
JSON.stringify(normalize(l)) === JSON.stringify(normalize(r));
export const RotationProvider = () =>
Provider.effect(
RotationResource,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: { name?: string }) {
return props.name ?? (yield* createPhysicalName({ id, maxLength: 200 }));
});
const rotationArn = Effect.fn(function* (name: string) {
const { accountId, region } = yield* AWSEnvironment.current;
return `arn:aws:ssm-contacts:${region}:${accountId}:rotation/${name}`;
});
const getRotation = (arn: string) =>
contacts.getRotation({ RotationId: arn }).pipe(
// A rotation ARN that does not resolve surfaces as either a plain
// ResourceNotFoundException or the "Invalid resource Arn"
// ValidationException (typed as InvalidRotationArn) — both mean
// "missing" to the reconciler.
Effect.catchTag(
["ResourceNotFoundException", "InvalidRotationArn"],
() => Effect.undefined,
),
);
const readTags = (arn: string) =>
contacts.listTagsForResource({ ResourceARN: arn }).pipe(
// Distilled Tag has optional Key/Value; narrow to defined pairs
// before handing off to the shared tagRecord helper.
Effect.map((r) =>
tagRecord(
(r.Tags ?? []).flatMap((t) =>
t.Key !== undefined && t.Value !== undefined
? [{ Key: t.Key, Value: t.Value }]
: [],
),
),
),
Effect.orElseSucceed(() => ({})),
);
const buildAttrs = (rotation: contacts.GetRotationResult): Rotation["Attributes"] => ({
rotationArn: rotation.RotationArn,
name: rotation.Name,
startTime: rotation.StartTime.toISOString(),
});
return RotationResource.Provider.of({
stables: ["rotationArn", "name"],
list: () =>
contacts.listRotations.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).map((rotation) => ({
rotationArn: rotation.RotationArn,
name: rotation.Name,
startTime: rotation.StartTime?.toISOString(),
})),
),
),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.name ?? (yield* createName(id, olds ?? {}));
const arn = output?.rotationArn ?? (yield* rotationArn(name));
const rotation = yield* getRotation(arn);
if (rotation === undefined) return undefined;
const attrs = buildAttrs(rotation);
const tags = yield* readTags(rotation.RotationArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
// The name is create-only (updateRotation cannot rename); contacts,
// start time, time zone, and recurrence update in place.
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds);
const newName = yield* createName(id, news);
if (oldName !== newName) return { action: "replace" } as const;
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = output?.name ?? (yield* createName(id, news));
const arn = output?.rotationArn ?? (yield* rotationArn(name));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
const desiredStart = news.startTime !== undefined ? new Date(news.startTime) : undefined;
// 1. OBSERVE
let rotation = yield* getRotation(arn);
// 2. ENSURE — create if missing; tolerate the already-exists race.
if (rotation === undefined) {
yield* session.note(`creating rotation ${name}`);
yield* contacts
.createRotation({
Name: name,
ContactIds: news.contactIds,
StartTime: desiredStart,
TimeZoneId: news.timeZoneId,
Recurrence: news.recurrence,
Tags: createTagsList(desiredTags),
})
.pipe(
Effect.asVoid,
Effect.catchTag("ConflictException", () => Effect.void),
);
rotation = (yield* getRotation(arn))!;
}
// 3. SYNC contacts / start time / time zone / recurrence —
// observed vs desired (epoch-second granularity for the start
// time, matching the wire format).
const contactsDelta = !same(rotation.ContactIds, news.contactIds);
const timeZoneDelta = rotation.TimeZoneId !== news.timeZoneId;
const startDelta =
desiredStart !== undefined &&
Math.floor(rotation.StartTime.getTime() / 1000) !==
Math.floor(desiredStart.getTime() / 1000);
const recurrenceDelta = !same(
{
MonthlySettings: rotation.Recurrence.MonthlySettings ?? [],
WeeklySettings: rotation.Recurrence.WeeklySettings ?? [],
DailySettings: rotation.Recurrence.DailySettings ?? [],
NumberOfOnCalls: rotation.Recurrence.NumberOfOnCalls,
ShiftCoverages: rotation.Recurrence.ShiftCoverages ?? {},
RecurrenceMultiplier: rotation.Recurrence.RecurrenceMultiplier,
},
{
MonthlySettings: news.recurrence.MonthlySettings ?? [],
WeeklySettings: news.recurrence.WeeklySettings ?? [],
DailySettings: news.recurrence.DailySettings ?? [],
NumberOfOnCalls: news.recurrence.NumberOfOnCalls,
ShiftCoverages: news.recurrence.ShiftCoverages ?? {},
RecurrenceMultiplier: news.recurrence.RecurrenceMultiplier,
},
);
if (contactsDelta || timeZoneDelta || startDelta || recurrenceDelta) {
yield* contacts.updateRotation({
RotationId: rotation.RotationArn,
ContactIds: news.contactIds,
StartTime: desiredStart,
TimeZoneId: news.timeZoneId,
Recurrence: news.recurrence,
});
}
// 3b. SYNC tags — diff against OBSERVED cloud tags.
const currentTags = yield* readTags(rotation.RotationArn);
const { upsert, removed } = diffTags(currentTags, desiredTags);
if (upsert.length > 0) {
yield* contacts.tagResource({
ResourceARN: rotation.RotationArn,
Tags: upsert,
});
}
if (removed.length > 0) {
yield* contacts.untagResource({
ResourceARN: rotation.RotationArn,
TagKeys: removed,
});
}
// 4. RETURN fresh attributes.
const final = (yield* getRotation(rotation.RotationArn))!;
yield* session.note(final.RotationArn);
return buildAttrs(final);
}),
delete: Effect.fn(function* ({ output }) {
yield* contacts.deleteRotation({ RotationId: output.rotationArn }).pipe(
Effect.asVoid,
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
);
}),
});
}),
);