[Gusto] [Bug] Update GustoSyncResult to match IS payload shape from JOB_DONE event

[yuwenmemon]

Bug

After a Gusto sync, the App's connectionSyncProgress.result stays undefined because the IS doesn't currently emit the result on the JOB_DONE Pusher event for NewDot syncs — and the App's GustoSyncResult type doesn't match what's about to start being emitted.

The IS-side fix is in Expensify/Integration-Server#8948. Once merged, JOB_DONE Onyx events for Gusto syncs will carry a new result field:

{
  "timestamp": "...",
  "connectionName": "gusto",
  "stageInProgress": "jobDone",
  "result": {
    "addedEmployeesCount": 3,
    "removedEmployeesCount": 1,
    "skippedEmployees": [
      {"name": "Anu M", "id": "uuid-1", "reason": "Employee doesn't have an email address."}
    ]
  }
}

The App-side GustoSyncResult type currently models {added, removed, skipped} as arrays of user objects with emails. This needs to switch to counts for added/removed (just like Classic does) plus the detailed skipped list.

Proposed change

Update src/libs/API/GustoSyncResult.ts to:

type GustoSyncResult = {
    addedEmployeesCount?: number;
    removedEmployeesCount?: number;
    skippedEmployees?: Array<{name: string; id: string; reason: string}>;
};

…and update any rendering code that consumes the old {added, removed, skipped} shape to use counts for added/removed and the new skippedEmployees array shape (only the skipped list keeps per-employee details — same as Classic).

Steps to reproduce (after IS merge)

1. On a Control workspace, connect Gusto via NewDot and trigger a sync (e.g. switch the approval mode).
2. After the sync completes, the post-sync summary should show the added count, removed count, and a list of skipped employees with their reason.
3. With the current GustoSyncResult type, the App ignores the payload because field names don't match what IS sends.

Parent

For https://github.com/Expensify/Expensify/issues/591910

Issue Owner

Current Issue Owner: @shubham1206agra

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022054682980734946047
• Upwork Job ID: 2054682980734946047
• Last Price Increase: 2026-05-13

[MelvinBot]

Proposal

What is the root cause of that problem?

