@gravity-ai/api 1.1.0 → 1.1.2

package/dist/index.d.mts

@@ -27,38 +27,8 @@ type Placement = 'above_response' | 'below_response' | 'inline_response' | 'left
 interface PlacementObject {
     /** Position where the ad should appear (required) */
     placement: Placement;
-    /** Optional tracking ID for this specific ad slot */
-    placement_id?: string;
-}
-/**
- * Describes how your app will display the ad
- * @description Contains placement array and rendering capabilities for ad customization
- * @example
- * ```typescript
- * const renderContext: RenderContextObject = {
- *   placements: [
- *     { placement: 'below_response' },
- *     { placement: 'right_response', placement_id: 'sidebar' }
- *   ],
- *   max_ad_length: 200
- * };
- * ```
- */
-interface RenderContextObject {
-    /** Where you plan to show the ad(s). Array of 1-3 placements, must match numAds. */
-    placements: PlacementObject[];
-    /** Character limit you can display, so we don't send copy that gets truncated */
-    max_ad_length?: number;
-    /** Whether you can render markdown-formatted text */
-    supports_markdown?: boolean;
-    /** Whether you can render clickable links */
-    supports_links?: boolean;
-    /** Whether you can display images (brand logos, product images) */
-    supports_images?: boolean;
-    /** Whether you can render CTA buttons */
-    supports_cta_button?: boolean;
-    /** Additional render context properties (supports JSON objects) */
-    [key: string]: PlacementObject[] | string | number | boolean | object | null | undefined;
+    /** Tracking ID for this specific ad slot (required) */
+    placement_id: string;
 }
 /**
  * Represents a single message in a conversation
@@ -140,14 +110,10 @@ interface UserObject {
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
  *   sessionId: 'session-123',
- *   numAds: 1,
- *   render_context: {
- *     placements: [{ placement: 'below_response' }]
- *   },
+ *   placements: [{ placement: 'below_response' }],
  *   userId: 'user-456',
- *   testAd: true,
  *   user: { gender: 'male', age: '25-34' },
- *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
+ *   device: { ip: '1.2.3.4', country: 'US' },
  *   excludedTopics: ['politics'],
  *   relevancy: 0.5
  * };
@@ -158,10 +124,8 @@ interface AdParams {
     messages: MessageObject[];
     /** Session identifier for ad relevance (required) */
     sessionId: string;
-    /** Render context with placements array (required). Length of placements must match numAds. */
-    render_context: RenderContextObject;
-    /** Number of ads to return (1-3). Must match render_context.placements length. */
-    numAds?: number;
+    /** Ad placement specifications (required). Array of 1-10 placements. */
+    placements: PlacementObject[];
     /** Unique user identifier */
     userId?: string;
     /** Device and location information */
