fix(tiktokPixel): missing types (#773)

harlan-zw · web-flow · commit f73a0ce9b324 · 2026-05-14T15:14:52.000+10:00
diff --git 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)
diff --git 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')
+  })
+})
