@gravity-ai/api 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -8,6 +8,58 @@ type Role = 'user' | 'assistant';
  * @description Used for demographic targeting of advertisements
  */
 type Gender = 'male' | 'female' | 'other';
+/**
+ * Placement positions for ad rendering
+ * @description Specifies where ads should appear relative to the AI response
+ */
+type Placement = 'above_response' | 'below_response' | 'inline_response' | 'left_response' | 'right_response';
+/**
+ * Individual ad placement specification
+ * @description Defines a single ad slot with its position and optional tracking ID
+ * @example
+ * ```typescript
+ * const placement: PlacementObject = {
+ *   placement: 'below_response',
+ *   placement_id: 'sidebar-1'
+ * };
+ * ```
+ */
+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;
+}
 /**
  * Represents a single message in a conversation
  * @description Used to provide conversation context for contextual ad targeting
@@ -39,16 +91,18 @@ interface MessageObject {
  * ```
  */
 interface DeviceObject {
-    /** User's IP address for geo-targeting */
+    /** User's IP address for geo-targeting (required) */
     ip: string;
+    /** Browser user-agent string (optional for non-web publishers like IDEs, CLIs, mobile apps) */
+    ua?: string;
     /** ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') */
-    country: string;
-    /** User agent string from the browser */
-    ua: string;
+    country?: string;
     /** Operating system name (e.g., 'macOS', 'Windows', 'iOS', 'Android') */
     os?: string;
     /** Identifier for Advertisers (mobile advertising ID) */
     ifa?: string;
+    /** Additional device properties (timezone, locale, browser, device_type, screen dimensions, etc.) */
+    [key: string]: string | number | boolean | undefined;
 }
 /**
  * User profile information for ad targeting
@@ -64,7 +118,7 @@ interface DeviceObject {
  * ```
  */
 interface UserObject {
-    /** Unique user identifier for frequency capping and tracking */
+    /** Unique user identifier for improving ad relevance */
     uid?: string;
     /** User's gender for demographic targeting */
     gender?: Gender;
@@ -72,6 +126,8 @@ interface UserObject {
     age?: string;
     /** Comma-separated keywords representing user interests */
     keywords?: string;
+    /** Additional user properties (email, subscription_tier, user_interests, company_size, etc.) */
+    [key: string]: string | string[] | number | boolean | Gender | undefined;
 }
 /**
  * Parameters for requesting an advertisement
@@ -83,6 +139,13 @@ interface UserObject {
  *     { role: 'user', content: 'What laptop should I buy?' },
  *     { role: 'assistant', content: 'What is your budget?' }
  *   ],
+ *   sessionId: 'session-123',
+ *   numAds: 1,
+ *   render_context: {
+ *     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...' },
  *   excludedTopics: ['politics'],
@@ -91,10 +154,16 @@ 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 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 */
@@ -103,43 +172,65 @@ 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 */
+    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,12 +245,15 @@ 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 {
-    /** Session identifier for tracking user sessions */
-    sessionId?: string;
+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 */
@@ -170,26 +264,16 @@ interface AdRequestBaseV1 {
     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 {
+interface SummaryAdParams extends AdRequestBase {
     /** Search/summary query string (required) */
     queryString: string;
 }
@@ -197,18 +281,21 @@ 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
  * @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;
+    /** 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 */
@@ -227,45 +314,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 +367,19 @@ 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',
+ *   numAds: 1,
+ *   render_context: {
+ *     placements: [{ placement: 'below_response' }]
+ *   }
  * });
  *
- * if (ad) {
+ * if (response) {
+ *   const ad = response.ads[0];
  *   console.log(ad.adText);
  * }
  * ```
@@ -373,7 +428,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 +436,36 @@ 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',
+     *   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',
@@ -410,9 +483,15 @@ declare class Client {
      *
      * @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);
      *
@@ -425,78 +504,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));
-     * }
-     * ```
+     * @param params - Request parameters (sessionId required)
+     * @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 +532,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 +558,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 Placement, type PlacementObject, type RenderContextObject, type RenderParams, type Role, type SummaryAdParams, type UserObject };