@thalorlabs/swapiinfo 1.0.0

package/.prettierrc

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

package/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md — @thalorlabs/swapiinfo
+
+## What this is
+
+Provider adapter for swapi.info (Star Wars API alternative). Returns `TLStarWarsFact`.
+
+## External API
+
+- swapi.info — free, no auth, no billing, no rate limits
+- Returns planet data from the Star Wars universe
+- Hosted on Vercel with CDN caching, ~50ms responses
+
+## 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.info planet response to TLStarWarsFact
+- Generates deterministic MD5 hash ID from planet name
+- Sets: type=PLANET, 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/SwapiInfoClient.d.ts

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

package/dist/SwapiInfoClient.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwapiInfoClient = void 0;
+const crypto_1 = require("crypto");
+const api_1 = require("@thalorlabs/api");
+const types_1 = require("@thalorlabs/types");
+/**
+ * HTTP adapter for swapi.info (Star Wars API).
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Normalises the raw planet response to TLStarWarsFact.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+class SwapiInfoClient extends api_1.BaseHttpClient {
+    constructor(config = {}) {
+        super({
+            baseURL: config.baseURL ?? 'https://swapi.info/api',
+            serviceName: 'swapiinfo',
+            retries: 3,
+            timeout: config.timeout ?? 10000,
+        });
+        this.serviceName = 'swapiinfo';
+    }
+    async getFact() {
+        let lastError;
+        for (let attempt = 0; attempt < SwapiInfoClient.MAX_RETRIES_404; attempt++) {
+            const id = this.randomPlanetId();
+            try {
+                const { response } = await this.handleRequest({ method: 'GET', url: `/planets/${id}` }, { method: 'GET', url: `/planets/${id}`, requestId: (0, crypto_1.randomUUID)() });
+                return this.normalise(response.data);
+            }
+            catch (err) {
+                lastError = err;
+                if (this.is404(err))
+                    continue;
+                throw err;
+            }
+        }
+        throw lastError;
+    }
+    randomPlanetId() {
+        return Math.floor(Math.random() * SwapiInfoClient.MAX_PLANET_ID) + 1;
+    }
+    is404(err) {
+        if (err && typeof err === 'object' && 'response' in err) {
+            const resp = err.response;
+            return resp?.status === 404;
+        }
+        return false;
+    }
+    normalise(raw) {
+        return types_1.TLStarWarsFact.parse({
+            id: (0, crypto_1.createHash)('md5').update(raw.name).digest('hex'),
+            type: types_1.EStarWarsFactType.PLANET,
+            content: `${raw.name} is a ${raw.climate} planet with ${raw.terrain} terrain and a population of ${raw.population}.`,
+            character: undefined,
+            faction: types_1.EStarWarsFaction.UNKNOWN,
+            film: undefined,
+            isSafe: true,
+        });
+    }
+}
+exports.SwapiInfoClient = SwapiInfoClient;
+SwapiInfoClient.MAX_PLANET_ID = 60;
+SwapiInfoClient.MAX_RETRIES_404 = 5;

package/dist/SwapiInfoTypes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Raw response from swapi.info planet endpoint.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwapiInfoPlanetRaw {
+    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[];
+    url: string;
+}
+/**
+ * Raw response from swapi.info film endpoint.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwapiInfoFilmRaw {
+    title: string;
+    episode_id: number;
+    opening_crawl: string;
+    director: string;
+    producer: string;
+    release_date: string;
+    url: string;
+}

package/dist/SwapiInfoTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SwapiInfoClient, SwapiInfoClientConfig } from './SwapiInfoClient';
+export declare const SWAPIINFO_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWAPIINFO_CONFIG = exports.SwapiInfoClient = void 0;
+var SwapiInfoClient_1 = require("./SwapiInfoClient");
+Object.defineProperty(exports, "SwapiInfoClient", { enumerable: true, get: function () { return SwapiInfoClient_1.SwapiInfoClient; } });
+exports.SWAPIINFO_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/swapiinfo",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for swapi.info — returns TLStarWarsFact",
+  "homepage": "https://github.com/ThalorLabs/swapiinfo#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/swapiinfo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/swapiinfo.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/SwapiInfoClient.ts

@@ -0,0 +1,80 @@
+import { createHash, randomUUID } from 'crypto';
+
+import { BaseHttpClient } from '@thalorlabs/api';
+import { EStarWarsFaction, EStarWarsFactType, TLStarWarsFact } from '@thalorlabs/types';
+
+import { SwapiInfoPlanetRaw } from './SwapiInfoTypes';
+
+export interface SwapiInfoClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+/**
+ * HTTP adapter for swapi.info (Star Wars API).
+ *
+ * Extends BaseHttpClient for retry logic, exponential backoff, and
+ * observability. Normalises the raw planet response to TLStarWarsFact.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ */
+export class SwapiInfoClient extends BaseHttpClient {
+  public readonly serviceName = 'swapiinfo';
+
+  private static readonly MAX_PLANET_ID = 60;
+  private static readonly MAX_RETRIES_404 = 5;
+
+  constructor(config: SwapiInfoClientConfig = {}) {
+    super({
+      baseURL: config.baseURL ?? 'https://swapi.info/api',
+      serviceName: 'swapiinfo',
+      retries: 3,
+      timeout: config.timeout ?? 10000,
+    });
+  }
+
+  async getFact(): Promise<TLStarWarsFact> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt < SwapiInfoClient.MAX_RETRIES_404; attempt++) {
+      const id = this.randomPlanetId();
+
+      try {
+        const { response } = await this.handleRequest<SwapiInfoPlanetRaw>(
+          { method: 'GET', url: `/planets/${id}` },
+          { method: 'GET', url: `/planets/${id}`, requestId: randomUUID() }
+        );
+        return this.normalise(response.data);
+      } catch (err: unknown) {
+        lastError = err;
+        if (this.is404(err)) continue;
+        throw err;
+      }
+    }
+
+    throw lastError;
+  }
+
+  private randomPlanetId(): number {
+    return Math.floor(Math.random() * SwapiInfoClient.MAX_PLANET_ID) + 1;
+  }
+
+  private is404(err: unknown): boolean {
+    if (err && typeof err === 'object' && 'response' in err) {
+      const resp = (err as { response?: { status?: number } }).response;
+      return resp?.status === 404;
+    }
+    return false;
+  }
+
+  private normalise(raw: SwapiInfoPlanetRaw): TLStarWarsFact {
+    return TLStarWarsFact.parse({
+      id: createHash('md5').update(raw.name).digest('hex'),
+      type: EStarWarsFactType.PLANET,
+      content: `${raw.name} is a ${raw.climate} planet with ${raw.terrain} terrain and a population of ${raw.population}.`,
+      character: undefined,
+      faction: EStarWarsFaction.UNKNOWN,
+      film: undefined,
+      isSafe: true,
+    });
+  }
+}

