@gravity-ai/api 1.0.0 → 1.0.2

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
@@ -154,10 +182,9 @@ interface ApiErrorResponse {
     statusCode?: number;
 }
 /**
- * Base fields shared across all v1 ad requests.
- * @description Mirrors engine's AdRequestBaseV1. All fields are optional.
+ * Base fields shared across all ad requests.
  */
-interface AdRequestBaseV1 {
+interface AdRequestBase {
     /** Session identifier for tracking user sessions */
     sessionId?: string;
     /** Unique user identifier */
@@ -177,19 +204,11 @@ interface AdRequestBaseV1 {
     /** 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 {
+interface SummaryAdParams extends AdRequestBase {
     /** Search/summary query string (required) */
     queryString: string;
 }
@@ -197,7 +216,7 @@ interface SummaryAdParams extends AdRequestBaseV1 {
  * POST /api/v1/ad/non-contextual
  * @description No context required - returns ads without context matching.
  */
-interface NonContextualAdParams extends AdRequestBaseV1 {
+interface NonContextualAdParams extends AdRequestBase {
 }
 /**
  * POST /api/v1/bid
@@ -227,45 +246,7 @@ interface RenderParams {
     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.
+ * Bid response.
  * @description Returned by the bid endpoint.
  */
 interface BidResponse {
@@ -318,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);
  * }
  * ```
@@ -373,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
@@ -381,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',
@@ -410,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);
      *
@@ -425,78 +418,27 @@ 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)
+     * 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 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);
-     * }
-     * ```
+     * @returns Promise resolving to AdResponse or null if no ad available
      */
-    summaryAd(params: SummaryAdParams): Promise<AdResponseV1 | null>;
+    summaryAd(params: SummaryAdParams): Promise<AdResponse | null>;
     /**
-     * Request non-contextual advertisements (v1 API)
+     * 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 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));
-     * }
-     * ```
+     * @returns Promise resolving to AdResponse or null if no ad available
      */
-    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponseV1 | null>;
+    nonContextualAd(params?: NonContextualAdParams): Promise<AdResponse | null>;
     /**
-     * Request a bid price for contextual ad placement (v1 API)
+     * 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.
@@ -504,51 +446,18 @@ declare class Client {
      *
      * @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)
+     * 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 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);
-     * }
-     * ```
+     * @returns Promise resolving to AdResponse or null if bid expired/error
      */
-    render(params: RenderParams): Promise<AdResponseV1 | null>;
+    render(params: RenderParams): Promise<AdResponse | null>;
     /**
      * Handle and log API errors
      *
@@ -563,4 +472,4 @@ declare class Client {
     private handleError;
 }
 
-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 };
+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);
    *   
@@ -127,61 +137,6 @@ var Client = class {
    * ```
    */
   async getAd(params) {
-    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);
-      if (response.status === 204) {
-        return null;
-      }
-      if (response.data && response.data.adText) {
-        return {
-          adText: response.data.adText,
-          impUrl: response.data.impUrl,
-          clickUrl: response.data.clickUrl,
-          payout: response.data.payout
-        };
-      }
-      return null;
-    } catch (error) {
-      this.handleError(error, "getAd");
-      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,
@@ -197,31 +152,21 @@ var Client = class {
       }
       return null;
     } catch (error) {
-      this.handleError(error, "contextualAd");
+      this.handleError(error, "getAd");
       return null;
     }
   }
+  // ===========================================================================
+  // Alternative Ad Methods (for advanced use cases)
+  // ===========================================================================
   /**
-   * Request summary-based advertisements (v1 API)
+   * 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 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);
-   * }
-   * ```
+   * @returns Promise resolving to AdResponse or null if no ad available
    */
   async summaryAd(params) {
     try {
@@ -244,25 +189,13 @@ var Client = class {
     }
   }
   /**
-   * Request non-contextual advertisements (v1 API)
+   * 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 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));
-   * }
-   * ```
+   * @returns Promise resolving to AdResponse or null if no ad available
    */
   async nonContextualAd(params = {}) {
     try {
@@ -284,7 +217,7 @@ var Client = class {
     }
   }
   /**
-   * Request a bid price for contextual ad placement (v1 API)
+   * 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.
@@ -292,25 +225,6 @@ var Client = class {
    *
    * @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 {
@@ -331,27 +245,13 @@ var Client = class {
     }
   }
   /**
-   * Render an ad from a cached bid (v1 API)
+   * 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 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);
-   * }
-   * ```
+   * @returns Promise resolving to AdResponse or null if bid expired/error
    */
   async render(params) {
     try {