diff --git a/.babelrc b/.babelrc
deleted file mode 100644
index 1320b9a..0000000
--- a/.babelrc
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  "presets": ["@babel/preset-env"]
-}
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index a77f6e5..928198c 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -22,10 +22,13 @@ jobs:
         with:
           ref: 'refs/heads/master'
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
       - name: Configure Git
@@ -33,18 +36,15 @@ jobs:
           git config user.name "cloudinary-bot"
           git config user.email "cloudinary-bot@clodinary.com"
 
-      - name: Setup yarn
-        run: npm install -g yarn
-
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: pnpm install
 
       - name: Bump version
         run: npm version ${{ github.event.inputs.version-type }} -m "Bumping to version %s" --tag-version-prefix=""
 
       - name: Build
         shell: bash
-        run: yarn build
+        run: pnpm build
 
       - name: Publish packages
         run: npm publish --access="public"
diff --git a/.gitignore b/.gitignore
index 3f6f8f5..96aab62 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,7 @@ tags
 # nodejs
 node_modules/
 npm-debug.log
-yarn-error.log
+pnpm-debug.log
 
 # project
 env.js
diff --git a/.npmignore b/.npmignore
index e11cf97..d4bec2d 100644
--- a/.npmignore
+++ b/.npmignore
@@ -6,7 +6,7 @@ tags
 # nodejs
 node_modules/
 npm-debug.log
-yarn-error.log
+pnpm-debug.log
 
 # project
 env.js
