D&D 5e API

/**
 * DD5eAPI - generated by OmniStream from D&D 5e API's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/dnd5eapi";

export class DD5eAPIError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `DD5eAPI error ${status}`);
    this.name = "DD5eAPIError";
    this.status = status;
    this.code = code;
  }
}

export interface DD5eAPIOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class DD5eAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: DD5eAPIOptions = {}) {
    if (!token) throw new Error("DD5eAPI: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new DD5eAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Get all resource URLs. */
  getapi(): Promise<any> {
    return this._request("GET", "/api", {});
  }

  /** Get an ability score by index. */
  getapiAbilityScoresIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/ability-scores/{index}", { params });
  }

  /** Get an alignment by index. */
  getapiAlignmentsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/alignments/{index}", { params });
  }

  /** Get a background by index. */
  getapiBackgroundsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/backgrounds/{index}", { params });
  }

  /** Get a class by index. */
  getapiClassesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}", { params });
  }

  /** Get features available for a class. */
  getapiClassesIndexFeatures(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/features", { params });
  }

  /** Get all level resources for a class. */
  getapiClassesIndexLevels(params: { "index": string; "subclass"?: string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/levels", { params });
  }

  /** Get level resource for a class and level. */
  getapiClassesIndexLevelsClassLevel(params: { "index": string; "class_level": number }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/levels/{class_level}", { params });
  }

  /** Get features available to a class at the requested level. */
  getapiClassesIndexLevelsClassLevelFeatures(params: { "index": string; "class_level": number }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/levels/{class_level}/features", { params });
  }

  /** Get spells of the requested level available to the class. */
  getapiClassesIndexLevelsSpellLevelSpells(params: { "index": string; "spell_level": number }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/levels/{spell_level}/spells", { params });
  }

  /** Get multiclassing resource for a class. */
  getapiClassesIndexMultiClassing(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/multi-classing", { params });
  }

  /** Get proficiencies available for a class. */
  getapiClassesIndexProficiencies(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/proficiencies", { params });
  }

  /** Get spellcasting info for a class. */
  getapiClassesIndexSpellcasting(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/spellcasting", { params });
  }

  /** Get spells available for a class. */
  getapiClassesIndexSpells(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/spells", { params });
  }

  /** Get subclasses available for a class. */
  getapiClassesIndexSubclasses(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/classes/{index}/subclasses", { params });
  }

  /** Get a condition by index. */
  getapiConditionsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/conditions/{index}", { params });
  }

  /** Get a damage type by index. */
  getapiDamageTypesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/damage-types/{index}", { params });
  }

  /** Get an equipment category by index. */
  getapiEquipmentCategoriesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/equipment-categories/{index}", { params });
  }

  /** Get an equipment item by index. */
  getapiEquipmentIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/equipment/{index}", { params });
  }

  /** Get a feat by index. */
  getapiFeatsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/feats/{index}", { params });
  }

  /** Get a feature by index. */
  getapiFeaturesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/features/{index}", { params });
  }

  /** Get a language by index. */
  getapiLanguagesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/languages/{index}", { params });
  }

  /** Get a magic item by index. */
  getapiMagicItemsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/magic-items/{index}", { params });
  }

  /** Get a magic school by index. */
  getapiMagicSchoolsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/magic-schools/{index}", { params });
  }

  /** Get list of monsters with optional filtering */
  getapiMonsters(params: { "challenge_rating"?: unknown[] }): Promise<any> {
    return this._request("GET", "/api/monsters", { params });
  }

  /** Get monster by index. */
  getapiMonstersIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/monsters/{index}", { params });
  }

  /** Get a proficiency by index. */
  getapiProficienciesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/proficiencies/{index}", { params });
  }

  /** Get a race by index. */
  getapiRacesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/races/{index}", { params });
  }

  /** Get proficiencies available for a race. */
  getapiRacesIndexProficiencies(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/races/{index}/proficiencies", { params });
  }

  /** Get subraces available for a race. */
  getapiRacesIndexSubraces(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/races/{index}/subraces", { params });
  }

  /** Get traits available for a race. */
  getapiRacesIndexTraits(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/races/{index}/traits", { params });
  }

  /** Get a rule section by index. */
  getapiRuleSectionsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/rule-sections/{index}", { params });
  }

  /** Get a rule by index. */
  getapiRulesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/rules/{index}", { params });
  }

  /** Get a skill by index. */
  getapiSkillsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/skills/{index}", { params });
  }

  /** Get list of spells with optional filtering. */
  getapiSpells(params: { "level"?: unknown[]; "school"?: unknown[] }): Promise<any> {
    return this._request("GET", "/api/spells", { params });
  }

  /** Get a spell by index. */
  getapiSpellsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/spells/{index}", { params });
  }

  /** Get a subclass by index. */
  getapiSubclassesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subclasses/{index}", { params });
  }

  /** Get features available for a subclass. */
  getapiSubclassesIndexFeatures(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subclasses/{index}/features", { params });
  }

  /** Get all level resources for a subclass. */
  getapiSubclassesIndexLevels(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subclasses/{index}/levels", { params });
  }

  /** Get level resources for a subclass and level. */
  getapiSubclassesIndexLevelsSubclassLevel(params: { "index": string; "subclass_level": number }): Promise<any> {
    return this._request("GET", "/api/subclasses/{index}/levels/{subclass_level}", { params });
  }

  /** Get features of the requested spell level available to the class. */
  getapiSubclassesIndexLevelsSubclassLevelFeatu(params: { "index": string; "subclass_level": number }): Promise<any> {
    return this._request("GET", "/api/subclasses/{index}/levels/{subclass_level}/features", { params });
  }

  /** Get a subrace by index. */
  getapiSubracesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subraces/{index}", { params });
  }

  /** Get proficiences available for a subrace. */
  getapiSubracesIndexProficiencies(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subraces/{index}/proficiencies", { params });
  }

  /** Get traits available for a subrace. */
  getapiSubracesIndexTraits(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/subraces/{index}/traits", { params });
  }

  /** Get a trait by index. */
  getapiTraitsIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/traits/{index}", { params });
  }

  /** Get a weapon property by index. */
  getapiWeaponPropertiesIndex(params: { "index": string }): Promise<any> {
    return this._request("GET", "/api/weapon-properties/{index}", { params });
  }

  /** Get list of all available resources for an endpoint. */
  getapiEndpoint(params: { "endpoint": string }): Promise<any> {
    return this._request("GET", "/api/{endpoint}", { params });
  }
}

export default DD5eAPI;