SDK and Client Helpers

src/integrations/uppzy/
  client.ts
  errors.ts
  types.ts
  factory.ts
  testing.ts

export type UppzyChatResponse = {
  session_id: string;
  request_id: string;
  answer: string;
  confidence_level?: string;
  confidence_score?: number;
};

export type UppzyAsyncResponse = {
  session_id: string;
  request_id: string;
  status: string;
};

export type UppzyAsyncStatusResponse = {
  session_id: string;
  request_id: string;
  status: string;
  answer?: string;
  error?: string;
};

import { UppzyApiError, isRetryableStatus } from "./errors";

type RequestOptions = {
  method?: string;
  body?: unknown;
  timeoutMs?: number;
  maxRetries?: number;
};

export class UppzyClient {
  constructor(
    private readonly baseUrl: string,
    private readonly apiKey: string,
    private readonly siteId: string,
  ) {}

  private async request<T>(path: string, {
    method = "GET",
    body,
    timeoutMs = 15000,
    maxRetries = 2,
  }: RequestOptions = {}): Promise<T> {
    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
      const controller = new AbortController();
      const timeout = setTimeout(() => controller.abort(), timeoutMs);

      try {
        const response = await fetch(`${this.baseUrl}${path}`, {
          method,
          signal: controller.signal,
          headers: {
            "X-API-Key": this.apiKey,
            "Content-Type": "application/json",
          },
          body: body ? JSON.stringify(body) : undefined,
        });

        const text = await response.text();
        const data = text ? JSON.parse(text) : null;

        if (response.ok) {
          return data as T;
        }

        const retryable = isRetryableStatus(response.status);
        if (!retryable || attempt === maxRetries) {
          throw new UppzyApiError(`Uppzy API returned HTTP ${response.status}`, {
            status: response.status,
            endpoint: path,
            details: data,
            retryable,
          });
        }

        await this.sleep(this.backoff(attempt));
      } catch (error: any) {
        if (error instanceof UppzyApiError) {
          throw error;
        }

        const isAbort = error?.name === "AbortError";
        if (!isAbort || attempt === maxRetries) {
          throw new UppzyApiError(isAbort ? "Uppzy API request timed out" : "Uppzy API request failed", {
            status: null,
            endpoint: path,
            details: null,
            retryable: isAbort,
          });
        }

        await this.sleep(this.backoff(attempt));
      } finally {
        clearTimeout(timeout);
      }
    }

    throw new Error("Unexpected Uppzy client state");
  }

  private backoff(attempt: number): number {
    const jitter = Math.floor(Math.random() * 250);
    return Math.min(4000, 300 * 2 ** attempt) + jitter;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }

  sendSyncChat(payload: {
    session_id: string;
    message: string;
    email?: string;
    ui_locale?: string;
    response_language?: string;
  }) {
    return this.request<UppzyChatResponse>(`/m2m/sites/${this.siteId}/chat`, {
      method: "POST",
      body: payload,
    });
  }

  sendAsyncChat(payload: {
    session_id: string;
    message: string;
    response_language?: string;
  }) {
    return this.request<UppzyAsyncResponse>(`/m2m/sites/${this.siteId}/chat/async`, {
      method: "POST",
      body: payload,
    });
  }

  getAsyncChatStatus(requestId: string) {
    return this.request<UppzyAsyncStatusResponse>(`/m2m/sites/${this.siteId}/chat/requests/${requestId}`);
  }

  createTextDocument(payload: {
    title: string;
    content: string;
    category?: string;
  }) {
    return this.request(`/m2m/sites/${this.siteId}/documents/text`, {
      method: "POST",
      body: payload,
    });
  }

  createQaDocument(payload: {
    title: string;
    question: string;
    answer: string;
    category?: string;
  }) {
    return this.request(`/m2m/sites/${this.siteId}/documents/qa`, {
      method: "POST",
      body: payload,
    });
  }

  submitFeedback(payload: {
    session_id: string;
    request_id: string;
    feedback: "good" | "bad";
  }) {
    return this.request(`/m2m/sites/${this.siteId}/chat/feedback`, {
      method: "POST",
      body: payload,
    });
  }

  closeSession(sessionId: string) {
    return this.request(`/m2m/sites/${this.siteId}/chat/session/close`, {
      method: "POST",
      body: { session_id: sessionId },
    });
  }

  getStatistics() {
    return this.request(`/m2m/sites/${this.siteId}/statistics`);
  }

  getSessions() {
    return this.request(`/m2m/sites/${this.siteId}/sessions`);
  }
}

