feat: add extraQueryKeys param to useCustomer and useEntity for declarative revalidation

[kylegrahammatzen]

Summary

• Adds an optional extraQueryKeys parameter to useCustomer and useEntity hooks that gets spread into the SWR query key
• When any value in extraQueryKeys changes, SWR automatically refetches without needing useEffect or imperative refetch() calls

Problem

When a user switches organizations (or any external dependency changes), there's no declarative way to trigger a refetch of customer/entity data. The current options are:

1. Call refetch() imperatively
2. Put refetch() in a useEffect — bad practice with real sync issues
3. Poll with refreshInterval — wasteful and laggy

Solution

Spread an optional extraQueryKeys array into the SWR query key. When any value changes, SWR treats it as a new cache entry and refetches automatically.

const { customer } = useCustomer({
  extraQueryKeys: [activeOrgId],
});

Files changed

• useCustomerBase.tsx — added extraQueryKeys to UseCustomerParams, spread into SWR query key
• useEntityBase.tsx — added extraQueryKeys param, spread into SWR query key
• useEntity.tsx (react) — forward extraQueryKeys to base hook
• useEntity.tsx (next) — forward extraQueryKeys to base hook

useCustomer wrappers (react + next) already pass params through to useCustomerBase, so they get extraQueryKeys for free.

Testing

• Built autumn-js package with zero errors
• Type-checked against a Next.js 16.1.6 test app with tsc --noEmit

---

Summary by cubic

Adds an optional extraQueryKeys param to useCustomer and useEntity so data refetches automatically when external dependencies change. This enables declarative revalidation without useEffect or manual refetch calls.

• New Features

  • extraQueryKeys is appended to the SWR key; any value change triggers a refetch.
  • Supported in useCustomerBase and useEntityBase; React and Next useEntity wrappers forward the param.

• Migration

  • No breaking changes. Param is optional.

^{Written for commit 1a7a52a. Summary will update on new commits.}

Greptile Summary

This PR adds declarative revalidation support to the useCustomer and useEntity hooks by introducing an optional extraQueryKeys parameter that gets spread into the SWR query key. When any value in extraQueryKeys changes (e.g., when switching organizations), SWR automatically refetches the data without requiring imperative refetch() calls or useEffect workarounds.

Key Changes:

• API changes: Added extraQueryKeys?: (string | null | undefined)[] parameter to useCustomer and useEntity hooks
• Improvements: Enabled declarative data refetching when external dependencies change, eliminating the need for imperative refetch patterns or polling

The implementation spreads extraQueryKeys into the SWR query key across both base hooks (useCustomerBase and useEntityBase), and the wrapper hooks properly forward this parameter. The type signature allows null and undefined values in the array to handle loading states gracefully.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - it's a purely additive feature with no breaking changes
• The changes are minimal, focused, and follow existing patterns. The implementation is type-safe, backward compatible (optional parameter), and has been tested with both build and type-checking. No logical errors, security issues, or breaking changes detected.
• No files require special attention - all changes follow the same pattern consistently

Important Files Changed

Filename	Overview
package/src/libraries/react/hooks/useCustomerBase.tsx	Added extraQueryKeys param to UseCustomerParams interface and spread it into SWR query key - clean implementation with no issues
package/src/libraries/react/hooks/useEntityBase.tsx	Added extraQueryKeys as separate param and spread it into SWR query key - consistent with useCustomer implementation
package/src/libraries/react/hooks/useEntity.tsx	Wrapper hook that correctly destructures extraQueryKeys from params and forwards it to useEntityBase
package/src/next/client/hooks/useEntity.tsx	Next.js wrapper with identical implementation to React version - correctly forwards extraQueryKeys to useEntityBase

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User calls useCustomer/useEntity with extraQueryKeys] --> B{Wrapper Hook}
    B --> C[Destructure extraQueryKeys from params]
    C --> D[Forward to Base Hook]
    D --> E[Build SWR Query Key]
    E --> F["queryKey = ['customer/entity', baseUrl/entityId, expand, ...extraQueryKeys]"]
    F --> G[SWR Cache Lookup]
    G --> H{extraQueryKeys changed?}
    H -->|Yes| I[New cache key - trigger refetch]
    H -->|No| J[Return cached data]
    I --> K[Fetch from API]
    K --> L[Update cache with new key]
    L --> M[Return fresh data]
    J --> M

Loading

_{Last reviewed commit: 1a7a52a}

[vercel]

@kylegrahammatzen is attempting to deploy a commit to the Autumn Team on Vercel.

A member of the Team first needs to authorize it.

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[SirTenzin]

perfect