@thalorlabs/chucknorris 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# @thalorlabs/chucknorris
+# No environment variables required — api.chucknorris.io is free and unauthenticated.
+# This file exists for consistency with other provider packages.
+
+# Optional: Override the API base URL (e.g. for testing with a mock server)
+# CHUCK_NORRIS_BASE_URL=https://api.chucknorris.io

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "tabWidth": 2
+}

package/CLAUDE.md

@@ -0,0 +1,52 @@
+# @thalorlabs/chucknorris
+
+## What this repo is
+
+Provider adapter package for api.chucknorris.io. Calls one external API, normalises the response to `TLJoke`, and returns it. No DB, no cache, no logging.
+
+## Knowledge base
+
+Before writing any code, read:
+- TL-Coding vault: `knowledge/multi-provider-pattern.md`
+- TL-Coding vault: `examples/jokes/layer-provider-package.md`
+- TL-Coding vault: `context/packages.md`
+
+## External API
+
+- **API:** api.chucknorris.io
+- **Auth:** None
+- **Billable:** No
+- **Joke type:** Always SINGLE (one-liner)
+- **Category:** Always GENERAL
+
+## Build & publish
+
+```bash
+npm run build      # tsc → dist/
+npm test           # vitest
+npm version patch  # or minor/major
+npm publish --access public
+```
+
+## Folder structure
+
+```
+src/
+  index.ts               ← exports ChuckNorrisClient, CHUCK_NORRIS_CONFIG
+  ChuckNorrisClient.ts   ← HTTP adapter, normalises to TLJoke
+  ChuckNorrisTypes.ts    ← raw API types, local only, never exported
+tests/
+  ChuckNorrisClient.test.ts
+```
+
+## What this package does NOT do
+
+- No database access
+- No caching (orchestrator handles this)
+- No logging (orchestrator handles this)
+- Raw types (`ChuckNorrisRawResponse`) never exported, never in `@thalorlabs/types`
+- No provider selection logic — that's the orchestrator's job
+
+## Migration note
+
+When `@thalorlabs/api` is published, `ChuckNorrisClient` should extend `BaseHttpClient` instead of managing its own axios instance.

package/README.md

