@sqaoss/flowy 1.1.3 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {

package/skills/using-flowy/SKILL.md

@@ -20,9 +20,11 @@ flowy init           # auto-detects the git repo, creates a project, maps this d
 If Flowy isn't set up yet, the human needs to run:
 ```bash
 npm i -g @sqaoss/flowy
-flowy setup remote --email their@email.com
+flowy setup remote --email their@email.com --tier explorer
 ```
 
+After registration, complete payment at the checkout URL provided.
+
 ## Core Workflow
 
 ```bash
@@ -53,6 +55,18 @@ project -> feature -> task
 
 Every task belongs to a feature. Every feature belongs to a project. No orphans. The project is set automatically by `flowy init`.
 
+## Subscription Tiers
+
+Flowy requires an active subscription for all data operations.
+
+| Tier | Projects | Description |
+|------|----------|-------------|
+| `explorer` | Up to 10 | For individual developers |
+| `pro` | Unlimited | For power users |
+| `team` | Unlimited | For teams |
+
+After registration, complete payment at the checkout URL. Existing users can get a new checkout URL with `flowy billing checkout --tier <tier>`.
+
 ## Status Flow
 
 ```
@@ -104,6 +118,23 @@ flowy search "query" --type task --status draft --limit 10
 flowy tree <project-id> --depth 3     # Show full subtree
 ```
 
+### Setup
+```bash
+flowy setup remote --email <email> --tier <tier>  # Register (tier: explorer, pro, team)
+flowy setup local                                  # Self-hosted Docker server
+flowy whoami                                       # Show user info (includes grace period)
+```
+
+### Billing
+```bash
+flowy billing checkout --tier <tier>              # Get checkout URL for subscription
+```
+
+### API Key Management
+```bash
+flowy key rotate                                  # Revoke all keys and generate a new one
+```
+
 ## Validation Rules
 
 - **Title is required** and cannot be empty

package/src/commands/billing.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockGraphql: ReturnType<typeof vi.fn>
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  mockGraphql = vi.fn()
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+
+  vi.doMock('../util/client.ts', () => ({
+    graphql: mockGraphql,
+  }))
+
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('billing command', () => {
+  test('exports a command named "billing"', async () => {
+    const { billingCommand } = await import('./billing.ts')
+    expect(billingCommand.name()).toBe('billing')
+  })
+
+  test('has checkout subcommand', async () => {
+    const { billingCommand } = await import('./billing.ts')
+    const subcommandNames = billingCommand.commands.map((c) => c.name())
+    expect(subcommandNames).toContain('checkout')
+    expect(billingCommand.commands).toHaveLength(1)
+  })
+
+  test('checkout calls createCheckout mutation and outputs result', async () => {
+    const checkoutResult = { url: 'https://checkout.stripe.com/session_123' }
+    mockGraphql.mockResolvedValue({ createCheckout: checkoutResult })
+
+    const { billingCommand } = await import('./billing.ts')
+    await billingCommand.parseAsync(['checkout', '--tier', 'pro'], {
+      from: 'user',
+    })
+
+    expect(mockGraphql).toHaveBeenCalledWith(
+      expect.stringContaining('createCheckout'),
+      { tier: 'pro' },
+    )
+    expect(mockOutput).toHaveBeenCalledWith(checkoutResult)
+  })
+
+  test('checkout errors when --tier is not provided', async () => {
+    const { billingCommand } = await import('./billing.ts')
+
+    billingCommand.exitOverride()
+    billingCommand.configureOutput({ writeErr: () => {}, writeOut: () => {} })
+    for (const cmd of billingCommand.commands) {
+      cmd.exitOverride()
+      cmd.configureOutput({ writeErr: () => {}, writeOut: () => {} })
+    }
+
+    await expect(
+      billingCommand.parseAsync(['checkout'], { from: 'user' }),
+    ).rejects.toThrow('--tier')
+  })
+
+  test('checkout sends correct tier in mutation variables', async () => {
+    mockGraphql.mockResolvedValue({
+      createCheckout: { url: 'https://checkout.stripe.com/session_abc' },
+    })
+
+    const { billingCommand } = await import('./billing.ts')
+    await billingCommand.parseAsync(['checkout', '--tier', 'team'], {
+      from: 'user',
+    })
+
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    const [, variables] = mockGraphql.mock.calls[0]!
+    expect(variables).toEqual({ tier: 'team' })
+  })
+
+  test('checkout calls outputError on failure', async () => {
+    const error = new Error('Unauthorized')
+    mockGraphql.mockRejectedValue(error)
+
+    const { billingCommand } = await import('./billing.ts')
+    await billingCommand.parseAsync(['checkout', '--tier', 'explorer'], {
+      from: 'user',
+    })
+
+    expect(mockOutputError).toHaveBeenCalledWith(error)
+  })
+})

package/src/commands/billing.ts

@@ -0,0 +1,30 @@
+import { Command, Option } from 'commander'
+import { graphql } from '../util/client.ts'
+import { output, outputError } from '../util/format.ts'
+
+const checkoutCommand = new Command('checkout')
+  .description('Create a checkout session for a subscription tier')
+  .addOption(
+    new Option('--tier <tier>', 'Subscription tier')
+      .choices(['explorer', 'pro', 'team'])
+      .makeOptionMandatory(),
+  )
+  .action(async (opts: { tier: string }) => {
+    try {
+      const data = await graphql<{ createCheckout: { url: string } }>(
+        `mutation CreateCheckout($tier: String!) {
+          createCheckout(tier: $tier) {
+            url
+          }
+        }`,
+        { tier: opts.tier },
+      )
+      output(data.createCheckout)
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+export const billingCommand = new Command('billing')
+  .description('Billing and subscription management')
+  .addCommand(checkoutCommand)

package/src/commands/key.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockLoadConfig: ReturnType<typeof vi.fn>
+let mockSaveConfig: ReturnType<typeof vi.fn>
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  mockLoadConfig = vi.fn(() => ({
+    mode: 'saas',
+    apiUrl: 'https://flowy-ai.fly.dev/graphql',
+    apiKey: 'old-key',
+    client: { name: '' },
+    projects: {},
+  }))
+  mockSaveConfig = vi.fn()
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+
+  vi.doMock('../util/config.ts', () => ({
+    loadConfig: mockLoadConfig,
+    saveConfig: mockSaveConfig,
+  }))
+
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('key command', () => {
+  test('exports a command named "key"', async () => {
+    const { keyCommand } = await import('./key.ts')
+    expect(keyCommand.name()).toBe('key')
+  })
+
+  test('has rotate subcommand', async () => {
+    const { keyCommand } = await import('./key.ts')
+    const subcommandNames = keyCommand.commands.map((c) => c.name())
+    expect(subcommandNames).toContain('rotate')
+    expect(keyCommand.commands).toHaveLength(1)
+  })
+
+  test('rotate calls rotateApiKey mutation, saves new key to config, and outputs result', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      rotateApiKey: {
+        user: {
+          id: 'user_1',
+          email: 'test@example.com',
+          tier: 'free',
+          createdAt: '2025-01-01T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_new_key_456',
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+
+    const { keyCommand } = await import('./key.ts')
+    await keyCommand.parseAsync(['rotate'], { from: 'user' })
+
+    expect(mockGraphql).toHaveBeenCalledWith(
+      expect.stringContaining('rotateApiKey'),
+    )
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: 'flowy_new_key_456',
+      }),
+    )
+    expect(mockOutput).toHaveBeenCalledWith(
+      expect.objectContaining({
+        user: expect.objectContaining({ email: 'test@example.com' }),
+        apiKey: 'flowy_new_key_456',
+      }),
+    )
+  })
+
+  test('rotate saves the exact new apiKey to config', async () => {
+    const newKey = 'flowy_rotated_key_789'
+    const mockGraphql = vi.fn().mockResolvedValue({
+      rotateApiKey: {
+        user: {
+          id: 'user_1',
+          email: 'dev@example.com',
+          tier: 'pro',
+          createdAt: '2025-06-01T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: newKey,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+
+    const { keyCommand } = await import('./key.ts')
+    await keyCommand.parseAsync(['rotate'], { from: 'user' })
+
+    expect(mockSaveConfig).toHaveBeenCalledOnce()
+    const savedConfig = mockSaveConfig.mock.calls[0]![0]
+    expect(savedConfig.apiKey).toBe(newKey)
+    expect(savedConfig.apiKey).not.toBe('old-key')
+  })
+
+  test('rotate outputs error when mutation fails', async () => {
+    const mockGraphql = vi.fn().mockRejectedValue(new Error('Unauthorized'))
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+
+    const { keyCommand } = await import('./key.ts')
+    await keyCommand.parseAsync(['rotate'], { from: 'user' })
+
+    expect(mockOutputError).toHaveBeenCalledWith(expect.any(Error))
+    expect(mockSaveConfig).not.toHaveBeenCalled()
+    expect(mockOutput).not.toHaveBeenCalled()
+  })
+})

package/src/commands/key.ts

@@ -0,0 +1,41 @@
+import { Command } from 'commander'
+import { graphql } from '../util/client.ts'
+import { loadConfig, saveConfig } from '../util/config.ts'
+import { output, outputError } from '../util/format.ts'
+
+export const keyCommand = new Command('key').description('API key management')
+
+keyCommand
+  .command('rotate')
+  .description('Rotate API key')
+  .action(async () => {
+    try {
+      const data = await graphql<{
+        rotateApiKey: {
+          user: {
+            id: string
+            email: string
+            tier: string
+            createdAt: string
+            graceEndsAt: string | null
+          }
+          apiKey: string
+        }
+      }>(
+        `mutation RotateApiKey {
+          rotateApiKey {
+            user { id email tier createdAt graceEndsAt }
+            apiKey
+          }
+        }`,
+      )
+
+      const config = loadConfig()
+      config.apiKey = data.rotateApiKey.apiKey
+      saveConfig(config)
+
+      output(data.rotateApiKey)
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/project.ts

@@ -53,7 +53,7 @@ projectCommand
       )
       const project = data.nodes.find((n) => n.title === name)
       if (!project) {
-        throw new Error(`Project "${name}" not found`)
+        throw new Error(`Project "${name}" not found.`)
       }
       await setProject(project.id, project.title)
     } catch (error) {

package/src/commands/setup.test.ts

@@ -99,11 +99,92 @@ describe('setup command', () => {
     )
   })
 
+  test('setup remote requires --tier', async () => {
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['remote', '--email', 'test@example.com'], {
+      from: 'user',
+    })
+
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringContaining('--tier is required'),
+      }),
+    )
+  })
+
+  test('setup remote outputs error when registration fails', async () => {
+    const mockGraphql = vi
+      .fn()
+      .mockRejectedValue(new Error('Registration is temporarily closed.'))
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(
+      ['remote', '--email', 'test@example.com', '--tier', 'explorer'],
+      { from: 'user' },
+    )
+
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Registration is temporarily closed.',
+      }),
+    )
+    expect(mockSaveConfig).toHaveBeenCalledTimes(1)
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mode: 'remote',
+        apiUrl: 'https://flowy-ai.fly.dev/graphql',
+      }),
+    )
+  })
+
+  test('setup remote sends correct email and tier in mutation', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      register: {
+        user: {
+          id: 'user_1',
+          email: 'a@b.com',
+          tier: 'pro',
+          createdAt: '2026-01-01T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_key',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: Buffer.from(''),
+    })
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(
+      ['remote', '--email', 'a@b.com', '--tier', 'pro'],
+      { from: 'user' },
+    )
+
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    const [, variables] = mockGraphql.mock.calls[0]!
+    expect(variables).toEqual({ email: 'a@b.com', tier: 'pro' })
+  })
+
   test('setup remote registers, saves API key, and outputs result', async () => {
     const mockGraphql = vi.fn().mockResolvedValue({
       register: {
-        user: { id: 'user_1', email: 'test@example.com', tier: 'free' },
+        user: {
+          id: 'user_1',
+          email: 'test@example.com',
+          tier: 'explorer',
+          createdAt: '2026-03-30T00:00:00Z',
+          graceEndsAt: '2026-04-13T00:00:00Z',
+        },
         apiKey: 'flowy_test_key_123',
+        checkoutUrl: 'https://checkout.stripe.com/session_123',
       },
     })
     vi.doMock('../util/client.ts', () => ({
@@ -115,10 +196,15 @@ describe('setup command', () => {
     })
 
     const { setupCommand } = await import('./setup.ts')
-    await setupCommand.parseAsync(['remote', '--email', 'test@example.com'], {
-      from: 'user',
-    })
+    await setupCommand.parseAsync(
+      ['remote', '--email', 'test@example.com', '--tier', 'explorer'],
+      { from: 'user' },
+    )
 
+    expect(mockGraphql).toHaveBeenCalledWith(
+      expect.stringContaining('register(email: $email, tier: $tier)'),
+      { email: 'test@example.com', tier: 'explorer' },
+    )
     expect(mockSaveConfig).toHaveBeenCalledWith(
       expect.objectContaining({
         mode: 'remote',
@@ -127,8 +213,13 @@ describe('setup command', () => {
     )
     expect(mockOutput).toHaveBeenCalledWith(
       expect.objectContaining({
-        user: expect.objectContaining({ email: 'test@example.com' }),
+        user: expect.objectContaining({
+          email: 'test@example.com',
+          tier: 'explorer',
+          graceEndsAt: '2026-04-13T00:00:00Z',
+        }),
         apiKey: 'flowy_test_key_123',
+        checkoutUrl: 'https://checkout.stripe.com/session_123',
       }),
     )
   })

package/src/commands/setup.ts

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { resolve } from 'node:path'
-import { Command } from 'commander'
+import { Command, Option } from 'commander'
 import { loadConfig, saveConfig } from '../util/config.ts'
 import { output, outputError } from '../util/format.ts'
 
@@ -104,11 +104,21 @@ setupCommand
   .command('remote')
   .description('Connect to the hosted Flowy service')
   .option('--email <email>', 'Email address for registration')
+  .addOption(
+    new Option('--tier <tier>', 'Subscription tier').choices([
+      'explorer',
+      'pro',
+      'team',
+    ]),
+  )
   .action(async (opts) => {
     try {
       if (!opts.email) {
         throw new Error('--email is required for registration')
       }
+      if (!opts.tier) {
+        throw new Error('--tier is required for registration')
+      }
 
       const { graphql } = await import('../util/client.ts')
 
@@ -119,17 +129,25 @@ setupCommand
 
       const data = await graphql<{
         register: {
-          user: { id: string; email: string; tier: string }
+          user: {
+            id: string
+            email: string
+            tier: string
+            createdAt: string
+            graceEndsAt: string
+          }
           apiKey: string
+          checkoutUrl: string
         }
       }>(
-        `mutation Register($email: String!) {
-          register(email: $email) {
-            user { id email tier }
+        `mutation Register($email: String!, $tier: String!) {
+          register(email: $email, tier: $tier) {
+            user { id email tier createdAt graceEndsAt }
             apiKey
+            checkoutUrl
           }
         }`,
-        { email: opts.email },
+        { email: opts.email, tier: opts.tier },
       )
 
       config.apiKey = data.register.apiKey

package/src/commands/whoami.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockGraphql: ReturnType<typeof vi.fn>
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+  mockGraphql = vi.fn().mockResolvedValue({
+    whoami: {
+      id: 'user_1',
+      email: 'test@example.com',
+      tier: 'free',
+      createdAt: '2026-01-01',
+      graceEndsAt: null,
+    },
+  })
+
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+
+  vi.doMock('../util/client.ts', () => ({
+    graphql: mockGraphql,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('whoami command', () => {
+  test('whoami outputs user data from query', async () => {
+    const userData = {
+      id: '1',
+      email: 'a@b.com',
+      tier: 'explorer',
+      createdAt: '2026-01-01',
+      graceEndsAt: null,
+    }
+    mockGraphql.mockResolvedValue({ whoami: userData })
+
+    const { whoamiCommand } = await import('./whoami.ts')
+    await whoamiCommand.parseAsync([], { from: 'user' })
+
+    expect(mockOutput).toHaveBeenCalledWith(userData)
+  })
+
+  test('whoami outputs error when query fails', async () => {
+    mockGraphql.mockRejectedValue(new Error('Auth required'))
+
+    const { whoamiCommand } = await import('./whoami.ts')
+    await whoamiCommand.parseAsync([], { from: 'user' })
+
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Auth required',
+      }),
+    )
+    expect(mockOutput).not.toHaveBeenCalled()
+  })
+
+  test('whoami queries graceEndsAt field', async () => {
+    const { whoamiCommand } = await import('./whoami.ts')
+    await whoamiCommand.parseAsync([], { from: 'user' })
+
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    const query = mockGraphql.mock.calls[0]?.[0] as string
+    expect(query).toContain('graceEndsAt')
+  })
+})

package/src/commands/whoami.ts

@@ -9,7 +9,7 @@ export const whoamiCommand = new Command('whoami')
       const data = await graphql<{ whoami: unknown }>(
         `query Whoami {
           whoami {
-            id email tier createdAt
+            id email tier createdAt graceEndsAt
           }
         }`,
       )

package/src/index.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test, vi } from 'vitest'
+
+vi.mock('./commands/approve.ts', () => ({
+  approveCommand: { name: () => 'approve' },
+}))
+vi.mock('./commands/client.ts', () => ({
+  clientCommand: { name: () => 'client' },
+}))
+vi.mock('./commands/feature.ts', () => ({
+  featureCommand: { name: () => 'feature' },
+}))
+vi.mock('./commands/init.ts', () => ({
+  initCommand: { name: () => 'init' },
+}))
+vi.mock('./commands/project.ts', () => ({
+  projectCommand: { name: () => 'project' },
+}))
+vi.mock('./commands/search.ts', () => ({
+  searchCommand: { name: () => 'search' },
+}))
+vi.mock('./commands/setup.ts', () => ({
+  setupCommand: { name: () => 'setup' },
+}))
+vi.mock('./commands/status.ts', () => ({
+  statusCommand: { name: () => 'status' },
+}))
+vi.mock('./commands/task.ts', () => ({
+  taskCommand: { name: () => 'task' },
+}))
+vi.mock('./commands/tree.ts', () => ({
+  treeCommand: { name: () => 'tree' },
+}))
+vi.mock('./commands/whoami.ts', () => ({
+  whoamiCommand: { name: () => 'whoami' },
+}))
+vi.mock('./commands/billing.ts', () => ({
+  billingCommand: { name: () => 'billing' },
+}))
+vi.mock('./commands/key.ts', () => ({
+  keyCommand: { name: () => 'key' },
+}))
+
+describe('index.ts command registration', () => {
+  test('registers billing and key commands', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { billingCommand } from './commands/billing.ts'",
+    )
+    expect(indexSource).toContain(
+      "import { keyCommand } from './commands/key.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(billingCommand)')
+    expect(indexSource).toContain('program.addCommand(keyCommand)')
+  })
+})

