Types & Interfaces

Grain Tag Types

import type { GrainTagConfig, GrainTagInstance, ConsentState } from '@grainql/tag';

GrainTagConfig

Configuration options passed to init().

interface GrainTagConfig {
  // Required
  tenantId: string;

  // API
  apiUrl?: string;

  // Debug
  debug?: boolean;

  // Version
  version?: string;

  // Consent
  consentMode?: 'auto' | 'opt-in' | 'opt-out';

  // Tracking features
  enablePageViews?: boolean;
  enableHeatmaps?: boolean;
  enableSnapshots?: boolean;
  enableRescue?: boolean;

  // Advanced
  batchSize?: number;
  flushInterval?: number;
  retryAttempts?: number;
}

Field	Type	Default	Description
`tenantId`	`string`	required	Your tenant identifier
`apiUrl`	`string`	Production URL	Override the API endpoint
`debug`	`boolean`	`false`	Enable debug logging
`version`	`string`	—	SDK version override
`consentMode`	`'auto' \| 'opt-in' \| 'opt-out'`	`'auto'`	Consent handling strategy
`enablePageViews`	`boolean`	`true`	Auto-track page views
`enableHeatmaps`	`boolean`	`true`	Track clicks and scroll depth
`enableSnapshots`	`boolean`	`true`	Capture DOM snapshots
`enableRescue`	`boolean`	`true`	Enable rescue tracking
`batchSize`	`number`	`50`	Max events per batch
`flushInterval`	`number`	`5000`	Flush interval in milliseconds
`retryAttempts`	`number`	`3`	Number of retry attempts

GrainTagInstance

The instance returned by init() and getInstance().

interface GrainTagInstance {
  track(eventName: string, properties?: Record<string, unknown>): void;
  identify(userId: string): void;
  consent: {
    grant(categories?: string[]): void;
    revoke(categories?: string[]): void;
    status(): ConsentState | null;
  };
  flush(): Promise<void>;
  destroy(): void;
  isReady(): boolean;
}

ConsentState

Returned by grain.consent.status().

interface ConsentState {
  granted: boolean;
  categories: string[];
  timestamp: number;
  version: string;
}

Field	Type	Description
`granted`	`boolean`	Whether consent is currently granted
`categories`	`string[]`	Active consent categories (e.g. `['necessary', 'analytics']`)
`timestamp`	`number`	Unix timestamp of the consent decision
`version`	`string`	Consent version identifier

ConsentMode

type ConsentMode = 'auto' | 'opt-in' | 'opt-out';

auto — Starts in cookieless mode, upgrades when consent is granted
opt-in — Requires explicit consent before any tracking beyond necessary
opt-out — Full tracking by default, respects revocation

ConsentCategory

type ConsentCategory = 'necessary' | 'analytics' | 'functional' | 'marketing';

Analytics Web Types

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

GrainConfig

Configuration options for createGrainAnalytics().

interface GrainConfig {
  // Required
  tenantId: string;

  // Authentication
  authStrategy?: 'NONE' | 'SERVER_SIDE' | 'JWT';
  secretKey?: string;
  authProvider?: AuthProvider;

  // User
  userId?: string;

  // API
  apiUrl?: string;

  // Batching
  batchSize?: number;
  flushInterval?: number;

  // Retry
  retryAttempts?: number;
  retryDelay?: number;

  // Remote Config
  defaultConfigurations?: Record<string, string>;
  configCacheKey?: string;
  configRefreshInterval?: number;
  enableConfigCache?: boolean;

  // Debug
  debug?: boolean;
}

GrainEvent

Event structure for tracking.

interface GrainEvent {
  eventName: string;
  userId?: string;
  properties?: Record<string, unknown>;
  timestamp?: Date;
}

AuthProvider

JWT authentication provider interface.

interface AuthProvider {
  getToken(): Promise<string> | string;
}

Example:

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

Options Types

SendEventOptions

Options for the Analytics Web track() method.

interface SendEventOptions {
  flush?: boolean;  // Force immediate send
}

SetPropertyOptions

Options for the Analytics Web setProperty() method.

interface SetPropertyOptions {
  userId?: string;  // User ID override
}

RemoteConfigOptions

Options for Analytics Web configuration methods.

interface RemoteConfigOptions {
  immediateKeys?: string[];
  properties?: Record<string, string>;
  userId?: string;
  forceRefresh?: boolean;
}

Response Types

RemoteConfigResponse

API response for configuration fetch.

interface RemoteConfigResponse {
  userId: string;
  snapshotId: string;
  configurations: Record<string, string>;
  isFinal: boolean;
  qualifiedSegments: string[];
  qualifiedRuleSets: string[];
  timestamp: string;
  isFromCache: boolean;
}

Template Event Types

LoginEventProperties

interface LoginEventProperties extends Record<string, unknown> {
  method?: string;
  success?: boolean;
  errorMessage?: string;
  loginAttempt?: number;
  rememberMe?: boolean;
  twoFactorEnabled?: boolean;
}

