@thalorlabs/dadjoke 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# @thalorlabs/dadjoke
+# No environment variables required — icanhazdadjoke.com 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)
+# DAD_JOKE_BASE_URL=https://icanhazdadjoke.com

package/.prettierrc

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

package/CLAUDE.md

@@ -0,0 +1,52 @@
+# @thalorlabs/dadjoke
+
+## What this repo is
+
+Provider adapter package for icanhazdadjoke.com. 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:** icanhazdadjoke.com
+- **Auth:** None
+- **Billable:** No
+- **Joke type:** Always SINGLE (one-liner)
+- **Category:** Always DAD
+
+## 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 DadJokeClient, DAD_JOKE_CONFIG
+  DadJokeClient.ts   ← HTTP adapter, normalises to TLJoke
+  DadJokeTypes.ts    ← raw API types, local only, never exported
+tests/
+  DadJokeClient.test.ts
+```
+
+## What this package does NOT do
+
+- No database access
+- No caching (orchestrator handles this)
+- No logging (orchestrator handles this)
+- Raw types (`DadJokeRawResponse`) never exported, never in `@thalorlabs/types`
+- No provider selection logic — that's the orchestrator's job
+
+## Migration note
+
+When `@thalorlabs/api` is published, `DadJokeClient` should extend `BaseHttpClient` instead of managing its own axios instance. This gives us retry logic, exponential backoff, and observability for free.

package/README.md

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

package/dist/DadJokeClient.d.ts

@@ -0,0 +1,21 @@
+import { TLJoke } from '@thalorlabs/types';
+export interface DadJokeClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+/**
+ * HTTP adapter for icanhazdadjoke.com.
+ *
+ * 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 DadJokeClient {
+    readonly serviceName = "dadjoke";
+    private readonly axiosInstance;
+    constructor(config?: DadJokeClientConfig);
+    getJoke(): Promise<TLJoke>;
+    private normalise;
+}

package/dist/DadJokeClient.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.DadJokeClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = require("crypto");
+const types_1 = require("@thalorlabs/types");
+/**
+ * HTTP adapter for icanhazdadjoke.com.
+ *
+ * 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 DadJokeClient {
+    constructor(config = {}) {
+        this.serviceName = 'dadjoke';
+        this.axiosInstance = axios_1.default.create({
+            baseURL: config.baseURL ?? 'https://icanhazdadjoke.com',
+            timeout: config.timeout ?? 10000,
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+    }
+    async getJoke() {
+        const { data } = await this.axiosInstance.get('/');
+        return this.normalise(data);
+    }
+    normalise(raw) {
+        return types_1.TLJoke.parse({
+            id: (0, crypto_1.createHash)('md5').update(raw.joke).digest('hex'),
+            type: types_1.EJokeType.SINGLE,
+            joke: raw.joke,
+            category: types_1.EJokeCategory.DAD,
+            safe: true,
+            provider: this.serviceName,
+        });
+    }
+}
+exports.DadJokeClient = DadJokeClient;

package/dist/DadJokeTypes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raw response from icanhazdadjoke.com API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface DadJokeRawResponse {
+    id: string;
+    joke: string;
+    status: number;
+}

package/dist/DadJokeTypes.js

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { DadJokeClient, DadJokeClientConfig } from './DadJokeClient';
+export declare const DAD_JOKE_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAD_JOKE_CONFIG = exports.DadJokeClient = void 0;
+var DadJokeClient_1 = require("./DadJokeClient");
+Object.defineProperty(exports, "DadJokeClient", { enumerable: true, get: function () { return DadJokeClient_1.DadJokeClient; } });
+exports.DAD_JOKE_CONFIG = {
+    cacheTtlMs: 1000 * 60 * 60 * 24, // 24h — jokes don't change
+    isBillable: false, // icanhazdadjoke 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', // TypeScript handles this
+      'n/no-unpublished-import': 'off',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/'],
+  }
+);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@thalorlabs/dadjoke",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Provider adapter for icanhazdadjoke.com — returns TLJoke",
+  "homepage": "https://github.com/ThalorLabs/dadjoke#readme",
+  "bugs": {
+    "url": "https://github.com/ThalorLabs/dadjoke/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThalorLabs/dadjoke.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/DadJokeClient.ts

@@ -0,0 +1,49 @@
+import axios, { AxiosInstance } from 'axios';
+import { createHash } from 'crypto';
+import { TLJoke, EJokeType, EJokeCategory } from '@thalorlabs/types';
+import { DadJokeRawResponse } from './DadJokeTypes';
+
+export interface DadJokeClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+/**
+ * HTTP adapter for icanhazdadjoke.com.
+ *
+ * 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 DadJokeClient {
+  public readonly serviceName = 'dadjoke';
+  private readonly axiosInstance: AxiosInstance;
+
+  constructor(config: DadJokeClientConfig = {}) {
+    this.axiosInstance = axios.create({
+      baseURL: config.baseURL ?? 'https://icanhazdadjoke.com',
+      timeout: config.timeout ?? 10000,
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  async getJoke(): Promise<TLJoke> {
+    const { data } = await this.axiosInstance.get<DadJokeRawResponse>('/');
+    return this.normalise(data);
+  }
+
+  private normalise(raw: DadJokeRawResponse): TLJoke {
+    return TLJoke.parse({
+      id: createHash('md5').update(raw.joke).digest('hex'),
+      type: EJokeType.SINGLE,
+      joke: raw.joke,
+      category: EJokeCategory.DAD,
+      safe: true,
+      provider: this.serviceName,
+    });
+  }
+}

package/src/DadJokeTypes.ts

@@ -0,0 +1,11 @@
+/**
+ * Raw response from icanhazdadjoke.com API.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface DadJokeRawResponse {
+  id: string;
+  joke: string;
+  status: number;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { DadJokeClient, DadJokeClientConfig } from './DadJokeClient';
+
+export const DAD_JOKE_CONFIG = {
+  cacheTtlMs: 1000 * 60 * 60 * 24, // 24h — jokes don't change
+  isBillable: false, // icanhazdadjoke is free
+} as const;

package/tests/DadJokeClient.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { DadJokeClient } from '../src/DadJokeClient';
+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('DadJokeClient', () => {
+  let client: DadJokeClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new DadJokeClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to dadjoke', () => {
+      expect(client.serviceName).toBe('dadjoke');
+    });
+
+    it('creates axios instance with default config', () => {
+      expect(axios.create).toHaveBeenCalledWith({
+        baseURL: 'https://icanhazdadjoke.com',
+        timeout: 10000,
+        headers: { Accept: 'application/json' },
+      });
+    });
+
+    it('accepts custom baseURL and timeout', () => {
+      vi.clearAllMocks();
+      new DadJokeClient({ 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 DAD category', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          id: 'abc123',
+          joke: 'Why did the scarecrow win an award? He was outstanding in his field.',
+          status: 200,
+        },
+      });
+
+      const joke = await client.getJoke();
+
+      expect(joke.type).toBe(EJokeType.SINGLE);
+      expect(joke.category).toBe(EJokeCategory.DAD);
+      expect(joke.joke).toBe(
+        'Why did the scarecrow win an award? He was outstanding in his field.'
+      );
+      expect(joke.safe).toBe(true);
+      expect(joke.provider).toBe('dadjoke');
+      expect(joke.id).toBeDefined();
+    });
+
+    it('generates a deterministic id from joke text', async () => {
+      const mockGet = getMockAxios();
+      const jokeText = 'Test joke';
+      mockGet.mockResolvedValue({
+        data: { id: 'raw-id', joke: jokeText, status: 200 },
+      });
+
+      const joke1 = await client.getJoke();
+      const joke2 = await client.getJoke();
+
+      expect(joke1.id).toBe(joke2.id);
+    });
+
+    it('calls GET / on the API', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: { id: 'abc', joke: 'A joke', status: 200 },
+      });
+
+      await client.getJoke();
+
+      expect(mockGet).toHaveBeenCalledWith('/');
+    });
+
+    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"]
+}