package/src/index.ts

@@ -12,9 +12,11 @@ const pkgPath = resolve(
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
 
 import { approveCommand } from './commands/approve.ts'
+import { billingCommand } from './commands/billing.ts'
 import { clientCommand } from './commands/client.ts'
 import { featureCommand } from './commands/feature.ts'
 import { initCommand } from './commands/init.ts'
+import { keyCommand } from './commands/key.ts'
 import { projectCommand } from './commands/project.ts'
 import { searchCommand } from './commands/search.ts'
 import { setupCommand } from './commands/setup.ts'
@@ -36,6 +38,8 @@ program.addCommand(featureCommand)
 program.addCommand(taskCommand)
 program.addCommand(statusCommand)
 program.addCommand(approveCommand)
+program.addCommand(billingCommand)
+program.addCommand(keyCommand)
 program.addCommand(searchCommand)
 program.addCommand(treeCommand)
 program.addCommand(whoamiCommand)

package/src/util/client.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+beforeEach(() => {
+  vi.doMock('./config.ts', () => ({
+    getConfig: () => ({
+      apiUrl: 'http://test/graphql',
+      apiKey: 'test-key',
+    }),
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('graphql client', () => {
+  test('returns data on successful response', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            data: { whoami: { id: '1' } },
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    const result = await graphql('query { whoami { id } }')
+    expect(result).toEqual({ whoami: { id: '1' } })
+  })
+
+  test('throws original server message for unknown error codes', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [
+              {
+                message: 'Something broke',
+                extensions: { code: 'UNKNOWN_CODE' },
+              },
+            ],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      'Something broke',
+    )
+  })
+
+  test('throws error message when extensions are absent', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [{ message: 'Auth required' }],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      'Auth required',
+    )
+  })
+
+  test('omits Authorization header when no apiKey configured', async () => {
+    vi.doMock('./config.ts', () => ({
+      getConfig: () => ({
+        apiUrl: 'http://test/graphql',
+        apiKey: '',
+      }),
+    }))
+
+    const mockFetch = vi.fn().mockResolvedValue({
+      json: () =>
+        Promise.resolve({
+          data: { whoami: { id: '1' } },
+        }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const { graphql } = await import('./client.ts')
+    await graphql('query { whoami { id } }')
+
+    const callHeaders = mockFetch.mock.calls[0]![1].headers
+    expect(callHeaders).not.toHaveProperty('Authorization')
+  })
+
+  test('throws on network error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('fetch failed')))
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      'fetch failed',
+    )
+  })
+
+  test('throws friendly message for SUBSCRIPTION_REQUIRED error code', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [
+              {
+                message: 'Active subscription required.',
+                extensions: { code: 'SUBSCRIPTION_REQUIRED' },
+              },
+            ],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      /flowy billing checkout/,
+    )
+  })
+
+  test('throws friendly message for SUBSCRIPTION_EXPIRED error code', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [
+              {
+                message: 'Subscription has expired.',
+                extensions: { code: 'SUBSCRIPTION_EXPIRED' },
+              },
+            ],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      /flowy billing checkout/,
+    )
+  })
+
+  test('throws friendly message for SUBSCRIPTION_SUSPENDED error code', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [
+              {
+                message: 'Subscription is suspended.',
+                extensions: { code: 'SUBSCRIPTION_SUSPENDED' },
+              },
+            ],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
+      /suspended.*contact support/,
+    )
+  })
+})

package/src/util/client.ts

@@ -22,11 +22,32 @@ export async function graphql<T = unknown>(
 
   const json = (await res.json()) as {
     data?: T
-    errors?: Array<{ message: string }>
+    errors?: Array<{ message: string; extensions?: { code?: string } }>
   }
 
   if (json.errors?.length) {
-    throw new Error(json.errors[0]?.message)
+    const error = json.errors[0]
+    const code = error?.extensions?.code
+
+    if (code === 'SUBSCRIPTION_REQUIRED') {
+      throw new Error(
+        'An active subscription is required. Run `flowy billing checkout` to subscribe.',
+      )
+    }
+
+    if (code === 'SUBSCRIPTION_EXPIRED') {
+      throw new Error(
+        'Your subscription has expired. Run `flowy billing checkout` to renew.',
+      )
+    }
+
+    if (code === 'SUBSCRIPTION_SUSPENDED') {
+      throw new Error(
+        'Your subscription is suspended. Please contact support to resolve this.',
+      )
+    }
+
+    throw new Error(error?.message)
   }
 
   return json.data as T