import * as contacts from "@distilled.cloud/aws/notificationscontacts";
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, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export interface EmailContactProps {
/**
* Display name of the contact (1–64 characters). If omitted, a unique
* name is generated from the app, stage and logical ID. Contacts have no
* update API, so changing the name replaces the contact.
*/
name?: string;
/**
* The email address that receives notifications. Unique per account —
* AWS rejects a second contact with the same address. Changing the
* address replaces the contact.
*
* A new contact is created in the unverified `inactive` state; AWS sends
* notifications to it only after the address owner confirms the
* activation email (`SendActivationCode` / the console).
*/
emailAddress: string;
/**
* User tags to attach to the contact. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface EmailContact extends Resource<
"AWS.NotificationsContacts.EmailContact",
EmailContactProps,
{
/** The ARN of the email contact (regionless). */
emailContactArn: string;
/** The display name of the contact. */
name: string;
/** The email address of the contact. */
emailAddress: string;
/**
* Verification status: `inactive` until the address owner confirms the
* activation email, then `active`.
*/
status: string;
},
never,
Providers
> {}
/**
* An AWS User Notifications Contacts **email contact** — an email address
* that can be attached to a notification configuration as a delivery
* channel.
*
* Contacts are created in the unverified `inactive` state; activation is a
* human email-confirmation loop (AWS emails the address a confirmation
* link), so Alchemy provisions the contact and leaves activation to the
* address owner. Contacts are immutable (no update API) — changing the
* name or address replaces the contact; tags update in place.
*
* ### Creating an Email Contact
* **Example:** Basic email contact
* ```typescript
* import * as NotificationsContacts from "@alchemy.run/aws/NotificationsContacts";
*
* const contact = yield* NotificationsContacts.EmailContact("OnCall", {
* emailAddress: "oncall@example.com",
* });
* // contact.status === "inactive" until the address owner confirms
* ```
*
* **Example:** Named contact with tags
* ```typescript
* const contact = yield* NotificationsContacts.EmailContact("OnCall", {
* name: "platform-oncall",
* emailAddress: "oncall@example.com",
* tags: { team: "platform" },
* });
* ```
*
* @resource
*/
export const EmailContact = Resource<EmailContact>("AWS.NotificationsContacts.EmailContact");
/** Unwrap distilled `SensitiveString` values into plain strings. */
const unwrapSensitive = (value: string | Redacted.Redacted<string>): string =>
typeof value === "string" ? value : Redacted.value(value);
const readContactTags = Effect.fn(function* (arn: string) {
return yield* contacts.listTagsForResource({ arn }).pipe(
Effect.map((r) => (r.tags ?? {}) as Record<string, string>),
Effect.catchTag(["ResourceNotFoundException", "ValidationException"], () =>
Effect.succeed({} as Record<string, string>),
),
);
});
const syncContactTags = Effect.fn(function* (
arn: string,
id: string,
userTags: Record<string, string> | undefined,
) {
const internalTags = yield* createInternalTags(id);
const desired = { ...userTags, ...internalTags };
const observed = yield* readContactTags(arn);
const { upsert, removed } = diffTags(observed, desired);
if (upsert.length > 0) {
yield* contacts.tagResource({
arn,
tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
if (removed.length > 0) {
yield* contacts.untagResource({ arn, tagKeys: removed });
}
});
export const EmailContactProvider = () =>
Provider.effect(
EmailContact,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: EmailContactProps) {
return props.name ?? (yield* createPhysicalName({ id }));
});
// Email addresses are unique account-wide (CreateEmailContact rejects
// duplicates with ConflictException), so an address scan is a
// reliable identity fallback when the ARN cache is missing.
const findByAddress = Effect.fn(function* (emailAddress: string) {
return yield* contacts.listEmailContacts.items({}).pipe(
Stream.filter((contact) => unwrapSensitive(contact.address) === emailAddress),
Stream.runHead,
Effect.map(Option.getOrUndefined),
);
});
const getByArn = Effect.fn(function* (arn: string) {
return yield* contacts.getEmailContact({ arn }).pipe(
Effect.map((r) => r.emailContact),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
});
const toAttrs = (live: contacts.EmailContact) => ({
emailContactArn: live.arn,
name: unwrapSensitive(live.name),
emailAddress: unwrapSensitive(live.address),
status: live.status,
});
return EmailContact.Provider.of({
stables: ["emailContactArn", "name", "emailAddress"],
list: () =>
contacts.listEmailContacts.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).map(toAttrs)),
),
read: Effect.fn(function* ({ id, olds, output }) {
const found = output?.emailContactArn
? yield* getByArn(output.emailContactArn)
: olds?.emailAddress
? yield* findByAddress(olds.emailAddress)
: undefined;
if (!found) return undefined;
const attrs = toAttrs(found);
const tags = yield* readContactTags(found.arn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds);
const newName = yield* createName(id, news);
// No update API — any change to the contact itself replaces it.
if (oldName !== newName || news.emailAddress !== olds.emailAddress) {
return { action: "replace" } as const;
}
return undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = yield* createName(id, news);
// OBSERVE — cloud state is authoritative; the cached ARN falls
// through to an address scan when it no longer resolves.
let live = output?.emailContactArn
? yield* getByArn(output.emailContactArn)
: yield* findByAddress(news.emailAddress);
// ENSURE — create when missing; ConflictException means a
// same-address contact already exists (race) → re-observe.
if (live === undefined) {
const created = yield* contacts
.createEmailContact({
name,
emailAddress: news.emailAddress,
tags: news.tags,
})
.pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
live = created ? yield* getByArn(created.arn) : yield* findByAddress(news.emailAddress);
}
const arn = live!.arn;
// SYNC tags — the contact itself is immutable; tags are the only
// mutable aspect (diffed against observed cloud tags).
yield* syncContactTags(arn, id, news.tags);
yield* session.note(arn);
return toAttrs(live!);
}),
delete: Effect.fn(function* ({ output }) {
yield* contacts
.deleteEmailContact({ arn: output.emailContactArn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
});
}),
);