add private API fallback for drafts and centralize Heroku auth inheroku-api-auth

Author: michaelmalave

README.md

@@ -48,6 +48,8 @@ heroku devcenter:pull https://devcenter.heroku.com/articles/article-slug
 
 This writes `article-slug.md` in the current directory: YAML front matter (`title`, `id`) then a blank line, then markdown body. You may edit the title and content, but **do not change the article `id`**.
 
+`pull` first requests the public `/articles/<slug>.json` endpoint. If that fails and you have a plain **`~/.netrc`** from **`heroku login`**, it **retries the same URL with Heroku API credentials**, then **`GET /api/v1/private/articles/<slug>.json`** (the same private API as `push`) so drafts and other non-public articles can load when your Dev Center account is authorized. Run **`heroku devcenter:pull <slug> --debug`** to print status and full JSON bodies for each attempt.
+
 Use `--force` (`-f`) to overwrite an existing file without prompting.
 
 ### Preview a local article

slowdb.md

@@ -0,0 +1,4 @@
+id: 2360
+title: SlowDB
+
+Test

src/commands/devcenter/pull.ts

@@ -6,7 +6,14 @@ import {stringify as stringifyYaml} from 'yaml'
 
 import {formatArticleNotFoundMessage} from '../../lib/article-not-found.js'
 import {DevcenterClient} from '../../lib/devcenter-client.js'