@@ -0,0 +1,44 @@
+# @thalorlabs/chucknorris
+
+Provider adapter for [api.chucknorris.io](https://api.chucknorris.io). Returns normalised `TLJoke` from `@thalorlabs/types`.
+
+## Installation
+
+```bash
+npm install @thalorlabs/chucknorris
+```
+
+## Usage
+
+```typescript
+import { ChuckNorrisClient, CHUCK_NORRIS_CONFIG } from '@thalorlabs/chucknorris';
+
+const client = new ChuckNorrisClient();
+const joke = await client.getJoke();
+// → TLJoke { id, type: 'SINGLE', joke: '...', category: 'GENERAL', safe: false, provider: 'chucknorris' }
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `baseURL` | `https://api.chucknorris.io` | API base URL |
+| `timeout` | `10000` | Request timeout (ms) |
+
+## Exported Config
+
+```typescript
+CHUCK_NORRIS_CONFIG = {
+  cacheTtlMs: 3600000,  // 1h
+  isBillable: false,
+}
+```
+
+## Scripts
+
+```bash
+npm run build          # tsc → dist/
+npm test               # vitest
+npm run lint           # eslint
+npm run format:check   # prettier
+```

package/dist/ChuckNorrisClient.d.ts

@@ -0,0 +1,21 @@
+import { TLJoke } from '@thalorlabs/types';
+export interface ChuckNorrisClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+/**
+ * HTTP adapter for api.chucknorris.io.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ *
+ * When @thalorlabs/api is available, this should extend BaseHttpClient
+ * instead of managing its own axios instance.
+ */
+export declare class ChuckNorrisClient {
+    readonly serviceName = "chucknorris";
+    private readonly axiosInstance;
+    constructor(config?: ChuckNorrisClientConfig);
+    getJoke(): Promise<TLJoke>;
+    private normalise;
+}

package/dist/ChuckNorrisClient.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChuckNorrisClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = require("crypto");
+const types_1 = require("@thalorlabs/types");
+/**
+ * HTTP adapter for api.chucknorris.io.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ *
+ * When @thalorlabs/api is available, this should extend BaseHttpClient
+ * instead of managing its own axios instance.
+ */
+class ChuckNorrisClient {
+    constructor(config = {}) {
+        this.serviceName = 'chucknorris';
+        this.axiosInstance = axios_1.default.create({
+            baseURL: config.baseURL ?? 'https://api.chucknorris.io',
+            timeout: config.timeout ?? 10000,
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+    }
+    async getJoke() {
+        const { data } = await this.axiosInstance.get('/jokes/random');
+        return this.normalise(data);
+    }
+    normalise(raw) {
+        return types_1.TLJoke.parse({
+            id: (0, crypto_1.createHash)('md5').update(raw.value).digest('hex'),
+            type: types_1.EJokeType.SINGLE,
+            joke: raw.value,
+            category: types_1.EJokeCategory.GENERAL,
+            safe: false, // Chuck Norris jokes can contain explicit content
+            provider: this.serviceName,
+        });
+    }
+}
+exports.ChuckNorrisClient = ChuckNorrisClient;

package/dist/ChuckNorrisTypes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Raw response from api.chucknorris.io.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface ChuckNorrisRawResponse {
+    icon_url: string;
+    id: string;
+    url: string;
+    value: string;
+}

package/dist/ChuckNorrisTypes.js

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ChuckNorrisClient, ChuckNorrisClientConfig, } from './ChuckNorrisClient';
+export declare const CHUCK_NORRIS_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHUCK_NORRIS_CONFIG = exports.ChuckNorrisClient = void 0;
+var ChuckNorrisClient_1 = require("./ChuckNorrisClient");
+Object.defineProperty(exports, "ChuckNorrisClient", { enumerable: true, get: function () { return ChuckNorrisClient_1.ChuckNorrisClient; } });
+exports.CHUCK_NORRIS_CONFIG = {
+    cacheTtlMs: 1000 * 60 * 60, // 1h
+    isBillable: false, // api.chucknorris.io is free
+};

package/eslint.config.mjs

@@ -0,0 +1,21 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-config-prettier';
+import nodePlugin from 'eslint-plugin-n';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  nodePlugin.configs['flat/recommended-module'],
+  prettier,
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      'n/no-missing-import': 'off',
+      'n/no-unpublished-import': 'off',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/'],
+  }
+);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@thalorlabs/chucknorris",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for api.chucknorris.io — returns TLJoke",
+  "homepage": "https://github.com/ThalorLabs/chucknorris#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/chucknorris/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/chucknorris.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": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.2",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^17.24.0",
+    "prettier": "^3.8.1",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@thalorlabs/types": "^1.7.0",
+    "axios": "^1.7.0"
+  }
+}

package/src/ChuckNorrisClient.ts

