@gravity-ai/api 1.0.2 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @gravity-ai/api
 
-The official Node.js/TypeScript SDK for the Gravity AI advertising API. Fetch contextually relevant ads based on conversation content.
+The official Node.js/TypeScript SDK for the Gravity AI advertising API.
 
 ## Installation
 
@@ -8,304 +8,11 @@ The official Node.js/TypeScript SDK for the Gravity AI advertising API. Fetch co
 npm install @gravity-ai/api
 ```
 
-> **Note:** Requires Node.js 18+
+## Documentation
 
-## Quick Start
+For full documentation, examples, and API reference, visit:
 
-```typescript
-import { Client } from '@gravity-ai/api';
-
-const client = new Client('your-api-key');
-
-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
-});
-
-if (response) {
-  const ad = response.ads[0];
-  console.log(ad.adText);
-}
-```
-
-## Migrating from v0
-
-If you're upgrading from a previous version, the `getAd()` response format has changed:
-
-```typescript
-// Before (v0)
-const ad = await client.getAd({ messages });
-if (ad) {
-  console.log(ad.adText);
-}
-
-// After (v1)
-const response = await client.getAd({ messages, sessionId: '...' });
-if (response) {
-  const ad = response.ads[0];
-  console.log(ad.adText);
-}
-```
-
-The response is now an object with an `ads` array instead of a single ad object.
-
----
-
-## Client Configuration
-
-### Basic Initialization
-
-```typescript
-import { Client } from '@gravity-ai/api';
-
-const client = new Client('your-api-key');
-```
-
-### Advanced Configuration
-
-```typescript
-import { Client } from '@gravity-ai/api';
-
-const client = new Client('your-api-key', {
-  // Topics to exclude globally (optional)
-  excludedTopics: ['politics', 'religion'],
-  
-  // Minimum relevancy threshold 0-1 (optional)
-  relevancy: 0.8,
-});
-```
-
-#### 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) |
-
----
-
-## `getAd()` — Fetch Contextual Ads
-
-Fetch ads based on conversation context. Requires `messages` array.
-
-```typescript
-const response = await client.getAd({
-  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
-});
-
-if (response) {
-  const ad = response.ads[0];
-  console.log(ad.adText);
-}
-```
-
-### Full Request with All Options
-
-```typescript
-const response = await client.getAd({
-  // Required: conversation messages
-  messages: [
-    { role: 'user', content: 'I need help finding a new laptop.' },
-    { role: 'assistant', content: 'What is your budget?' }
-  ],
-  
-  // Recommended: session/user tracking (improves ad relevance & revenue)
-  sessionId: 'session-123',
-  userId: 'user-456',
-  
-  // Optional: user information for targeting
-  user: {
-    uid: 'user-123',           // Unique user identifier
-    gender: 'male',            // 'male' | 'female' | 'other'
-    age: '25-34',              // Age range string
-    keywords: 'tech,gadgets',  // User interest keywords
-  },
-  
-  // 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
-  },
-  
-  // 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',
-});
-```
-
----
-
-## Request Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `messages` | `MessageObject[]` | Yes | Conversation history |
-| `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 |
-
----
-
-## Response Types
-
-### AdResponse
-
-Returned by `getAd()`.
-
-```typescript
-interface AdResponse {
-  ads: Ad[];           // Array of ads
-  numAds: number;        // Number of ads returned
-  totalPayout?: number;  // Total payout across all ads
-}
-
-interface Ad {
-  adText: string;        // Ad copy text
-  adId: string;          // Unique ad identifier
-  title?: string;        // Ad title
-  brandName?: string;    // Brand name
-  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
-}
-```
-
----
-
-## Common Types
-
-### Message Object
-
-```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
-}
-```
-
-### 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
-}
-```
-
----
-
-## Error Handling
-
-The client handles errors gracefully and returns `null` on failure. Errors are logged to the console.
-
-```typescript
-const response = await client.getAd({ messages, sessionId: '...' });
-
-// Returns null on:
-// - Network errors
-// - API errors (4xx, 5xx)
-// - No relevant ad (204)
-// - Invalid response data
-
-if (!response) {
-  // Handle gracefully - don't break the user experience
-}
-```
-
-## TypeScript
-
-Full TypeScript support with exported types:
-
-```typescript
-import { Client, ClientParams } from '@gravity-ai/api';
-import type { 
-  AdParams,
-  Ad,
-  AdResponse,
-  MessageObject, 
-  DeviceObject, 
-  UserObject,
-} 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:
-
-```bash
-npm install @gravity-ai/api @gravity-ai/react
-```
-
-```tsx
-import { Client } from '@gravity-ai/api';
-import { AdBanner } from '@gravity-ai/react';
-
-const client = new Client('your-api-key');
-
-function ChatApp() {
-  const [ad, setAd] = useState(null);
-  
-  useEffect(() => {
-    client.getAd({ 
-      messages,
-      sessionId: 'session-123',
-      userId: 'user-456',
-    }).then(res => setAd(res?.ads[0] || null));
-  }, [messages]);
-
-  return <AdBanner ad={ad} theme="dark" />;
-}
-```
-
-## Best Practices
-
-1. **Always include `sessionId` and `userId`** — These directly impact publisher revenue through better frequency capping and ad relevance.
-
-2. **Handle null responses gracefully** — Don't break the user experience when no ad is available.
-
-3. **Fire impression url** — Use the `impUrl` when the ad becomes visible to properly track impressions.
+**[https://www.trygravity.ai/api](https://www.trygravity.ai/api)**
 
 ## License
 

package/dist/index.d.mts

@@ -8,6 +8,58 @@ type Role = 'user' | 'assistant';
  * @description Used for demographic targeting of advertisements
  */
 type Gender = 'male' | 'female' | 'other';
+/**
+ * Placement positions for ad rendering
+ * @description Specifies where ads should appear relative to the AI response
+ */
+type Placement = 'above_response' | 'below_response' | 'inline_response' | 'left_response' | 'right_response';
+/**
+ * Individual ad placement specification
+ * @description Defines a single ad slot with its position and optional tracking ID
+ * @example
+ * ```typescript
+ * const placement: PlacementObject = {
+ *   placement: 'below_response',
+ *   placement_id: 'sidebar-1'
+ * };
+ * ```
+ */
+interface PlacementObject {
+    /** Position where the ad should appear (required) */
+    placement: Placement;
+    /** Optional tracking ID for this specific ad slot */
+    placement_id?: string;
+}
+/**
+ * Describes how your app will display the ad
+ * @description Contains placement array and rendering capabilities for ad customization
+ * @example
+ * ```typescript
+ * const renderContext: RenderContextObject = {
+ *   placements: [
+ *     { placement: 'below_response' },
+ *     { placement: 'right_response', placement_id: 'sidebar' }
+ *   ],
+ *   max_ad_length: 200
+ * };
+ * ```
+ */
+interface RenderContextObject {
+    /** Where you plan to show the ad(s). Array of 1-3 placements, must match numAds. */
+    placements: PlacementObject[];
+    /** Character limit you can display, so we don't send copy that gets truncated */
+    max_ad_length?: number;
+    /** Whether you can render markdown-formatted text */
+    supports_markdown?: boolean;
+    /** Whether you can render clickable links */
+    supports_links?: boolean;
+    /** Whether you can display images (brand logos, product images) */
+    supports_images?: boolean;
+    /** Whether you can render CTA buttons */
+    supports_cta_button?: boolean;
+    /** Additional render context properties (supports JSON objects) */
+    [key: string]: PlacementObject[] | string | number | boolean | object | null | undefined;
+}
 /**
  * Represents a single message in a conversation
  * @description Used to provide conversation context for contextual ad targeting
@@ -39,16 +91,18 @@ interface MessageObject {
  * ```
  */
 interface DeviceObject {
-    /** User's IP address for geo-targeting */
+    /** User's IP address for geo-targeting (required) */
     ip: string;
+    /** Browser user-agent string (optional for non-web publishers like IDEs, CLIs, mobile apps) */
+    ua?: string;
     /** ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') */
-    country: string;
-    /** User agent string from the browser */
-    ua: string;
+    country?: string;
     /** Operating system name (e.g., 'macOS', 'Windows', 'iOS', 'Android') */
     os?: string;
     /** Identifier for Advertisers (mobile advertising ID) */
     ifa?: string;
+    /** Additional device properties (timezone, locale, browser, device_type, screen dimensions, etc.) */
+    [key: string]: string | number | boolean | undefined;
 }
 /**
  * User profile information for ad targeting
@@ -64,7 +118,7 @@ interface DeviceObject {
  * ```
  */
 interface UserObject {
-    /** Unique user identifier for frequency capping and tracking */
+    /** Unique user identifier for improving ad relevance */
     uid?: string;
     /** User's gender for demographic targeting */
     gender?: Gender;
@@ -72,6 +126,8 @@ interface UserObject {
     age?: string;
     /** Comma-separated keywords representing user interests */
     keywords?: string;
+    /** Additional user properties (email, subscription_tier, user_interests, company_size, etc.) */
+    [key: string]: string | string[] | number | boolean | Gender | undefined;
 }
 /**
  * Parameters for requesting an advertisement
@@ -84,7 +140,12 @@ interface UserObject {
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
  *   sessionId: 'session-123',
+ *   numAds: 1,
+ *   render_context: {
+ *     placements: [{ placement: 'below_response' }]
+ *   },
  *   userId: 'user-456',
+ *   testAd: true,
  *   user: { gender: 'male', age: '25-34' },
  *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
  *   excludedTopics: ['politics'],
@@ -95,8 +156,12 @@ interface UserObject {
 interface AdParams {
     /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
-    /** Session identifier for tracking user sessions */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Device and location information */
@@ -107,8 +172,6 @@ interface AdParams {
     excludedTopics?: string[];
     /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
     relevancy?: number | null;
-    /** Number of ads to return (1-3, default 1) */
-    numAds?: number;
     /** Returns a test ad when true */
     testAd?: boolean;
     /**
@@ -185,8 +248,12 @@ interface ApiErrorResponse {
  * Base fields shared across all ad requests.
  */
 interface AdRequestBase {
-    /** Session identifier for tracking user sessions */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Device and location information */
@@ -197,8 +264,6 @@ interface AdRequestBase {
     excludedTopics?: string[];
     /** Minimum relevancy score threshold (0-1) */
     relevancy?: number | null;
-    /** Number of ads to return (1-3, default 1) */
-    numAds?: number;
     /** Returns a test ad when true */
     testAd?: boolean;
     /** Additional custom fields */
@@ -221,13 +286,16 @@ interface NonContextualAdParams extends AdRequestBase {
 /**
  * POST /api/v1/bid
  * @description Two-phase bid request. Returns bid price and bidId.
- * @note Does NOT extend AdRequestBaseV1 - has its own field set.
  */
 interface BidParams {
     /** Array of conversation messages (required) */
     messages: MessageObject[];
-    /** Session identifier */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Chat/conversation identifier */
@@ -304,6 +372,10 @@ interface ClientParams {
  *     { role: 'user', content: 'What laptop should I buy?' }
  *   ],
  *   sessionId: 'session-123',
+ *   numAds: 1,
+ *   render_context: {
+ *     placements: [{ placement: 'below_response' }]
+ *   }
  * });
  *
  * if (response) {
@@ -370,6 +442,10 @@ declare class Client {
      *     { role: 'assistant', content: 'What is your budget range?' }
      *   ],
      *   sessionId: 'session-123',
+     *   numAds: 1,
+     *   render_context: {
+     *     placements: [{ placement: 'below_response' }]
+     *   },
      *   userId: 'user-456',
      * });
      *
@@ -384,6 +460,11 @@ declare class Client {
      * const response = await client.getAd({
      *   messages: [...],
      *   sessionId: 'session-123',
+     *   numAds: 1,
+     *   render_context: {
+     *     placements: [{ placement: 'below_response' }],
+     *     max_ad_length: 200
+     *   },
      *   userId: 'user-456',
      *   user: {
      *     uid: 'user-123',
@@ -402,7 +483,12 @@ declare class Client {
      *
      * @example Handling the response
      * ```typescript
-     * const response = await client.getAd({ messages, sessionId: '...' });
+     * const response = await client.getAd({
+     *   messages,
+     *   sessionId: '...',
+     *   numAds: 1,
+     *   render_context: { placements: [{ placement: 'below_response' }] }
+     * });
      *
      * if (response) {
      *   const ad = response.ads[0];
@@ -433,10 +519,10 @@ declare class Client {
      * @description Fetches ads without context matching. Useful for brand awareness placements.
      * Returns null if no ad is available or on error.
      *
-     * @param params - Optional request parameters
+     * @param params - Request parameters (sessionId required)
      * @returns Promise resolving to AdResponse or null if no ad available
      */
-    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponse | null>;
+    nonContextualAd(params: NonContextualAdParams): Promise<AdResponse | null>;
     /**
      * Request a bid price for contextual ad placement
      *
@@ -472,4 +558,4 @@ declare class Client {
     private handleError;
 }
 
-export { type Ad, type AdParams, type AdRequestBase, type AdResponse, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type RenderParams, type Role, type SummaryAdParams, type UserObject };
+export { type Ad, type AdParams, type AdRequestBase, type AdResponse, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type Placement, type PlacementObject, type RenderContextObject, type RenderParams, type Role, type SummaryAdParams, type UserObject };

package/dist/index.d.ts

@@ -8,6 +8,58 @@ type Role = 'user' | 'assistant';
  * @description Used for demographic targeting of advertisements
  */
 type Gender = 'male' | 'female' | 'other';
+/**
+ * Placement positions for ad rendering
+ * @description Specifies where ads should appear relative to the AI response
+ */
+type Placement = 'above_response' | 'below_response' | 'inline_response' | 'left_response' | 'right_response';
+/**
+ * Individual ad placement specification
+ * @description Defines a single ad slot with its position and optional tracking ID
+ * @example
+ * ```typescript
+ * const placement: PlacementObject = {
+ *   placement: 'below_response',
+ *   placement_id: 'sidebar-1'
+ * };
+ * ```
+ */
+interface PlacementObject {
+    /** Position where the ad should appear (required) */
+    placement: Placement;
+    /** Optional tracking ID for this specific ad slot */
+    placement_id?: string;
+}
+/**
+ * Describes how your app will display the ad
+ * @description Contains placement array and rendering capabilities for ad customization
+ * @example
+ * ```typescript
+ * const renderContext: RenderContextObject = {
+ *   placements: [
+ *     { placement: 'below_response' },
+ *     { placement: 'right_response', placement_id: 'sidebar' }
+ *   ],
+ *   max_ad_length: 200
+ * };
+ * ```
+ */
+interface RenderContextObject {
+    /** Where you plan to show the ad(s). Array of 1-3 placements, must match numAds. */
+    placements: PlacementObject[];
+    /** Character limit you can display, so we don't send copy that gets truncated */
+    max_ad_length?: number;
+    /** Whether you can render markdown-formatted text */
+    supports_markdown?: boolean;
+    /** Whether you can render clickable links */
+    supports_links?: boolean;
+    /** Whether you can display images (brand logos, product images) */
+    supports_images?: boolean;
+    /** Whether you can render CTA buttons */
+    supports_cta_button?: boolean;
+    /** Additional render context properties (supports JSON objects) */
+    [key: string]: PlacementObject[] | string | number | boolean | object | null | undefined;
+}
 /**
  * Represents a single message in a conversation
  * @description Used to provide conversation context for contextual ad targeting
@@ -39,16 +91,18 @@ interface MessageObject {
  * ```
  */
 interface DeviceObject {
-    /** User's IP address for geo-targeting */
+    /** User's IP address for geo-targeting (required) */
     ip: string;
+    /** Browser user-agent string (optional for non-web publishers like IDEs, CLIs, mobile apps) */
+    ua?: string;
     /** ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') */
-    country: string;
-    /** User agent string from the browser */
-    ua: string;
+    country?: string;
     /** Operating system name (e.g., 'macOS', 'Windows', 'iOS', 'Android') */
     os?: string;
     /** Identifier for Advertisers (mobile advertising ID) */
     ifa?: string;
+    /** Additional device properties (timezone, locale, browser, device_type, screen dimensions, etc.) */
+    [key: string]: string | number | boolean | undefined;
 }
 /**
  * User profile information for ad targeting
@@ -64,7 +118,7 @@ interface DeviceObject {
  * ```
  */
 interface UserObject {
-    /** Unique user identifier for frequency capping and tracking */
+    /** Unique user identifier for improving ad relevance */
     uid?: string;
     /** User's gender for demographic targeting */
     gender?: Gender;
@@ -72,6 +126,8 @@ interface UserObject {
     age?: string;
     /** Comma-separated keywords representing user interests */
     keywords?: string;
+    /** Additional user properties (email, subscription_tier, user_interests, company_size, etc.) */
+    [key: string]: string | string[] | number | boolean | Gender | undefined;
 }
 /**
  * Parameters for requesting an advertisement
@@ -84,7 +140,12 @@ interface UserObject {
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
  *   sessionId: 'session-123',
+ *   numAds: 1,
+ *   render_context: {
+ *     placements: [{ placement: 'below_response' }]
+ *   },
  *   userId: 'user-456',
+ *   testAd: true,
  *   user: { gender: 'male', age: '25-34' },
  *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
  *   excludedTopics: ['politics'],
@@ -95,8 +156,12 @@ interface UserObject {
 interface AdParams {
     /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
-    /** Session identifier for tracking user sessions */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Device and location information */
@@ -107,8 +172,6 @@ interface AdParams {
     excludedTopics?: string[];
     /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
     relevancy?: number | null;
-    /** Number of ads to return (1-3, default 1) */
-    numAds?: number;
     /** Returns a test ad when true */
     testAd?: boolean;
     /**
@@ -185,8 +248,12 @@ interface ApiErrorResponse {
  * Base fields shared across all ad requests.
  */
 interface AdRequestBase {
-    /** Session identifier for tracking user sessions */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Device and location information */
@@ -197,8 +264,6 @@ interface AdRequestBase {
     excludedTopics?: string[];
     /** Minimum relevancy score threshold (0-1) */
     relevancy?: number | null;
-    /** Number of ads to return (1-3, default 1) */
-    numAds?: number;
     /** Returns a test ad when true */
     testAd?: boolean;
     /** Additional custom fields */
@@ -221,13 +286,16 @@ interface NonContextualAdParams extends AdRequestBase {
 /**
  * POST /api/v1/bid
  * @description Two-phase bid request. Returns bid price and bidId.
- * @note Does NOT extend AdRequestBaseV1 - has its own field set.
  */
 interface BidParams {
     /** Array of conversation messages (required) */
     messages: MessageObject[];
-    /** Session identifier */
-    sessionId?: string;
+    /** Session identifier for ad relevance (required) */
+    sessionId: string;
+    /** Render context with placements array (required). Length of placements must match numAds. */
+    render_context: RenderContextObject;
+    /** Number of ads to return (1-3). Must match render_context.placements length. */
+    numAds?: number;
     /** Unique user identifier */
     userId?: string;
     /** Chat/conversation identifier */
@@ -304,6 +372,10 @@ interface ClientParams {
  *     { role: 'user', content: 'What laptop should I buy?' }
  *   ],
  *   sessionId: 'session-123',
+ *   numAds: 1,
+ *   render_context: {
+ *     placements: [{ placement: 'below_response' }]
+ *   }
  * });
  *
  * if (response) {
@@ -370,6 +442,10 @@ declare class Client {
      *     { role: 'assistant', content: 'What is your budget range?' }
      *   ],
      *   sessionId: 'session-123',
+     *   numAds: 1,
+     *   render_context: {
+     *     placements: [{ placement: 'below_response' }]
+     *   },
      *   userId: 'user-456',
      * });
      *
@@ -384,6 +460,11 @@ declare class Client {
      * const response = await client.getAd({
      *   messages: [...],
      *   sessionId: 'session-123',
+     *   numAds: 1,
+     *   render_context: {
+     *     placements: [{ placement: 'below_response' }],
+     *     max_ad_length: 200
+     *   },
      *   userId: 'user-456',
      *   user: {
      *     uid: 'user-123',
@@ -402,7 +483,12 @@ declare class Client {
      *
      * @example Handling the response
      * ```typescript
-     * const response = await client.getAd({ messages, sessionId: '...' });
+     * const response = await client.getAd({
+     *   messages,
+     *   sessionId: '...',
+     *   numAds: 1,
+     *   render_context: { placements: [{ placement: 'below_response' }] }
+     * });
      *
      * if (response) {
      *   const ad = response.ads[0];
@@ -433,10 +519,10 @@ declare class Client {
      * @description Fetches ads without context matching. Useful for brand awareness placements.
      * Returns null if no ad is available or on error.
      *
-     * @param params - Optional request parameters
+     * @param params - Request parameters (sessionId required)
      * @returns Promise resolving to AdResponse or null if no ad available
      */
-    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponse | null>;
+    nonContextualAd(params: NonContextualAdParams): Promise<AdResponse | null>;
     /**
      * Request a bid price for contextual ad placement
      *
@@ -472,4 +558,4 @@ declare class Client {
     private handleError;
 }
 
-export { type Ad, type AdParams, type AdRequestBase, type AdResponse, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type RenderParams, type Role, type SummaryAdParams, type UserObject };
+export { type Ad, type AdParams, type AdRequestBase, type AdResponse, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type Placement, type PlacementObject, type RenderContextObject, type RenderParams, type Role, type SummaryAdParams, type UserObject };

package/dist/index.js

@@ -90,6 +90,10 @@ var Client = class {
    *     { role: 'assistant', content: 'What is your budget range?' }
    *   ],
    *   sessionId: 'session-123',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }]
+   *   },
    *   userId: 'user-456',
    * });
    * 
@@ -104,6 +108,11 @@ var Client = class {
    * const response = await client.getAd({
    *   messages: [...],
    *   sessionId: 'session-123',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }],
+   *     max_ad_length: 200
+   *   },
    *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
@@ -122,7 +131,12 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const response = await client.getAd({ messages, sessionId: '...' });
+   * const response = await client.getAd({
+   *   messages,
+   *   sessionId: '...',
+   *   numAds: 1,
+   *   render_context: { placements: [{ placement: 'below_response' }] }
+   * });
    * 
    * if (response) {
    *   const ad = response.ads[0];
@@ -194,10 +208,10 @@ var Client = class {
    * @description Fetches ads without context matching. Useful for brand awareness placements.
    * Returns null if no ad is available or on error.
    *
-   * @param params - Optional request parameters
+   * @param params - Request parameters (sessionId required)
    * @returns Promise resolving to AdResponse or null if no ad available
    */
-  async nonContextualAd(params = {}) {
+  async nonContextualAd(params) {
     try {
       const body = {
         ...params,

package/dist/index.mjs

@@ -54,6 +54,10 @@ var Client = class {
    *     { role: 'assistant', content: 'What is your budget range?' }
    *   ],
    *   sessionId: 'session-123',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }]
+   *   },
    *   userId: 'user-456',
    * });
    * 
@@ -68,6 +72,11 @@ var Client = class {
    * const response = await client.getAd({
    *   messages: [...],
    *   sessionId: 'session-123',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }],
+   *     max_ad_length: 200
+   *   },
    *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
@@ -86,7 +95,12 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const response = await client.getAd({ messages, sessionId: '...' });
+   * const response = await client.getAd({
+   *   messages,
+   *   sessionId: '...',
+   *   numAds: 1,
+   *   render_context: { placements: [{ placement: 'below_response' }] }
+   * });
    * 
    * if (response) {
    *   const ad = response.ads[0];
@@ -158,10 +172,10 @@ var Client = class {
    * @description Fetches ads without context matching. Useful for brand awareness placements.
    * Returns null if no ad is available or on error.
    *
-   * @param params - Optional request parameters
+   * @param params - Request parameters (sessionId required)
    * @returns Promise resolving to AdResponse or null if no ad available
    */
-  async nonContextualAd(params = {}) {
+  async nonContextualAd(params) {
     try {
       const body = {
         ...params,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ai/api",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Gravity JS SDK for retrieving targeted advertisements",
   "main": "dist/index.js",
   "module": "dist/index.mjs",