Sperry Jobber Integration — Friction Report & Build

Executive Summary

The daily Sperry campaign chart was undercounting weekly Requests by roughly 10x — reporting 11 inbound requests for the week of Apr 19 when the actual count was 119. Root cause: the production script was counting newly-created Jobber Clients flagged as isLead=true, which only catches first-time customers. Repeat customers submitting new Requests (the majority of inbound volume) were invisible to the metric.

The straightforward fix — swap to Jobber's top-level Query.requests field — was blocked by Jobber's OAuth scope-grant logic. Despite the read_requests scope being toggled ON and saved in the developer center, every access token grant silently stripped it from the resulting permissions. After three full disconnect/reconnect cycles and a Jobber app config save-and-reauth, the scope remained absent from token grants while other newly-toggled scopes (Marketing, Custom Field Configurations, Users) came through correctly.

Workaround deployed: query Requests through the nested Client.requests connection. This path is gated only by read_clients (which we have) and returns the same Request data. The corrected daily script and a 26-week historical backfill are now live; the chart for week ending Apr 19 reads 119, matching ground truth.

11

Old Metric (this week)

119

New Metric (this week)

10.8x

Undercount Factor

26 wks

Backfilled History

1. The Friction

1.1 Original Defect

The production script sperry_requests_update.py ran daily at 06:03 AM, querying Jobber's GraphQL clients connection and counting clients with isLead=true created in the current week. This metric was named "Requests" in the chart but measured something different — first-time customer creations, not actual Request submissions.

For a tree care business with high repeat-customer volume, the gap between "new lead clients" and "Request submissions" is substantial. Most weekly inbound activity comes from existing clients re-engaging — those Requests never trigger an isLead flag because the client record already exists.

1.2 Friction Map — Time Spent vs. Path

Phase	Action	Outcome
Diagnose	Compared script output (11) to known correct value (119) — identified isLead vs Request mismatch	Win
Probe	Tested top-level Query.requests with existing access token	Blocked: permissions
Scope check	Inspected access token JWT — only read_clients read_quotes read_jobs read_invoices granted despite Requests scope toggled ON	Discovery
Reauth #1	Disconnected via appDisconnect mutation, re-ran OAuth flow	Same 4 scopes
Reauth #2	Added explicit scope= param to auth URL	Param ignored — Jobber doesn't accept it
App save	Suspected uncommitted scope changes — clicked Save App in dev center	Unlocked: marketing, custom_field_configurations, users, expenses
Reauth #3	Fresh consent flow with all scopes saved + clean app config	read_requests still silently dropped
Pivot	Schema introspection on Client type — found Client.requests connection	Win
Verify	Tested nested query under read_clients scope alone	Returns Request data
Deploy	Patched script, ran live — 118 this week, 60 prior week (within 1 of 119 target)	Production

1.3 Jobber Platform Issues Uncovered

2. The Working Architecture

2.1 Data Flow

Component	Role
sperry_requests_update.py	Daily updater. Auths to Jobber, queries weekly Request counts, patches CF Worker, redeploys.
run_secrets.json	Stores rotating Jobber refresh token + client credentials. Token is rotated by Jobber on every refresh; script saves new token immediately to disk before any further work.
Jobber GraphQL API	Source of truth. Queried via Client.requests nested connection (read_clients scope only).
CF Worker sperry-requests-apr2026	Renders the chart. rawCounts[] array drives YoY table, stat cards, EV panel — all via JS, never hardcoded HTML.
Scheduled Task sperry-requests-daily-update	Cron 0 6 * * *. Runs the script daily at 06:03 AM Pacific. Built-in zero-guard aborts deploy if both counts return 0.

2.2 The Workaround Query

Jobber's OAuth scope check applies at the field level. The top-level Query.requests field requires read_requests. The nested Client.requests connection requires only read_clients. Since Client records bump their updatedAt timestamp whenever a new Request is submitted on their behalf, we can filter clients to those touched in the last 2 weeks, then iterate their nested Requests and bucket by week.

query Clients($after: String, $filter: ClientFilterAttributes) {
  clients(
    first: 30,
    after: $after,
    filter: $filter,
    sort: { key: UPDATED_AT, direction: DESCENDING }
  ) {
    pageInfo { hasNextPage endCursor }
    nodes {
      id
      updatedAt
      requests(first: 50) {
        nodes { id createdAt }
      }
    }
  }
}

Filter: { updatedAt: { after: prior_sunday } }. Returns approximately 280 active clients per run, well under the throttle budget. Total query cost ~150 units against a 10,000 budget.

2.3 Verification

