thinkwork-cli 0.12.15 → 0.12.17

package/dist/plugins/twenty/scripts/lib/schema-ensure.ts

@@ -0,0 +1,425 @@
+/**
+ * Idempotent Twenty schema preparation (plan U3, R1–R3).
+ *
+ * Creates only missing custom fields via `createOneField` on `/metadata`, and
+ * merges the migration's stage options into the opportunity `stage` SELECT.
+ * U1 confirmed `updateOneField` FULL-REPLACES the options array, so the merge
+ * always writes existing options + additions; existing options (including
+ * CUSTOMER, which the ThinkWork workflow triggers on) are preserved verbatim.
+ */
+
+import { MIGRATION_STAGE_OPTIONS } from "./mappers";
+import type { TwentyClient } from "./twenty-client";
+
+/** The whole schema delta in one reviewable place (plan U3 approach note). */
+/**
+ * Opportunities carry MULTIPLE product lines (LastMile keeps them in
+ * `task.entity_data->'items'`: 816 opportunities, 82 with 2-5 lines each), so
+ * product/quantity/amount belong on a child object, not on the opportunity
+ * row. This custom object holds one row per line, related many-to-one back to
+ * the opportunity. The opportunity's own `product` (category) and native
+ * `amount` (deal total) stay where they are.
+ */
+export const OPPORTUNITY_PRODUCT_OBJECT = {
+  nameSingular: "opportunityProduct",
+  namePlural: "opportunityProducts",
+  labelSingular: "Opportunity Product",
+  labelPlural: "Opportunity Products",
+  icon: "IconPackage",
+  /** Field created on `opportunity` pointing back at the lines. */
+  targetFieldLabel: "Products",
+} as const;
+
+export const FIELD_SPECS: Array<{
+  object: string;
+  name: string;
+  label: string;
+  type: "TEXT" | "NUMBER" | "BOOLEAN" | "CURRENCY";
+  isUnique?: boolean;
+}> = [
+  {
+    object: "company",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  { object: "company", name: "sourceHash", label: "Source Hash", type: "TEXT" },
+  {
+    object: "person",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  { object: "person", name: "sourceHash", label: "Source Hash", type: "TEXT" },
+  {
+    object: "opportunity",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  {
+    object: "opportunity",
+    name: "sourceHash",
+    label: "Source Hash",
+    type: "TEXT",
+  },
+  { object: "opportunity", name: "product", label: "Product", type: "TEXT" },
+  {
+    object: "opportunity",
+    name: "quantity",
+    label: "Quantity",
+    type: "NUMBER",
+  },
+  {
+    object: "opportunity",
+    name: "isMobil",
+    label: "Mobil Product",
+    type: "BOOLEAN",
+  },
+  {
+    object: "note",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  { object: "note", name: "sourceHash", label: "Source Hash", type: "TEXT" },
+  {
+    object: "attachment",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  // Product-line object (created first when missing; see ensureOpportunityProductObject).
+  {
+    object: "opportunityProduct",
+    name: "sourceId",
+    label: "Source ID",
+    type: "TEXT",
+    isUnique: true,
+  },
+  {
+    object: "opportunityProduct",
+    name: "sourceHash",
+    label: "Source Hash",
+    type: "TEXT",
+  },
+  {
+    object: "opportunityProduct",
+    name: "product",
+    label: "Product",
+    type: "TEXT",
+  },
+  {
+    object: "opportunityProduct",
+    name: "quantity",
+    label: "Quantity",
+    type: "NUMBER",
+  },
+  {
+    object: "opportunityProduct",
+    name: "amount",
+    label: "Amount",
+    type: "CURRENCY",
+  },
+  {
+    object: "opportunityProduct",
+    name: "isMobil",
+    label: "Mobil Product",
+    type: "BOOLEAN",
+  },
+  {
+    object: "opportunityProduct",
+    name: "lineNumber",
+    label: "Line",
+    type: "NUMBER",
+  },
+];
+
+/** Placeholder id used only in dry-run plans, never sent to Twenty. */
+export const PENDING_OBJECT_ID = "<pending-object-creation>";
+
+interface ObjectMetadata {
+  id: string;
+  nameSingular: string;
+  fields: Map<
+    string,
+    { id: string; name: string; type: string; options: StageOption[] | null }
+  >;
+}
+
+export interface StageOption {
+  id?: string;
+  label: string;
+  value: string;
+  color: string;
+  position: number;
+}
+
+const OBJECTS_QUERY = `
+  query MigrationObjects {
+    objects(paging: { first: 1000 }) {
+      edges {
+        node {
+          id
+          nameSingular
+          fields(paging: { first: 1000 }) {
+            edges { node { id name type options } }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const CREATE_FIELD_MUTATION = `
+  mutation MigrationCreateField($input: CreateOneFieldMetadataInput!) {
+    createOneField(input: $input) { id name }
+  }
+`;
+
+const UPDATE_FIELD_MUTATION = `
+  mutation MigrationUpdateField($input: UpdateOneFieldMetadataInput!) {
+    updateOneField(input: $input) { id name options }
+  }
+`;
+
+const CREATE_OBJECT_MUTATION = `
+  mutation MigrationCreateObject($input: CreateOneObjectInput!) {
+    createOneObject(input: $input) { id nameSingular }
+  }
+`;
+
+/**
+ * Create the opportunityProduct object and its many-to-one relation to
+ * opportunity, if absent. Idempotent: returns the existing object's id when it
+ * is already there. Must run before the field pass, which addresses the object
+ * by name. Verified live: the workspace API key may create objects and
+ * RELATION fields via `relationCreationPayload`, and Twenty exposes the FK to
+ * the data API as `opportunityId` on the line's create input.
+ */
+export async function ensureOpportunityProductObject(
+  client: TwentyClient,
+  objects: Map<string, ObjectMetadata>,
+  dryRun: boolean,
+): Promise<{ created: boolean; relationCreated: boolean }> {
+  const existing = objects.get(OPPORTUNITY_PRODUCT_OBJECT.nameSingular);
+  const opportunity = objects.get("opportunity");
+  if (!opportunity) throw new Error('Twenty object "opportunity" not found.');
+
+  if (existing?.fields.has("opportunity")) {
+    return { created: false, relationCreated: false };
+  }
+  if (dryRun) {
+    return { created: !existing, relationCreated: true };
+  }
+
+  let objectId = existing?.id;
+  if (!objectId) {
+    const created = await client.requestOnce<{
+      createOneObject: { id: string };
+    }>("/metadata", CREATE_OBJECT_MUTATION, {
+      input: {
+        object: {
+          nameSingular: OPPORTUNITY_PRODUCT_OBJECT.nameSingular,
+          namePlural: OPPORTUNITY_PRODUCT_OBJECT.namePlural,
+          labelSingular: OPPORTUNITY_PRODUCT_OBJECT.labelSingular,
+          labelPlural: OPPORTUNITY_PRODUCT_OBJECT.labelPlural,
+          icon: OPPORTUNITY_PRODUCT_OBJECT.icon,
+        },
+      },
+    });
+    objectId = created.createOneObject.id;
+  }
+
+  await client.requestOnce("/metadata", CREATE_FIELD_MUTATION, {
+    input: {
+      field: {
+        objectMetadataId: objectId,
+        name: "opportunity",
+        label: "Opportunity",
+        type: "RELATION",
+        relationCreationPayload: {
+          targetObjectMetadataId: opportunity.id,
+          targetFieldLabel: OPPORTUNITY_PRODUCT_OBJECT.targetFieldLabel,
+          targetFieldIcon: OPPORTUNITY_PRODUCT_OBJECT.icon,
+          type: "MANY_TO_ONE",
+        },
+      },
+    },
+  });
+
+  return { created: !existing, relationCreated: true };
+}
+
+export async function fetchObjectMetadata(
+  client: TwentyClient,
+): Promise<Map<string, ObjectMetadata>> {
+  const data = await client.requestWithRetry<{
+    objects: {
+      edges: Array<{
+        node: {
+          id: string;
+          nameSingular: string;
+          fields: {
+            edges: Array<{
+              node: {
+                id: string;
+                name: string;
+                type: string;
+                options: StageOption[] | null;
+              };
+            }>;
+          };
+        };
+      }>;
+    };
+  }>("/metadata", OBJECTS_QUERY);
+
+  const byName = new Map<string, ObjectMetadata>();
+  for (const { node } of data.objects.edges) {
+    byName.set(node.nameSingular, {
+      id: node.id,
+      nameSingular: node.nameSingular,
+      fields: new Map(
+        node.fields.edges.map(({ node: field }) => [field.name, field]),
+      ),
+    });
+  }
+  return byName;
+}
+
+export interface SchemaEnsurePlan {
+  createFields: Array<{
+    object: string;
+    objectMetadataId: string;
+    name: string;
+  }>;
+  stageOptionsToAdd: string[];
+  /** Full merged array to write when stageOptionsToAdd is non-empty. */
+  mergedStageOptions: StageOption[] | null;
+  stageFieldId: string | null;
+}
+
+export function planSchemaEnsure(
+  objects: Map<string, ObjectMetadata>,
+): SchemaEnsurePlan {
+  const createFields: SchemaEnsurePlan["createFields"] = [];
+  for (const spec of FIELD_SPECS) {
+    const object = objects.get(spec.object);
+    if (!object) {
+      // ensureOpportunityProductObject creates this object earlier in the same
+      // run; in a dry-run against a workspace that lacks it, its fields are
+      // planned rather than an error.
+      if (spec.object === OPPORTUNITY_PRODUCT_OBJECT.nameSingular) {
+        createFields.push({
+          object: spec.object,
+          objectMetadataId: PENDING_OBJECT_ID,
+          name: spec.name,
+        });
+        continue;
+      }
+      throw new Error(
+        `Twenty object "${spec.object}" not found in metadata; aborting.`,
+      );
+    }
+    if (!object.fields.has(spec.name)) {
+      createFields.push({
+        object: spec.object,
+        objectMetadataId: object.id,
+        name: spec.name,
+      });
+    }
+  }
+
+  const opportunity = objects.get("opportunity");
+  const stageField = opportunity?.fields.get("stage");
+  if (!stageField || !stageField.options) {
+    throw new Error(
+      "Opportunity stage field (SELECT with options) not found; aborting.",
+    );
+  }
+  const existingValues = new Set(
+    stageField.options.map((option) => option.value),
+  );
+  const additions = MIGRATION_STAGE_OPTIONS.filter(
+    (option) => !existingValues.has(option.value),
+  );
+  let mergedStageOptions: StageOption[] | null = null;
+  if (additions.length > 0) {
+    const preserved = stageField.options.map((option, index) => ({
+      ...(option.id ? { id: option.id } : {}),
+      label: option.label,
+      value: option.value,
+      color: option.color,
+      position: index,
+    }));
+    const appended = additions.map((option, index) => ({
+      label: option.label,
+      value: option.value,
+      color: option.color,
+      position: preserved.length + index,
+    }));
+    mergedStageOptions = [...preserved, ...appended];
+  }
+  return {
+    createFields,
+    stageOptionsToAdd: additions.map((option) => option.value),
+    mergedStageOptions,
+    stageFieldId: stageField.id,
+  };
+}
+
+export interface SchemaEnsureResult {
+  createdFields: string[];
+  addedStageOptions: string[];
+}
+
+export async function applySchemaEnsure(
+  client: TwentyClient,
+  plan: SchemaEnsurePlan,
+): Promise<SchemaEnsureResult> {
+  const createdFields: string[] = [];
+  for (const create of plan.createFields) {
+    const spec = FIELD_SPECS.find(
+      (candidate) =>
+        candidate.object === create.object && candidate.name === create.name,
+    );
+    if (!spec)
+      throw new Error(`No field spec for ${create.object}.${create.name}`);
+    if (create.objectMetadataId === PENDING_OBJECT_ID) {
+      throw new Error(
+        `Field ${create.object}.${create.name} was planned against an uncreated object — ` +
+          `re-plan after ensureOpportunityProductObject so the real object id is known.`,
+      );
+    }
+    // Metadata mutation errors abort the run before any record loading (U3).
+    await client.requestOnce("/metadata", CREATE_FIELD_MUTATION, {
+      input: {
+        field: {
+          objectMetadataId: create.objectMetadataId,
+          name: spec.name,
+          label: spec.label,
+          type: spec.type,
+          ...(spec.isUnique ? { isUnique: true } : {}),
+        },
+      },
+    });
+    createdFields.push(`${create.object}.${create.name}`);
+  }
+
+  if (plan.mergedStageOptions && plan.stageFieldId) {
+    await client.requestOnce("/metadata", UPDATE_FIELD_MUTATION, {
+      input: {
+        id: plan.stageFieldId,
+        update: { options: plan.mergedStageOptions },
+      },
+    });
+  }
+
+  return { createdFields, addedStageOptions: plan.stageOptionsToAdd };
+}

package/dist/plugins/twenty/scripts/lib/twenty-client.ts

@@ -0,0 +1,246 @@
+/**
+ * GraphQL client for Twenty CRM used by the LastMile migration script.
+ *
+ * Follows the TwentyGraphqlClient shape from scripts/wire-thinkwork-workflow.mjs:
+ * Bearer auth, `/graphql` (workspace data) + `/metadata` (field metadata), throws
+ * on `body.errors`. Adds the retry/backoff and batching discipline from the
+ * migration plan (KTD3): reads may auto-retry; mutations are only retried by
+ * callers after re-querying, never blindly.
+ */
+
+export const BATCH_LIMIT = 60;
+
+export type TwentyEndpointPath = "/graphql" | "/metadata";
+
+export class TwentyGraphqlError extends Error {
+  readonly errors: Array<{
+    message: string;
+    extensions?: Record<string, unknown>;
+  }>;
+  readonly httpStatus: number | undefined;
+
+  constructor(
+    message: string,
+    options: {
+      errors?: Array<{ message: string; extensions?: Record<string, unknown> }>;
+      httpStatus?: number;
+    } = {},
+  ) {
+    super(message);
+    this.name = "TwentyGraphqlError";
+    this.errors = options.errors ?? [];
+    this.httpStatus = options.httpStatus;
+  }
+
+  get isDuplicateError(): boolean {
+    return this.errors.some((error) =>
+      /duplicate|unique|already exists/i.test(error.message),
+    );
+  }
+
+  /** Twenty's throttle rejects with a GraphQL error (subCode LIMIT_REACHED),
+   * not HTTP 429. The guard fires before the resolver, so a rate-limited
+   * request had NO side effect — safe to retry even for mutations. */
+  get isRateLimited(): boolean {
+    return (
+      this.httpStatus === 429 ||
+      this.errors.some(
+        (error) =>
+          (error.extensions as { subCode?: string } | undefined)?.subCode ===
+            "LIMIT_REACHED" || /limit reached/i.test(error.message),
+      )
+    );
+  }
+
+  get isRetryable(): boolean {
+    return (
+      this.isNetworkError ||
+      this.isRateLimited ||
+      (this.httpStatus !== undefined && this.httpStatus >= 500)
+    );
+  }
+
+  isNetworkError = false;
+}
+
+export interface TwentyClientOptions {
+  /** e.g. https://crm.tei.thinkwork.ai — no trailing slash. */
+  baseUrl: string;
+  /** Workspace API key or a user access token; sent as Bearer. */
+  authToken: string;
+  fetchImpl?: typeof fetch;
+  /** Base backoff in ms; test seam. */
+  backoffMs?: number;
+  maxRetries?: number;
+  /** Minimum ms between requests — Twenty allows 100 req/min, so the default
+   * paces to ~92/min. 0 disables (tests). */
+  minRequestIntervalMs?: number;
+  /** Wait before retrying a rate-limited request; test seam. */
+  rateLimitWaitMs?: number;
+}
+
+export function normalizeBaseUrl(url: string): string {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+    throw new Error(`Twenty URL must be HTTPS or localhost, got ${url}.`);
+  }
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function chunk<T>(items: readonly T[], size: number): T[][] {
+  if (size < 1) throw new Error(`chunk size must be >= 1, got ${size}`);
+  const chunks: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class TwentyClient {
+  private readonly baseUrl: string;
+  private readonly authToken: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly backoffMs: number;
+  private readonly maxRetries: number;
+  private readonly minRequestIntervalMs: number;
+  private readonly rateLimitWaitMs: number;
+  private nextSlotAt = 0;
+
+  constructor(options: TwentyClientOptions) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.authToken = options.authToken;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.backoffMs = options.backoffMs ?? 1_000;
+    this.maxRetries = options.maxRetries ?? 4;
+    this.minRequestIntervalMs = options.minRequestIntervalMs ?? 650;
+    this.rateLimitWaitMs = options.rateLimitWaitMs ?? 15_000;
+  }
+
+  endpoint(path: TwentyEndpointPath): string {
+    return `${this.baseUrl}${path}`;
+  }
+
+  /** Pace requests under Twenty's 100 req/min throttle. */
+  private async takeSlot(): Promise<void> {
+    if (this.minRequestIntervalMs <= 0) return;
+    const now = Date.now();
+    const slot = Math.max(this.nextSlotAt, now);
+    this.nextSlotAt = slot + this.minRequestIntervalMs;
+    if (slot > now) await sleep(slot - now);
+  }
+
+  /**
+   * Single request with NO blind mutation retries (plan KTD3) — with one
+   * carve-out: Twenty's rate-limit guard rejects before the resolver runs, so
+   * a LIMIT_REACHED rejection had no side effect and is retried here after a
+   * wait, for mutations and reads alike.
+   */
+  async requestOnce<T = Record<string, unknown>>(
+    path: TwentyEndpointPath,
+    query: string,
+    variables: Record<string, unknown> = {},
+  ): Promise<T> {
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await this.performRequest<T>(path, query, variables);
+      } catch (error) {
+        const rateLimited =
+          error instanceof TwentyGraphqlError && error.isRateLimited;
+        if (!rateLimited || attempt >= this.maxRetries) throw error;
+        // The 100-token window refills per minute; wait a meaningful slice.
+        await sleep(
+          this.rateLimitWaitMs +
+            Math.floor(Math.random() * (this.rateLimitWaitMs / 3 + 1)),
+        );
+        attempt += 1;
+      }
+    }
+  }
+
+  private async performRequest<T>(
+    path: TwentyEndpointPath,
+    query: string,
+    variables: Record<string, unknown>,
+  ): Promise<T> {
+    await this.takeSlot();
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.endpoint(path), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.authToken}`,
+        },
+        body: JSON.stringify({ query, variables }),
+      });
+    } catch (cause) {
+      // Socket-level failure (DNS, reset, timeout): no response was received.
+      // Reads retry these; mutation callers re-query by sourceId first (KTD3).
+      const error = new TwentyGraphqlError(
+        `Twenty GraphQL network error: ${cause instanceof Error ? (cause.cause instanceof Error ? cause.cause.message : cause.message) : String(cause)}`,
+      );
+      error.isNetworkError = true;
+      throw error;
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+      throw new TwentyGraphqlError(
+        `Twenty GraphQL HTTP ${response.status}: ${bodyText}`,
+        {
+          httpStatus: response.status,
+        },
+      );
+    }
+    let body: {
+      data?: T;
+      errors?: Array<{ message: string; extensions?: Record<string, unknown> }>;
+    };
+    try {
+      body = JSON.parse(bodyText);
+    } catch {
+      throw new TwentyGraphqlError(
+        `Twenty GraphQL returned non-JSON body: ${bodyText.slice(0, 300)}`,
+      );
+    }
+    if (body.errors?.length) {
+      throw new TwentyGraphqlError(
+        `Twenty GraphQL errors: ${JSON.stringify(body.errors)}`,
+        {
+          errors: body.errors,
+        },
+      );
+    }
+    if (body.data === undefined || body.data === null) {
+      throw new TwentyGraphqlError("Twenty GraphQL returned no data.");
+    }
+    return body.data;
+  }
+
+  /**
+   * Read request with exponential backoff on 429/5xx. Only use for queries —
+   * retrying a mutation blind can double-write (plan KTD3).
+   */
+  async requestWithRetry<T = Record<string, unknown>>(
+    path: TwentyEndpointPath,
+    query: string,
+    variables: Record<string, unknown> = {},
+  ): Promise<T> {
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await this.requestOnce<T>(path, query, variables);
+      } catch (error) {
+        const retryable =
+          error instanceof TwentyGraphqlError && error.isRetryable;
+        if (!retryable || attempt >= this.maxRetries) throw error;
+        const delay =
+          this.backoffMs * 2 ** attempt + Math.floor(Math.random() * 250);
+        await sleep(delay);
+        attempt += 1;
+      }
+    }
+  }
+}