[Bug]: Issues with TypeScript types for video.startArchive

[pebergia]

Node Version

22.x

Platform

Mac (Apple Silcon)

SDK Version

3.29.0

Code Sample

const startTimestamp = Date.now();
const composedTag = `composed-${startTimestamp}`;
const individualTag = `individual-${startTimestamp}`;
const trimmedArchiveName = archiveName?.trim();

const defaultOptions: Partial<ArchiveOptions> = {
  hasAudio,
  hasVideo,
  hasTranscription,
  transcriptionProperties: {
    hasSummary: true,
  },
};

const startedArchives: (SingleArchiveResponse & {
  multiArchiveTag?: string;
})[] = [];

try {
  const composedArchive = await vonage.video.startArchive(sessionId, {
    ...defaultOptions,
    outputMode: ArchiveOutputMode.COMPOSED,
    ...(trimmedArchiveName ? { name: `${trimmedArchiveName}-composed` } : {}),
    ...{ multiArchiveTag: composedTag },
  });
  startedArchives.push(composedArchive);

  const individualArchive = await vonage.video.startArchive(sessionId, {
    ...defaultOptions,
    outputMode: ArchiveOutputMode.INDIVIDUAL,
    ...(trimmedArchiveName
      ? { name: `${trimmedArchiveName}-individual` }
      : {}),
    ...{ multiArchiveTag: individualTag },
  });
  startedArchives.push(individualArchive);

  return sendJson(res, 200, {
    sessionId,
    startedAt: new Date(startTimestamp).toISOString(),
    archives: startedArchives.map((item) =>
      mapArchiveSummary(item, item.multiArchiveTag),
    ),
  });
} catch (error) {
  for (const startedArchive of startedArchives) {
    try {
      await vonage.video.stopArchive(startedArchive.id);
    } catch (stopError) {
      console.error(
        "Failed to rollback partially started archive:",
        stopError,
      );
    }
  }

  console.error("error starting archive: ", error);

  return sendJson(res, 500, {
    error: getErrorMessage(error, "Failed to start archives."),
  });
}

Expected Behavior

• I would expect to easily use multiArchiveTag in typescript (without extending interface or casting types with any)
• I want to use transcription related arguments as the types say exist

Actual Behavior

Quick summary:

• Type error without casting when trying to use multiArchiveTag with vonage.startArchive
• 400 bad request error when using hasTranscription or transcriptionProperties options when starting an archive.

Longer one:

I've recently been testing archiving videos and I was going through this bit of documentation:

https://developer.vonage.com/en/video/guides/archiving/overview#simultaneous-archive-recordings

I want to do a composed and individual on the same session and noticed multiArchiveTag isn't in the TypeScript interface for ArchiveOptions (nor the response for archive related APIs).

It would be nice to have this option within the types and to note its purpose.

I was also trying to use the transcription related arguments, but I kept getting 400 bad request errors when I tried any of those. I saw on the related doc page it isn't supported by the sdk, only the rest API, which is confusing cause the TypeScript types has those options (hasTranscription and transcriptionProperties). I have confirmed that without the transcription options, I can archive and view those files in my vonage account.

[pebergia]

Oh I also noticed I'm in Canada at the moment and I see under transcription is a note that transcription is 'Based on requirement' but I am usually in the USA (so maybe that explains those options, but I'm unsure).

[manchuck]

@pebergia, can you run this in debug mode? DEBUG=*vonage* node .... That will output the requests and responses the SDK makes and receives.

Note: When you run this, it will output the private key along with the JWT token used. Please redact that information when sharing. We plan to add redactions.

[pebergia]

Hey @manchuck , thanks for the reply. I just realized that the composed archive type doesn't support transcripts and when I only included the options with the individual archive things worked. I think if the error had something about an unsupported param that would be helpful.

This was the response though for the composed with the transcription param:

vonage:server-client Request prepared {
  url: 'https://video.api.vonage.com/v2/project/74346f44-9448-42bc-91e2-19566a85e36b/archive',
  method: 'POST',
  type: 'application/json',
  data: {
    sessionId: 'REDACTED',
    hasAudio: true,
    hasVideo: true,
    hasTranscription: true,
    outputMode: 'composed',
    name: 'test3-composed',
    multiArchiveTag: 'composed-1787067664466'
  },
  headers: {
    'user-agent': '@vonage/server-sdk/3.0.0, node/22.23.2,',
    'content-type': 'application/json',
    Authorization: REDACTED
  }
} +4ms
  vonage:server-client Sending request {
  url: 'https://video.api.vonage.com/v2/project/74346f44-9448-42bc-91e2-19566a85e36b/archive',
  method: 'POST',
  headers: {
    'user-agent': '@vonage/server-sdk/3.0.0, node/22.23.2,',
    'content-type': 'application/json',
    Authorization: REDACTED
  },
  body: '{"sessionId":"REDACTED","hasAudio":true,"hasVideo":true,"hasTranscription":true,"outputMode":"composed","name":"test3-composed","multiArchiveTag":"composed-1787067664466"}'
} +1ms
  vonage:server-client Request failed Response {
  status: 400,
  statusText: 'Bad Request',
  headers: Headers {
    date: 'Tue, 18 Aug 2026 15:41:05 GMT',
    'content-type': 'application/json',
    'content-length': '168',
    connection: 'keep-alive',
    'x-envoy-upstream-service-time': '8',
    'x-frame-options': 'deny',
    'x-xss-protection': '1; mode=block',
    'strict-transport-security': 'max-age=31536000; includeSubdomains',
    'x-content-type-options': 'nosniff',
    server: 'envoy'
  },
  body: ReadableStream { locked: false, state: 'readable', supportsBYOB: true },
  bodyUsed: false,
  ok: false,
  redirected: false,
  type: 'basic',
  url: 'https://video.api.vonage.com/v2/project/74346f44-9448-42bc-91e2-19566a85e36b/archive'
} +462ms

[manchuck]

Your assumption is correct. I wanted to see the response to see if we could get the SDK to expose the error. However, it looks like the body was not read before being output, so it just shows it as a buffer 😒. I blame past @manchuck for that. He's an idiot sometimes 🤣.

I will look into parsing the response to throw a better error for you; however, I cannot promise anything that could be a breaking change. We are planning on a major version of the SDK, which will have a better design for throwing specific errors

[pebergia]

Heh past @pebergia gets blamed for stuff too. Ah okay, I have it all working now then so that's good (totally spaced on the combined not supporting it). Can the type/usage for multiArchiveTag be added easily? It doesn't block using it but it is still a bit confusing.

[manchuck]

Yes the types can be added easily. Will add a ticket to work on that