@elqnt/api-client

Shared API client infrastructure for the Eloquent platform. Provides consistent HTTP communication with automatic token management, error handling, and TypeScript support.

Installation

npm install @elqnt/api-client

Entry Points

Browser Usage

Basic Request

import { browserApiRequest } from "@elqnt/api-client/browser";

const response = await browserApiRequest<Agent[]>("/api/v1/agents", {
  baseUrl: "https://api.example.com",
  orgId: "org_123",
});

if (response.data) {
  console.log(response.data);
}

With Options

const response = await browserApiRequest("/api/v1/agents", {
  method: "POST",
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
  body: {
    name: "My Agent",
    goal: "Help users",
  },
  headers: {
    "X-Custom-Header": "value",
  },
});

Clear Token Cache

import { clearGatewayTokenCache } from "@elqnt/api-client/browser";

// Call on logout or token refresh
clearGatewayTokenCache();

Server Usage (SSR)

Create Server Client

import { createServerClient } from "@elqnt/api-client/server";

const client = createServerClient({
  gatewayUrl: process.env.API_GATEWAY_URL!,
  jwtSecret: process.env.JWT_SECRET!,
});

Make Requests

// GET request
const agents = await client.get<Agent[]>("/api/v1/agents", {
  orgId: "org_123",
  userId: "user_456",
});

// POST request
const newAgent = await client.post<Agent>("/api/v1/agents", {
  orgId: "org_123",
  userId: "user_456",
  body: { name: "My Agent" },
});

In Next.js Server Actions

// app/actions/agents.ts
"use server";

import { createServerClient } from "@elqnt/api-client/server";
import { getServerSession } from "@/lib/auth";

export async function getAgents() {
  const session = await getServerSession();
  const client = createServerClient({
    gatewayUrl: process.env.API_GATEWAY_URL!,
    jwtSecret: process.env.JWT_SECRET!,
  });

  return client.get("/api/v1/agents", {
    orgId: session.orgId,
    userId: session.userId,
  });
}

Types

ApiClientOptions

interface ApiClientOptions {
  baseUrl: string;
  orgId: string;
  userId?: string;
  headers?: Record<string, string>;
}

ApiResponse

interface ApiResponse<T> {
  data?: T;
  error?: ApiError;
  metadata?: ResponseMetadata;
}

interface ApiError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

Error Handling

const response = await browserApiRequest("/api/v1/agents", options);

if (response.error) {
  switch (response.error.code) {
    case "UNAUTHORIZED":
      // Redirect to login
      break;
    case "NOT_FOUND":
      // Show 404
      break;
    default:
      // Show error message
      console.error(response.error.message);
  }
}

Best Practices

1. Always use the appropriate client - browser for client-side, server for SSR
2. Handle errors - Check response.error before using response.data
3. Clear cache on logout - Call clearGatewayTokenCache() when user logs out
4. Use TypeScript generics - browserApiRequest<MyType>(...) for type safety

See Also

• API Gateway - Backend routing
• Frontend Apps - React patterns