@gravity-ai/api 1.1.3 → 1.1.5

package/dist/index.d.mts

@@ -1,207 +1,162 @@
+import { G as GravityAdsOptions, I as IncomingAdRequest, M as MessageObject, P as PlacementObject, a as GravityAdsResult, b as GravityContextOverrides, c as GravityContext, A as AdParams, d as Ad } from './types-DYbti_CZ.mjs';
+export { e as ApiErrorResponse, D as DeviceObject, g as Gender, f as Placement, R as Role, U as UserObject } from './types-DYbti_CZ.mjs';
+
 /**
- * Role type for conversation messages
- * @description Indicates whether a message is from the user or the AI assistant
- */
-type Role = 'user' | 'assistant';
-/**
- * Gender type for user targeting
- * @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
+ * Gravity ad client.
+ *
+ * Configure once at startup, then call `getAds()` in your endpoint handlers.
+ * Test ads are returned by default — pass `production: true` when you're ready
+ * to go live.
+ *
  * @example
- * ```typescript
- * const placement: PlacementObject = {
- *   placement: 'below_response',
- *   placement_id: 'sidebar-1'
- * };
+ * ```ts
+ * import { Gravity } from '@gravity-ai/api';
+ *
+ * const gravity = new Gravity({ production: true });
+ *
+ * app.post('/api/chat', async (req, res) => {
+ *   const { messages } = req.body;
+ *   const adPromise = gravity.getAds(req, messages, [
+ *     { placement: 'below_response', placement_id: 'main' },
+ *   ]);
+ *
+ *   // stream your LLM response...
+ *
+ *   const { ads } = await adPromise;
+ *   res.write(`data: ${JSON.stringify({ type: 'done', ads })}\n\n`);
+ *   res.end();
+ * });
  * ```
  */
