sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AppIntegrations/ DataIntegration.ts

import * as appintegrations from "@distilled.cloud/aws/appintegrations";
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 Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { definedTags } from "./internal.ts";

export interface DataIntegrationScheduleConfig {
  /**
   * The start date for objects to import, in ISO 8601 format,
   * e.g. `2024-01-01T00:00:00Z`.
   */
  firstExecutionFrom?: string;
  /**
   * The name of the object to pull from the data source.
   */
  object?: string;
  /**
   * How often the data should be pulled from the data source, e.g.
   * `rate(1 hours)`.
   */
  scheduleExpression: string;
}

export interface DataIntegrationProps {
  /**
   * Name of the data integration. If omitted, a unique name is generated
   * from the app, stage, and logical ID. The name can be updated in place.
   */
  name?: string;
  /**
   * Description of the data integration (1-1000 characters).
   */
  description?: string;
  /**
   * The ARN of the KMS key used to encrypt the data integration. Changing
   * the key replaces the data integration.
   */
  kmsKey: string;
  /**
   * The URI of the data source, e.g. `s3://my-bucket` or
   * `Salesforce://AppFlow/my-connector-profile`. Changing the source URI
   * replaces the data integration.
   */
  sourceURI: string;
  /**
   * The scheduling configuration for pulling data from the source. Required
   * for SaaS (AppFlow) sources; must be omitted for S3 sources. Changing it
   * replaces the data integration.
   */
  scheduleConfig?: DataIntegrationScheduleConfig;
  /**
   * The configuration for which files to pull from the source (folders and
   * filters). Changing it replaces the data integration.
   */
  fileConfiguration?: {
    /**
     * Identifiers for the source folders to pull all files from recursively.
     */
    folders: string[];
    /**
     * Restrictions for what files should be pulled from the source.
     */
    filters?: Record<string, string[]>;
  };
  /**
   * The configuration for which objects and fields to pull from the source.
   * Changing it replaces the data integration.
   */
  objectConfiguration?: Record<string, Record<string, string[]>>;
  /**
   * Tags to apply to the data integration. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface DataIntegration extends Resource<
  "AWS.AppIntegrations.DataIntegration",
  DataIntegrationProps,
  {
    dataIntegrationId: string;
    dataIntegrationArn: string;
    dataIntegrationName: string;
    kmsKey: string;
    sourceURI: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon AppIntegrations data integration. Data integrations reference an
 * external data source (an S3 bucket, or a SaaS application through Amazon
 * AppFlow) so services like Amazon Q in Connect can ingest its content.
 *
 * The KMS key, source URI, schedule, file configuration, and object
 * configuration are immutable; changing any of them replaces the data
 * integration. Only the name and description can be updated in place.
 * ### Creating a Data Integration
 * **Example:** S3 Data Integration
 * ```typescript
 * import * as AppIntegrations from "@alchemy.run/aws/AppIntegrations";
 * import * as KMS from "@alchemy.run/aws/KMS";
 * import * as S3 from "@alchemy.run/aws/S3";
 *
 * const bucket = yield* S3.Bucket("Content");
 * const key = yield* KMS.Key("ContentKey");
 *
 * const integration = yield* AppIntegrations.DataIntegration("Content", {
 *   kmsKey: key.keyArn,
 *   sourceURI: Output.interpolate`s3://${bucket.bucketName}`,
 * });
 * ```
 *
 * **Example:** Scheduled SaaS Data Integration
 * ```typescript
 * const integration = yield* AppIntegrations.DataIntegration("Salesforce", {
 *   kmsKey: key.keyArn,
 *   sourceURI: "Salesforce://AppFlow/my-connector-profile",
 *   scheduleConfig: {
 *     firstExecutionFrom: "2024-01-01T00:00:00Z",
 *     object: "Account",
 *     scheduleExpression: "rate(1 hours)",
 *   },
 * });
 * ```
 *
 * @resource
 */
export const DataIntegration = Resource<DataIntegration>("AWS.AppIntegrations.DataIntegration");

/**
 * Raised when the AppIntegrations API returns a data integration without
 * the fields required to build the resource attributes.
 */
export class DataIntegrationIncomplete extends Data.TaggedError("DataIntegrationIncomplete")<{
  message: string;
}> {}

export const DataIntegrationProvider = () =>
  Provider.effect(
    DataIntegration,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { name?: string }) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 255 }));
      });

      /** Get a single data integration by ARN or ID; undefined if absent. */
      const observe = (arnOrId: string) =>
        appintegrations
          .getDataIntegration({ Identifier: arnOrId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      /** Find a data integration ARN by name via list enumeration. */
      const findByName = (name: string) =>
        appintegrations.listDataIntegrations.items({}).pipe(
          Stream.filter((item) => item.Name === name),
          Stream.take(1),
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)[0]?.Arn),
        );

      const toAttrs = Effect.fn(function* (live: appintegrations.GetDataIntegrationResponse) {
        if (
          live.Arn === undefined ||
          live.Id === undefined ||
          live.Name === undefined ||
          live.KmsKey === undefined ||
          live.SourceURI === undefined
        ) {
          return yield* new DataIntegrationIncomplete({
            message: `data integration '${live.Name}' is missing Arn, Id, Name, KmsKey, or SourceURI`,
          });
        }
        return {
          dataIntegrationId: live.Id,
          dataIntegrationArn: live.Arn,
          dataIntegrationName: live.Name,
          kmsKey: live.KmsKey,
          sourceURI: live.SourceURI,
        };
      });

      const toScheduleConfiguration = (
        config: DataIntegrationScheduleConfig,
      ): appintegrations.ScheduleConfiguration => ({
        ScheduleExpression: config.scheduleExpression,
        ...(config.firstExecutionFrom !== undefined
          ? { FirstExecutionFrom: config.firstExecutionFrom }
          : {}),
        ...(config.object !== undefined ? { Object: config.object } : {}),
      });

      return DataIntegration.Provider.of({
        stables: ["dataIntegrationId", "dataIntegrationArn", "kmsKey", "sourceURI"],

        // The list API only returns Arn/Name/SourceURI summaries — hydrate
        // each into the full attributes shape, tolerating per-item NotFound
        // races.
        list: () =>
          Effect.gen(function* () {
            const arns = yield* appintegrations.listDataIntegrations.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((item) => (item.Arn !== undefined ? [item.Arn] : [])),
              ),
            );
            const items = yield* Effect.forEach(
              arns,
              (arn) =>
                observe(arn).pipe(
                  Effect.flatMap((live) => (live === undefined ? Effect.undefined : toAttrs(live))),
                ),
              { concurrency: 10 },
            );
            return items.filter(
              (item): item is DataIntegration["Attributes"] => item !== undefined,
            );
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          let identifier: string | undefined = output?.dataIntegrationId;
          if (identifier === undefined) {
            const name = yield* createName(id, olds ?? {});
            identifier = yield* findByName(name);
          }
          if (identifier === undefined) return undefined;
          const live = yield* observe(identifier);
          if (live === undefined) return undefined;
          const attrs = yield* toAttrs(live);
          const tags = definedTags(live.Tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds === undefined) return undefined;
          if (
            olds.kmsKey !== news.kmsKey ||
            olds.sourceURI !== news.sourceURI ||
            JSON.stringify(olds.scheduleConfig) !== JSON.stringify(news.scheduleConfig) ||
            JSON.stringify(olds.fileConfiguration) !== JSON.stringify(news.fileConfiguration) ||
            JSON.stringify(olds.objectConfiguration) !== JSON.stringify(news.objectConfiguration)
          ) {
            return { action: "replace" } as const;
          }
          // fall through: default update path (name, description, tags)
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* createName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. Observe — prefer the cached ID; fall back to enumerating by
          //    name so a lost-state re-run converges.
          let identifier: string | undefined = output?.dataIntegrationId;
          let live = identifier === undefined ? undefined : yield* observe(identifier);
          if (live === undefined) {
            identifier = yield* findByName(name);
            live = identifier === undefined ? undefined : yield* observe(identifier);
          }

          // 2. Ensure — create if missing.
          if (live === undefined) {
            const created = yield* appintegrations.createDataIntegration({
              Name: name,
              Description: news.description,
              KmsKey: news.kmsKey,
              SourceURI: news.sourceURI,
              ScheduleConfig: news.scheduleConfig
                ? toScheduleConfiguration(news.scheduleConfig)
                : undefined,
              FileConfiguration: news.fileConfiguration
                ? {
                    Folders: news.fileConfiguration.folders,
                    ...(news.fileConfiguration.filters
                      ? { Filters: news.fileConfiguration.filters }
                      : {}),
                  }
                : undefined,
              ObjectConfiguration: news.objectConfiguration,
              Tags: desiredTags,
            });
            if (created.Arn === undefined) {
              return yield* new DataIntegrationIncomplete({
                message: `createDataIntegration for '${name}' returned no Arn`,
              });
            }
            live = yield* appintegrations.getDataIntegration({
              Identifier: created.Arn,
            });
          }
          const attrs = yield* toAttrs(live);

          // 3. Sync mutable aspects — only the name and description can be
          //    updated in place. The API cannot clear a description (min
          //    length 1), so only push a defined value that differs.
          const update: Omit<appintegrations.UpdateDataIntegrationRequest, "Identifier"> = {};
          if (live.Name !== name) {
            update.Name = name;
          }
          if (news.description !== undefined && news.description !== live.Description) {
            update.Description = news.description;
          }
          if (Object.keys(update).length > 0) {
            yield* appintegrations.updateDataIntegration({
              Identifier: attrs.dataIntegrationId,
              ...update,
            });
          }

          // 4. Sync tags — diff against OBSERVED cloud tags so adoption
          //    converges.
          const observedTags = definedTags(live.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* appintegrations.tagResource({
              resourceArn: attrs.dataIntegrationArn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* appintegrations.untagResource({
              resourceArn: attrs.dataIntegrationArn,
              tagKeys: removed,
            });
          }

          yield* session.note(name);
          return { ...attrs, dataIntegrationName: name };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* appintegrations
            .deleteDataIntegration({
              DataIntegrationIdentifier: output.dataIntegrationId,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );