@gravity-ai/api 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,24 @@
 
 The official Node.js/TypeScript SDK for the Gravity AI advertising API. Fetch contextually relevant ads based on conversation content.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Migrating from v0](#migrating-from-v0)
+- [Client Configuration](#client-configuration)
+- [Integration Types](#integration-types)
+  - [Web](#web)
+  - [IDE / CLI](#ide--cli)
+  - [Mobile](#mobile)
+  - [General](#general)
+- [Response Types](#response-types)
+- [Error Handling](#error-handling)
+- [Using with React](#using-with-react)
+- [Best Practices](#best-practices)
+
+---
+
 ## Installation
 
 ```bash
@@ -10,6 +28,8 @@ npm install @gravity-ai/api
 
 > **Note:** Requires Node.js 18+
 
+---
+
 ## Quick Start
 
 ```typescript
@@ -17,14 +37,17 @@ import { Client } from '@gravity-ai/api';
 
 const client = new Client('your-api-key');
 
-// Contextual ads (v1 API)
-const response = await client.contextualAd({
+const response = await client.getAd({
   messages: [
     { role: 'user', content: 'What are some good hiking trails?' },
-    { role: 'assistant', content: 'Here are some popular trails...' }
   ],
-  sessionId: 'session-123',  // Recommended
-  userId: 'user-456',        // Recommended
+  sessionId: 'session-123',
+  userId: 'user-456',
+  numAds: 1,
+  render_context: {
+    placements: [{ placement: 'below_response' }]
+  },
+  testAd: true,
 });
 
 if (response) {
@@ -33,221 +56,366 @@ if (response) {
 }
 ```
 
-## Client Configuration
+---
+
+## Migrating from v0
+
+If you're upgrading from a previous version, there are key changes:
 
-### Basic Initialization
+**1. `sessionId` is now required**
+
+**2. `render_context` object with `placements` array is now required**
+
+**3. Response format changed to `ads` array**
 
 ```typescript
-import { Client } from '@gravity-ai/api';
+// Before (v0)
+const ad = await client.getAd({ messages });
 
-const client = new Client('your-api-key');
+// After (v1)
+const response = await client.getAd({
+  messages,
+  sessionId: 'session-123',
+  numAds: 1,
+  render_context: {
+    placements: [{ placement: 'below_response' }]
+  }
+});
+const ad = response?.ads[0];
 ```
 
-### Advanced Configuration
+---
+
+## Client Configuration
 
 ```typescript
 import { Client } from '@gravity-ai/api';
 
+// Basic
+const client = new Client('your-api-key');
+
+// Advanced
 const client = new Client('your-api-key', {
-  // Topics to exclude globally (optional)
-  excludedTopics: ['politics', 'religion'],
-  
-  // Minimum relevancy threshold 0-1 (optional)
-  relevancy: 0.8,
+  excludedTopics: ['politics', 'religion'],  // Global exclusions
+  relevancy: 0.6,                            // Min relevancy threshold (0.1-1)
 });
 ```
 
-#### Configuration Options
-
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `endpoint` | `string` | `'https://server.trygravity.ai'` | API endpoint URL |
 | `excludedTopics` | `string[]` | `[]` | Topics to exclude from ad matching |
-| `relevancy` | `number \| null` | `null` | Minimum relevancy score (0-1) |
+| `relevancy` | `number` | `null` | Minimum relevancy score (0.1-1) |
 
 ---
 
-## v1 API Methods
+## Integration Types
 
-The v1 API provides explicit endpoints for different ad types with multi-ad support.
+Choose the integration type that matches your application. All types share a **common schema**.
 
-### `contextualAd()` — Contextual Ads
+### Common Fields
 
-Fetch ads based on conversation context. Requires `messages` array.
+| Field | Type | Description |
+|-------|------|-------------|
+| `messages` | `MessageObject[]` | Conversation context. Array of `{role, content}` objects. **Required.** |
+| `sessionId` | `string` | Session identifier for frequency capping. **Required.** |
+| `render_context` | `RenderContextObject` | Describes how the ad will be rendered in your app. **Required.** |
+| `userId` | `string` | Unique user identifier. |
+| `testAd` | `boolean` | Returns real ad without tracking. Use for testing. |
+| `numAds` | `number` | Number of ads to return (1-3). Must match `placements` length. |
 
-```typescript
-const response = await client.contextualAd({
-  messages: [
-    { role: 'user', content: 'I need help finding a new laptop.' },
-    { role: 'assistant', content: 'What is your budget?' }
-  ],
-  sessionId: 'session-123',  // Recommended
-  userId: 'user-456',        // Recommended
-  numAds: 1,                 // 1-3, default 1
-});
+#### What is `render_context`?
 
-if (response) {
-  const ad = response.ads[0];
-  console.log(ad.adText);
-}
-```
+The `render_context` object describes how the ad will be rendered in your app, so Gravity can generate a more contextually relevant ad.
+
+For example:
+- **`placements`** — Where you plan to show the ad (below the response, in a sidebar, etc.)
+- **`max_ad_length`** — Character limit you can display, so we don't send copy that gets truncated
+- **`supports_markdown`** — Whether you can render formatted text
+- **`supports_images`** — Whether you can display brand logos or product images
+
+The more context you provide, the better we can optimize the ad copy, format, and creative for your specific integration.
+
+<details>
+<summary><strong>RenderContextObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `placements` | `PlacementObject[]` | Array of placement objects (1-3). Length must match `numAds`. **Required.** |
+| `max_ad_length` | `number` | Max characters for ad text. |
+| `supports_markdown` | `boolean` | Whether markdown rendering is supported. |
+| `supports_links` | `boolean` | Whether clickable links are supported. |
+| `supports_images` | `boolean` | Whether images can be displayed. |
+| `supports_cta_button` | `boolean` | Whether CTA buttons are supported. |
+
+</details>
+
+<details>
+<summary><strong>PlacementObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `placement` | `string` | **Required.** One of: `"above_response"`, `"below_response"`, `"inline_response"`, `"left_response"`, `"right_response"` |
+| `placement_id` | `string` | Optional tracking ID for this ad slot. |
+
+</details>
+
+<details>
+<summary><strong>DeviceObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ip` | `string` | IP address for geo-targeting. **Required.** |
+| `ua` | `string` | User agent string. Enables browser/device detection. |
+| `os` | `string` | Operating system: `"macos"`, `"windows"`, `"linux"`, `"iOS"`, `"Android"`. |
+| `os_version` | `string` | OS version (e.g., `"17.2"`). |
+| `browser` | `string` | Browser name: `"chrome"`, `"safari"`, `"firefox"`. |
+| `device_type` | `string` | `"desktop"`, `"mobile"`, `"tablet"`. |
+| `device_model` | `string` | Device model (e.g., `"iPhone 15 Pro"`). |
+| `ifa` | `string` | IDFA/GAID for cross-app attribution. **Higher CPMs.** |
+| `timezone` | `string` | IANA timezone (e.g., `"America/New_York"`). |
+| `locale` | `string` | Locale (e.g., `"en-US"`). |
+| `connection_type` | `string` | `"wifi"` or `"cellular"`. |
+
+</details>
+
+<details>
+<summary><strong>UserObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `email` | `string` | User's email for identity matching. **Higher CPMs.** |
+| `gender` | `string` | `"male"`, `"female"`, `"other"`. |
+| `age` | `string` | Age range: `"18-24"`, `"25-34"`, `"35-44"`, etc. |
+| `keywords` | `string` | Comma-separated interest keywords. |
+| `subscription_tier` | `string` | `"free"`, `"pro"`, `"premium"`, `"enterprise"`. |
+| `user_created_at` | `string` | Account creation date (ISO 8601). |
+| `user_interests` | `string[]` | Array of user interests for targeting. |
 
-#### Full Request with All Options
+</details>
+
+---
+
+### Web
+
+**For:** Chat interfaces, AI assistants, web apps with conversational UI
+
+#### Web-specific Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `web.referrer` | `string` | Referring URL. Enables traffic source targeting. |
+
+#### Example
 
 ```typescript
-const response = await client.contextualAd({
-  // Required: conversation messages
+const response = await client.getAd({
+  // Common fields
   messages: [
-    { role: 'user', content: 'I need help finding a new laptop.' },
-    { role: 'assistant', content: 'What is your budget?' }
+    { role: 'user', content: 'What are the best practices for React performance?' }
   ],
-  
-  // Recommended: session/user tracking (improves ad relevance & revenue)
-  sessionId: 'session-123',
-  userId: 'user-456',
-  
-  // Optional: user information for targeting
+  sessionId: 'session-web-001',
+  userId: 'user-web-789',
+  numAds: 1,
+  testAd: true,
+  render_context: {
+    placements: [
+      { placement: 'right_response', placement_id: 'sidebar-1' }
+    ],
+    max_ad_length: 200
+  },
+
+  // Web-specific fields
   user: {
-    uid: 'user-123',           // Unique user identifier
-    gender: 'male',            // 'male' | 'female' | 'other'
-    age: '25-34',              // Age range string
-    keywords: 'tech,gadgets',  // User interest keywords
+    email: 'webuser@example.com',
+    subscription_tier: 'pro'
   },
-  
-  // Optional: device information
   device: {
-    ip: '1.2.3.4',             // User IP address
-    country: 'US',             // ISO country code
-    ua: 'Mozilla/5.0...',      // User agent string
-    os: 'macOS',               // Operating system
-    ifa: 'device-ad-id',       // Advertising identifier
+    ip: '203.0.113.50',
+    ua: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0',
+    browser: 'chrome',
+    device_type: 'desktop',
+    timezone: 'Europe/London',
+    locale: 'en-GB'
   },
-  
-  // Optional: ad request settings
-  excludedTopics: ['politics'],  // Topics to exclude
-  relevancy: 0.8,                // Min relevancy threshold (0-1)
-  numAds: 1,                     // Number of ads (1-3)
-  testAd: false,                 // Return test ad when true
-  
-  // Optional: custom fields (open-ended, passed to matching)
-  interests: ['coding', 'apple', 'software development'],
-  summary: 'User wants a laptop for software development',
+  web: {
+    referrer: 'https://google.com'
+  }
 });
 ```
 
-### `summaryAd()` — Summary-Based Ads
+---
 
-Fetch ads based on a search query or summary string. Requires `queryString`.
+### IDE / CLI
 
-```typescript
-const response = await client.summaryAd({
-  queryString: 'User wants a laptop for software development',
-  sessionId: 'session-123',
-  userId: 'user-456',
-});
+**For:** Dev tools like Cursor, Claude Code, GitHub Copilot, Windsurf and VS Code extensions
 
-if (response) {
-  const ad = response.ads[0];
-  console.log(ad.adText);
-}
-```
+#### IDE-specific Fields
+
+<details>
+<summary><strong>IDEObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | IDE name: `"cursor"`, `"vscode"`, `"intellij"`. |
+| `session_duration_ms` | `number` | Time since IDE opened. Helps with engagement-based targeting. |
+| `active_file_language` | `string` | Current file language (e.g., `"typescript"`). |
 
-### `nonContextualAd()` — Non-Contextual Ads
+</details>
 
-Fetch ads without context matching. Ideal for:
-- **Integration testing** — Test your ad implementation on a subset of users before rolling out contextual ads
-- **Brand awareness** — Show ads without requiring conversation context
-- **Fallback placements** — Ad slots where context isn't available
+#### Example
 
 ```typescript
-const response = await client.nonContextualAd({
-  sessionId: 'session-123',
-  userId: 'user-456',
-  numAds: 2,  // Request multiple ads
-});
+const response = await client.getAd({
+  // Common fields
+  messages: [
+    { role: 'user', content: 'How do I set up authentication in my Express app?' }
+  ],
+  sessionId: 'session-ide-001',
+  userId: 'user-dev-123',
+  numAds: 1,
+  testAd: true,
+  render_context: {
+    placements: [
+      { placement: 'below_response' }
+    ],
+    max_ad_length: 280,
+    supports_markdown: true,
+    supports_links: true
+  },
 
-if (response) {
-  response.ads.forEach(ad => console.log(ad.adText));
-}
+  // IDE-specific fields
+  user: {
+    email: 'developer@example.com'
+  },
+  device: {
+    ip: '192.168.1.100',
+    os: 'macos',
+    timezone: 'America/New_York',
+    locale: 'en-US'
+  },
+  ide: {
+    name: 'cursor',
+    session_duration_ms: 3600000,
+    active_file_language: 'typescript'
+  }
+});
 ```
 
-### `bid()` + `render()` — Two-Phase Flow
+---
+
+### Mobile
+
+**For:** iOS apps, Android apps, React Native, Flutter
+
+#### Mobile-specific Fields
 
-For publishers who need to know the clearing price before rendering the ad.
+<details>
+<summary><strong>AppObject</strong></summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `string` | Your app version. |
+
+</details>
+
+#### Example
 
 ```typescript
-// Phase 1: Get bid price
-const bidResult = await client.bid({
+const response = await client.getAd({
+  // Common fields
   messages: [
-    { role: 'user', content: 'I need help with my code' }
+    { role: 'assistant', content: 'I found several Italian restaurants nearby.' },
+    { role: 'user', content: 'Which one has the best pasta?' }
   ],
-  sessionId: 'session-123',
-});
+  sessionId: 'session-mobile-001',
+  userId: 'user-app-456',
+  numAds: 1,
+  testAd: true,
+  render_context: {
+    placements: [
+      { placement: 'inline_response' }
+    ],
+    max_ad_length: 150,
+    supports_images: true,
+    supports_cta_button: true
+  },
 
-if (bidResult) {
-  console.log(`Clearing price: $${bidResult.bid} CPM`);
-  console.log(`Bid ID: ${bidResult.bidId}`);
-  
-  // Decide whether to show ad based on price...
-  
-  // Phase 2: Render the ad
-  const response = await client.render({
-    bidId: bidResult.bidId,
-    realizedPrice: bidResult.bid,
-  });
-  
-  if (response) {
-    const ad = response.ads[0];
-    console.log(ad.adText);
+  // Mobile-specific fields
+  user: {
+    email: 'user@example.com',
+    subscription_tier: 'premium',
+    user_created_at: '2023-06-15T00:00:00Z',
+    user_interests: ['food', 'dining', 'travel']
+  },
+  device: {
+    ip: '198.51.100.23',
+    ua: 'MyApp/2.1.0 (iPhone; iOS 17.2)',
+    os: 'iOS',
+    os_version: '17.2',
+    device_model: 'iPhone 15 Pro',
+    ifa: '6D92078A-8246-4BA4-AE5B-76104861E7DC',
+    timezone: 'America/Los_Angeles',
+    locale: 'en-US',
+    connection_type: 'wifi'
+  },
+  app: {
+    version: '2.1.0'
   }
-}
+});
 ```
 
-> **Note:** Bids expire after 60 seconds. Call `render()` promptly after `bid()`.
-
 ---
 
-## v1 Request Parameters
+### General
 
-### Base Parameters (All v1 Methods)
+**For:** Any integration not covered above.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `sessionId` | `string` | Recommended | Session identifier for tracking |
-| `userId` | `string` | Recommended | User identifier for frequency capping |
-| `device` | `DeviceObject` | - | Device/location info |
-| `user` | `UserObject` | - | User targeting info |
-| `excludedTopics` | `string[]` | - | Topics to exclude |
-| `relevancy` | `number` | - | Min relevancy (0-1) |
-| `numAds` | `number` | - | Number of ads (1-3, default 1) |
-| `testAd` | `boolean` | - | Return test ad when true |
+#### Example
 
-### Method-Specific Parameters
+```typescript
+const response = await client.getAd({
+  // Common fields
+  messages: [
+    { role: 'user', content: 'Where can I buy marathon gear?' }
+  ],
+  sessionId: 'session-general-001',
+  userId: 'user-general-123',
+  numAds: 1,
+  testAd: true,
+  render_context: {
+    placements: [
+      { placement: 'below_response' }
+    ]
+  },
 
-| Method | Required Parameter | Description |
-|--------|-------------------|-------------|
-| `contextualAd()` | `messages: MessageObject[]` | Conversation history |
-| `summaryAd()` | `queryString: string` | Search/summary query |
-| `nonContextualAd()` | None | No context required |
-| `bid()` | `messages: MessageObject[]` | Conversation for bid |
-| `render()` | `bidId: string`, `realizedPrice: number` | From bid response |
+  // Optional fields
+  device: {
+    ip: '192.168.1.1',
+    timezone: 'America/New_York',
+    locale: 'en-US'
+  }
+});
+```
 
 ---
 
-## v1 Response Types
+## Response Types
 
-### AdResponseV1
-
-Returned by `contextualAd()`, `summaryAd()`, `nonContextualAd()`, and `render()`.
+### AdResponse
 
 ```typescript
-interface AdResponseV1 {
-  ads: AdV1[];           // Array of ads
+interface AdResponse {
+  ads: Ad[];             // Array of ads (one per placement)
   numAds: number;        // Number of ads returned
   totalPayout?: number;  // Total payout across all ads
 }
+```
 
-interface AdV1 {
+### Ad
+
+```typescript
+interface Ad {
   adText: string;        // Ad copy text
   adId: string;          // Unique ad identifier
   title?: string;        // Ad title
@@ -255,164 +423,74 @@ interface AdV1 {
   brandImage?: string;   // Brand logo URL
   url?: string;          // Landing page URL
   favicon?: string;      // Favicon URL
-  impUrl?: string;       // Impression tracking URL
-  clickUrl?: string;     // Click-through URL
-  payout?: number;       // Payout amount
-}
-```
-
-### BidResponse
-
-Returned by `bid()`.
-
-```typescript
-interface BidResponse {
-  bid: number;     // Clearing price (CPM)
-  bidId: string;   // Use this in render()
+  impUrl?: string;       // Impression tracking URL (null for testAd)
+  clickUrl?: string;     // Click-through URL (null for testAd)
+  payout?: number;       // Payout amount (null for testAd)
 }
 ```
 
----
-
-## Common Types
-
-### Message Object
+### Request Types
 
 ```typescript
 interface MessageObject {
   role: 'user' | 'assistant';
   content: string;
 }
-```
 
-### User Object
-
-```typescript
-interface UserObject {
-  uid?: string;                              // Unique user ID
-  gender?: 'male' | 'female' | 'other';      // User gender
-  age?: string;                              // Age range (e.g., '25-34')
-  keywords?: string;                         // Interest keywords
+interface RenderContextObject {
+  placements: PlacementObject[];  // Required, 1-3 items
+  max_ad_length?: number;
+  supports_markdown?: boolean;
+  supports_links?: boolean;
+  supports_images?: boolean;
+  supports_cta_button?: boolean;
 }
-```
 
-### Device Object
-
-```typescript
-interface DeviceObject {
-  ip: string;          // IP address
-  country: string;     // ISO country code
-  ua: string;          // User agent
-  os?: string;         // Operating system
-  ifa?: string;        // Advertising ID
+interface PlacementObject {
+  placement: 'above_response' | 'below_response' | 'inline_response' | 'left_response' | 'right_response';
+  placement_id?: string;
 }
 ```
 
 ---
 
-## Legacy API (v0)
-
-The original `getAd()` method is still available for backward compatibility.
-
-### Basic Request
-
-```typescript
-const ad = await client.getAd({
-  messages: [
-    { role: 'user', content: 'I need help finding a new laptop.' },
-    { role: 'assistant', content: 'What is your budget?' }
-  ]
-});
-```
-
-### Full Request with All Options
-
-```typescript
-const ad = await client.getAd({
-  messages: [...],
-  user: { uid: 'user-123', gender: 'male', age: '25-34' },
-  device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
-  excludedTopics: ['politics'],
-  relevancy: 0.8,
-});
-```
-
-### Legacy Response
-
-```typescript
-interface AdResponse {
-  adText: string;       // The ad copy to display
-  impUrl?: string;      // Impression tracking URL
-  clickUrl?: string;    // Click-through URL
-  payout?: number;      // Payout amount
-}
-```
-
-### Handling the Legacy Response
-
-```typescript
-const ad = await client.getAd({ messages });
-
-if (ad) {
-  console.log('Ad:', ad.adText);
-  
-  // Track impression
-  if (ad.impUrl) {
-    fetch(ad.impUrl);
-  }
-} else {
-  console.log('No ad available');
-}
-```
-
 ## Error Handling
 
-The client handles errors gracefully and returns `null` on failure. Errors are logged to the console.
+The client returns `null` on failure. Errors are logged to console.
 
 ```typescript
-const response = await client.contextualAd({ messages, sessionId: '...' });
+const response = await client.getAd({
+  messages,
+  sessionId: 'session-123',
+  numAds: 1,
+  render_context: { placements: [{ placement: 'below_response' }] }
+});
 
 // Returns null on:
 // - Network errors
-// - API errors (4xx, 5xx)
-// - No relevant ad (204)
-// - Invalid response data
-// - Expired bid (404 for render())
+// - 401: Invalid API key
+// - 422: Validation error (missing sessionId, render_context, or numAds/placements mismatch)
+// - 204: No relevant ad found
+// - 429: Rate limit exceeded
 
 if (!response) {
   // Handle gracefully - don't break the user experience
 }
 ```
 
-## TypeScript
-
-Full TypeScript support with exported types:
+| Status | Meaning |
+|--------|---------|
+| `200` | Ad(s) matched and returned successfully |
+| `204` | No matching ads found (null response) |
+| `401` | Invalid or missing API key |
+| `422` | Validation error (e.g., missing `sessionId`, `render_context`, or `numAds`/`placements` mismatch) |
+| `429` | Rate limit exceeded |
 
-```typescript
-import { Client, ClientParams } from '@gravity-ai/api';
-import type { 
-  // v1 types
-  ContextualAdParams,
-  SummaryAdParams,
-  NonContextualAdParams,
-  BidParams,
-  RenderParams,
-  AdV1,
-  AdResponseV1,
-  BidResponse,
-  // Common types
-  MessageObject, 
-  DeviceObject, 
-  UserObject,
-  // Legacy types
-  AdParams, 
-  AdResponse,
-} from '@gravity-ai/api';
-```
+---
 
 ## Using with React
 
-For React applications, consider using the companion package `@gravity-ai/react` which provides ready-to-use components with automatic tracking:
+For React applications, use the companion package `@gravity-ai/react`:
 
 ```bash
 npm install @gravity-ai/api @gravity-ai/react
@@ -426,12 +504,15 @@ const client = new Client('your-api-key');
 
 function ChatApp() {
   const [ad, setAd] = useState(null);
-  
+
   useEffect(() => {
-    client.contextualAd({ 
+    client.getAd({
       messages,
       sessionId: 'session-123',
       userId: 'user-456',
+      numAds: 1,
+      render_context: { placements: [{ placement: 'below_response' }] },
+      testAd: true,
     }).then(res => setAd(res?.ads[0] || null));
   }, [messages]);
 
@@ -439,19 +520,47 @@ function ChatApp() {
 }
 ```
 
+---
+
 ## Best Practices
 
-1. **Always include `sessionId` and `userId`** — These directly impact publisher revenue through better frequency capping and ad relevance.
+1. **`sessionId` and `render_context` are required** — Enable frequency capping and ad placement tracking.
+
+2. **`numAds` must match `placements` length** — Request 2 ads? Provide 2 placement objects.
+
+3. **Include `userId` when available** — Improves targeting and increases CPMs.
 
-2. **Choose the right method**:
-   - Chat/conversation → `contextualAd()`
-   - Chat summary → `summaryAd()`
-   - Brand awareness → `nonContextualAd()`
-   - Custom auction → `bid()` + `render()`
+4. **Use `testAd: true` during development** — Prevents generating real impressions or clicks.
 
-3. **Handle null responses gracefully** — Don't break the user experience when no ad is available.
+5. **Handle null responses gracefully** — Don't break the UX when no ad is available.
 
-4. **Fire impression url** — Use the `impUrl` when the ad becomes visible to properly track impressions.
+6. **Fire `impUrl` when the ad is visible** — Required for proper impression tracking.
+
+7. **Include `device.ip` for geo-targeting** — Enables location-based ads and higher CPMs.
+
+8. **Include `user.email` when available** — Enables identity matching for significantly higher CPMs.
+
+---
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import { Client } from '@gravity-ai/api';
+import type {
+  AdParams,
+  Ad,
+  AdResponse,
+  MessageObject,
+  RenderContextObject,
+  PlacementObject,
+  DeviceObject,
+  UserObject,
+} from '@gravity-ai/api';
+```
+
+---
 
 ## License