Week Index	Date Range	Old Method	New Method	Delta
328	Apr 19 – Apr 25	11	119	+108
327	Apr 12 – Apr 18	10	60	+50
326	Apr 5 – Apr 11	—	77	consistent
322	Mar 8 – Mar 14	—	97	consistent

Indices 302–326 were already populated with correct historical Request data from prior runs of a different methodology — only [327] and [328] (last 2 weeks) had been overwritten with the broken isLead-based count.

3. Operational Runbook

3.1 Daily Run

The scheduled task sperry-requests-daily-update runs at 06:03 AM Pacific. It:

1. Refreshes the Jobber access token (rotates the refresh token, saves new value immediately to run_secrets.json).
2. Computes this week (Sun → now) and prior week (prior Sun → this Sun) ranges in UTC.
3. Runs the Client.requests nested query with safety stop at 50 pages.
4. Fetches the CF Worker's current code, parses rawCounts[], patches indices [this_idx] and [prior_idx].
5. Updates the hardcoded Apr 19 storm-table entry to match the new this_idx value.
6. Aborts via RuntimeError if both counts are 0 (prevents wiping the chart on a data-pull failure).
7. Redeploys the worker via Cloudflare API.

3.2 Manual Run

python3 "/Users/Jason/My Drive (jason@bosstorque.ai)/1_Clients/Sperry Tree Care/2. Campaign Performance/scripts/sperry_requests_update.py"

3.3 Refresh Token Recovery

If the saved refresh token becomes invalid (HTTP 401 on token refresh), the connection must be re-authorized:

1. Visit the OAuth consent URL in a logged-in Jobber browser tab:

   https://api.getjobber.com/api/oauth/authorize?response_type=code&client_id=7e52aab6-cb92-4318-9261-beb1f4249447&redirect_uri=https://localhost/callback

2. Click Allow Access on the consent screen.
3. Browser will fail to load localhost — copy the code=... value from the URL bar.
4. Exchange the code for a refresh token by POSTing to https://api.getjobber.com/api/oauth/token with grant_type=authorization_code, the code, client_id, client_secret, and the same redirect_uri.
5. Update JOBBER_REFRESH_TOKEN in run_secrets.json.

3.4 Backfill

To re-baseline historical weeks under the new methodology, run sperry_requests_backfill.py with WEEKS_BACK set to the desired number of weeks. The 26-week (6-month) backfill executed on Apr 24, 2026 covers indices 302–328.

4. Open Issues & Risks

4.1 Pagination Limits

The query fetches the most recent 50 Requests per Client. For the rare repeat customer with more than 50 Requests in a 6-month window, older Requests would be missed. Sperry's customer pattern (1–3 Requests per client per year) makes this a non-issue in practice, but a high-volume contract account could expose it.

4.2 Scope-Grant Fragility

The current architecture depends on the Client.requests nested connection remaining accessible under read_clients alone. If Jobber tightens its scope enforcement to require read_requests for all Request data (including nested), this script breaks immediately and silently — the query would error and counts would zero out, triggering the zero-guard abort.

4.3 Recommended Follow-up

• File a Jobber dev support ticket documenting the silent scope-drop behavior. Even if the workaround holds, the platform behavior is a bug worth reporting. Reference client_id 7e52aab6-cb92-4318-9261-beb1f4249447 and the specific scopes affected (read_requests, read_scheduled_items, write_clients, write_quotes, write_jobs, write_invoices).
• Add monitoring alert if the daily run completes but writes a value that drops more than 50% week-over-week — would catch silent scope-tightening before it persists in the chart for days.
• Consider tester accounts in the Jobber developer center if Jobber's marketplace review path is ever pursued. The DRAFT app supports up to 5 paying accounts without review; the only reason to escalate is if scope-grant behavior becomes a hard block.

5. Reference

Item	Value
Jobber App Name	BOSSTORQUE Sperry Report
Status	DRAFT (does not require review per Jobber custom integration policy)
Jobber Account	Sperry Tree Care (account_id 1970331)
Client ID	7e52aab6-cb92-4318-9261-beb1f4249447
Granted Scopes	read_clients, read_quotes, read_jobs, read_invoices, read_jobber_payments, read_users, write_users, write_tax_rates, read_expenses, read_custom_field_configurations, write_custom_field_configurations, read_marketing, write_marketing
Silently Dropped	read_requests, read_scheduled_items, write_clients, write_quotes, write_jobs, write_invoices
Chart URL	sperry-requests-apr2026.jason-8ce.workers.dev
Terms of Service URL	sperry-bosstorque-tos.jason-8ce.workers.dev
Privacy Policy URL	sperrytreecare.com/privacy-policy