analyticscli-ts-sdk

What this skill does

# AnalyticsCLI TypeScript SDK

## Use This Skill When

- adding AnalyticsCLI analytics to a JS or TS app
- instrumenting onboarding, paywall, purchase, or survey events
- upgrading within the current `@analyticscli/sdk` line
- validating SDK behavior together with `analyticscli`

## Supported Versions

- Skill pack: `1.6.8`
- Target package: `@analyticscli/sdk`
- Supported range: `>=0.1.0-preview.6 <0.2.0`
- If a future SDK major changes APIs or event contracts in incompatible ways, add a sibling skill such as `analyticscli-ts-sdk-v1`

See [Versioning Notes](references/versioning.md).

## Core Rules

- Initialize exactly once near app bootstrap.
- For generated host-app code, prefer `init({ ... })` with explicit identity mode (`identityTrackingMode: 'consent_gated'`).
- `init('<YOUR_APP_KEY>')` shortform is acceptable for quick demos/tests or low-level client-only integrations.
- Keep setup options minimal: `apiKey` is enough for ingest.
- In host apps, use client-safe publishable env names (for example `ANALYTICSCLI_PUBLISHABLE_API_KEY`).
- Do not use `WRITE_KEY` env names in generated host-app snippets (`ANALYTICSCLI_WRITE_KEY`, `EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY`, etc.).
- `runtimeEnv` is auto-attached. Do not pass a `mode` string.
- `debug` is only a boolean for SDK console logging.
- Do not pass `endpoint` and do not add endpoint env vars in app templates. Use the SDK default collector endpoint.
- For `platform`, do not use framework labels (`react-native`, `expo`).
- Use only canonical platform values (`web`, `ios`, `android`, `mac`, `windows`) or omit the field.
- In React Native/Expo, pass `Platform.OS` directly; the SDK normalizes values like `macos -> mac` and `win32 -> windows`.
- Treat `platform` as runtime family only (`web`/`ios`/`android`/`mac`/`windows`), not as OS version/name.
- Treat `osName` as operating-system label (for example `iOS`, `Android`, `Windows`, `macOS`, `Web`). Prefer always setting/populating `osName`; keep `platform` optional.
- `init(...)`/`new AnalyticsClient(...)` auto-emits one `session_start` event per client instance on SDK mount (`source: sdk_mount`), so host apps do not need manual startup wiring.
- Do not manually emit duplicate `session_start` unless you intentionally also track a separate custom launch event (for example `app_launch`).
- In React Native/Expo, prefer `appVersion` from `expo-application` (`nativeApplicationVersion`); nullable values can be passed directly.
- Do not specify `dedupeOnboardingStepViewsPerSession` in generated host-app code by default; SDK default is `true`. Only set it explicitly when the user requests a different behavior or asks for explicit config.
- Do not specify `dedupeScreenViewsPerSession` in generated host-app code by default; SDK default is `true`. Only set it explicitly when the user requests a different behavior or asks for explicit config.
- Set `screenViewDedupeWindowMs` only when needed for a non-standard navigation stack; otherwise rely on SDK default (`1200` ms).
- Prefer SDK trackers over host-side wrapper utilities. Keep integration code close to call sites.
- Keep event properties stable and query-relevant.
- Avoid direct PII.
- Set `identityTrackingMode` explicitly in generated host-app bootstrap code; use `'consent_gated'` as the default.
- For EU/EEA/UK user traffic, keep `identityTrackingMode: 'consent_gated'` (or `strict`) unless legal counsel approves a different setup.
- `identify` / `setUser` only work when full tracking is enabled (`always_on`, or after full-tracking consent in `consent_gated`).
- Do not force storage adapters in generated bootstrap code by default.
- Avoid top-level `Promise` singletons in app utility files.
- Use neutral file names like `analytics.ts` (not provider-specific names such as `aptabase.ts`).
- Avoid re-exporting `PAYWALL_EVENTS` / `PURCHASE_EVENTS` from host app utility files. Import SDK constants directly when needed, or use `createPaywallTracker(...)`.
- When using `createPaywallTracker(...)`, create one tracker per stable paywall context and reuse it across `shown`/`skip`/purchase calls. Recreate only when defaults change.
- If your paywall provider exposes an offering/paywall identifier, pass it as `offering` in tracker defaults.
  RevenueCat: offering identifier; Adapty: paywall/placement identifier; Superwall: placement/paywall identifier.
