sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Vault/ MattersHold.ts

import * as vault from "@distilled.cloud/gcp/vault_v1";
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 { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  desiredAccounts,
  encodeOwnershipLine,
  findHoldByName,
  findOwnedHold,
  getHold,
  hasOwnershipMarker,
  ignoreMissing,
  jsonEqual,
  listActiveMatters,
  listHolds,
  MAX_HOLD_NAME_LENGTH,
  ownedByAlchemy,
  ownershipLabels,
  parseOwnership,
  sameAccounts,
  sameOrgUnit,
  toGeneratedName,
} from "./internal.ts";

export type HeldAccount = {
  /** Primary email. Takes precedence over `accountId` on write. */
  email?: string;
  /** Admin SDK account id. */
  accountId?: string;
};

export type HeldOrgUnit = {
  /** Admin SDK organizational unit id. */
  orgUnitId?: string;
};

export type MattersHoldProps = {
  /**
   * Parent matter id. Immutable — changing it replaces the hold.
   */
  matterId: string;
  /**
   * Server-assigned hold id. Leave blank on create. Immutable —
   * changing it replaces the hold.
   */
  holdId?: string;
  /**
   * Hold name (max 100 characters including Alchemy's ownership marker).
   * Vault holds have no labels field, so ownership is stored in a
   * `[alchemy …]` prefix and stripped from attributes. Immutable —
   * changing it replaces the hold.
   */
  name?: string;
  /**
   * Workspace service covered by the hold. Immutable — changing it
   * replaces the hold.
   */
  corpus: vault.HoldCorpusEnum | (string & {});
  /**
   * Individual accounts covered by the hold. Mutually exclusive with
   * `orgUnit` — switching scope replaces the hold.
   */
  accounts?: HeldAccount[];
  /**
   * Organizational unit covered by the hold. Mutually exclusive with
   * `accounts` — switching scope replaces the hold.
   */
  orgUnit?: HeldOrgUnit;
  /**
   * Service-specific query options. Must match `corpus`.
   */
  query?: vault.CorpusQuery;
};

