fix(hc): resolve www.todoist.com marketing article URLs (#310)

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

Author: scottlovegrove

skills/todoist-cli/SKILL.md

@@ -247,9 +247,10 @@ td reminder location get id:456
 td hc
 td hc --help
 td hc locale --set-default pt-br
+td hc view https://www.todoist.com/help/articles/introduction-to-filters-V98wIH
 ```
 
-`td hc` queries the Todoist online Help Center. Run `td hc --help` for locale discovery, article search, and article viewing details. `td hc locale --set-default <locale>` persists a preferred locale in `~/.config/todoist-cli/config.json` under `hc.defaultLocale`; the `--locale` flag on individual subcommands still overrides it.
+`td hc` queries the Todoist online Help Center. Run `td hc --help` for locale discovery, article search, and article viewing details. `td hc locale --set-default <locale>` persists a preferred locale in `~/.config/todoist-cli/config.json` under `hc.defaultLocale`; the `--locale` flag on individual subcommands still overrides it. `td hc view` accepts `id:N`, raw numeric article IDs, `get.todoist.help` URLs, and public `www.todoist.com/help/articles/...` marketing URLs (resolved to the underlying Zendesk article via slug search).
 
 ### Templates
 ```bash

src/commands/hc/hc.test.ts

@@ -259,6 +259,180 @@ describe('hc command', () => {
         expect(fetchSpy).not.toHaveBeenCalled()
     })
 
+    it('opens the marketing URL directly in --browser mode without resolving', async () => {
+        const program = createProgram()
+        await program.parseAsync([
+            'node',
+            'td',
+            'hc',
+            'view',
+            'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+            '--browser',
+        ])
+
+        expect(openInBrowser).toHaveBeenCalledWith(
+            'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+        )
+        expect(fetchSpy).not.toHaveBeenCalled()
+    })
+
+    it('resolves a www.todoist.com marketing URL via search and fetches the article', async () => {
+        fetchSpy
+            .mockResolvedValueOnce(
+                createJsonResponse({
+                    count: 2,
+                    results: [
+                        {
+                            id: 26646901023644,
+                            title: 'Todoist glossary',
+                            html_url:
+                                'https://get.todoist.help/hc/en-us/articles/26646901023644-Todoist-glossary',
+                        },
+                        {
+                            id: 205248842,
+                            title: 'Introduction to filters',
+                            html_url:
+                                'https://get.todoist.help/hc/en-us/articles/205248842-Introduction-to-filters',
+                        },
+                    ],
+                }),
+            )
+            .mockResolvedValueOnce(
+                createJsonResponse({
+                    article: {
+                        id: 205248842,
+                        title: 'Introduction to filters',
+                        html_url:
+                            'https://get.todoist.help/hc/en-us/articles/205248842-Introduction-to-filters',
+                        body: '<p>Filters help you...</p>',
+                    },
+                }),
+            )
+
+        const program = createProgram()
+        await program.parseAsync([
+            'node',
+            'td',
+            'hc',
+            'view',
+            'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+        ])
+
+        expect(fetchSpy).toHaveBeenCalledTimes(2)
+        expect(String(fetchSpy.mock.calls[0][0])).toContain(
+            '/api/v2/help_center/articles/search?query=introduction-to-filters-V98wIH&locale=en-us&per_page=10',
+        )
+        expect(fetchSpy.mock.calls[1][0]).toBe(
+            'https://todoist.zendesk.com/api/v2/help_center/en-us/articles/205248842',
+        )
+
+        const output = consoleSpy.mock.calls[0][0] as string
+        expect(output).toContain('# Introduction to filters')
+        expect(output).toContain('Filters help you')
+    })
+
+    it('searches in en-us when an English marketing URL is pasted with a non-English default locale', async () => {
+        mockReadConfig.mockResolvedValue({ hc: { defaultLocale: 'pt-br' } })
+        fetchSpy
+            .mockResolvedValueOnce(
+                createJsonResponse({
+                    count: 1,
+                    results: [
+                        {
+                            id: 205248842,
+                            title: 'Introduction to filters',
+                            html_url:
+                                'https://get.todoist.help/hc/en-us/articles/205248842-Introduction-to-filters',
+                        },
+                    ],
+                }),
+            )
+            .mockResolvedValueOnce(
+                createJsonResponse({
+                    article: {
+                        id: 205248842,
+                        title: 'Introdução aos filtros',
+                        html_url:
+                            'https://get.todoist.help/hc/pt-br/articles/205248842-Introducao-aos-filtros',
+                        body: '<p>Filtros</p>',
+                    },
+                }),
+            )
+
+        const program = createProgram()
+        await program.parseAsync([
+            'node',
+            'td',
+            'hc',
+            'view',
+            'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+        ])
+
+        expect(String(fetchSpy.mock.calls[0][0])).toContain('locale=en-us')
+        expect(fetchSpy.mock.calls[1][0]).toBe(
+            'https://todoist.zendesk.com/api/v2/help_center/pt-br/articles/205248842',
+        )
+    })
+
+    it('opens the resolved zendesk URL once when --browser is combined with --locale on a marketing URL', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            createJsonResponse({
+                count: 1,
+                results: [
+                    {
+                        id: 205248842,
+                        title: 'Introduction to filters',
+                        html_url:
+                            'https://get.todoist.help/hc/en-us/articles/205248842-Introduction-to-filters',
+                    },
+                ],
+            }),
+        )
+
+        const program = createProgram()
+        await program.parseAsync([
+            'node',
+            'td',
+            'hc',
+            'view',
+            'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+            '--browser',
+            '--locale',
+            'fr',
+        ])
+
+        expect(fetchSpy).toHaveBeenCalledTimes(1)
+        expect(openInBrowser).toHaveBeenCalledWith(
+            'https://get.todoist.help/hc/en-us/articles/205248842-Introduction-to-filters',
+        )
+    })
+
+    it('errors when the marketing URL slug cannot be matched', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            createJsonResponse({
+                count: 1,
+                results: [
+                    {
+                        id: 999,
+                        title: 'Something else',
+                        html_url: 'https://get.todoist.help/hc/en-us/articles/999-Something-else',
+                    },
+                ],
+            }),
+        )
+
+        const program = createProgram()
+        await expect(
+            program.parseAsync([
+                'node',
+                'td',
+                'hc',
+                'view',
+                'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+            ]),
+        ).rejects.toMatchObject({ code: 'NOT_FOUND' })
+    })
+
     it('outputs the raw HTML body with --html', async () => {
         const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
         fetchSpy.mockResolvedValue(

src/commands/hc/index.ts

@@ -22,10 +22,11 @@ Examples:
   td hc view id:360000269065
   td hc view 360000269065
   td hc view https://get.todoist.help/hc/en-us/articles/360000269065
+  td hc view https://www.todoist.com/help/articles/introduction-to-filters-V98wIH
 
 Notes:
   search prints real Help Center article IDs
-  view accepts id:N, raw article IDs, and Help Center URLs`,
+  view accepts id:N, raw article IDs, get.todoist.help URLs, and www.todoist.com/help/articles/... URLs`,
         )
 
     hc.command('locales')

src/commands/hc/view.ts

@@ -5,6 +5,7 @@ import {
     formatHelpCenterArticleMarkdown,
     getHelpCenterArticle,
     resolveHelpCenterRef,
+    resolveMarketingArticleId,
 } from '../../lib/help-center.js'
 import { renderMarkdown } from '../../lib/markdown.js'
 import { withSpinner } from '../../lib/spinner.js'
@@ -40,9 +41,26 @@ export async function viewHelpCenterArticle(
         return
     }
 
+    let articleId: string
+    if (resolved.kind === 'marketing') {
+        const { marketingSlug, urlLocale } = resolved
+        const resolvedMarketing = await withSpinner(
+            { text: 'Resolving Help Center article...', color: 'blue' },
+            () => resolveMarketingArticleId(marketingSlug, urlLocale),
+        )
+        articleId = resolvedMarketing.articleId
+
+        if (options.browser) {
+            await openInBrowser(resolvedMarketing.htmlUrl)
+            return
+        }
+    } else {
+        articleId = resolved.articleId
+    }
+
     const article = await withSpinner(
         { text: 'Loading Help Center article...', color: 'blue' },
-        () => getHelpCenterArticle(resolved.articleId, { locale: resolved.locale }),
+        () => getHelpCenterArticle(articleId, { locale: resolved.locale }),
     )
 
     if (options.browser) {

src/lib/help-center.test.ts

@@ -33,6 +33,7 @@ describe('help center helpers', () => {
 
     it('resolves an explicit id: ref', () => {
         expect(resolveHelpCenterRef('id:360000269065')).toEqual({
+            kind: 'article',
             articleId: '360000269065',
             locale: 'en-us',
             source: 'id',
@@ -41,6 +42,7 @@ describe('help center helpers', () => {
 
     it('resolves a raw numeric article id', () => {
         expect(resolveHelpCenterRef('205348301')).toEqual({
+            kind: 'article',
             articleId: '205348301',
             locale: 'en-us',
             source: 'id',
@@ -53,6 +55,7 @@ describe('help center helpers', () => {
                 'https://get.todoist.help/hc/en-us/articles/360000269065-manage-your-notifications',
             ),
         ).toEqual({
+            kind: 'article',
             articleId: '360000269065',
             htmlUrl:
                 'https://get.todoist.help/hc/en-us/articles/360000269065-manage-your-notifications',
@@ -66,4 +69,45 @@ describe('help center helpers', () => {
             'Invalid Help Center reference "notifications".',
         )
     })
+
+    it('flags a www.todoist.com marketing URL for slug resolution', () => {
+        expect(
+            resolveHelpCenterRef(
+                'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+            ),
+        ).toEqual({
+            kind: 'marketing',
+            marketingSlug: 'introduction-to-filters-V98wIH',
+            urlLocale: 'en-us',
+            locale: 'en-us',
+            htmlUrl: 'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+            source: 'url',
+        })
+    })
+
+    it('extracts the URL locale from a localized marketing URL', () => {
+        expect(
+            resolveHelpCenterRef(
+                'https://www.todoist.com/de/help/articles/einfuehrung-in-filter-V98wIH',
+            ),
+        ).toMatchObject({
+            kind: 'marketing',
+            urlLocale: 'de',
+            locale: 'en-us',
+        })
+    })
+
+    it('honours an explicit locale on a marketing URL while preserving the URL locale', () => {
+        expect(
+            resolveHelpCenterRef(
+                'https://www.todoist.com/help/articles/introduction-to-filters-V98wIH',
+                { locale: 'pt-br' },
+            ),
+        ).toMatchObject({
+            kind: 'marketing',
+            marketingSlug: 'introduction-to-filters-V98wIH',
+            urlLocale: 'en-us',
+            locale: 'pt-br',
+        })
+    })
 })