import { UppzyClient } from "./client";

export function createUppzyClient() {
  const baseUrl = process.env.UPPZY_BASE_URL || "https://api.uppzy.com/api/v1";
  const apiKey = process.env.UPPZY_API_KEY;
  const siteId = process.env.UPPZY_SITE_ID;

  if (!apiKey || !siteId) {
    throw new Error("Missing Uppzy configuration");
  }

  return new UppzyClient(baseUrl, apiKey, siteId);
}

import { createUppzyClient } from "./integrations/uppzy/factory";

export async function postAssistantQuestion(req, res) {
  const uppzy = createUppzyClient();
  const { visitorId, message } = req.body;

  const result = await uppzy.sendSyncChat({
    session_id: `visitor_${visitorId}`,
    message,
    response_language: "en",
  });

  return res.json({
    request_id: result.request_id,
    answer: result.answer,
    confidence_level: result.confidence_level,
  });
}

import os
import time
import random
import requests


class UppzyApiError(RuntimeError):
    def __init__(self, message, status=None, endpoint=None, details=None, retryable=False):
        super().__init__(message)
        self.status = status
        self.endpoint = endpoint
        self.details = details
        self.retryable = retryable


def is_retryable_status(status):
    return status == 429 or (status is not None and 500 <= status <= 599)


class UppzyClient:
    def __init__(self, base_url: str, api_key: str, site_id: str):
        self.base_url = base_url.rstrip("/")
        self.site_id = site_id
        self.session = requests.Session()
        self.session.headers.update({"X-API-Key": api_key})

    def _backoff(self, attempt: int) -> float:
        return min(4.0, 0.3 * (2 ** attempt)) + random.random() * 0.25

    def _request(self, path: str, method: str = "GET", json_body=None, timeout: int = 15, max_retries: int = 2):
        for attempt in range(max_retries + 1):
            try:
                response = self.session.request(
                    method,
                    f"{self.base_url}{path}",
                    json=json_body,
                    timeout=timeout,
                )

                data = response.json() if response.text else None

                if response.ok:
                    return data

                retryable = is_retryable_status(response.status_code)
                if not retryable or attempt == max_retries:
                    raise UppzyApiError(
                        f"Uppzy API returned HTTP {response.status_code}",
                        status=response.status_code,
                        endpoint=path,
                        details=data,
                        retryable=retryable,
                    )

                time.sleep(self._backoff(attempt))
            except requests.Timeout:
                if attempt == max_retries:
                    raise UppzyApiError(
                        "Uppzy API request timed out",
                        status=None,
                        endpoint=path,
                        details=None,
                        retryable=True,
                    )
                time.sleep(self._backoff(attempt))

    def send_sync_chat(self, payload: dict):
        return self._request(f"/m2m/sites/{self.site_id}/chat", method="POST", json_body=payload)

    def get_statistics(self):
        return self._request(f"/m2m/sites/{self.site_id}/statistics")

type Transport = (url: string, init: RequestInit) => Promise<Response>;

export class TestableUppzyClient {
  constructor(
    private readonly baseUrl: string,
    private readonly apiKey: string,
    private readonly siteId: string,
    private readonly transport: Transport = fetch,
  ) {}

  async getStatistics() {
    const response = await this.transport(
      `${this.baseUrl}/m2m/sites/${this.siteId}/statistics`,
      {
        method: "GET",
        headers: { "X-API-Key": this.apiKey },
      },
    );

    return response.json();
  }
}