refactor: keep defineExpose(refresh), centralize refresh signal in useBillingContext

Per review feedback: defineExpose('refresh') on UsageLogsTable was a
legitimate stateless imperative command (no state to desync), so the
refetchKey-prop replacement was the wrong fix for the wrong problem.
Reverted UsageLogsTable to expose refresh() again via a template ref,
matching this repo's own defineExpose convention
(docs/guidance/vue-components.md, src/components/AGENTS.md,
.agents/checks/vue-patterns.md).

What still needed fixing was where the "should credits UI refresh"
decision lived: CreditsPanel had its own local watch(balance) +
revision counter, and PlanCreditsPanelContent had none at all (so a
top-up while on its Activity tab never refreshed that table). Moved
the skip-first-hydration balance-watch into useBillingContext as a new
exposed `usageLogsRefreshSignal`, the shared composable that already
owns `balance`. Both CreditsPanel and PlanCreditsPanelContent now just
watch that one signal and call their own table ref's refresh() -
the "when" lives once in the data layer; the "how" (an imperative
command) stays where Vue's defineExpose convention says it belongs.

usePaginatedQuery's page/limit/total derivation is unchanged - that
part was never in dispute.

Author: claude

src/components/dialog/content/setting/CreditsPanel.test.ts

@@ -1,41 +1,37 @@
 import { render, screen } from '@testing-library/vue'
 import userEvent from '@testing-library/user-event'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { defineComponent, h, nextTick } from 'vue'
+import { defineComponent, h } from 'vue'
 import { createI18n } from 'vue-i18n'
 
-import type { BalanceInfo } from '@/composables/billing/types'
-
 import CreditsPanel from './CreditsPanel.vue'
 
 const billingMocks = vi.hoisted(() => ({
-  balance: { value: null as BalanceInfo | null },
+  usageLogsRefreshSignal: { value: 0 },
   manageSubscription: vi.fn()
 }))
 vi.mock('@/composables/billing/useBillingContext', async () => {
   const { ref } = await import('vue')
-  const balance = ref<BalanceInfo | null>(null)
-  Object.defineProperty(billingMocks, 'balance', { get: () => balance })
+  const usageLogsRefreshSignal = ref(0)
+  Object.defineProperty(billingMocks, 'usageLogsRefreshSignal', {
+    get: () => usageLogsRefreshSignal
+  })
   return {
     useBillingContext: () => ({
-      balance,
+      usageLogsRefreshSignal,
       manageSubscription: billingMocks.manageSubscription
     })
   }
 })
 
