@westmarches/api-client

Typed TypeScript client for the WestMarches.Games API.

Read characters, adventures, wiki articles, and inventory — distribute rewards, manage items, and update character data — 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 keys are scoped to a single community — every request automatically operates on the community the key belongs to.

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 },
});
// data?.data — CharacterSummary[]
// data?.total — total count

client.getCharacter(opts)

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

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

const character = data?.data;
console.log(character?.name);
console.log(character?.inventoryItems); // InventoryItem[] — items with remainingQty > 0

client.distributeReward(opts)

Award experience, currencies, and/or items to a character. Items are always recorded in the reward log. Requires write permission.

// XP + gold
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}`);
}

// Grant items only (no XP required)
await client.distributeReward({
  path: { characterId: 'abc123' },
  body: {
    items: [
      {
        name: 'Potion of Healing',
        quantity: 2,
        isConsumable: true,
        sellValue: { gold_currency_id: 50 },
      },
    ],
    reason: 'Loot from the dragon hoard',
  },
});

client.distributeBulkRewards(opts)

Award experience, currencies, and/or items to multiple characters in one request. Requires write permission.

await client.distributeBulkRewards({
  body: {
    rewards: [
      { characterId: 'abc123', experience: 200 },
      { characterId: 'def456', experience: 200, currencies: { gold_id: 100 } },
    ],
    adventureId: 'adv789', // optional — links rewards to an adventure
  },
});

client.updateCharacterStatus(opts)

Set a character's status to ACTIVE, RETIRED, or DECEASED. Requires write permission.

await client.updateCharacterStatus({
  path: { characterId: 'abc123' },
  body: {
    status: 'DECEASED',
    reason: 'Fell in the Battle of Ironhold',
  },
});

client.approveCharacter(opts)

Approve a pending character, allowing them to receive rewards. Idempotent. Requires write permission.

await client.approveCharacter({
  path: { characterId: 'abc123' },
});

Inventory

All inventory mutations require write permission. Items can only be created via the rewards endpoint so they are always audit-logged.

client.updateInventoryItem(opts)

Update an item's metadata. Setting quantity resets remainingQty to the new value.

const { data } = await client.updateInventoryItem({
  path: { characterId: 'abc123', itemId: 'item456' },
  body: {
    notes: 'Found in the ruins of Thornwall',
    isConsumable: true,
    sellValue: { gold_id: 25 },
  },
});

client.consumeInventoryItem(opts)

Consume a quantity of a consumable item, decrementing remainingQty. Returns 400 if the item is not consumable or quantity would exceed what's available.

const { data } = await client.consumeInventoryItem({
  path: { characterId: 'abc123', itemId: 'item456' },
  body: { quantity: 1 },
});
console.log(data?.data?.remainingQty); // decremented

client.sellInventoryItem(opts)

Sell a quantity of an item. Credits the item's sellValue currencies to the character, decrements remainingQty, and creates a reward log entry.

const { data } = await client.sellInventoryItem({
  path: { characterId: 'abc123', itemId: 'item456' },
  body: { quantity: 1 },
});
console.log(data?.data?.currenciesAwarded); // Record<currencyId, amount>

client.transferInventoryItem(opts)

Transfer a quantity of an item to another character in the same community. Creates two reward log entries (ITEM_TRANSFER_OUT / ITEM_TRANSFER_IN).

const { data } = await client.transferInventoryItem({
  path: { characterId: 'abc123', itemId: 'item456' },
  body: {
    toCharacterId: 'def456',
    quantity: 1,
  },
});
console.log(data?.data?.updatedItem);    // source item (decremented)
console.log(data?.data?.transferredItem); // new item on target character

Data Tables

client.updateDataTableRows(opts)

Replace all rows for a character in a data table. The server performs a diff and creates, updates, or soft-deletes rows as needed. Column IDs are available on the character's dataTables field. Requires write permission.

await client.updateDataTableRows({
  path: { characterId: 'abc123', dataTableId: 'tbl789' },
  body: {
    rows: [
      {
        rowIndex: 0,
        values: {
          'col-uuid-1': 'Dagger',
          'col-uuid-2': 5,
          'col-uuid-3': null,
        },
      },
    ],
  },
});

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' },
});

Wiki Articles

client.listArticles(opts?)

List all published, public wiki articles. Excludes drafts, GM-only pages, and archived pages.

// Search by title
const { data } = await client.listArticles({
  query: { search: 'Riverrun', pageSize: 10 },
});

// Filter by category
const { data: npcs } = await client.listArticles({
  query: { category: 'NPC' },
});

Available categories: NPC, LOCATION, FACTION, DEITY, LORE, EVENT, ARTIFACT, CREATURE, RULES, ADVENTURE_REPORT.

client.getArticle(opts)

Get a single wiki article including its full content body. The content field is a ProseMirror/TipTap JSON document — extract text from the text fields in leaf nodes, or pass the whole object to an LLM.

const { data } = await client.getArticle({
  path: { articleId: 'art123' },
});

const article = data?.data;
console.log(article?.title);
console.log(article?.url);    // direct link to the article page
console.log(article?.content); // ProseMirror JSON

Discord bot pattern: user asks about "Riverrun" → search articles → fetch full content → summarise with an LLM → respond with the article link.

const results = await client.listArticles({ query: { search: 'Riverrun' } });
const hit = results.data?.data?.[0];
if (hit) {
  const { data: detail } = await client.getArticle({ path: { articleId: hit.id } });
  // pass detail.data.content to your LLM, reply with detail.data.url
}

Currencies

client.listCurrencies(opts?)

List all currencies defined for the community. Use these IDs when distributing rewards or reading sell values.

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,
  InventoryItem,
  RewardItem,
  AdventureSummary,
  AdventureDetail,
  ArticleSummary,
  ArticleDetail,
  Currency,
  RewardRequest,
  RewardResponse,
  BulkRewardEntry,
  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