package/src/SwapiInfoTypes.ts

@@ -0,0 +1,36 @@
+/**
+ * Raw response from swapi.info planet endpoint.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwapiInfoPlanetRaw {
+  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[];
+  url: string;
+}
+
+/**
+ * Raw response from swapi.info film endpoint.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwapiInfoFilmRaw {
+  title: string;
+  episode_id: number;
+  opening_crawl: string;
+  director: string;
+  producer: string;
+  release_date: string;
+  url: string;
+}

package/src/index.ts

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

package/tests/SwapiInfoClient.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SwapiInfoClient } from '../src/SwapiInfoClient';
+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
+);
+
+const MOCK_PLANET = {
+  name: 'Tatooine',
+  rotation_period: '23',
+  orbital_period: '304',
+  diameter: '10465',
+  climate: 'arid',
+  gravity: '1 standard',
+  terrain: 'desert',
+  surface_water: '1',
+  population: '200000',
+  residents: ['https://swapi.info/api/people/1'],
+  films: ['https://swapi.info/api/films/1'],
+  url: 'https://swapi.info/api/planets/1',
+};
+
+describe('SwapiInfoClient', () => {
+  let client: SwapiInfoClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new SwapiInfoClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to swapiinfo', () => {
+      expect(client.serviceName).toBe('swapiinfo');
+    });
+  });
+
+  describe('getFact', () => {
+    it('returns a valid TLStarWarsFact with PLANET type', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: { data: MOCK_PLANET },
+        durationMs: 50,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.type).toBe(EStarWarsFactType.PLANET);
+      expect(fact.faction).toBe(EStarWarsFaction.UNKNOWN);
+      expect(fact.isSafe).toBe(true);
+      expect(fact.character).toBeUndefined();
+      expect(fact.film).toBeUndefined();
+      expect(fact.id).toBeDefined();
+    });
+
+    it('formats content string correctly', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: { data: MOCK_PLANET },
+        durationMs: 50,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.content).toBe(
+        'Tatooine is a arid planet with desert terrain and a population of 200000.'
+      );
+    });
+
+    it('generates a deterministic id from planet name', async () => {
+      mockHandleRequest.mockResolvedValue({
+        response: { data: MOCK_PLANET },
+        durationMs: 10,
+      });
+
+      const fact1 = await client.getFact();
+      const fact2 = await client.getFact();
+
+      expect(fact1.id).toBe(fact2.id);
+    });
+
+    it('calls handleRequest with GET /planets/{id}', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: { data: MOCK_PLANET },
+        durationMs: 10,
+      });
+
+      await client.getFact();
+
+      expect(mockHandleRequest).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'GET' }),
+        expect.objectContaining({ method: 'GET' })
+      );
+      const callUrl = mockHandleRequest.mock.calls[0][0].url;
+      expect(callUrl).toMatch(/^\/planets\/\d+$/);
+    });
+
+    it('retries on 404 with a different planet ID', async () => {
+      const err404 = Object.assign(new Error('Not Found'), {
+        response: { status: 404 },
+      });
+      mockHandleRequest
+        .mockRejectedValueOnce(err404)
+        .mockResolvedValueOnce({
+          response: { data: MOCK_PLANET },
+          durationMs: 10,
+        });
+
+      const fact = await client.getFact();
+
+      expect(mockHandleRequest).toHaveBeenCalledTimes(2);
+      expect(fact.type).toBe(EStarWarsFactType.PLANET);
+    });
+
+    it('propagates non-404 errors immediately', async () => {
+      mockHandleRequest.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(client.getFact()).rejects.toThrow('Network error');
+      expect(mockHandleRequest).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws after exhausting 404 retries', async () => {
+      const err404 = Object.assign(new Error('Not Found'), {
+        response: { status: 404 },
+      });
+      mockHandleRequest.mockRejectedValue(err404);
+
+      await expect(client.getFact()).rejects.toThrow('Not Found');
+      expect(mockHandleRequest).toHaveBeenCalledTimes(5);
+    });
+  });
+});

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"]
+}