User Agent Management

/**
 * Creates a base Algolia user agent
 * @param version - The version of the Algolia client
 * @returns AlgoliaAgent object with base user agent string and add method
 */
function createAlgoliaAgent(version: string): AlgoliaAgent;

import { createAlgoliaAgent } from "@algolia/client-common";

// Create base agent
const agent = createAlgoliaAgent("5.35.0");
console.log(agent.value); // "Algolia for JavaScript (5.35.0)"

// Add additional segments
agent.add({ segment: "MyClient", version: "1.0.0" });
console.log(agent.value); // "Algolia for JavaScript (5.35.0); MyClient (1.0.0)"

// Add segment without version
agent.add({ segment: "Integration" });
console.log(agent.value); // "Algolia for JavaScript (5.35.0); MyClient (1.0.0); Integration"

/**
 * Creates a configured Algolia user agent with client information
 * @param options - Configuration with client info and additional agents
 * @returns Configured AlgoliaAgent with all segments added
 */
function getAlgoliaAgent(options: GetAlgoliaAgent): AlgoliaAgent;

interface GetAlgoliaAgent {
  /** Additional agent segments to include */
  algoliaAgents: AlgoliaAgentOptions[];
  /** Client name */
  client: string;
  /** Client version */
  version: string;
}

import { getAlgoliaAgent } from "@algolia/client-common";

const agent = getAlgoliaAgent({
  client: "SearchClient",
  version: "1.2.0",
  algoliaAgents: [
    { segment: "React", version: "18.0.0" },
    { segment: "NextJS", version: "13.0.0" }
  ]
});

console.log(agent.value);
// "Algolia for JavaScript (1.2.0); SearchClient (1.2.0); React (18.0.0); NextJS (13.0.0)"

interface AlgoliaAgent {
  /** The current user agent string value */
  value: string;
  /** Add an additional segment to the user agent */
  add: (options: AlgoliaAgentOptions) => AlgoliaAgent;
}

interface AlgoliaAgentOptions {
  /** The segment name (usually integration or library name) */
  segment: string;
  /** Optional version for the segment */
  version?: string;
}

/**
 * Adds a segment to the user agent string
 * @param options - Segment configuration with name and optional version
 * @returns The same AlgoliaAgent instance for chaining
 */
add(options: AlgoliaAgentOptions): AlgoliaAgent;

import { createAlgoliaAgent } from "@algolia/client-common";

const agent = createAlgoliaAgent("5.35.0")
  .add({ segment: "Framework", version: "2.1.0" })
  .add({ segment: "Plugin", version: "1.0.0" })
  .add({ segment: "CustomIntegration" });

// Duplicate segments are ignored
agent.add({ segment: "Framework", version: "2.1.0" }); // Won't add duplicate

console.log(agent.value);
// "Algolia for JavaScript (5.35.0); Framework (2.1.0); Plugin (1.0.0); CustomIntegration"

import { createAlgoliaAgent, createTransporter } from "@algolia/client-common";

const algoliaAgent = createAlgoliaAgent("5.35.0")
  .add({ segment: "MyClient", version: "1.0.0" });

const transporter = createTransporter({
  // ... other options
  algoliaAgent,
});

// The user agent will be automatically added to requests as 'x-algolia-agent' query parameter

import { getAlgoliaAgent } from "@algolia/client-common";

class CustomSearchClient {
  private agent: AlgoliaAgent;

  constructor(version: string) {
    this.agent = getAlgoliaAgent({
      client: "CustomSearchClient",
      version,
      algoliaAgents: [
        { segment: "React", version: "18.0.0" },
        { segment: "TypeScript" }
      ]
    });
  }

  addIntegration(name: string, version?: string) {
    this.agent.add({ segment: name, version });
  }

  getUserAgent(): string {
    return this.agent.value;
  }
}