@gravity-ai/api 0.0.1 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @gravity-ai/api
 
-The official Node.js/TypeScript SDK for the Gravity API.
+The official Node.js/TypeScript SDK for the Gravity AI advertising API. Fetch contextually relevant ads based on conversation content.
 
 ## Installation
 
@@ -8,61 +8,240 @@ The official Node.js/TypeScript SDK for the Gravity API.
 npm install @gravity-ai/api
 ```
 
-## Usage
+> **Note:** Requires Node.js 18+
 
-First, import and initialize the client with your API key.
+## Quick Start
 
 ```typescript
 import { Client } from '@gravity-ai/api';
 
-const client = new Client('YOUR_API_KEY');
+const client = new Client('your-api-key');
+
+const ad = await client.getAd({
+  messages: [
+    { role: 'user', content: 'What are some good hiking trails?' },
+    { role: 'assistant', content: 'Here are some popular trails...' }
+  ]
+});
+
+if (ad) {
+  console.log(ad.adText);
+}
 ```
 
-### Fetching an Ad
+## Client Configuration
 
-To request an ad, you need to pass the conversation context (messages). You can also provide optional user or device information to improve targeting.
+### Basic Initialization
+
+```typescript
+import { Client } from '@gravity-ai/api';
+
+const client = new Client('your-api-key');
+```
+
+### Advanced Configuration
+
+```typescript
+import { Client } from '@gravity-ai/api';
+
+const client = new Client('your-api-key', {
+  // Topics to exclude globally (optional)
+  excludedTopics: ['politics', 'religion'],
+  
+  // Minimum relevancy threshold 0-1 (optional)
+  relevancy: 0.8,
+});
+```
+
+#### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `endpoint` | `string` | `'https://server.trygravity.ai'` | API endpoint URL |
+| `excludedTopics` | `string[]` | `[]` | Topics to exclude from ad matching |
+| `relevancy` | `number \| null` | `null` | Minimum relevancy score (0-1) |
+
+## Fetching Ads
+
+### Basic Request
+
+```typescript
+const ad = await client.getAd({
+  messages: [
+    { role: 'user', content: 'I need help finding a new laptop.' },
+    { role: 'assistant', content: 'What is your budget?' }
+  ]
+});
+```
+
+### Full Request with All Options
 
 ```typescript
 const ad = await client.getAd({
+  // Required: conversation messages
   messages: [
     { role: 'user', content: 'I need help finding a new laptop.' },
     { role: 'assistant', content: 'What is your budget?' }
   ],
-  // User context
+  
+  // Optional: user information for targeting
   user: {
-    gender: 'male',
-    age: '25-34'
+    uid: 'user-123',           // Unique user identifier
+    gender: 'male',            // 'male' | 'female' | 'other'
+    age: '25-34',              // Age range string
+    keywords: 'tech,gadgets',  // User interest keywords
   },
-  // Device info
-  device: { 
-    ip: '1.2.3.4', 
-    country: 'US', 
-    ua: 'UA' 
+  
+  // Optional: device information
+  device: {
+    ip: '1.2.3.4',             // User IP address
+    country: 'US',             // ISO country code
+    ua: 'Mozilla/5.0...',      // User agent string
+    os: 'macOS',               // Operating system
+    ifa: 'device-ad-id',       // Advertising identifier
   },
-  // Optional additional context
-  interests: ["coding", "apple", "software development"],
-  summary: "User is building software on his windows laptop but wants an apple laptop"
+  
+  // Optional: additional targeting context
+  excludedTopics: ['politics'],  // Override client-level exclusions
+  relevancy: 0.8,                // Override client-level relevancy
+  
+  // Optional: custom fields (open-ended)
+  interests: ['coding', 'apple', 'software development'],
+  summary: 'User wants a laptop for software development',
 });
+```
+
+### Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `messages` | `MessageObject[]` | ✅ | Conversation history |
+| `user` | `UserObject` | - | User targeting info |
+| `device` | `DeviceObject` | - | Device/location info |
+| `excludedTopics` | `string[]` | - | Topics to exclude |
+| `relevancy` | `number` | - | Min relevancy (0-1) |
+| `apiKey` | `string` | - | Override client API key |
+| `[key: string]` | `any` | - | Custom fields allowed |
+
+### Message Object
+
+```typescript
+interface MessageObject {
+  role: 'user' | 'assistant';
+  content: string;
+}
+```
+
+### User Object
+
+```typescript
+interface UserObject {
+  uid?: string;                              // Unique user ID
+  gender?: 'male' | 'female' | 'other';      // User gender
+  age?: string;                              // Age range (e.g., '25-34')
+  keywords?: string;                         // Interest keywords
+}
+```
+
+### Device Object
+
+```typescript
+interface DeviceObject {
+  ip: string;          // IP address
+  country: string;     // ISO country code
+  ua: string;          // User agent
+  os?: string;         // Operating system
+  ifa?: string;        // Advertising ID
+}
+```
+
+## Ad Response
+
+The `getAd` method returns an `AdResponse` object or `null` if no relevant ad is found.
+
+```typescript
+interface AdResponse {
+  adText: string;       // The ad copy to display
+  impUrl?: string;      // Impression tracking URL (fire on view)
+  clickUrl?: string;    // Click-through URL
+  payout?: number;      // Payout amount
+}
+```
+
+### Handling the Response
+
+```typescript
+const ad = await client.getAd({ messages });
 
 if (ad) {
-  console.log('Ad Text:', ad.adText);
-  console.log('Impression URL:', ad.impUrl);
-  console.log("Click URL:", ad.clickUrl);
-  console.log("Payout", ad.payout)
+  // Display the ad
+  console.log('Ad:', ad.adText);
+  
+  // Track impression (fire pixel)
+  if (ad.impUrl) {
+    fetch(ad.impUrl); // or use an image beacon
+  }
+  
+  // Handle clicks
+  if (ad.clickUrl) {
+    // Navigate user to ad.clickUrl on click
+  }
 } else {
-  console.log('No ad available for this context.');
+  // No relevant ad found - show fallback or nothing
+  console.log('No ad available');
 }
 ```
 
-### Advanced Configuration
+## Error Handling
 
-You can override the default API endpoint or provide global excluded topics during initialization.
+The client handles errors gracefully and returns `null` on failure. Errors are logged to the console.
 
 ```typescript
-const client = new Client('YOUR_API_KEY', {
-  endpoint: 'https://custom.gravity.server',
-  excludedTopics: ['politics', 'religion']
-});
+const ad = await client.getAd({ messages });
+
+// Returns null on:
+// - Network errors
+// - API errors (4xx, 5xx)
+// - No relevant ad (204)
+// - Invalid response data
+
+if (!ad) {
+  // Handle gracefully - don't break the user experience
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import { Client, ClientParams } from '@gravity-ai/api';
+import type { AdParams, AdResponse, MessageObject, DeviceObject, UserObject } from '@gravity-ai/api';
+```
+
+## Using with React
+
+For React applications, consider using the companion package `@gravity-ai/react` which provides ready-to-use components with automatic tracking:
+
+```bash
+npm install @gravity-ai/api @gravity-ai/react
+```
+
+```tsx
+import { Client } from '@gravity-ai/api';
+import { AdBanner } from '@gravity-ai/react';
+
+const client = new Client('your-api-key');
+
+function ChatApp() {
+  const [ad, setAd] = useState(null);
+  
+  useEffect(() => {
+    client.getAd({ messages }).then(setAd);
+  }, [messages]);
+
+  return <AdBanner ad={ad} theme="dark" />;
+}
 ```
 
 ## License

package/dist/index.d.mts

@@ -1,68 +1,318 @@
+/**
+ * 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';
+/**
+ * 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.'
+ * };
+ * ```
+ */
 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'
+ * };
+ * ```
+ */
 interface DeviceObject {
+    /** User's IP address for geo-targeting */
     ip: string;
+    /** ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') */
     country: string;
+    /** User agent string from the browser */
     ua: string;
+    /** Operating system name (e.g., 'macOS', 'Windows', 'iOS', 'Android') */
     os?: string;
+    /** Identifier for Advertisers (mobile advertising ID) */
     ifa?: string;
 }
+/**
+ * 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'
+ * };
+ * ```
+ */
 interface UserObject {
+    /** Unique user identifier for frequency capping and tracking */
     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;
 }
+/**
+ * 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?' }
+ *   ],
+ *   user: { gender: 'male', age: '25-34' },
+ *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
+ *   excludedTopics: ['politics'],
+ *   relevancy: 0.5
+ * };
+ * ```
+ */
 interface AdParams {
+    /** Override the client's API key for this request */
     apiKey?: string;
+    /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
+    /** 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[];
-    [key: string]: any;
+    /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
+    relevancy?: number | null;
+    /**
+     * Additional custom fields for publisher-specific targeting
+     * @description Any additional key-value pairs will be passed to the API
+     */
+    [key: string]: unknown;
 }
+/**
+ * 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
+ * };
+ * ```
+ */
 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;
 }
 /**
- * API error response structure
+ * 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;
 }
 
+/**
+ * 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
+ * };
+ * ```
+ */
 interface ClientParams {
+    /**
+     * Custom API endpoint URL
+     * @default 'https://server.trygravity.ai'
+     */
     endpoint?: string;
+    /**
+     * Topics to exclude from all ad requests
+     * @description These exclusions apply to all getAd() calls unless overridden
+     * @example ['politics', 'religion', 'adult']
+     */
     excludedTopics?: string[];
+    /**
+     * Default minimum relevancy threshold (0-1)
+     * @description Higher values return more relevant ads but may reduce fill rate
+     * @default null (no threshold)
+     */
+    relevancy?: number | null;
 }
 /**
- * Client for the Gravity API
+ * Gravity API 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 ad = await client.getAd({
+ *   messages: [
+ *     { role: 'user', content: 'What laptop should I buy?' }
+ *   ]
+ * });
+ *
+ * if (ad) {
+ *   console.log(ad.adText);
+ * }
+ * ```
+ *
+ * @example With configuration options
+ * ```typescript
+ * const client = new Client('your-api-key', {
+ *   endpoint: 'https://custom.server.com',
+ *   excludedTopics: ['politics'],
+ *   relevancy: 0.7
+ * });
+ * ```
  */
 declare class Client {
+    /** The API key used for authentication */
     private apiKey;
-    private endpoint?;
-    private excludedTopics?;
+    /** The API endpoint URL */
+    private endpoint;
+    /** Topics to exclude from ad matching */
+    private excludedTopics;
+    /** Minimum relevancy threshold */
+    private relevancy;
+    /** Axios HTTP client instance */
     private axios;
+    /**
+     * Create a new Gravity API client
+     *
+     * @param apiKey - Your Gravity API key (required)
+     * @param params - Optional configuration parameters
+     *
+     * @throws Will not throw - invalid API key errors occur on first request
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const client = new Client('your-api-key');
+     *
+     * // With custom options
+     * const client = new Client('your-api-key', {
+     *   excludedTopics: ['gambling', 'alcohol'],
+     *   relevancy: 0.6
+     * });
+     * ```
+     */
     constructor(apiKey: string, params?: ClientParams);
     /**
-     * Request a text advertisement. Returns null if there is no relevant ad found.
-     * @param params - AdParams matching the server schema
-     * @returns Promise<BidResponse | null>
+     * Request a contextually relevant advertisement
+     *
+     * @description Fetches an ad 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
+     *
+     * @example Basic request
+     * ```typescript
+     * const ad = await client.getAd({
+     *   messages: [
+     *     { role: 'user', content: 'I need a new laptop for programming' },
+     *     { role: 'assistant', content: 'What is your budget range?' }
+     *   ]
+     * });
+     * ```
+     *
+     * @example Full request with targeting
+     * ```typescript
+     * const ad = await client.getAd({
+     *   messages: [...],
+     *   user: {
+     *     uid: 'user-123',
+     *     gender: 'male',
+     *     age: '25-34'
+     *   },
+     *   device: {
+     *     ip: '192.168.1.1',
+     *     country: 'US',
+     *     ua: navigator.userAgent
+     *   },
+     *   excludedTopics: ['gambling'],
+     *   relevancy: 0.8
+     * });
+     * ```
+     *
+     * @example Handling the response
+     * ```typescript
+     * const ad = await client.getAd({ messages });
+     *
+     * if (ad) {
+     *   // Display the ad
+     *   showAd(ad.adText);
+     *
+     *   // Track impression
+     *   if (ad.impUrl) {
+     *     new Image().src = ad.impUrl;
+     *   }
+     * }
+     * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
     /**
-     * Handle API errors with logging
-     * @param error - The error object
-     * @param method - The method name where error occurred
+     * Handle and log API errors
+     *
+     * @description Processes errors from API calls and logs appropriate messages.
+     * Distinguishes between network errors, server errors, and unexpected errors.
+     *
+     * @param error - The error object from the failed request
+     * @param method - The name of the method where the error occurred
+     *
+     * @internal This method is for internal use only
      */
     private handleError;
 }

