bhooai-nexus 0.1.2

package/packages/nexus-admin/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+// Ambient declarations that keep `@bhooai/admin` self-contained: it does
+// not depend on the consumer having `vite/client` types installed. Vite /
+// esbuild inject `import.meta.env` and resolve asset imports at runtime; the
+// host project's build (vite build) handles actual bundling.
+interface ImportMetaEnv {
+  readonly VITE_SUPERVISOR_URL?: string;
+  readonly [key: string]: string | undefined;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+declare module '*.svg' {
+  const src: string;
+  export default src;
+}
+declare module '*.png' {
+  const src: string;
+  export default src;
+}

package/packages/nexus-ads/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-ads",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-ads/src/GaqlBuilder.ts

@@ -0,0 +1,72 @@
+/**
+ * GAQL (Google Ads Query Language) builder. Produces queries like:
+ *   SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED' ORDER BY campaign.id LIMIT 50
+ */
+export class GaqlBuilder {
+  private fields: string[] = [];
+  private resource: string = '';
+  private conditions: string[] = [];
+  private order?: { field: string; dir: 'ASC' | 'DESC' };
+  private limitN?: number;
+
+  select(...fields: string[]): this {
+    this.fields.push(...fields);
+    return this;
+  }
+  from(resource: string): this {
+    this.resource = resource;
+    return this;
+  }
+  /** Add a condition, e.g. `where("campaign.status = 'ENABLED'")`. */
+  where(condition: string): this {
+    this.conditions.push(condition);
+    return this;
+  }
+  orderBy(field: string, dir: 'ASC' | 'DESC' = 'ASC'): this {
+    this.order = { field, dir };
+    return this;
+  }
+  limit(n: number): this {
+    this.limitN = n;
+    return this;
+  }
+
+  build(): string {
+    if (!this.resource) throw new Error('[nexus-ads] GaqlBuilder: FROM resource required');
+    if (this.fields.length === 0) throw new Error('[nexus-ads] GaqlBuilder: at least one field required');
+    let q = `SELECT ${this.fields.join(', ')} FROM ${this.resource}`;
+    if (this.conditions.length) q += ` WHERE ${this.conditions.join(' AND ')}`;
+    if (this.order) q += ` ORDER BY ${this.order.field} ${this.order.dir}`;
+    if (this.limitN != null) q += ` LIMIT ${this.limitN}`;
+    return q;
+  }
+}
+
+/** Convenience: standard campaign listing query. */
+export function campaignsQuery(limit = 50): string {
+  return new GaqlBuilder()
+    .select('campaign.id', 'campaign.name', 'campaign.status', 'campaign.advertising_channel_type')
+    .from('campaign')
+    .orderBy('campaign.id')
+    .limit(limit)
+    .build();
+}
+
+/** Convenience: campaign performance metrics for a date range (YYYY-MM-DD). */
+export function campaignMetricsQuery(fromDate: string, toDate: string, limit = 50): string {
+  return new GaqlBuilder()
+    .select(
+      'campaign.id',
+      'campaign.name',
+      'metrics.impressions',
+      'metrics.clicks',
+      'metrics.cost_micros',
+      'metrics.conversions',
+    )
+    .from('campaign')
+    .where(`segments.date >= '${fromDate}'`)
+    .where(`segments.date <= '${toDate}'`)
+    .orderBy('campaign.id')
+    .limit(limit)
+    .build();
+}

package/packages/nexus-ads/src/GoogleAdsClient.ts

@@ -0,0 +1,121 @@
+import type { GoogleAdsConfig, HttpTransport, AdsRow, Campaign } from './types.js';
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+/**
+ * Google Ads REST client (no grpc/native deps). Uses the Google Ads API REST
+ * endpoint `googleAds:search` with GAQL. OAuth2 access tokens are acquired via
+ * the refresh-token grant and cached until near expiry. The HTTP transport is
+ * injectable so tests run without live credentials.
+ */
+export class GoogleAdsClient {
+  private readonly cfg: GoogleAdsConfig;
+  private readonly transport: HttpTransport;
+  private readonly apiVersion: string;
+  private token: { value: string; expiresAt: number } | null = null;
+
+  constructor(cfg: GoogleAdsConfig, transport: HttpTransport, apiVersion = 'v17') {
+    this.cfg = cfg;
+    this.transport = transport;
+    this.apiVersion = apiVersion;
+    if (!cfg.developerToken || !cfg.clientId || !cfg.clientSecret || !cfg.refreshToken) {
+      throw new Error('[nexus-ads] developerToken, clientId, clientSecret, refreshToken all required');
+    }
+  }
+
+  private baseUrl(): string {
+    return `https://googleads.googleapis.com/${this.apiVersion}`;
+  }
+
+  /** OAuth2 refresh-token → access token, cached with a 60s safety margin. */
+  private async accessToken(): Promise<string> {
+    if (this.token && Date.now() < this.token.expiresAt - 60_000) return this.token.value;
+    const body = new URLSearchParams({
+      client_id: this.cfg.clientId,
+      client_secret: this.cfg.clientSecret,
+      refresh_token: this.cfg.refreshToken,
+      grant_type: 'refresh_token',
+    }).toString();
+    const res = await this.transport({
+      method: 'POST',
+      url: TOKEN_URL,
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+    const parsed = safeJson(res.body);
+    if (res.status !== 200 || !parsed?.access_token) {
+      throw new Error(`[nexus-ads] token refresh failed: HTTP ${res.status} ${res.body}`);
+    }
+    this.token = { value: parsed.access_token, expiresAt: Date.now() + (parsed.expires_in ?? 3600) * 1000 };
+    return this.token.value;
+  }
+
+  private async searchHeaders(): Promise<Record<string, string>> {
+    return {
+      authorization: `Bearer ${await this.accessToken()}`,
+      'developer-token': this.cfg.developerToken,
+      'content-type': 'application/json',
+      ...(this.cfg.loginCustomerId ? { 'login-customer-id': normalizeId(this.cfg.loginCustomerId) } : {}),
+    };
+  }
+
+  /** Run a GAQL query against a customer and return all rows (handles pagination). */
+  async search(customerId: string, query: string): Promise<AdsRow[]> {
+    const headers = await this.searchHeaders();
+    let pageToken: string | undefined;
+    const rows: AdsRow[] = [];
+    do {
+      const body = JSON.stringify({ query, ...(pageToken ? { pageToken } : {}) });
+      const res = await this.transport({
+        method: 'POST',
+        url: `${this.baseUrl()}/customers/${normalizeId(customerId)}/googleAds:search`,
+        headers,
+        body,
+      });
+      const parsed = safeJson(res.body);
+      if (res.status !== 200) {
+        throw new Error(`[nexus-ads] search failed: HTTP ${res.status} ${res.body}`);
+      }
+      if (Array.isArray(parsed?.results)) rows.push(...parsed.results);
+      pageToken = parsed?.nextPageToken;
+    } while (pageToken);
+    return rows;
+  }
+
+  /** List campaigns on the default customer. */
+  async listCampaigns(customerId = this.cfg.customerId, limit = 50): Promise<Campaign[]> {
+    const rows = await this.search(customerId, listCampaignsGaql(limit));
+    return rows.map(rowToCampaign);
+  }
+
+  /** Campaign metrics for a date range (YYYY-MM-DD). */
+  async campaignMetrics(fromDate: string, toDate: string, customerId = this.cfg.customerId, limit = 50): Promise<AdsRow[]> {
+    const rows = await this.search(customerId, metricsGaql(fromDate, toDate, limit));
+    return rows;
+  }
+}
+
+function listCampaignsGaql(limit: number): string {
+  return `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type FROM campaign ORDER BY campaign.id LIMIT ${limit}`;
+}
+function metricsGaql(from: string, to: string, limit: number): string {
+  return `SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date >= '${from}' AND segments.date <= '${to}' ORDER BY campaign.id LIMIT ${limit}`;
+}
+
+function rowToCampaign(row: AdsRow): Campaign {
+  const c = (row.campaign ?? {}) as Record<string, unknown>;
+  return {
+    id: String(c.id ?? ''),
+    name: String(c.name ?? ''),
+    status: String(c.status ?? ''),
+    advertisingChannelType: c.advertisingChannelType != null ? String(c.advertisingChannelType) : undefined,
+  };
+}
+
+function normalizeId(id: string): string {
+  return id.replace(/-/g, '');
+}
+
+function safeJson(body: string): any {
+  try { return JSON.parse(body); } catch { return undefined; }
+}

package/packages/nexus-ads/src/fetchTransport.ts

@@ -0,0 +1,10 @@
+import type { HttpTransport, HttpRequest, HttpResponse } from './types.js';
+
+/** Default HTTP transport built on the global `fetch` (Node >= 18). */
+export const fetchTransport: HttpTransport = async (req: HttpRequest): Promise<HttpResponse> => {
+  const res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+  const body = await res.text();
+  const headers: Record<string, string> = {};
+  res.headers.forEach((v, k) => { headers[k] = v; });
+  return { status: res.status, body, headers };
+};

package/packages/nexus-ads/src/index.ts

@@ -0,0 +1,20 @@
+export * from './types.js';
+export * from './GaqlBuilder.js';
+export * from './GoogleAdsClient.js';
+
+import { GoogleAdsClient } from './GoogleAdsClient.js';
+import { fetchTransport } from './fetchTransport.js';
+import type { GoogleAdsConfig, HttpTransport } from './types.js';
+
+/** Default fetch-based transport (Node >= 18). */
+export { fetchTransport };
+
+export interface CreateAdsOptions {
+  transport?: HttpTransport;
+  apiVersion?: string;
+}
+
+/** Build a Google Ads client. Throws at construction if required creds are missing. */
+export function createGoogleAds(config: GoogleAdsConfig, opts: CreateAdsOptions = {}): GoogleAdsClient {
+  return new GoogleAdsClient(config, opts.transport ?? fetchTransport, opts.apiVersion);
+}

package/packages/nexus-ads/src/types.ts

@@ -0,0 +1,41 @@
+/** Injectable HTTP transport so the client is testable without live Google creds. */
+export interface HttpRequest {
+  method: 'GET' | 'POST';
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+export interface HttpResponse {
+  status: number;
+  body: string;
+  headers?: Record<string, string>;
+}
+export type HttpTransport = (req: HttpRequest) => Promise<HttpResponse>;
+
+/** Google Ads config as it appears in nexus.config.ts `ads`. */
+export interface GoogleAdsConfig {
+  enabled: boolean;
+  /** Google Ads API developer token. */
+  developerToken: string;
+  /** OAuth2 client credentials. */
+  clientId: string;
+  clientSecret: string;
+  /** OAuth2 refresh token (long-lived). */
+  refreshToken: string;
+  /** Login customer ID (MCC account, hyphenated or plain). Required for MCC. */
+  loginCustomerId?: string;
+  /** Default customer ID to query. */
+  customerId: string;
+}
+
+/** Minimal campaign shape from `campaign` resource. */
+export interface Campaign {
+  id: string;
+  name: string;
+  status: string;
+  advertisingChannelType?: string;
+  budget?: { amountMicros?: string };
+}
+
+/** A row from a GAQL search: a record mapping resource name → fields. */
+export type AdsRow = Record<string, unknown>;

package/packages/nexus-ai-client/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@bhooai/nexus-ai-client",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-ai-client/src/client.ts

@@ -0,0 +1,159 @@
+import type {
+  AiClientOptions,
+  ChatCompletionRequest,
+  ChatCompletionResponse,
+  ChatCompletionChunk,
+  EmbeddingRequest,
+  EmbeddingResponse,
+  ModelsResponse,
+  ImageGenRequest,
+  ImageGenResponse,
+  ImageGenModelsResponse,
+  AgentImageRequest,
+  AgentImageEvent,
+} from './types.js';
+import { AiError, isRetryable } from './errors.js';
+import { parseSseStream } from './sse.js';
+
+/**
+ * Node client for the BhooAI Nexus AI server (Python FastAPI). OpenAI-compatible.
+ * Supports non-streaming + streaming chat completions, embeddings, and model
+ * listing, with timeout (AbortController) and exponential-backoff retries on
+ * transient failures (network errors, 5xx, 429).
+ */
+export class AiClient {
+  private readonly serverUrl: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly retryDelayMs: number;
+  private readonly authToken?: string;
+
+  constructor(opts: AiClientOptions) {
+    this.serverUrl = opts.serverUrl.replace(/\/+$/, '');
+    this.timeoutMs = opts.timeoutMs ?? 60_000;
+    this.maxRetries = opts.maxRetries ?? 2;
+    this.retryDelayMs = opts.retryDelayMs ?? 500;
+    this.authToken = opts.authToken;
+  }
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json', ...extra };
+    if (this.authToken) h.authorization = `Bearer ${this.authToken}`;
+    return h;
+  }
+
+  private async request<T>(path: string, init: RequestInit, { stream = false } = {}): Promise<T> {
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const res = await fetch(`${this.serverUrl}${path}`, {
+          ...init,
+          signal: controller.signal,
+          headers: this.headers(init.headers as Record<string, string> | undefined),
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+          let message = `AI server ${res.status}`;
+          let code: string | undefined;
+          try {
+            const body = await res.json() as { error?: { message?: string; code?: string } };
+            message = body?.error?.message ?? message;
+            code = body?.error?.code;
+          } catch { /* non-JSON error body */ }
+          const err = new AiError(message, { status: res.status, code });
+          if (isRetryable(err) && attempt < this.maxRetries) {
+            lastErr = err;
+            await this.backoff(attempt);
+            continue;
+          }
+          throw err;
+        }
+        return (stream ? res : await res.json() as T) as T;
+      } catch (e) {
+        clearTimeout(timer);
+        // Abort → timeout; network errors are retryable.
+        const isAbort = e instanceof Error && e.name === 'AbortError';
+        const err = e instanceof AiError ? e : new AiError(isAbort ? 'AI request timed out' : String((e as Error)?.message ?? e));
+        if (isRetryable(err) && attempt < this.maxRetries) {
+          lastErr = err;
+          await this.backoff(attempt);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new AiError('AI request failed');
+  }
+
+  private async backoff(attempt: number): Promise<void> {
+    const delay = this.retryDelayMs * Math.pow(2, attempt);
+    // Tiny jitter without Math.random (deterministic): fold attempt into the delay.
+    await new Promise((r) => setTimeout(r, delay + attempt));
+  }
+
+  /** Non-streaming chat completion. */
+  async chat(req: ChatCompletionRequest): Promise<ChatCompletionResponse> {
+    const body = { ...req, stream: false };
+    return this.request<ChatCompletionResponse>('/chat/completions', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+  }
+
+  /** Streaming chat completion — yields chunks until the stream ends. */
+  async *chatStream(req: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown> {
+    const body = { ...req, stream: true };
+    const res = await this.request<Response>('/chat/completions', {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { accept: 'text/event-stream' },
+    }, { stream: true });
+    if (!res.body) throw new AiError('streaming response has no body');
+    for await (const chunk of parseSseStream(res.body as unknown as ReadableStream<Uint8Array>)) {
+      yield chunk as ChatCompletionChunk;
+    }
+  }
+
+  /** Create embeddings for one or more inputs. */
+  async embeddings(req: EmbeddingRequest): Promise<EmbeddingResponse> {
+    return this.request<EmbeddingResponse>('/embeddings', {
+      method: 'POST',
+      body: JSON.stringify(req),
+    });
+  }
+
+  /** List available models (optionally for a specific provider). */
+  async listModels(provider?: string): Promise<ModelsResponse> {
+    const qs = provider ? `?provider=${encodeURIComponent(provider)}` : '';
+    return this.request<ModelsResponse>(`/models${qs}`, { method: 'GET' });
+  }
+
+  /** Generate images via the local Stable Diffusion HTTP server. */
+  async images(req: ImageGenRequest): Promise<ImageGenResponse> {
+    return this.request<ImageGenResponse>('/images/generations', {
+      method: 'POST',
+      body: JSON.stringify(req),
+    });
+  }
+
+  /** List available image-generation models (SD checkpoints). */
+  async listImageModels(): Promise<ImageGenModelsResponse> {
+    return this.request<ImageGenModelsResponse>('/images/models', { method: 'GET' });
+  }
+
+  /** Agentic image loop — streams reasoning/tool/image/done events.
+   *  Drives the Ollama LLM (reasoning) + local SD server (pixels). */
+  async *agentImageStream(req: AgentImageRequest): AsyncGenerator<AgentImageEvent, void, unknown> {
+    const res = await this.request<Response>('/agent/image', {
+      method: 'POST',
+      body: JSON.stringify(req),
+      headers: { accept: 'text/event-stream' },
+    }, { stream: true });
+    if (!res.body) throw new AiError('agent stream response has no body');
+    for await (const chunk of parseSseStream(res.body as unknown as ReadableStream<Uint8Array>)) {
+      yield chunk as AgentImageEvent;
+    }
+  }
+}

package/packages/nexus-ai-client/src/errors.ts

@@ -0,0 +1,21 @@
+/** AI client errors. */
+
+export class AiError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+  constructor(message: string, opts: { status?: number; code?: string } = {}) {
+    super(message);
+    this.name = 'AiError';
+    this.status = opts.status;
+    this.code = opts.code;
+  }
+}
+
+/** True for transient errors worth retrying: network failures + 5xx + 429. */
+export function isRetryable(err: unknown): boolean {
+  if (err instanceof AiError) {
+    if (err.status === undefined) return true; // network-level failure
+    return err.status >= 500 || err.status === 429;
+  }
+  return true;
+}

package/packages/nexus-ai-client/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './errors.js';
+export { AiClient } from './client.js';
+export { parseSseStream } from './sse.js';

package/packages/nexus-ai-client/src/sse.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal SSE parser for the streaming chat endpoint. Reads a web
+ * ReadableStream<Uint8Array>, buffers bytes, splits events on blank lines, and
+ * yields the parsed `data:` JSON payload of each event. Stops at `[DONE]`.
+ */
+export async function* parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<any, void, unknown> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      // SSE events are separated by a blank line (\n\n). Process complete ones.
+      let idx: number;
+      while ((idx = buffer.indexOf('\n\n')) !== -1) {
+        const rawEvent = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        const payload = extractData(rawEvent);
+        if (payload === undefined) continue;
+        if (payload === '[DONE]') return;
+        try {
+          yield JSON.parse(payload);
+        } catch {
+          /* skip malformed */
+        }
+      }
+    }
+    // Flush any trailing event without a blank-line terminator.
+    if (buffer.trim()) {
+      const payload = extractData(buffer);
+      if (payload && payload !== '[DONE]') {
+        try { yield JSON.parse(payload); } catch { /* skip */ }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function extractData(event: string): string | undefined {
+  // An event may have multiple lines; collect `data:` fields (concatenated).
+  const parts: string[] = [];
+  for (const line of event.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('data:')) {
+      parts.push(trimmed.slice(5).trimStart());
+    }
+  }
+  if (parts.length === 0) return undefined;
+  return parts.join('\n');
+}