From d1252e74ba8f1a92dc6e57617694cb93564553b2 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 14 May 2026 14:55:41 +1000
Subject: [PATCH 1/2] feat(tiktokPixel): support event_id options on track +
 add missing standard events

Adds optional fourth `options` arg to `ttq('track', ...)` typed overload
exposing `event_id` for Pixel + Events API deduplication, and adds the
current TikTok standard events `Purchase` and `StartTrial` to the
`StandardEvents` union.

Closes #767
---
 packages/script/src/runtime/registry/tiktok-pixel.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/script/src/runtime/registry/tiktok-pixel.ts b/packages/script/src/runtime/registry/tiktok-pixel.ts
index cf6c713b6..4f97c3836 100644
--- a/packages/script/src/runtime/registry/tiktok-pixel.ts
+++ b/packages/script/src/runtime/registry/tiktok-pixel.ts
@@ -13,11 +13,13 @@ type StandardEvents
     | 'AddPaymentInfo'
     | 'CompletePayment'
     | 'PlaceAnOrder'
+    | 'Purchase'
     | 'Contact'
     | 'Download'
     | 'SubmitForm'
     | 'CompleteRegistration'
     | 'Subscribe'
+    | 'StartTrial'
 
 interface EventProperties {
   content_id?: string
@@ -37,8 +39,14 @@ interface IdentifyProperties {
   external_id?: string
 }
 
+interface TrackOptions {
+  /** Used to deduplicate events sent from both the browser Pixel and the server-side Events API. */
+  event_id?: string
+  [key: string]: any
+}
+
 type TtqFns
-  = ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties) => void)
+  = ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void)
     & ((cmd: 'page') => void)
     & ((cmd: 'identify', properties: IdentifyProperties) => void)
     & ((cmd: (string & {}), ...args: any[]) => void)

From d72ebcb3fc206956dc0d5c1748b72bbb3a8cd15d Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 14 May 2026 15:09:41 +1000
Subject: [PATCH 2/2] test(tiktokPixel): add type assertions for ttq overload +
 standard events

---
 test/types/types.test-d.ts | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/test/types/types.test-d.ts b/test/types/types.test-d.ts
index 0976a8966..1789ffdc3 100644
--- a/test/types/types.test-d.ts
+++ b/test/types/types.test-d.ts
@@ -1,6 +1,7 @@
 import type { ModuleOptions } from '../../packages/script/src/module'
 import type { CrispApi } from '../../packages/script/src/runtime/registry/crisp'
 import type { DefaultEventName } from '../../packages/script/src/runtime/registry/google-analytics'
+import type { TikTokPixelApi } from '../../packages/script/src/runtime/registry/tiktok-pixel'
 import type { NuxtConfigScriptRegistry, NuxtConfigScriptRegistryEntry, NuxtUseScriptOptions, RegistryScriptInput, ScriptRegistry, UseScriptContext } from '../../packages/script/src/runtime/types'
 import { describe, expectTypeOf, it } from 'vitest'
 
@@ -157,3 +158,20 @@ describe('#nuxt-scripts/types exports', () => {
     expectTypeOf<ScriptRegistry>().toHaveProperty('clarity')
   })
 })
+
+describe('tiktok pixel ttq', () => {
+  type Ttq = TikTokPixelApi['ttq']
+
+  it('track accepts the 4th options arg with event_id', () => {
+    expectTypeOf<Ttq>().toBeCallableWith('track', 'Purchase', { value: 10 }, { event_id: 'abc' })
+  })
+
+  it('track accepts standard events including Purchase and StartTrial', () => {
+    expectTypeOf<Ttq>().toBeCallableWith('track', 'Purchase')
+    expectTypeOf<Ttq>().toBeCallableWith('track', 'StartTrial')
+  })
+
+  it('track still accepts arbitrary custom event names', () => {
+    expectTypeOf<Ttq>().toBeCallableWith('track', 'CustomEvent')
+  })
+})