package/dist/index.d.ts

@@ -1,68 +1,318 @@
+/**
+ * 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';
+/**
+ * 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.'
+ * };
+ * ```
+ */
 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'
+ * };
+ * ```
+ */
 interface DeviceObject {
+    /** User's IP address for geo-targeting */
     ip: string;
+    /** ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') */
     country: string;
+    /** User agent string from the browser */
     ua: string;
+    /** Operating system name (e.g., 'macOS', 'Windows', 'iOS', 'Android') */
     os?: string;
+    /** Identifier for Advertisers (mobile advertising ID) */
     ifa?: string;
 }
+/**
+ * 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'
+ * };
+ * ```
+ */
 interface UserObject {
+    /** Unique user identifier for frequency capping and tracking */
     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;
 }
+/**
+ * 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?' }
+ *   ],
+ *   user: { gender: 'male', age: '25-34' },
+ *   device: { ip: '1.2.3.4', country: 'US', ua: 'Mozilla/5.0...' },
+ *   excludedTopics: ['politics'],
+ *   relevancy: 0.5
+ * };
+ * ```
+ */
 interface AdParams {
+    /** Override the client's API key for this request */
     apiKey?: string;
+    /** Array of conversation messages for contextual targeting (required) */
     messages: MessageObject[];
+    /** 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[];
-    [key: string]: any;
+    /** Minimum relevancy score threshold (0-1). Higher = more relevant but fewer ads */
+    relevancy?: number | null;
+    /**
+     * Additional custom fields for publisher-specific targeting
+     * @description Any additional key-value pairs will be passed to the API
+     */
+    [key: string]: unknown;
 }
