sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ MerchantApiReviews/ MerchantReview.ts

import * as reviews from "@distilled.cloud/gcp/merchantapi_reviews_v1beta";
import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { createInternalLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  accountIdOf,
  configuredAccountIds,
  dataSourceNameOf,
  DEFAULT_COUNTRY,
  DEFAULT_LANGUAGE,
  DEFAULT_REVIEW_TIME,
  findOwnedMerchantReview,
  getMerchantReview,
  hasAlchemyOwnership,
  jsonEqual,
  lastSegment,
  listMerchantReviewsAt,
  merchantReviewNameOf,
  normalizeCustomAttributes,
  ownedByAlchemy,
  parseOwnership,
  parentOf,
  stampCustomAttributes,
  stripCustomAttributes,
  toResourceId,
  type ReviewCustomAttribute,
} from "./internal.ts";

export type MerchantReviewAttributesProps = {
  /** Reviewer's overall rating of the merchant. */
  rating?: number;
  /** Title of the review. */
  title?: string;
  /**
   * Unique, stable identifier for the merchant being reviewed. Defaults
   * to the Merchant Center account id.
   */
  merchantId?: string;
  /** When true, the reviewer remains anonymous. */
  isAnonymous?: boolean;
  /**
   * Timestamp when the review was written (RFC3339).
   * @default "2020-01-01T00:00:00Z"
   */
  reviewTime?: string;
  /** URL of the merchant's main website. */
  merchantLink?: string;
  /** How the review was collected. */
  collectionMethod?: reviews.MerchantReviewAttributesCollectionMethodEnum | (string & {});
  /** Publisher-system identifier for the review author. */
  reviewerId?: string;
  /**
   * BCP-47 language of the review.
   * @default "en"
   */
  reviewLanguage?: string;
  /**
   * ISO 3166-1 alpha-2 country where the reviewer ordered.
   * @default "US"
   */
  reviewCountry?: string;
  /** Human-readable merchant display name. */
  merchantDisplayName?: string;
  /** Landing page that hosts reviews for this merchant. */
  merchantRatingLink?: string;
  /** Maximum possible rating (must be greater than `minRating`). */
  maxRating?: string;
  /** Minimum possible rating (worst value, not "no rating"). */
  minRating?: string;
  /** Display name of the review author. */
  reviewerUsername?: string;
  /**
   * Freeform review text, sent verbatim.
   */
  content?: string;
};

export type MerchantReviewProps = {
  /**
   * Merchant Center account id (the `{account}` segment of
   * `accounts/{account}`). Immutable — changing it replaces the review.
   */
  account: string;
  /**
   * Merchant-reviews data source. Full name
   * `accounts/{account}/dataSources/{datasource}` or the data source id.
   */
  dataSource: string;
  /**
   * User-provided merchant review id. If omitted, a unique id is
   * generated from the stack, stage, and logical id. Immutable —
   * changing it replaces the review.
   */
  merchantReviewId?: string;
  /**
   * Merchant review attributes. `merchantId`, `reviewTime`, and
   * `content` are required by the API; omitted values get defaults.
   */
  merchantReviewAttributes?: MerchantReviewAttributesProps;
  /**
   * Custom (merchant-provided) attributes. Alchemy ownership keys are
   * merged in automatically.
   */
  customAttributes?: ReviewCustomAttribute[];
};

