sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SocialMessaging/ LinkedWhatsAppBusinessAccount.ts

import * as socialmessaging from "@distilled.cloud/aws/socialmessaging";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export class LinkedWhatsAppBusinessAccountInvalidProps extends Data.TaggedError(
  "LinkedWhatsAppBusinessAccountInvalidProps",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type RegistrationStatus = socialmessaging.RegistrationStatus;
export type WhatsAppPhoneNumberSummary = socialmessaging.WhatsAppPhoneNumberSummary;

/**
 * An event destination (Amazon SNS topic) that AWS End User Messaging Social
 * publishes WhatsApp events (messages, message status updates) to.
 */
export interface LinkedWhatsAppBusinessAccountEventDestination {
  /**
   * ARN of the SNS topic that receives WhatsApp events for this account.
   */
  eventDestinationArn: string;
  /**
   * ARN of an IAM role the service assumes to publish to the topic. Omit to
   * publish with a service principal.
   */
  roleArn?: string;
}

export interface LinkedWhatsAppBusinessAccountProps {
  /**
   * The unique identifier of the WhatsApp Business Account already linked to
   * your AWS account (format `waba-...`).
   *
   * WhatsApp Business onboarding requires the Meta embedded-signup OAuth flow
   * in the AWS console and cannot be automated — this resource adopts and
   * manages an account that has already been linked. Changing the identifier
   * replaces the resource.
   */
  accountId: string;
  /**
   * Event destinations (SNS topics) to publish WhatsApp events to. When set,
   * the full list is synced (the API replaces the whole list). When omitted,
   * existing event destinations are left untouched.
   */
  eventDestinations?: LinkedWhatsAppBusinessAccountEventDestination[];
  /**
   * Tags to associate with the linked WhatsApp Business Account.
   */
  tags?: Record<string, string>;
}

export interface LinkedWhatsAppBusinessAccount extends Resource<
  "AWS.SocialMessaging.LinkedWhatsAppBusinessAccount",
  LinkedWhatsAppBusinessAccountProps,
  {
    /**
     * ARN of the linked WhatsApp Business Account.
     */
    arn: string;
    /**
     * The unique identifier of the linked WhatsApp Business Account
     * (`waba-...`).
     */
    id: string;
    /**
     * The WhatsApp Business Account ID from Meta.
     */
    wabaId: string;
    /**
     * The name of the WhatsApp Business Account.
     */
    wabaName: string;
    /**
     * Registration status of the linked account (`COMPLETE` | `INCOMPLETE`).
     */
    registrationStatus: RegistrationStatus;
    /**
     * ISO-8601 date the WhatsApp Business Account was linked.
     */
    linkDate: string;
    /**
     * Event destinations currently configured on the account.
     */
    eventDestinations: LinkedWhatsAppBusinessAccountEventDestination[];
    /**
     * Phone numbers registered to the WhatsApp Business Account.
     */
    phoneNumbers: WhatsAppPhoneNumberSummary[];
    /**
     * Current tags reported for the account.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A WhatsApp Business Account (WABA) linked to your AWS account through
 * AWS End User Messaging Social.
 *
 * :::caution
 * Linking a WhatsApp Business Account requires the Meta embedded-signup
 * OAuth flow in the AWS console and cannot be automated. This resource
 * adopts an already-linked account by its `waba-...` identifier and manages
 * its event destinations and tags. Destroying the resource disassociates
 * the WhatsApp Business Account from your AWS account.
 * :::
 * ### Managing a Linked Account
 * **Example:** Adopt a console-linked WABA and route events to SNS
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const events = yield* AWS.SNS.Topic("WhatsAppEvents", {});
 *
 * const waba = yield* AWS.SocialMessaging.LinkedWhatsAppBusinessAccount(
 *   "Business",
 *   {
 *     // from the AWS End User Messaging Social console after onboarding
 *     accountId: "waba-0123456789abcdef0123456789abcdef",
 *     eventDestinations: [{ eventDestinationArn: events.topicArn }],
 *     tags: { team: "growth" },
 *   },
 * );
 * ```
 *
 * ### Consuming WhatsApp Events
 * **Example:** Handle Inbound Messages in a Lambda
 * WhatsApp events (inbound messages, message status updates) are delivered
 * exclusively to the SNS topics listed in `eventDestinations` — there is no
 * separate event source for this service. Compose the resource with
 * `AWS.SNS.consumeTopicNotifications` on the destination topic:
 * ```typescript
 * const events = yield* AWS.SNS.Topic("WhatsAppEvents", {});
 *
 * const waba = yield* AWS.SocialMessaging.LinkedWhatsAppBusinessAccount(
 *   "Business",
 *   {
 *     accountId: "waba-0123456789abcdef0123456789abcdef",
 *     eventDestinations: [{ eventDestinationArn: events.topicArn }],
 *   },
 * );
 *
 * // inside a Lambda Function's init effect
 * yield* AWS.SNS.consumeTopicNotifications(events, (stream) =>
 *   stream.pipe(
 *     Stream.runForEach((notification) =>
 *       Effect.log("whatsapp event", notification.Message),
 *     ),
 *   ),
 * );
 * ```
 *
 * @resource
 */
export const LinkedWhatsAppBusinessAccount = Resource<LinkedWhatsAppBusinessAccount>(
  "AWS.SocialMessaging.LinkedWhatsAppBusinessAccount",
);

/**
 * The referenced WhatsApp Business Account is not linked to this AWS
 * account. Linking requires the Meta embedded-signup flow in the AWS
 * console and cannot be performed by the provider.
 */
export class WhatsAppBusinessAccountNotLinked extends Data.TaggedError(
  "WhatsAppBusinessAccountNotLinked",
)<{
  readonly accountId: string;
}> {}

const fetchTags = Effect.fn(function* (arn: string) {
  const response = yield* socialmessaging.listTagsForResource({
    resourceArn: arn,
  });
  return Object.fromEntries(
    (response.tags ?? []).flatMap((tag) =>
      tag.value === undefined ? [] : [[tag.key, tag.value] as const],
    ),
  );
});

interface LinkedAccountState {
  attrs: LinkedWhatsAppBusinessAccount["Attributes"];
  account: socialmessaging.LinkedWhatsAppBusinessAccount;
}

const readLinkedAccount = Effect.fn(function* (accountId: string) {
  const response = yield* socialmessaging
    .getLinkedWhatsAppBusinessAccount({ id: accountId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  const account = response?.account;
  if (account === undefined) return undefined;
  const state: LinkedAccountState = {
    account,
    attrs: {
      arn: account.arn,
      id: account.id,
      wabaId: account.wabaId,
      wabaName: account.wabaName,
      registrationStatus: account.registrationStatus,
      linkDate: account.linkDate.toISOString(),
      eventDestinations: account.eventDestinations.map((destination) => ({
        eventDestinationArn: destination.eventDestinationArn,
        roleArn: destination.roleArn,
      })),
      phoneNumbers: account.phoneNumbers.map((phone) => ({ ...phone })),
      tags: yield* fetchTags(account.arn),
    },
  };
  return state;
});

const sortDestinations = (destinations: LinkedWhatsAppBusinessAccountEventDestination[]) =>
  destinations
    .map((destination) => ({
      eventDestinationArn: destination.eventDestinationArn,
      roleArn: destination.roleArn,
    }))
    .sort((l, r) => l.eventDestinationArn.localeCompare(r.eventDestinationArn));

const destinationsDrifted = (
  observed: LinkedWhatsAppBusinessAccountEventDestination[],
  desired: LinkedWhatsAppBusinessAccountEventDestination[],
) => {
  const left = sortDestinations(observed);
  const right = sortDestinations(desired);
  return (
    left.length !== right.length ||
    left.some(
      (destination, index) =>
        destination.eventDestinationArn !== right[index].eventDestinationArn ||
        destination.roleArn !== right[index].roleArn,
    )
  );
};

export const LinkedWhatsAppBusinessAccountProvider = () =>
  Provider.effect(
    LinkedWhatsAppBusinessAccount,
    Effect.gen(function* () {
      return {
        stables: ["arn", "id", "wabaId"],
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* socialmessaging.listLinkedWhatsAppBusinessAccounts
              .pages({})
              .pipe(
                EffectStream.runCollect,
                Effect.map((chunk) =>
                  Array.from(chunk).flatMap((page) => page.linkedAccounts ?? []),
                ),
              );
            const hydrated = yield* Effect.forEach(
              summaries,
              (summary) => readLinkedAccount(summary.id),
              { concurrency: 5 },
            );
            return hydrated.flatMap((state) => (state === undefined ? [] : [state.attrs]));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const accountId = output?.id ?? olds?.accountId;
          if (accountId === undefined) return undefined;
          const state = yield* readLinkedAccount(accountId);
          if (state === undefined) return undefined;
          return (yield* hasAlchemyTags(id, state.attrs.tags as Tags))
            ? state.attrs
            : Unowned(state.attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          // The linked account identity is fixed by Meta onboarding.
          if (news.accountId !== olds.accountId) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news?.accountId) {
            return yield* new LinkedWhatsAppBusinessAccountInvalidProps({
              message:
                "LinkedWhatsAppBusinessAccount requires an accountId (link the WABA in the AWS console first)",
            });
          }
          const accountId = output?.id ?? news.accountId;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — onboarding is console-only, so the account must already
          // be linked; there is no create path to fall through to.
          const state = yield* readLinkedAccount(accountId);
          if (state === undefined) {
            return yield* new WhatsAppBusinessAccountNotLinked({ accountId });
          }

          // Sync event destinations — the API replaces the full list.
          if (
            news.eventDestinations !== undefined &&
            destinationsDrifted(state.attrs.eventDestinations, news.eventDestinations)
          ) {
            yield* socialmessaging.putWhatsAppBusinessAccountEventDestinations({
              id: state.attrs.id,
              eventDestinations: news.eventDestinations.map((destination) => ({
                eventDestinationArn: destination.eventDestinationArn,
                roleArn: destination.roleArn,
              })),
            });
            yield* session.note(`Updated event destinations for ${state.attrs.id}`);
          }

          // Sync tags — diff against observed cloud tags.
          const { removed, upsert } = diffTags(state.attrs.tags, desiredTags);
          if (removed.length > 0) {
            yield* socialmessaging.untagResource({
              resourceArn: state.attrs.arn,
              tagKeys: removed,
            });
          }
          if (upsert.length > 0) {
            yield* socialmessaging.tagResource({
              resourceArn: state.attrs.arn,
              tags: upsert.map(({ Key, Value }) => ({
                key: Key,
                value: Value,
              })),
            });
          }

          yield* session.note(state.attrs.arn);

          const final = yield* readLinkedAccount(accountId);
          if (final === undefined) {
            return yield* new WhatsAppBusinessAccountNotLinked({ accountId });
          }
          return final.attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* socialmessaging
            .disassociateWhatsAppBusinessAccount({ id: output.id })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );