@thalorlabs/pokeapi 1.0.0

package/.prettierrc

@@ -0,0 +1 @@
+"@thalorlabs/eslint-plugin-dev-config/prettier"

package/CLAUDE.md

@@ -0,0 +1,36 @@
+# CLAUDE.md — @thalorlabs/pokeapi
+
+## What this is
+
+Provider adapter for pokeapi.co (PokeAPI). Returns `TLPokemon`.
+
+## External API
+
+- pokeapi.co — free, no auth, no billing, no rate limits
+- Multi-call provider: /pokemon/{id} + /pokemon-species/{id}
+- 1025 Pokemon in the National Dex
+
+## Build & publish
+
+```bash
+npm run build      # tsc → dist/
+npm test           # vitest
+npm version patch  # or minor/major
+npm publish --access public
+```
+
+## What this package does
+
+- HTTP adapter extending BaseHttpClient
+- Two API calls per getPokemon() — pokemon data + species data
+- Normalises combined response to TLPokemon
+- Maps type names to EPokemonType enum (skips unknown types)
+- Parses generation from roman numeral format
+- Cleans flavor text (removes newlines/form feeds)
+- Sets: isSafe=true
+
+## What this package does NOT do
+
+- No database, no caching, no logging — orchestrator handles that
+- Raw types never exported
+- No provider selection logic

package/dist/PokeApiClient.d.ts

