@gravity-ai/api 0.1.1 → 1.0.0

package/README.md

@@ -17,14 +17,18 @@ import { Client } from '@gravity-ai/api';
 
 const client = new Client('your-api-key');
 
-const ad = await client.getAd({
+// Contextual ads (v1 API)
+const response = await client.contextualAd({
   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 (ad) {
+if (response) {
+  const ad = response.ads[0];
   console.log(ad.adText);
 }
 ```
@@ -61,29 +65,47 @@ 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
+---
 
-### Basic Request
+## v1 API Methods
+
+The v1 API provides explicit endpoints for different ad types with multi-ad support.
+
+### `contextualAd()` — Contextual Ads
+
+Fetch ads based on conversation context. Requires `messages` array.
 
 ```typescript
-const ad = await client.getAd({
+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
 });
+
+if (response) {
+  const ad = response.ads[0];
+  console.log(ad.adText);
+}
 ```
 
-### Full Request with All Options
+#### Full Request with All Options
 
 ```typescript
-const ad = await client.getAd({
+const response = await client.contextualAd({
   // 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 +123,158 @@ 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
+### `summaryAd()` — Summary-Based Ads
+
+Fetch ads based on a search query or summary string. Requires `queryString`.
+
+```typescript
+const response = await client.summaryAd({
+  queryString: 'User wants a laptop for software development',
+  sessionId: 'session-123',
+  userId: 'user-456',
+});
+
+if (response) {
+  const ad = response.ads[0];
+  console.log(ad.adText);
+}
+```
+
+### `nonContextualAd()` — Non-Contextual Ads
+
+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
+
+```typescript
+const response = await client.nonContextualAd({
+  sessionId: 'session-123',
+  userId: 'user-456',
+  numAds: 2,  // Request multiple ads
+});
+
+if (response) {
+  response.ads.forEach(ad => console.log(ad.adText));
+}
+```
+
+### `bid()` + `render()` — Two-Phase Flow
+
+For publishers who need to know the clearing price before rendering the ad.
+
+```typescript
+// Phase 1: Get bid price
+const bidResult = await client.bid({
+  messages: [
+    { role: 'user', content: 'I need help with my code' }
+  ],
+  sessionId: 'session-123',
+});
+
+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);
+  }
+}
+```
+
+> **Note:** Bids expire after 60 seconds. Call `render()` promptly after `bid()`.
+
+---
+
+## v1 Request Parameters
+
+### Base Parameters (All v1 Methods)
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `messages` | `MessageObject[]` | ✅ | Conversation history |
-| `user` | `UserObject` | - | User targeting info |
+| `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 |
+
+### Method-Specific Parameters
+
+| 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 |
+
+---
+
+## v1 Response Types
+
+### AdResponseV1
+
+Returned by `contextualAd()`, `summaryAd()`, `nonContextualAd()`, and `render()`.
+
+```typescript
+interface AdResponseV1 {
+  ads: AdV1[];           // Array of ads
+  numAds: number;        // Number of ads returned
+  totalPayout?: number;  // Total payout across all ads
+}
+
+interface AdV1 {
+  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
+}
+```
+
+### BidResponse
+
+Returned by `bid()`.
+
+```typescript
+interface BidResponse {
+  bid: number;     // Clearing price (CPM)
+  bidId: string;   // Use this in render()
+}
+```
+
+---
+
+## Common Types
 
 ### Message Object
 
@@ -155,39 +308,59 @@ interface DeviceObject {
 }
 ```
 
-## Ad Response
+---
+
+## Legacy API (v0)
 
-The `getAd` method returns an `AdResponse` object or `null` if no relevant ad is found.
+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 (fire on view)
+  impUrl?: string;      // Impression tracking URL
   clickUrl?: string;    // Click-through URL
   payout?: number;      // Payout amount
 }
 ```
 
-### Handling the Response
+### Handling the Legacy Response
 
 ```typescript
 const ad = await client.getAd({ messages });
 
 if (ad) {
-  // Display the ad
   console.log('Ad:', ad.adText);
   
-  // Track impression (fire pixel)
+  // Track impression
   if (ad.impUrl) {
-    fetch(ad.impUrl); // or use an image beacon
-  }
-  
-  // Handle clicks
-  if (ad.clickUrl) {
-    // Navigate user to ad.clickUrl on click
+    fetch(ad.impUrl);
   }
 } else {
-  // No relevant ad found - show fallback or nothing
   console.log('No ad available');
 }
 ```
@@ -197,15 +370,16 @@ if (ad) {
 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.contextualAd({ messages, sessionId: '...' });
 
 // Returns null on:
 // - Network errors
 // - API errors (4xx, 5xx)
 // - No relevant ad (204)
 // - Invalid response data
+// - Expired bid (404 for render())
 
-if (!ad) {
+if (!response) {
   // Handle gracefully - don't break the user experience
 }
 ```
@@ -216,7 +390,24 @@ 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 { 
+  // 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
@@ -237,13 +428,31 @@ function ChatApp() {
   const [ad, setAd] = useState(null);
   
   useEffect(() => {
-    client.getAd({ messages }).then(setAd);
+    client.contextualAd({ 
+      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. **Choose the right method**:
+   - Chat/conversation → `contextualAd()`
+   - Chat summary → `summaryAd()`
+   - Brand awareness → `nonContextualAd()`
+   - Custom auction → `bid()` + `render()`
+
+3. **Handle null responses gracefully** — Don't break the user experience when no ad is available.
+
+4. **Fire impression url** — Use the `impUrl` when the ad becomes visible to properly track impressions.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -153,6 +153,127 @@ interface ApiErrorResponse {
     /** HTTP status code */
     statusCode?: number;
 }
+/**
+ * Base fields shared across all v1 ad requests.
+ * @description Mirrors engine's AdRequestBaseV1. All fields are optional.
+ */
+interface AdRequestBaseV1 {
+    /** 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/contextual
+ * @description Requires messages array for contextual targeting.
+ */
+interface ContextualAdParams extends AdRequestBaseV1 {
+    /** Array of conversation messages (required) */
+    messages: MessageObject[];
+}
+/**
+ * POST /api/v1/ad/summary
+ * @description Requires queryString for summary-based targeting.
+ */
+interface SummaryAdParams extends AdRequestBaseV1 {
+    /** 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 AdRequestBaseV1 {
+}
+/**
+ * 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;
+}
+/**
+ * Single ad object in v1 responses.
+ * @description Contains all ad creative and tracking data.
+ */
+interface AdV1 {
+    /** 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;
+}
+/**
+ * v1 ad response (multi-ad support).
+ * @description Returned by contextual, summary, non-contextual, and render endpoints.
+ */
+interface AdResponseV1 {
+    /** Array of ad objects */
+    ads: AdV1[];
+    /** Number of ads returned */
+    numAds: number;
+    /** Total payout across all ads */
+    totalPayout?: number;
+}
+/**
+ * v1 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
@@ -303,6 +424,131 @@ declare class Client {
      * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Request contextual advertisements (v1 API)
+     *
+     * @description Fetches ads based on conversation context. Requires messages array.
+     * Returns null if no relevant ad is available or on error.
+     *
+     * @param params - Request parameters including messages array
+     * @returns Promise resolving to AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.contextualAd({
+     *   messages: [
+     *     { role: 'user', content: 'What laptop should I buy?' }
+     *   ],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
+     * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
+     * ```
+     */
+    contextualAd(params: ContextualAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request summary-based advertisements (v1 API)
+     *
+     * @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 AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.summaryAd({
+     *   queryString: 'best laptops for programming 2025',
+     *   sessionId: 'session-123',
+     * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
+     * ```
+     */
+    summaryAd(params: SummaryAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request non-contextual advertisements (v1 API)
+     *
+     * @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 AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.nonContextualAd({
+     *   sessionId: 'session-123',
+     *   numAds: 2,
+     * });
+     *
+     * if (response) {
+     *   response.ads.forEach(ad => console.log(ad.adText));
+     * }
+     * ```
+     */
+    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request a bid price for contextual ad placement (v1 API)
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const bidResult = await client.bid({
+     *   messages: [
+     *     { role: 'user', content: 'I need help with my code' }
+     *   ],
+     *   sessionId: 'session-123',
+     * });
+     *
+     * if (bidResult) {
+     *   console.log(`Bid price: $${bidResult.bid} CPM`);
+     *   // Decide whether to show ad based on price...
+     *   const ad = await client.render({
+     *     bidId: bidResult.bidId,
+     *     realizedPrice: bidResult.bid,
+     *   });
+     * }
+     * ```
+     */
+    bid(params: BidParams): Promise<BidResponse | null>;
+    /**
+     * Render an ad from a cached bid (v1 API)
+     *
+     * @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 AdResponseV1 or null if bid expired/error
+     *
+     * @example
+     * ```typescript
+     * // After getting a bid...
+     * const ad = await client.render({
+     *   bidId: bidResult.bidId,
+     *   realizedPrice: bidResult.bid,
+     * });
+     *
+     * if (ad) {
+     *   const firstAd = ad.ads[0];
+     *   displayAd(firstAd);
+     * }
+     * ```
+     */
+    render(params: RenderParams): Promise<AdResponseV1 | null>;
     /**
      * Handle and log API errors
      *
@@ -317,4 +563,4 @@ declare class Client {
     private handleError;
 }
 
-export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };
+export { type AdParams, type AdRequestBaseV1, type AdResponse, type AdResponseV1, type AdV1, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type ContextualAdParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type RenderParams, type Role, type SummaryAdParams, type UserObject };

package/dist/index.d.ts

@@ -153,6 +153,127 @@ interface ApiErrorResponse {
     /** HTTP status code */
     statusCode?: number;
 }
+/**
+ * Base fields shared across all v1 ad requests.
+ * @description Mirrors engine's AdRequestBaseV1. All fields are optional.
+ */
+interface AdRequestBaseV1 {
+    /** 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/contextual
+ * @description Requires messages array for contextual targeting.
+ */
+interface ContextualAdParams extends AdRequestBaseV1 {
+    /** Array of conversation messages (required) */
+    messages: MessageObject[];
+}
+/**
+ * POST /api/v1/ad/summary
+ * @description Requires queryString for summary-based targeting.
+ */
+interface SummaryAdParams extends AdRequestBaseV1 {
+    /** 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 AdRequestBaseV1 {
+}
+/**
+ * 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;
+}
+/**
+ * Single ad object in v1 responses.
+ * @description Contains all ad creative and tracking data.
+ */
+interface AdV1 {
+    /** 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;
+}
+/**
+ * v1 ad response (multi-ad support).
+ * @description Returned by contextual, summary, non-contextual, and render endpoints.
+ */
+interface AdResponseV1 {
+    /** Array of ad objects */
+    ads: AdV1[];
+    /** Number of ads returned */
+    numAds: number;
+    /** Total payout across all ads */
+    totalPayout?: number;
+}
+/**
+ * v1 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
@@ -303,6 +424,131 @@ declare class Client {
      * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Request contextual advertisements (v1 API)
+     *
+     * @description Fetches ads based on conversation context. Requires messages array.
+     * Returns null if no relevant ad is available or on error.
+     *
+     * @param params - Request parameters including messages array
+     * @returns Promise resolving to AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.contextualAd({
+     *   messages: [
+     *     { role: 'user', content: 'What laptop should I buy?' }
+     *   ],
+     *   sessionId: 'session-123',
+     *   userId: 'user-456',
+     * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
+     * ```
+     */
+    contextualAd(params: ContextualAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request summary-based advertisements (v1 API)
+     *
+     * @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 AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.summaryAd({
+     *   queryString: 'best laptops for programming 2025',
+     *   sessionId: 'session-123',
+     * });
+     *
+     * if (response) {
+     *   const ad = response.ads[0];
+     *   console.log(ad.adText);
+     * }
+     * ```
+     */
+    summaryAd(params: SummaryAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request non-contextual advertisements (v1 API)
+     *
+     * @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 AdResponseV1 or null if no ad available
+     *
+     * @example
+     * ```typescript
+     * const response = await client.nonContextualAd({
+     *   sessionId: 'session-123',
+     *   numAds: 2,
+     * });
+     *
+     * if (response) {
+     *   response.ads.forEach(ad => console.log(ad.adText));
+     * }
+     * ```
+     */
+    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponseV1 | null>;
+    /**
+     * Request a bid price for contextual ad placement (v1 API)
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const bidResult = await client.bid({
+     *   messages: [
+     *     { role: 'user', content: 'I need help with my code' }
+     *   ],
+     *   sessionId: 'session-123',
+     * });
+     *
+     * if (bidResult) {
+     *   console.log(`Bid price: $${bidResult.bid} CPM`);
+     *   // Decide whether to show ad based on price...
+     *   const ad = await client.render({
+     *     bidId: bidResult.bidId,
+     *     realizedPrice: bidResult.bid,
+     *   });
+     * }
+     * ```
+     */
+    bid(params: BidParams): Promise<BidResponse | null>;
+    /**
+     * Render an ad from a cached bid (v1 API)
+     *
+     * @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 AdResponseV1 or null if bid expired/error
+     *
+     * @example
+     * ```typescript
+     * // After getting a bid...
+     * const ad = await client.render({
+     *   bidId: bidResult.bidId,
+     *   realizedPrice: bidResult.bid,
+     * });
+     *
+     * if (ad) {
+     *   const firstAd = ad.ads[0];
+     *   displayAd(firstAd);
+     * }
+     * ```
+     */
+    render(params: RenderParams): Promise<AdResponseV1 | null>;
     /**
      * Handle and log API errors
      *
@@ -317,4 +563,4 @@ declare class Client {
     private handleError;
 }
 
-export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };
+export { type AdParams, type AdRequestBaseV1, type AdResponse, type AdResponseV1, type AdV1, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type ContextualAdParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type RenderParams, type Role, type SummaryAdParams, type UserObject };

package/dist/index.js

@@ -130,8 +130,6 @@ var Client = class {
     try {
       const body = {
         ...params,
-        // Prefer explicit apiKey in params, else use client's apiKey
-        apiKey: params.apiKey ?? this.apiKey,
         // 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
@@ -155,6 +153,224 @@ var Client = class {
       return null;
     }
   }
+  // ===========================================================================
+  // v1 API Methods
+  // ===========================================================================
+  /**
+   * Request contextual advertisements (v1 API)
+   *
+   * @description Fetches ads based on conversation context. Requires messages array.
+   * Returns null if no relevant ad is available or on error.
+   *
+   * @param params - Request parameters including messages array
+   * @returns Promise resolving to AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.contextualAd({
+   *   messages: [
+   *     { role: 'user', content: 'What laptop should I buy?' }
+   *   ],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
+   * });
+   *
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
+   * ```
+   */
+  async contextualAd(params) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics,
+        relevancy: params.relevancy ?? this.relevancy
+      };
+      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, "contextualAd");
+      return null;
+    }
+  }
+  /**
+   * Request summary-based advertisements (v1 API)
+   *
+   * @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 AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.summaryAd({
+   *   queryString: 'best laptops for programming 2025',
+   *   sessionId: 'session-123',
+   * });
+   *
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
+   * ```
+   */
+  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 (v1 API)
+   *
+   * @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 AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.nonContextualAd({
+   *   sessionId: 'session-123',
+   *   numAds: 2,
+   * });
+   *
+   * if (response) {
+   *   response.ads.forEach(ad => console.log(ad.adText));
+   * }
+   * ```
+   */
+  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 (v1 API)
+   *
+   * @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
+   *
+   * @example
+   * ```typescript
+   * const bidResult = await client.bid({
+   *   messages: [
+   *     { role: 'user', content: 'I need help with my code' }
+   *   ],
+   *   sessionId: 'session-123',
+   * });
+   *
+   * if (bidResult) {
+   *   console.log(`Bid price: $${bidResult.bid} CPM`);
+   *   // Decide whether to show ad based on price...
+   *   const ad = await client.render({
+   *     bidId: bidResult.bidId,
+   *     realizedPrice: bidResult.bid,
+   *   });
+   * }
+   * ```
+   */
+  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.data) {
+        return {
+          bid: response.data.data.bid,
+          bidId: response.data.data.bidId
+        };
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "bid");
+      return null;
+    }
+  }
+  /**
+   * Render an ad from a cached bid (v1 API)
+   *
+   * @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 AdResponseV1 or null if bid expired/error
+   *
+   * @example
+   * ```typescript
+   * // After getting a bid...
+   * const ad = await client.render({
+   *   bidId: bidResult.bidId,
+   *   realizedPrice: bidResult.bid,
+   * });
+   *
+   * if (ad) {
+   *   const firstAd = ad.ads[0];
+   *   displayAd(firstAd);
+   * }
+   * ```
+   */
+  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;
+    }
+  }
   /**
    * Handle and log API errors
    * 

package/dist/index.mjs

@@ -94,8 +94,6 @@ var Client = class {
     try {
       const body = {
         ...params,
-        // Prefer explicit apiKey in params, else use client's apiKey
-        apiKey: params.apiKey ?? this.apiKey,
         // 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
@@ -119,6 +117,224 @@ var Client = class {
       return null;
     }
   }
+  // ===========================================================================
+  // v1 API Methods
+  // ===========================================================================
+  /**
+   * Request contextual advertisements (v1 API)
+   *
+   * @description Fetches ads based on conversation context. Requires messages array.
+   * Returns null if no relevant ad is available or on error.
+   *
+   * @param params - Request parameters including messages array
+   * @returns Promise resolving to AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.contextualAd({
+   *   messages: [
+   *     { role: 'user', content: 'What laptop should I buy?' }
+   *   ],
+   *   sessionId: 'session-123',
+   *   userId: 'user-456',
+   * });
+   *
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
+   * ```
+   */
+  async contextualAd(params) {
+    try {
+      const body = {
+        ...params,
+        excludedTopics: params.excludedTopics ?? this.excludedTopics,
+        relevancy: params.relevancy ?? this.relevancy
+      };
+      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, "contextualAd");
+      return null;
+    }
+  }
+  /**
+   * Request summary-based advertisements (v1 API)
+   *
+   * @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 AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.summaryAd({
+   *   queryString: 'best laptops for programming 2025',
+   *   sessionId: 'session-123',
+   * });
+   *
+   * if (response) {
+   *   const ad = response.ads[0];
+   *   console.log(ad.adText);
+   * }
+   * ```
+   */
+  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 (v1 API)
+   *
+   * @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 AdResponseV1 or null if no ad available
+   *
+   * @example
+   * ```typescript
+   * const response = await client.nonContextualAd({
+   *   sessionId: 'session-123',
+   *   numAds: 2,
+   * });
+   *
+   * if (response) {
+   *   response.ads.forEach(ad => console.log(ad.adText));
+   * }
+   * ```
+   */
+  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 (v1 API)
+   *
+   * @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
+   *
+   * @example
+   * ```typescript
+   * const bidResult = await client.bid({
+   *   messages: [
+   *     { role: 'user', content: 'I need help with my code' }
+   *   ],
+   *   sessionId: 'session-123',
+   * });
+   *
+   * if (bidResult) {
+   *   console.log(`Bid price: $${bidResult.bid} CPM`);
+   *   // Decide whether to show ad based on price...
+   *   const ad = await client.render({
+   *     bidId: bidResult.bidId,
+   *     realizedPrice: bidResult.bid,
+   *   });
+   * }
+   * ```
+   */
+  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.data) {
+        return {
+          bid: response.data.data.bid,
+          bidId: response.data.data.bidId
+        };
+      }
+      return null;
+    } catch (error) {
+      this.handleError(error, "bid");
+      return null;
+    }
+  }
+  /**
+   * Render an ad from a cached bid (v1 API)
+   *
+   * @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 AdResponseV1 or null if bid expired/error
+   *
+   * @example
+   * ```typescript
+   * // After getting a bid...
+   * const ad = await client.render({
+   *   bidId: bidResult.bidId,
+   *   realizedPrice: bidResult.bid,
+   * });
+   *
+   * if (ad) {
+   *   const firstAd = ad.ads[0];
+   *   displayAd(firstAd);
+   * }
+   * ```
+   */
+  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;
+    }
+  }
   /**
    * Handle and log API errors
    * 

package/package.json

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