[Release] @strata-eve/esi - ESI TypeScript SDK

EVE Technology and Research Center Third Party Developers
1

Hello fellow capsuleers!

I want to share a new open-source project I recently published for the Eve Developer community: @strata-eve/esi.

It is a fully typed, object-oriented TypeScript SDK for ESI. You can interact with ESI using clean and chainable methods.

One of the biggest pains in EVE development is handling authentication. To solve this, the library includes a complete SsoManager and a TokenProvider system. The SsoManager handles generating login URLs (supports PKCE flows out of the box) and validating JWTs. Once your user is authenticated, you can write a simple TokenProvider class to teach the SDK how to fetch tokens from your own database. Once you plug the provider into the client, you never have to worry about manually attaching authorization headers again; the SDK simply asks your provider for the token exactly when it needs it.

import { SsoManager, TokenProvider } from "@strata-eve/esi";

const sso = new SsoManager({
  clientId: "YOUR_CLIENT_ID",
  redirectURI: "http://localhost/callback"
});

// Generate a URL using the PKCE flow
const { url, codeVerifier } = sso.getAuthorizationUrl(['esi-mail.read_mail.v1']);

// (Save the codeVerifier in your session and redirect the user to the url)

// Later, when the user returns, exchange their code for tokens
const tokenData = await sso.exchangeCodeForToken('CODE_FROM_URL', { codeVerifier });

class MyDatabaseTokenProvider implements TokenProvider {
  async getAccessToken(characterId: number): Promise<string> {
    const user = await myDatabase.getUser(characterId);

    // You can also use the sso instance here to refresh the token if it has expired

    return user.accessToken;
  }
}

Once your token provier is ready, you can pass it to the main client. Here is a look at how your application code becomes when fetching public data or acting as an authenticated character.

import { EsiClient } from "@strata-eve/esi";

const esi = new EsiClient({
  agent: {
    appName: "YourApp",
    contact: "youremail@example.com"
  },
  tokenProvider: new MyDatabaseTokenProvider(), // Plug the provider in here!
});

async function run() {
  // Fetch public data
  const jita = await esi.universe.system(30000142).fetch();
  console.log(`System name: ${jita.name}`);

  // Act as a specific character for authenticated data
  // The SDK will automatically call your TokenProvider to get the auth headers
  const me = esi.as(123456789);
  const myWallet = await me.wallet.fetch();
  console.log(`My balance: ${myWallet} ISK`);

  // Fetch your corporation. If you run this twice, the second
  // call is instant served from memory cache (respecting ESI ETags)
  const myCorp = await me.corporation();
  if (!myCorp) return;

  const corpInfo = await myCorp.fetch();
  console.log(`Corp ticker: ${corpInfo.ticker}`);
}

The project is completely open-source. Whether you want to use it for your next project, report a bug, or contribute, you can find the links below:

Fly safe,
Yoko Ruoska