-interface PlacementObject {
-    /** Position where the ad should appear (required) */
-    placement: Placement;
-    /** Tracking ID for this specific ad slot (required) */
-    placement_id: string;
+declare class Gravity {
+    private opts;
+    /**
+     * @param opts - Configuration applied to every `getAds()` call.
+     *
+     * | Option | Type | Default | Description |
+     * |--------|------|---------|-------------|
+     * | `apiKey` | `string` | `process.env.GRAVITY_API_KEY` | Gravity API key |
+     * | `production` | `boolean` | `false` | `true` = real ads. `false` = test ads (no billing). |
+     * | `relevancy` | `number` | `0.2` | Minimum relevancy threshold (0-1) |
+     * | `timeoutMs` | `number` | `3000` | Request timeout in ms |
+     * | `excludedTopics` | `string[]` | — | Topics to exclude from ad matching |
+     * | `gravityApi` | `string` | production URL | Custom API endpoint |
+     */
+    constructor(opts?: GravityAdsOptions);
+    /**
+     * Fetch ads from the Gravity API. **Never throws.**
+     *
+     * Reads `gravity_context` from `req.body` (sent by the client via
+     * `gravityContext()`), extracts the end-user's IP from request headers,
+     * and calls the Gravity ad endpoint.
+     *
+     * @param req        - Server request object (Express, Fastify, Next.js, etc.)
+     * @param messages   - Conversation `[{ role, content }]` — last 2 turns sent
+     * @param placements - Ad slots, e.g. `[{ placement: "below_response", placement_id: "main" }]`
+     * @param overrides  - Per-call overrides that merge on top of constructor config
+     * @returns `{ ads, status, elapsed, requestBody, error? }` — always resolves
+     */
+    getAds(req: IncomingAdRequest, messages: MessageObject[], placements: PlacementObject[], overrides?: GravityAdsOptions): Promise<GravityAdsResult>;
 }
+
 /**
- * Represents a single message in a conversation
- * @description Used to provide conversation context for contextual ad targeting
- * @example
- * ```typescript
- * const message: MessageObject = {
- *   role: 'user',
- *   content: 'I need help finding a new laptop.'
- * };
+ * Collect device + user context and return a plain object to include
+ * in your request body as `gravity_context`.
+ *
+ * Works in browsers, Node.js, Bun, and Deno. Auto-detects the runtime
+ * and collects the appropriate signals (user-agent, screen size, timezone, etc.).
+ *
+ * Nothing is written to disk, localStorage, or cookies.
+ *
+ * @param overrides - Must include `sessionId` and `user.userId`.
+ *
+ * @example Browser (React, Next.js, vanilla JS)
+ * ```ts
+ * import { gravityContext } from '@gravity-ai/api';
+ *
+ * const ctx = gravityContext({
+ *   sessionId: chatSession.id,
+ *   user: { userId: currentUser.id },
+ * });
+ *
+ * fetch('/api/chat', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ messages, gravity_context: ctx }),
+ * });
  * ```
- */
-interface MessageObject {
-    /** The role of the message sender - either 'user' or 'assistant' */
-    role: Role;
-    /** The text content of the message */
-    content: string;
-}
-/**
- * Device and location information for ad targeting
- * @description Provides device-level context for better ad relevance and compliance
- * @example
- * ```typescript
- * const device: DeviceObject = {
- *   ip: '192.168.1.1',
- *   country: 'US',
- *   ua: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...',
- *   os: 'macOS'
- * };
+ *
+ * @example Node.js CLI
+ * ```ts
+ * const ctx = gravityContext({
+ *   sessionId: conversationId,
+ *   user: { userId: 'cli-user-1' },
+ * });
  * ```
  */
-interface DeviceObject {
-    /** 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;
-    /** 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;
-}
+declare function gravityContext(overrides: GravityContextOverrides): GravityContext;
+
 /**
- * User profile information for ad targeting
- * @description Demographic and interest data for personalized ad delivery
- * @example
- * ```typescript
- * const user: UserObject = {
- *   uid: 'user-123',
- *   gender: 'male',
- *   age: '25-34',
- *   keywords: 'technology,programming,gaming'
- * };
- * ```
+ * Trim conversation to the last N turns sent to Gravity for contextual matching.
  */
-interface UserObject {
-    /** Unique user identifier for improving ad relevance */
-    uid?: string;
-    /** User's gender for demographic targeting */
-    gender?: Gender;
-    /** Age range string (e.g., '18-24', '25-34', '35-44', '45-54', '55-64', '65+') */
-    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;
-}
+declare function toGravityMessages(messages: MessageObject[], maxTurns?: number): MessageObject[];
 /**
- * Parameters for requesting an advertisement
- * @description The complete request payload for the getAd() method
- * @example
- * ```typescript
- * const params: AdParams = {
- *   messages: [
- *     { role: 'user', content: 'What laptop should I buy?' },
- *     { role: 'assistant', content: 'What is your budget?' }
- *   ],
- *   sessionId: 'session-123',
- *   placements: [{ placement: 'below_response' }],
- *   userId: 'user-456',
- *   user: { gender: 'male', age: '25-34' },
- *   device: { ip: '1.2.3.4', country: 'US' },
- *   excludedTopics: ['politics'],
- *   relevancy: 0.5
- * };
- * ```
+ * Extract the end-user's real IP from a server request object.
+ * Works with Express, Fastify, Node http, Next.js, and any object with `headers`.
  */
-interface AdParams {
-    /** Array of conversation messages for contextual targeting (required) */
-    messages: MessageObject[];
-    /** Session identifier for ad relevance (required) */
-    sessionId: string;
-    /** Ad placement specifications (required). Array of 1-10 placements. */
-    placements: PlacementObject[];
-    /** Unique user identifier */
-    userId?: string;
-    /** Device and location information */
-    device?: DeviceObject;
-    /** User demographic and interest data */
-    user?: UserObject;
-    /** Topics to exclude from ad matching (e.g., ['politics', 'religion']) */
-    excludedTopics?: string[];
-    /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
-    relevancy?: number | null;
-    /** Returns a test ad when true (no billing, for integration testing) */
-    testAd?: boolean;
-    /**
-     * Additional custom fields for publisher-specific targeting
-     * @description Any additional key-value pairs will be passed to the API
-     */
-    [key: string]: unknown;
-}
+declare function extractClientIp(req: IncomingAdRequest): string | undefined;
 /**
- * Single ad object in responses.
- * @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'
- * };
+ * Fetch ads from the Gravity API. **Never throws.**
+ *
+ * Reads `gravity_context` from `req.body` (sent by the client via `gravityContext()`),
+ * extracts the end-user's IP from request headers, and calls the Gravity ad endpoint.
+ *
+ * The publisher just passes `req` through — no manual IP extraction or context
+ * forwarding needed.
+ *
+ * @param req        - The server request object (Express, Fastify, Node http, Next.js, etc.)
+ * @param messages   - Conversation messages `[{ role, content }]` — last 2 turns are sent
+ * @param placements - Ad placements, e.g. `[{ placement: "below_response", placement_id: "main" }]`
+ * @param opts       - API key, timeout, relevancy, testAd, etc.
+ * @returns `{ ads, status, elapsed, requestBody, error? }` — always resolves
+ *
+ * @example Express
+ * ```ts
+ * import { gravityAds } from '@gravity-ai/api';
+ *
+ * app.post('/api/chat', async (req, res) => {
+ *   const { messages } = req.body;
+ *
+ *   const adPromise = gravityAds(req, messages, [
+ *     { placement: 'below_response', placement_id: 'main' },
+ *   ]);
+ *
+ *   // stream your LLM response...
+ *
+ *   const { ads } = await adPromise;
+ *   res.write(`data: ${JSON.stringify({ type: 'done', ads })}\n\n`);
+ *   res.end();
+ * });
+ * ```
+ *
+ * @example Next.js Route Handler
+ * ```ts
+ * import { gravityAds } from '@gravity-ai/api';
+ *
+ * export async function POST(request: Request) {
+ *   const body = await request.json();
+ *   const { ads } = await gravityAds(
+ *     { body, headers: Object.fromEntries(request.headers) },
+ *     body.messages,
+ *     [{ placement: 'below_response', placement_id: 'main' }],
+ *   );
+ *   return Response.json({ ads });
+ * }
  * ```
  */
-interface Ad {
-    /** The advertisement copy text */
-    adText: string;
-    /** Ad title */
-    title?: string;
-    /** Call-to-action text (e.g., 'Learn More', 'Shop Now') */
-    cta?: string;
-    /** Brand/advertiser name */
-    brandName?: string;
-    /** Landing page URL */
-    url?: string;
-    /** Favicon URL */
-    favicon?: string;
-    /** Impression tracking URL - fire this when ad is displayed */
-    impUrl?: string;
-    /** Click-through tracking URL - use this as href for ad clicks */
-    clickUrl?: string;
-}
-/**
- * Error response structure from the Gravity API
- * @description Returned when the API encounters an error processing the request
- */
-interface ApiErrorResponse {
-    /** Error code or type identifier */
-    error: string;
-    /** Human-readable error description */
-    message?: string;
-    /** HTTP status code */
-    statusCode?: number;
-}
+declare function gravityAds(req: IncomingAdRequest, messages: MessageObject[], placements: PlacementObject[], opts?: GravityAdsOptions): Promise<GravityAdsResult>;
 
 /**
- * Configuration options for the Gravity API Client
- * @description Pass these options when creating a new Client instance
- * @example
- * ```typescript
- * const params: ClientParams = {
- *   endpoint: 'https://custom.gravity.server',
- *   excludedTopics: ['politics', 'religion'],
- *   relevancy: 0.5
- * };
- * ```
+ * @deprecated Use `Gravity` instead. See README for migration guide.
  */
 interface ClientParams {
     /**
@@ -223,37 +178,13 @@ interface ClientParams {
     relevancy?: number | null;
 }
 /**
- * Gravity API Client
+ * @deprecated Use `Gravity` instead — it reads the API key from env, auto-extracts
+ * client context and IP from the request, and pairs with `gravityContext()` on the client.
  *
- * @description The main client for interacting with the Gravity AI advertising API.
- * Use this client to fetch contextually relevant advertisements based on conversation content.
- *
- * @example Basic usage
- * ```typescript
- * import { Client } from '@gravity-ai/api';
- *
- * const client = new Client('your-api-key');
- *
- * const ads = await client.getAd({
- *   messages: [
- *     { role: 'user', content: 'What laptop should I buy?' }
- *   ],
- *   sessionId: 'session-123',
- *   placements: [{ placement: 'below_response' }]
- * });
- *
- * if (ads) {
- *   console.log(ads[0].adText);
- * }
- * ```
- *
- * @example With configuration options
- * ```typescript
- * const client = new Client('your-api-key', {
- *   endpoint: 'https://custom.server.com',
- *   excludedTopics: ['politics'],
- *   relevancy: 0.7
- * });
+ * ```ts
+ * import { Gravity } from '@gravity-ai/api';
+ * const gravity = new Gravity({ production: true });
+ * const { ads } = await gravity.getAds(req, messages, placements);
  * ```
  */
 declare class Client {
@@ -361,4 +292,4 @@ declare class Client {
     private handleError;
 }
 
-export { type Ad, type AdParams, type ApiErrorResponse, Client, type ClientParams, type DeviceObject, type Gender, type MessageObject, type Placement, type PlacementObject, type Role, type UserObject };
+export { Ad, AdParams, Client, type ClientParams, Gravity, GravityAdsOptions, GravityAdsResult, GravityContext, GravityContextOverrides, IncomingAdRequest, MessageObject, PlacementObject, extractClientIp, gravityAds, gravityContext, toGravityMessages };