@thalorlabs/swquotes 1.0.0

package/.prettierrc

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

package/CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md — @thalorlabs/swquotes
+
+## What this is
+
+Provider adapter for swquotesapi.digitaljedi.dk (Star Wars Quotes API). Returns `TLStarWarsFact`.
+
+## External API
+
+- swquotesapi.digitaljedi.dk — free, no auth, no billing
+- Returns random Star Wars quotes with character attribution
+- HTTP only (not HTTPS)
+
+## 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 quote response to TLStarWarsFact
+- Parses character name from quote text
+- Maps numeric faction codes to EStarWarsFaction enum
+- Sets: type=QUOTE, 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/SwQuotesClient.d.ts

@@ -0,0 +1,21 @@
+import { BaseHttpClient } from '@thalorlabs/api';
+import { TLStarWarsFact } from '@thalorlabs/types';
+export interface SwQuotesClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+/**
+ * HTTP adapter for swquotesapi.digitaljedi.dk.
+ *
+ * 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 SwQuotesClient extends BaseHttpClient {
+    readonly serviceName = "swquotes";
+    constructor(config?: SwQuotesClientConfig);
+    getFact(): Promise<TLStarWarsFact>;
+    private normalise;
+    private parseQuote;
+    private mapFaction;
+}

package/dist/SwQuotesClient.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwQuotesClient = void 0;
+const crypto_1 = require("crypto");
+const api_1 = require("@thalorlabs/api");
+const types_1 = require("@thalorlabs/types");
+/**
+ * HTTP adapter for swquotesapi.digitaljedi.dk.
+ *
+ * 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 SwQuotesClient extends api_1.BaseHttpClient {
+    constructor(config = {}) {
+        super({
+            baseURL: config.baseURL ?? 'http://swquotesapi.digitaljedi.dk',
+            serviceName: 'swquotes',
+            retries: 3,
+            timeout: config.timeout ?? 10000,
+        });
+        this.serviceName = 'swquotes';
+    }
+    async getFact() {
+        const { response } = await this.handleRequest({ method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote' }, { method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote', requestId: (0, crypto_1.randomUUID)() });
+        return this.normalise(response.data);
+    }
+    normalise(raw) {
+        const { content, character } = this.parseQuote(raw.starWarsQuote);
+        return types_1.TLStarWarsFact.parse({
+            id: (0, crypto_1.createHash)('md5').update(raw.starWarsQuote).digest('hex'),
+            type: types_1.EStarWarsFactType.QUOTE,
+            content,
+            character,
+            faction: this.mapFaction(raw.faction),
+            film: undefined,
+            isSafe: true,
+        });
+    }
+    parseQuote(quote) {
+        // Try " — " first (em-dash style), then " - " (hyphen style)
+        const emDashIndex = quote.lastIndexOf(' — ');
+        if (emDashIndex !== -1) {
+            return {
+                content: quote.substring(0, emDashIndex).trim(),
+                character: quote.substring(emDashIndex + 3).trim(),
+            };
+        }
+        const hyphenIndex = quote.lastIndexOf(' - ');
+        if (hyphenIndex !== -1) {
+            return {
+                content: quote.substring(0, hyphenIndex).trim(),
+                character: quote.substring(hyphenIndex + 3).trim(),
+            };
+        }
+        return { content: quote };
+    }
+    mapFaction(faction) {
+        switch (faction) {
+            case 0:
+                return types_1.EStarWarsFaction.JEDI_ORDER;
+            case 1:
+                return types_1.EStarWarsFaction.SITH;
+            case 3:
+                return types_1.EStarWarsFaction.REBEL_ALLIANCE;
+            case 2:
+            case 4:
+            default:
+                return types_1.EStarWarsFaction.UNKNOWN;
+        }
+    }
+}
+exports.SwQuotesClient = SwQuotesClient;

package/dist/SwQuotesTypes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raw response from swquotesapi.digitaljedi.dk API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwQuotesRawResponse {
+    id: number;
+    starWarsQuote: string;
+    faction: number;
+}

package/dist/SwQuotesTypes.js

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SwQuotesClient, SwQuotesClientConfig } from './SwQuotesClient';
+export declare const SWQUOTES_CONFIG: {
+    readonly cacheTtlMs: 0;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWQUOTES_CONFIG = exports.SwQuotesClient = void 0;
+var SwQuotesClient_1 = require("./SwQuotesClient");
+Object.defineProperty(exports, "SwQuotesClient", { enumerable: true, get: function () { return SwQuotesClient_1.SwQuotesClient; } });
+exports.SWQUOTES_CONFIG = {
+    cacheTtlMs: 0, // random endpoint — no caching
+    isBillable: false, // swquotesapi is free
+};

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/swquotes",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for swquotesapi.digitaljedi.dk — returns TLStarWarsFact",
+  "homepage": "https://github.com/ThalorLabs/swquotes#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/swquotes/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/swquotes.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/SwQuotesClient.ts

@@ -0,0 +1,89 @@
+import { createHash, randomUUID } from 'crypto';
+
+import { BaseHttpClient } from '@thalorlabs/api';
+import { EStarWarsFaction, EStarWarsFactType, TLStarWarsFact } from '@thalorlabs/types';
+
+import { SwQuotesRawResponse } from './SwQuotesTypes';
+
+export interface SwQuotesClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+/**
+ * HTTP adapter for swquotesapi.digitaljedi.dk.
+ *
+ * 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 SwQuotesClient extends BaseHttpClient {
+  public readonly serviceName = 'swquotes';
+
+  constructor(config: SwQuotesClientConfig = {}) {
+    super({
+      baseURL: config.baseURL ?? 'http://swquotesapi.digitaljedi.dk',
+      serviceName: 'swquotes',
+      retries: 3,
+      timeout: config.timeout ?? 10000,
+    });
+  }
+
+  async getFact(): Promise<TLStarWarsFact> {
+    const { response } = await this.handleRequest<SwQuotesRawResponse>(
+      { method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote' },
+      { method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote', requestId: randomUUID() }
+    );
+    return this.normalise(response.data);
+  }
+
+  private normalise(raw: SwQuotesRawResponse): TLStarWarsFact {
+    const { content, character } = this.parseQuote(raw.starWarsQuote);
+
+    return TLStarWarsFact.parse({
+      id: createHash('md5').update(raw.starWarsQuote).digest('hex'),
+      type: EStarWarsFactType.QUOTE,
+      content,
+      character,
+      faction: this.mapFaction(raw.faction),
+      film: undefined,
+      isSafe: true,
+    });
+  }
+
+  private parseQuote(quote: string): { content: string; character?: string } {
+    // Try " — " first (em-dash style), then " - " (hyphen style)
+    const emDashIndex = quote.lastIndexOf(' — ');
+    if (emDashIndex !== -1) {
+      return {
+        content: quote.substring(0, emDashIndex).trim(),
+        character: quote.substring(emDashIndex + 3).trim(),
+      };
+    }
+
+    const hyphenIndex = quote.lastIndexOf(' - ');
+    if (hyphenIndex !== -1) {
+      return {
+        content: quote.substring(0, hyphenIndex).trim(),
+        character: quote.substring(hyphenIndex + 3).trim(),
+      };
+    }
+
+    return { content: quote };
+  }
+
+  private mapFaction(faction: number): EStarWarsFaction {
+    switch (faction) {
+      case 0:
+        return EStarWarsFaction.JEDI_ORDER;
+      case 1:
+        return EStarWarsFaction.SITH;
+      case 3:
+        return EStarWarsFaction.REBEL_ALLIANCE;
+      case 2:
+      case 4:
+      default:
+        return EStarWarsFaction.UNKNOWN;
+    }
+  }
+}

package/src/SwQuotesTypes.ts

@@ -0,0 +1,11 @@
+/**
+ * Raw response from swquotesapi.digitaljedi.dk API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface SwQuotesRawResponse {
+  id: number;
+  starWarsQuote: string;
+  faction: number;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { SwQuotesClient, SwQuotesClientConfig } from './SwQuotesClient';
+
+export const SWQUOTES_CONFIG = {
+  cacheTtlMs: 0, // random endpoint — no caching
+  isBillable: false, // swquotesapi is free
+} as const;

package/tests/SwQuotesClient.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SwQuotesClient } from '../src/SwQuotesClient';
+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('SwQuotesClient', () => {
+  let client: SwQuotesClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new SwQuotesClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to swquotes', () => {
+      expect(client.serviceName).toBe('swquotes');
+    });
+  });
+
+  describe('getFact', () => {
+    it('returns a valid TLStarWarsFact with QUOTE type', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            id: 7,
+            starWarsQuote: 'Never tell me the odds! — Han Solo',
+            faction: 4,
+          },
+        },
+        durationMs: 50,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.type).toBe(EStarWarsFactType.QUOTE);
+      expect(fact.content).toBe('Never tell me the odds!');
+      expect(fact.character).toBe('Han Solo');
+      expect(fact.isSafe).toBe(true);
+      expect(fact.id).toBeDefined();
+    });
+
+    it('parses character name from em-dash separator', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            id: 1,
+            starWarsQuote: 'Do. Or do not. There is no try. — Yoda',
+            faction: 0,
+          },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.content).toBe('Do. Or do not. There is no try.');
+      expect(fact.character).toBe('Yoda');
+    });
+
+    it('parses character name from hyphen separator', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            id: 2,
+            starWarsQuote: 'I am your father - Darth Vader',
+            faction: 1,
+          },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.content).toBe('I am your father');
+      expect(fact.character).toBe('Darth Vader');
+    });
+
+    it('handles quotes without character attribution', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: {
+            id: 3,
+            starWarsQuote: 'A long time ago in a galaxy far, far away...',
+            faction: 2,
+          },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+
+      expect(fact.content).toBe('A long time ago in a galaxy far, far away...');
+      expect(fact.character).toBeUndefined();
+    });
+
+    it('maps faction 0 to JEDI_ORDER', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: { id: 10, starWarsQuote: 'The Force is strong — Yoda', faction: 0 },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+      expect(fact.faction).toBe(EStarWarsFaction.JEDI_ORDER);
+    });
+
+    it('maps faction 1 to SITH', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: { id: 11, starWarsQuote: 'The dark side — Palpatine', faction: 1 },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+      expect(fact.faction).toBe(EStarWarsFaction.SITH);
+    });
+
+    it('maps faction 3 to REBEL_ALLIANCE', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: { id: 12, starWarsQuote: 'May the Force be with you — Leia', faction: 3 },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+      expect(fact.faction).toBe(EStarWarsFaction.REBEL_ALLIANCE);
+    });
+
+    it('maps faction 2 and 4 to UNKNOWN', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: { id: 13, starWarsQuote: 'Beep boop — R2-D2', faction: 2 },
+        },
+        durationMs: 10,
+      });
+
+      const fact = await client.getFact();
+      expect(fact.faction).toBe(EStarWarsFaction.UNKNOWN);
+    });
+
+    it('generates a deterministic id from quote text', async () => {
+      const quoteText = 'Never tell me the odds! — Han Solo';
+      mockHandleRequest.mockResolvedValue({
+        response: { data: { id: 7, starWarsQuote: quoteText, faction: 4 } },
+        durationMs: 10,
+      });
+
+      const fact1 = await client.getFact();
+      const fact2 = await client.getFact();
+
+      expect(fact1.id).toBe(fact2.id);
+    });
+
+    it('calls handleRequest with GET /api/SWQuote/RandomStarWarsQuote', async () => {
+      mockHandleRequest.mockResolvedValueOnce({
+        response: {
+          data: { id: 1, starWarsQuote: 'A quote — Someone', faction: 0 },
+        },
+        durationMs: 10,
+      });
+
+      await client.getFact();
+
+      expect(mockHandleRequest).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote' }),
+        expect.objectContaining({ method: 'GET', url: '/api/SWQuote/RandomStarWarsQuote' })
+      );
+    });
+
+    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"]
+}