diff --git a/README.md b/README.md
index 83279d8..b8f552a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # Cloudinary Video Analytics
 The Cloudinary Video Analytics package allows you to track analytics for your Cloudinary videos using video players other than the Cloudinary Video Player. The library targets the HTML5 video tag and is designed to work with any video player that use this tag. For more information view the [documentation](https://cloudinary.com/documentation/video_analytics).
 
-### Usage
+The package is written in TypeScript and ships its own type declarations.
+
+## Usage
 **1. Install the package**:
 
 ```shell
@@ -12,7 +14,7 @@ npm i cloudinary-video-analytics
 ```js
 import { connectCloudinaryAnalytics } from 'cloudinary-video-analytics';
 ```
-**3. Connect the analytics:**:
+**3. Connect the analytics**:
 
 Connect the analytics by calling the `connectCloudinaryAnalytics` method and provide the video element as a parameter. For example, if your video element has the id ‘video-player’:
 ```js
@@ -36,7 +38,140 @@ cloudinaryAnalytics.startManualTracking({
 
 Auto and manual tracking cannot be used together for the same video element. Manual tracking should only be used in cases where you need to track certain videos, you want to track a video tag element which is dynamic, or you have custom domains which require providing `cloudName` and `publicId`.
 
-### CodeSandbox examples
+## API
+
+`connectCloudinaryAnalytics(videoElement, mainOptions?)` returns an object with the following methods:
+
+| Method | Description |
+| --- | --- |
+| `startAutoTracking(options?)` | Automatically detects and tracks Cloudinary videos played in the element. |
+| `startManualTracking(metadata, options?)` | Tracks a specific video (or live stream) identified by `cloudName` / `publicId`. |
+| `stopManualTracking()` | Stops the current tracking session. |
+| `stopAutoTracking()` | Alias of `stopManualTracking` — stops the current tracking session. |
+| `stopTracking()` | Stops whichever tracking (auto or manual) is currently active. |
+| `reportCustomEvent(name, data?)` | Records a consumer-defined event into the current view (see [Custom events](#custom-events)). |
+
+### `metadata` (manual tracking)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cloudName` | `string` | Your Cloudinary cloud name. Required. |
+| `publicId` | `string` | Public ID of the video (or live stream output). Required. |
+| `type` | `'live'` | Optional. Set to `'live'` to track a live stream. |
+
+### `options` (tracking options)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `customData` | `object \| () => object` | Up to five string fields (`customData1`…`customData5`); non-string values are ignored. |
+| `videoPlayerType` | `string` | `'native'` (default) or `'cloudinary video player'`. |
+| `videoPlayerVersion` | `string` | Semantic version of the player. |
+| `customVideoUrlFallback` | `(videoUrl) => ({ cloudName, publicId })` | Resolves `cloudName`/`publicId` from a video URL (auto tracking / custom domains). |
+
+### `mainOptions`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `playerAdapter` | `PlayerAdapter` | Custom player adapter. Defaults to the built-in native HTML5 `<video>` adapter. |
+
+## Custom events
+
+Report your own events into the active view — for example an "on screen" / viewability signal coming from your player integration — so they can be correlated (by time) with the built-in events:
+
+```js
+cloudinaryAnalytics.reportCustomEvent('onScreen', { visible: true, ratio: 0.75 });
+```
+
+- The event is **recorded** into the current view and shipped in the same payload; it is not sent immediately.
+- `name` must be a non-empty string; `data` must be a plain object (JSON-serializable, ≤ 2000 characters).
+- It is a **no-op** when no view is currently being tracked, and for live streams (which are not collected into a view).
+
+## Collected events
+
+### Payload shape
+
+Data is sent once per view (see [Views](#views)) via `navigator.sendBeacon` as `multipart/form-data` with three fields:
+
+| Field | Description |
+| --- | --- |
+| `userId` | Anonymous, persistent per-browser id (stored in `localStorage`). Stable across views and sessions. |
+| `viewId` | Unique id for a single view. |
+| `events` | JSON-stringified array of event objects. |
+
+Every event object has the shape:
+
+```json
+{ "eventName": "play", "eventTime": 1784973602000, "eventDetails": {} }
+```
+
+- `eventName` — the event type (see below).
+- `eventTime` — epoch milliseconds when the event was recorded.
+- `eventDetails` — event-specific payload.
+
+### Views
+
+A **view** is one `viewStart` … `viewEnd` window sharing a single `viewId`. Events accumulate in memory during the view and are sent as a single beacon when the view ends (page unload on desktop, tab hidden on mobile). Backgrounding and returning to a tab ends one view and begins a new one (a new `viewId`, a separate beacon).
+
+### Event reference
+
+| `eventName` | Fired when | `eventDetails` |
+| --- | --- | --- |
+| `viewStart` | A view begins. | `videoUrl`, `trackingType` (`'auto'` \| `'manual'`), `analyticsModuleVersion`, `videoPlayer` (`{ type, version }`), `customerData` (`{ providedData?, videoData? }`) |
+| `viewEnd` | A view ends. | `{}` |
+| `play` | Playback is requested (user or autoplay). | `{}` |
+| `pause` | Playback is paused (or the source is emptied). | `{}` |
+| `ended` | Playback reaches the natural end. | `{}` |
+| `loadMetadata` | Video metadata has loaded. | `videoDuration` (seconds, or `'Infinity'` / `null`), `videoUrl` |
+| `startup` | The first frame renders after play was requested. | `joinTime` (ms from play intent to first frame) |
+| `buffering` | Once per view (summary of all rebuffering). | see [Buffering](#buffering) |
+| `qualityChange` | The decoded video resolution changes (incl. the initial resolution). | `videoWidth`, `videoHeight` |
+| `error` | A media error occurs. | `errorCode` (`MediaError.code` or `null`), `errorMessage` |
+| `fullscreenChange` | This video enters or leaves fullscreen. | `isFullscreen` (`boolean`) |
+| `pictureInPictureChange` | This video enters or leaves picture-in-picture. | `isPictureInPicture` (`boolean`) |
+| `custom` | You call `reportCustomEvent`. | `name` (your event name), `data` (your payload) |
+| `truncated` | A view hits the per-view event cap (250). Emitted once; further events are dropped. | `limit` |
+
+> A view that has a `play` event but no `startup` event means playback never began — a **startup failure**. If it also has no `error`, it is an **exit before video start**.
+
+### Buffering
+
+Rebuffering is reported as a single summary event per view. Stalls that occur before the first frame are attributed to `startup` (join time), not buffering; a user pause during a stall ends that stall so paused time is never counted.
+
+```json
+{
+  "eventName": "buffering",
+  "eventTime": 1784973685000,
+  "eventDetails": {
+    "count": 4,
+    "totalDuration": 7400,
+    "maxDuration": 4200,
+    "byCause": {
+      "seek":     { "count": 1, "totalDuration": 1200 },
+      "rebuffer": { "count": 3, "totalDuration": 6200 }
+    },
+    "occurrences": [
+      { "atTime": 1784973620000, "duration": 4200, "cause": "rebuffer", "endedBy": "recovery" },
+      { "atTime": 1784973640000, "duration": 1200, "cause": "seek",     "endedBy": "recovery" }
+    ],
+    "occurrencesTruncated": false
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `count` | Total number of buffering episodes in the view. |
+| `totalDuration` | Total buffering time (ms) across all episodes. |
+| `maxDuration` | Longest single episode (ms). |
+| `byCause` | Per-cause totals. `cause` is `'seek'` (buffering after a user seek) or `'rebuffer'` (buffering during normal playback — the true QoE signal). |
+| `occurrences` | Exact per-episode detail, capped at 20 entries. Each has `atTime`, `duration`, `cause`, and `endedBy` (`'recovery'` \| `'pause'` \| `'viewEnd'`). |
+| `occurrencesTruncated` | `true` when there were more episodes than the `occurrences` array holds (totals still cover them all). |
+
+### Live streams
+
+For live streams (`type: 'live'`), only `viewStart` and `viewEnd` are collected, and each is sent immediately as its own beacon.
+
+## CodeSandbox examples
 [Native HTML Video Tag - Auto tracking](https://4rqcfc.csb.app/src/native-html-auto-tracking/index.html)
 <br />
 [Native HTML Video Tag - Manual tracking](https://4rqcfc.csb.app/src/native-html-manual-tracking/index.html)
diff --git a/dev/main.js b/dev/main.ts
similarity index 71%
rename from dev/main.js
rename to dev/main.ts
index 1873161..68dea39 100644
--- a/dev/main.js
+++ b/dev/main.ts
@@ -1,7 +1,19 @@
 import { connectCloudinaryAnalytics } from 'cloudinary-video-analytics';
+
+declare global {
+  interface Window {
+    connectCloudinaryAnalytics: typeof connectCloudinaryAnalytics;
+  }
+}
+
 window.connectCloudinaryAnalytics = connectCloudinaryAnalytics;
 
-const videos = [
+interface DemoVideo {
+  url: string;
+  publicId: string;
+}
+
+const videos: DemoVideo[] = [
   {
     url: 'https://res.cloudinary.com/demo/video/upload/v1651840278/samples/cld-sample-video.mp4',
     publicId: 'samples/cld-sample-video',
@@ -17,11 +29,11 @@ const videos = [
 ];
 
 window.addEventListener('load', () => {
-  const manualVideoElement = document.getElementById('main-video-player');
+  const manualVideoElement = document.getElementById('main-video-player') as HTMLVideoElement;
   const manualCloudinaryAnalytics = connectCloudinaryAnalytics(manualVideoElement);
   const connectVideoPanel = () => {
     let currentSelectedRadioValue = '0';
-    const onMainVideoChange = (newVideoPublicId) => {
+    const onMainVideoChange = (newVideoPublicId: string) => {
       manualVideoElement.src = newVideoPublicId;
       manualCloudinaryAnalytics.startManualTracking({
         cloudName: 'demo',
@@ -29,10 +41,11 @@ window.addEventListener('load', () => {
       });
     };
 
-    document.addEventListener('input', (e) => {
-      if (e.target.getAttribute('name') === 'videoType') {
-        currentSelectedRadioValue = e.target.value;
-        onMainVideoChange(videos[currentSelectedRadioValue].url);
+    document.addEventListener('input', (e: Event) => {
+      const target = e.target as HTMLInputElement;
+      if (target.getAttribute('name') === 'videoType') {
+        currentSelectedRadioValue = target.value;
+        onMainVideoChange(videos[Number(currentSelectedRadioValue)].url);
       }
     });
   };
@@ -45,14 +58,14 @@ window.addEventListener('load', () => {
   });
 
   // connect extra videos
-  const extraVideo1Element = document.getElementById('extra-video-1');
+  const extraVideo1Element = document.getElementById('extra-video-1') as HTMLVideoElement;
   const extraVideo1CldAnalytics = connectCloudinaryAnalytics(extraVideo1Element);
   extraVideo1CldAnalytics.startManualTracking({
     cloudName: 'demo',
     publicId: videos[0].publicId,
   });
 
-  const extraVideo2Element = document.getElementById('extra-video-2');
+  const extraVideo2Element = document.getElementById('extra-video-2') as HTMLVideoElement;
   const extraVideo2CldAnalytics = connectCloudinaryAnalytics(extraVideo2Element);
   extraVideo2CldAnalytics.startManualTracking({
     cloudName: 'demo',
@@ -60,18 +73,19 @@ window.addEventListener('load', () => {
   });
 
   // auto detection
-  const autoVideoElement = document.getElementById('auto-video-player');
+  const autoVideoElement = document.getElementById('auto-video-player') as HTMLVideoElement;
   const autoCloudinaryAnalytics = connectCloudinaryAnalytics(autoVideoElement);
   const connectAutoVideoPanel = () => {
     let currentSelectedRadioValue = '0';
-    const onMainVideoChange = (newVideoPublicId) => {
+    const onMainVideoChange = (newVideoPublicId: string) => {
       autoVideoElement.src = newVideoPublicId;
     };
 
-    document.addEventListener('input', (e) => {
-      if (e.target.getAttribute('name') === 'autoVideoType') {
-        currentSelectedRadioValue = e.target.value;
-        onMainVideoChange(videos[currentSelectedRadioValue].url || '');
+    document.addEventListener('input', (e: Event) => {
+      const target = e.target as HTMLInputElement;
+      if (target.getAttribute('name') === 'autoVideoType') {
+        currentSelectedRadioValue = target.value;
+        onMainVideoChange(videos[Number(currentSelectedRadioValue)].url || '');
       }
     });
   };
@@ -87,18 +101,19 @@ window.addEventListener('load', () => {
         value: 1,
       },
     },
-    customVideoUrlFallback: (videoUrl) => {
+    customVideoUrlFallback: (videoUrl: string) => {
       if (videoUrl === 'https://res.cloudinary.com/demo/video/upload/v1692105601/dog_demo.mp4') {
         return {
           cloudName: 'fallback-cloud-name',
           publicId: 'fallback-public-id',
         };
       }
+      return undefined;
     },
   });
 
   // live stream
-  const liveStreamVideoElement = document.getElementById('live-stream-video-player');
+  const liveStreamVideoElement = document.getElementById('live-stream-video-player') as HTMLVideoElement;
   const liveStreamCldAnalytics = connectCloudinaryAnalytics(liveStreamVideoElement);
   liveStreamCldAnalytics.startManualTracking({
     cloudName: 'demo',
diff --git a/package.json b/package.json
index 63d82c3..9e0fe96 100644
--- a/package.json
+++ b/package.json
@@ -3,11 +3,14 @@
   "version": "1.8.2",
   "description": "",
   "main": "dist/main.js",
+  "types": "dist/index.d.ts",
+  "packageManager": "pnpm@10.33.2",
   "scripts": {
-    "build": "NODE_ENV=production webpack",
+    "build": "NODE_ENV=production webpack && tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "start": "webpack serve --config webpack.dev.config.js ",
     "start-server": "node ./dev/http-server.js",
-    "dev": "concurrently --kill-others \"yarn start-server\" \"yarn start\""
+    "dev": "concurrently --kill-others \"pnpm start-server\" \"pnpm start\""
   },
   "author": "Cloudinary",
   "license": "MIT",
@@ -16,13 +19,12 @@
     "uuid": "14.0.0"
   },
   "devDependencies": {
-    "@babel/core": "7.22.5",
-    "@babel/preset-env": "7.22.5",
-    "babel-loader": "9.1.2",
     "concurrently": "8.2.0",
     "html-webpack-plugin": "5.5.0",
     "http": "0.0.1-security",
     "multiparty": "4.2.3",
+    "ts-loader": "9.5.1",
+    "typescript": "5.5.4",
     "webpack": "5.88.2",
     "webpack-cli": "5.1.4",
     "webpack-dev-server": "4.15.1",
diff --git a/src/cloudinary-analytics.js b/src/cloudinary-analytics.ts
similarity index 63%
rename from src/cloudinary-analytics.js
rename to src/cloudinary-analytics.ts
index 793a11b..bb86829 100644
--- a/src/cloudinary-analytics.js
+++ b/src/cloudinary-analytics.ts
@@ -1,5 +1,6 @@
 import { isMobile } from 'is-mobile';
 import { initEventsCollector } from './events-collector';
+import type { EventsCollector } from './events-collector';
 import { getVideoViewId, getUserId } from './utils/unique-ids';
 import { sendBeaconRequest } from './utils/send-beacon-request';
 import {
@@ -9,12 +10,48 @@ import {
   createRegularVideoViewStartEvent,
   prepareEvents,
 } from './utils/events';
-import { throwErrorIfInvalid, metadataValidator, mainOptionsValidator, trackingOptionsValidator } from './utils/validators';
+import { throwErrorIfInvalid, metadataValidator, mainOptionsValidator, trackingOptionsValidator, customEventValidator } from './utils/validators';
 import { nativeHtmlVideoPlayerAdapter } from './player-adapters/nativeHtmlVideoPlayerAdapter';
 import { parseCustomerVideoData } from './utils/customer-data';
 import { createPageTracker } from './utils/page-events';
+import { CUSTOM_EVENT } from './events.consts';
+import type { MainOptions, TrackingOptions, VideoMetadata } from './types';
 
-const CLD_ANALYTICS_ENDPOINTS_LIST = {
+interface AnalyticsEndpoints {
+  default: string;
+  liveStreams: string;
+}
+
+interface ViewIdRef {
+  _value: string;
+  getValue: () => string;
+  regenerateValue: () => string;
+}
+
+interface VideoTrackingSession {
+  viewId: ViewIdRef | string;
+  type: 'auto' | 'manual';
+  subtype?: 'default' | 'live-stream';
+  clear: () => void;
+}
+
+export interface CloudinaryAnalytics {
+  startManualTracking: (metadata: VideoMetadata, options?: TrackingOptions) => void;
+  stopManualTracking: () => void;
+  startAutoTracking: (options?: TrackingOptions) => void;
+  stopAutoTracking: () => void;
+  /** Stops whichever tracking (manual or auto) is currently active. */
+  stopTracking: () => void;
+  /**
+   * Reports a consumer-defined event into the current video view (e.g. an
+   * "on screen" / viewability signal from a player integration). It is attached
+   * to the active view and shipped in the same payload, so it can be correlated
+   * with built-in events by time. No-op when no view is currently being tracked.
+   */
+  reportCustomEvent: (name: string, data?: Record<string, unknown>) => void;
+}
+
+const CLD_ANALYTICS_ENDPOINTS_LIST: Record<'production' | 'development', AnalyticsEndpoints> = {
   production: {
     default: 'https://video-analytics-api.cloudinary.com/v1/video-analytics',
     liveStreams: 'https://video-analytics-api.cloudinary.com/v1/live-streams',
@@ -26,7 +63,10 @@ const CLD_ANALYTICS_ENDPOINTS_LIST = {
 };
 const CLD_ANALYTICS_ENDPOINT = process.env.NODE_ENV === 'development' ? CLD_ANALYTICS_ENDPOINTS_LIST.development : CLD_ANALYTICS_ENDPOINTS_LIST.production;
 
-export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
+export const connectCloudinaryAnalytics = (
+  videoElement: HTMLVideoElement,
+  mainOptions: MainOptions = {},
+): CloudinaryAnalytics => {
   throwErrorIfInvalid(
     mainOptionsValidator(mainOptions),
     'Cloudinary video analytics requires proper options object'
@@ -36,18 +76,39 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
     mainOptions.playerAdapter = nativeHtmlVideoPlayerAdapter(videoElement);
   }
 
-  let videoTrackingSession = null;
+  let videoTrackingSession: VideoTrackingSession | null = null;
+  // Points at the collector of the currently tracked view (regular/auto only),
+  // so custom events can be attached to it. Null for live streams and when no
+  // view is active.
+  let activeEventCollector: EventsCollector | null = null;
   const userId = getUserId();
-  const { playerAdapter } = mainOptions;
+  const playerAdapter = mainOptions.playerAdapter;
   const isMobileDetected = isMobile({ tablet: true, featureDetect: true });
   const createEventsCollector = initEventsCollector(playerAdapter);
-  const clearVideoTracking = () => {
+  const clearVideoTracking = (): void => {
     if (videoTrackingSession) {
       videoTrackingSession.clear();
       videoTrackingSession = null;
     }
+    activeEventCollector = null;
+  };
+
+  const reportCustomEvent = (name: string, data: Record<string, unknown> = {}): void => {
+    throwErrorIfInvalid(
+      customEventValidator(name, data),
+      'Cloudinary video analytics custom event is invalid'
+    );
+
+    // Only attributable while a view is actively collecting; otherwise ignored.
+    if (activeEventCollector?.isCollecting()) {
+      activeEventCollector.addEvent({
+        eventName: CUSTOM_EVENT,
+        eventTime: Date.now(),
+        eventDetails: { name, data },
+      });
+    }
   };
-  const viewId = {
+  const viewId: ViewIdRef = {
     _value: getVideoViewId(),
     getValue: () => viewId._value,
     regenerateValue: () => {
@@ -61,7 +122,7 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
     },
   };
 
-  const startManualTracking = (metadata, options = {}) => {
+  const startManualTracking = (metadata: VideoMetadata, options: TrackingOptions = {}): void => {
     if (videoTrackingSession?.type === 'auto') {
       throw 'Cloudinary video analytics auto tracking is already connected with this HTML Video Element, to start manual tracking you need to stop auto tracking';
     }
@@ -85,13 +146,17 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
     }
   };
 
-  const _startManualTrackingRegularVideo = (metadata, options) => {
-    const sendData = (data) => sendBeaconRequest(CLD_ANALYTICS_ENDPOINT.default, data);
+  const _startManualTrackingRegularVideo = (_metadata: VideoMetadata, options: TrackingOptions): void => {
+    const sendData = (data: Record<string, unknown>) => sendBeaconRequest(CLD_ANALYTICS_ENDPOINT.default, data);
     const videoViewEventCollector = createEventsCollector();
+    activeEventCollector = videoViewEventCollector;
     const finishVideoTracking = () => {
       // multiple events can be triggered one by one for specific browsers but we don't have guarantee which ones
       // in this case send data for first event and for rest just skip it to avoid empty payload
       if (videoViewEventCollector.getCollectedEventsCount() > 0) {
+        // Let registrars emit their end-of-view summaries before viewEnd, so
+        // viewEnd remains the last event in the payload.
+        videoViewEventCollector.finalize();
         videoViewEventCollector.addEvent(createRegularVideoViewEndEvent());
         const events = prepareEvents([...videoViewEventCollector.flushEvents()]);
         sendData({
@@ -131,9 +196,12 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
       },
     };
   };
-  const _startManualTrackingLiveStream = (metadata, options) => {
+  const _startManualTrackingLiveStream = (metadata: VideoMetadata, options: TrackingOptions): void => {
+    // Live streams don't use an events collector (events are sent immediately),
+    // so custom events are not attributable here.
+    activeEventCollector = null;
     const liveStreamData = parseCustomerVideoData(metadata);
-    const sendLiveStreamEvent = (event) => {
+    const sendLiveStreamEvent = (event: ReturnType<typeof createLiveStreamViewStartEvent>) => {
       sendBeaconRequest(CLD_ANALYTICS_ENDPOINT.liveStreams, {
         userId,
         viewId: viewId.getValue(),
@@ -165,7 +233,7 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
     };
   };
 
-  const startAutoTracking = (options = {}) => {
+  const startAutoTracking = (options: TrackingOptions = {}): void => {
     if (videoTrackingSession) {
       throw 'Cloudinary video analytics tracking is already connected with this HTML Video Element';
     }
@@ -175,13 +243,17 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
       'Cloudinary video analytics auto tracking called with invalid options'
     );
 
-    const sendData = (data) => sendBeaconRequest(CLD_ANALYTICS_ENDPOINT.default, data);
+    const sendData = (data: Record<string, unknown>) => sendBeaconRequest(CLD_ANALYTICS_ENDPOINT.default, data);
     const videoViewEventCollector = createEventsCollector();
+    activeEventCollector = videoViewEventCollector;
 
     const finishVideoTracking = () => {
       // multiple events can be triggered one by one for specific browsers but we don't have guarantee which ones
       // in this case send data for first event and for rest just skip it to avoid empty payload
       if (videoViewEventCollector.getCollectedEventsCount() > 0) {
+        // Let registrars emit their end-of-view summaries before viewEnd, so
+        // viewEnd remains the last event in the payload.
+        videoViewEventCollector.finalize();
         videoViewEventCollector.addEvent(createRegularVideoViewEndEvent());
         const events = prepareEvents([...videoViewEventCollector.flushEvents()]);
         sendData({
@@ -192,7 +264,7 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
       }
     };
 
-    const startVideoTracking = () => {
+    const startVideoTracking = (): null | void => {
       const sourceUrl = playerAdapter.getCurrentSrc();
       if (sourceUrl === window.location.href || !sourceUrl) {
         return null;
@@ -234,5 +306,8 @@ export const connectCloudinaryAnalytics = (videoElement, mainOptions = {}) => {
     startManualTracking,
     stopManualTracking: clearVideoTracking,
     startAutoTracking,
+    stopAutoTracking: clearVideoTracking,
+    stopTracking: clearVideoTracking,
+    reportCustomEvent,
   };
 };
diff --git a/src/events-collector.js b/src/events-collector.js
deleted file mode 100644
index d83b41d..0000000
--- a/src/events-collector.js
+++ /dev/null
@@ -1,70 +0,0 @@
-import { registerPlayEvent } from './events/play-event';
-import { registerPauseEvent } from './events/pause-event';
-import { registerMetadataEvent } from './events/metadata-event';
-import { createEvent } from './utils/events';
-
-export const initEventsCollector = (playerAdapter) => {
-  const collectedEvents = {};
-  const rawEvents = {};
-
-  return () => {
-    let viewId = null;
-    const registeredEvents = [];
-
-    const start = (_viewId) => {
-      if (viewId) {
-        throw new Error('Events collector session already started');
-      }
-
-      // create new collection of events for new video view
-      viewId = _viewId;
-      collectedEvents[viewId] = [];
-      rawEvents[viewId] = [];
-      registeredEvents.push(
-        registerPlayEvent(playerAdapter, reportEvent),
-        registerPauseEvent(playerAdapter, reportEvent),
-        registerMetadataEvent(playerAdapter, reportEvent),
-      );
-    };
-    const destroy = () => {
-      if (!viewId) {
-        throw new Error('Events collector session not started');
-      }
-
-      registeredEvents.forEach((cb) => cb());
-      viewId = null;
-    };
-    const reportEvent = (eventName, eventDetails) => {
-      if (!viewId) {
-        throw new Error('Events collector session not started');
-      }
-
-      rawEvents[viewId].push(createEvent(eventName, eventDetails));
-    };
-    const flushEvents = () => {
-      if (!viewId) {
-        throw new Error('Events collector session not started');
-      }
-
-      const events = rawEvents[viewId].splice(0, rawEvents[viewId].length);
-      collectedEvents[viewId].splice(collectedEvents[viewId].length, 0, ...events);
-      return events;
-    };
-
-    const getCollectedEventsCount = () => {
-      if (viewId) {
-        return rawEvents[viewId]?.length || 0;
-      }
-
-      return 0;
-    };
-
-    return {
-      flushEvents,
-      getCollectedEventsCount,
-      addEvent: ({ eventName, eventDetails }) => reportEvent(eventName, eventDetails),
-      start,
-      destroy,
-    };
-  }
-};
diff --git a/src/events-collector.ts b/src/events-collector.ts
new file mode 100644
index 0000000..2a49d0f
--- /dev/null
+++ b/src/events-collector.ts
@@ -0,0 +1,145 @@
+import { registerPlayEvent } from './events/play-event';
+import { registerPauseEvent } from './events/pause-event';
+import { registerMetadataEvent } from './events/metadata-event';
+import { registerStartupEvent } from './events/startup-event';
+import { registerEndedEvent } from './events/ended-event';
+import { registerBufferingEvent } from './events/buffering-event';
+import { registerQualityChangeEvent } from './events/quality-change-event';
+import { registerErrorEvent } from './events/error-event';
+import { registerFullscreenEvent } from './events/fullscreen-event';
+import { registerPictureInPictureEvent } from './events/picture-in-picture-event';
+import { createEvent } from './utils/events';
+import { VIDEO_EVENT } from './events.consts';
+import type { AnalyticsEvent, PlayerAdapter, UnregisterEvent } from './types';
+
+// Hard upper bound on events collected per view. A single beacon must stay well
+// under the browser sendBeacon size limit (~64KB across queued beacons); past
+// this the browser drops the whole payload. Normal views emit well under 50.
+const MAX_EVENTS_PER_VIEW = 250;
+
+export interface EventsCollector {
+  flushEvents: () => AnalyticsEvent[];
+  getCollectedEventsCount: () => number;
+  addEvent: (event: AnalyticsEvent) => void;
+  isCollecting: () => boolean;
+  finalize: () => void;
+  start: (viewId: string) => void;
+  destroy: () => void;
+}
+
+export const initEventsCollector = (playerAdapter: PlayerAdapter): (() => EventsCollector) => {
+  const collectedEvents: Record<string, AnalyticsEvent[]> = {};
+  const rawEvents: Record<string, AnalyticsEvent[]> = {};
+
+  return (): EventsCollector => {
+    let viewId: string | null = null;
+    let truncated = false;
+    let finalized = false;
+    const registeredEvents: UnregisterEvent[] = [];
+    const finalizers: Array<() => void> = [];
+    const registerFinalizer = (finalizer: () => void): void => {
+      finalizers.push(finalizer);
+    };
+
+    const start = (_viewId: string): void => {
+      if (viewId) {
+        throw new Error('Events collector session already started');
+      }
+
+      // create new collection of events for new video view
+      viewId = _viewId;
+      truncated = false;
+      finalized = false;
+      // Previous listeners were already removed on destroy(); drop their stale
+      // removers so the arrays don't grow across re-views (e.g. mobile tab
+      // visibility toggling).
+      registeredEvents.length = 0;
+      finalizers.length = 0;
+      collectedEvents[viewId] = [];
+      rawEvents[viewId] = [];
+      registeredEvents.push(
+        registerPlayEvent(playerAdapter, reportEvent),
+        registerPauseEvent(playerAdapter, reportEvent),
+        registerMetadataEvent(playerAdapter, reportEvent),
+        registerStartupEvent(playerAdapter, reportEvent),
+        registerEndedEvent(playerAdapter, reportEvent),
+        registerBufferingEvent(playerAdapter, reportEvent, registerFinalizer),
+        registerQualityChangeEvent(playerAdapter, reportEvent),
+        registerErrorEvent(playerAdapter, reportEvent),
+        registerFullscreenEvent(playerAdapter, reportEvent),
+        registerPictureInPictureEvent(playerAdapter, reportEvent),
+      );
+    };
+    const destroy = (): void => {
+      // Idempotent: a view can be ended more than once (e.g. onPageViewEnd then
+      // an explicit stop), so a second destroy is a no-op rather than an error.
+      if (!viewId) {
+        return;
+      }
+
+      registeredEvents.forEach((cb) => cb());
+      // The collected/raw events for this view have already been flushed and
+      // sent; drop them so the maps don't grow unbounded over a session's views.
+      delete collectedEvents[viewId];
+      delete rawEvents[viewId];
+      viewId = null;
+    };
+    const reportEvent = (eventName: string, eventDetails: Record<string, unknown>): void => {
+      if (!viewId) {
+        throw new Error('Events collector session not started');
+      }
+
+      const totalCount = collectedEvents[viewId].length + rawEvents[viewId].length;
+      if (totalCount >= MAX_EVENTS_PER_VIEW) {
+        // Drop further events, but emit a single marker so the backend can tell
+        // the view's data was capped rather than genuinely complete.
+        if (!truncated) {
+          truncated = true;
+          rawEvents[viewId].push(createEvent(VIDEO_EVENT.TRUNCATED, { limit: MAX_EVENTS_PER_VIEW }));
+        }
+        return;
+      }
+
+      rawEvents[viewId].push(createEvent(eventName, eventDetails));
+    };
+    // Give registrars a chance to contribute an end-of-view summary. Runs once
+    // per view; the core calls it before adding the viewEnd event, and
+    // flushEvents calls it as a fallback in case it was not invoked explicitly.
+    const finalize = (): void => {
+      if (finalized) {
+        return;
+      }
+      finalized = true;
+      finalizers.forEach((finalizer) => finalizer());
+    };
+    const flushEvents = (): AnalyticsEvent[] => {
+      if (!viewId) {
+        throw new Error('Events collector session not started');
+      }
+
+      finalize();
+
+      const events = rawEvents[viewId].splice(0, rawEvents[viewId].length);
+      collectedEvents[viewId].splice(collectedEvents[viewId].length, 0, ...events);
+      return events;
+    };
+
+    const getCollectedEventsCount = (): number => {
+      if (viewId) {
+        return rawEvents[viewId]?.length || 0;
+      }
+
+      return 0;
+    };
+
+    return {
+      flushEvents,
+      getCollectedEventsCount,
+      addEvent: ({ eventName, eventDetails }: AnalyticsEvent) => reportEvent(eventName, eventDetails),
+      isCollecting: () => viewId !== null,
+      finalize,
+      start,
+      destroy,
+    };
+  };
+};
diff --git a/src/events.consts.js b/src/events.consts.js
deleted file mode 100644
index 86a7dfb..0000000
--- a/src/events.consts.js
+++ /dev/null
@@ -1,10 +0,0 @@
-export const VIDEO_EVENT = {
-  PLAY: 'play',
-  PAUSE: 'pause',
-  LOADED_METADATA: 'loadMetadata',
-};
-
-export const VIEW_EVENT = {
-  START: 'viewStart',
-  END: 'viewEnd',
-};
diff --git a/src/events.consts.ts b/src/events.consts.ts
new file mode 100644
index 0000000..07f9bc4
--- /dev/null
+++ b/src/events.consts.ts
@@ -0,0 +1,26 @@
+export const VIDEO_EVENT = {
+  PLAY: 'play',
+  PAUSE: 'pause',
+  ENDED: 'ended',
+  LOADED_METADATA: 'loadMetadata',
+  // Quality of experience
+  STARTUP: 'startup',
+  BUFFERING: 'buffering',
+  QUALITY_CHANGE: 'qualityChange',
+  ERROR: 'error',
+  // Engagement
+  FULLSCREEN_CHANGE: 'fullscreenChange',
+  PICTURE_IN_PICTURE_CHANGE: 'pictureInPictureChange',
+  // Emitted once when a view's event count hits the per-view safety cap
+  TRUNCATED: 'truncated',
+} as const;
+
+export const VIEW_EVENT = {
+  START: 'viewStart',
+  END: 'viewEnd',
+} as const;
+
+// Wrapper event for consumer-reported custom events. The consumer's name and
+// payload live in eventDetails ({ name, data }) so they are namespaced away
+// from — and cannot collide with — the built-in event names above.
+export const CUSTOM_EVENT = 'custom';
diff --git a/src/events/buffering-event.ts b/src/events/buffering-event.ts
new file mode 100644
index 0000000..aa75d0f
--- /dev/null
+++ b/src/events/buffering-event.ts
@@ -0,0 +1,182 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, RegisterFinalizer, ReportEvent, UnregisterEvent } from '../types';
+
+// Playback must stay healthy this long after `playing` before we consider a
+// buffering episode over. Real players flap (waiting→playing→waiting…) many
+// times per rough patch; this grace period merges that burst into one episode.
+const RECOVERY_GRACE_MS = 500;
+// Episodes shorter than this are seek jitter / micro-stalls, not real
+// rebuffering, and are dropped entirely.
+const MIN_BUFFERING_MS = 300;
+// Upper bound on the number of exact per-episode records kept. Totals are still
+// computed over every episode; only the detail array is capped so the single
+// end-of-view event cannot grow unbounded.
+const MAX_OCCURRENCES = 20;
+
+// Stalls that happen before playback ever starts are startup/join time (see
+// startup-event.ts), not rebuffering, so buffering only tracks two causes:
+// - `seek`     : buffering caused by the user jumping to an un-buffered position
+// - `rebuffer` : buffering during normal playback — the true QoE signal
+type BufferingCause = 'seek' | 'rebuffer';
+// How an episode ended — lets the backend separate tolerated stalls (recovery)
+// from abandonment-during-buffer (pause / viewEnd with no resume).
+type BufferingEnd = 'recovery' | 'pause' | 'viewEnd';
+
+interface BufferingOccurrence {
+  atTime: number;
+  duration: number;
+  cause: BufferingCause;
+  endedBy: BufferingEnd;
+}
+
+interface CauseTotals {
+  count: number;
+  totalDuration: number;
+}
+
+// Buffering is derived from `waiting`/`stalled` (stall begins) and `playing`
+// (candidate recovery, debounced so a flapping burst counts as one episode).
+// Episodes are accumulated, classified by cause, and emitted as a single
+// authoritative summary at view end: exact totals over every episode, a
+// per-cause breakdown, and a bounded array of detail (incl. a stall still in
+// progress at exit). Pre-playback stalls are ignored (they are join time), and
+// a user pause ends the current episode so paused time is never counted.
+export const registerBufferingEvent = (
+  playerAdapter: PlayerAdapter,
+  reportEvent: ReportEvent,
+  registerFinalizer: RegisterFinalizer,
+): UnregisterEvent => {
+  let episodeStartTime: number | null = null;
+  let episodeCause: BufferingCause = 'rebuffer';
+  let pendingRecoveryTime: number | null = null;
+  let recoveryTimerId: ReturnType<typeof setTimeout> | null = null;
+
+  let hasStartedPlayback = false;
+  let isSeeking = false;
+
+  let count = 0;
+  let totalDuration = 0;
+  let maxDuration = 0;
+  const byCause: Record<BufferingCause, CauseTotals> = {
+    seek: { count: 0, totalDuration: 0 },
+    rebuffer: { count: 0, totalDuration: 0 },
+  };
+  const occurrences: BufferingOccurrence[] = [];
+
+  const clearRecoveryTimer = () => {
+    if (recoveryTimerId !== null) {
+      clearTimeout(recoveryTimerId);
+      recoveryTimerId = null;
+    }
+  };
+
+  const classifyCause = (): BufferingCause => (isSeeking ? 'seek' : 'rebuffer');
+
+  const recordEpisode = (atTime: number, duration: number, cause: BufferingCause, endedBy: BufferingEnd) => {
+    if (duration < MIN_BUFFERING_MS) {
+      return;
+    }
+
+    count += 1;
+    totalDuration += duration;
+    maxDuration = Math.max(maxDuration, duration);
+    byCause[cause].count += 1;
+    byCause[cause].totalDuration += duration;
+    if (occurrences.length < MAX_OCCURRENCES) {
+      occurrences.push({ atTime, duration, cause, endedBy });
+    }
+  };
+
+  const endEpisode = (endTime: number, endedBy: BufferingEnd) => {
+    clearRecoveryTimer();
+    if (episodeStartTime === null) {
+      return;
+    }
+
+    recordEpisode(episodeStartTime, endTime - episodeStartTime, episodeCause, endedBy);
+    episodeStartTime = null;
+    pendingRecoveryTime = null;
+  };
+
+  // A stall begins (or relapses during the grace period): (re)enter the episode.
+  const onStall = () => {
+    clearRecoveryTimer();
+    pendingRecoveryTime = null;
+    // Stalls before the first frame are startup/join time, not rebuffering.
+    if (!hasStartedPlayback) {
+      return;
+    }
+    if (episodeStartTime === null) {
+      episodeStartTime = Date.now();
+      episodeCause = classifyCause();
+    }
+  };
+
+  // Confirmed recovery: playback stayed healthy for the whole grace period.
+  const onPlaying = () => {
+    hasStartedPlayback = true;
+    if (episodeStartTime === null) {
+      return;
+    }
+
+    pendingRecoveryTime = Date.now();
+    clearRecoveryTimer();
+    recoveryTimerId = setTimeout(() => endEpisode(pendingRecoveryTime as number, 'recovery'), RECOVERY_GRACE_MS);
+  };
+
+  // A user pause interrupts a stall: end the episode now so paused time (until a
+  // later resume fires `playing`) is not counted as buffering.
+  const onPause = () => {
+    if (episodeStartTime === null) {
+      return;
+    }
+    endEpisode(pendingRecoveryTime !== null ? pendingRecoveryTime : Date.now(), 'pause');
+  };
+
+  const onSeeking = () => {
+    isSeeking = true;
+  };
+  const onSeeked = () => {
+    isSeeking = false;
+  };
+
+  // Emit the single summary right before the view's events are flushed.
+  const finalize = () => {
+    clearRecoveryTimer();
+
+    // Close out a stall still in progress when the view ends.
+    if (episodeStartTime !== null) {
+      recordEpisode(episodeStartTime, Date.now() - episodeStartTime, episodeCause, 'viewEnd');
+      episodeStartTime = null;
+      pendingRecoveryTime = null;
+    }
+
+    if (count === 0) {
+      return;
+    }
+
+    reportEvent(VIDEO_EVENT.BUFFERING, {
+      count,
+      totalDuration,
+      maxDuration,
+      byCause,
+      occurrences,
+      occurrencesTruncated: count > occurrences.length,
+    });
+  };
+
+  const removeListeners = [
+    playerAdapter.onWaiting(onStall),
+    playerAdapter.onStalled(onStall),
+    playerAdapter.onPlaying(onPlaying),
+    playerAdapter.onPause(onPause),
+    playerAdapter.onSeeking(onSeeking),
+    playerAdapter.onSeeked(onSeeked),
+  ];
+  registerFinalizer(finalize);
+
+  return () => {
+    clearRecoveryTimer();
+    removeListeners.forEach((removeListener) => removeListener());
+  };
+};
diff --git a/src/events/ended-event.ts b/src/events/ended-event.ts
new file mode 100644
index 0000000..bf53a00
--- /dev/null
+++ b/src/events/ended-event.ts
@@ -0,0 +1,31 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+// Playback reached the natural end. This marks completion and bounds the final
+// playing span for watch-time calculations.
+//
+// Repeats: a looping video (`loop`) never fires `ended` at all — it seeks back
+// and keeps playing — so loops produce no events here. A genuine replay (user
+// restarts a finished video) SHOULD count as another completion, so we reset on
+// the next `playing`. What we guard against is a spurious duplicate `ended`
+// firing with no playback in between, which is ignored.
+export const registerEndedEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  let endedSinceLastPlayback = false;
+
+  const eventPlayingClearCallback = playerAdapter.onPlaying(() => {
+    endedSinceLastPlayback = false;
+  });
+  const eventEndedClearCallback = playerAdapter.onEnded(() => {
+    if (endedSinceLastPlayback) {
+      return;
+    }
+
+    endedSinceLastPlayback = true;
+    reportEvent(VIDEO_EVENT.ENDED, {});
+  });
+
+  return () => {
+    eventPlayingClearCallback();
+    eventEndedClearCallback();
+  };
+};
diff --git a/src/events/error-event.ts b/src/events/error-event.ts
new file mode 100644
index 0000000..04faaab
--- /dev/null
+++ b/src/events/error-event.ts
@@ -0,0 +1,16 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+export const registerErrorEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  const eventErrorClearCallback = playerAdapter.onError(() => {
+    const error = playerAdapter.getError();
+    reportEvent(VIDEO_EVENT.ERROR, {
+      errorCode: error ? error.code : null,
+      errorMessage: error ? error.message : null,
+    });
+  });
+
+  return () => {
+    eventErrorClearCallback();
+  };
+};
diff --git a/src/events/fullscreen-event.ts b/src/events/fullscreen-event.ts
new file mode 100644
index 0000000..424b28f
--- /dev/null
+++ b/src/events/fullscreen-event.ts
@@ -0,0 +1,24 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+// The Fullscreen API dispatches `fullscreenchange` on `document`, so on a page
+// with several tracked videos every adapter hears every video's transition. We
+// only report when *this* element's fullscreen state actually changed, so an
+// unrelated video going fullscreen doesn't emit a spurious event here.
+export const registerFullscreenEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  let lastIsFullscreen = playerAdapter.getIsFullscreen();
+
+  const eventFullscreenClearCallback = playerAdapter.onFullscreenChange(() => {
+    const isFullscreen = playerAdapter.getIsFullscreen();
+    if (isFullscreen === lastIsFullscreen) {
+      return;
+    }
+
+    lastIsFullscreen = isFullscreen;
+    reportEvent(VIDEO_EVENT.FULLSCREEN_CHANGE, { isFullscreen });
+  });
+
+  return () => {
+    eventFullscreenClearCallback();
+  };
+};
diff --git a/src/events/metadata-event.js b/src/events/metadata-event.ts
similarity index 72%
rename from src/events/metadata-event.js
rename to src/events/metadata-event.ts
index 65b32ea..5b507ef 100644
--- a/src/events/metadata-event.js
+++ b/src/events/metadata-event.ts
@@ -1,11 +1,12 @@
 import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
 
-export const parseVideoDuration = (durationValue) => {
+export const parseVideoDuration = (durationValue: number): number | 'Infinity' | null => {
   const videoDuration = Number.isNaN(durationValue) ? null : durationValue;
   return Number.POSITIVE_INFINITY === videoDuration ? 'Infinity' : videoDuration;
 };
 
-export const registerMetadataEvent = (playerAdapter, reportEvent) => {
+export const registerMetadataEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
   const reportLoadedMetadata = () => {
     reportEvent(VIDEO_EVENT.LOADED_METADATA, {
       videoDuration: parseVideoDuration(playerAdapter.getDuration()),
diff --git a/src/events/pause-event.js b/src/events/pause-event.ts
similarity index 65%
rename from src/events/pause-event.js
rename to src/events/pause-event.ts
index d432d89..3ceeee9 100644
--- a/src/events/pause-event.js
+++ b/src/events/pause-event.ts
@@ -1,6 +1,7 @@
 import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
 
-export const registerPauseEvent = (playerAdapter, reportEvent) => {
+export const registerPauseEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
   const eventPauseClearCallback = playerAdapter.onPause(() => {
     reportEvent(VIDEO_EVENT.PAUSE, {});
   });
diff --git a/src/events/picture-in-picture-event.ts b/src/events/picture-in-picture-event.ts
new file mode 100644
index 0000000..3af1803
--- /dev/null
+++ b/src/events/picture-in-picture-event.ts
@@ -0,0 +1,16 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+export const registerPictureInPictureEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  const eventEnterClearCallback = playerAdapter.onEnterPictureInPicture(() => {
+    reportEvent(VIDEO_EVENT.PICTURE_IN_PICTURE_CHANGE, { isPictureInPicture: true });
+  });
+  const eventLeaveClearCallback = playerAdapter.onLeavePictureInPicture(() => {
+    reportEvent(VIDEO_EVENT.PICTURE_IN_PICTURE_CHANGE, { isPictureInPicture: false });
+  });
+
+  return () => {
+    eventEnterClearCallback();
+    eventLeaveClearCallback();
+  };
+};
diff --git a/src/events/play-event.js b/src/events/play-event.ts
similarity index 52%
rename from src/events/play-event.js
rename to src/events/play-event.ts
index 381ff33..7780c93 100644
--- a/src/events/play-event.js
+++ b/src/events/play-event.ts
@@ -1,6 +1,7 @@
 import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
 
-export const registerPlayEvent = (playerAdapter, reportEvent) => {
+export const registerPlayEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
   const eventPlayClearCallback = playerAdapter.onPlay(() => {
     reportEvent(VIDEO_EVENT.PLAY, {});
   });
diff --git a/src/events/quality-change-event.ts b/src/events/quality-change-event.ts
new file mode 100644
index 0000000..707036c
--- /dev/null
+++ b/src/events/quality-change-event.ts
@@ -0,0 +1,46 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+// Debounce window: adaptive-bitrate players can fire a burst of `resize` events
+// while the ladder settles. We wait for it to quiet down and only report the
+// resolution the video actually ended up at.
+const RESIZE_DEBOUNCE_MS = 1000;
+
+// The `resize` event fires whenever the decoded video dimensions change, which
+// is the native signal for an adaptive-bitrate / resolution switch. We debounce
+// the burst and skip no-op changes so a long streaming session cannot flood the
+// payload with quality events.
+export const registerQualityChangeEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  let debounceTimerId: ReturnType<typeof setTimeout> | null = null;
+  let lastWidth: number | null = null;
+  let lastHeight: number | null = null;
+
+  const reportQualityChange = () => {
+    debounceTimerId = null;
+    const videoWidth = playerAdapter.getVideoWidth();
+    const videoHeight = playerAdapter.getVideoHeight();
+
+    if (videoWidth === lastWidth && videoHeight === lastHeight) {
+      return;
+    }
+
+    lastWidth = videoWidth;
+    lastHeight = videoHeight;
+    reportEvent(VIDEO_EVENT.QUALITY_CHANGE, { videoWidth, videoHeight });
+  };
+
+  const eventResizeClearCallback = playerAdapter.onResize(() => {
+    if (debounceTimerId !== null) {
+      clearTimeout(debounceTimerId);
+    }
+    debounceTimerId = setTimeout(reportQualityChange, RESIZE_DEBOUNCE_MS);
+  });
+
+  return () => {
+    if (debounceTimerId !== null) {
+      clearTimeout(debounceTimerId);
+      debounceTimerId = null;
+    }
+    eventResizeClearCallback();
+  };
+};
diff --git a/src/events/startup-event.ts b/src/events/startup-event.ts
new file mode 100644
index 0000000..fddd80e
--- /dev/null
+++ b/src/events/startup-event.ts
@@ -0,0 +1,31 @@
+import { VIDEO_EVENT } from '../events.consts';
+import type { PlayerAdapter, ReportEvent, UnregisterEvent } from '../types';
+
+// Startup (join) time: the delay from play intent (`play`) to the first rendered
+// frame (`playing`). This is measured directly rather than inferred from a
+// `waiting` stall, which browsers emit inconsistently during startup. Emitted
+// once per view. A view with a `play` event but no `startup` event means
+// playback never began — a startup failure.
+export const registerStartupEvent = (playerAdapter: PlayerAdapter, reportEvent: ReportEvent): UnregisterEvent => {
+  let playIntentTime: number | null = null;
+  let reported = false;
+
+  const eventPlayClearCallback = playerAdapter.onPlay(() => {
+    if (playIntentTime === null) {
+      playIntentTime = Date.now();
+    }
+  });
+  const eventPlayingClearCallback = playerAdapter.onPlaying(() => {
+    if (reported || playIntentTime === null) {
+      return;
+    }
+
+    reported = true;
+    reportEvent(VIDEO_EVENT.STARTUP, { joinTime: Date.now() - playIntentTime });
+  });
+
+  return () => {
+    eventPlayClearCallback();
+    eventPlayingClearCallback();
+  };
+};
diff --git a/src/index.js b/src/index.js
deleted file mode 100644
index 0ba691e..0000000
--- a/src/index.js
+++ /dev/null
@@ -1 +0,0 @@
-export { connectCloudinaryAnalytics } from './cloudinary-analytics';
diff --git a/src/index.ts b/src/index.ts
new file mode 100644
index 0000000..e62ac50
--- /dev/null
+++ b/src/index.ts
@@ -0,0 +1,13 @@
+export { connectCloudinaryAnalytics } from './cloudinary-analytics';
+export type { CloudinaryAnalytics } from './cloudinary-analytics';
+export type {
+  PlayerAdapter,
+  PlayerEventCallback,
+  RemoveListener,
+  MainOptions,
+  TrackingOptions,
+  VideoMetadata,
+  CustomData,
+  CustomerVideoData,
+  VideoPlayerType,
+} from './types';
diff --git a/src/player-adapters/nativeHtmlVideoPlayerAdapter.js b/src/player-adapters/nativeHtmlVideoPlayerAdapter.js
deleted file mode 100644
index b8cd2f2..0000000
--- a/src/player-adapters/nativeHtmlVideoPlayerAdapter.js
+++ /dev/null
@@ -1,36 +0,0 @@
-const createBaseOnEventListener = (videoElement, eventName, callback) => {
-  videoElement.addEventListener(eventName, callback);
-  return () => {
-    videoElement.removeEventListener(eventName, callback);
-  };
-};
-
-export const nativeHtmlVideoPlayerAdapter = (videoElement) => ({
-  onCanPlay: (callback) => createBaseOnEventListener(videoElement, 'canplay', callback),
-  onCanPlayThrough: (callback) => createBaseOnEventListener(videoElement, 'canplaythrough', callback),
-  onComplete: (callback) => createBaseOnEventListener(videoElement, 'complete', callback),
-  onDurationChange: (callback) => createBaseOnEventListener(videoElement, 'durationchange', callback),
-  onEmptied: (callback) => createBaseOnEventListener(videoElement, 'emptied', callback),
-  onEnded: (callback) => createBaseOnEventListener(videoElement, 'ended', callback),
-  onError: (callback) => createBaseOnEventListener(videoElement, 'error', callback),
-  onLoadedData: (callback) => createBaseOnEventListener(videoElement, 'loadeddata', callback),
-  onLoadedMetadata: (callback) => createBaseOnEventListener(videoElement, 'loadedmetadata', callback),
-  onLoadStart: (callback) => createBaseOnEventListener(videoElement, 'loadstart', callback),
-  onPause: (callback) => createBaseOnEventListener(videoElement, 'pause', callback),
-  onPlay: (callback) => createBaseOnEventListener(videoElement, 'play', callback),
-  onPlaying: (callback) => createBaseOnEventListener(videoElement, 'playing', callback),
-  onProgress: (callback) => createBaseOnEventListener(videoElement, 'progress', callback),
-  onRateChange: (callback) => createBaseOnEventListener(videoElement, 'ratechange', callback),
-  onSeeked: (callback) => createBaseOnEventListener(videoElement, 'seeked', callback),
-  onSeeking: (callback) => createBaseOnEventListener(videoElement, 'seeking', callback),
-  onStalled: (callback) => createBaseOnEventListener(videoElement, 'stalled', callback),
-  onSuspend: (callback) => createBaseOnEventListener(videoElement, 'suspend', callback),
-  onTimeUpdate: (callback) => createBaseOnEventListener(videoElement, 'timeupdate', callback),
-  onVolumeChange: (callback) => createBaseOnEventListener(videoElement, 'volumechange', callback),
-  onWaiting: (callback) => createBaseOnEventListener(videoElement, 'waiting', callback),
-
-  getCurrentSrc: () => videoElement.currentSrc,
-  getCurrentTime: () => videoElement.currentTime,
-  getReadyState: () => videoElement.readyState,
-  getDuration: () => videoElement.duration,
-});
diff --git a/src/player-adapters/nativeHtmlVideoPlayerAdapter.ts b/src/player-adapters/nativeHtmlVideoPlayerAdapter.ts
new file mode 100644
index 0000000..8d5cf0f
--- /dev/null
+++ b/src/player-adapters/nativeHtmlVideoPlayerAdapter.ts
@@ -0,0 +1,80 @@
+import type { PlayerAdapter, PlayerEventCallback, RemoveListener } from '../types';
+
+// iOS Safari does not fire the standard `fullscreenchange` on `document`; it
+// dispatches non-standard events on the video element and exposes fullscreen
+// state via `webkitDisplayingFullscreen`. These are not in the DOM lib types.
+type IosFullscreenVideoElement = HTMLVideoElement & {
+  webkitDisplayingFullscreen?: boolean;
+};
+
+const createBaseOnEventListener = (
+  target: EventTarget,
+  eventName: string,
+  callback: PlayerEventCallback,
+): RemoveListener => {
+  target.addEventListener(eventName, callback);
+  return () => {
+    target.removeEventListener(eventName, callback);
+  };
+};
+
+export const nativeHtmlVideoPlayerAdapter = (videoElement: HTMLVideoElement): PlayerAdapter => ({
+  // Loading / source lifecycle
+  onAbort: (callback) => createBaseOnEventListener(videoElement, 'abort', callback),
+  onCanPlay: (callback) => createBaseOnEventListener(videoElement, 'canplay', callback),
+  onCanPlayThrough: (callback) => createBaseOnEventListener(videoElement, 'canplaythrough', callback),
+  onDurationChange: (callback) => createBaseOnEventListener(videoElement, 'durationchange', callback),
+  onEmptied: (callback) => createBaseOnEventListener(videoElement, 'emptied', callback),
+  onEnded: (callback) => createBaseOnEventListener(videoElement, 'ended', callback),
+  onError: (callback) => createBaseOnEventListener(videoElement, 'error', callback),
+  onLoadedData: (callback) => createBaseOnEventListener(videoElement, 'loadeddata', callback),
+  onLoadedMetadata: (callback) => createBaseOnEventListener(videoElement, 'loadedmetadata', callback),
+  onLoadStart: (callback) => createBaseOnEventListener(videoElement, 'loadstart', callback),
+  onProgress: (callback) => createBaseOnEventListener(videoElement, 'progress', callback),
+  onSuspend: (callback) => createBaseOnEventListener(videoElement, 'suspend', callback),
+  // Playback state
+  onPause: (callback) => createBaseOnEventListener(videoElement, 'pause', callback),
+  onPlay: (callback) => createBaseOnEventListener(videoElement, 'play', callback),
+  onPlaying: (callback) => createBaseOnEventListener(videoElement, 'playing', callback),
+  onRateChange: (callback) => createBaseOnEventListener(videoElement, 'ratechange', callback),
+  onSeeked: (callback) => createBaseOnEventListener(videoElement, 'seeked', callback),
+  onSeeking: (callback) => createBaseOnEventListener(videoElement, 'seeking', callback),
+  onTimeUpdate: (callback) => createBaseOnEventListener(videoElement, 'timeupdate', callback),
+  onVolumeChange: (callback) => createBaseOnEventListener(videoElement, 'volumechange', callback),
+  // Quality of experience (buffering / adaptive bitrate)
+  onResize: (callback) => createBaseOnEventListener(videoElement, 'resize', callback),
+  onStalled: (callback) => createBaseOnEventListener(videoElement, 'stalled', callback),
+  onWaiting: (callback) => createBaseOnEventListener(videoElement, 'waiting', callback),
+  // Encrypted media (DRM / EME)
+  onEncrypted: (callback) => createBaseOnEventListener(videoElement, 'encrypted', callback),
+  onWaitingForKey: (callback) => createBaseOnEventListener(videoElement, 'waitingforkey', callback),
+  // Engagement (picture-in-picture / fullscreen)
+  onEnterPictureInPicture: (callback) => createBaseOnEventListener(videoElement, 'enterpictureinpicture', callback),
+  onLeavePictureInPicture: (callback) => createBaseOnEventListener(videoElement, 'leavepictureinpicture', callback),
+  // The Fullscreen API dispatches on `document`, not on the media element;
+  // iOS Safari instead fires webkit-prefixed events on the element itself.
+  onFullscreenChange: (callback) => {
+    const removeListeners = [
+      createBaseOnEventListener(document, 'fullscreenchange', callback),
+      createBaseOnEventListener(videoElement, 'webkitbeginfullscreen', callback),
+      createBaseOnEventListener(videoElement, 'webkitendfullscreen', callback),
+    ];
+    return () => removeListeners.forEach((removeListener) => removeListener());
+  },
+
+  getCurrentSrc: () => videoElement.currentSrc,
+  getCurrentTime: () => videoElement.currentTime,
+  getReadyState: () => videoElement.readyState,
+  getNetworkState: () => videoElement.networkState,
+  getDuration: () => videoElement.duration,
+  getPlaybackRate: () => videoElement.playbackRate,
+  getVolume: () => videoElement.volume,
+  getMuted: () => videoElement.muted,
+  getVideoWidth: () => videoElement.videoWidth,
+  getVideoHeight: () => videoElement.videoHeight,
+  getBuffered: () => videoElement.buffered,
+  getError: () => videoElement.error,
+  getIsFullscreen: () =>
+    document.fullscreenElement === videoElement ||
+    Boolean((videoElement as IosFullscreenVideoElement).webkitDisplayingFullscreen),
+});
diff --git a/src/types.ts b/src/types.ts
new file mode 100644
index 0000000..6377e5d
--- /dev/null
+++ b/src/types.ts
@@ -0,0 +1,145 @@
+/**
+ * Shared domain types for the Cloudinary Video Analytics library.
+ */
+
+/** Removes an event listener previously registered on a player adapter. */
+export type RemoveListener = () => void;
+
+/** Callback invoked when a player event fires. */
+export type PlayerEventCallback = (event: Event) => void;
+
+/**
+ * Abstraction over a video player. The library ships a native HTML5 video
+ * adapter, but consumers may provide their own implementation to integrate
+ * a custom player.
+ */
+export interface PlayerAdapter {
+  // Loading / source lifecycle
+  onAbort: (callback: PlayerEventCallback) => RemoveListener;
+  onCanPlay: (callback: PlayerEventCallback) => RemoveListener;
+  onCanPlayThrough: (callback: PlayerEventCallback) => RemoveListener;
+  onDurationChange: (callback: PlayerEventCallback) => RemoveListener;
+  onEmptied: (callback: PlayerEventCallback) => RemoveListener;
+  onEnded: (callback: PlayerEventCallback) => RemoveListener;
+  onError: (callback: PlayerEventCallback) => RemoveListener;
+  onLoadedData: (callback: PlayerEventCallback) => RemoveListener;
+  onLoadedMetadata: (callback: PlayerEventCallback) => RemoveListener;
+  onLoadStart: (callback: PlayerEventCallback) => RemoveListener;
+  onProgress: (callback: PlayerEventCallback) => RemoveListener;
+  onSuspend: (callback: PlayerEventCallback) => RemoveListener;
+  // Playback state
+  onPause: (callback: PlayerEventCallback) => RemoveListener;
+  onPlay: (callback: PlayerEventCallback) => RemoveListener;
+  onPlaying: (callback: PlayerEventCallback) => RemoveListener;
+  onRateChange: (callback: PlayerEventCallback) => RemoveListener;
+  onSeeked: (callback: PlayerEventCallback) => RemoveListener;
+  onSeeking: (callback: PlayerEventCallback) => RemoveListener;
+  onTimeUpdate: (callback: PlayerEventCallback) => RemoveListener;
+  onVolumeChange: (callback: PlayerEventCallback) => RemoveListener;
+  // Quality of experience (buffering / adaptive bitrate)
+  onResize: (callback: PlayerEventCallback) => RemoveListener;
+  onStalled: (callback: PlayerEventCallback) => RemoveListener;
+  onWaiting: (callback: PlayerEventCallback) => RemoveListener;
+  // Encrypted media (DRM / EME)
+  onEncrypted: (callback: PlayerEventCallback) => RemoveListener;
+  onWaitingForKey: (callback: PlayerEventCallback) => RemoveListener;
+  // Engagement (picture-in-picture / fullscreen)
+  onEnterPictureInPicture: (callback: PlayerEventCallback) => RemoveListener;
+  onLeavePictureInPicture: (callback: PlayerEventCallback) => RemoveListener;
+  onFullscreenChange: (callback: PlayerEventCallback) => RemoveListener;
+
+  getCurrentSrc: () => string;
+  getCurrentTime: () => number;
+  getReadyState: () => number;
+  getNetworkState: () => number;
+  getDuration: () => number;
+  getPlaybackRate: () => number;
+  getVolume: () => number;
+  getMuted: () => boolean;
+  getVideoWidth: () => number;
+  getVideoHeight: () => number;
+  getBuffered: () => TimeRanges;
+  getError: () => MediaError | null;
+  getIsFullscreen: () => boolean;
+}
+
+/** Identifies the video player integration reporting the events. */
+export type VideoPlayerType = 'native' | 'cloudinary video player';
+
+/** Cloudinary account/video identifiers describing the tracked video. */
+export interface CustomerVideoData {
+  cloudName: string;
+  publicId: string;
+}
+
+/** Arbitrary customer-provided metadata (`customData1` ... `customData5`). */
+export type CustomData = Partial<Record<
+  'customData1' | 'customData2' | 'customData3' | 'customData4' | 'customData5',
+  string
+>>;
+
+/**
+ * Metadata describing the video being tracked, provided by the customer when
+ * starting manual tracking.
+ */
+export interface VideoMetadata {
+  cloudName: string;
+  publicId: string;
+  type?: 'live';
+}
+
+/** Options accepted by `connectCloudinaryAnalytics`. */
+export interface MainOptions {
+  playerAdapter?: PlayerAdapter;
+}
+
+/** Options accepted by the tracking methods. */
+export interface TrackingOptions {
+  customData?: CustomData | (() => CustomData) | unknown;
+  videoPlayerType?: string;
+  videoPlayerVersion?: string;
+  customVideoUrlFallback?: (videoUrl: string) => CustomerVideoData | VideoMetadata | undefined;
+}
+
+/** Result returned by the validators. */
+export interface ValidationResult {
+  isValid: boolean;
+  errorMessage?: string;
+}
+
+/** A single analytics event before serialization. */
+export interface AnalyticsEvent {
+  eventName: string;
+  eventTime: number;
+  eventDetails: Record<string, unknown>;
+}
+
+/** Payload sent to the analytics endpoints. */
+export interface AnalyticsPayload {
+  userId: string;
+  viewId: string;
+  events: string;
+}
+
+/** Callback used to report a raw event from an event registrar. */
+export type ReportEvent = (
+  eventName: string,
+  eventDetails: Record<string, unknown>,
+) => void;
+
+/** Cleans up any listeners registered by an event registrar. */
+export type UnregisterEvent = () => void;
+
+/**
+ * Lets an event registrar contribute a final event right before the view's
+ * events are flushed and sent. Used to emit an authoritative end-of-view
+ * summary (e.g. aggregated buffering) that also captures state still in
+ * progress at the moment the view ends.
+ */
+export type RegisterFinalizer = (finalizer: () => void) => void;
+
+/** Page lifecycle callbacks used by the page tracker. */
+export interface PageEvents {
+  onPageViewStart?: () => void;
+  onPageViewEnd?: () => void;
+}
diff --git a/src/utils/customer-data.js b/src/utils/customer-data.js
deleted file mode 100644
index 03197ba..0000000
--- a/src/utils/customer-data.js
+++ /dev/null
@@ -1,63 +0,0 @@
-const CUSTOMER_DATA_CHARS_LIMIT = 1000;
-
-const filterOutNonStrings = (data) => {
-  return Array.from({ length: 5 }).reduce((obj, cv, currentIndex) => {
-    const key = `customData${currentIndex + 1}`;
-
-    if (typeof data[key] === 'string') {
-      obj[key] = data[key];
-    }
-
-    return obj;
-  }, {})
-};
-
-export const parseCustomData = (customData) => {
-  const data = typeof customData === 'function' ? customData() : customData;
-
-  if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
-    const filteredData = filterOutNonStrings(data);
-    return Object.keys(filteredData).length > 0 ? filteredData : null;
-  }
-
-  return null;
-}
-
-export const isCustomDataValid = (customData) => {
-  if (customData === null) {
-    return false;
-  }
-
-  const stringifiedValue = JSON.stringify(customData);
-  return stringifiedValue.length <= CUSTOMER_DATA_CHARS_LIMIT;
-};
-
-export const useCustomerVideoDataFallback = (videoUrl, fallback) => {
-  try {
-    const result = fallback(videoUrl);
-    return {
-      cloudName: result.cloudName,
-      publicId: result.publicId,
-    };
-  } catch (e) {
-    return null;
-  }
-};
-
-export const parseCustomerVideoData = (data) => {
-  if (
-    data !== null &&
-    typeof data === 'object' &&
-    typeof data.cloudName === 'string' &&
-    data.cloudName &&
-    typeof data.publicId === 'string' &&
-    data.publicId
-  ) {
-    return {
-      cloudName: data.cloudName,
-      publicId: data.publicId,
-    };
-  }
-
-  return null;
-};
diff --git a/src/utils/customer-data.ts b/src/utils/customer-data.ts
new file mode 100644
index 0000000..9cdf9ac
--- /dev/null
+++ b/src/utils/customer-data.ts
@@ -0,0 +1,70 @@
+import type { CustomData, CustomerVideoData, TrackingOptions } from '../types';
+
+const CUSTOMER_DATA_CHARS_LIMIT = 1000;
+
+const filterOutNonStrings = (data: Record<string, unknown>): CustomData => {
+  return Array.from({ length: 5 }).reduce<CustomData>((obj, _cv, currentIndex) => {
+    const key = `customData${currentIndex + 1}` as keyof CustomData;
+
+    if (typeof data[key] === 'string') {
+      obj[key] = data[key] as string;
+    }
+
+    return obj;
+  }, {});
+};
+
+export const parseCustomData = (
+  customData: TrackingOptions['customData'],
+): CustomData | null => {
+  const data = typeof customData === 'function' ? customData() : customData;
+
+  if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+    const filteredData = filterOutNonStrings(data as Record<string, unknown>);
+    return Object.keys(filteredData).length > 0 ? filteredData : null;
+  }
+
+  return null;
+};
+
+export const isCustomDataValid = (customData: CustomData | null): boolean => {
+  if (customData === null) {
+    return false;
+  }
+
+  const stringifiedValue = JSON.stringify(customData);
+  return stringifiedValue.length <= CUSTOMER_DATA_CHARS_LIMIT;
+};
+
+export const useCustomerVideoDataFallback = (
+  videoUrl: string,
+  fallback: NonNullable<TrackingOptions['customVideoUrlFallback']>,
+): CustomerVideoData | null => {
+  try {
+    const result = fallback(videoUrl);
+    return {
+      cloudName: (result as CustomerVideoData).cloudName,
+      publicId: (result as CustomerVideoData).publicId,
+    };
+  } catch (e) {
+    return null;
+  }
+};
+
+export const parseCustomerVideoData = (data: unknown): CustomerVideoData | null => {
+  if (
+    data !== null &&
+    typeof data === 'object' &&
+    typeof (data as CustomerVideoData).cloudName === 'string' &&
+    (data as CustomerVideoData).cloudName &&
+    typeof (data as CustomerVideoData).publicId === 'string' &&
+    (data as CustomerVideoData).publicId
+  ) {
+    return {
+      cloudName: (data as CustomerVideoData).cloudName,
+      publicId: (data as CustomerVideoData).publicId,
+    };
+  }
+
+  return null;
+};
diff --git a/src/utils/events.js b/src/utils/events.ts
similarity index 57%
rename from src/utils/events.js
rename to src/utils/events.ts
index 0418f4c..23ec166 100644
--- a/src/utils/events.js
+++ b/src/utils/events.ts
@@ -1,11 +1,26 @@
 import { isCustomDataValid, parseCustomData, parseCustomerVideoData, useCustomerVideoDataFallback } from './customer-data';
 import { VIEW_EVENT } from '../events.consts';
 import { getVideoPlayerType, getVideoPlayerVersion } from './video-player-options';
+import type { AnalyticsEvent, CustomerVideoData, TrackingOptions } from '../types';
 
-export const createRegularVideoViewStartEvent = (baseData, customerOptions) => {
+interface RegularViewStartBaseData {
+  videoUrl: string;
+  trackingType: 'auto' | 'manual';
+}
+
+interface LiveStreamViewBaseData {
+  liveStreamData: CustomerVideoData | null;
+}
+
+export const createRegularVideoViewStartEvent = (
+  baseData: RegularViewStartBaseData,
+  customerOptions?: TrackingOptions,
+): AnalyticsEvent => {
   const customData = parseCustomData(customerOptions?.customData);
   const isValidCustomData = isCustomDataValid(customData);
-  const customerVideoDataFromFallback = customerOptions?.customVideoUrlFallback ? useCustomerVideoDataFallback(baseData.videoUrl, customerOptions.customVideoUrlFallback) : null;
+  const customerVideoDataFromFallback = customerOptions?.customVideoUrlFallback
+    ? useCustomerVideoDataFallback(baseData.videoUrl, customerOptions.customVideoUrlFallback)
+    : null;
   const customerVideoData = parseCustomerVideoData(customerVideoDataFromFallback);
   return createEvent(VIEW_EVENT.START, {
     ...baseData,
@@ -21,11 +36,16 @@ export const createRegularVideoViewStartEvent = (baseData, customerOptions) => {
   });
 };
 
-export const createRegularVideoViewEndEvent = (baseData = {}) => {
+export const createRegularVideoViewEndEvent = (
+  baseData: Record<string, unknown> = {},
+): AnalyticsEvent => {
   return createEvent(VIEW_EVENT.END, { ...baseData });
 };
 
-export const createLiveStreamViewStartEvent = (baseData, customerOptions) => {
+export const createLiveStreamViewStartEvent = (
+  baseData: LiveStreamViewBaseData,
+  customerOptions?: TrackingOptions,
+): AnalyticsEvent => {
   return createEvent(VIEW_EVENT.START, {
     ...baseData,
     analyticsModuleVersion: ANALYTICS_VERSION,
@@ -36,17 +56,23 @@ export const createLiveStreamViewStartEvent = (baseData, customerOptions) => {
   });
 };
 
-export const createLiveStreamViewEndEvent = (baseData, customerOptions) => {
+export const createLiveStreamViewEndEvent = (
+  baseData: LiveStreamViewBaseData,
+  _customerOptions?: TrackingOptions,
+): AnalyticsEvent => {
   return createEvent(VIEW_EVENT.END, { ...baseData });
 };
 
-export const createEvent = (eventName, eventDetails) => ({
+export const createEvent = (
+  eventName: string,
+  eventDetails: Record<string, unknown>,
+): AnalyticsEvent => ({
   eventName,
   eventTime: Date.now(),
   eventDetails,
 });
 
-export const prepareEvents = (collectedEvents) => {
+export const prepareEvents = (collectedEvents: AnalyticsEvent[]): string => {
   const events = [...collectedEvents];
   return JSON.stringify(events);
 };
diff --git a/src/utils/metadata-validator.js b/src/utils/metadata-validator.ts
similarity index 64%
rename from src/utils/metadata-validator.js
rename to src/utils/metadata-validator.ts
index 6de6300..a7a2630 100644
--- a/src/utils/metadata-validator.js
+++ b/src/utils/metadata-validator.ts
@@ -1,27 +1,31 @@
-export const metadataValidator = (metadata) => {
-  if (typeof metadata !== 'object') {
+import type { ValidationResult, VideoMetadata } from '../types';
+
+export const metadataValidator = (metadata: unknown): ValidationResult => {
+  if (typeof metadata !== 'object' || metadata === null) {
     return {
       isValid: false,
       errorMessage: 'Metadata param needs to be an object',
     };
   }
 
-  if (typeof metadata.cloudName !== 'string') {
+  const data = metadata as Partial<VideoMetadata>;
+
+  if (typeof data.cloudName !== 'string') {
     return {
       isValid: false,
       errorMessage: 'You need to provide proper cloud name of your Cloudinary account [cloudName: string]',
     };
   }
 
-  if (typeof metadata.type === 'string' && metadata.type !== 'live') {
+  if (typeof data.type === 'string' && data.type !== 'live') {
     return {
       isValid: false,
       errorMessage: 'Property "type" can be either undefined or "live" value [type: "live"]',
     };
   }
 
-  if (typeof metadata.publicId !== 'string') {
-    if (metadata.type === 'live') {
+  if (typeof data.publicId !== 'string') {
+    if (data.type === 'live') {
       return {
         isValid: false,
         errorMessage: 'You need to provide proper public ID of your Live Stream output [publicId: string]',
diff --git a/src/utils/page-events.js b/src/utils/page-events.ts
similarity index 83%
rename from src/utils/page-events.js
rename to src/utils/page-events.ts
index b60d5cb..cebe78b 100644
--- a/src/utils/page-events.js
+++ b/src/utils/page-events.ts
@@ -1,4 +1,6 @@
-export const createPageTracker = (events, isMobile) => {
+import type { PageEvents, RemoveListener } from '../types';
+
+export const createPageTracker = (events: PageEvents, isMobile: boolean): RemoveListener => {
   if (isMobile) {
     return createMobilePageTracker(events);
   }
@@ -6,7 +8,7 @@ export const createPageTracker = (events, isMobile) => {
   return createDesktopPageTracker(events);
 };
 
-const createMobilePageTracker = ({ onPageViewStart, onPageViewEnd }) => {
+const createMobilePageTracker = ({ onPageViewStart, onPageViewEnd }: PageEvents): RemoveListener => {
   const handleVisibilityChange = () => {
     if (document.visibilityState === 'visible') {
       onPageViewStart?.();
@@ -26,7 +28,7 @@ const createMobilePageTracker = ({ onPageViewStart, onPageViewEnd }) => {
   };
 };
 
-const createDesktopPageTracker = ({ onPageViewStart, onPageViewEnd }) => {
+const createDesktopPageTracker = ({ onPageViewStart, onPageViewEnd }: PageEvents): RemoveListener => {
   const handlePageLoad = () => onPageViewStart?.();
   const handleBeforeUnload = () => onPageViewEnd?.();
 
diff --git a/src/utils/send-beacon-request.js b/src/utils/send-beacon-request.ts
similarity index 62%
rename from src/utils/send-beacon-request.js
rename to src/utils/send-beacon-request.ts
index 2b664a1..0e69072 100644
--- a/src/utils/send-beacon-request.js
+++ b/src/utils/send-beacon-request.ts
@@ -1,6 +1,9 @@
-export const sendBeaconRequest = (url, data) => {
+export const sendBeaconRequest = (
+  url: string,
+  data: Record<string, unknown>,
+): boolean | Promise<Response> => {
   const params = Object.keys(data).reduce((formData, key) => {
-    formData.append(key, data[key]);
+    formData.append(key, data[key] as string | Blob);
     return formData;
   }, new FormData());
 
@@ -9,7 +12,7 @@ export const sendBeaconRequest = (url, data) => {
       method: 'POST',
       mode: 'no-cors',
       body: params,
-      keepalive: true
+      keepalive: true,
     });
   }
 
diff --git a/src/utils/unique-ids.js b/src/utils/unique-ids.ts
similarity index 82%
rename from src/utils/unique-ids.js
rename to src/utils/unique-ids.ts
index 5e56902..d49b8cd 100644
--- a/src/utils/unique-ids.js
+++ b/src/utils/unique-ids.ts
@@ -2,7 +2,7 @@ import { v4 as uuidv4 } from 'uuid';
 
 const CLD_ANALYTICS_USER_ID_KEY = 'cld-analytics-user-id';
 
-export const getUserId = () => {
+export const getUserId = (): string => {
   const storageUserId = window.localStorage.getItem(CLD_ANALYTICS_USER_ID_KEY);
 
   if (storageUserId) {
@@ -14,6 +14,6 @@ export const getUserId = () => {
   return userId;
 };
 
-export const getVideoViewId = () => {
+export const getVideoViewId = (): string => {
   return uuidv4().replace(/-/g, '');
 };
diff --git a/src/utils/validators.js b/src/utils/validators.js
deleted file mode 100644
index c42c54e..0000000
--- a/src/utils/validators.js
+++ /dev/null
@@ -1,73 +0,0 @@
-export const throwErrorIfInvalid = (validationResult, errorHeader) => {
-  if (!validationResult.isValid) {
-    throw errorHeader ? `${errorHeader}:` + "\n\n" + validationResult.errorMessage : validationResult.errorMessage;
-  }
-};
-
-export const metadataValidator = (metadata) => {
-  if (typeof metadata !== 'object') {
-    return {
-      isValid: false,
-      errorMessage: 'Metadata param needs to be an object',
-    };
-  }
-
-  if (typeof metadata.cloudName !== 'string') {
-    return {
-      isValid: false,
-      errorMessage: 'You need to provide proper cloud name of your Cloudinary account [cloudName: string]',
-    };
-  }
-
-  if (typeof metadata.type === 'string' && metadata.type !== 'live') {
-    return {
-      isValid: false,
-      errorMessage: 'Property "type" can be either undefined or "live" value',
-    };
-  }
-
-  if (typeof metadata.publicId !== 'string') {
-    if (metadata.type === 'live') {
-      return {
-        isValid: false,
-        errorMessage: 'You need to provide proper public ID of your Live Stream output',
-      };
-    }
-
-    return {
-      isValid: false,
-      errorMessage: 'You need to provide proper video public ID of your video on your Cloudinary cloud [videoPublicId: string]',
-    };
-  }
-
-  return {
-    isValid: true,
-  };
-};
-
-export const mainOptionsValidator = (mainOptions) => {
-  if (mainOptions && typeof mainOptions !== 'object') {
-    return {
-      isValid: false,
-      errorMessage: 'Options property must be an object',
-    };
-  }
-
-  return {
-    isValid: true,
-  };
-};
-
-export const trackingOptionsValidator = (trackingOptions) => {
-  if (trackingOptions && typeof trackingOptions !== 'object') {
-    return {
-      isValid: false,
-      errorMessage: 'Options property must be an object',
-    };
-  }
-
-  return {
-    isValid: true,
-  };
-};
-
diff --git a/src/utils/validators.ts b/src/utils/validators.ts
new file mode 100644
index 0000000..ee11707
--- /dev/null
+++ b/src/utils/validators.ts
@@ -0,0 +1,112 @@
+import type { ValidationResult, VideoMetadata } from '../types';
+
+const CUSTOM_EVENT_DATA_CHARS_LIMIT = 2000;
+
+export const throwErrorIfInvalid = (validationResult: ValidationResult, errorHeader?: string): void => {
+  if (!validationResult.isValid) {
+    throw errorHeader ? `${errorHeader}:` + '\n\n' + validationResult.errorMessage : validationResult.errorMessage;
+  }
+};
+
+export const metadataValidator = (metadata: unknown): ValidationResult => {
+  if (typeof metadata !== 'object' || metadata === null) {
+    return {
+      isValid: false,
+      errorMessage: 'Metadata param needs to be an object',
+    };
+  }
+
+  const data = metadata as Partial<VideoMetadata>;
+
+  if (typeof data.cloudName !== 'string') {
+    return {
+      isValid: false,
+      errorMessage: 'You need to provide proper cloud name of your Cloudinary account [cloudName: string]',
+    };
+  }
+
+  if (typeof data.type === 'string' && data.type !== 'live') {
+    return {
+      isValid: false,
+      errorMessage: 'Property "type" can be either undefined or "live" value',
+    };
+  }
+
+  if (typeof data.publicId !== 'string') {
+    if (data.type === 'live') {
+      return {
+        isValid: false,
+        errorMessage: 'You need to provide proper public ID of your Live Stream output',
+      };
+    }
+
+    return {
+      isValid: false,
+      errorMessage: 'You need to provide proper video public ID of your video on your Cloudinary cloud [videoPublicId: string]',
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+};
+
+export const mainOptionsValidator = (mainOptions: unknown): ValidationResult => {
+  if (mainOptions && typeof mainOptions !== 'object') {
+    return {
+      isValid: false,
+      errorMessage: 'Options property must be an object',
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+};
+
+export const trackingOptionsValidator = (trackingOptions: unknown): ValidationResult => {
+  if (trackingOptions && typeof trackingOptions !== 'object') {
+    return {
+      isValid: false,
+      errorMessage: 'Options property must be an object',
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+};
+
+export const customEventValidator = (name: unknown, data: unknown): ValidationResult => {
+  if (typeof name !== 'string' || name.length === 0) {
+    return {
+      isValid: false,
+      errorMessage: 'Custom event name must be a non-empty string [name: string]',
+    };
+  }
+
+  if (data !== undefined && (typeof data !== 'object' || data === null || Array.isArray(data))) {
+    return {
+      isValid: false,
+      errorMessage: 'Custom event data must be an object [data: object]',
+    };
+  }
+
+  try {
+    if (JSON.stringify(data ?? {}).length > CUSTOM_EVENT_DATA_CHARS_LIMIT) {
+      return {
+        isValid: false,
+        errorMessage: `Custom event data exceeds the ${CUSTOM_EVENT_DATA_CHARS_LIMIT} character limit`,
+      };
+    }
+  } catch (e) {
+    return {
+      isValid: false,
+      errorMessage: 'Custom event data must be JSON-serializable',
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+};
diff --git a/src/utils/video-player-options.js b/src/utils/video-player-options.js
deleted file mode 100644
index 0a32478..0000000
--- a/src/utils/video-player-options.js
+++ /dev/null
@@ -1,19 +0,0 @@
-const REGEX_SEMANTIC_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
-const NATIVE_VIDEO_PLAYER = 'native';
-const ALLOWED_VIDEO_PLAYER_TYPES = [NATIVE_VIDEO_PLAYER, 'cloudinary video player'];
-
-export const getVideoPlayerType = (videoPlayerType) => {
-  if (ALLOWED_VIDEO_PLAYER_TYPES.includes(videoPlayerType)) {
-    return videoPlayerType;
-  }
-
-  return NATIVE_VIDEO_PLAYER;
-};
-
-export const getVideoPlayerVersion = (videoPlayerVersion) => {
-  if (typeof videoPlayerVersion === 'string' && REGEX_SEMANTIC_VERSION.test(videoPlayerVersion)) {
-    return videoPlayerVersion;
-  }
-
-  return null;
-};
diff --git a/src/utils/video-player-options.ts b/src/utils/video-player-options.ts
new file mode 100644
index 0000000..36d1e5d
--- /dev/null
+++ b/src/utils/video-player-options.ts
@@ -0,0 +1,21 @@
+import type { VideoPlayerType } from '../types';
+
+const REGEX_SEMANTIC_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const NATIVE_VIDEO_PLAYER = 'native';
+const ALLOWED_VIDEO_PLAYER_TYPES: VideoPlayerType[] = [NATIVE_VIDEO_PLAYER, 'cloudinary video player'];
+
+export const getVideoPlayerType = (videoPlayerType?: string): VideoPlayerType => {
+  if (ALLOWED_VIDEO_PLAYER_TYPES.includes(videoPlayerType as VideoPlayerType)) {
+    return videoPlayerType as VideoPlayerType;
+  }
+
+  return NATIVE_VIDEO_PLAYER;
+};
+
+export const getVideoPlayerVersion = (videoPlayerVersion?: string): string | null => {
+  if (typeof videoPlayerVersion === 'string' && REGEX_SEMANTIC_VERSION.test(videoPlayerVersion)) {
+    return videoPlayerVersion;
+  }
+
+  return null;
+};
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..ea44707
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "declaration": false,
+    "paths": {
+      "cloudinary-video-analytics": ["./src/index"]
+    }
+  },
+  "include": ["src", "types", "dev"]
+}
diff --git a/tsconfig.types.json b/tsconfig.types.json
new file mode 100644
index 0000000..9fe9217
--- /dev/null
+++ b/tsconfig.types.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "sourceMap": false,
+    "outDir": "dist"
+  },
+  "include": ["src", "types"]
+}
diff --git a/types/globals.d.ts b/types/globals.d.ts
new file mode 100644
index 0000000..1773c48
--- /dev/null
+++ b/types/globals.d.ts
@@ -0,0 +1,18 @@
+/**
+ * Injected at build time by webpack's DefinePlugin
+ * (see webpack.config.js). Resolves to the package version.
+ */
+declare const ANALYTICS_VERSION: string;
+
+/**
+ * Minimal ambient declaration for the build-time environment variable
+ * used to switch analytics endpoints. Replaced by webpack's DefinePlugin
+ * in the browser bundle; declared here so the source type-checks without
+ * pulling in the full @types/node surface.
+ */
+declare const process: {
+  env: {
+    NODE_ENV?: string;
+    [key: string]: string | undefined;
+  };
+};
diff --git a/webpack.config.js b/webpack.config.js
index 3820092..9472a00 100644
--- a/webpack.config.js
+++ b/webpack.config.js
@@ -10,7 +10,7 @@ module.exports = {
       new TerserPlugin()
     ]
   },
-  entry: './src/index.js',
+  entry: './src/index.ts',
   output: {
     clean: true,
     filename: `[name].js`,
@@ -19,13 +19,16 @@ module.exports = {
       type: 'umd',
     }
   },
+  resolve: {
+    extensions: ['.ts', '.js'],
+  },
   module: {
     rules: [
       {
-        test: /\.js$/,
+        test: /\.ts$/,
         exclude: /node_modules/,
         use: [{
-          loader: 'babel-loader'
+          loader: 'ts-loader'
         }]
       }
     ]
diff --git a/webpack.dev.config.js b/webpack.dev.config.js
index 10aa76d..fcdbc99 100644
--- a/webpack.dev.config.js
+++ b/webpack.dev.config.js
@@ -4,10 +4,10 @@ const HtmlWebpackPlugin = require('html-webpack-plugin');
 const productionWebpackConfig = require('./webpack.config');
 
 module.exports = merge(productionWebpackConfig, {
-  entry: './dev/main.js',
+  entry: './dev/main.ts',
   resolve: {
     alias: {
-      'cloudinary-video-analytics': path.resolve(__dirname, 'src/index.js'),
+      'cloudinary-video-analytics': path.resolve(__dirname, 'src/index.ts'),
     },
   },
   mode: 'development',