@gravity-ai/api 1.1.3 → 1.1.5

package/dist/types-DYbti_CZ.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 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
+ * @example
+ * ```typescript
+ * const placement: PlacementObject = {
+ *   placement: 'below_response',
+ *   placement_id: 'sidebar-1'
+ * };
+ * ```
+ */
+interface PlacementObject {
+    /** Position where the ad should appear (required) */
+    placement: Placement;
+    /** Tracking ID for this specific ad slot (required) */
+    placement_id: string;
+}
+/**
+ * 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 (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;
+}
+/**
+ * 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 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;
+}
+/**
+ * @deprecated Use `Gravity.getAds()` or `gravityAds()` instead, which accept
+ * standard request objects and auto-extract context from `gravityContext()`.
+ */
+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;
+}
+/**
+ * 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'
+ * };
+ * ```
+ */
+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;
+}
+/**
+ * Overrides passed to `gravityContext()`.
+ * `sessionId` and `user.userId` are required; everything else is auto-detected.
+ */
+interface GravityContextOverrides {
+    /** Your chat/conversation session ID (required) */
+    sessionId: string;
+    /** User info — `userId` is required */
+    user: {
+        userId: string;
+    } & Record<string, unknown>;
+    /** Device field overrides (timezone, locale, etc.) */
+    device?: Record<string, unknown>;
+}
+/** The context object returned by `gravityContext()` and sent in the request body. */
+interface GravityContext {
+    sessionId: string;
+    user: {
+        id: string;
+    } & Record<string, unknown>;
+    device: Record<string, unknown>;
+}
+/** Options for `gravityAds()`. */
+interface GravityAdsOptions {
+    /** Gravity API key. Defaults to `process.env.GRAVITY_API_KEY`. */
+    apiKey?: string;
+    /** Gravity ad endpoint URL. Defaults to production. */
+    gravityApi?: string;
+    /** Abort after this many ms. Default: `3000`. */
+    timeoutMs?: number;
+    /** Minimum relevancy threshold (0-1). Default: `0.2`. */
+    relevancy?: number;
+    /**
+     * Serve real ads when `true`. Defaults to `false` (test ads, no billing).
+     * Pass `production: true` when you're ready to go live.
+     */
+    production?: boolean;
+    /** Topics to exclude from ad matching. */
+    excludedTopics?: string[];
+}
+/** Result returned by `gravityAds()`. Never throws. */
+interface GravityAdsResult {
+    /** Matched ads (empty array on failure or no-fill). */
+    ads: Ad[];
+    /** HTTP status from the Gravity API. `0` = network error or missing API key. */
+    status: number;
+    /** Round-trip time in ms (string for easy logging). */
+    elapsed: string;
+    /** The full request body sent to Gravity (useful for debugging). */
+    requestBody: Record<string, unknown> | null;
+    /** Error message, only present on failure. */
+    error?: string;
+}
+/**
+ * Minimal server request shape that `gravityAds()` can read.
+ * Compatible with Express, Fastify, Node http (with body-parser), Next.js, etc.
+ */
+interface IncomingAdRequest {
+    body?: {
+        gravity_context?: GravityContext;
+        [key: string]: unknown;
+    };
+    headers?: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    ip?: string;
+}
+
+export type { AdParams as A, DeviceObject as D, GravityAdsOptions as G, IncomingAdRequest as I, MessageObject as M, PlacementObject as P, Role as R, UserObject as U, GravityAdsResult as a, GravityContextOverrides as b, GravityContext as c, Ad as d, ApiErrorResponse as e, Placement as f, Gender as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ai/api",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Gravity JS SDK for retrieving targeted advertisements",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,12 +13,17 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
+    },
+    "./opentui": {
+      "types": "./dist/opentui.d.ts",
+      "require": "./dist/opentui.js",
+      "import": "./dist/opentui.mjs"
     }
   },
   "scripts": {
-    "build": "tsup index.ts --format cjs,esm --dts",
+    "build": "tsup index.ts opentui.ts --format cjs,esm --dts",
     "clean": "rm -rf dist",
-    "dev": "tsup index.ts --format cjs,esm --watch --dts",
+    "dev": "tsup index.ts opentui.ts --format cjs,esm --watch --dts",
     "lint": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run clean && npm run build",
@@ -56,10 +61,19 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "peerDependencies": {
+    "@opentui/core": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "axios": "^1.13.2"
   },
   "devDependencies": {
+    "@opentui/core": "^0.1.80",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
     "vitest": "^1.2.1"