@eve-online-tools/esi-provider

React provider for typed ESI clients via openapi-fetch and openapi-typescript.

Installation

pnpm add @eve-online-tools/esi-provider openapi-fetch openapi-typescript react react-dom

Generating ESI types

The package includes a CLI for maintaining generated ESI artifacts in your project.

update-compatibility-date

Fetches the latest compatibility date from ESI and updates compatibility-date.ts only. Does not download the spec or regenerate types.

npx @eve-online-tools/esi-provider update-compatibility-date -o ./src/esi/generated

download-spec

Fetches the OpenAPI spec (using the compatibility date in the output dir), and generates types:

npx @eve-online-tools/esi-provider download-spec -o ./src/esi/generated

Writes or updates:

• openapi.json — stripped spec (the provider sets CompatibilityDate/Tenant headers)
• esi-schema.d.ts — types generated via openapi-typescript
• types.d.ts — helper types for extracting response bodies from paths and operations
• compatibility-date.ts — created automatically if missing
• index.ts — created on first run only; includes a createESIProvider helper and re-exports schema/types helpers

download-spec --update-only

Updates compatibility-date.ts first, then downloads and regenerates the spec only if the compatibility date changed:

npx @eve-online-tools/esi-provider download-spec -o ./src/esi --update-only

Recommended usage (after download-spec)

import { createRateLimitMiddleware, useRateLimits } from "@eve-online-tools/esi-provider";
import { createESIProvider } from "./esi";

const rateLimit = createRateLimitMiddleware();

const [ESIProvider, useESIClient] = createESIProvider({
  appName: "my-app",
  appVersion: "1.0.0",
  appContact: "mailto:[email protected]",
  middleware: [rateLimit],
});

createESIProvider applies the generated baseUrl and compatibilityDate automatically. Pass any NewProviderProps field to override defaults (for example tenant or middleware).

Manual setup

If you manage the schema yourself, use newESIProvider<paths>(...) directly:

import type { paths } from "./esi-schema";
import { newESIProvider } from "@eve-online-tools/esi-provider";

const [ESIProvider, useESIClient] = newESIProvider<paths>({
  appName: "my-app",
  appVersion: "1.0.0",
  appContact: "mailto:[email protected]",
});

Usage

import { createRateLimitMiddleware, useRateLimits } from "@eve-online-tools/esi-provider";
import { createESIProvider } from "./esi";

const rateLimit = createRateLimitMiddleware();

const [ESIProvider, useESIClient] = createESIProvider({
  appName: "my-app",
  appVersion: "1.0.0",
  appContact: "mailto:[email protected]",
  middleware: [rateLimit],
});

function App() {
  return (
    <ESIProvider>
      <Dashboard />
    </ESIProvider>
  );
}

function Dashboard() {
  const client = useESIClient();
  const rateLimits = useRateLimits();

  // client.GET("/status/", ...) — typed against your OpenAPI schema
  // rateLimits?.groups — per-group token usage for UI
}

Calling ESI

The generated types contain a ResponseFor helper to type response bodies.

import { ESIError } from "./error";
import type { Client, ResponseFor } from "./generated"; // 
import { useESIClient } from "./provider";

type StatusResponse = ResponseFor<"/status/", "get", 200>;
type ErrorResponse = ResponseFor<"/status/", "get", "default">;

export const getServerStatus = async (client: Client) => {
  const response = await client.GET("/status/");

  switch (response.response.status) {
    case 200:
      return response.data as StatusResponse;
    default:
      throw new ESIError<ErrorResponse>(
        "Failed to get server status",
        response.error,
      );
  }
};

Middleware

Middleware plugs into the provider reducer and openapi-fetch. Each middleware has a unique key, initialState, reducer, and optional onRequest / onResponse / onError handlers.

createRateLimitMiddleware learns ESI rate-limit groups from response headers, tracks token usage per group and character, and proactively delays outbound requests when a bucket is low.

Development

pnpm --filter @eve-online-tools/esi-provider build
pnpm --filter @eve-online-tools/esi-provider test
pnpm --filter @eve-online-tools/esi-provider typecheck

License

MIT