@gravity-ai/api 0.0.1

package/README.md

@@ -0,0 +1,70 @@
+# @gravity-ai/api
+
+The official Node.js/TypeScript SDK for the Gravity API.
+
+## Installation
+
+```bash
+npm install @gravity-ai/api
+```
+
+## Usage
+
+First, import and initialize the client with your API key.
+
+```typescript
+import { Client } from '@gravity-ai/api';
+
+const client = new Client('YOUR_API_KEY');
+```
+
+### Fetching an Ad
+
+To request an ad, you need to pass the conversation context (messages). You can also provide optional user or device information to improve targeting.
+
+```typescript
+const ad = await client.getAd({
+  messages: [
+    { role: 'user', content: 'I need help finding a new laptop.' },
+    { role: 'assistant', content: 'What is your budget?' }
+  ],
+  // User context
+  user: {
+    gender: 'male',
+    age: '25-34'
+  },
+  // Device info
+  device: { 
+    ip: '1.2.3.4', 
+    country: 'US', 
+    ua: 'UA' 
+  },
+  // Optional additional context
+  interests: ["coding", "apple", "software development"],
+  summary: "User is building software on his windows laptop but wants an apple laptop"
+});
+
+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)
+} else {
+  console.log('No ad available for this context.');
+}
+```
+
+### Advanced Configuration
+
+You can override the default API endpoint or provide global excluded topics during initialization.
+
+```typescript
+const client = new Client('YOUR_API_KEY', {
+  endpoint: 'https://custom.gravity.server',
+  excludedTopics: ['politics', 'religion']
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+type Role = 'user' | 'assistant';
+type Gender = 'male' | 'female' | 'other';
+interface MessageObject {
+    role: Role;
+    content: string;
+}
+interface DeviceObject {
+    ip: string;
+    country: string;
+    ua: string;
+    os?: string;
+    ifa?: string;
+}
+interface UserObject {
+    uid?: string;
+    gender?: Gender;
+    age?: string;
+    keywords?: string;
+}
+interface AdParams {
+    apiKey?: string;
+    messages: MessageObject[];
+    device?: DeviceObject;
+    user?: UserObject;
+    excludedTopics?: string[];
+    [key: string]: any;
+}
+interface AdResponse {
+    adText: string;
+    impUrl?: string;
+    clickUrl?: string;
+    payout?: number;
+}
+/**
+ * API error response structure
+ */
+interface ApiErrorResponse {
+    error: string;
+    message?: string;
+    statusCode?: number;
+}
+
+interface ClientParams {
+    endpoint?: string;
+    excludedTopics?: string[];
+}
+/**
+ * Client for the Gravity API
+ */
+declare class Client {
+    private apiKey;
+    private endpoint?;
+    private excludedTopics?;
+    private axios;
+    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>
+     */
+    getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Handle API errors with logging
+     * @param error - The error object
+     * @param method - The method name where error occurred
+     */
+    private handleError;
+}
+
+export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+type Role = 'user' | 'assistant';
+type Gender = 'male' | 'female' | 'other';
+interface MessageObject {
+    role: Role;
+    content: string;
+}
+interface DeviceObject {
+    ip: string;
+    country: string;
+    ua: string;
+    os?: string;
+    ifa?: string;
+}
+interface UserObject {
+    uid?: string;
+    gender?: Gender;
+    age?: string;
+    keywords?: string;
+}
+interface AdParams {
+    apiKey?: string;
+    messages: MessageObject[];
+    device?: DeviceObject;
+    user?: UserObject;
+    excludedTopics?: string[];
+    [key: string]: any;
+}
+interface AdResponse {
+    adText: string;
+    impUrl?: string;
+    clickUrl?: string;
+    payout?: number;
+}
+/**
+ * API error response structure
+ */
+interface ApiErrorResponse {
+    error: string;
+    message?: string;
+    statusCode?: number;
+}
+
+interface ClientParams {
+    endpoint?: string;
+    excludedTopics?: string[];
+}
+/**
+ * Client for the Gravity API
+ */
+declare class Client {
+    private apiKey;
+    private endpoint?;
+    private excludedTopics?;
+    private axios;
+    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>
+     */
+    getAd(params: AdParams): Promise<AdResponse | null>;
+    /**
+     * Handle API errors with logging
+     * @param error - The error object
+     * @param method - The method name where error occurred
+     */
+    private handleError;
+}
+
+export { type AdParams, type AdResponse, type ApiErrorResponse, Client, type ClientParams };

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  Client: () => Client
+});
+module.exports = __toCommonJS(index_exports);
+
+// client.ts
+var import_axios = __toESM(require("axios"));
+var Client = class {
+  constructor(apiKey, params = {}) {
+    this.apiKey = apiKey;
+    this.endpoint = params.endpoint || "https://server.trygravity.ai";
+    this.excludedTopics = params.excludedTopics || [];
+    this.axios = import_axios.default.create({
+      baseURL: this.endpoint,
+      timeout: 1e4,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+  }
+  /**
+   * Request a text advertisement. Returns null if there is no relevant ad found.
+   * @param params - AdParams matching the server schema
+   * @returns Promise<BidResponse | null>
+   */
+  async getAd(params) {
+    try {
+      const body = {
+        ...params,
+        // prefer explicit apiKey in params, else default to client's apiKey
+        apiKey: params.apiKey ?? this.apiKey,
+        // supply top-level excludedTopics if not provided
+        excludedTopics: params.excludedTopics ?? this.excludedTopics
+      };
+      const response = await this.axios.post("/ad", body);
+      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
+        };
+      }
+    } 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
+   */
+  handleError(error, method) {
+    if (import_axios.default.isAxiosError(error)) {
+      const axiosError = error;
+      if (axiosError.response) {
+        console.error(`[GravityClient.${method}] API Error:`, {
+          status: axiosError.response.status,
+          statusText: axiosError.response.statusText,
+          data: axiosError.response.data
+        });
+      } else if (axiosError.request) {
+        console.error(`[GravityClient.${method}] Network Error:`, {
+          message: "No response received from server",
+          code: axiosError.code
+        });
+      } else {
+        console.error(`[GravityClient.${method}] Request Error:`, axiosError.message);
+      }
+    } else {
+      console.error(`[GravityClient.${method}] Unexpected Error:`, error);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Client
+});

package/dist/index.mjs

@@ -0,0 +1,77 @@
+// client.ts
+import axios from "axios";
+var Client = class {
+  constructor(apiKey, params = {}) {
+    this.apiKey = apiKey;
+    this.endpoint = params.endpoint || "https://server.trygravity.ai";
+    this.excludedTopics = params.excludedTopics || [];
+    this.axios = axios.create({
+      baseURL: this.endpoint,
+      timeout: 1e4,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+  }
+  /**
+   * Request a text advertisement. Returns null if there is no relevant ad found.
+   * @param params - AdParams matching the server schema
+   * @returns Promise<BidResponse | null>
+   */
+  async getAd(params) {
+    try {
+      const body = {
+        ...params,
+        // prefer explicit apiKey in params, else default to client's apiKey
+        apiKey: params.apiKey ?? this.apiKey,
+        // supply top-level excludedTopics if not provided
+        excludedTopics: params.excludedTopics ?? this.excludedTopics
+      };
+      const response = await this.axios.post("/ad", body);
+      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
+        };
+      }
+    } 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
+   */
+  handleError(error, method) {
+    if (axios.isAxiosError(error)) {
+      const axiosError = error;
+      if (axiosError.response) {
+        console.error(`[GravityClient.${method}] API Error:`, {
+          status: axiosError.response.status,
+          statusText: axiosError.response.statusText,
+          data: axiosError.response.data
+        });
+      } else if (axiosError.request) {
+        console.error(`[GravityClient.${method}] Network Error:`, {
+          message: "No response received from server",
+          code: axiosError.code
+        });
+      } else {
+        console.error(`[GravityClient.${method}] Request Error:`, axiosError.message);
+      }
+    } else {
+      console.error(`[GravityClient.${method}] Unexpected Error:`, error);
+    }
+  }
+};
+export {
+  Client
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@gravity-ai/api",
+  "version": "0.0.1",
+  "description": "Gravity JS SDK for retrieving targeted advertisements",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup index.ts --format cjs,esm --dts",
+    "clean": "rm -rf dist",
+    "dev": "tsup index.ts --format cjs,esm --watch --dts",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run clean && npm run build",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "publish:patch": "npm run version:patch && npm publish",
+    "publish:minor": "npm run version:minor && npm publish",
+    "publish:major": "npm run version:major && npm publish"
+  },
+  "keywords": [
+    "gravity",
+    "advertising",
+    "api",
+    "client",
+    "ads",
+    "typescript",
+    "contextual-advertising",
+    "ai-ads"
+  ],
+  "author": "Gravity Team",
+  "license": "MIT",
+  "homepage": "https://github.com/Try-Gravity/gravity-js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Try-Gravity/gravity-js.git",
+    "directory": "packages/api"
+  },
+  "bugs": {
+    "url": "https://github.com/Try-Gravity/gravity-js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  }
+}