@@ -0,0 +1,20 @@
+import { BaseHttpClient } from '@thalorlabs/api';
+import { TLPokemon } from '@thalorlabs/types';
+export interface PokeApiClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+/**
+ * HTTP adapter for pokeapi.co.
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Multi-call provider: fetches pokemon data + species data,
+ * then normalises the combined response to TLPokemon.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+export declare class PokeApiClient extends BaseHttpClient {
+    readonly serviceName = "pokeapi";
+    constructor(config?: PokeApiClientConfig);
+    getPokemon(): Promise<TLPokemon>;
+    private normalise;
+}

package/dist/PokeApiClient.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PokeApiClient = void 0;
+const crypto_1 = require("crypto");
+const api_1 = require("@thalorlabs/api");
+const types_1 = require("@thalorlabs/types");
+const ROMAN_NUMERAL_MAP = {
+    i: 1,
+    ii: 2,
+    iii: 3,
+    iv: 4,
+    v: 5,
+    vi: 6,
+    vii: 7,
+    viii: 8,
+    ix: 9,
+};
+/**
+ * HTTP adapter for pokeapi.co.
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Multi-call provider: fetches pokemon data + species data,
+ * then normalises the combined response to TLPokemon.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+class PokeApiClient extends api_1.BaseHttpClient {
+    constructor(config = {}) {
+        super({
+            baseURL: config.baseURL ?? 'https://pokeapi.co/api/v2',
+            serviceName: 'pokeapi',
+            retries: 3,
+            timeout: config.timeout ?? 10000,
+        });
+        this.serviceName = 'pokeapi';
+    }
+    async getPokemon() {
+        const pokemonId = Math.floor(Math.random() * 1025) + 1;
+        const { response: pokemonResponse } = await this.handleRequest({ method: 'GET', url: `/pokemon/${pokemonId}` }, { method: 'GET', url: `/pokemon/${pokemonId}`, requestId: (0, crypto_1.randomUUID)() });
+        const { response: speciesResponse } = await this.handleRequest({ method: 'GET', url: `/pokemon-species/${pokemonId}` }, {
+            method: 'GET',
+            url: `/pokemon-species/${pokemonId}`,
+            requestId: (0, crypto_1.randomUUID)(),
+        });
+        return this.normalise(pokemonResponse.data, speciesResponse.data);
+    }
+    normalise(pokemon, species) {
+        const name = pokemon.name.charAt(0).toUpperCase() + pokemon.name.slice(1);
+        const types = pokemon.types
+            .map((t) => t.type.name.toUpperCase())
+            .filter((t) => Object.values(types_1.EPokemonType).includes(t));
+        const englishEntry = species.flavor_text_entries.find((e) => e.language.name === 'en');
+        const description = englishEntry
+            ? englishEntry.flavor_text.replace(/[\n\f\r]/g, ' ')
+            : '';
+        const generationRoman = species.generation.name.split('-')[1];
+        const generation = ROMAN_NUMERAL_MAP[generationRoman] ?? 0;
+        const imageUrl = pokemon.sprites.other['official-artwork'].front_default;
+        return types_1.TLPokemon.parse({
+            id: (0, crypto_1.createHash)('md5').update(pokemon.name).digest('hex'),
+            name,
+            types,
+            description,
+            imageUrl,
+            generation,
+            isSafe: true,
+        });
+    }
+}
+exports.PokeApiClient = PokeApiClient;

package/dist/PokeApiTypes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Raw response types from pokeapi.co API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface PokeApiPokemonRaw {
+    id: number;
+    name: string;
+    types: Array<{
+        slot: number;
+        type: {
+            name: string;
+            url: string;
+        };
+    }>;
+    sprites: {
+        front_default: string;
+        other: {
+            'official-artwork': {
+                front_default: string;
+            };
+        };
+    };
+    species: {
+        name: string;
+        url: string;
+    };
+}
+export interface PokeApiSpeciesRaw {
+    id: number;
+    name: string;
+    generation: {
+        name: string;
+        url: string;
+    };
+    flavor_text_entries: Array<{
+        flavor_text: string;
+        language: {
+            name: string;
+        };
+        version: {
+            name: string;
+        };
+    }>;
+}

package/dist/PokeApiTypes.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Raw response types from pokeapi.co API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { PokeApiClient, PokeApiClientConfig } from './PokeApiClient';
+export declare const POKEAPI_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POKEAPI_CONFIG = exports.PokeApiClient = void 0;
+var PokeApiClient_1 = require("./PokeApiClient");
+Object.defineProperty(exports, "PokeApiClient", { enumerable: true, get: function () { return PokeApiClient_1.PokeApiClient; } });
+exports.POKEAPI_CONFIG = {
+    cacheTtlMs: 1000 * 60 * 60 * 24 * 7, // 7 days — Pokemon data never changes
+    isBillable: false,
+};

package/eslint.config.mjs

@@ -0,0 +1,2 @@
+import { backend } from '@thalorlabs/eslint-plugin-dev-config';
+export default backend;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@thalorlabs/pokeapi",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for pokeapi.co — returns TLPokemon",
+  "homepage": "https://github.com/ThalorLabs/pokeapi#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/pokeapi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/pokeapi.git"
+  },
+  "license": "ISC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  },
+  "devDependencies": {
+    "@thalorlabs/eslint-plugin-dev-config": "^2.1.1",
+    "@types/node": "^25.5.2",
+    "prettier": "^3.8.1",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@thalorlabs/api": "^1.0.0",
+    "@thalorlabs/types": "^1.9.0"
+  }
+}

package/src/PokeApiClient.ts

@@ -0,0 +1,103 @@
+import { createHash, randomUUID } from 'crypto';
+
+import { BaseHttpClient } from '@thalorlabs/api';
+import { EPokemonType, TLPokemon } from '@thalorlabs/types';
+
+import { PokeApiPokemonRaw, PokeApiSpeciesRaw } from './PokeApiTypes';
+
+export interface PokeApiClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+const ROMAN_NUMERAL_MAP: Record<string, number> = {
+  i: 1,
+  ii: 2,
+  iii: 3,
+  iv: 4,
+  v: 5,
+  vi: 6,
+  vii: 7,
+  viii: 8,
+  ix: 9,
+};
+
+/**
+ * HTTP adapter for pokeapi.co.
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Multi-call provider: fetches pokemon data + species data,
+ * then normalises the combined response to TLPokemon.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+export class PokeApiClient extends BaseHttpClient {
+  public readonly serviceName = 'pokeapi';
+
+  constructor(config: PokeApiClientConfig = {}) {
+    super({
+      baseURL: config.baseURL ?? 'https://pokeapi.co/api/v2',
+      serviceName: 'pokeapi',
+      retries: 3,
+      timeout: config.timeout ?? 10000,
+    });
+  }
+
+  async getPokemon(): Promise<TLPokemon> {
+    const pokemonId = Math.floor(Math.random() * 1025) + 1;
+
+    const { response: pokemonResponse } =
+      await this.handleRequest<PokeApiPokemonRaw>(
+        { method: 'GET', url: `/pokemon/${pokemonId}` },
+        { method: 'GET', url: `/pokemon/${pokemonId}`, requestId: randomUUID() }
+      );
+
+    const { response: speciesResponse } =
+      await this.handleRequest<PokeApiSpeciesRaw>(
+        { method: 'GET', url: `/pokemon-species/${pokemonId}` },
+        {
+          method: 'GET',
+          url: `/pokemon-species/${pokemonId}`,
+          requestId: randomUUID(),
+        }
+      );
+
+    return this.normalise(pokemonResponse.data, speciesResponse.data);
+  }
+
+  private normalise(
+    pokemon: PokeApiPokemonRaw,
+    species: PokeApiSpeciesRaw
+  ): TLPokemon {
+    const name =
+      pokemon.name.charAt(0).toUpperCase() + pokemon.name.slice(1);
+
+    const types = pokemon.types
+      .map((t) => t.type.name.toUpperCase())
+      .filter((t): t is EPokemonType =>
+        Object.values(EPokemonType).includes(t as EPokemonType)
+      );
+
+    const englishEntry = species.flavor_text_entries.find(
+      (e) => e.language.name === 'en'
+    );
+    const description = englishEntry
+      ? englishEntry.flavor_text.replace(/[\n\f\r]/g, ' ')
+      : '';
+
+    const generationRoman = species.generation.name.split('-')[1];
+    const generation = ROMAN_NUMERAL_MAP[generationRoman] ?? 0;
+
+    const imageUrl =
+      pokemon.sprites.other['official-artwork'].front_default;
+
+    return TLPokemon.parse({
+      id: createHash('md5').update(pokemon.name).digest('hex'),
+      name,
+      types,
+      description,
+      imageUrl,
+      generation,
+      isSafe: true,
+    });
+  }
+}

package/src/PokeApiTypes.ts

@@ -0,0 +1,48 @@
+/**
+ * Raw response types from pokeapi.co API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+
+export interface PokeApiPokemonRaw {
+  id: number;
+  name: string;
+  types: Array<{
+    slot: number;
+    type: {
+      name: string;
+      url: string;
+    };
+  }>;
+  sprites: {
+    front_default: string;
+    other: {
+      'official-artwork': {
+        front_default: string;
+      };
+    };
+  };
+  species: {
+    name: string;
+    url: string;
+  };
+}
+
+export interface PokeApiSpeciesRaw {
+  id: number;
+  name: string;
+  generation: {
+    name: string; // e.g. "generation-i"
+    url: string;
+  };
+  flavor_text_entries: Array<{
+    flavor_text: string;
+    language: {
+      name: string;
+    };
+    version: {
+      name: string;
+    };
+  }>;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { PokeApiClient, PokeApiClientConfig } from './PokeApiClient';
+
+export const POKEAPI_CONFIG = {
+  cacheTtlMs: 1000 * 60 * 60 * 24 * 7, // 7 days — Pokemon data never changes
+  isBillable: false,
+} as const;

package/tests/PokeApiClient.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PokeApiClient } from '../src/PokeApiClient';
+import { EPokemonType } from '@thalorlabs/types';
+import { BaseHttpClient } from '@thalorlabs/api';
+
+// Mock handleRequest on the prototype — no axios import needed in tests
+const mockHandleRequest = vi.fn();
+vi.spyOn(BaseHttpClient.prototype as any, 'handleRequest').mockImplementation(
+  mockHandleRequest
+);
+
+const MOCK_POKEMON_RAW = {
+  id: 25,
+  name: 'pikachu',
+  types: [{ slot: 1, type: { name: 'electric', url: '' } }],
+  sprites: {
+    front_default: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png',
+    other: { 'official-artwork': { front_default: 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/25.png' } },
+  },
+  species: { name: 'pikachu', url: '' },
+};
+
+const MOCK_SPECIES_RAW = {
+  id: 25,
+  name: 'pikachu',
+  generation: { name: 'generation-i', url: '' },
+  flavor_text_entries: [
+    {
+      flavor_text: 'An electric\nPokemon.',
+      language: { name: 'en' },
+      version: { name: 'red' },
+    },
+  ],
+};
+
+function mockBothCalls() {
+  mockHandleRequest
+    .mockResolvedValueOnce({
+      response: { data: MOCK_POKEMON_RAW },
+      durationMs: 50,
+    })
+    .mockResolvedValueOnce({
+      response: { data: MOCK_SPECIES_RAW },
+      durationMs: 50,
+    });
+}
+
+describe('PokeApiClient', () => {
+  let client: PokeApiClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new PokeApiClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to pokeapi', () => {
+      expect(client.serviceName).toBe('pokeapi');
+    });
+  });
+
+  describe('getPokemon', () => {
+    it('returns a valid TLPokemon', async () => {
+      mockBothCalls();
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.name).toBe('Pikachu');
+      expect(pokemon.isSafe).toBe(true);
+      expect(pokemon.id).toBeDefined();
+      expect(pokemon.imageUrl).toBe('https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/25.png');
+    });
+
+    it('maps known EPokemonType values and skips unknown types', async () => {
+      const pokemonWithMixedTypes = {
+        ...MOCK_POKEMON_RAW,
+        types: [
+          { slot: 1, type: { name: 'electric', url: '' } },
+          { slot: 2, type: { name: 'fighting', url: '' } },
+        ],
+      };
+
+      mockHandleRequest
+        .mockResolvedValueOnce({
+          response: { data: pokemonWithMixedTypes },
+          durationMs: 50,
+        })
+        .mockResolvedValueOnce({
+          response: { data: MOCK_SPECIES_RAW },
+          durationMs: 50,
+        });
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.types).toContain(EPokemonType.ELECTRIC);
+      expect(pokemon.types).not.toContain('FIGHTING');
+      expect(pokemon.types).toHaveLength(1);
+    });
+
+    it('cleans flavor text by replacing newlines and form feeds', async () => {
+      const speciesWithDirtyText = {
+        ...MOCK_SPECIES_RAW,
+        flavor_text_entries: [
+          {
+            flavor_text: 'A cute\felectric\npokemon\rthat sparks.',
+            language: { name: 'en' },
+            version: { name: 'red' },
+          },
+        ],
+      };
+
+      mockHandleRequest
+        .mockResolvedValueOnce({
+          response: { data: MOCK_POKEMON_RAW },
+          durationMs: 50,
+        })
+        .mockResolvedValueOnce({
+          response: { data: speciesWithDirtyText },
+          durationMs: 50,
+        });
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.description).toBe(
+        'A cute electric pokemon that sparks.'
+      );
+      expect(pokemon.description).not.toMatch(/[\n\f\r]/);
+    });
+
+    it('parses generation number from roman numerals', async () => {
+      mockBothCalls();
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.generation).toBe(1);
+    });
+
+    it('parses higher generation roman numerals correctly', async () => {
+      const speciesGen4 = {
+        ...MOCK_SPECIES_RAW,
+        generation: { name: 'generation-iv', url: '' },
+      };
+
+      mockHandleRequest
+        .mockResolvedValueOnce({
+          response: { data: MOCK_POKEMON_RAW },
+          durationMs: 50,
+        })
+        .mockResolvedValueOnce({
+          response: { data: speciesGen4 },
+          durationMs: 50,
+        });
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.generation).toBe(4);
+    });
+
+    it('capitalizes the pokemon name', async () => {
+      mockBothCalls();
+
+      const pokemon = await client.getPokemon();
+
+      expect(pokemon.name).toBe('Pikachu');
+    });
+
+    it('generates a deterministic id from pokemon name', async () => {
+      mockBothCalls();
+      const pokemon1 = await client.getPokemon();
+
+      mockBothCalls();
+      const pokemon2 = await client.getPokemon();
+
+      expect(pokemon1.id).toBe(pokemon2.id);
+    });
+
+    it('makes two handleRequest calls (pokemon + species)', async () => {
+      mockBothCalls();
+
+      await client.getPokemon();
+
+      expect(mockHandleRequest).toHaveBeenCalledTimes(2);
+      expect(mockHandleRequest).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'GET' }),
+        expect.objectContaining({ method: 'GET' })
+      );
+    });
+
+    it('propagates errors from handleRequest', async () => {
+      mockHandleRequest.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(client.getPokemon()).rejects.toThrow('Network error');
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@thalorlabs/eslint-plugin-dev-config/tsconfig/backend.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}