Update TikTok Pixel types for event_id options and current standard events

[felixgabler]

🆒 Your use case

When using useScriptTikTokPixel with both browser Pixel events and server-side Events API, TikTok recommends sending the same event_id on both sides so events can be deduplicated.

The current runtime implementation appears to support this at runtime because proxy.ttq forwards arbitrary calls to TikTok native queue, but the TypeScript overload for track only accepts three arguments:

proxy.ttq("track", "Purchase", properties)

For deduplication we need the fourth argument:

proxy.ttq("track", "Purchase", properties, { event_id: eventId })

This currently requires casting around the ttq type in app code. I may be missing a preferred Nuxt Scripts pattern here, but I could not find a typed helper or overload for this in the TikTok Pixel registry.

There is a related smaller typing gap: the StandardEvents union seems to include some older TikTok standard events, but not some current event names used in TikTok current event taxonomy, for example Purchase and StartTrial.

🅕 The solution you would like

Would it make sense to extend the TikTok Pixel registry types to support the native ttq("track", ..., options) form?

Something along these lines:

interface TrackOptions {
  event_id?: string
}

type TtqFns =
  & ((cmd: "track", event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void)
  & ((cmd: "page") => void)
  & ((cmd: "identify", properties: IdentifyProperties) => void)
  & ((cmd: (string & {}), ...args: any[]) => void)

It may also be worth refreshing StandardEvents to include TikTok current standard event names. I would expect at least Purchase and StartTrial to type cleanly, while still preserving the existing escape hatch for custom strings.

🔍 Alternatives you have considered

The current workaround is to cast the proxy call locally:

const ttqTrack = proxy.ttq as (
  command: "track",
  eventName: string,
  properties: Record<string, unknown>,
  options: { event_id: string },
) => void

ttqTrack("track", "Purchase", properties, { event_id: eventId })

That works, but it loses the benefit of the registry types exactly where a common Pixel + Events API setup needs them.

ℹ️ Additional info

Relevant current source:

• TikTok Pixel registry source: https://github.com/nuxt/scripts/blob/main/packages/script/src/runtime/registry/tiktok-pixel.ts
• TikTok Pixel docs: https://github.com/nuxt/scripts/blob/main/docs/content/scripts/tiktok-pixel.md

TikTok references I was looking at:

• Event deduplication: https://ads.tiktok.com/help/article/event-deduplication?lang=en
• Pixel example using the fourth event_id argument: https://ads.us.tiktok.com/help/article/tiktok-adobe-eapi-implementation-guide?lang=en
• Updated standard events: https://ads.tiktok.com/help/article/how-to-adopt-tiktoks-updated-standard-events?lang=en

The existing consent API in Nuxt Scripts looks good to me (defaultConsent, consent.grant(), consent.revoke(), consent.hold()). This issue is only about the typed tracking call shape and event-name coverage.