Google Docs | CreateHeader type value

[xgalen]

Please make sure you have searched for information in the following guides.

• Search the issues already opened: https://github.com/GoogleCloudPlatform/google-cloud-node/issues
• Check our Troubleshooting guide: https://googlecloudplatform.github.io/google-cloud-node/#/docs/guides/troubleshooting
• Check our FAQ: https://googlecloudplatform.github.io/google-cloud-node/#/docs/guides/faq
• Check our libraries HOW-TO: https://github.com/googleapis/gax-nodejs/blob/main/client-libraries.md
• Check out our authentication guide: https://github.com/googleapis/google-auth-library-nodejs
• Check out handwritten samples for many of our APIs: https://github.com/GoogleCloudPlatform/nodejs-docs-samples

Documentation Request

Hi,

I am trying to create a Google Docs with this library and I am not able to discover what other values (more than DEFAULT: ) I can use to generate a "First Page Header", like you can do in Google Docs using the UI.

This is the type field I refer to:

google-api-nodejs-client/src/apis/docs/v1.ts

Line 345 in 05b1db8

type?: string | null;

There is a firstPageHeaderId but I am not able to receive anything:

google-api-nodejs-client/src/apis/docs/v1.ts

Line 667 in 05b1db8

firstPageHeaderId?: string | null;

I share a small test to reproduce the issue. Of course here I am using DEFAULT because I have tried several values just in case but none worked:

import { google } from 'googleapis'

async function main() {
  // 1. Setup Auth
  const credentialsJson = process.env.GOOGLE_SERVICE_ACCOUNT_KEY
  if (!credentialsJson) {
    console.error('Error: GOOGLE_SERVICE_ACCOUNT_KEY environment variable is required.')
    process.exit(1)
  }

  const credentials = JSON.parse(credentialsJson)
  const auth = new google.auth.JWT({
    email: credentials.client_email,
    key: credentials.private_key,
    scopes: ['https://www.googleapis.com/auth/documents', 'https://www.googleapis.com/auth/drive'],
    subject: credentials.subject, // Optional impersonation
  })

  const docs = google.docs({ version: 'v1', auth })
  const drive = google.drive({ version: 'v3', auth })

  console.log('1. Creating a blank document...')
  const createRes = await docs.documents.create({ requestBody: { title: 'API Issue Reproduction Doc' } })
  const documentId = createRes.data.documentId!
  console.log(`   Created Document ID: ${documentId}\n`)

  try {
    // 2. Enable "Different First Page Header"
    console.log('2. Enabling "useFirstPageHeaderFooter" via UpdateDocumentStyle...')
    await docs.documents.batchUpdate({
      documentId,
      requestBody: {
        requests: [
          {
            updateDocumentStyle: {
              documentStyle: { useFirstPageHeaderFooter: true },
              fields: 'useFirstPageHeaderFooter',
            },
          },
        ],
      },
    })

    // 3. Attempt to create a header
    console.log('3. Calling CreateHeaderRequest (type: "DEFAULT")...')
    // Note: The API throws an error if we try to send 'FIRST_PAGE' or 'FIRST_PAGE_HEADER'.
    await docs.documents.batchUpdate({
      documentId,
      requestBody: {
        requests: [
          {
            createHeader: {
              type: 'DEFAULT',
            },
          },
        ],
      },
    })

    // 4. Inspect the result
    console.log('4. Fetching document to inspect header IDs...')
    const doc = await docs.documents.get({ documentId })
    const style = doc.data.documentStyle

    console.log('\n--- RESULTS ---')
    console.log(`useFirstPageHeaderFooter: ${style?.useFirstPageHeaderFooter}`)
    console.log(`defaultHeaderId (Pages 2+): ${style?.defaultHeaderId}  <-- Created Successfully`)
    console.log(`firstPageHeaderId (Page 1): ${style?.firstPageHeaderId}  <-- MISSING / UNDEFINED`)
    console.log('-----------------')

    if (!style?.firstPageHeaderId) {
      console.log('\nFAIL: Cannot write to First Page Header because its ID does not exist.')
      console.log('      There is no API method to force its creation.')
    }

  } catch (error: any) {
    console.error('An error occurred:', error.message)
  } finally {
    // Cleanup
    console.log(`\nCleaning up: Deleting document ${documentId}...`)
    await drive.files.delete({ fileId: documentId })
  }
}

main()

I have created this like a Documentation Request in case there are some hidden values I can't find but maybe it is because the API does not allow to do anything else and this has to be a "Feature request".

Thanks for your attention and help in advance!

[feywind]

@xgalen Thanks for the report. It looks like this part of the API is open-ended... same as you quoted above:

    /**
     * The type of header to create.
     */
    type?: string | null;

Our flow is to convert this to a discussion, since the client library itself isn't broken, but we'd also recommend entering an issue on the tracker for the service. (Sorry, not a very satisfying answer, I know, but they'd have more info.)