SignupEventProperties

interface SignupEventProperties extends Record<string, unknown> {
  method?: string;
  source?: string;
  plan?: string;
  success?: boolean;
  referralCode?: string;
}

CheckoutEventProperties

interface CheckoutEventProperties extends Record<string, unknown> {
  orderId?: string;
  total?: number;
  currency?: string;
  items?: Array<{
    id: string;
    name: string;
    price: number;
    quantity: number;
  }>;
  paymentMethod?: string;
  success?: boolean;
  errorMessage?: string;
  couponCode?: string;
  discount?: number;
}

PurchaseEventProperties

interface PurchaseEventProperties extends Record<string, unknown> {
  orderId?: string;
  total?: number;
  currency?: string;
  paymentMethod?: string;
  shipping?: number;
  tax?: number;
}

AddToCartEventProperties

interface AddToCartEventProperties extends Record<string, unknown> {
  itemId?: string;
  itemName?: string;
  price?: number;
  quantity?: number;
  currency?: string;
}

RemoveFromCartEventProperties

interface RemoveFromCartEventProperties extends Record<string, unknown> {
  itemId?: string;
  itemName?: string;
  price?: number;
  quantity?: number;
}

PageViewEventProperties

interface PageViewEventProperties extends Record<string, unknown> {
  page?: string;
  title?: string;
  url?: string;
  referrer?: string;
}

SearchEventProperties

interface SearchEventProperties extends Record<string, unknown> {
  query?: string;
  results?: number;
  filters?: Record<string, unknown>;
  sortBy?: string;
}

React Hook Types

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

UseConfigResult

interface UseConfigResult {
  value: string | undefined;
  isRefreshing: boolean;
  error: Error | null;
  refresh: () => Promise<void>;
}

UseAllConfigsResult

interface UseAllConfigsResult {
  configs: Record<string, string>;
  isRefreshing: boolean;
  error: Error | null;
  refresh: () => Promise<void>;
}

Listener Types

ConfigChangeListener

type ConfigChangeListener = (
  configurations: Record<string, string>
) => void;

Example:

const listener: ConfigChangeListener = (configs) => {
  console.log('Updated:', configs);
};

Importing Types

Grain Tag

import type {
  GrainTagConfig,
  GrainTagInstance,
  ConsentState,
  ConsentMode,
  GrainEvent
} from '@grainql/tag';

Analytics Web

import type {
  GrainConfig,
  GrainEvent,
  AuthProvider,
  SendEventOptions,
  RemoteConfigOptions,
  LoginEventProperties,
  CheckoutEventProperties
} from '@grainql/analytics-web';

React Hook Types

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

Grain Tag Types

GrainTagConfig

GrainTagInstance

ConsentState

ConsentMode

ConsentCategory

Analytics Web Types

GrainConfig

GrainEvent

AuthProvider

Options Types

SendEventOptions

SetPropertyOptions

RemoteConfigOptions

Response Types

RemoteConfigResponse

Template Event Types

LoginEventProperties

SignupEventProperties

CheckoutEventProperties

PurchaseEventProperties

AddToCartEventProperties

RemoveFromCartEventProperties

PageViewEventProperties

SearchEventProperties

React Hook Types

UseConfigResult

UseAllConfigsResult

Listener Types

ConfigChangeListener

Importing Types

Grain Tag

Analytics Web

React Hook Types

Next Steps

Core Methods

API Overview

​Grain Tag Types

​GrainTagConfig

​GrainTagInstance

​ConsentState

​ConsentMode

​ConsentCategory

​Analytics Web Types

​GrainConfig

​GrainEvent

​AuthProvider

​Options Types

​SendEventOptions

​SetPropertyOptions

​RemoteConfigOptions

​Response Types

​RemoteConfigResponse

​Template Event Types

​LoginEventProperties

​SignupEventProperties

​CheckoutEventProperties

​PurchaseEventProperties

​AddToCartEventProperties

​RemoveFromCartEventProperties

​PageViewEventProperties

​SearchEventProperties

​React Hook Types

​UseConfigResult

​UseAllConfigsResult

​Listener Types

​ConfigChangeListener

​Importing Types

​Grain Tag

​Analytics Web

​React Hook Types

​Next Steps

Core Methods

API Overview

Grain Tag Types

GrainTagConfig

GrainTagInstance

ConsentState

ConsentMode

ConsentCategory

Analytics Web Types

GrainConfig

GrainEvent

AuthProvider

Options Types

SendEventOptions

SetPropertyOptions

RemoteConfigOptions

Response Types

RemoteConfigResponse

Template Event Types

LoginEventProperties

SignupEventProperties

CheckoutEventProperties

PurchaseEventProperties

AddToCartEventProperties

RemoveFromCartEventProperties

PageViewEventProperties

SearchEventProperties

React Hook Types

UseConfigResult

UseAllConfigsResult

Listener Types

ConfigChangeListener

Importing Types

Grain Tag

Analytics Web

React Hook Types

Next Steps