export type MerchantReview = Resource<
  "GCP.MerchantApiReviews.MerchantReview",
  MerchantReviewProps,
  {
    /** Full resource name `accounts/{account}/merchantReviews/{id}`. */
    name: string;
    /** Merchant Center account id. */
    account: string;
    /** User-provided merchant review id. */
    merchantReviewId: string;
    /** Primary data source of the review. */
    dataSource: string | undefined;
    /** Review attributes with the Alchemy ownership prefix stripped. */
    merchantReviewAttributes: MerchantReviewAttributesProps | undefined;
    /** User custom attributes (Alchemy ownership keys stripped). */
    customAttributes: ReviewCustomAttribute[];
    /** Server-computed create time. */
    createTime: string | undefined;
    /** Server-computed last update time. */
    lastUpdateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Merchant Center merchant review (Merchant API Reviews).
 *
 * Reviews have no labels field — Alchemy stamps ownership into
 * `customAttributes` (never the review text) so `list` / nuke can find
 * them. `account` and `merchantReviewId` are identity.
 * `insertAccountsMerchantReviews` is a full-document upsert, so updates
 * replace the review in place. Creating a review requires a Merchant
 * Center account enrolled in merchant reviews and a merchant-reviews
 * data source.
 *
 * ### Creating a Merchant Review
 * **Example:** Generated id
 * ```typescript
 * const review = yield* GCP.MerchantApiReviews.MerchantReview("Storefront", {
 *   account: "123456",
 *   dataSource: "accounts/123456/dataSources/789",
 *   merchantReviewAttributes: {
 *     title: "Great shop",
 *     content: "Fast shipping",
 *     rating: 5,
 *   },
 * });
 * ```
 *
 * **Example:** Explicit id
 * ```typescript
 * const review = yield* GCP.MerchantApiReviews.MerchantReview("Storefront", {
 *   account: "123456",
 *   dataSource: "accounts/123456/dataSources/789",
 *   merchantReviewId: "storefront-2020",
 *   merchantReviewAttributes: {
 *     title: "Great shop",
 *     content: "Fast shipping",
 *     rating: 5,
 *     reviewLanguage: "en",
 *     reviewCountry: "US",
 *   },
 * });
 * ```
 *
 * ### Updating a Merchant Review
 * **Example:** Change the title and rating
 * ```typescript
 * const review = yield* GCP.MerchantApiReviews.MerchantReview("Storefront", {
 *   account: "123456",
 *   dataSource: "accounts/123456/dataSources/789",
 *   merchantReviewAttributes: {
 *     title: "Even better",
 *     content: "Fast shipping and packing",
 *     rating: 5,
 *   },
 * });
 * ```
 *
 * @resource
 * @category MerchantApiReviews
 */
export const MerchantReview = Resource<MerchantReview>("GCP.MerchantApiReviews.MerchantReview");

export class MerchantReviewNotResolved extends Data.TaggedError(
  "GCP.MerchantApiReviews.MerchantReviewNotResolved",
)<{
  resourceName: string;
}> {}

const attributesOf = (
  attrs: reviews.MerchantReviewAttributes | undefined,
): MerchantReviewAttributesProps | undefined => {
  if (attrs === undefined) return undefined;
  return {
    rating: attrs.rating,
    title: attrs.title,
    merchantId: attrs.merchantId,
    isAnonymous: attrs.isAnonymous,
    reviewTime: attrs.reviewTime,
    merchantLink: attrs.merchantLink,
    collectionMethod: attrs.collectionMethod,
    reviewerId: attrs.reviewerId,
    reviewLanguage: attrs.reviewLanguage,
    reviewCountry: attrs.reviewCountry,
    merchantDisplayName: attrs.merchantDisplayName,
    merchantRatingLink: attrs.merchantRatingLink,
    maxRating: attrs.maxRating,
    minRating: attrs.minRating,
    reviewerUsername: attrs.reviewerUsername,
    content: parseOwnership(attrs.content).text,
  };
};

const toAttrs = (review: reviews.MerchantReview, account: string, dataSource?: string) => {
  const merchantReviewId = review.merchantReviewId ?? (review.name ? lastSegment(review.name) : "");
  return {
    name: review.name ?? merchantReviewNameOf(account, merchantReviewId),
    account: accountIdOf(account),
    merchantReviewId,
    dataSource: review.dataSource ?? dataSource,
    merchantReviewAttributes: attributesOf(review.merchantReviewAttributes),
    customAttributes: stripCustomAttributes(review.customAttributes),
    createTime: review.merchantReviewStatus?.createTime,
    lastUpdateTime: review.merchantReviewStatus?.lastUpdateTime,
  };
};

const desiredAttributes = (input: {
  account: string;
  ownership: Record<string, string>;
  attrs: MerchantReviewAttributesProps | undefined;
}): reviews.MerchantReviewAttributes => ({
  rating: input.attrs?.rating,
  title: input.attrs?.title,
  merchantId: input.attrs?.merchantId ?? input.account,
  isAnonymous: input.attrs?.isAnonymous,
  reviewTime: input.attrs?.reviewTime ?? DEFAULT_REVIEW_TIME,
  merchantLink: input.attrs?.merchantLink,
  collectionMethod: input.attrs?.collectionMethod,
  reviewerId: input.attrs?.reviewerId,
  reviewLanguage: input.attrs?.reviewLanguage ?? DEFAULT_LANGUAGE,
  reviewCountry: input.attrs?.reviewCountry ?? DEFAULT_COUNTRY,
  merchantDisplayName: input.attrs?.merchantDisplayName,
  merchantRatingLink: input.attrs?.merchantRatingLink,
  maxRating: input.attrs?.maxRating,
  minRating: input.attrs?.minRating,
  reviewerUsername: input.attrs?.reviewerUsername,
  content: input.attrs?.content,
});

const desiredBody = (input: {
  merchantReviewId: string;
  attributes: reviews.MerchantReviewAttributes;
  customAttributes: reviews.CustomAttribute[];
}): reviews.MerchantReview => ({
  merchantReviewId: input.merchantReviewId,
  merchantReviewAttributes: input.attributes,
  customAttributes: input.customAttributes,
});

const reviewNeedsSync = (current: reviews.MerchantReview, desired: reviews.MerchantReview) =>
  !jsonEqual(current.merchantReviewId, desired.merchantReviewId) ||
  !jsonEqual(current.merchantReviewAttributes, desired.merchantReviewAttributes) ||
  !jsonEqual(
    normalizeCustomAttributes(current.customAttributes),
    normalizeCustomAttributes(desired.customAttributes),
  );

export const MerchantReviewProvider = () =>
  Provider.succeed(MerchantReview, {
    stables: ["name", "account", "merchantReviewId"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousAccount = olds?.account ?? output?.account;
      if (
        previousAccount !== undefined &&
        accountIdOf(news.account) !== accountIdOf(previousAccount)
      ) {
        return { action: "replace" as const, deleteFirst: false };
      }
      const previousId = olds?.merchantReviewId ?? output?.merchantReviewId;
      if (
        previousId !== undefined &&
        news.merchantReviewId !== undefined &&
        news.merchantReviewId !== previousId
      ) {
        return { action: "replace" as const, deleteFirst: true };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output, previous }) {
      const account = olds?.account ?? output?.account ?? "";
      const merchantReviewId = yield* toResourceId(
        id,
        olds?.merchantReviewId,
        output?.merchantReviewId,
      );
      const name = output?.name ?? merchantReviewNameOf(account, merchantReviewId);
      let existing = yield* getMerchantReview(name);
      if (existing === undefined && account) {
        existing = yield* findOwnedMerchantReview(id, account, merchantReviewId);
      }
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, account, olds?.dataSource ?? output?.dataSource);
      return (yield* ownedByAlchemy(id, {
        customAttributes: existing.customAttributes,
        content: existing.merchantReviewAttributes?.content,
      }))
        ? attrs
        : unownedUnlessPrevious(attrs, previous, "name");
    }),

    list: () =>
      Effect.gen(function* () {
        const accounts = yield* configuredAccountIds();
        const pages = yield* Effect.forEach(accounts, (account) => listMerchantReviewsAt(account), {
          concurrency: 4,
        });
        const attrs = [];
        for (let i = 0; i < pages.length; i++) {
          const account = accounts[i]!;
          for (const review of pages[i] ?? []) {
            if (
              !hasAlchemyOwnership({
                customAttributes: review.customAttributes,
                content: review.merchantReviewAttributes?.content,
              })
            ) {
              continue;
            }
            attrs.push(toAttrs(review, account, review.dataSource));
          }
        }
        return attrs;
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const account = accountIdOf(news.account);
      const merchantReviewId = yield* toResourceId(
        id,
        news.merchantReviewId,
        output?.merchantReviewId,
      );
      const dataSource = dataSourceNameOf(account, news.dataSource);
      const name = output?.name ?? merchantReviewNameOf(account, merchantReviewId);
      const ownership = yield* createInternalLabels(id);
      const attributes = desiredAttributes({
        account,
        ownership,
        attrs: news.merchantReviewAttributes,
      });
      const customAttributes = stampCustomAttributes(ownership, news.customAttributes);
      const desired = desiredBody({
        merchantReviewId,
        attributes,
        customAttributes,
      });

      let current = yield* getMerchantReview(name);
      if (current === undefined) {
        current = yield* findOwnedMerchantReview(id, account, merchantReviewId);
      }

      const upsert = () =>
        reviews
          .insertAccountsMerchantReviews({
            parent: parentOf(account),
            dataSource,
            body: desired,
          })
          .pipe(Effect.catchTag("Conflict", () => getMerchantReview(name)));

      if (current === undefined) {
        current = (yield* upsert()) ?? undefined;
      } else if (reviewNeedsSync(current, desired)) {
        current = (yield* upsert()) ?? current;
      }

      if (current === undefined) {
        return yield* new MerchantReviewNotResolved({ resourceName: name });
      }

      return toAttrs(current, account, dataSource);
    }),

    delete: Effect.fn(function* ({ output }) {
      if (!output.name) return;
      yield* reviews
        .deleteAccountsMerchantReviews({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });