thinkwork-cli 0.13.1 → 1.0.0

package/dist/plugins/twenty/scripts/lib/__tests__/members-ensure.test.ts

@@ -28,70 +28,56 @@ function dataClientWithMembers(
   } as unknown as TwentyClient;
 }
 
-describe("ensureMembers (dry run)", () => {
-  it("three reps, one already a member → one existing + two planned, map holds the existing", async () => {
+describe("ensureMembers (matches existing members; never creates)", () => {
+  it("maps reps onto members by email, case-insensitively", async () => {
     const dataClient = dataClientWithMembers([
       { id: "wm-1", userEmail: "Jane@TEI.com" },
     ]);
-    const result = await ensureMembers({
-      dataClient,
-      adminClient: null,
-      reps: [
-        rep(),
-        rep({ repId: "rep_2", email: "bob@tei.com" }),
-        rep({ repId: "rep_3", email: "amy@tei.com" }),
-      ],
-      repPassword: "test",
-      workspaceId: null,
-      dryRun: true,
-    });
+    const result = await ensureMembers({ dataClient, reps: [rep()] });
     expect(result.ownerMap.get("rep_1")).toBe("wm-1");
-    expect(
-      result.report.filter((row) => row.action === "planned"),
-    ).toHaveLength(2);
-    expect(result.hadFailures).toBe(false);
+    expect(result.report[0]).toMatchObject({ action: "existing" });
+    expect(result.missingMembers).toBe(0);
   });
 
-  it("reps without an email are unprovisionable and the run continues", async () => {
+  it("reports a rep with no Twenty member instead of failing the run", async () => {
+    // provision-twenty-members.ts creates members; this module only matches
+    // them. Records for an unmatched rep load ownerless and heal on a re-run.
     const dataClient = dataClientWithMembers([]);
+    const result = await ensureMembers({ dataClient, reps: [rep()] });
+    expect(result.ownerMap.size).toBe(0);
+    expect(result.report[0]).toMatchObject({ action: "missing-member" });
+    expect(result.missingMembers).toBe(1);
+    expect(result.hadFailures).toBe(false);
+  });
+
+  it("marks emailless reps unprovisionable and keeps going", async () => {
+    const dataClient = dataClientWithMembers([
+      { id: "wm-bob", userEmail: "bob@tei.com" },
+    ]);
     const result = await ensureMembers({
       dataClient,
-      adminClient: null,
       reps: [
         rep({ email: null }),
         rep({ repId: "rep_2", email: "bob@tei.com" }),
       ],
-      repPassword: "test",
-      workspaceId: null,
-      dryRun: true,
     });
     expect(result.report[0]).toMatchObject({
       repId: "rep_1",
       action: "unprovisionable",
     });
-    expect(result.report[1]).toMatchObject({
-      repId: "rep_2",
-      action: "planned",
-    });
+    expect(result.ownerMap.get("rep_2")).toBe("wm-bob");
   });
 
-  it("duplicate emails collapse to one login; both rep ids map to the same member", async () => {
-    // Observed live in LastMile: a "house" sales_rep row reusing a real rep's
-    // email. Email is the login identity, so the reps merge — reported, never
-    // silent.
+  it("collapses reps sharing an email onto one login, and says so", async () => {
     const dataClient = dataClientWithMembers([
       { id: "wm-jane", userEmail: "jane@tei.com" },
     ]);
     const result = await ensureMembers({
       dataClient,
-      adminClient: null,
       reps: [
         rep(),
         rep({ repId: "rep_2", firstName: "Employee", lastName: "Accounts" }),
       ],
-      repPassword: "test",
-      workspaceId: null,
-      dryRun: true,
     });
     expect(result.ownerMap.get("rep_1")).toBe("wm-jane");
     expect(result.ownerMap.get("rep_2")).toBe("wm-jane");
@@ -99,101 +85,14 @@ describe("ensureMembers (dry run)", () => {
       action: "merged-duplicate-email",
     });
   });
-});
 
-describe("ensureMembers (apply)", () => {
-  it("requires the admin client when new members must be provisioned", async () => {
+  it("leaves a merged rep unmapped when its primary has no member either", async () => {
     const dataClient = dataClientWithMembers([]);
-    await expect(
-      ensureMembers({
-        dataClient,
-        adminClient: null,
-        reps: [rep()],
-        repPassword: "test",
-        workspaceId: "ws-1",
-        dryRun: false,
-      }),
-    ).rejects.toThrow(/TWENTY_ADMIN_EMAIL/);
-  });
-
-  it("a signUpInWorkspace rejection is reported per-user and the run continues", async () => {
-    const membersAfterSignup = [{ id: "wm-bob", userEmail: "bob@tei.com" }];
-    let listCalls = 0;
-    const dataClient = {
-      requestWithRetry: vi.fn(async () => {
-        listCalls += 1;
-        return {
-          workspaceMembers: {
-            // First list: empty; lists after signup include bob only.
-            edges: (listCalls === 1 ? [] : membersAfterSignup).map(
-              (member) => ({
-                node: member,
-              }),
-            ),
-            pageInfo: { hasNextPage: false, endCursor: null },
-          },
-        };
-      }),
-      endpoint: (path: string) => `https://crm.example.com${path}`,
-    } as unknown as TwentyClient;
-
-    const adminClient = {
-      requestOnce: vi.fn(async () => ({
-        sendInvitations: { success: true, result: [] },
-      })),
-      requestWithRetry: vi.fn(async (_path: string, query: string) => {
-        if (query.includes("findWorkspaceInvitations")) {
-          return {
-            findWorkspaceInvitations: [
-              { id: "inv-jane", email: "jane@tei.com" },
-              { id: "inv-bob", email: "bob@tei.com" },
-            ],
-          };
-        }
-        return { getWorkspaceInvitationToken: "token-123" };
-      }),
-    } as unknown as TwentyClient;
-
-    // jane's signup fails (fetch mock), bob's succeeds.
-    const fetchMock = vi.fn(
-      async (_url: RequestInfo | URL, init?: RequestInit) => {
-        const body = JSON.parse(String(init?.body ?? "{}")) as {
-          variables?: { email?: string };
-        };
-        if (body.variables?.email === "jane@tei.com") {
-          return new Response(
-            JSON.stringify({ errors: [{ message: "invite token invalid" }] }),
-            {
-              status: 200,
-            },
-          );
-        }
-        return new Response(
-          JSON.stringify({ data: { signUpInWorkspace: {} } }),
-          { status: 200 },
-        );
-      },
-    );
-    vi.stubGlobal("fetch", fetchMock);
-    try {
-      const result = await ensureMembers({
-        dataClient,
-        adminClient,
-        reps: [rep(), rep({ repId: "rep_2", email: "bob@tei.com" })],
-        repPassword: "test",
-        workspaceId: "ws-1",
-        dryRun: false,
-      });
-      expect(result.hadFailures).toBe(true);
-      expect(result.report.find((row) => row.repId === "rep_1")).toMatchObject({
-        action: "failed",
-      });
-      expect(result.report.find((row) => row.repId === "rep_2")).toMatchObject({
-        action: "invited+signedUp",
-      });
-      expect(result.ownerMap.get("rep_2")).toBe("wm-bob");
-    } finally {
-      vi.unstubAllGlobals();
-    }
+    const result = await ensureMembers({
+      dataClient,
+      reps: [rep(), rep({ repId: "rep_2" })],
+    });
+    expect(result.ownerMap.size).toBe(0);
+    expect(result.missingMembers).toBe(1);
   });
 });

package/dist/plugins/twenty/scripts/lib/__tests__/provision-members-db.test.ts

@@ -41,3 +41,13 @@ describe("quoteIdent", () => {
     expect(() => quoteIdent("public")).toThrow(/Refusing/);
   });
 });
+
+describe("hashPassword salts per call", () => {
+  it("never reuses a salt, so rotation does not share hashes across reps", () => {
+    const a = hashPassword("SharedSecret1!", 4);
+    const b = hashPassword("SharedSecret1!", 4);
+    expect(a).not.toBe(b);
+    expect(bcrypt.compareSync("SharedSecret1!", a)).toBe(true);
+    expect(bcrypt.compareSync("SharedSecret1!", b)).toBe(true);
+  });
+});

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

@@ -61,9 +61,9 @@ function bareObjects() {
     opportunity: [stageField],
     note: [],
     attachment: [],
-    // The product-line object exists (ensureOpportunityProductObject ran) but
-    // has none of its fields yet.
+    // Custom objects exist (their ensure* ran) but have none of their fields.
     opportunityProduct: [],
+    organization: [],
   });
 }
 
@@ -115,6 +115,7 @@ function provisionedObjects() {
         options: null,
       },
     ],
+    organization: withAll("organization"),
   });
 }
 
@@ -122,15 +123,18 @@ describe("planSchemaEnsure", () => {
   it("plans every missing field and all stage options on an empty workspace", () => {
     const plan = planSchemaEnsure(bareObjects());
     expect(plan.createFields).toHaveLength(FIELD_SPECS.length);
+    // NEW already exists on the workspace, so it is merged, not duplicated.
     expect(plan.stageOptionsToAdd).toEqual(
-      MIGRATION_STAGE_OPTIONS.map((option) => option.value),
+      MIGRATION_STAGE_OPTIONS.filter((option) => option.value !== "NEW").map(
+        (option) => option.value,
+      ),
     );
     // Full-replace semantics (U1): the merged array keeps existing options first.
     expect(
       plan.mergedStageOptions?.slice(0, 2).map((option) => option.value),
     ).toEqual(["NEW", "CUSTOMER"]);
     expect(plan.mergedStageOptions).toHaveLength(
-      EXISTING_STAGE_OPTIONS.length + MIGRATION_STAGE_OPTIONS.length,
+      EXISTING_STAGE_OPTIONS.length + MIGRATION_STAGE_OPTIONS.length - 1,
     );
   });
 
@@ -143,7 +147,7 @@ describe("planSchemaEnsure", () => {
 
   it("creates only the gap on partial presence", () => {
     const objects = bareObjects();
-    objects.get("opportunity")!.fields.set("product", {
+    objects.get("opportunityProduct")!.fields.set("product", {
       id: "f-product",
       name: "product",
       type: "TEXT",
@@ -153,8 +157,8 @@ describe("planSchemaEnsure", () => {
     const names = plan.createFields.map(
       (field) => `${field.object}.${field.name}`,
     );
-    expect(names).not.toContain("opportunity.product");
-    expect(names).toContain("opportunity.quantity");
+    expect(names).not.toContain("opportunityProduct.product");
+    expect(names).toContain("opportunityProduct.quantity");
   });
 
   it("aborts when the stage field is missing", () => {
@@ -165,6 +169,7 @@ describe("planSchemaEnsure", () => {
       note: [],
       attachment: [],
       opportunityProduct: [],
+      organization: [],
     });
     expect(() => planSchemaEnsure(objects)).toThrow(/stage field/);
   });
@@ -202,7 +207,7 @@ describe("applySchemaEnsure", () => {
     ).toContain("CUSTOMER");
     expect(
       lastCall[2].input.update.options.map((option) => option.value),
-    ).toContain("LEAD");
+    ).toContain("PROSPECT");
   });
 
   it("refuses to create a field against a pending object id", async () => {

package/dist/plugins/twenty/scripts/lib/lastmile-reader.ts

@@ -43,6 +43,17 @@ export interface LastmileContact {
   title: string | null;
 }
 
+export interface LastmileDispatchCustomer {
+  id: string;
+  name: string | null;
+  /** dispatch customer.external_id — the P21 account key ("P21:12345"). */
+  p21Code: string | null;
+  ownerRepId: string | null;
+  /** An `account` row already carries this exact (case-folded) name — the
+   * account-sourced company covers it, so the dispatch source skips it. */
+  hasAccountNameMatch: boolean;
+}
+
 export interface LastmileLead {
   id: string;
   status: string | null;
@@ -91,13 +102,76 @@ export interface LastmileOpportunityItem {
   amount: string | null;
 }
 
+/**
+ * The `task` table is LastMile's live CRM. Everything a rep sees hangs off it:
+ * `status_id` (the real pipeline status — the `opportunity.stage` column is
+ * stale and disagrees for 889 of 950 rows), `assignee_id` (the owning rep),
+ * `organization_id` (the branch, e.g. "GWO 300"), and `entity_data` (name,
+ * description, account, and the product `items` array). Task rows only exist
+ * from 2025-07 onward; older opportunity/lead rows are legacy and out of scope.
+ */
+export interface LastmileCrmTask {
+  taskId: string;
+  entityType: "lead" | "opportunity";
+  /** opportunity/lead row id — the stable identity for the Twenty record. */
+  entityId: string;
+  title: string | null;
+  description: string | null;
+  /** Present on opportunity tasks only; leads pre-date an account. */
+  accountId: string | null;
+  /** Company name typed on a lead before an account exists. */
+  leadCompanyName: string | null;
+  statusName: string | null;
+  organizationId: string | null;
+  /** Owning rep, resolved from the task's assignee user. */
+  assigneeRepId: string | null;
+  dueDate: Date | null;
+  createdAt: Date | null;
+  /** Product lines: [{ brand, quantity, amount }, ...] */
+  items: Array<{
+    brand?: string | null;
+    quantity?: string | number | null;
+    amount?: string | number | null;
+  }> | null;
+}
+
+export interface LastmileOrganization {
+  id: string;
+  name: string | null;
+  /** Short code shown in the LastMile UI, e.g. "GWO 300". */
+  abbv: string | null;
+  archived: boolean;
+}
+
 export interface LastmileCrmComment {
   id: string;
   entityType: "lead" | "opportunity";
   entityId: string;
   content: string | null;
   isDeleted: boolean;
+  /** Authored-at time. Carried onto the Twenty note so the activity feed
+   * reflects when the rep actually wrote it, not when the import ran. */
+  createdAt: Date | null;
+  authorName: string | null;
+}
+
+/**
+ * A single status-change event from LastMile's `task_activity` log — the row
+ * behind "Dean Kittel changed status to 10-Prospect" in the task activity feed.
+ * The pipeline transition is reconstructed onto the Twenty opportunity as a
+ * dated Note so the activity timeline reads in true order. `activity_data`
+ * carries human-readable stage names (`new_status_name` in every prod row; the
+ * camelCase `newStatusName` variant is coalesced defensively). `created_at` is
+ * the real transition time; `user_id` resolves to the rep who moved it.
+ */
+export interface LastmileTaskStatusChange {
+  id: string;
+  entityType: "lead" | "opportunity";
+  entityId: string;
+  oldStatusName: string | null;
+  newStatusName: string | null;
   createdAt: Date | null;
+  authorName: string | null;
 }
 
 export interface LastmileCrmAttachment {
@@ -120,19 +194,53 @@ export interface LastmileCustomerNote {
   dateCreated: Date | null;
 }
 
+/** TEI's operating company in the dispatch database (the others are demo
+ * shells) — dispatch-side reads scope to it; the CRM tables are single-tenant
+ * and stay unscoped. */
+const TEI_DISPATCH_COMPANY_ID = "co_y15610tsjbkqz5cqoic8gjla";
+
 export interface LastmileReader {
   readReps(): Promise<LastmileRep[]>;
   readAccounts(): Promise<LastmileAccount[]>;
+  /** Dispatch customers with an order in the last `days` days (the ThinkWork
+   * twin's seed cohort rule) — the "real customers" band for the CRM. With
+   * `includeOpenInvoices`, customers holding an open invoice (nonzero
+   * amount_remaining, any age) join the cohort regardless of order recency —
+   * the twin carries ALL open invoices, so their customers must exist in the
+   * CRM too. */
+  readOrderCohortCustomers(
+    days: number,
+    includeOpenInvoices?: boolean,
+  ): Promise<LastmileDispatchCustomer[]>;
   readContacts(): Promise<LastmileContact[]>;
   readLeads(): Promise<LastmileLead[]>;
   readOpportunities(): Promise<LastmileOpportunity[]>;
+  readCrmTasks(): Promise<LastmileCrmTask[]>;
+  readOrganizations(): Promise<LastmileOrganization[]>;
   readOpportunityItems(): Promise<LastmileOpportunityItem[]>;
   readCrmComments(): Promise<LastmileCrmComment[]>;
+  readTaskStatusChanges(): Promise<LastmileTaskStatusChange[]>;
   readCrmAttachments(): Promise<LastmileCrmAttachment[]>;
   readCustomerNotes(): Promise<LastmileCustomerNote[]>;
   close(): Promise<void>;
 }
 
+/**
+ * The accounts TEI actually sells to: those referenced by a CRM task (lead or
+ * opportunity). Companies and contacts are both scoped to this set — LastMile
+ * carries 3,403 accounts and 29,966 contacts, but only 805 accounts have an
+ * opportunity, and 443 contacts sit on them. Everything else is old data that
+ * stays in LastMile (Eric, 2026-07-10).
+ */
+const OPPORTUNITY_ACCOUNTS_CTE = `
+  opportunity_accounts as (
+    select distinct nullif(trim(t.entity_data ->> 'account_id'), '') as account_id
+    from task t
+    where t.entity_type in ('lead', 'opportunity')
+      and nullif(trim(t.entity_data ->> 'account_id'), '') is not null
+  )
+`;
+
 export function createLastmileReader(databaseUrl: string): LastmileReader {
   const pool = new pg.Pool({
     connectionString: databaseUrl,
@@ -161,12 +269,57 @@ export function createLastmileReader(databaseUrl: string): LastmileReader {
       `),
     readAccounts: () =>
       rows<LastmileAccount>(`
+        with ${OPPORTUNITY_ACCOUNTS_CTE}
         select id, nullif(trim(name), '') as "name", nullif(owner, '') as "ownerRepId"
         from account
+        where id in (select account_id from opportunity_accounts)
         order by id
       `),
+    readOrderCohortCustomers: (days: number, includeOpenInvoices?: boolean) => {
+      if (!Number.isInteger(days) || days < 1 || days > 365) {
+        throw new Error(`cohort days must be an integer 1..365, got ${days}`);
+      }
+      const openInvoiceUnion = includeOpenInvoices
+        ? `
+          union
+          select distinct i.customer_id as id
+          from invoice i
+          where i.company_id = '${TEI_DISPATCH_COMPANY_ID}'
+            and i.amount_remaining is not null
+            and i.amount_remaining <> 0
+            and i.customer_id is not null`
+        : "";
+      return rows<LastmileDispatchCustomer>(`
+        with cohort as (
+          select distinct o.customer_id as id
+          from order_header o
+          where o.company_id = '${TEI_DISPATCH_COMPANY_ID}'
+            and o.archived is not true
+            and o.order_date > now() - interval '${days} days'
+            and o.customer_id is not null${openInvoiceUnion}
+        )
+        select c.id,
+               nullif(trim(c.name), '') as "name",
+               nullif(trim(c.external_id), '') as "p21Code",
+               (
+                 select s.sales_rep_id from ship_to s
+                 where s.customer_id = c.id and s.sales_rep_id is not null
+                 group by s.sales_rep_id order by count(*) desc, s.sales_rep_id
+                 limit 1
+               ) as "ownerRepId",
+               exists (
+                 select 1 from account a
+                 where lower(trim(a.name)) = lower(trim(c.name))
+               ) as "hasAccountNameMatch"
+        from customer c
+        join cohort on cohort.id = c.id
+        where c.archived is not true
+        order by c.id
+      `);
+    },
     readContacts: () =>
       rows<LastmileContact>(`
+        with ${OPPORTUNITY_ACCOUNTS_CTE}
         select id,
                nullif(account_id, '')      as "accountId",
                nullif(trim(first_name), '') as "firstName",
@@ -176,6 +329,7 @@ export function createLastmileReader(databaseUrl: string): LastmileReader {
                nullif(trim(phone_cellular), '') as "phoneCellular",
                nullif(trim(title), '')     as "title"
         from contact
+        where account_id in (select account_id from opportunity_accounts)
         order by id
       `),
     readLeads: () =>
@@ -213,6 +367,44 @@ export function createLastmileReader(databaseUrl: string): LastmileReader {
         from opportunity
         order by id
       `),
+    readCrmTasks: () =>
+      rows<LastmileCrmTask>(`
+        select t.id                              as "taskId",
+               t.entity_type                     as "entityType",
+               t.entity_id                       as "entityId",
+               coalesce(
+                 nullif(trim(t.entity_data ->> 'opp_name'), ''),
+                 nullif(trim(t.title), '')
+               )                                 as "title",
+               nullif(trim(t.entity_data ->> 'description'), '') as "description",
+               nullif(trim(t.entity_data ->> 'account_id'), '')  as "accountId",
+               nullif(trim(t.entity_data ->> 'company'), '')     as "leadCompanyName",
+               nullif(trim(s.name), '')          as "statusName",
+               nullif(t.organization_id, '')     as "organizationId",
+               nullif(u.sales_rep_id, '')        as "assigneeRepId",
+               t.due_date                        as "dueDate",
+               t.created_at                      as "createdAt",
+               case
+                 when jsonb_typeof(t.entity_data -> 'items') = 'array'
+                 then t.entity_data -> 'items'
+                 else null
+               end                               as "items"
+        from task t
+        left join status s on s.id = t.status_id
+        left join users u  on u.id = t.assignee_id
+        where t.entity_type in ('lead', 'opportunity')
+          and t.entity_id is not null
+        order by t.entity_type, t.entity_id
+      `),
+    readOrganizations: () =>
+      rows<LastmileOrganization>(`
+        select id,
+               nullif(trim(name), '') as "name",
+               nullif(trim(abbv), '') as "abbv",
+               coalesce(archived, false) as "archived"
+        from organization
+        order by id
+      `),
     readOpportunityItems: () =>
       rows<LastmileOpportunityItem>(`
         select t.entity_id                       as "opportunityId",
@@ -236,13 +428,38 @@ export function createLastmileReader(databaseUrl: string): LastmileReader {
                t.entity_id   as "entityId",
                nullif(trim(tc.content), '') as "content",
                coalesce(tc.is_deleted, false) as "isDeleted",
-               tc.created_at as "createdAt"
+               tc.created_at as "createdAt",
+               nullif(trim(concat_ws(' ', u.first_name, u.last_name)), '') as "authorName"
         from task_comment tc
         join task t on t.id = tc.task_id
+        left join users u on u.id = tc.user_id
         where t.entity_type in ('lead', 'opportunity')
           and t.entity_id is not null
         order by tc.id
       `),
+    readTaskStatusChanges: () =>
+      rows<LastmileTaskStatusChange>(`
+        select ta.id,
+               t.entity_type as "entityType",
+               t.entity_id   as "entityId",
+               coalesce(
+                 nullif(trim(ta.activity_data ->> 'old_status_name'), ''),
+                 nullif(trim(ta.activity_data ->> 'oldStatusName'), '')
+               ) as "oldStatusName",
+               coalesce(
+                 nullif(trim(ta.activity_data ->> 'new_status_name'), ''),
+                 nullif(trim(ta.activity_data ->> 'newStatusName'), '')
+               ) as "newStatusName",
+               ta.created_at as "createdAt",
+               nullif(trim(concat_ws(' ', u.first_name, u.last_name)), '') as "authorName"
+        from task_activity ta
+        join task t on t.id = ta.task_id
+        left join users u on u.id = ta.user_id
+        where t.entity_type in ('lead', 'opportunity')
+          and t.entity_id is not null
+          and ta.activity_type in ('status_changed', 'status_change')
+        order by ta.id
+      `),
     readCrmAttachments: () =>
       rows<LastmileCrmAttachment>(`
         select ta.id,
@@ -260,10 +477,13 @@ export function createLastmileReader(databaseUrl: string): LastmileReader {
       `),
     readCustomerNotes: () =>
       rows<LastmileCustomerNote>(`
-        with account_names as (
+        with ${OPPORTUNITY_ACCOUNTS_CTE},
+        account_names as (
+          -- Only migrated accounts can host a note.
           select lower(trim(name)) as norm_name, min(id) as account_id, count(*) as n
           from account
           where nullif(trim(name), '') is not null
+            and id in (select account_id from opportunity_accounts)
           group by lower(trim(name))
         )
         select n.id,

package/dist/plugins/twenty/scripts/lib/load-attachments.ts

@@ -18,6 +18,27 @@ import { fetchExistingBySourceIds, type EntityCounters } from "./load-records";
 import { sourceId as makeSourceId } from "./mappers";
 import { TwentyClient, TwentyGraphqlError } from "./twenty-client";
 
+/**
+ * TEI's Twenty exposes no file-upload mutation to a workspace API key
+ * (`uploadFile` and the `Upload` scalar are absent; `/rest/files` is object
+ * CRUD). Same root cause as the missing auth schema. Four LastMile attachments
+ * hang off CRM records and one of those binaries is already gone from S3, so
+ * this is reported as a capability gap rather than a per-record failure —
+ * otherwise every future delta run would exit non-zero on the same files.
+ */
+export function isUploadUnsupported(error: unknown): boolean {
+  const message =
+    error instanceof TwentyGraphqlError
+      ? error.errors.map((entry) => entry.message).join(" ")
+      : error instanceof Error
+        ? error.message
+        : "";
+  return (
+    /Unknown type "Upload"/i.test(message) ||
+    /Cannot query field "uploadFile"/i.test(message)
+  );
+}
+
 const ATTACHMENT_ENTITY = {
   singular: "attachment",
   plural: "attachments",
@@ -119,6 +140,14 @@ export async function loadCrmAttachments(options: {
       );
       counters.created += 1;
     } catch (error) {
+      if (isUploadUnsupported(error)) {
+        counters.skipped += 1;
+        counters.gaps.push(
+          `attachment ${attachmentSourceId} (${attachment.filename ?? "?"}): ` +
+            "Twenty exposes no file-upload API to this credential — upload by hand",
+        );
+        continue;
+      }
       counters.failed += 1;
       counters.gaps.push(
         `attachment ${attachmentSourceId} failed: ${