@gravity-ai/api 1.1.4 → 1.1.5

package/dist/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,13 +30,320 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports2, module2) {
+    module2.exports = {
+      name: "@gravity-ai/api",
+      version: "1.1.5",
+      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"
+        },
+        "./opentui": {
+          types: "./dist/opentui.d.ts",
+          require: "./dist/opentui.js",
+          import: "./dist/opentui.mjs"
+        }
+      },
+      scripts: {
+        build: "tsup index.ts opentui.ts --format cjs,esm --dts",
+        clean: "rm -rf dist",
+        dev: "tsup index.ts opentui.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"
+      },
+      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"
+      }
+    };
+  }
+});
+
 // index.ts
 var index_exports = {};
 __export(index_exports, {
-  Client: () => Client
+  Client: () => Client,
+  Gravity: () => Gravity,
+  extractClientIp: () => extractClientIp,
+  gravityAds: () => gravityAds,
+  gravityContext: () => gravityContext,
+  toGravityMessages: () => toGravityMessages
 });
 module.exports = __toCommonJS(index_exports);
 
+// ads.ts
+var DEFAULT_GRAVITY_API = "https://server.trygravity.ai/api/v1/ad";
+var DEFAULT_TIMEOUT_MS = 3e3;
+function toGravityMessages(messages, maxTurns = 2) {
+  if (!messages || messages.length === 0) return [];
+  return messages.slice(-maxTurns).map((m) => ({
+    role: m.role,
+    content: m.content
+  }));
+}
+function extractClientIp(req) {
+  if (!req) return void 0;
+  const headers = req.headers || {};
+  const forwarded = headers["x-forwarded-for"] || headers["x-real-ip"];
+  if (forwarded) {
+    const first = (typeof forwarded === "string" ? forwarded : forwarded[0])?.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  if (req.socket?.remoteAddress) return req.socket.remoteAddress;
+  if (req.connection?.remoteAddress) return req.connection.remoteAddress;
+  if (req.ip) return req.ip;
+  return void 0;
+}
+async function gravityAds(req, messages, placements, opts = {}) {
+  const apiKey = opts.apiKey || (typeof process !== "undefined" ? process.env?.GRAVITY_API_KEY : void 0);
+  const gravityApi = opts.gravityApi || DEFAULT_GRAVITY_API;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!apiKey) {
+    return { ads: [], status: 0, elapsed: "0", requestBody: null };
+  }
+  const ctx = req?.body?.gravity_context;
+  const clientUser = ctx?.user || {};
+  const clientDevice = ctx?.device || {};
+  const clientIp = extractClientIp(req);
+  const body = {
+    messages: toGravityMessages(messages),
+    sessionId: ctx?.sessionId,
+    placements,
+    user: {
+      ...clientUser,
+      id: clientUser.id || clientUser.userId || "anonymous"
+    },
+    device: {
+      ...clientDevice,
+      ...clientIp ? { ip: clientIp } : {}
+    }
+  };
+  body.relevancy = opts.relevancy ?? 0.2;
+  body.testAd = opts.production === true ? false : true;
+  if (opts.excludedTopics) body.excludedTopics = opts.excludedTopics;
+  const start = performance.now();
+  try {
+    const res = await fetch(gravityApi, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const elapsed = (performance.now() - start).toFixed(0);
+    if (res.status === 204) {
+      return { ads: [], status: 204, elapsed, requestBody: body };
+    }
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      return {
+        ads: [],
+        status: res.status,
+        elapsed,
+        error: errText,
+        requestBody: body
+      };
+    }
+    const data = await res.json();
+    const ads = Array.isArray(data) ? data : [data];
+    return { ads, status: res.status, elapsed, requestBody: body };
+  } catch (err) {
+    const elapsed = (performance.now() - start).toFixed(0);
+    const error = err instanceof Error ? err.name === "TimeoutError" ? `Timeout (${timeoutMs}ms)` : err.message : String(err);
+    return { ads: [], status: 0, elapsed, error, requestBody: body };
+  }
+}
+
+// gravity.ts
+var Gravity = class {
+  /**
+   * @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 = {}) {
+    this.opts = opts;
+  }
+  /**
+   * 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
+   */
+  async getAds(req, messages, placements, overrides = {}) {
+    return gravityAds(req, messages, placements, {
+      ...this.opts,
+      ...overrides
+    });
+  }
+};
+
+// context.ts
+function gravityContext(overrides) {
+  if (!overrides?.sessionId) {
+    throw new Error("gravityContext() requires sessionId");
+  }
+  if (!overrides?.user?.userId) {
+    throw new Error("gravityContext() requires user.userId");
+  }
+  const isBrowser = typeof window !== "undefined" && typeof navigator !== "undefined";
+  const device = isBrowser ? browserDevice() : nodeDevice();
+  if (overrides.device) {
+    Object.assign(device, overrides.device);
+  }
+  const { userId, ...restUser } = overrides.user;
+  return {
+    sessionId: overrides.sessionId,
+    user: { ...restUser, id: userId },
+    device
+  };
+}
+function browserDevice() {
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  const win = typeof window !== "undefined" ? window : void 0;
+  return {
+    ua: nav?.userAgent || "",
+    browser: "web",
+    device_type: /Mobi|Android/i.test(nav?.userAgent || "") ? "mobile" : "desktop",
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    language: nav?.language || "en",
+    screen_width: win?.screen?.width,
+    screen_height: win?.screen?.height,
+    viewport_width: win?.innerWidth,
+    viewport_height: win?.innerHeight,
+    platform: nav?.platform || "web"
+  };
+}
+function nodeDevice() {
+  let os;
+  try {
+    os = require("os");
+  } catch {
+  }
+  const runtimeTag = (() => {
+    if (typeof globalThis !== "undefined") {
+      const g = globalThis;
+      if (g.Bun && typeof g.Bun === "object" && "version" in g.Bun) {
+        return `Bun/${g.Bun.version}`;
+      }
+      if (g.Deno && typeof g.Deno === "object") {
+        const deno = g.Deno;
+        const ver = deno.version;
+        return `Deno/${ver?.deno || "unknown"}`;
+      }
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return `Node/${process.versions.node}`;
+    }
+    return "unknown";
+  })();
+  const cols = typeof process !== "undefined" ? process.stdout?.columns || 80 : 80;
+  const rows = typeof process !== "undefined" ? process.stdout?.rows || 24 : 24;
+  const env = typeof process !== "undefined" ? process.env : {};
+  return {
+    ua: `gravity-js/${PKG_VERSION} (${os?.type() || "unknown"} ${os?.arch() || "unknown"}; ${runtimeTag})`,
+    os: os ? `${os.type()} ${os.release()}` : void 0,
+    browser: "cli",
+    device_type: env.CI ? "server" : "desktop",
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    language: env.LANG?.split(".")[0]?.replace("_", "-") || "en",
+    platform: typeof process !== "undefined" ? process.platform : void 0,
+    arch: os?.arch(),
+    screen_width: cols,
+    screen_height: rows,
+    viewport_width: cols,
+    viewport_height: rows,
+    runtime: runtimeTag,
+    term_program: env.TERM_PROGRAM || void 0,
+    term: env.TERM || void 0,
+    colorterm: env.COLORTERM || void 0,
+    is_ci: !!env.CI
+  };
+}
+var PKG_VERSION = (() => {
+  try {
+    return require_package().version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
 // client.ts
 var import_axios = __toESM(require("axios"));
 var DEFAULT_ENDPOINT = "https://server.trygravity.ai";
@@ -186,5 +496,10 @@ var Client = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Client
+  Client,
+  Gravity,
+  extractClientIp,
+  gravityAds,
+  gravityContext,
+  toGravityMessages
 });

package/dist/index.mjs

@@ -1,3 +1,310 @@
+import {
+  __commonJS,
+  __require
+} from "./chunk-EBO3CZXG.mjs";
+
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports, module) {
+    module.exports = {
+      name: "@gravity-ai/api",
+      version: "1.1.5",
+      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"
+        },
+        "./opentui": {
+          types: "./dist/opentui.d.ts",
+          require: "./dist/opentui.js",
+          import: "./dist/opentui.mjs"
+        }
+      },
+      scripts: {
+        build: "tsup index.ts opentui.ts --format cjs,esm --dts",
+        clean: "rm -rf dist",
+        dev: "tsup index.ts opentui.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"
+      },
+      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"
+      }
+    };
+  }
+});
+
+// ads.ts
+var DEFAULT_GRAVITY_API = "https://server.trygravity.ai/api/v1/ad";
+var DEFAULT_TIMEOUT_MS = 3e3;
+function toGravityMessages(messages, maxTurns = 2) {
+  if (!messages || messages.length === 0) return [];
+  return messages.slice(-maxTurns).map((m) => ({
+    role: m.role,
+    content: m.content
+  }));
+}
+function extractClientIp(req) {
+  if (!req) return void 0;
+  const headers = req.headers || {};
+  const forwarded = headers["x-forwarded-for"] || headers["x-real-ip"];
+  if (forwarded) {
+    const first = (typeof forwarded === "string" ? forwarded : forwarded[0])?.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  if (req.socket?.remoteAddress) return req.socket.remoteAddress;
+  if (req.connection?.remoteAddress) return req.connection.remoteAddress;
+  if (req.ip) return req.ip;
+  return void 0;
+}
+async function gravityAds(req, messages, placements, opts = {}) {
+  const apiKey = opts.apiKey || (typeof process !== "undefined" ? process.env?.GRAVITY_API_KEY : void 0);
+  const gravityApi = opts.gravityApi || DEFAULT_GRAVITY_API;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!apiKey) {
+    return { ads: [], status: 0, elapsed: "0", requestBody: null };
+  }
+  const ctx = req?.body?.gravity_context;
+  const clientUser = ctx?.user || {};
+  const clientDevice = ctx?.device || {};
+  const clientIp = extractClientIp(req);
+  const body = {
+    messages: toGravityMessages(messages),
+    sessionId: ctx?.sessionId,
+    placements,
+    user: {
+      ...clientUser,
+      id: clientUser.id || clientUser.userId || "anonymous"
+    },
+    device: {
+      ...clientDevice,
+      ...clientIp ? { ip: clientIp } : {}
+    }
+  };
+  body.relevancy = opts.relevancy ?? 0.2;
+  body.testAd = opts.production === true ? false : true;
+  if (opts.excludedTopics) body.excludedTopics = opts.excludedTopics;
+  const start = performance.now();
+  try {
+    const res = await fetch(gravityApi, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const elapsed = (performance.now() - start).toFixed(0);
+    if (res.status === 204) {
+      return { ads: [], status: 204, elapsed, requestBody: body };
+    }
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      return {
+        ads: [],
+        status: res.status,
+        elapsed,
+        error: errText,
+        requestBody: body
+      };
+    }
+    const data = await res.json();
+    const ads = Array.isArray(data) ? data : [data];
+    return { ads, status: res.status, elapsed, requestBody: body };
+  } catch (err) {
+    const elapsed = (performance.now() - start).toFixed(0);
+    const error = err instanceof Error ? err.name === "TimeoutError" ? `Timeout (${timeoutMs}ms)` : err.message : String(err);
+    return { ads: [], status: 0, elapsed, error, requestBody: body };
+  }
+}
+
+// gravity.ts
+var Gravity = class {
+  /**
+   * @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 = {}) {
+    this.opts = opts;
+  }
+  /**
+   * 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
+   */
+  async getAds(req, messages, placements, overrides = {}) {
+    return gravityAds(req, messages, placements, {
+      ...this.opts,
+      ...overrides
+    });
+  }
+};
+
+// context.ts
+function gravityContext(overrides) {
+  if (!overrides?.sessionId) {
+    throw new Error("gravityContext() requires sessionId");
+  }
+  if (!overrides?.user?.userId) {
+    throw new Error("gravityContext() requires user.userId");
+  }
+  const isBrowser = typeof window !== "undefined" && typeof navigator !== "undefined";
+  const device = isBrowser ? browserDevice() : nodeDevice();
+  if (overrides.device) {
+    Object.assign(device, overrides.device);
+  }
+  const { userId, ...restUser } = overrides.user;
+  return {
+    sessionId: overrides.sessionId,
+    user: { ...restUser, id: userId },
+    device
+  };
+}
+function browserDevice() {
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  const win = typeof window !== "undefined" ? window : void 0;
+  return {
+    ua: nav?.userAgent || "",
+    browser: "web",
+    device_type: /Mobi|Android/i.test(nav?.userAgent || "") ? "mobile" : "desktop",
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    language: nav?.language || "en",
+    screen_width: win?.screen?.width,
+    screen_height: win?.screen?.height,
+    viewport_width: win?.innerWidth,
+    viewport_height: win?.innerHeight,
+    platform: nav?.platform || "web"
+  };
+}
+function nodeDevice() {
+  let os;
+  try {
+    os = __require("os");
+  } catch {
+  }
+  const runtimeTag = (() => {
+    if (typeof globalThis !== "undefined") {
+      const g = globalThis;
+      if (g.Bun && typeof g.Bun === "object" && "version" in g.Bun) {
+        return `Bun/${g.Bun.version}`;
+      }
+      if (g.Deno && typeof g.Deno === "object") {
+        const deno = g.Deno;
+        const ver = deno.version;
+        return `Deno/${ver?.deno || "unknown"}`;
+      }
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return `Node/${process.versions.node}`;
+    }
+    return "unknown";
+  })();
+  const cols = typeof process !== "undefined" ? process.stdout?.columns || 80 : 80;
+  const rows = typeof process !== "undefined" ? process.stdout?.rows || 24 : 24;
+  const env = typeof process !== "undefined" ? process.env : {};
+  return {
+    ua: `gravity-js/${PKG_VERSION} (${os?.type() || "unknown"} ${os?.arch() || "unknown"}; ${runtimeTag})`,
+    os: os ? `${os.type()} ${os.release()}` : void 0,
+    browser: "cli",
+    device_type: env.CI ? "server" : "desktop",
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    language: env.LANG?.split(".")[0]?.replace("_", "-") || "en",
+    platform: typeof process !== "undefined" ? process.platform : void 0,
+    arch: os?.arch(),
+    screen_width: cols,
+    screen_height: rows,
+    viewport_width: cols,
+    viewport_height: rows,
+    runtime: runtimeTag,
+    term_program: env.TERM_PROGRAM || void 0,
+    term: env.TERM || void 0,
+    colorterm: env.COLORTERM || void 0,
+    is_ci: !!env.CI
+  };
+}
+var PKG_VERSION = (() => {
+  try {
+    return require_package().version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
 // client.ts
 import axios from "axios";
 var DEFAULT_ENDPOINT = "https://server.trygravity.ai";
@@ -149,5 +456,10 @@ var Client = class {
   }
 };
 export {
-  Client
+  Client,
+  Gravity,
+  extractClientIp,
+  gravityAds,
+  gravityContext,
+  toGravityMessages
 };