✨ [FFL-2858] add feature-flag catalog browsing to the flags tab

Builds on FFL-2597: fetches the flag catalog via the OAuth-capable FFE UI
endpoint (transparently refreshing the token), and renders it with
search + type/tag filters and pagination. Read-only; overriding flags
comes in FFL-2596.

Author: kellyw1806

developer-extension/src/panel/components/tabs/flagsTab/flagCatalog.spec.ts

@@ -0,0 +1,151 @@
+import { fetchFlagCatalogWithToken } from './flagCatalog'
+
+describe('flagCatalog', () => {
+  describe('fetchFlagCatalogWithToken', () => {
+    // Returns each provided page in turn, then empty pages (the loop stops on the first empty page).
+    function mockPages(pages: Array<Array<{ attributes: Record<string, unknown> }>>) {
+      let call = 0
+      spyOn(globalThis, 'fetch').and.callFake(() => {
+        const data = pages[call] ?? []
+        call += 1
+        return Promise.resolve(new Response(JSON.stringify({ data })))
+      })
+    }
+
+    it('paginates until an empty page and maps attributes', async () => {
+      mockPages([
+        [
+          {
+            attributes: {
+              key: 'flag-a',
+              name: 'Flag A',
+              value_type: 'BOOLEAN',
+              variants: [{ name: 'on', value: 'true' }],
+              tags: ['team:x'],
+            },
+          },
+        ],
+        [],
+      ])
+
+      expect(await fetchFlagCatalogWithToken('tok', 'datad0g.com')).toEqual([
+        { key: 'flag-a', name: 'Flag A', type: 'BOOLEAN', variants: [{ name: 'on', value: true }], tags: ['team:x'] },
+      ])
+    })
+
+    it('dedupes flags repeated across pages, keeping the first occurrence', async () => {
+      mockPages([
+        [{ attributes: { key: 'dup', name: 'First', value_type: 'STRING', variants: [], tags: [] } }],
+        [{ attributes: { key: 'dup', name: 'Second', value_type: 'STRING', variants: [], tags: [] } }],
+        [],
+      ])
+
+      const flags = await fetchFlagCatalogWithToken('tok', 'datad0g.com')
+      expect(flags.length).toBe(1)
+      expect(flags[0].name).toBe('First')
+    })
+
+    it('parses variant values by declared type, falling back to the raw string on bad input', async () => {
+      mockPages([
+        [
+          {
+            attributes: {
+              key: 'f',
+              value_type: 'JSON',
+              variants: [
+                { name: 'ok', value: '{"a":1}' },
+                { name: 'bad', value: 'not json' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'n',
+              value_type: 'INTEGER',
+              variants: [
+                { name: 'five', value: '5' },
+                { name: 'nan', value: 'abc' },
+              ],
+            },
+          },
+        ],
+        [],
+      ])
+
+      const [json, integer] = await fetchFlagCatalogWithToken('tok', 'datad0g.com')
+      expect(json.variants[0].value).toEqual({ a: 1 })
+      expect(json.variants[1].value).toBe('not json')
+      expect(integer.variants[0].value).toBe(5)
+      expect(integer.variants[1].value).toBe('abc')
+    })
+
+    it('keeps malformed or out-of-range variant values raw instead of coercing them', async () => {
+      mockPages([
+        [
+          {
+            attributes: {
+              key: 'b',
+              value_type: 'BOOLEAN',
+              variants: [
+                { name: 't', value: 'true' },
+                { name: 'f', value: 'false' },
+                { name: 'weird', value: 'True' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'i',
+              value_type: 'INTEGER',
+              variants: [
+                { name: 'partial', value: '5abc' },
+                { name: 'float', value: '5.5' },
+                { name: 'unsafe', value: '9007199254740993' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'd',
+              value_type: 'NUMERIC',
+              variants: [
+                { name: 'ok', value: '5.5' },
+                { name: 'partial', value: '5abc' },
+                { name: 'empty', value: '' },
+              ],
+            },
+          },
+        ],
+        [],
+      ])
+
+      const [booleanFlag, integer, numeric] = await fetchFlagCatalogWithToken('tok', 'datad0g.com')
+      expect(booleanFlag.variants.map((variant) => variant.value)).toEqual([true, false, 'True'])
+      expect(integer.variants.map((variant) => variant.value)).toEqual(['5abc', '5.5', '9007199254740993'])
+      expect(numeric.variants.map((variant) => variant.value)).toEqual([5.5, '5abc', ''])
+    })
+
+    it('falls back to the key for a missing name and defaults tags/variants', async () => {
+      mockPages([[{ attributes: { key: 'no-name', value_type: 'STRING' } }], []])
+
+      const [flag] = await fetchFlagCatalogWithToken('tok', 'datad0g.com')
+      expect(flag.name).toBe('no-name')
+      expect(flag.tags).toEqual([])
+      expect(flag.variants).toEqual([])
+    })
+
+    it('tolerates a 200 response that omits the data array', async () => {
+      spyOn(globalThis, 'fetch').and.returnValue(Promise.resolve(new Response(JSON.stringify({ errors: ['x'] }))))
+      expect(await fetchFlagCatalogWithToken('tok', 'datad0g.com')).toEqual([])
+    })
+
+    it('throws on a non-ok response', async () => {
+      spyOn(globalThis, 'fetch').and.returnValue(
+        Promise.resolve(new Response('err', { status: 500, statusText: 'Server Error' }))
+      )
+      await expectAsync(fetchFlagCatalogWithToken('tok', 'datad0g.com')).toBeRejectedWithError(
+        /Failed to fetch flag catalog/
+      )
+    })
+  })
+})

developer-extension/src/panel/components/tabs/flagsTab/flagCatalog.ts

@@ -0,0 +1,148 @@
+import type { FlagOverrideType } from './flagTypeConstants'
+import { getFlagsApiHost } from './oauth'
+
+// A parsed feature-flag value — any JSON value. Objects and arrays are both `object`; `null` and
+// primitives are covered explicitly (JSON.parse can return any of them).
+export type CatalogVariantValue = boolean | string | number | object | null
+
+export interface CatalogVariant {
+  name: string
+  value: CatalogVariantValue
+}
+
+export interface CatalogFlag {
+  key: string
+  // Human-friendly display name; falls back to the key when the API doesn't provide one.
+  name: string
+  type: FlagOverrideType
+  variants: CatalogVariant[]
+  tags: string[]
+}
+
+interface RawFeatureFlagVariant {
+  name: string
+  value: string
+}
+
+interface RawFeatureFlagAttributes {
+  key: string
+  name?: string
+  value_type: FlagOverrideType
+  variants?: RawFeatureFlagVariant[]
+  tags?: string[]
+}
+
+interface RawFeatureFlagResource {
+  attributes: RawFeatureFlagAttributes
+}
+
+interface RawFeatureFlagsResponse {
+  data: RawFeatureFlagResource[]
+}
+
+// Variant values come back from the API as strings regardless of the flag's declared type. Falls
+// back to the raw string on unparseable input so one malformed variant can't blow up the mapping
+// of the entire catalog.
+function parseVariantValue(type: FlagOverrideType, rawValue: string): CatalogVariantValue {
+  switch (type) {
+    case 'BOOLEAN':
+      // Only the exact strings count; anything else (e.g. "True", "falsex", "") is malformed and
+      // kept raw rather than silently collapsing to false.
+      if (rawValue === 'true') {
+        return true
+      }
+      if (rawValue === 'false') {
+        return false
+      }
+      return rawValue
+    case 'INTEGER': {
+      // parseInt would accept partial/oversized input ("5abc" -> 5, unsafe integers get rounded), so
+      // require the whole string to be an integer within the safe range; otherwise keep it raw.
+      const parsed = Number(rawValue)
+      return /^[+-]?\d+$/.test(rawValue) && Number.isSafeInteger(parsed) ? parsed : rawValue
+    }
+    case 'NUMERIC': {
+      // parseFloat accepts a numeric prefix ("5abc" -> 5) and Number("") is 0, so require a
+      // non-empty string that parses fully to a finite number; otherwise keep it raw.
+      const parsed = Number(rawValue)
+      return rawValue.trim() !== '' && Number.isFinite(parsed) ? parsed : rawValue
+    }
+    case 'JSON':
+      try {
+        return JSON.parse(rawValue) as CatalogVariantValue
+      } catch {
+        return rawValue
+      }
+    case 'STRING':
+      return rawValue
+  }
+}
+
+// The endpoint paginates via limit/offset and enforces its own max page size, so a page can
+// come back shorter than PAGE_LIMIT even when more results remain — only an empty page means
+// we've reached the end. Advance offset by what actually came back, not by PAGE_LIMIT.
+const PAGE_LIMIT = 100
+// Safety bound so a backend that ignores `offset` (returns the same page forever) can't spin an
+// unbounded loop. 500 pages × 100 = 50k flags, far beyond any real catalog.
+const MAX_PAGES = 500
+
+/**
+ * Fetches the full flag catalog using an OAuth access token, via the FFE UI endpoint
+ * (GET /api/ui/ffe/feature-flags). OAuth is the only supported auth path (see oauth.ts).
+ */
+export async function fetchFlagCatalogWithToken(token: string, site: string): Promise<CatalogFlag[]> {
+  const host = getFlagsApiHost(site)
+  const resources: RawFeatureFlagResource[] = []
+  let offset = 0
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const url = new URL(`https://${host}/api/ui/ffe/feature-flags`)
+    url.searchParams.set('limit', String(PAGE_LIMIT))
+    url.searchParams.set('offset', String(offset))
+
+    const response = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch flag catalog: ${response.status} ${response.statusText}`)
+    }
+
+    const body = (await response.json()) as RawFeatureFlagsResponse
+    // Tolerate a response that omits/mistypes `data` rather than throwing on `.length`/spread.
+    const pageResources = Array.isArray(body?.data) ? body.data : []
+    resources.push(...pageResources)
+
+    if (pageResources.length === 0) {
+      break
+    }
+    offset += pageResources.length
+  }
+
+  return mapResources(resources)
+}
+
+function mapResources(resources: RawFeatureFlagResource[]): CatalogFlag[] {
+  // Dedupe by key. The endpoint's offset pagination can return the same flag on more than one
+  // page, which would otherwise render as duplicate rows AND collide React keys (`key={flag.key}`),
+  // breaking variant clicks, search, and clear-all. Keep the first occurrence of each key.
+  const byKey = new Map<string, CatalogFlag>()
+  for (const { attributes } of resources) {
+    if (byKey.has(attributes.key)) {
+      continue
+    }
+    byKey.set(attributes.key, {
+      key: attributes.key,
+      name: attributes.name || attributes.key,
+      type: attributes.value_type,
+      variants: (attributes.variants ?? []).map((variant) => ({
+        name: variant.name,
+        value: parseVariantValue(attributes.value_type, variant.value),
+      })),
+      tags: attributes.tags ?? [],
+    })
+  }
+  return Array.from(byKey.values())
+}