Botify API

/**
 * BotifyAPI - generated by OmniStream from Botify API's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/botify";

export class BotifyAPIError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `BotifyAPI error ${status}`);
    this.name = "BotifyAPIError";
    this.status = status;
    this.code = code;
  }
}

export interface BotifyAPIOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class BotifyAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: BotifyAPIOptions = {}) {
    if (!token) throw new Error("BotifyAPI: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new BotifyAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** List all analyses for a project */
  getProjectAnalyses(params: { "username": string; "project_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}", { params });
  }

  /** Get an Analysis detail */
  getAnalysisSummary(params: { "username": string; "project_slug": string; "analysis_slug": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}", { params });
  }

  /** Return global statistics for an analysis */
  getCrawlStatistics(params: { "username": string; "project_slug": string; "analysis_slug": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/crawl_statistics", { params });
  }

  /** Return crawl statistics grouped by time frequency (1 min, 5 mins or 60 min) */
  getCrawlStatisticsByFrequency(params: { "username": string; "project_slug": string; "analysis_slug": string; "frequency": string; "limit"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/crawl_statistics/time", { params });
  }

  /** Return a list of 1000 latest URLs crawled (all crawled URLs or only URLS with HTTP errors) */
  getCrawlStatisticsUrls(params: { "username": string; "project_slug": string; "analysis_slug": string; "list_type": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/crawl_statistics/urls/{list_type}", { params });
  }

  /** List of Orphan URLs */
  getGanalyticsOrphanURLs(params: { "username": string; "project_slug": string; "analysis_slug": string; "medium": string; "source": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/ganalytics/orphan_urls/{medium}/{source}", { params });
  }

  /** Get inlinks percentiles */
  getLinksPercentiles(params: { "username": string; "project_slug": string; "analysis_slug": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/links/percentiles", { params });
  }

  /** Lost pagerank */
  getPageRankLost(params: { "username": string; "project_slug": string; "analysis_slug": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/pagerank/lost", { params });
  }

  /** Get global information of the sitemaps found (sitemaps indexes, invalid sitemaps urls, etc */
  getSitemapsReport(params: { "username": string; "project_slug": string; "analysis_slug": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/sitemaps/report", { params });
  }

  /** Sample list of URLs which were found in your sitemaps but outside of the */
  getSitemapsSamplesOutOfConfig(params: { "username": string; "project_slug": string; "analysis_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/sitemaps/samples/out_of_config", { params });
  }

  /** Sample list of URLs which were found in your sitemaps, within the project */
  getSitemapsSamplesSitemapsOnly(params: { "username": string; "project_slug": string; "analysis_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/sitemaps/samples/sitemap_only", { params });
  }

  /** Top domains */
  getLinksTopDomains(params: { "username": string; "project_slug": string; "analysis_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/top_domains/domains", { params });
  }

  /** Top subddomains */
  getLinksTopSubdomains(params: { "username": string; "project_slug": string; "analysis_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/features/top_domains/subdomains", { params });
  }

  /** Executes a query and returns a paginated response */
  getUrls(params: { "username": string; "project_slug": string; "analysis_slug": string; "area"?: string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("POST", "/analyses/{username}/{project_slug}/{analysis_slug}/urls", { params });
  }

  /** Query aggregator */
  getUrlsAggs(params: { "username": string; "project_slug": string; "analysis_slug": string; "area"?: string }): Promise<any> {
    return this._request("POST", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/aggs", { params });
  }

  /** Gets an Analysis datamodel */
  getUrlsDatamodel(params: { "username": string; "project_slug": string; "analysis_slug": string; "area"?: string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/datamodel", { params });
  }

  /** A list of the CSV Exports requests and their current status */
  getUrlsExports(params: { "username": string; "project_slug": string; "analysis_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/export", { params });
  }

  /** Creates a new UrlExport object and starts a task that will export the results into a csv */
  createUrlsExport(params: { "username": string; "project_slug": string; "analysis_slug": string; "area"?: string }): Promise<any> {
    return this._request("POST", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/export", { params });
  }

  /** Checks the status of an CSVUrlExportJob object */
  getUrlsExportStatus(params: { "username": string; "project_slug": string; "analysis_slug": string; "url_export_id": string }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/export/{url_export_id}", { params });
  }

  /** Return most frequent segments (= suggested patterns in the previous version) */
  getUrlsSuggestedFilters(body: unknown, params: { "username": string; "project_slug": string; "analysis_slug": string; "area"?: string }): Promise<any> {
    return this._request("POST", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/suggested_filters", { body, params });
  }

  /** Gets the detail of an URL for an analysis */
  getUrlDetail(params: { "username": string; "project_slug": string; "analysis_slug": string; "url": string; "fields"?: unknown[] }): Promise<any> {
    return this._request("GET", "/analyses/{username}/{project_slug}/{analysis_slug}/urls/{url}", { params });
  }

  /** List all active projects for the user */
  getUserProjects(params: { "username": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/projects/{username}", { params });
  }

  /** Match and replace parts of a URL based on rules passed in POST data */
  testUrlRewritingRules(params: { "username": string; "project_slug": string }): Promise<any> {
    return this._request("POST", "/projects/{username}/{project_slug}/features/url_rewriting/rules_validator", { params });
  }

  /** List all the project's saved filters (each filter's name, ID and filter value) */
  getSavedFilters(params: { "username": string; "project_slug": string; "page"?: number; "size"?: number }): Promise<any> {
    return this._request("GET", "/projects/{username}/{project_slug}/filters", { params });
  }

  /** Retrieves a specific saved filter's name, ID and filter value */
  getSavedFilter(params: { "username": string; "project_slug": string; "identifier": string }): Promise<any> {
    return this._request("GET", "/projects/{username}/{project_slug}/filters/{identifier}", { params });
  }

  /** Project Query aggregator */
  getProjectUrlsAggs(params: { "username": string; "project_slug": string; "area"?: string; "last_analysis_slug"?: string; "nb_analyses"?: number }): Promise<any> {
    return this._request("POST", "/projects/{username}/{project_slug}/urls/aggs", { params });
  }
}

export default BotifyAPI;