+const refreshActivity = vi.hoisted(() => vi.fn())
 vi.mock('./UsageLogsTable.vue', async () => {
   const { defineComponent, h } = await import('vue')
   return {
     default: defineComponent({
-      props: { refetchKey: { type: Number, default: 0 } },
-      setup(props) {
-        return () =>
-          h(
-            'div',
-            { 'data-testid': 'usage-logs-table' },
-            String(props.refetchKey)
-          )
+      setup(_props, { expose }) {
+        expose({ refresh: refreshActivity })
+        return () => h('div', { 'data-testid': 'usage-logs-table' })
       }
     })
   }
@@ -77,19 +73,10 @@ const i18n = createI18n({
   }
 })
 
-function makeBalance(amountMicros: number): BalanceInfo {
-  return {
-    amountMicros,
-    currency: 'usd',
-    effectiveBalanceMicros: amountMicros,
-    prepaidBalanceMicros: 0,
-    cloudCreditBalanceMicros: 0
-  }
-}
-
 describe('CreditsPanel', () => {
   beforeEach(() => {
-    billingMocks.balance.value = null
+    billingMocks.usageLogsRefreshSignal.value = 0
+    refreshActivity.mockClear()
   })
 
   function renderComponent() {
@@ -107,16 +94,12 @@ describe('CreditsPanel', () => {
     expect(billingMocks.manageSubscription).toHaveBeenCalledOnce()
   })
 
-  it('bumps the activity refetch key on a balance change but not on first hydration', async () => {
+  it('refreshes activity when the shared billing signal changes', async () => {
     renderComponent()
-    const activityTable = screen.getByTestId('usage-logs-table')
-
-    billingMocks.balance.value = makeBalance(5000)
-    await nextTick()
-    expect(activityTable.textContent).toBe('0')
+    screen.getByTestId('usage-logs-table')
+    expect(refreshActivity).not.toHaveBeenCalled()
 
-    billingMocks.balance.value = makeBalance(9000)
-    await nextTick()
-    expect(activityTable.textContent).toBe('1')
+    billingMocks.usageLogsRefreshSignal.value++
+    await vi.waitFor(() => expect(refreshActivity).toHaveBeenCalledOnce())
   })
 })

src/components/dialog/content/setting/CreditsPanel.vue

@@ -39,7 +39,7 @@
       </Button>
     </div>
 
-    <UsageLogsTable v-if="!embedded" :refetch-key="creditsRevision" />
+    <UsageLogsTable v-if="!embedded" ref="usageLogsTableRef" />
 
     <div v-if="!embedded" class="flex flex-row gap-2">
       <Button variant="muted-textonly" @click="handleFaqClick">
@@ -76,19 +76,14 @@ const { embedded = false } = defineProps<{
 }>()
 
 const { buildDocsUrl, docsPaths } = useExternalLink()
-const { balance, manageSubscription } = useBillingContext()
+const { usageLogsRefreshSignal, manageSubscription } = useBillingContext()
 const commandStore = useCommandStore()
 const telemetry = useTelemetry()
 
-// A genuine balance change (not the first hydration) is a reason for the
-// activity table to reload. This is a plain reactive value passed down as a
-// prop, rather than the parent reaching into the child to call a method it
-// exposes for that purpose.
-const creditsRevision = ref(0)
+const usageLogsTableRef = ref<InstanceType<typeof UsageLogsTable> | null>(null)
 
-watch(balance, (next, previous) => {
-  if (!next || !previous) return
-  creditsRevision.value++
+watch(usageLogsRefreshSignal, () => {
+  void usageLogsTableRef.value?.refresh()
 })
 
 const handleCreditsHistoryClick = async () => {

src/components/dialog/content/setting/UsageLogsTable.test.ts

@@ -354,20 +354,6 @@ describe('UsageLogsTable', () => {
         limit: 7
       })
     })
-
-    it('refetches page 1 when refetchKey changes', async () => {
-      const { rerender } = await renderLoaded()
-      mockCustomerEventsService.getMyEvents.mockClear()
-
-      await rerender({ refetchKey: 1 })
-
-      await waitFor(() => {
-        expect(mockCustomerEventsService.getMyEvents).toHaveBeenCalledWith({
-          page: 1,
-          limit: 7
-        })
-      })
-    })
   })
 
   describe('billing events source', () => {

src/components/dialog/content/setting/UsageLogsTable.vue

@@ -110,36 +110,23 @@ import {
   useCustomerEventsService
 } from '@/services/customerEventsService'
 
-const { refetchKey = 0 } = defineProps<{
-  /**
-   * Bumped by the parent to signal an out-of-band reason to reload (e.g. a
-   * balance change) without reaching into this component's internals.
-   */
-  refetchKey?: number
-}>()
-
 const { t } = useI18n()
 
 const customerEventService = useCustomerEventsService()
 
 const { shouldUseWorkspaceBilling } = useBillingRouting()
 
-// A billing-rail flip or a parent-signalled refetch are both reasons to
-// reset to page 1 and reload against the (possibly new) backend.
-const queryKey = computed(
-  () => `${shouldUseWorkspaceBilling.value}:${refetchKey}`
-)
-
 const {
   items: events,
   limit,
   total,
   first,
   loading,
   error,
-  goToPage
-} = usePaginatedQuery<AuditLog, string>({
-  key: queryKey,
+  goToPage,
+  refresh
+} = usePaginatedQuery<AuditLog, boolean>({
+  key: shouldUseWorkspaceBilling,
   initialLimit: 7,
   fetchPage: async ({ page, limit: requestedLimit }) => {
     const params = { page, limit: requestedLimit }
@@ -189,4 +176,8 @@ const tooltipContentMap = computed(() => {
 const onPageChange = (event: { page: number }) => {
   goToPage(event.page + 1)
 }
+
+defineExpose({
+  refresh
+})
 </script>

src/composables/billing/types.ts

@@ -123,6 +123,13 @@ export interface BillingState {
 export interface BillingContext extends BillingState, BillingActions {
   type: ComputedRef<BillingType>
   reconcileSubscriptionSuccess: () => Promise<void>
+  /**
+   * Bumped whenever `balance` genuinely changes (not on its initial
+   * hydration) — the one signal for "credits-derived UI, like the usage
+   * log, should reload," so consumers watch this instead of each
+   * re-deriving the same balance-transition check.
+   */
+  usageLogsRefreshSignal: Ref<number>
   /**
    * True when the active team workspace is still on a pre-credit-slider
    * (legacy) per-member tier plan, which keeps the old team pricing table.

src/composables/billing/useBillingContext.test.ts

@@ -282,6 +282,17 @@ describe('useBillingContext', () => {
     await expect(fetchBalance()).resolves.toBeUndefined()
   })
 
+  it('bumps usageLogsRefreshSignal on a genuine balance change but not on first hydration', async () => {
+    const context = useBillingContext()
+
+    await vi.waitFor(() => expect(context.balance.value).not.toBeNull())
+    expect(context.usageLogsRefreshSignal.value).toBe(0)
+
+    await context.fetchBalance()
+
+    expect(context.usageLogsRefreshSignal.value).toBe(1)
+  })
+
   it('exposes subscribe action', async () => {
     const { subscribe } = useBillingContext()
     await expect(subscribe('pro-monthly')).resolves.toEqual({

src/composables/billing/useBillingContext.ts

@@ -124,6 +124,12 @@ function useBillingContextInternal(): BillingContext {
     toValue(activeContext.value.balance)
   )
 
+  const usageLogsRefreshSignal = ref(0)
+  watch(balance, (next, previous) => {
+    if (!next || !previous) return
+    usageLogsRefreshSignal.value++
+  })
+
   const plans = computed(() => toValue(checkoutContext.value.plans))
 
   const currentPlanSlug = computed(() =>
@@ -348,6 +354,7 @@ function useBillingContextInternal(): BillingContext {
     isInitialized,
     subscription,
     balance,
+    usageLogsRefreshSignal,
     plans,
     currentPlanSlug,
     teamCreditStops,

src/platform/workspace/components/dialogs/settings/PlanCreditsPanelContent.test.ts

@@ -1,5 +1,6 @@
 import userEvent from '@testing-library/user-event'
 import { describe, expect, it, vi } from 'vitest'
+import { defineComponent, h } from 'vue'
 import { createI18n } from 'vue-i18n'
 
 import { render, screen } from '@testing-library/vue'
@@ -15,6 +16,22 @@ vi.mock('@/platform/distribution/types', () => ({
   }
 }))
 
+const billingMocks = vi.hoisted(() => ({
+  usageLogsRefreshSignal: { value: 0 }
+}))
+vi.mock('@/composables/billing/useBillingContext', async () => {
+  const { ref } = await import('vue')
+  const usageLogsRefreshSignal = ref(0)
+  Object.defineProperty(billingMocks, 'usageLogsRefreshSignal', {
+    get: () => usageLogsRefreshSignal
+  })
+  return {
+    useBillingContext: () => ({ usageLogsRefreshSignal })
+  }
+})
+
+const refreshUsageLogs = vi.hoisted(() => vi.fn())
+
 const stubs = {
   SubscriptionPanelContentWorkspace: {
     template: '<section aria-label="Plan and credits overview" />'
@@ -26,9 +43,12 @@ const stubs = {
   SubscriptionFooterLinks: {
     template: '<footer aria-label="Subscription links" />'
   },
-  UsageLogsTable: {
-    template: '<section aria-label="Usage logs" />'
-  }
+  UsageLogsTable: defineComponent({
+    setup(_props, { expose }) {
+      expose({ refresh: refreshUsageLogs })
+      return () => h('section', { 'aria-label': 'Usage logs' })
+    }
+  })
 }
 
 function renderPanel({ cloud = true } = {}) {
@@ -75,4 +95,13 @@ describe('PlanCreditsPanelContent', () => {
       screen.queryByRole('region', { name: 'Plan and credits overview' })
     ).toBeNull()
   })
+
+  it('refreshes the usage log when the shared billing signal changes', async () => {
+    renderPanel()
+    await userEvent.click(screen.getByRole('button', { name: 'Activity' }))
+    refreshUsageLogs.mockClear()
+
+    billingMocks.usageLogsRefreshSignal.value++
+    await vi.waitFor(() => expect(refreshUsageLogs).toHaveBeenCalledOnce())
+  })
 })

src/platform/workspace/components/dialogs/settings/PlanCreditsPanelContent.vue

@@ -27,29 +27,36 @@
         />
       </div>
     </template>
-    <UsageLogsTable v-else />
+    <UsageLogsTable v-else ref="usageLogsTable" />
   </div>
 </template>
 
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, ref, useTemplateRef, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 import CreditsPanel from '@/components/dialog/content/setting/CreditsPanel.vue'
 import UsageLogsTable from '@/components/dialog/content/setting/UsageLogsTable.vue'
 import Button from '@/components/ui/button/Button.vue'
+import { useBillingContext } from '@/composables/billing/useBillingContext'
 import SubscriptionFooterLinks from '@/platform/cloud/subscription/components/SubscriptionFooterLinks.vue'
 import { isCloud } from '@/platform/distribution/types'
 import SubscriptionPanelContentWorkspace from '@/platform/workspace/components/SubscriptionPanelContentWorkspace.vue'
 
 type View = 'overview' | 'activity'
 
 const { t } = useI18n()
+const { usageLogsRefreshSignal } = useBillingContext()
 
 const tabs = computed<{ key: View; label: string }[]>(() => [
   { key: 'overview', label: t('workspacePanel.planCredits.tabs.overview') },
   { key: 'activity', label: t('workspacePanel.planCredits.tabs.activity') }
 ])
 
 const activeView = ref<View>('overview')
+
+const usageLogsTable = useTemplateRef('usageLogsTable')
+watch(usageLogsRefreshSignal, () => {
+  void usageLogsTable.value?.refresh()
+})
 </script>

src/storybook/mocks/useBillingContext.ts

@@ -52,6 +52,7 @@ export function useBillingContext(): BillingContext {
     isInitialized: ref(true),
     subscription: computed(() => state.value.subscription),
     balance: computed(() => null),
+    usageLogsRefreshSignal: ref(0),
     plans: computed(() => []),
     currentPlanSlug: computed(() => null),
     teamCreditStops: computed(() => null),