- In hosted paywall screens (RevenueCat UI / Adapty / Superwall or custom wrappers around them), do not use generic `track(...)` / `trackEvent(...)` for paywall or purchase milestones.
  Use one memoized `createPaywallTracker(...)` per screen/context and route lifecycle callbacks to tracker methods:
  `shown` (visible), `purchaseStarted`, one terminal event (`purchaseSuccess`/`purchaseFailed`/`purchaseCancel`), and `skip` (dismiss/close/back).
- If multiple paywall screens exist, each screen/context must have its own stable tracker defaults (`source`, `paywallId`, optional `offering`) so events are not mixed across screens.
- Prefer SDK identity helpers (`setUser`, `identify`, `clearUser`) directly instead of wrapping identify logic in host-app boilerplate.
- Do not keep legacy analytics providers or event aliases active in generated host-app code.
- For touched paywall/purchase/onboarding flows, use canonical AnalyticsCLI event names only.
- For generated docs or README snippets, write from tenant developer perspective (`your app`, `your workspace`) and avoid provider-centric phrasing such as `our SaaS`.
- Default to canonical SDK event names at call sites.
- Before generating host-app code, ensure `@analyticscli/sdk` is upgraded to the newest preview in that repo.
- For onboarding instrumentation, use dedicated SDK onboarding APIs instead of generic `track(...)`/`trackEvent(...)`:
  `createOnboardingTracker(...)`, `trackOnboardingEvent(...)`, `trackOnboardingSurveyResponse(...)`,
  plus step helpers (`step(...).view()`, `step(...).complete()`, `step(...).surveyResponse(...)`).
- Use `onboarding:step_view` as the default step progression signal. Treat `onboarding:step_complete` as optional and only emit it when a step has a meaningful completion boundary (for example explicit submit/continue confirmation or async success).
- For survey steps, default to `onboarding:step_view` + `onboarding:survey_response`; avoid unconditional `onboarding:step_complete` unless completion semantics are explicit.
- For onboarding survey events, prefer `trackOnboardingSurveyResponse(...)` (or tracker survey helpers) so SDK sanitization/normalization is preserved.
- To avoid repetitive payloads, create one onboarding tracker with shared flow defaults and use `step(...).surveyResponse(...)` with only survey-specific fields at call sites.
- For React Native / Expo non-onboarding screens, track screen views on focus with `useFocusEffect(...)` and `analytics.screen(...)`.
- For RevenueCat correlation in host apps, keep AnalyticsCLI user identity in sync with the same stable user id used in `Purchases.logIn(...)` (`setUser` on sign-in/session restore, `clearUser` on sign-out).

## Host App Minimalism Guardrails

When this skill writes host-app code, optimize for low boilerplate by default.

- Do not generate a large event translation layer such as `mapEventToCanonical(...)` with many `switch` branches.
- Do not create host-side wrappers around `identify`/`setUser` unless required by an existing app contract.
- Do not add per-call `try/catch` wrappers around every analytics helper unless the user asked for that policy.
- Do not duplicate SDK constants/events in host utility files.
- Prefer direct SDK calls in feature code (`trackPaywallEvent`, tracker helpers, `screen`, `track`) instead of generic proxy helpers.
- Keep a single screen-tracking owner per route boundary (parent layout or screen component, not both).
- If a thin `analytics.ts` is needed, keep it focused to bootstrap + a few shared helpers. Avoid becoming an event-translation layer.

## Hard Fail Patterns

Do not generate these patter