+/**
+ * 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
+ * };
+ * ```
+ */
 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;
 }
 /**
- * API error response structure
+ * 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;
 }
 
+/**
+ * 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
+ * };
+ * ```
+ */
 interface ClientParams {
+    /**
+     * Custom API endpoint URL
+     * @default 'https://server.trygravity.ai'
+     */
     endpoint?: string;
+    /**
+     * Topics to exclude from all ad requests
+     * @description These exclusions apply to all getAd() calls unless overridden
+     * @example ['politics', 'religion', 'adult']
+     */
     excludedTopics?: string[];
+    /**
+     * Default minimum relevancy threshold (0-1)
+     * @description Higher values return more relevant ads but may reduce fill rate
+     * @default null (no threshold)
+     */
+    relevancy?: number | null;
 }
 /**
- * Client for the Gravity API
+ * Gravity API 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 ad = await client.getAd({
+ *   messages: [
+ *     { role: 'user', content: 'What laptop should I buy?' }
+ *   ]
+ * });
+ *
+ * if (ad) {
+ *   console.log(ad.adText);
+ * }
+ * ```
+ *
+ * @example With configuration options
+ * ```typescript
+ * const client = new Client('your-api-key', {
+ *   endpoint: 'https://custom.server.com',
+ *   excludedTopics: ['politics'],
+ *   relevancy: 0.7
+ * });
+ * ```
  */
 declare class Client {
+    /** The API key used for authentication */
     private apiKey;
-    private endpoint?;
-    private excludedTopics?;
+    /** The API endpoint URL */
+    private endpoint;
+    /** Topics to exclude from ad matching */
+    private excludedTopics;
+    /** Minimum relevancy threshold */
+    private relevancy;
+    /** Axios HTTP client instance */
     private axios;
+    /**
+     * Create a new Gravity API client
+     *
+     * @param apiKey - Your Gravity API key (required)
+     * @param params - Optional configuration parameters
+     *
+     * @throws Will not throw - invalid API key errors occur on first request
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const client = new Client('your-api-key');
+     *
+     * // With custom options
+     * const client = new Client('your-api-key', {
+     *   excludedTopics: ['gambling', 'alcohol'],
+     *   relevancy: 0.6
+     * });
+     * ```
+     */
     constructor(apiKey: string, params?: ClientParams);
     /**
-     * Request a text advertisement. Returns null if there is no relevant ad found.
-     * @param params - AdParams matching the server schema
-     * @returns Promise<BidResponse | null>
+     * Request a contextually relevant advertisement
+     *
+     * @description Fetches an ad 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
+     *
+     * @example Basic request
+     * ```typescript
+     * const ad = await client.getAd({
+     *   messages: [
+     *     { role: 'user', content: 'I need a new laptop for programming' },
+     *     { role: 'assistant', content: 'What is your budget range?' }
+     *   ]
+     * });
+     * ```
+     *
+     * @example Full request with targeting
+     * ```typescript
+     * const ad = await client.getAd({
+     *   messages: [...],
+     *   user: {
+     *     uid: 'user-123',
+     *     gender: 'male',
+     *     age: '25-34'
+     *   },
+     *   device: {
+     *     ip: '192.168.1.1',
+     *     country: 'US',
+     *     ua: navigator.userAgent
+     *   },
+     *   excludedTopics: ['gambling'],
+     *   relevancy: 0.8
+     * });
+     * ```
+     *
+     * @example Handling the response
+     * ```typescript
+     * const ad = await client.getAd({ messages });
+     *
+     * if (ad) {
+     *   // Display the ad
+     *   showAd(ad.adText);
+     *
+     *   // Track impression
+     *   if (ad.impUrl) {
+     *     new Image().src = ad.impUrl;
+     *   }
+     * }
+     * ```
      */
     getAd(params: AdParams): Promise<AdResponse | null>;
     /**
-     * Handle API errors with logging
-     * @param error - The error object
-     * @param method - The method name where error occurred
+     * Handle and log API errors
+     *
+     * @description Processes errors from API calls and logs appropriate messages.
+     * Distinguishes between network errors, server errors, and unexpected errors.
+     *
+     * @param error - The error object from the failed request
+     * @param method - The name of the method where the error occurred
+     *
+     * @internal This method is for internal use only
      */
     private handleError;
 }