export type MattersHold = Resource<
  "GCP.Vault.MattersHold",
  MattersHoldProps,
  {
    /** Server-assigned hold id. */
    holdId: string;
    /** Parent matter id. */
    matterId: string;
    /** Project id used when the hold was reconciled. */
    project: string;
    /** User-facing name with the Alchemy ownership prefix stripped. */
    name: string | undefined;
    /** Workspace service covered by the hold. */
    corpus: string | undefined;
    /** Individual accounts on the hold. */
    accounts: HeldAccount[] | undefined;
    /** Organizational unit on the hold. */
    orgUnit: HeldOrgUnit | undefined;
    /** Service-specific query options. */
    query: vault.CorpusQuery | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Google Vault hold on a matter.
 *
 * Vault holds have no labels field, so Alchemy stamps ownership into
 * `name` for `list` / nuke. Parent matter, hold id, corpus, and name are
 * identity. Query, accounts, and org unit update in place. Switching
 * between accounts and an org unit replaces the hold.
 *
 * ### Creating a Hold
 * **Example:** Mail hold on accounts
 * ```typescript
 * const hold = yield* GCP.Vault.MattersHold("Mail", {
 *   matterId: matter.matterId,
 *   corpus: "MAIL",
 *   accounts: [{ email: "user@example.com" }],
 *   query: { mailQuery: { terms: "subject:contract" } },
 * });
 * ```
 *
 * **Example:** Drive hold on an org unit
 * ```typescript
 * const hold = yield* GCP.Vault.MattersHold("Drive", {
 *   matterId: matter.matterId,
 *   name: "Drive OU",
 *   corpus: "DRIVE",
 *   orgUnit: { orgUnitId: "id:ou" },
 *   query: { driveQuery: { includeSharedDriveFiles: true } },
 * });
 * ```
 *
 * ### Updating a Hold
 * **Example:** Narrow the mail query
 * ```typescript
 * // Same logical id, changed props: the engine updates it in place.
 * const hold = yield* GCP.Vault.MattersHold("Mail", {
 *   matterId: matter.matterId,
 *   corpus: "MAIL",
 *   accounts: [{ email: "user@example.com" }],
 *   query: { mailQuery: { terms: "subject:contract 2026" } },
 * });
 * ```
 *
 * @resource
 * @category Vault
 */
export const MattersHold = Resource<MattersHold>("GCP.Vault.MattersHold");

export class MattersHoldNotResolved extends Data.TaggedError("GCP.Vault.MattersHoldNotResolved")<{
  matterId: string;
  holdId: string;
}> {}

const accountsOf = (accounts: vault.HeldAccountList | undefined): HeldAccount[] | undefined => {
  if (accounts === undefined) return undefined;
  return accounts.map((account) => ({
    email: account.email,
    accountId: account.accountId,
  }));
};

const orgUnitOf = (orgUnit: vault.HeldOrgUnit | undefined): HeldOrgUnit | undefined => {
  if (orgUnit === undefined) return undefined;
  return { orgUnitId: orgUnit.orgUnitId };
};

const toAttrs = (hold: vault.Hold, matterId: string, project: string) => ({
  holdId: hold.holdId ?? "",
  matterId: matterId,
  project,
  name: parseOwnership(hold.name).text,
  corpus: hold.corpus,
  accounts: accountsOf(hold.accounts),
  orgUnit: orgUnitOf(hold.orgUnit),
  query: hold.query,
  updateTime: hold.updateTime,
});

export const MattersHoldProvider = () =>
  Provider.succeed(MattersHold, {
    stables: ["holdId", "matterId", "project"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousMatter = olds?.matterId ?? output?.matterId;
      if (previousMatter !== undefined && news.matterId !== previousMatter) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousId = olds?.holdId ?? output?.holdId;
      if (previousId !== undefined && news.holdId !== undefined && news.holdId !== previousId) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousCorpus = olds?.corpus ?? output?.corpus;
      if (previousCorpus !== undefined && news.corpus !== previousCorpus) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousName = olds?.name ?? output?.name;
      if (news.name !== undefined && previousName !== undefined && news.name !== previousName) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousOrg = olds?.orgUnit ?? output?.orgUnit;
      const previousAccounts = olds?.accounts ?? output?.accounts;
      if (
        previousOrg?.orgUnitId !== undefined &&
        news.accounts !== undefined &&
        news.accounts.length > 0
      ) {
        return { action: "replace" as const, deleteFirst: true };
      }
      if (
        previousAccounts !== undefined &&
        previousAccounts.length > 0 &&
        news.orgUnit?.orgUnitId !== undefined
      ) {
        return { action: "replace" as const, deleteFirst: true };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output, previous }) {
      const env = yield* GcpEnvironment.current;
      const matterId = olds?.matterId ?? output?.matterId ?? "";
      const holdId = olds?.holdId ?? output?.holdId ?? "";
      let existing = yield* getHold(matterId, holdId);
      let parentId = matterId;
      if (existing === undefined) {
        const ownership = yield* ownershipLabels(id);
        const name = encodeOwnershipLine(
          ownership,
          olds?.name ?? output?.name,
          MAX_HOLD_NAME_LENGTH,
        );
        existing = yield* findHoldByName(matterId, name);
      }
      if (existing === undefined) {
        const owned = yield* findOwnedHold(id, matterId);
        if (owned !== undefined) {
          existing = owned.hold;
          parentId = owned.matterId;
        }
      }
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, parentId || (existing.holdId ?? ""), env.project);
      const resolvedMatter = parentId.length > 0 ? parentId : attrs.matterId;
      return (yield* ownedByAlchemy(id, existing.name))
        ? { ...attrs, matterId: resolvedMatter }
        : unownedUnlessPrevious({ ...attrs, matterId: resolvedMatter }, previous, "holdId");
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const matters = yield* listActiveMatters();
        const pages = yield* Effect.forEach(
          matters,
          (matter) =>
            listHolds(matter.matterId ?? "").pipe(
              Effect.map((holds) =>
                holds
                  .filter((hold) => hasOwnershipMarker(hold.name))
                  .map((hold) => toAttrs(hold, matter.matterId ?? "", env.project)),
              ),
            ),
          { concurrency: 4 },
        );
        return pages.flat();
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const matterId = news.matterId;
      const ownership = yield* ownershipLabels(id);
      const displayName = yield* toGeneratedName(id, news.name, output?.name, 40);
      const name = encodeOwnershipLine(ownership, displayName, MAX_HOLD_NAME_LENGTH);
      const accounts = desiredAccounts(news.accounts);
      const desired: vault.Hold = {
        name,
        corpus: news.corpus,
        accounts,
        orgUnit: news.orgUnit,
        query: news.query,
      };

      let current = yield* getHold(matterId, news.holdId ?? output?.holdId ?? "");
      if (current === undefined) {
        current = yield* findHoldByName(matterId, name);
      }
      if (current === undefined) {
        const owned = yield* findOwnedHold(id, matterId);
        current = owned?.hold;
      }

      if (current === undefined) {
        const created = yield* vault
          .createMattersHolds({
            matterId,
            body: desired,
          })
          .pipe(Effect.catchTag("Conflict", () => findHoldByName(matterId, name)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new MattersHoldNotResolved({
          matterId,
          holdId: news.holdId ?? output?.holdId ?? name,
        });
      }

      const holdId = current.holdId ?? news.holdId ?? output?.holdId ?? "";
      const queryChanged = news.query !== undefined && !jsonEqual(current.query, news.query);
      const accountsChanged =
        news.accounts !== undefined && !sameAccounts(current.accounts, news.accounts);
      const orgUnitChanged =
        news.orgUnit !== undefined && !sameOrgUnit(current.orgUnit, news.orgUnit);

      if (queryChanged || accountsChanged || orgUnitChanged) {
        current = yield* vault.updateMattersHolds({
          matterId,
          holdId,
          body: {
            query: news.query ?? current.query,
            accounts: accounts ?? current.accounts,
            orgUnit: news.orgUnit ?? current.orgUnit,
          },
        });
      }

      return toAttrs(current, matterId, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      if (output.matterId.length === 0 || output.holdId.length === 0) return;
      yield* ignoreMissing(
        vault.deleteMattersHolds({
          matterId: output.matterId,
          holdId: output.holdId,
        }),
      );
    }),
  });