@gravity-ai/api 1.0.0 → 1.1.0

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,36 @@ 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',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }]
+   *   },
+   *   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',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }],
+   *     max_ad_length: 200
+   *   },
+   *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
    *     gender: 'male',
@@ -113,9 +131,15 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const ad = await client.getAd({ messages });
+   * const response = await client.getAd({
+   *   messages,
+   *   sessionId: '...',
+   *   numAds: 1,
+   *   render_context: { placements: [{ placement: 'below_response' }] }
+   * });
    * 
-   * if (ad) {
+   * if (response) {
+   *   const ad = response.ads[0];
    *   // Display the ad
    *   showAd(ad.adText);
    *   
@@ -127,61 +151,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 +166,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,27 +203,15 @@ 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));
-   * }
-   * ```
+   * @param params - Request parameters (sessionId required)
+   * @returns Promise resolving to AdResponse or null if no ad available
    */
-  async nonContextualAd(params = {}) {
+  async nonContextualAd(params) {
     try {
       const body = {
         ...params,
@@ -284,7 +231,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 +239,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 +259,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 {

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,36 @@ 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',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }]
+   *   },
+   *   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',
+   *   numAds: 1,
+   *   render_context: {
+   *     placements: [{ placement: 'below_response' }],
+   *     max_ad_length: 200
+   *   },
+   *   userId: 'user-456',
    *   user: {
    *     uid: 'user-123',
    *     gender: 'male',
@@ -77,9 +95,15 @@ var Client = class {
    * 
    * @example Handling the response
    * ```typescript
-   * const ad = await client.getAd({ messages });
+   * const response = await client.getAd({
+   *   messages,
+   *   sessionId: '...',
+   *   numAds: 1,
+   *   render_context: { placements: [{ placement: 'below_response' }] }
+   * });
    * 
-   * if (ad) {
+   * if (response) {
+   *   const ad = response.ads[0];
    *   // Display the ad
    *   showAd(ad.adText);
    *   
@@ -91,61 +115,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,
@@ -161,31 +130,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 {
@@ -208,27 +167,15 @@ 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));
-   * }
-   * ```
+   * @param params - Request parameters (sessionId required)
+   * @returns Promise resolving to AdResponse or null if no ad available
    */
-  async nonContextualAd(params = {}) {
+  async nonContextualAd(params) {
     try {
       const body = {
         ...params,
@@ -248,7 +195,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.
@@ -256,25 +203,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 {
@@ -295,27 +223,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 {

package/package.json

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