feat(audience): typed track() surface for v1 event catalogue (SDK-116)#2850
Merged
ImmutableJeffrey merged 2 commits intomainfrom Apr 14, 2026
Merged
feat(audience): typed track() surface for v1 event catalogue (SDK-116)#2850ImmutableJeffrey merged 2 commits intomainfrom
ImmutableJeffrey merged 2 commits intomainfrom
Conversation
|
View your CI Pipeline Execution ↗ for commit 3b16d38
☁️ Nx Cloud last updated this comment at |
ImmutableJeffrey
force-pushed
the
feat/audience-typed-events
branch
3 times, most recently
from
3c09e6e to
90a8fec
Compare
ImmutableJeffrey
changed the title
bkbooth
reviewed
Apr 13, 2026
bkbooth
reviewed
Apr 13, 2026
bkbooth
previously approved these changes
Apr 13, 2026
ImmutableJeffrey
force-pushed
the
feat/audience-typed-events
branch
from
90a8fec to
22182cd
Compare
nattb8
reviewed
Apr 14, 2026
nattb8
reviewed
Apr 14, 2026
nattb8
reviewed
Apr 14, 2026
nattb8
reviewed
Apr 14, 2026
ImmutableJeffrey
force-pushed
the
feat/audience-typed-events
branch
from
22182cd to
703e5b0
Compare
ImmutableJeffrey
added a commit
that referenced
this pull request
Apr 14, 2026
- Widen track() generic constraint to `AudienceEventName | string & {}`.
IntelliSense surfaces the 11 predefined event names at `sdk.track('|`.
- Export `AudienceEventName` and `PropsFor<E>` from the package root.
- Note predefined-event type enforcement in track()'s JSDoc.
Addresses PR #2850 review feedback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ImmutableJeffrey
added a commit
that referenced
this pull request
Apr 14, 2026
- Widen track() generic constraint to `AudienceEventName | string & {}`.
IntelliSense surfaces the 11 predefined event names at `sdk.track('|`.
- Export `AudienceEventName` and `PropsFor<E>` from the package root.
- Note predefined-event type enforcement in track()'s JSDoc.
Addresses PR #2850 review feedback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ImmutableJeffrey
force-pushed
the
feat/audience-typed-events
branch
from
ace1525 to
cbdab5d
Compare
Adds the v1 typed event surface to @imtbl/audience: 11 events
(sign_up, sign_in, wishlist_add, wishlist_remove, purchase,
game_launch, progression, resource, email_acquired, game_page_viewed,
link_clicked), each with a property interface and compile-time
enforcement on the track() call site.
Uses a single generic track<E extends string>(event, ...args) signature
backed by a PropsFor<E> conditional type. Traditional overloads fall
through to the string catch-all when the properties object is incomplete
(TypeScript picks the more-specific overload's first arg match, sees
the second arg is not assignable, then silently picks the less-specific
overload that accepts any object). The generic approach does not fall
through and produces a real error for missing, wrong-type, and extra
properties. A variadic-tuple conditional ({} extends PropsFor<E>) makes
the properties argument required for events that have required fields
and optional for events where every field is optional.
Extended events (email_acquired, game_page_viewed, link_clicked) carry
over from immutable/play#5151 with two normalisations:
- isLoggedIn is dropped from all three shapes. The SDK already knows
logged-in state via identify() + consent level; pipeline consumers
should derive is_logged_in from userId IS NOT NULL on the events
table rather than accept a duplicated property from every call site.
- source is a free string. Play keeps its AudienceSource enum locally
and passes its values into the SDK as strings.
Runtime is unchanged modulo one type cast in the enqueue call (widening
PropsFor<E> to Record<string, unknown>). Bundle size unchanged. The
track() method body's runtime logic is identical to baseline.
Type safety is asserted by a new sdk.test-d.ts file that uses
@ts-expect-error to prove negative cases fail typecheck — missing
required properties, extra properties, wrong value types, wrong enum
values, and zero-argument calls on required-props events. The file is
included in tsc but skipped by Jest (its .test-d.ts suffix does not
match the default test pattern).
Runtime coverage: five new it blocks in sdk.test.ts exercise sign_up,
game_launch, progression, resource, and wishlist_add end-to-end through
the queue flush path. 54 tests passing (up from 49).
Independent of the feat/audience-web-sdk-demo branch and the Phase 0
audience-foundations work. No shared files; merges in any order.
Spec: docs/superpowers/specs/2026-04-13-websdk-typed-events-design.md
Plan: docs/superpowers/plans/2026-04-13-websdk-typed-events.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Widen track() generic constraint to `AudienceEventName | string & {}`.
IntelliSense surfaces the 11 predefined event names at `sdk.track('|`.
- Export `AudienceEventName` and `PropsFor<E>` from the package root.
- Note predefined-event type enforcement in track()'s JSDoc.
Addresses PR #2850 review feedback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ImmutableJeffrey
force-pushed
the
feat/audience-typed-events
branch
from
cbdab5d to
3b16d38
Compare
nattb8
approved these changes
Apr 14, 2026
ImmutableJeffrey
added a commit
that referenced
this pull request
Apr 14, 2026
TypeScript's `?` modifier already encodes property optionality at the type level. The JSDoc labels duplicate what the syntax says without adding information. Follow-up to #2850. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ImmutableJeffrey
added a commit
that referenced
this pull request
Apr 14, 2026
TypeScript's `?` modifier already encodes property optionality at the type level. The JSDoc labels duplicate what the syntax says without adding information. Follow-up to #2850. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds pre-defined events per the Web SDK Event Reference (v1).
Linear: SDK-116.
Detail and impact of the change
Added
sdk.track()as a generictrack<E extends string>with aPropsFor<E>conditional type mapping each of 11 event names to its property interfaceAudienceEvents, 11*Propertiesinterfaces,ProgressionStatus,ResourceFlowsdk.test-d.tswith compile-time negative assertionsDemo
2026-04-14.11-14-28.mov
Test plan
pnpm lint && pnpm typecheck && pnpm test && pnpm typegen— 54/54 passing