@thalorlabs/swapi 1.0.0

package/.prettierrc

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

package/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md — @thalorlabs/swapi
+
+## What this is
+
+Provider adapter for swapi.dev (Star Wars API). Returns `TLStarWarsFact`.
+
+## External API
+
+- swapi.dev — free, no auth, no billing
+- Returns character data from the Star Wars universe
+- No random endpoint — uses random ID selection
+
+## 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
+- Normalises raw swapi.dev response to TLStarWarsFact
+- Generates deterministic MD5 hash ID from character name
+- Sets: type=CHARACTER, faction=UNKNOWN, 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/SwapiClient.d.ts

@@ -0,0 +1,21 @@
+import { BaseHttpClient } from '@thalorlabs/api';
+import { TLStarWarsFact } from '@thalorlabs/types';
+export interface SwapiClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+/**
+ * HTTP adapter for swapi.dev (Star Wars API).
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Normalises the raw response to TLStarWarsFact.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+export declare class SwapiClient extends BaseHttpClient {
+    readonly serviceName = "swapi";
+    private static readonly MAX_PERSON_ID;
+    private static readonly MAX_RETRIES_FOR_GAPS;
+    constructor(config?: SwapiClientConfig);
+    getFact(): Promise<TLStarWarsFact>;
+    private normalise;
+}

package/dist/SwapiClient.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwapiClient = void 0;
+const crypto_1 = require("crypto");
+const api_1 = require("@thalorlabs/api");
+const types_1 = require("@thalorlabs/types");
+/**
+ * HTTP adapter for swapi.dev (Star Wars API).
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Normalises the raw response to TLStarWarsFact.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+class SwapiClient extends api_1.BaseHttpClient {
+    constructor(config = {}) {
+        super({
+            baseURL: config.baseURL ?? 'https://swapi.dev/api',
+            serviceName: 'swapi',
+            retries: 3,
+            timeout: config.timeout ?? 10000,
+        });
+        this.serviceName = 'swapi';
+    }
+    async getFact() {
+        let lastError;
+        for (let attempt = 0; attempt < SwapiClient.MAX_RETRIES_FOR_GAPS; attempt++) {
+            const id = Math.floor(Math.random() * SwapiClient.MAX_PERSON_ID) + 1;
+            try {
+                const { response } = await this.handleRequest({ method: 'GET', url: `/people/${id}/` }, { method: 'GET', url: `/people/${id}/`, requestId: (0, crypto_1.randomUUID)() });
+                return this.normalise(response.data);
+            }
+            catch (error) {
+                lastError = error;
+                // If it's a 404 (gap in IDs), retry with a different ID
+                if (error?.response?.status === 404 || error?.status === 404) {
+                    continue;
+                }
+                // For non-404 errors, throw immediately
+                throw error;
+            }
+        }
+        throw lastError ?? new Error('Failed to fetch Star Wars character after maximum retries');
+    }
+    normalise(raw) {
+        const content = `${raw.name} is a ${raw.gender} character born in ${raw.birth_year}, standing ${raw.height}cm tall.`;
+        return types_1.TLStarWarsFact.parse({
+            id: (0, crypto_1.createHash)('md5').update(raw.name).digest('hex'),
+            type: types_1.EStarWarsFactType.CHARACTER,
+            content,
+            character: raw.name,
+            faction: types_1.EStarWarsFaction.UNKNOWN,
+            film: undefined,
+            isSafe: true,
+        });
+    }
+}
+exports.SwapiClient = SwapiClient;
+SwapiClient.MAX_PERSON_ID = 82;
+SwapiClient.MAX_RETRIES_FOR_GAPS = 5;

package/dist/SwapiTypes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Raw response types from swapi.dev API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwapiPersonRaw {
+    name: string;
+    height: string;
+    mass: string;
+    hair_color: string;
+    skin_color: string;
+    eye_color: string;
+    birth_year: string;
+    gender: string;
+    homeworld: string;
+    films: string[];
+    species: string[];
+    vehicles: string[];
+    starships: string[];
+    created: string;
+    edited: string;
+    url: string;
+}
+export interface SwapiPlanetRaw {
+    name: string;
+    rotation_period: string;
+    orbital_period: string;
+    diameter: string;
+    climate: string;
+    gravity: string;
+    terrain: string;
+    surface_water: string;
+    population: string;
+    residents: string[];
+    films: string[];
+    created: string;
+    edited: string;
+    url: string;
+}
+export interface SwapiFilmRaw {
+    title: string;
+    episode_id: number;
+    opening_crawl: string;
+    director: string;
+    producer: string;
+    release_date: string;
+    characters: string[];
+    planets: string[];
+    starships: string[];
+    vehicles: string[];
+    species: string[];
+    created: string;
+    edited: string;
+    url: string;
+}
+export interface SwapiListResponse<T> {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    results: T[];
+}

package/dist/SwapiTypes.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Raw response types from swapi.dev 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 { SwapiClient, SwapiClientConfig } from './SwapiClient';
+export declare const SWAPI_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWAPI_CONFIG = exports.SwapiClient = void 0;
+var SwapiClient_1 = require("./SwapiClient");
+Object.defineProperty(exports, "SwapiClient", { enumerable: true, get: function () { return SwapiClient_1.SwapiClient; } });
+exports.SWAPI_CONFIG = {
+    cacheTtlMs: 1000 * 60 * 60 * 24 * 7, // 7 days — Star Wars 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/swapi",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for swapi.dev — returns TLStarWarsFact",
+  "homepage": "https://github.com/ThalorLabs/swapi#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/swapi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/swapi.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/SwapiClient.ts

@@ -0,0 +1,76 @@
+import { createHash, randomUUID } from 'crypto';
+
+import { BaseHttpClient } from '@thalorlabs/api';
+import { EStarWarsFaction, EStarWarsFactType, TLStarWarsFact } from '@thalorlabs/types';
+
+import { SwapiPersonRaw } from './SwapiTypes';
+
+export interface SwapiClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+/**
+ * HTTP adapter for swapi.dev (Star Wars API).
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Normalises the raw response to TLStarWarsFact.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+export class SwapiClient extends BaseHttpClient {
+  public readonly serviceName = 'swapi';
+
+  private static readonly MAX_PERSON_ID = 82;
+  private static readonly MAX_RETRIES_FOR_GAPS = 5;
+
+  constructor(config: SwapiClientConfig = {}) {
+    super({
+      baseURL: config.baseURL ?? 'https://swapi.dev/api',
+      serviceName: 'swapi',
+      retries: 3,
+      timeout: config.timeout ?? 10000,
+    });
+  }
+
+  async getFact(): Promise<TLStarWarsFact> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < SwapiClient.MAX_RETRIES_FOR_GAPS; attempt++) {
+      const id = Math.floor(Math.random() * SwapiClient.MAX_PERSON_ID) + 1;
+
+      try {
+        const { response } = await this.handleRequest<SwapiPersonRaw>(
+          { method: 'GET', url: `/people/${id}/` },
+          { method: 'GET', url: `/people/${id}/`, requestId: randomUUID() }
+        );
+        return this.normalise(response.data);
+      } catch (error: any) {
+        lastError = error;
+
+        // If it's a 404 (gap in IDs), retry with a different ID
+        if (error?.response?.status === 404 || error?.status === 404) {
+          continue;
+        }
+
+        // For non-404 errors, throw immediately
+        throw error;
+      }
+    }
+
+    throw lastError ?? new Error('Failed to fetch Star Wars character after maximum retries');
+  }
+
+  private normalise(raw: SwapiPersonRaw): TLStarWarsFact {
+    const content = `${raw.name} is a ${raw.gender} character born in ${raw.birth_year}, standing ${raw.height}cm tall.`;
+
+    return TLStarWarsFact.parse({
+      id: createHash('md5').update(raw.name).digest('hex'),
+      type: EStarWarsFactType.CHARACTER,
+      content,
+      character: raw.name,
+      faction: EStarWarsFaction.UNKNOWN,
+      film: undefined,
+      isSafe: true,
+    });
+  }
+}

package/src/SwapiTypes.ts

@@ -0,0 +1,66 @@
+/**
+ * Raw response types from swapi.dev API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+
+export interface SwapiPersonRaw {
+  name: string;
+  height: string;
+  mass: string;
+  hair_color: string;
+  skin_color: string;
+  eye_color: string;
+  birth_year: string;
+  gender: string;
+  homeworld: string;
+  films: string[];
+  species: string[];
+  vehicles: string[];
+  starships: string[];
+  created: string;
+  edited: string;
+  url: string;
+}
+
+export interface SwapiPlanetRaw {
+  name: string;
+  rotation_period: string;
+  orbital_period: string;
+  diameter: string;
+  climate: string;
+  gravity: string;
+  terrain: string;
+  surface_water: string;
+  population: string;
+  residents: string[];
+  films: string[];
+  created: string;
+  edited: string;
+  url: string;
+}
+
+export interface SwapiFilmRaw {
+  title: string;
+  episode_id: number;
+  opening_crawl: string;
+  director: string;
+  producer: string;
+  release_date: string;
+  characters: string[];
+  planets: string[];
+  starships: string[];
+  vehicles: string[];
+  species: string[];
+  created: string;
+  edited: string;
+  url: string;
+}
+
+export interface SwapiListResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { SwapiClient, SwapiClientConfig } from './SwapiClient';
+
+export const SWAPI_CONFIG = {
+  cacheTtlMs: 1000 * 60 * 60 * 24 * 7, // 7 days — Star Wars data never changes
+  isBillable: false,
+} as const;

package/tests/SwapiClient.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SwapiClient } from '../src/SwapiClient';
+import { EStarWarsFactType, EStarWarsFaction } 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
+);
+
+describe('SwapiClient', () => {
+  let client: SwapiClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new SwapiClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to swapi', () => {
+      expect(client.serviceName).toBe('swapi');
+    });
+  });
+
+  describe('getFact', () => {
+    it('returns a valid TLStarWarsFact with CHARACTER type', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            name: 'Luke Skywalker',
+            height: '172',
+            mass: '77',
+            hair_color: 'blond',
+            skin_color: 'fair',
+            eye_color: 'blue',
+            birth_year: '19BBY',
+            gender: 'male',
+            homeworld: 'https://swapi.dev/api/planets/1/',
+            films: ['https://swapi.dev/api/films/1/'],
+            species: [],
+            vehicles: [],
+            starships: [],
+            created: '2014-12-09T13:50:51.644000Z',
+            edited: '2014-12-20T21:17:56.891000Z',
+            url: 'https://swapi.dev/api/people/1/',
+          },
+        },
+        durationMs: 50,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.type).toBe(EStarWarsFactType.CHARACTER);
+      expect(fact.faction).toBe(EStarWarsFaction.UNKNOWN);
+      expect(fact.character).toBe('Luke Skywalker');
+      expect(fact.content).toBe(
+        'Luke Skywalker is a male character born in 19BBY, standing 172cm tall.'
+      );
+      expect(fact.isSafe).toBe(true);
+      expect(fact.id).toBeDefined();
+    });
+
+    it('generates a deterministic id from character name', async () => {
+      const personData = {
+        name: 'Darth Vader',
+        height: '202',
+        mass: '136',
+        hair_color: 'none',
+        skin_color: 'white',
+        eye_color: 'yellow',
+        birth_year: '41.9BBY',
+        gender: 'male',
+        homeworld: 'https://swapi.dev/api/planets/1/',
+        films: [],
+        species: [],
+        vehicles: [],
+        starships: [],
+        created: '2014-12-10T15:18:20.704000Z',
+        edited: '2014-12-20T21:17:50.313000Z',
+        url: 'https://swapi.dev/api/people/4/',
+      };
+
+      mockHandleRequest.mockResolvedValue({
+        response: { data: personData },
+        durationMs: 10,
+      });
+
+      const fact1 = await client.getFact();
+      const fact2 = await client.getFact();
+
+      expect(fact1.id).toBe(fact2.id);
+    });
+
+    it('calls handleRequest with GET /people/{id}/', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            name: 'C-3PO',
+            height: '167',
+            mass: '75',
+            hair_color: 'n/a',
+            skin_color: 'gold',
+            eye_color: 'yellow',
+            birth_year: '112BBY',
+            gender: 'n/a',
+            homeworld: 'https://swapi.dev/api/planets/1/',
+            films: [],
+            species: [],
+            vehicles: [],
+            starships: [],
+            created: '2014-12-10T15:10:51.357000Z',
+            edited: '2014-12-20T21:17:50.309000Z',
+            url: 'https://swapi.dev/api/people/2/',
+          },
+        },
+        durationMs: 10,
+      });
+
+      await client.getFact();
+
+      expect(mockHandleRequest).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'GET', url: expect.stringMatching(/^\/people\/\d+\/$/) }),
+        expect.objectContaining({ method: 'GET', url: expect.stringMatching(/^\/people\/\d+\/$/) })
+      );
+    });
+
+    it('propagates errors from handleRequest', async () => {
+      mockHandleRequest.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(client.getFact()).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"]
+}