@westmarches/api-client

Typed TypeScript client for the WestMarches.Games API.

Read characters, adventures, currencies, and distribute rewards to characters — all with full TypeScript autocompletion.

Install

npm install @westmarches/api-client

Quick Start

import { createWestMarchesClient } from '@westmarches/api-client';

const client = createWestMarchesClient({
  apiKey: 'wm_your_api_key_here',
});

// List all characters
const { data } = await client.listCharacters();
console.log(data?.data); // CharacterSummary[]

// Get a single character
const { data: character } = await client.getCharacter({
  path: { characterId: 'abc123' },
});
console.log(character?.data?.name);

Authentication

API keys are created in your community settings at Settings > API Keys. Requires Legendary tier (boost level 8+).

The client reads the API key from the options or falls back to the WESTMARCHES_API_KEY environment variable:

// Option 1: Pass explicitly
const client = createWestMarchesClient({ apiKey: 'wm_xxx' });

// Option 2: Set env variable and skip the option
// WESTMARCHES_API_KEY=wm_xxx
const client = createWestMarchesClient();

API Reference

Characters

client.listCharacters(opts?)

List all non-deleted characters in the community, ordered by level descending.

const { data } = await client.listCharacters({
  query: { page: 1, pageSize: 50 },
});

client.getCharacter(opts)

Get detailed information for a single character, including currencies and attributes.

const { data } = await client.getCharacter({
  path: { characterId: 'abc123' },
});

client.distributeReward(opts)

Award experience and/or currencies to a character. Requires write permission on the API key.

const { data } = await client.distributeReward({
  path: { characterId: 'abc123' },
  body: {
    experience: 100,
    currencies: { currency_id: 50 },
    reason: 'Quest completion bonus',
  },
});

if (data?.data?.levelUp) {
  console.log(`Level up! Now level ${data.data.newLevel}`);
}

Adventures

client.listAdventures(opts?)

List all published adventures, ordered by start time descending.

const { data } = await client.listAdventures({
  query: { page: 1, pageSize: 20 },
});

client.getAdventure(opts)

Get detailed information for a single adventure, including public notes.

const { data } = await client.getAdventure({
  path: { adventureId: 'xyz789' },
});

Currencies

client.listCurrencies(opts?)

List all currencies defined for the community. Use these IDs when distributing rewards.

const { data } = await client.listCurrencies();
const currencies = data?.data; // Currency[]

Types

All API types are exported for use in your code:

import type {
  CharacterSummary,
  CharacterDetail,
  AdventureSummary,
  AdventureDetail,
  Currency,
  RewardRequest,
  RewardResponse,
  Pagination,
} from '@westmarches/api-client';

Rate Limiting

Requests are limited to 100 per minute per API key. Rate limit info is available in the response headers.

License

MIT