feat: add away status command (#79)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Scott Lovegrove <scott@ferretlabs.com>

Author: 3 people

README.md

@@ -74,6 +74,9 @@ tw conversation view <ref>         # view conversation messages
 tw msg view <ref>                  # view a conversation message
 tw search "keyword"                # search across workspace
 tw react thread <ref> 👍          # add reaction
+tw away                            # show away status
+tw away set vacation 2026-03-20    # set away until date
+tw away clear                      # clear away status
 ```
 
 References accept IDs (`123` or `id:123`), Twist URLs, or fuzzy names (for workspaces/users).

package-lock.json

@@ -47,7 +47,7 @@
         "dist"
     ],
     "dependencies": {
-        "@doist/twist-sdk": "2.0.2",
+        "@doist/twist-sdk": "2.1.0",
         "@pnpm/tabtab": "0.5.4",
         "chalk": "5.6.2",
         "commander": "14.0.3",

package.json

@@ -0,0 +1,197 @@
+import { TwistRequestError } from '@doist/twist-sdk'
+import { Command } from 'commander'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const apiMocks = vi.hoisted(() => ({
+    getSessionUser: vi.fn(),
+    getTwistClient: vi.fn(),
+    updateUser: vi.fn(),
+}))
+
+vi.mock('../lib/api.js', () => ({
+    getSessionUser: apiMocks.getSessionUser,
+    getTwistClient: apiMocks.getTwistClient,
+}))
+
+vi.mock('chalk')
+
+import { registerAwayCommand } from '../commands/away.js'
+
+function createProgram() {
+    const program = new Command()
+    program.exitOverride()
+    registerAwayCommand(program)
+    return program
+}
+
+describe('away', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        apiMocks.updateUser.mockResolvedValue({
+            id: 1,
+            name: 'Test User',
+            email: 'test@example.com',
+            awayMode: null,
+        })
+        apiMocks.getTwistClient.mockResolvedValue({
+            users: { update: apiMocks.updateUser },
+        })
+    })
+
+    describe('show', () => {
+        it('shows not away when awayMode is null', async () => {
+            apiMocks.getSessionUser.mockResolvedValue({
+                id: 1,
+                name: 'Test User',
+                awayMode: null,
+            })
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync(['node', 'tw', 'away'])
+
+            expect(logSpy).toHaveBeenCalledWith('Not away.')
+            logSpy.mockRestore()
+        })
+
+        it('shows away status when set', async () => {
+            apiMocks.getSessionUser.mockResolvedValue({
+                id: 1,
+                name: 'Test User',
+                awayMode: { type: 'vacation', dateFrom: '2026-03-10', dateTo: '2026-03-20' },
+            })
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync(['node', 'tw', 'away'])
+
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Vacation'))
+            logSpy.mockRestore()
+        })
+    })
+
+    describe('set', () => {
+        it('calls users.update with awayMode', async () => {
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync(['node', 'tw', 'away', 'set', 'vacation', '2026-03-20'])
+
+            expect(apiMocks.updateUser).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    awayMode: expect.objectContaining({
+                        type: 'vacation',
+                        dateTo: '2026-03-20',
+                    }),
+                }),
+            )
+            logSpy.mockRestore()
+        })
+
+        it('supports --from flag', async () => {
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync([
+                'node',
+                'tw',
+                'away',
+                'set',
+                'vacation',
+                '2026-03-20',
+                '--from',
+                '2026-03-15',
+            ])
+
+            expect(apiMocks.updateUser).toHaveBeenCalledWith({
+                awayMode: { type: 'vacation', dateFrom: '2026-03-15', dateTo: '2026-03-20' },
+            })
+            logSpy.mockRestore()
+        })
+
+        it('shows dry-run message', async () => {
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync([
+                'node',
+                'tw',
+                'away',
+                'set',
+                'vacation',
+                '2026-03-20',
+                '--dry-run',
+            ])
+
+            expect(apiMocks.updateUser).not.toHaveBeenCalled()
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Dry run'))
+            logSpy.mockRestore()
+        })
+
+        it('shows friendly error on insufficient scope (403)', async () => {
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
+                throw new Error('process.exit')
+            })
+            apiMocks.updateUser.mockRejectedValue(
+                new TwistRequestError('Request failed with status 403', 403, {
+                    error_code: 109,
+                    error_string: 'Insufficient scope provided: user:write',
+                }),
+            )
+            const program = createProgram()
+
+            await expect(
+                program.parseAsync(['node', 'tw', 'away', 'set', 'vacation', '2026-03-20']),
+            ).rejects.toThrow()
+
+            expect(errorSpy).toHaveBeenCalledWith(
+                expect.anything(),
+                'The away status feature requires additional permissions.',
+            )
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('tw auth login'))
+            errorSpy.mockRestore()
+            exitSpy.mockRestore()
+        })
+
+        it('rejects invalid away type', async () => {
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
+                throw new Error('process.exit')
+            })
+            const program = createProgram()
+
+            await expect(
+                program.parseAsync(['node', 'tw', 'away', 'set', 'invalid', '2026-03-20']),
+            ).rejects.toThrow()
+
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid away type'))
+            errorSpy.mockRestore()
+            exitSpy.mockRestore()
+        })
+    })
+
+    describe('clear', () => {
+        it('calls users.update with empty string awayMode to clear', async () => {
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync(['node', 'tw', 'away', 'clear'])
+
+            expect(apiMocks.updateUser).toHaveBeenCalledWith({ awayMode: '' })
+            expect(logSpy).toHaveBeenCalledWith('Away status cleared.')
+            logSpy.mockRestore()
+        })
+
+        it('shows dry-run message', async () => {
+            const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+            const program = createProgram()
+
+            await program.parseAsync(['node', 'tw', 'away', 'clear', '--dry-run'])
+
+            expect(apiMocks.updateUser).not.toHaveBeenCalled()
+            expect(logSpy).toHaveBeenCalledWith('Dry run: would clear away status')
+            logSpy.mockRestore()
+        })
+    })
+})

src/__tests__/away.test.ts

@@ -0,0 +1,158 @@
+import { AWAY_MODE_TYPES, type AwayModeType, TwistRequestError } from '@doist/twist-sdk'
+import chalk from 'chalk'
+import { Command } from 'commander'
+import { getSessionUser, getTwistClient } from '../lib/api.js'
+import type { MutationOptions, ViewOptions } from '../lib/options.js'
+import { colors, formatJson } from '../lib/output.js'
+
+type SetAwayOptions = ViewOptions & MutationOptions & { from?: string }
+
+function formatLocalDate(d: Date): string {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+function todayStr(): string {
+    return formatLocalDate(new Date())
+}
+
+function tomorrowStr(): string {
+    const d = new Date()
+    d.setDate(d.getDate() + 1)
+    return formatLocalDate(d)
+}
+
+function formatAwayType(type: string): string {
+    const labels: Record<string, string> = {
+        vacation: 'Vacation',
+        parental: 'Parental leave',
+        sickleave: 'Sick leave',
+        other: 'Away',
+    }
+    return labels[type] ?? type
+}
+
+async function showAwayStatus(options: ViewOptions): Promise<void> {
+    const user = await getSessionUser()
+
+    if (options.json) {
+        console.log(formatJson(user, 'user', options.full))
+        return
+    }
+
+    if (!user.awayMode) {
+        console.log('Not away.')
+        return
+    }
+
+    const { type, dateFrom, dateTo } = user.awayMode
+    console.log(chalk.bold(formatAwayType(type)))
+    console.log(`From:  ${colors.timestamp(dateFrom)}`)
+    console.log(`Until: ${colors.timestamp(dateTo)}`)
+}
+
+async function setAway(
+    type: string,
+    until: string | undefined,
+    options: SetAwayOptions,
+): Promise<void> {
+    if (!AWAY_MODE_TYPES.includes(type as AwayModeType)) {
+        console.error(`Invalid away type: ${type}. Use: ${AWAY_MODE_TYPES.join(', ')}`)
+        process.exit(1)
+    }
+
+    const dateFrom = options.from ?? todayStr()
+    const dateTo = until ?? tomorrowStr()
+
+    if (options.dryRun) {
+        console.log(
+            `Dry run: would set away to ${formatAwayType(type)} from ${dateFrom} until ${dateTo}`,
+        )
+        return
+    }
+
+    const client = await getTwistClient()
+    try {
+        const user = await client.users.update({
+            awayMode: { type: type as AwayModeType, dateFrom, dateTo },
+        })
+
+        if (options.json) {
+            console.log(formatJson(user, 'user', options.full))
+            return
+        }
+
+        console.log(`Set away: ${formatAwayType(type)} from ${dateFrom} until ${dateTo}`)
+    } catch (error) {
+        handleAwayError(error)
+    }
+}
+
+async function clearAway(options: MutationOptions & ViewOptions): Promise<void> {
+    if (options.dryRun) {
+        console.log('Dry run: would clear away status')
+        return
+    }
+
+    const client = await getTwistClient()
+    try {
+        const user = await client.users.update({ awayMode: '' as never })
+
+        if (options.json) {
+            console.log(formatJson(user, 'user', options.full))
+            return
+        }
+
+        console.log('Away status cleared.')
+    } catch (error) {
+        handleAwayError(error)
+    }
+}
+
+function isInsufficientScope(error: unknown): boolean {
+    if (!(error instanceof TwistRequestError)) return false
+    const data = error.responseData as { error_string?: string } | undefined
+    return (
+        error.httpStatusCode === 403 && data?.error_string?.includes('Insufficient scope') === true
+    )
+}
+
+function handleAwayError(error: unknown): never {
+    if (isInsufficientScope(error)) {
+        console.error(
+            chalk.red('Permission denied.'),
+            'The away status feature requires additional permissions.',
+        )
+        console.error(
+            `Run ${chalk.cyan('tw auth login')} to re-authenticate with the required scopes.`,
+        )
+        process.exit(1)
+    }
+    throw error
+}
+
+export function registerAwayCommand(program: Command): void {
+    const away = program
+        .command('away')
+        .description('Manage away status')
+        .option('--json', 'Output as JSON')
+        .option('--full', 'Include all fields in JSON output')
+        .action((options: ViewOptions) => showAwayStatus(options))
+
+    away.command('set <type> [until]')
+        .usage('<type> [until] [options]')
+        .description('Set away status (type: vacation, parental, sickleave, other)')
+        .option('--from <date>', 'Start date (YYYY-MM-DD, defaults to today)')
+        .option('--dry-run', 'Show what would happen without executing')
+        .option('--json', 'Output as JSON')
+        .option('--full', 'Include all fields in JSON output')
+        .action((type: string, until: string | undefined, options: SetAwayOptions) =>
+            setAway(type, until, options),
+        )
+
+    away.command('clear')
+        .description('Clear away status')
+        .option('--dry-run', 'Show what would happen without executing')
+        .option('--json', 'Output as JSON')
+        .option('--full', 'Include all fields in JSON output')
+        .action((options: MutationOptions & ViewOptions) => clearAway(options))
+}