-import {articleApiPath, mdFilePath, slugFromArticleUrl} from '../../lib/paths.js'
+import {getHerokuApiToken} from '../../lib/heroku-api-auth.js'
+import {
+  articleApiPath,
+  getDevcenterBaseUrl,
+  mdFilePath,
+  privateArticleShowPath,
+  slugFromArticleUrl,
+} from '../../lib/paths.js'
 
 type ArticleJson = {
   content: string
@@ -24,6 +31,10 @@ export default class Pull extends Command {
   }
   static description = 'save a local copy of a Dev Center article'
   static flags = {
+    debug: Flags.boolean({
+      description:
+        'log HTTP status and response shape for public, authenticated public, and private API article fetch',
+    }),
     force: Flags.boolean({
       char: 'f',
       description: 'overwrite an existing local file without prompting',
@@ -41,9 +52,55 @@ export default class Pull extends Command {
       )
     }
 
+    const dbg = (message: string) => {
+      if (flags.debug) {
+        process.stdout.write(`devcenter: ${message}\n`)
+      }
+    }
+
     const client = new DevcenterClient()
-    const {body, ok} = await client.getJson<ArticleJson>(articleApiPath(slug))
-    const articleOk = ok && body?.slug === slug
+    const path = articleApiPath(slug)
+    dbg(`baseUrl=${getDevcenterBaseUrl()} path=${path} expectedSlug=${slug}`)
+
+    let {body, ok, status} = await client.getJson<ArticleJson>(path)
+    let articleOk = ok && body?.slug === slug
+    logArticleJsonFetch(dbg, {
+      expectedSlug: slug, label: 'no auth', path, res: {body, ok, status},
+    })
+
+    let token: string | undefined
+    try {
+      token = getHerokuApiToken()
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      dbg(`Heroku ~/.netrc token unavailable: ${msg}`)
+    }
+
+    if (!articleOk && token) {
+      dbg('retrying GET with Heroku ~/.netrc token (public JSON)')
+      const authed = await client.getJson<ArticleJson>(path, undefined, {token})
+      body = authed.body
+      ok = authed.ok
+      status = authed.status
+      articleOk = ok && body?.slug === slug
+      logArticleJsonFetch(dbg, {
+        expectedSlug: slug, label: 'authenticated public', path, res: authed,
+      })
+    }
+
+    if (!articleOk && token) {
+      const privatePath = privateArticleShowPath(slug)
+      dbg(`retrying GET private API ${privatePath}`)
+      const priv = await client.getJson<ArticleJson>(privatePath, undefined, {token})
+      body = priv.body
+      ok = priv.ok
+      status = priv.status
+      articleOk = ok && body?.slug === slug
+      logArticleJsonFetch(dbg, {
+        expectedSlug: slug, label: 'private API', path: privatePath, res: priv,
+      })
+    }
+
     if (!articleOk) {
       const msg = await formatArticleNotFoundMessage(client, slug)
       this.error(msg, {exit: 1})
@@ -69,3 +126,32 @@ export default class Pull extends Command {
     this.log(`"${metadata.title}" article saved as ${filePath}`)
   }
 }
+
+function logArticleJsonFetch(
+  dbg: (m: string) => void,
+  opts: {
+    expectedSlug: string
+    label: string
+    path: string
+    res: {body: ArticleJson; ok: boolean; status: number}
+  },
+): void {
+  const {expectedSlug, label, path, res} = opts
+  const {body, ok, status} = res
+  const slugPart = body?.slug === undefined ? '(missing)' : JSON.stringify(body.slug)
+  const titlePart
+    = body?.title === undefined ? '(missing)' : JSON.stringify(String(body.title).slice(0, 80))
+  dbg(`GET ${path} (${label}): status=${status} ok=${ok} body.slug=${slugPart} title=${titlePart}`)
+  dbg(`slugMatch=${String(body?.slug === expectedSlug)} (want ${JSON.stringify(expectedSlug)})`)
+  if (body && typeof body === 'object') {
+    dbg(`response keys: ${Object.keys(body as object).sort().join(', ')}`)
+    dbg('response body (full JSON):')
+    try {
+      for (const line of JSON.stringify(body, undefined, 2).split('\n')) {
+        dbg(`  ${line}`)
+      }
+    } catch {
+      dbg(`  (could not stringify body: ${String(body)})`)
+    }
+  }
+}

src/commands/devcenter/push.ts

@@ -5,7 +5,7 @@ import {stringify as stringifyYaml} from 'yaml'
 
 import {ArticleFile} from '../../lib/article-file.js'
 import {DevcenterClient} from '../../lib/devcenter-client.js'
-import {getHerokuNetrcToken} from '../../lib/netrc-token.js'
+import {getHerokuApiToken} from '../../lib/heroku-api-auth.js'
 import {mdFilePath} from '../../lib/paths.js'
 
 function hasValidationErrors(body: unknown): boolean {
@@ -59,7 +59,7 @@ export default class Push extends Command {
 
     let token: string
     try {
-      token = getHerokuNetrcToken()
+      token = getHerokuApiToken()
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
       this.error(message, {exit: 1})

src/lib/devcenter-client.ts

@@ -2,6 +2,7 @@ import * as http from 'node:http'
 import * as https from 'node:https'
 import {URL} from 'node:url'
 
+import {basicAuthHeaders} from './heroku-api-auth.js'
 import {
   brokenLinkChecksPath,
   getDevcenterBaseUrl,
@@ -65,13 +66,12 @@ export class DevcenterClient {
     token: string,
     params: Record<string, string>,
   ): Promise<{body: unknown; ok: boolean; status: number;}> {
-    const auth = Buffer.from(token).toString('base64')
     const body = new URLSearchParams(params).toString()
     const res = await nodeRequest(method, this.url(path), {
       body,
       headers: {
         ...DEFAULT_HEADERS,
-        Authorization: `Basic ${auth}`,
+        ...basicAuthHeaders(token),
         'Content-Length': String(Buffer.byteLength(body)),
         'Content-Type': 'application/x-www-form-urlencoded',
       },
@@ -92,15 +92,24 @@ export class DevcenterClient {
     return this.authForm('POST', brokenLinkChecksPath(), token, {content})
   }
 
-  async getJson<T>(path: string, query?: Record<string, string>): Promise<{body: T; ok: boolean; status: number;}> {
+  async getJson<T>(
+    path: string,
+    query?: Record<string, string>,
+    options?: {token?: string},
+  ): Promise<{body: T; ok: boolean; status: number;}> {
     const u = new URL(this.url(path))
     if (query) {
       for (const [k, v] of Object.entries(query)) {
         u.searchParams.set(k, v)
       }
     }
 
-    const res = await nodeRequest('GET', u.toString(), {headers: {...DEFAULT_HEADERS}})
+    const headers: Record<string, string> = {...DEFAULT_HEADERS}
+    if (options?.token) {
+      Object.assign(headers, basicAuthHeaders(options.token))
+    }
+
+    const res = await nodeRequest('GET', u.toString(), {headers})
     let parsed: T
     try {
       parsed = JSON.parse(res.body || '{}') as T

src/lib/netrc-token.ts src/lib/heroku-api-auth.tssrc/lib/netrc-token.ts renamed to src/lib/heroku-api-auth.ts

@@ -4,10 +4,10 @@ import {homedir} from 'node:os'
 import {join} from 'node:path'
 
 /**
- * Returns the Heroku API token from ~/.netrc (same source as the legacy Ruby CLI).
- * Encrypted ~/.netrc.gpg is not supported; use a plain netrc or `heroku login`.
+ * Heroku API token from `~/.netrc` (`api.heroku.com`), same source as `heroku login`.
+ * Encrypted `~/.netrc.gpg` is not supported.
  */
-export function getHerokuNetrcToken(): string {
+export function getHerokuApiToken(): string {
   const home = homedir()
   const gpgPath = join(home, '.netrc.gpg')
   const plainPath = join(home, '.netrc')
@@ -28,3 +28,13 @@ export function getHerokuNetrcToken(): string {
 
   return token
 }
+
+/** `Authorization` header value Dev Center private APIs expect (matches legacy CLI behavior). */
+export function basicAuthHeaderValue(token: string): string {
+  const encoded = Buffer.from(token).toString('base64')
+  return `Basic ${encoded}`
+}
+
+export function basicAuthHeaders(token: string): Record<string, string> {
+  return {Authorization: basicAuthHeaderValue(token)}
+}

src/lib/paths.ts

@@ -24,6 +24,11 @@ export function updateArticlePath(id: number | string): string {
   return `/api/v1/private/articles/${id}.json`
 }
 
+/** Private CMS show by numeric id or slug (same path segment as `update`). */
+export function privateArticleShowPath(slugOrId: string): string {
+  return `/api/v1/private/articles/${encodeURIComponent(slugOrId)}.json`
+}
+
 export function brokenLinkChecksPath(): string {
   return '/api/v1/private/broken-link-checks.json'
 }

test/commands/pull.test.ts

@@ -8,13 +8,21 @@ import {join} from 'node:path'
 
 import Pull from '../../src/commands/devcenter/pull.js'
 import {runCommand} from '../helpers/run-command.js'
+import {
+  applyHomeEnv, type HomeEnvSnapshot, setHomeDirForTests, snapshotHomeEnv,
+} from '../helpers/test-home-env.js'
 
 describe('devcenter:pull', function () {
   let workDir: string
+  let homeEnv: HomeEnvSnapshot
+  let noNetrcHome: string
   let previousArticleCwd: string | undefined
   let previousTestConfirm: string | undefined
 
   beforeEach(function () {
+    homeEnv = snapshotHomeEnv()
+    noNetrcHome = mkdtempSync(join(tmpdir(), 'devcenter-pull-home-'))
+    setHomeDirForTests(noNetrcHome)
     workDir = mkdtempSync(join(tmpdir(), 'devcenter-pull-'))
     previousArticleCwd = process.env.DEVCENTER_CLI_CWD
     previousTestConfirm = process.env.DEVCENTER_CLI_TEST_CONFIRM
@@ -30,13 +38,15 @@ describe('devcenter:pull', function () {
     }
 
     nock.cleanAll()
+    applyHomeEnv(homeEnv)
     if (previousArticleCwd === undefined) {
       delete process.env.DEVCENTER_CLI_CWD
     } else {
       process.env.DEVCENTER_CLI_CWD = previousArticleCwd
     }
 
     rmSync(workDir, {recursive: true})
+    rmSync(noNetrcHome, {recursive: true})
   })
 
   it('writes a local markdown file from the Dev Center API', async function () {
@@ -73,6 +83,64 @@ describe('devcenter:pull', function () {
     expect(error?.message).to.contain('Please provide an article slug')
   })
 
+  it('retries with netrc auth when the public JSON request fails', async function () {
+    const token = 'fake-pull-token'
+    writeFileSync(
+      join(noNetrcHome, '.netrc'),
+      `machine api.heroku.com
+login t@t.com
+password ${token}
+`,
+      'utf8',
+    )
+
+    nock('https://devcenter.heroku.com').get('/articles/draftish.json').reply(404, {})
+    nock('https://devcenter.heroku.com', {
+      reqheaders: {authorization: `Basic ${Buffer.from(token).toString('base64')}`},
+    })
+    .get('/articles/draftish.json')
+    .reply(200, {
+      content: 'Draft **body**.',
+      id: 99,
+      slug: 'draftish',
+      title: 'Draft Title',
+    })
+
+    const {error} = await runCommand(Pull, ['draftish', '--force'])
+    expect(error).to.equal(undefined)
+    expect(readFileSync(join(workDir, 'draftish.md'), 'utf8')).to.contain('Draft **body**.')
+  })
+
+  it('falls back to private API when public JSON stays unavailable', async function () {
+    const token = 'fake-pull-token'
+    const auth = {authorization: `Basic ${Buffer.from(token).toString('base64')}`}
+    writeFileSync(
+      join(noNetrcHome, '.netrc'),
+      `machine api.heroku.com
+login t@t.com
+password ${token}
+`,
+      'utf8',
+    )
+
+    nock('https://devcenter.heroku.com').get('/articles/private-only.json').reply(401, {error: 'Authentication required'})
+    nock('https://devcenter.heroku.com', {reqheaders: auth})
+    .get('/articles/private-only.json')
+    .reply(401, {error: 'Authentication required'})
+    nock('https://devcenter.heroku.com', {reqheaders: auth})
+    .get('/api/v1/private/articles/private-only.json')
+    .reply(200, {
+      content: 'From **private** API.',
+      id: 42,
+      slug: 'private-only',
+      title: 'Private Only Title',
+    })
+
+    const {error} = await runCommand(Pull, ['private-only', '--force'])
+    expect(error).to.equal(undefined)
+    expect(readFileSync(join(workDir, 'private-only.md'), 'utf8')).to.contain('From **private** API.')
+  })
+
   it('does not overwrite when user declines the prompt', async function () {
     writeFileSync(join(workDir, 'keep.md'), 'title: Old\nid: 1\n\nold', 'utf8')
     nock('https://devcenter.heroku.com')

test/unit/devcenter-client.test.ts

@@ -27,6 +27,21 @@ describe('DevcenterClient', function () {
     expect(res.notFound).to.equal(true)
   })
 
+  it('getJson sends Authorization when token is passed', async function () {
+    nock('https://devcenter.heroku.com', {
+      reqheaders: {authorization: `Basic ${Buffer.from('secret').toString('base64')}`},
+    })
+    .get('/articles/z.json')
+    .reply(200, {
+      content: 'x', id: 1, slug: 'z', title: 'Z',
+    })
+
+    const client = new DevcenterClient()
+    const res = await client.getJson('/articles/z.json', undefined, {token: 'secret'})
+    expect(res.ok).to.equal(true)
+    expect((res.body as {slug?: string}).slug).to.equal('z')
+  })
+
   it('getJson parses query params and tolerates invalid JSON body', async function () {
     nock('https://devcenter.heroku.com')
     .get('/articles/x.json')