@@ -0,0 +1,50 @@
+import axios, { AxiosInstance } from 'axios';
+import { createHash } from 'crypto';
+import { TLJoke, EJokeType, EJokeCategory } from '@thalorlabs/types';
+import { ChuckNorrisRawResponse } from './ChuckNorrisTypes';
+
+export interface ChuckNorrisClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+/**
+ * HTTP adapter for api.chucknorris.io.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * No DB, no cache, no logging — pure HTTP adapter.
+ *
+ * When @thalorlabs/api is available, this should extend BaseHttpClient
+ * instead of managing its own axios instance.
+ */
+export class ChuckNorrisClient {
+  public readonly serviceName = 'chucknorris';
+  private readonly axiosInstance: AxiosInstance;
+
+  constructor(config: ChuckNorrisClientConfig = {}) {
+    this.axiosInstance = axios.create({
+      baseURL: config.baseURL ?? 'https://api.chucknorris.io',
+      timeout: config.timeout ?? 10000,
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  async getJoke(): Promise<TLJoke> {
+    const { data } =
+      await this.axiosInstance.get<ChuckNorrisRawResponse>('/jokes/random');
+    return this.normalise(data);
+  }
+
+  private normalise(raw: ChuckNorrisRawResponse): TLJoke {
+    return TLJoke.parse({
+      id: createHash('md5').update(raw.value).digest('hex'),
+      type: EJokeType.SINGLE,
+      joke: raw.value,
+      category: EJokeCategory.GENERAL,
+      safe: false, // Chuck Norris jokes can contain explicit content
+      provider: this.serviceName,
+    });
+  }
+}

package/src/ChuckNorrisTypes.ts

@@ -0,0 +1,12 @@
+/**
+ * Raw response from api.chucknorris.io.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface ChuckNorrisRawResponse {
+  icon_url: string;
+  id: string;
+  url: string;
+  value: string;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  ChuckNorrisClient,
+  ChuckNorrisClientConfig,
+} from './ChuckNorrisClient';
+
+export const CHUCK_NORRIS_CONFIG = {
+  cacheTtlMs: 1000 * 60 * 60, // 1h
+  isBillable: false, // api.chucknorris.io is free
+} as const;

package/tests/ChuckNorrisClient.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ChuckNorrisClient } from '../src/ChuckNorrisClient';
+import { EJokeType, EJokeCategory } from '@thalorlabs/types';
+import axios from 'axios';
+
+vi.mock('axios', () => {
+  const mockAxiosInstance = {
+    get: vi.fn(),
+  };
+  return {
+    default: {
+      create: vi.fn(() => mockAxiosInstance),
+    },
+  };
+});
+
+function getMockAxios() {
+  const instance = (axios.create as ReturnType<typeof vi.fn>).mock.results[0]
+    .value;
+  return instance.get as ReturnType<typeof vi.fn>;
+}
+
+describe('ChuckNorrisClient', () => {
+  let client: ChuckNorrisClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new ChuckNorrisClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to chucknorris', () => {
+      expect(client.serviceName).toBe('chucknorris');
+    });
+
+    it('creates axios instance with default config', () => {
+      expect(axios.create).toHaveBeenCalledWith({
+        baseURL: 'https://api.chucknorris.io',
+        timeout: 10000,
+        headers: { Accept: 'application/json' },
+      });
+    });
+
+    it('accepts custom baseURL and timeout', () => {
+      vi.clearAllMocks();
+      new ChuckNorrisClient({
+        baseURL: 'http://localhost:3000',
+        timeout: 5000,
+      });
+      expect(axios.create).toHaveBeenCalledWith({
+        baseURL: 'http://localhost:3000',
+        timeout: 5000,
+        headers: { Accept: 'application/json' },
+      });
+    });
+  });
+
+  describe('getJoke', () => {
+    it('returns a valid TLJoke with SINGLE type and GENERAL category', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          icon_url: 'https://api.chucknorris.io/img/avatar/chuck-norris.png',
+          id: 'abc123',
+          url: '',
+          value: 'Chuck Norris can divide by zero.',
+        },
+      });
+
+      const joke = await client.getJoke();
+
+      expect(joke.type).toBe(EJokeType.SINGLE);
+      expect(joke.category).toBe(EJokeCategory.GENERAL);
+      expect(joke.joke).toBe('Chuck Norris can divide by zero.');
+      expect(joke.safe).toBe(false);
+      expect(joke.provider).toBe('chucknorris');
+      expect(joke.id).toBeDefined();
+    });
+
+    it('generates a deterministic id from joke text', async () => {
+      const mockGet = getMockAxios();
+      const jokeText = 'Test joke';
+      mockGet.mockResolvedValue({
+        data: {
+          icon_url: 'https://example.com/icon.png',
+          id: 'raw-id',
+          url: '',
+          value: jokeText,
+        },
+      });
+
+      const joke1 = await client.getJoke();
+      const joke2 = await client.getJoke();
+
+      expect(joke1.id).toBe(joke2.id);
+    });
+
+    it('calls GET /jokes/random on the API', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          icon_url: '',
+          id: 'abc',
+          url: '',
+          value: 'A joke',
+        },
+      });
+
+      await client.getJoke();
+
+      expect(mockGet).toHaveBeenCalledWith('/jokes/random');
+    });
+
+    it('propagates API errors', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(client.getJoke()).rejects.toThrow('Network error');
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}