@@ -172,7 +136,7 @@ interface AdParams {
     excludedTopics?: string[];
     /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
     relevancy?: number | null;
-    /** Returns a test ad when true */
+    /** Returns a test ad when true (no billing, for integration testing) */
     testAd?: boolean;
     /**
      * Additional custom fields for publisher-specific targeting
@@ -182,55 +146,37 @@ interface AdParams {
 }
 /**
  * Single ad object in responses.
- * @description Contains all ad creative and tracking data.
+ * @description Contains ad creative and tracking data. Returned as a flat array from v1 API.
+ * @example
+ * ```typescript
+ * const ad: Ad = {
+ *   adText: 'Check out our amazing laptops!',
+ *   title: 'Dell XPS 15',
+ *   cta: 'Shop Now',
+ *   brandName: 'Dell',
+ *   url: 'https://dell.com/xps',
+ *   impUrl: 'https://tracking.example.com/imp?id=123',
+ *   clickUrl: 'https://tracking.example.com/click?id=123'
+ * };
+ * ```
  */
 interface Ad {
     /** The advertisement copy text */
     adText: string;
-    /** Unique ad identifier */
-    adId: string;
     /** Ad title */
     title?: string;
+    /** Call-to-action text (e.g., 'Learn More', 'Shop Now') */
+    cta?: string;
     /** Brand/advertiser name */
     brandName?: string;
-    /** Brand logo image URL */
-    brandImage?: string;
     /** Landing page URL */
     url?: string;
     /** Favicon URL */
     favicon?: string;
-    /** Impression tracking URL */
+    /** Impression tracking URL - fire this when ad is displayed */
     impUrl?: string;
-    /** Click-through tracking URL */
+    /** Click-through tracking URL - use this as href for ad clicks */
     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 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 {
-    /** 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
@@ -244,85 +190,6 @@ interface ApiErrorResponse {
     /** HTTP status code */
     statusCode?: number;
 }
-/**
- * Base fields shared across all ad requests.
- */
-interface AdRequestBase {
-    /** Session identifier for ad relevance (required) */
-    sessionId: string;
-    /** Render context with placements array (required). Length of placements must match numAds. */
-    render_context: RenderContextObject;
-    /** Number of ads to return (1-3). Must match render_context.placements length. */
-    numAds?: number;
-    /** Unique user identifier */
-    userId?: string;
-    /** Device and location information */
-    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;
-    /** 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.
- */
-interface BidParams {
-    /** Array of conversation messages (required) */
-    messages: MessageObject[];
-    /** Session identifier for ad relevance (required) */
-    sessionId: string;
-    /** Render context with placements array (required). Length of placements must match numAds. */
-    render_context: RenderContextObject;
-    /** Number of ads to return (1-3). Must match render_context.placements length. */
-    numAds?: number;
-    /** Unique user identifier */
-    userId?: string;
-    /** Chat/conversation identifier */
-    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
@@ -367,20 +234,16 @@ interface ClientParams {
  *
  * const client = new Client('your-api-key');
  *
- * const response = await client.getAd({
+ * const ads = await client.getAd({
  *   messages: [
  *     { role: 'user', content: 'What laptop should I buy?' }
  *   ],
  *   sessionId: 'session-123',
- *   numAds: 1,
- *   render_context: {
- *     placements: [{ placement: 'below_response' }]
- *   }
+ *   placements: [{ placement: 'below_response' }]
  * });
  *
- * if (response) {
- *   const ad = response.ads[0];
- *   console.log(ad.adText);
+ * if (ads) {
+ *   console.log(ads[0].adText);
  * }
  * ```
  *
@@ -426,124 +289,64 @@ declare class Client {
      */
     constructor(apiKey: string, params?: ClientParams);
     /**
-     * Request a contextually relevant advertisement
+     * Request contextually relevant advertisements
      *
      * @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
-     * @returns Promise resolving to AdResponse or null if no ad available
+     * @returns Promise resolving to Ad array or null if no ads available
      *
      * @example Basic request
      * ```typescript
-     * const response = await client.getAd({
+     * const ads = 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',
+     *   placements: [{ placement: 'below_response' }]
      * });
      *
-     * if (response) {
-     *   const ad = response.ads[0];
-     *   console.log(ad.adText);
+     * if (ads) {
+     *   console.log(ads[0].adText);
      * }
      * ```
      *
-     * @example Full request with targeting
+     * @example With targeting options
      * ```typescript
-     * const response = await client.getAd({
+     * const ads = await client.getAd({
      *   messages: [...],
      *   sessionId: 'session-123',
-     *   numAds: 1,
-     *   render_context: {
-     *     placements: [{ placement: 'below_response' }],
-     *     max_ad_length: 200
-     *   },
+     *   placements: [{ placement: 'below_response' }],
      *   userId: 'user-456',
-     *   user: {
-     *     uid: 'user-123',
-     *     gender: 'male',
-     *     age: '25-34'
-     *   },
-     *   device: {
-     *     ip: '192.168.1.1',
-     *     country: 'US',
-     *     ua: navigator.userAgent
-     *   },
+     *   user: { gender: 'male', age: '25-34' },
+     *   device: { ip: '192.168.1.1', country: 'US' },
      *   excludedTopics: ['gambling'],
      *   relevancy: 0.8
      * });
      * ```
      *
-     * @example Handling the response
+     * @example Displaying and tracking
      * ```typescript
-     * const response = await client.getAd({
-     *   messages,
-     *   sessionId: '...',
-     *   numAds: 1,
-     *   render_context: { placements: [{ placement: 'below_response' }] }
-     * });
+     * const ads = await client.getAd({ messages, sessionId, placements });
      *
-     * if (response) {
-     *   const ad = response.ads[0];
+     * if (ads && ads.length > 0) {
+     *   const ad = ads[0];
      *   // Display the ad
-     *   showAd(ad.adText);
+     *   showAd(ad.adText, ad.cta);
      *
-     *   // Track impression
+     *   // Track impression when ad is displayed
      *   if (ad.impUrl) {
      *     new Image().src = ad.impUrl;
      *   }
+     *
+     *   // Use clickUrl as the href for clicks
+     *   adLink.href = ad.clickUrl || ad.url;
      * }
      * ```
      */
-    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 - Request parameters (sessionId required)
-     * @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>;
+    getAd(params: AdParams): Promise<Ad[] | null>;
     /**
      * Handle and log API errors
      *
@@ -558,4 +361,4 @@ declare class Client {
     private handleError;
 }
 
-export { type Ad, type AdParams, type AdRequestBase, type AdResponse, type ApiErrorResponse, type BidParams, type BidResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type NonContextualAdParams, type Placement, type PlacementObject, type RenderContextObject, type RenderParams, type Role, type SummaryAdParams, type UserObject };
+export { type Ad, type AdParams, type ApiErrorResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type Placement, type PlacementObject, type Role, type UserObject };