The GustoSyncResult type expects {added, removed, skipped} as arrays of user objects (with email/displayName), but the IS-side fix (Expensify/Integration-Server#8948) will emit {addedEmployeesCount, removedEmployeesCount, skippedEmployees} — counts for added/removed plus a detailed array only for skipped. Because the field names don't match, the App silently ignores the payload.

The type is consumed only at PolicyConnectionSyncProgress.result. No component currently renders the result field — WorkspaceHRPage and WorkspaceMembersPage both subscribe to sync progress via Onyx but only read stageInProgress and connectionName for spinner display. So this is purely a type alignment fix today; rendering will be added separately.

What changes do you think we should make in order to solve the problem?

1. Update src/libs/API/GustoSyncResult.ts — replace the current type with:

type GustoSyncSkippedEmployee = {
    name: string;
    id: string;
    reason: string;
};

type GustoSyncResult = {
    addedEmployeesCount?: number;
    removedEmployeesCount?: number;
    skippedEmployees?: GustoSyncSkippedEmployee[];
};

export type {GustoSyncResult};

2. Remove the GustoSyncResultUser export — it's only referenced by GustoSyncResult itself (no external consumers), so it can be deleted along with GustoSyncSkippedResultUser. The only import site is Policy.ts:3 which imports GustoSyncResult (not the user types).

That's the complete change — no rendering code needs updating since no component currently reads result.

What alternative solutions did you explore? (Optional)

A union type supporting both old and new shapes was considered but rejected — the old shape was never emitted in production for NewDot syncs (the IS didn't include result in JOB_DONE events until the IS PR), so there's no backwards-compatibility concern. A clean type replacement is simpler and correct.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Current assignee @ShridharGoel is eligible for the External assigner, not assigning anyone new.

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022054682980734946047

[wildan-m]

Proposal

Please re-state the problem that we are trying to solve in this issue.

After a Gusto sync completes on a Control workspace via NewDot, the post-sync summary cannot be rendered because connectionSyncProgress.result does not match the payload IS is about to start emitting on the JOB_DONE Pusher event. Once Integration-Server PR #8948 merges, JOB_DONE for Gusto will carry {addedEmployeesCount, removedEmployeesCount, skippedEmployees: [{name, id, reason}]}, but the App-side GustoSyncResult type still describes the prior {added, removed, skipped} shape (arrays of user objects with email/displayName). The field names don't overlap, so even when IS starts sending data, every field on the App side will be undefined.

What is the root cause of that problem?

The contract between the IS JOB_DONE Pusher event for Gusto and the App's typed Onyx slot is defined exclusively by the GustoSyncResult type at:

App/src/libs/API/GustoSyncResult.ts

Lines 1 to 16 in df35ada

	type GustoSyncResultUser = {
	email: string;
	displayName?: string;
	};
	type GustoSyncSkippedResultUser = GustoSyncResultUser & {
	reason: string;
	};
	type GustoSyncResult = {
	added?: GustoSyncResultUser[];
	removed?: GustoSyncResultUser[];
	skipped?: GustoSyncSkippedResultUser[];
	};
	export type {GustoSyncResult, GustoSyncResultUser};

That type was added pre-emptively with the assumption that IS would emit the NewDot-style {added, removed, skipped} shape used in earlier connection-sync designs. The IS implementation chose instead to align with Expensify Classic, which sends counts for added/removed (the full user objects aren't needed for the summary the workspace HR page renders) plus a detailed skippedEmployees list with {name, id, reason} so the user can see why certain employees were skipped. The shape was never reconciled, so the App's type now describes a payload that will never arrive.

The reference to GustoSyncResult from the Onyx Policy type lives here:

App/src/types/onyx/Policy.ts

Lines 2186 to 2188 in df35ada

	/** Optional result payload shown after a completed sync */
	result?: GustoSyncResult;
	};

A repo-wide search confirms there is no current rendering code that reads connectionSyncProgress.result?.added, …removed, or …skipped — the type was wired up before any consumer started displaying the summary. So this is a pure contract update: change the type, and the future rendering work (the post-sync summary on WorkspaceHRPage / WorkspaceMembersPage) will be written against the correct shape from the start. The now-unused exported helper GustoSyncResultUser is dead code with zero importers outside GustoSyncResult.ts itself.

What changes do you think we should make in order to solve the problem?

Update src/libs/API/GustoSyncResult.ts to model the new IS payload exactly, mirroring the JSON example in the issue body:

• Replace the added?: GustoSyncResultUser[] field with addedEmployeesCount?: number.
• Replace the removed?: GustoSyncResultUser[] field with removedEmployeesCount?: number.
• Replace the skipped?: GustoSyncSkippedResultUser[] field with skippedEmployees?: Array<{name: string; id: string; reason: string}>.
• All three fields stay optional (?) because JOB_DONE events for other stages don't include them, and the IS-side rollout for Gusto specifically is the only emitter — defensive consumers should still cope with the field being absent during in-progress stages.
• Delete the helper types GustoSyncResultUser and GustoSyncSkippedResultUser. They were only consumed by the old field shape we are replacing, and a repo-wide search shows no external import of GustoSyncResultUser despite it being exported — so removing them is dead-code cleanup, not a breaking change. The export type line shrinks to just export type {GustoSyncResult}.

No consumer code needs to change in this PR. A repo-wide search for reads of connectionSyncProgress.result?.added, …removed, or …skipped returns zero matches, and the Onyx slot reference in src/types/onyx/Policy.ts only mentions the type by name, not its fields. The future rendering work for the post-sync summary will be written against the updated type, against the same shape the IS will emit. The TypeScript compiler will catch any consumer that had been reading the old field names had one slipped in between commits — it cannot regress silently.

This change should land after (or in coordination with) Integration-Server PR #8948 so that the App's type and the actual Pusher payload move together; landing the App side first means the type briefly describes a payload IS is not yet sending, but since no consumer reads it today, that gap is harmless.

Compare branch: https://github.com/Expensify/App/compare/main...wildan-m:App:wildan/90573-gusto-sync-result-type?expand=1

What alternative solutions did you explore? (Optional)

Keeping GustoSyncResultUser exported in case a future caller needs the per-employee detail — rejected, because the new skippedEmployees entries use a different shape ({name, id, reason} instead of {email, displayName, reason}), and the IS payload deliberately drops email/displayName from added/removed in favour of counts. A future consumer that needs richer per-employee info on additions/removals would have to be paired with another IS-side change — speculating about that shape now would just produce a second type churn later.

[wildan-m]

Proposal updated — added compare branch with implementation.

[oqildev]

Proposal

What is the root cause of that problem?

The contract for the JOB_DONE Pusher payload for Gusto syncs lives only in the GustoSyncResult type, and that type was authored before the IS side decided on its final shape. After tracing the code, I see:

• The current type at

  App/src/libs/API/GustoSyncResult.ts

  Lines 1 to 16 in df35ada

  	type GustoSyncResultUser = {
  	email: string;
  	displayName?: string;
  	};
  	type GustoSyncSkippedResultUser = GustoSyncResultUser & {
  	reason: string;
  	};
  	type GustoSyncResult = {
  	added?: GustoSyncResultUser[];
  	removed?: GustoSyncResultUser[];
  	skipped?: GustoSyncSkippedResultUser[];
  	};
  	export type {GustoSyncResult, GustoSyncResultUser};

  models {added, removed, skipped} as arrays of {email, displayName, reason?} user objects.
• The Onyx slot that holds it is PolicyConnectionSyncProgress.result at

  App/src/types/onyx/Policy.ts

  Lines 2150 to 2164 in df35ada

  	/** Email address of the technical contact */
  	technicalContact?: string;
  	/** Indicate whether the Workspace plan can be downgraded */
  	canDowngrade?: boolean;
  	/** Policy level user created in-app export templates */
  	exportLayouts?: Record<string, OnyxTypes.ExportTemplate>;
  	/** Whether Attendee Tracking is enabled */
  	isAttendeeTrackingEnabled?: boolean;
  	/** Whether the policy requires purchases to be on a company card */
  	requireCompanyCardsEnabled?: boolean;

  .
• The IS-side change (Integration-Server#8948) is about to start emitting {addedEmployeesCount: number, removedEmployeesCount: number, skippedEmployees: [{name, id, reason}]} — counts for added/removed, full detail only for skipped (mirrors Classic).

The field names do not overlap at all (added vs addedEmployeesCount, skipped vs skippedEmployees, plus email/displayName vs name/id), so every property on every consumer will resolve to undefined the moment IS rolls out.

I also checked the "boring places" before settling on this as a pure type fix:

• Repo-wide grep for connectionSyncProgress.result, result?.added, result?.removed, result?.skipped — zero matches across all consumers of ${ONYXKEYS.COLLECTION.POLICY_CONNECTION_SYNC_PROGRESS} (PolicyAccountingPage, WorkspaceTaxesPage, WorkspaceCategoriesPage, QuickBooksDesktopSetupFlowSyncPage, ClaimOfferPage). Every reader touches only stageInProgress / connectionName.
• Repo-wide grep for GustoSyncResultUser (the exported helper) — zero importers outside the file that defines it. It is dead code.
• No WorkspaceHRPage / Gusto post-sync summary component exists yet (no file matches), so there is nothing rendering the old field shape that would silently break.

So the root cause is narrow: the App-side type was speculatively written against a payload shape IS never adopted, and the rendering side hasn't been built yet. Today's bug is a future one — once IS#8948 ships, any consumer added against the current type will read undefined for every field.

What changes do you think we should make in order to solve the problem?

The change belongs at the type-definition layer — src/libs/API/GustoSyncResult.ts — and nowhere else, because that file is the single source of truth for the Pusher payload contract and it has no transitive renderers today.

Concretely, in plain English:

1. In

   App/src/libs/API/GustoSyncResult.ts

   Lines 1 to 16 in df35ada

   	type GustoSyncResultUser = {
   	email: string;
   	displayName?: string;
   	};
   	type GustoSyncSkippedResultUser = GustoSyncResultUser & {
   	reason: string;
   	};
   	type GustoSyncResult = {
   	added?: GustoSyncResultUser[];
   	removed?: GustoSyncResultUser[];
   	skipped?: GustoSyncSkippedResultUser[];
   	};
   	export type {GustoSyncResult, GustoSyncResultUser};

   :
   • Replace added?: GustoSyncResultUser[] with an optional addedEmployeesCount?: number.
   • Replace removed?: GustoSyncResultUser[] with an optional removedEmployeesCount?: number.
   • Replace skipped?: GustoSyncSkippedResultUser[] with an optional skippedEmployees?: Array<{name: string; id: string; reason: string}> (a small named helper type is fine).
   • Keep all three fields optional because JOB_DONE for non-Gusto connections, and earlier in-flight stages for Gusto itself, won't include them — defensive consumers must cope.
   • Delete the now-unused GustoSyncResultUser and GustoSyncSkippedResultUser helpers and drop them from the export list, leaving only export type {GustoSyncResult}.

2. No other file should change.

   App/src/types/onyx/Policy.ts

   Lines 1 to 5 in df35ada

   	import type {CONST as COMMON_CONST} from 'expensify-common';
   	import type {ValueOf} from 'type-fest';
   	import type {GustoSyncResult} from '@libs/API/GustoSyncResult';
   	import type CONST from '@src/CONST';
   	import type {Country} from '@src/CONST';

   only imports GustoSyncResult by name, and

   App/src/types/onyx/Policy.ts

   Lines 2150 to 2164 in df35ada

   	/** Email address of the technical contact */
   	technicalContact?: string;
   	/** Indicate whether the Workspace plan can be downgraded */
   	canDowngrade?: boolean;
   	/** Policy level user created in-app export templates */
   	exportLayouts?: Record<string, OnyxTypes.ExportTemplate>;
   	/** Whether Attendee Tracking is enabled */
   	isAttendeeTrackingEnabled?: boolean;
   	/** Whether the policy requires purchases to be on a company card */
   	requireCompanyCardsEnabled?: boolean;

   only references it as a type — there is nothing to update there.

Edge cases I considered while picking this layer:

• Offline / optimistic rollback: not relevant — connectionSyncProgress is server-pushed via Pusher, not optimistically written.
• Rollout ordering: this PR should land after (or simultaneously with) Integration-Server#8948 so the type and the wire payload move together. Landing the App side first is harmless because no consumer reads result today, but landing it after is cleaner.
• Future renderer: when the post-sync summary UI gets built (a follow-up issue), it will consume addedEmployeesCount, removedEmployeesCount, and skippedEmployees directly — the same shape IS emits, so no second translation layer is needed.

What alternative solutions did you explore? (Optional)

• Union of old + new shape for backwards compatibility — Rejected: the old shape was never produced for NewDot in production. The IS only starts emitting result for Gusto with Use latest expensify-common #8948, so there is no historical payload sitting in any user's Onyx store that we would orphan by replacing the type.
• Keep GustoSyncResultUser exported in case a future feature needs per-employee detail on added/removed — Rejected: the IS deliberately dropped per-employee detail from added/removed in favor of counts (matching Classic). A future enhancement that wants richer detail would require a paired IS change and would almost certainly use name/id rather than email/displayName, so preserving the old helper would just produce a second migration later.
• Adding a renderer in the same PR — Deferred: rendering the summary on WorkspaceMembersPage / a Gusto post-sync card is a separate feature (and a separate issue at the parent link). This PR is purely a contract fix.

[trasnake87]

Proposal

Root cause

After Integration-Server PR #8948 lands, the JOB_DONE Pusher event for a Gusto sync will carry a result payload of {addedEmployeesCount, removedEmployeesCount, skippedEmployees} — counts for added/removed plus a detail array only for skipped, mirroring the Classic shape. That payload reaches Onyx via the policyConnectionSyncProgress_<policyID> collection key, which is typed by PolicyConnectionSyncProgress.result?: GustoSyncResult at src/types/onyx/Policy.ts:2161-2173:

// src/types/onyx/Policy.ts:2160-2173
/** Policy connection sync progress state */
type PolicyConnectionSyncProgress = {
    /** Current sync stage */
    stageInProgress: PolicyConnectionSyncStage;

    /** Name of the connected service */
    connectionName: ConnectionName;

    /** Timestamp of the connection */
    timestamp: string;

    /** Optional result payload shown after a completed sync */
    result?: GustoSyncResult;
};

The current shape behind that alias, at src/libs/API/GustoSyncResult.ts:1-16, is the legacy one and every field name differs from what IS will emit:

// src/libs/API/GustoSyncResult.ts (current)
type GustoSyncResultUser = {
    email: string;
    displayName?: string;
};

type GustoSyncSkippedResultUser = GustoSyncResultUser & {
    reason: string;
};

type GustoSyncResult = {
    added?: GustoSyncResultUser[];
    removed?: GustoSyncResultUser[];
    skipped?: GustoSyncSkippedResultUser[];
};

export type {GustoSyncResult, GustoSyncResultUser};

Because field names don't overlap (added vs addedEmployeesCount, removed vs removedEmployeesCount, skipped vs skippedEmployees, and the per-skipped row switches from {email, displayName, reason} to {name, id, reason}), TypeScript will keep accepting the old key names while runtime reads return undefined. The post-sync summary cannot be wired up until the type is re-aligned.

A repo-wide audit confirms no rendering code exists yet, so this change is purely type alignment with no migration tail:

• GustoSyncResult is imported in exactly one place — src/types/onyx/Policy.ts:3 — and consumed in exactly one position (line 2172).
• GustoSyncResultUser and GustoSyncSkippedResultUser are never imported outside GustoSyncResult.ts itself; they are dead exports.
• grep across src/ for result?.added, result?.removed, result?.skipped, addedEmployeesCount, removedEmployeesCount, and skippedEmployees returns zero hits. Every screen that subscribes to POLICY_CONNECTION_SYNC_PROGRESS — WorkspaceCategoriesPage, WorkspaceTagsPage, WorkspaceTaxesPage, WorkspaceReportsPage, WorkspaceCompanyCardDetailsPage, WorkspaceInitialPage, PolicyAccountingPage, ClaimOfferPage, TimeSensitiveSection, WorkspacesListPage, plus the usePolicyIndicatorChecks hook — reads only stageInProgress / connectionName / timestamp for spinner gating.

Rendering of the summary is downstream work and explicitly out of scope here, since no consumer currently exists to update.

Proposed fix

Replace src/libs/API/GustoSyncResult.ts in full. Drop the orphaned GustoSyncResultUser / GustoSyncSkippedResultUser exports, hoist the per-employee shape into a named type so the follow-up rendering PR can reference it directly, and add per-field JSDoc to match the convention used throughout src/types/onyx/Policy.ts:2162-2172:

// src/libs/API/GustoSyncResult.ts (new)
/** Per-employee detail for someone skipped during a Gusto sync */
type GustoSyncSkippedEmployee = {
    /** Display name of the skipped employee */
    name: string;

    /** Stable identifier (UUID) of the skipped employee */
    id: string;

    /** Human-readable reason the employee was skipped (e.g. "Employee doesn't have an email address.") */
    reason: string;
};

/** Result payload emitted on the JOB_DONE event for a Gusto sync */
type GustoSyncResult = {
    /** Number of employees added during the sync */
    addedEmployeesCount?: number;

    /** Number of employees removed during the sync */
    removedEmployeesCount?: number;

    /** Employees the sync chose to skip, along with the reason */
    skippedEmployees?: GustoSyncSkippedEmployee[];
};

export type {GustoSyncResult, GustoSyncSkippedEmployee};

No other file needs an edit. src/types/onyx/Policy.ts:3 already imports GustoSyncResult from @libs/API/GustoSyncResult, and PolicyConnectionSyncProgress.result?: GustoSyncResult keeps the same alias — only the shape behind it changes. Because GustoSyncResultUser / GustoSyncSkippedResultUser had no external importers, deleting them does not propagate further.

Why this approach

Keeping the file location at src/libs/API/GustoSyncResult.ts matches the path the issue explicitly calls out and avoids touching the single import in Policy.ts. Naming the per-employee row GustoSyncSkippedEmployee (rather than inlining Array<{name: string; id: string; reason: string}>) mirrors precedent in the same neighbourhood — PolicyConnectionSyncStage, PolicyConnectionName, Subrate, CustomUnit in Policy.ts are all hoisted as named types so rendering code can reference them without re-deriving the shape. Adding per-field JSDoc keeps the file consistent with the rest of src/types/onyx/, where every Onyx-bound model documents its fields (e.g. Account.ts, AccountData.ts, ApprovalWorkflow.ts). One alternative considered and rejected: broadening result? to a discriminated union keyed by connectionName to cover future QBO / Xero / NetSuite payloads. Gusto is currently the only connection that emits a structured JOB_DONE result, so the union should be introduced when the second connection follows suit — not pre-emptively, since today it would add a single-variant union that obscures rather than documents intent.