fix(tiktokPixel): missing types

[harlan-zw]

🔗 Linked issue

Resolves #767

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

The typed ttq('track', ...) overload didn't expose TikTok's optional 4th options arg, so users couldn't pass event_id for Pixel + Events API deduplication without casting. The StandardEvents union was also missing Purchase and StartTrial.

Adds the 4th options arg with event_id to the track overload and extends StandardEvents, preserving the (string & {}) escape hatch for custom event names.

✅ Verification

• pnpm test:types — TikTok-related type tests pass (pre-existing posthog version-mismatch errors are unrelated).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	May 14, 2026 5:11am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@773

commit: d72ebcb

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f9c099eb-cce9-451b-bdc5-8a07f44d0183

📥 Commits

Reviewing files that changed from the base of the PR and between d1252e7 and d72ebcb.

📒 Files selected for processing (1)

• test/types/types.test-d.ts

---

📝 Walkthrough

Walkthrough

This PR extends the TikTok Pixel registry type definitions. It adds 'Purchase' to the StandardEvents union to match current TikTok standard event taxonomy. It introduces a new TrackOptions type with an optional event_id field and updates the TtqFns track function signature to accept this options object as an optional fourth parameter, enabling event deduplication between browser and server-side tracking.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(tiktokPixel): missing types' is concise and clearly describes the main change: adding missing TypeScript type support for TikTok Pixel's track function options argument and standard events.
Description check	✅ Passed	The description is well-detailed and directly addresses the changeset: it explains the missing 4th options argument with event_id and the gaps in StandardEvents union, matching the actual code modifications.
Linked Issues check	✅ Passed	The pull request fully implements the objectives from issue #767: adds TrackOptions with event_id to the track overload signature, extends StandardEvents with Purchase and StartTrial, and preserves the custom string escape hatch.
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objectives: modifications are limited to TikTok Pixel type definitions and type tests, with no unrelated alterations introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/tiktok-pixel-event-id-options

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/script/src/runtime/registry/tiktok-pixel.ts`:
- Line 16: The StandardEvents union in tiktok-pixel.ts includes an invalid
member 'StartTrial' that is not part of TikTok's official Pixel standard events;
remove 'StartTrial' from the StandardEvents type (and any occurrences where it
is used/mapped) so the union only contains documented events like ViewContent,
AddToCart, InitiateCheckout, Purchase, etc.; update related enums or mappings
that reference 'StartTrial' (search for StandardEvents and any mapping
functions/classes in this file) to avoid dangling references.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7061713d-eff9-4a70-920f-3a7d778c948b

📥 Commits

Reviewing files that changed from the base of the PR and between 6129314 and d1252e7.

📒 Files selected for processing (1)

• packages/script/src/runtime/registry/tiktok-pixel.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

TikTok Pixel standard events list 2024 2025

💡 Result:

TikTok Pixel standard events list (the set of predefined web standard events you can send via TikTok Pixel / Events API) is not broken out by year (2024 vs 2025). The authoritative source is TikTok’s “Standard Events and Parameters” page, which lists the standard event names TikTok supports and is updated over time. As of TikTok’s latest help content, the supported standard event names include: ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, CompletePayment, Purchase (alias/mapped to CompletePayment in reserved-event mapping), PlaceAnOrder, Subscribe, Download, Search, Contact, SubmitForm, CompleteRegistration, and ApplicationApproval. [1][2][3] Note: There is also a separate “reserved events” list that maps certain reserved event names to standard events (e.g., AddBilling → AddPaymentInfo; Checkout → PlaceAnOrder/InitiateCheckout mappings; Registration → CompleteRegistration; Browse → ViewContent; etc.). You should not use reserved event names as custom events because TikTok automatically maps them to standard events. [3] Sources: TikTok Ads Manager help, “Standard Events and Parameters” and “About reserved events” pages. [1][3]

Citations:

• 1: https://ads.tiktok.com/help/article/standard-events-parameters?__hstc=188508983.20e3acfa39ad61fc2bb972fba4bdef19.1748908800443.1748908800444.1748908800445.1&__hssc=188508983.1.1748908800446&__hsfp=3282704936&redirected=1
• 2: https://ads.tiktok.com/help/article/standard-events-parameters?lang=en
• 3: https://ads.tiktok.com/help/article/reserved-events?lang=en

---

Remove 'StartTrial' from StandardEvents union—it is not in TikTok's official standard events list.

TikTok's official documentation lists these standard events: ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, CompletePayment, Purchase, PlaceAnOrder, Subscribe, Download, Search, Contact, SubmitForm, CompleteRegistration, and ApplicationApproval. 'Purchase' is confirmed valid, but 'StartTrial' does not appear in the official Pixel API documentation and should not be included as a standard event unless it is explicitly mapped or documented by TikTok's API contract.

Also applies to: 22-22

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/script/src/runtime/registry/tiktok-pixel.ts` at line 16, The
StandardEvents union in tiktok-pixel.ts includes an invalid member 'StartTrial'
that is not part of TikTok's official Pixel standard events; remove 'StartTrial'
from the StandardEvents type (and any occurrences where it is used/mapped) so
the union only contains documented events like ViewContent, AddToCart,
InitiateCheckout, Purchase, etc.; update related enums or mappings that
reference 'StartTrial' (search for StandardEvents and any mapping
functions/classes in this file) to avoid dangling references.