package/dist/index.js

@@ -36,14 +36,37 @@ module.exports = __toCommonJS(index_exports);
 
 // client.ts
 var import_axios = __toESM(require("axios"));
+var DEFAULT_ENDPOINT = "https://server.trygravity.ai";
+var REQUEST_TIMEOUT = 1e4;
 var Client = class {
+  /**
+   * Create a new Gravity API client
+   * 
+   * @param apiKey - Your Gravity API key (required)
+   * @param params - Optional configuration parameters
+   * 
+   * @throws Will not throw - invalid API key errors occur on first request
+   * 
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * const client = new Client('your-api-key');
+   * 
+   * // With custom options
+   * const client = new Client('your-api-key', {
+   *   excludedTopics: ['gambling', 'alcohol'],
+   *   relevancy: 0.6
+   * });
+   * ```
+   */
   constructor(apiKey, params = {}) {
     this.apiKey = apiKey;
-    this.endpoint = params.endpoint || "https://server.trygravity.ai";
+    this.endpoint = params.endpoint || DEFAULT_ENDPOINT;
     this.excludedTopics = params.excludedTopics || [];
+    this.relevancy = params.relevancy ?? null;
     this.axios = import_axios.default.create({
       baseURL: this.endpoint,
-      timeout: 1e4,
+      timeout: REQUEST_TIMEOUT,
       headers: {
         "Authorization": `Bearer ${this.apiKey}`,
         "Content-Type": "application/json"
@@ -51,40 +74,97 @@ var Client = class {
     });
   }
   /**
-   * Request a text advertisement. Returns null if there is no relevant ad found.
-   * @param params - AdParams matching the server schema
-   * @returns Promise<BidResponse | null>
+   * Request a contextually relevant advertisement
+   * 
+   * @description Fetches an ad 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
+   * 
+   * @example Basic request
+   * ```typescript
+   * const ad = await client.getAd({
+   *   messages: [
+   *     { role: 'user', content: 'I need a new laptop for programming' },
+   *     { role: 'assistant', content: 'What is your budget range?' }
+   *   ]
+   * });
+   * ```
+   * 
+   * @example Full request with targeting
+   * ```typescript
+   * const ad = await client.getAd({
+   *   messages: [...],
+   *   user: {
+   *     uid: 'user-123',
+   *     gender: 'male',
+   *     age: '25-34'
+   *   },
+   *   device: {
+   *     ip: '192.168.1.1',
+   *     country: 'US',
+   *     ua: navigator.userAgent
+   *   },
+   *   excludedTopics: ['gambling'],
+   *   relevancy: 0.8
+   * });
+   * ```
+   * 
+   * @example Handling the response
+   * ```typescript
+   * const ad = await client.getAd({ messages });
+   * 
+   * if (ad) {
+   *   // Display the ad
+   *   showAd(ad.adText);
+   *   
+   *   // Track impression
+   *   if (ad.impUrl) {
+   *     new Image().src = ad.impUrl;
+   *   }
+   * }
+   * ```
    */
   async getAd(params) {
     try {
       const body = {
         ...params,
-        // prefer explicit apiKey in params, else default to client's apiKey
+        // Prefer explicit apiKey in params, else use client's apiKey
         apiKey: params.apiKey ?? this.apiKey,
-        // supply top-level excludedTopics if not provided
-        excludedTopics: params.excludedTopics ?? this.excludedTopics
+        // 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.status === 204) {
+        return null;
+      }
       if (response.data && response.data.adText) {
-        const payload = response.data;
         return {
-          adText: payload.adText,
-          impUrl: payload.impUrl,
-          clickUrl: payload.clickUrl,
-          payout: payload.payout
+          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;
     }
-    return null;
   }
   /**
-   * Handle API errors with logging
-   * @param error - The error object
-   * @param method - The method name where error occurred
+   * Handle and log API errors
+   * 
+   * @description Processes errors from API calls and logs appropriate messages.
+   * Distinguishes between network errors, server errors, and unexpected errors.
+   * 
+   * @param error - The error object from the failed request
+   * @param method - The name of the method where the error occurred
+   * 
+   * @internal This method is for internal use only
    */
   handleError(error, method) {
     if (import_axios.default.isAxiosError(error)) {

package/dist/index.mjs

@@ -1,13 +1,36 @@
 // client.ts
 import axios from "axios";
+var DEFAULT_ENDPOINT = "https://server.trygravity.ai";
+var REQUEST_TIMEOUT = 1e4;
 var Client = class {
+  /**
+   * Create a new Gravity API client
+   * 
+   * @param apiKey - Your Gravity API key (required)
+   * @param params - Optional configuration parameters
+   * 
+   * @throws Will not throw - invalid API key errors occur on first request
+   * 
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * const client = new Client('your-api-key');
+   * 
+   * // With custom options
+   * const client = new Client('your-api-key', {
+   *   excludedTopics: ['gambling', 'alcohol'],
+   *   relevancy: 0.6
+   * });
+   * ```
+   */
   constructor(apiKey, params = {}) {
     this.apiKey = apiKey;
-    this.endpoint = params.endpoint || "https://server.trygravity.ai";
+    this.endpoint = params.endpoint || DEFAULT_ENDPOINT;
     this.excludedTopics = params.excludedTopics || [];
+    this.relevancy = params.relevancy ?? null;
     this.axios = axios.create({
       baseURL: this.endpoint,
-      timeout: 1e4,
+      timeout: REQUEST_TIMEOUT,
       headers: {
         "Authorization": `Bearer ${this.apiKey}`,
         "Content-Type": "application/json"
@@ -15,40 +38,97 @@ var Client = class {
     });
   }
   /**
-   * Request a text advertisement. Returns null if there is no relevant ad found.
-   * @param params - AdParams matching the server schema
-   * @returns Promise<BidResponse | null>
+   * Request a contextually relevant advertisement
+   * 
+   * @description Fetches an ad 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
+   * 
+   * @example Basic request
+   * ```typescript
+   * const ad = await client.getAd({
+   *   messages: [
+   *     { role: 'user', content: 'I need a new laptop for programming' },
+   *     { role: 'assistant', content: 'What is your budget range?' }
+   *   ]
+   * });
+   * ```
+   * 
+   * @example Full request with targeting
+   * ```typescript
+   * const ad = await client.getAd({
+   *   messages: [...],
+   *   user: {
+   *     uid: 'user-123',
+   *     gender: 'male',
+   *     age: '25-34'
+   *   },
+   *   device: {
+   *     ip: '192.168.1.1',
+   *     country: 'US',
+   *     ua: navigator.userAgent
+   *   },
+   *   excludedTopics: ['gambling'],
+   *   relevancy: 0.8
+   * });
+   * ```
+   * 
+   * @example Handling the response
+   * ```typescript
+   * const ad = await client.getAd({ messages });
+   * 
+   * if (ad) {
+   *   // Display the ad
+   *   showAd(ad.adText);
+   *   
+   *   // Track impression
+   *   if (ad.impUrl) {
+   *     new Image().src = ad.impUrl;
+   *   }
+   * }
+   * ```
    */
   async getAd(params) {
     try {
       const body = {
         ...params,
-        // prefer explicit apiKey in params, else default to client's apiKey
+        // Prefer explicit apiKey in params, else use client's apiKey
         apiKey: params.apiKey ?? this.apiKey,
-        // supply top-level excludedTopics if not provided
-        excludedTopics: params.excludedTopics ?? this.excludedTopics
+        // 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.status === 204) {
+        return null;
+      }
       if (response.data && response.data.adText) {
-        const payload = response.data;
         return {
-          adText: payload.adText,
-          impUrl: payload.impUrl,
-          clickUrl: payload.clickUrl,
-          payout: payload.payout
+          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;
     }
-    return null;
   }
   /**
-   * Handle API errors with logging
-   * @param error - The error object
-   * @param method - The method name where error occurred
+   * Handle and log API errors
+   * 
+   * @description Processes errors from API calls and logs appropriate messages.
+   * Distinguishes between network errors, server errors, and unexpected errors.
+   * 
+   * @param error - The error object from the failed request
+   * @param method - The name of the method where the error occurred
+   * 
+   * @internal This method is for internal use only
    */
   handleError(error, method) {
     if (axios.isAxiosError(error)) {

package/package.json

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