TypeScript

Both packages ship their own type definitions. No @types package is needed. This page lists the exported types and shows one example for each pattern. When this page and the types of the published package disagree, the types win.

Exported types

@grainql/analytics-web:

Type	What it describes
`GrainAnalytics`	The client class.
`GrainConfig`	The constructor argument.
`AuthStrategy`	`'NONE' \| 'SERVER_SIDE' \| 'JWT'`.
`AuthProvider`	`{ getToken(): Promise<string> \| string }`.
`GrainEvent`, `EventPayload`	An event object for `track(event, options?)`, and the wire shape.
`SendEventOptions`	`{ flush?: boolean }`.
`SetPropertyOptions`	`{ userId?: string }`.
`LoginOptions`	`{ userId?, authToken?, authStrategy? }`.
`PropertyPayload`	The wire shape of `setProperty`.
`RemoteConfigRequest`, `RemoteConfigResponse`, `RemoteConfigOptions`, `RemoteConfigCache`	The configuration fetch and its cache.
`ConfigChangeListener`	`(configurations: Record<string, string>) => void`.
`ConsentMode`, `ConsentState`, `CookieConfig`	Consent and cookie state.
`LoginEventProperties`, `SignupEventProperties`, `CheckoutEventProperties`, `PageViewEventProperties`, `PurchaseEventProperties`, `SearchEventProperties`, `AddToCartEventProperties`, `RemoveFromCartEventProperties`	The argument of each template method.
`ErrorDigest`, `FormattedError`	The error that the SDK logs in debug mode.
`ReferrerCategory`, `UTMParameters`, `FirstTouchAttribution`	Attribution values.
`InteractionConfig`, `SectionConfig`, `AutoTrackingConfig`, `SectionViewData`, `SectionTrackingOptions`	Automatic tracking definitions.

@grainql/analytics-web/react:

Type	What it describes
`GrainProviderProps`	`{ children, client?, config? }`.
`UseConfigOptions`, `UseConfigResult`	The argument and result of `useConfig`.
`UseAllConfigsOptions`, `UseAllConfigsResult`	The argument and result of `useAllConfigs`.
`TrackFunction`	The result of `useTrack`.
`ConsentBannerProps`, `PrivacyPreferenceCenterProps`, `CookieNoticeProps`	The props of the consent components.
`PrivacyPreferences`, `DataDeletionOptions`	The state of `usePrivacyPreferences` and the argument of `useDataDeletion`.

@grainql/tag:

Type	What it describes
`GrainTagConfig`	The argument of `init`.
`GrainTagInstance`	The object that `init` and `getInstance` return.
`GrainEvent`, `EventPayload`	An event and its wire shape.
`ConsentMode`, `ConsentState`	`'auto' \| 'opt-in' \| 'opt-out'` and the state that `consent.status()` returns.
`UTMParameters`, `FirstTouchAttribution`	Attribution values.
`HeatmapClickData`, `HeatmapScrollData`	Heatmap events.

Read Types for the fields of each type.

Typed configuration

Annotate the configuration object with GrainConfig. The compiler rejects an unknown option and a wrong authStrategy value.

import { createGrainAnalytics, type GrainConfig } from '@grainql/analytics-web';

const config: GrainConfig = {
  tenantId: 'your-tenant-id',
  authStrategy: 'JWT',
  batchSize: 50,
  debug: true
};

const grain = createGrainAnalytics(config);

Typed event properties

track accepts Record<string, unknown>. Wrap it in a function with a typed argument to get a compile error on a wrong property.

type VideoEventName = 'video_started' | 'video_paused' | 'video_completed';

interface VideoEventProperties {
  video_id: string;
  duration: number;
  progress: number;
}

function trackVideoEvent(name: VideoEventName, properties: VideoEventProperties) {
  return grain.track(name, properties);
}

trackVideoEvent('video_started', { video_id: 'abc123', duration: 120, progress: 0 });

An enum works the same way for event names. Read Name events.

Template event types

Each template method has a property type. The compiler lists the valid fields.

import type { LoginEventProperties } from '@grainql/analytics-web';

const login: LoginEventProperties = {
  method: 'email',
  success: true,
  rememberMe: false
};

await grain.trackLogin(login);

Read Template events.

Typed configuration values

Remote configuration values are strings. Declare the keys once, then read them through a generic accessor.

interface AppConfig {
  hero_text: string;
  button_color: string;
  feature_enabled: 'true' | 'false';
}

function getTypedConfig<K extends keyof AppConfig>(key: K): AppConfig[K] | undefined {
  return grain.getConfig(key) as AppConfig[K] | undefined;
}

const heroText = getTypedConfig('hero_text');

The cast does not check the value at run time. A wrong value in the dashboard still arrives.

The client as a dependency

Type a constructor argument with GrainAnalytics to inject the client, or a mock of it.

import type { GrainAnalytics } from '@grainql/analytics-web';

class AnalyticsService {
  constructor(private grain: GrainAnalytics) {}

  trackPageView(page: string) {
    return this.grain.track('page_viewed', { page });
  }
}

In a test, jest.Mocked<GrainAnalytics> types the mock.

const mockGrain = {
  track: jest.fn(),
  setUserId: jest.fn(),
  getConfig: jest.fn()
} as unknown as jest.Mocked<GrainAnalytics>;

expect(mockGrain.track).toHaveBeenCalledWith('test_event', { foo: 'bar' });

Auth provider

import type { AuthProvider } from '@grainql/analytics-web';

const authProvider: AuthProvider = {
  async getToken(): Promise<string> {
    return await auth0.getAccessToken();
  }
};

Null checks

The SDK compiles with strict: true. getUserId() returns string | null, and getConfig returns string | undefined. Test the value before you use it.

const userId = grain.getUserId();

if (userId) {
  console.log(userId.toUpperCase());
}

React hook results

The hooks return typed objects. useConfig gives value: string | undefined, isRefreshing: boolean, error: Error | null, and refresh: () => Promise<void>.

import { useConfig } from '@grainql/analytics-web/react';

function Hero() {
  const { value, isRefreshing, error, refresh } = useConfig('hero_text');
  return <h1>{value ?? 'Welcome'}</h1>;
}

Read React hooks.

Re-exporting types

Re-export the types that the app uses from one module, so that a package upgrade changes one import path.

export type {
  GrainAnalytics,
  GrainConfig,
  GrainEvent,
  AuthProvider,
  LoginEventProperties,
  CheckoutEventProperties
} from '@grainql/analytics-web';

export type { UseConfigResult, UseAllConfigsResult } from '@grainql/analytics-web/react';

Use import type for a type-only import. The bundler drops it from the output.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Exported types

Typed configuration

Typed event properties

Template event types

Typed configuration values

The client as a dependency

Auth provider

Null checks

React hook results

Re-exporting types

​Exported types

​Typed configuration

​Typed event properties

​Template event types

​Typed configuration values

​The client as a dependency

​Auth provider

​Null checks

​React hook results

​Re-exporting types

Exported types

Typed configuration

Typed event properties

Template event types

Typed configuration values

The client as a dependency

Auth provider

Null checks

React hook results

Re-exporting types