@gravity-ai/api 0.1.2 → 1.0.2

package/README.md

@@ -17,18 +17,44 @@ import { Client } from '@gravity-ai/api';
 
 const client = new Client('your-api-key');
 
-const ad = await client.getAd({
+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
@@ -61,29 +87,43 @@ const client = new Client('your-api-key', {
 | `excludedTopics` | `string[]` | `[]` | Topics to exclude from ad matching |
 | `relevancy` | `number \| null` | `null` | Minimum relevancy score (0-1) |
 
-## Fetching Ads
+---
+
+## `getAd()` — Fetch Contextual Ads
 
-### Basic Request
+Fetch ads based on conversation context. Requires `messages` array.
 
 ```typescript
-const ad = await client.getAd({
+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 ad = await client.getAd({
+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
@@ -101,27 +141,66 @@ const ad = await client.getAd({
     ifa: 'device-ad-id',       // Advertising identifier
   },
   
-  // Optional: additional targeting context
-  excludedTopics: ['politics'],  // Override client-level exclusions
-  relevancy: 0.8,                // Override client-level relevancy
+  // 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)
+  // Optional: custom fields (open-ended, passed to matching)
   interests: ['coding', 'apple', 'software development'],
   summary: 'User wants a laptop for software development',
 });
 ```
 
-### Request Parameters
+---
+
+## Request Parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `messages` | `MessageObject[]` | ✅ | Conversation history |
-| `user` | `UserObject` | - | User targeting info |
+| `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) |
-| `apiKey` | `string` | - | Override client API key |
-| `[key: string]` | `any` | - | Custom fields allowed |
+| `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
 
@@ -155,49 +234,14 @@ interface DeviceObject {
 }
 ```
 
-## Ad Response
-
-The `getAd` method returns an `AdResponse` object or `null` if no relevant ad is found.
-
-```typescript
-interface AdResponse {
-  adText: string;       // The ad copy to display
-  impUrl?: string;      // Impression tracking URL (fire on view)
-  clickUrl?: string;    // Click-through URL
-  payout?: number;      // Payout amount
-}
-```
-
-### Handling the Response
-
-```typescript
-const ad = await client.getAd({ messages });
-
-if (ad) {
-  // Display the ad
-  console.log('Ad:', ad.adText);
-  
-  // Track impression (fire pixel)
-  if (ad.impUrl) {
-    fetch(ad.impUrl); // or use an image beacon
-  }
-  
-  // Handle clicks
-  if (ad.clickUrl) {
-    // Navigate user to ad.clickUrl on click
-  }
-} else {
-  // No relevant ad found - show fallback or nothing
-  console.log('No ad available');
-}
-```
+---
 
 ## Error Handling
 
 The client handles errors gracefully and returns `null` on failure. Errors are logged to the console.
 
 ```typescript
-const ad = await client.getAd({ messages });
+const response = await client.getAd({ messages, sessionId: '...' });
 
 // Returns null on:
 // - Network errors
@@ -205,7 +249,7 @@ const ad = await client.getAd({ messages });
 // - No relevant ad (204)
 // - Invalid response data
 
-if (!ad) {
+if (!response) {
   // Handle gracefully - don't break the user experience
 }
 ```
@@ -216,7 +260,14 @@ Full TypeScript support with exported types:
 
 ```typescript
 import { Client, ClientParams } from '@gravity-ai/api';
-import type { AdParams, AdResponse, MessageObject, DeviceObject, UserObject } from '@gravity-ai/api';
+import type { 
+  AdParams,
+  Ad,
+  AdResponse,
+  MessageObject, 
+  DeviceObject, 
+  UserObject,
+} from '@gravity-ai/api';
 ```
 
 ## Using with React
@@ -237,13 +288,25 @@ function ChatApp() {
   const [ad, setAd] = useState(null);
   
   useEffect(() => {
-    client.getAd({ messages }).then(setAd);
+    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.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -83,6 +83,8 @@ interface UserObject {
  *     { role: 'user', content: 'What laptop should I buy?' },
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
  *   user: { gender: 'male', age: '25-34' },
  *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
  *   excludedTopics: ['politics'],
@@ -91,10 +93,12 @@ interface UserObject {
  * ```
  */
 interface AdParams {
-    /** Override the client's API key for this request */
-    apiKey?: string;
     /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
+    /** Session identifier for tracking user sessions */
+    sessionId?: string;
+    /** Unique user identifier */
+    userId?: string;
     /** Device and location information */
     device?: DeviceObject;
     /** User demographic and interest data */
@@ -103,43 +107,67 @@ 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;
     /**
      * Additional custom fields for publisher-specific targeting
      * @description Any additional key-value pairs will be passed to the API
      */
     [key: string]: unknown;
 }
+/**
+ * Single ad object in responses.
+ * @description Contains all ad creative and tracking data.
+ */
+interface Ad {
+    /** The advertisement copy text */
+    adText: string;
+    /** Unique ad identifier */
+    adId: string;
+    /** Ad title */
+    title?: string;
+    /** Brand/advertiser name */
+    brandName?: string;
+    /** Brand logo image URL */
+    brandImage?: string;
+    /** Landing page URL */
+    url?: string;
+    /** Favicon URL */
+    favicon?: string;
+    /** Impression tracking URL */
+    impUrl?: string;
+    /** Click-through tracking URL */
+    clickUrl?: string;
+    /** Payout amount in USD */
+    payout?: number;
+}
 /**
  * Response from the Gravity API containing ad data
  * @description Returned by getAd() when a relevant advertisement is found
  * @example
  * ```typescript
- * const ad: AdResponse = {
- *   adText: 'Check out our amazing laptops!',
- *   impUrl: 'https://tracking.example.com/imp?id=123',
- *   clickUrl: 'https://example.com/laptops',
- *   payout: 0.50
+ * const response: AdResponse = {
+ *   ads: [{
+ *     adText: 'Check out our amazing laptops!',
+ *     adId: 'ad-123',
+ *     impUrl: 'https://tracking.example.com/imp?id=123',
+ *     clickUrl: 'https://example.com/laptops',
+ *     payout: 0.50
+ *   }],
+ *   numAds: 1,
+ *   totalPayout: 0.50
  * };
  * ```
  */
 interface AdResponse {
-    /** The advertisement copy text to display to the user */
-    adText: string;
-    /**
-     * Impression tracking URL - fire this when the ad is viewed
-     * @description Should be loaded (e.g., via image beacon) when ad becomes visible
-     */
-    impUrl?: string;
-    /**
-     * Click-through URL - navigate user here when ad is clicked
-     * @description The destination page when the user clicks the ad
-     */
-    clickUrl?: string;
-    /**
-     * Payout amount in USD for this ad impression
-     * @description The revenue earned for displaying this ad
-     */
-    payout?: number;
+    /** Array of ad objects */
+    ads: Ad[];
+    /** Number of ads returned */
+    numAds: number;
+    /** Total payout across all ads */
+    totalPayout?: number;
 }
 /**
  * Error response structure from the Gravity API
@@ -153,6 +181,80 @@ interface ApiErrorResponse {
     /** HTTP status code */
     statusCode?: number;
 }
+/**
+ * Base fields shared across all ad requests.
+ */
+interface AdRequestBase {
+    /** Session identifier for tracking user sessions */
+    sessionId?: string;
+    /** Unique user identifier */
+    userId?: string;
+    /** Device and location information */
+    device?: DeviceObject;
+    /** User demographic and interest data */
+    user?: UserObject;
+    /** Topics to exclude from ad matching */
+    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 */
+    [key: string]: unknown;
+}
+/**
+ * POST /api/v1/ad/summary
+ * @description Requires queryString for summary-based targeting.
+ */
+interface SummaryAdParams extends AdRequestBase {
+    /** Search/summary query string (required) */
+    queryString: string;
+}
+/**
+ * POST /api/v1/ad/non-contextual
+ * @description No context required - returns ads without context matching.
+ */
+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;
+    /** Unique user identifier */
+    userId?: string;
+    /** Chat/conversation identifier */
+    chatId?: string;
+    /** Device and location information */
+    device?: DeviceObject;
+}
+/**
+ * POST /api/v1/render
+ * @description Two-phase render request using cached bid context.
+ */
+interface RenderParams {
+    /** Bid identifier from the bid phase (required) */
+    bidId: string;
+    /** Realized price to charge (required) */
+    realizedPrice: number;
+}
+/**
+ * Bid response.
+ * @description Returned by the bid endpoint.
+ */
+interface BidResponse {
+    /** Clearing price (CPM) */
+    bid: number;
+    /** Bid identifier for the render phase */
+    bidId: string;
+}
 
 /**
  * Configuration options for the Gravity API Client
@@ -197,13 +299,15 @@ interface ClientParams {
  *
  * const client = new Client('your-api-key');
  *
- * const ad = await client.getAd({
+ * const response = await client.getAd({
  *   messages: [
  *     { role: 'user', content: 'What laptop should I buy?' }
- *   ]
+ *   ],
+ *   sessionId: 'session-123',
  * });
  *
- * if (ad) {
+ * if (response) {
+ *   const ad = response.ads[0];
  *   console.log(ad.adText);
  * }
  * ```
@@ -252,7 +356,7 @@ declare class Client {
     /**
      * Request a contextually relevant advertisement
      *
-     * @description Fetches an ad based on the provided conversation context and targeting parameters.
+     * @description Fetches ads based on the provided conversation context and targeting parameters.
      * Returns `null` if no relevant ad is available or if an error occurs.
      *
      * @param params - Ad request parameters including conversation messages
@@ -260,18 +364,27 @@ declare class Client {
      *
      * @example Basic request
      * ```typescript
-     * const ad = await client.getAd({
+     * const response = await client.getAd({
      *   messages: [
      *     { role: 'user', content: 'I need a new laptop for programming' },
      *     { role: 'assistant', content: 'What is your budget range?' }
-     *   ]
+     *   ],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
      * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
      * ```
      *
      * @example Full request with targeting
      * ```typescript
-     * const ad = await client.getAd({
+     * const response = await client.getAd({
      *   messages: [...],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
      *   user: {
      *     uid: 'user-123',
      *     gender: 'male',
@@ -289,9 +402,10 @@ declare class Client {
      *
      * @example Handling the response
      * ```typescript
-     * const ad = await client.getAd({ messages });
+     * const response = await client.getAd({ messages, sessionId: '...' });
      *
-     * if (ad) {
+     * if (response) {
+     *   const ad = response.ads[0];
      *   // Display the ad
      *   showAd(ad.adText);
      *
@@ -303,6 +417,47 @@ declare class Client {
      * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Request summary-based advertisements
+     *
+     * @description Fetches ads based on a search/summary query string.
+     * Returns null if no relevant ad is available or on error.
+     *
+     * @param params - Request parameters including queryString
+     * @returns Promise resolving to AdResponse or null if no ad available
+     */
+    summaryAd(params: SummaryAdParams): Promise<AdResponse | null>;
+    /**
+     * Request non-contextual advertisements
+     *
+     * @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
+     * @returns Promise resolving to AdResponse or null if no ad available
+     */
+    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponse | null>;
+    /**
+     * Request a bid price for contextual ad placement
+     *
+     * @description First phase of two-phase ad flow. Returns bid price and bidId.
+     * Use the bidId with render() to generate the actual ad creative.
+     * Returns null if no bid is available or on error.
+     *
+     * @param params - Request parameters including messages array
+     * @returns Promise resolving to BidResponse or null if no bid available
+     */
+    bid(params: BidParams): Promise<BidResponse | null>;
+    /**
+     * Render an ad from a cached bid
+     *
+     * @description Second phase of two-phase ad flow. Generates ad creative using cached bid context.
+     * Returns null if bid expired (404) or on error. Bid expires after 60 seconds.
+     *
+     * @param params - Request parameters including bidId and realizedPrice
+     * @returns Promise resolving to AdResponse or null if bid expired/error
+     */
+    render(params: RenderParams): Promise<AdResponse | null>;
     /**
      * Handle and log API errors
      *
@@ -317,4 +472,4 @@ declare class Client {
     private handleError;
 }
 
-export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };
+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 };

package/dist/index.d.ts

@@ -83,6 +83,8 @@ interface UserObject {
  *     { role: 'user', content: 'What laptop should I buy?' },
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
  *   user: { gender: 'male', age: '25-34' },
  *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
  *   excludedTopics: ['politics'],
@@ -91,10 +93,12 @@ interface UserObject {
  * ```
  */
 interface AdParams {
-    /** Override the client's API key for this request */
-    apiKey?: string;
     /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
+    /** Session identifier for tracking user sessions */
+    sessionId?: string;
+    /** Unique user identifier */
+    userId?: string;
     /** Device and location information */
     device?: DeviceObject;
     /** User demographic and interest data */
@@ -103,43 +107,67 @@ 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;
     /**
      * Additional custom fields for publisher-specific targeting
      * @description Any additional key-value pairs will be passed to the API
      */
     [key: string]: unknown;
 }
+/**
+ * Single ad object in responses.
+ * @description Contains all ad creative and tracking data.
+ */
+interface Ad {
+    /** The advertisement copy text */
+    adText: string;
+    /** Unique ad identifier */
+    adId: string;
+    /** Ad title */
+    title?: string;
+    /** Brand/advertiser name */
+    brandName?: string;
+    /** Brand logo image URL */
+    brandImage?: string;
+    /** Landing page URL */
+    url?: string;
+    /** Favicon URL */
+    favicon?: string;
+    /** Impression tracking URL */
+    impUrl?: string;
+    /** Click-through tracking URL */
+    clickUrl?: string;
+    /** Payout amount in USD */
+    payout?: number;
+}
 /**
  * Response from the Gravity API containing ad data
  * @description Returned by getAd() when a relevant advertisement is found
  * @example
  * ```typescript
- * const ad: AdResponse = {
- *   adText: 'Check out our amazing laptops!',
- *   impUrl: 'https://tracking.example.com/imp?id=123',
- *   clickUrl: 'https://example.com/laptops',
- *   payout: 0.50
+ * const response: AdResponse = {
+ *   ads: [{
+ *     adText: 'Check out our amazing laptops!',
+ *     adId: 'ad-123',
+ *     impUrl: 'https://tracking.example.com/imp?id=123',
+ *     clickUrl: 'https://example.com/laptops',
+ *     payout: 0.50
+ *   }],
+ *   numAds: 1,
+ *   totalPayout: 0.50
  * };
  * ```
  */
 interface AdResponse {
-    /** The advertisement copy text to display to the user */
-    adText: string;
-    /**
-     * Impression tracking URL - fire this when the ad is viewed
-     * @description Should be loaded (e.g., via image beacon) when ad becomes visible
-     */
-    impUrl?: string;
-    /**
-     * Click-through URL - navigate user here when ad is clicked
-     * @description The destination page when the user clicks the ad
-     */
-    clickUrl?: string;
-    /**
-     * Payout amount in USD for this ad impression
-     * @description The revenue earned for displaying this ad
-     */
-    payout?: number;
+    /** Array of ad objects */
+    ads: Ad[];
+    /** Number of ads returned */
+    numAds: number;
+    /** Total payout across all ads */
+    totalPayout?: number;
 }
 /**
  * Error response structure from the Gravity API
@@ -153,6 +181,80 @@ interface ApiErrorResponse {
     /** HTTP status code */
     statusCode?: number;
 }
+/**
+ * Base fields shared across all ad requests.
+ */
+interface AdRequestBase {
+    /** Session identifier for tracking user sessions */
+    sessionId?: string;
+    /** Unique user identifier */
+    userId?: string;
+    /** Device and location information */
+    device?: DeviceObject;
+    /** User demographic and interest data */
+    user?: UserObject;
+    /** Topics to exclude from ad matching */
+    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 */
+    [key: string]: unknown;
+}
+/**
+ * POST /api/v1/ad/summary
+ * @description Requires queryString for summary-based targeting.
+ */
+interface SummaryAdParams extends AdRequestBase {
+    /** Search/summary query string (required) */
+    queryString: string;
+}
+/**
+ * POST /api/v1/ad/non-contextual
+ * @description No context required - returns ads without context matching.
+ */
+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;
+    /** Unique user identifier */
+    userId?: string;
+    /** Chat/conversation identifier */
+    chatId?: string;
+    /** Device and location information */
+    device?: DeviceObject;
+}
+/**
+ * POST /api/v1/render
+ * @description Two-phase render request using cached bid context.
+ */
+interface RenderParams {
+    /** Bid identifier from the bid phase (required) */
+    bidId: string;
+    /** Realized price to charge (required) */
+    realizedPrice: number;
+}
+/**
+ * Bid response.
+ * @description Returned by the bid endpoint.
+ */
+interface BidResponse {
+    /** Clearing price (CPM) */
+    bid: number;
+    /** Bid identifier for the render phase */
+    bidId: string;
+}
 
 /**
  * Configuration options for the Gravity API Client
@@ -197,13 +299,15 @@ interface ClientParams {
  *
  * const client = new Client('your-api-key');
  *
- * const ad = await client.getAd({
+ * const response = await client.getAd({
  *   messages: [
  *     { role: 'user', content: 'What laptop should I buy?' }
- *   ]
+ *   ],
+ *   sessionId: 'session-123',
  * });
  *
- * if (ad) {
+ * if (response) {
+ *   const ad = response.ads[0];
  *   console.log(ad.adText);
  * }
  * ```
@@ -252,7 +356,7 @@ declare class Client {
     /**
      * Request a contextually relevant advertisement
      *
-     * @description Fetches an ad based on the provided conversation context and targeting parameters.
+     * @description Fetches ads based on the provided conversation context and targeting parameters.
      * Returns `null` if no relevant ad is available or if an error occurs.
      *
      * @param params - Ad request parameters including conversation messages
@@ -260,18 +364,27 @@ declare class Client {
      *
      * @example Basic request
      * ```typescript
-     * const ad = await client.getAd({
+     * const response = await client.getAd({
      *   messages: [
      *     { role: 'user', content: 'I need a new laptop for programming' },
      *     { role: 'assistant', content: 'What is your budget range?' }
-     *   ]
+     *   ],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
      * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
      * ```
      *
      * @example Full request with targeting
      * ```typescript
-     * const ad = await client.getAd({
+     * const response = await client.getAd({
      *   messages: [...],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
      *   user: {
      *     uid: 'user-123',
      *     gender: 'male',
@@ -289,9 +402,10 @@ declare class Client {
      *
      * @example Handling the response
      * ```typescript
-     * const ad = await client.getAd({ messages });
+     * const response = await client.getAd({ messages, sessionId: '...' });
      *
-     * if (ad) {
+     * if (response) {
+     *   const ad = response.ads[0];
      *   // Display the ad
      *   showAd(ad.adText);
      *
@@ -303,6 +417,47 @@ declare class Client {
      * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Request summary-based advertisements
+     *
+     * @description Fetches ads based on a search/summary query string.
+     * Returns null if no relevant ad is available or on error.
+     *
+     * @param params - Request parameters including queryString
+     * @returns Promise resolving to AdResponse or null if no ad available
+     */
+    summaryAd(params: SummaryAdParams): Promise<AdResponse | null>;
+    /**
+     * Request non-contextual advertisements
+     *
+     * @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
+     * @returns Promise resolving to AdResponse or null if no ad available
+     */
+    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponse | null>;
+    /**
+     * Request a bid price for contextual ad placement
+     *
+     * @description First phase of two-phase ad flow. Returns bid price and bidId.
+     * Use the bidId with render() to generate the actual ad creative.
+     * Returns null if no bid is available or on error.
+     *
+     * @param params - Request parameters including messages array
+     * @returns Promise resolving to BidResponse or null if no bid available
+     */
+    bid(params: BidParams): Promise<BidResponse | null>;
+    /**
+     * Render an ad from a cached bid
+     *
+     * @description Second phase of two-phase ad flow. Generates ad creative using cached bid context.
+     * Returns null if bid expired (404) or on error. Bid expires after 60 seconds.
+     *
+     * @param params - Request parameters including bidId and realizedPrice
+     * @returns Promise resolving to AdResponse or null if bid expired/error
+     */
+    render(params: RenderParams): Promise<AdResponse | null>;
     /**
      * Handle and log API errors
      *
@@ -317,4 +472,4 @@ declare class Client {
     private handleError;
 }
 
-export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };
+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 };

package/dist/index.js

@@ -76,7 +76,7 @@ var Client = class {
   /**
    * Request a contextually relevant advertisement
    * 
-   * @description Fetches an ad based on the provided conversation context and targeting parameters.
+   * @description Fetches ads based on the provided conversation context and targeting parameters.
    * Returns `null` if no relevant ad is available or if an error occurs.
    * 
    * @param params - Ad request parameters including conversation messages
@@ -84,18 +84,27 @@ var Client = class {
    * 
    * @example Basic request
    * ```typescript
-   * const ad = await client.getAd({
+   * const response = await client.getAd({
    *   messages: [
    *     { role: 'user', content: 'I need a new laptop for programming' },
    *     { role: 'assistant', content: 'What is your budget range?' }
-   *   ]
+   *   ],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
    * });
+   * 
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
    * ```
    * 
    * @example Full request with targeting
    * ```typescript
-   * const ad = await client.getAd({
+   * const response = await client.getAd({
    *   messages: [...],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
    *     gender: 'male',
@@ -113,9 +122,10 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const ad = await client.getAd({ messages });
+   * const response = await client.getAd({ messages, sessionId: '...' });
    * 
-   * if (ad) {
+   * if (response) {
+   *   const ad = response.ads[0];
    *   // Display the ad
    *   showAd(ad.adText);
    *   
@@ -130,26 +140,134 @@ var Client = class {
     try {
       const body = {
         ...params,
-        // Use request-level excludedTopics, or fall back to client-level
         excludedTopics: params.excludedTopics ?? this.excludedTopics,
-        // Use request-level relevancy, or fall back to client-level
         relevancy: params.relevancy ?? this.relevancy
       };
-      const response = await this.axios.post("/ad", body);
+      const response = await this.axios.post("/api/v1/ad/contextual", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "getAd");
+      return null;
+    }
+  }
+  // ===========================================================================
+  // Alternative Ad Methods (for advanced use cases)
+  // ===========================================================================
+  /**
+   * Request summary-based advertisements
+   *
+   * @description Fetches ads based on a search/summary query string.
+   * Returns null if no relevant ad is available or on error.
+   *
+   * @param params - Request parameters including queryString
+   * @returns Promise resolving to AdResponse or null if no ad available
+   */
+  async summaryAd(params) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics,
+        relevancy: params.relevancy ?? this.relevancy
+      };
+      const response = await this.axios.post("/api/v1/ad/summary", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "summaryAd");
+      return null;
+    }
+  }
+  /**
+   * Request non-contextual advertisements
+   *
+   * @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
+   * @returns Promise resolving to AdResponse or null if no ad available
+   */
+  async nonContextualAd(params = {}) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics
+      };
+      const response = await this.axios.post("/api/v1/ad/non-contextual", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "nonContextualAd");
+      return null;
+    }
+  }
+  /**
+   * Request a bid price for contextual ad placement
+   *
+   * @description First phase of two-phase ad flow. Returns bid price and bidId.
+   * Use the bidId with render() to generate the actual ad creative.
+   * Returns null if no bid is available or on error.
+   *
+   * @param params - Request parameters including messages array
+   * @returns Promise resolving to BidResponse or null if no bid available
+   */
+  async bid(params) {
+    try {
+      const response = await this.axios.post("/api/v1/bid", params);
       if (response.status === 204) {
         return null;
       }
-      if (response.data && response.data.adText) {
+      if (response.data && response.data.data) {
         return {
-          adText: response.data.adText,
-          impUrl: response.data.impUrl,
-          clickUrl: response.data.clickUrl,
-          payout: response.data.payout
+          bid: response.data.data.bid,
+          bidId: response.data.data.bidId
         };
       }
       return null;
     } catch (error) {
-      this.handleError(error, "getAd");
+      this.handleError(error, "bid");
+      return null;
+    }
+  }
+  /**
+   * Render an ad from a cached bid
+   *
+   * @description Second phase of two-phase ad flow. Generates ad creative using cached bid context.
+   * Returns null if bid expired (404) or on error. Bid expires after 60 seconds.
+   *
+   * @param params - Request parameters including bidId and realizedPrice
+   * @returns Promise resolving to AdResponse or null if bid expired/error
+   */
+  async render(params) {
+    try {
+      const response = await this.axios.post("/api/v1/render", params);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      if (import_axios.default.isAxiosError(error) && error.response?.status === 404) {
+        return null;
+      }
+      this.handleError(error, "render");
       return null;
     }
   }

package/dist/index.mjs

@@ -40,7 +40,7 @@ var Client = class {
   /**
    * Request a contextually relevant advertisement
    * 
-   * @description Fetches an ad based on the provided conversation context and targeting parameters.
+   * @description Fetches ads based on the provided conversation context and targeting parameters.
    * Returns `null` if no relevant ad is available or if an error occurs.
    * 
    * @param params - Ad request parameters including conversation messages
@@ -48,18 +48,27 @@ var Client = class {
    * 
    * @example Basic request
    * ```typescript
-   * const ad = await client.getAd({
+   * const response = await client.getAd({
    *   messages: [
    *     { role: 'user', content: 'I need a new laptop for programming' },
    *     { role: 'assistant', content: 'What is your budget range?' }
-   *   ]
+   *   ],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
    * });
+   * 
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
    * ```
    * 
    * @example Full request with targeting
    * ```typescript
-   * const ad = await client.getAd({
+   * const response = await client.getAd({
    *   messages: [...],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
    *     gender: 'male',
@@ -77,9 +86,10 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const ad = await client.getAd({ messages });
+   * const response = await client.getAd({ messages, sessionId: '...' });
    * 
-   * if (ad) {
+   * if (response) {
+   *   const ad = response.ads[0];
    *   // Display the ad
    *   showAd(ad.adText);
    *   
@@ -94,26 +104,134 @@ var Client = class {
     try {
       const body = {
         ...params,
-        // Use request-level excludedTopics, or fall back to client-level
         excludedTopics: params.excludedTopics ?? this.excludedTopics,
-        // Use request-level relevancy, or fall back to client-level
         relevancy: params.relevancy ?? this.relevancy
       };
-      const response = await this.axios.post("/ad", body);
+      const response = await this.axios.post("/api/v1/ad/contextual", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "getAd");
+      return null;
+    }
+  }
+  // ===========================================================================
+  // Alternative Ad Methods (for advanced use cases)
+  // ===========================================================================
+  /**
+   * Request summary-based advertisements
+   *
+   * @description Fetches ads based on a search/summary query string.
+   * Returns null if no relevant ad is available or on error.
+   *
+   * @param params - Request parameters including queryString
+   * @returns Promise resolving to AdResponse or null if no ad available
+   */
+  async summaryAd(params) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics,
+        relevancy: params.relevancy ?? this.relevancy
+      };
+      const response = await this.axios.post("/api/v1/ad/summary", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "summaryAd");
+      return null;
+    }
+  }
+  /**
+   * Request non-contextual advertisements
+   *
+   * @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
+   * @returns Promise resolving to AdResponse or null if no ad available
+   */
+  async nonContextualAd(params = {}) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics
+      };
+      const response = await this.axios.post("/api/v1/ad/non-contextual", body);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "nonContextualAd");
+      return null;
+    }
+  }
+  /**
+   * Request a bid price for contextual ad placement
+   *
+   * @description First phase of two-phase ad flow. Returns bid price and bidId.
+   * Use the bidId with render() to generate the actual ad creative.
+   * Returns null if no bid is available or on error.
+   *
+   * @param params - Request parameters including messages array
+   * @returns Promise resolving to BidResponse or null if no bid available
+   */
+  async bid(params) {
+    try {
+      const response = await this.axios.post("/api/v1/bid", params);
       if (response.status === 204) {
         return null;
       }
-      if (response.data && response.data.adText) {
+      if (response.data && response.data.data) {
         return {
-          adText: response.data.adText,
-          impUrl: response.data.impUrl,
-          clickUrl: response.data.clickUrl,
-          payout: response.data.payout
+          bid: response.data.data.bid,
+          bidId: response.data.data.bidId
         };
       }
       return null;
     } catch (error) {
-      this.handleError(error, "getAd");
+      this.handleError(error, "bid");
+      return null;
+    }
+  }
+  /**
+   * Render an ad from a cached bid
+   *
+   * @description Second phase of two-phase ad flow. Generates ad creative using cached bid context.
+   * Returns null if bid expired (404) or on error. Bid expires after 60 seconds.
+   *
+   * @param params - Request parameters including bidId and realizedPrice
+   * @returns Promise resolving to AdResponse or null if bid expired/error
+   */
+  async render(params) {
+    try {
+      const response = await this.axios.post("/api/v1/render", params);
+      if (response.status === 204) {
+        return null;
+      }
+      if (response.data && response.data.ads && response.data.ads.length > 0) {
+        return response.data;
+      }
+      return null;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404) {
+        return null;
+      }
+      this.handleError(error, "render");
       return null;
     }
   }

package/package.json

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