@thalorlabs/jokeapi 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# @thalorlabs/jokeapi
+# No environment variables required — v2.jokeapi.dev 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)
+# JOKE_API_BASE_URL=https://v2.jokeapi.dev

package/.prettierrc

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

package/CLAUDE.md

@@ -0,0 +1,53 @@
+# @thalorlabs/jokeapi
+
+## What this repo is
+
+Provider adapter package for v2.jokeapi.dev. 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:** v2.jokeapi.dev
+- **Auth:** None
+- **Billable:** No
+- **Joke types:** SINGLE and TWOPART
+- **Categories:** Programming, Dark, Pun, Spooky, Christmas, Misc
+- **Safe mode:** Supported via `safe` query param
+
+## 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 JokeApiClient, JOKE_API_CONFIG
+  JokeApiClient.ts    ← HTTP adapter, normalises to TLJoke
+  JokeApiTypes.ts     ← raw API types, local only, never exported
+tests/
+  JokeApiClient.test.ts
+```
+
+## What this package does NOT do
+
+- No database access
+- No caching (orchestrator handles this)
+- No logging (orchestrator handles this)
+- Raw types never exported, never in `@thalorlabs/types`
+- No provider selection logic — that's the orchestrator's job
+
+## Migration note
+
+When `@thalorlabs/api` is published, `JokeApiClient` should extend `BaseHttpClient` instead of managing its own axios instance.

package/README.md

@@ -0,0 +1,62 @@
+# @thalorlabs/jokeapi
+
+Provider adapter for [v2.jokeapi.dev](https://v2.jokeapi.dev). Returns normalised `TLJoke` from `@thalorlabs/types`. Supports both single and twopart jokes with category filtering and safe mode.
+
+## Installation
+
+```bash
+npm install @thalorlabs/jokeapi
+```
+
+## Usage
+
+```typescript
+import { JokeApiClient, JOKE_API_CONFIG } from '@thalorlabs/jokeapi';
+import { EJokeCategory, EJokeType } from '@thalorlabs/types';
+
+const client = new JokeApiClient();
+
+// Random joke
+const joke = await client.getJoke();
+
+// Filtered by category and type
+const progJoke = await client.getJoke({
+  category: EJokeCategory.PROGRAMMING,
+  type: EJokeType.TWOPART,
+  safe: true,
+});
+// → TLJoke { id, type: 'TWOPART', setup: '...', delivery: '...', category: 'PROGRAMMING', safe: true, provider: 'jokeapi' }
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `baseURL` | `https://v2.jokeapi.dev` | API base URL |
+| `timeout` | `10000` | Request timeout (ms) |
+
+## Query Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `category` | `EJokeCategory` | Filter by category (PROGRAMMING, DARK, PUN, SPOOKY, CHRISTMAS, GENERAL) |
+| `type` | `EJokeType` | Filter by type (SINGLE, TWOPART) |
+| `safe` | `boolean` | Only return safe jokes |
+
+## Exported Config
+
+```typescript
+JOKE_API_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/JokeApiClient.d.ts

@@ -0,0 +1,27 @@
+import { TLJoke, EJokeType, EJokeCategory } from '@thalorlabs/types';
+export interface JokeApiClientConfig {
+    baseURL?: string;
+    timeout?: number;
+}
+export interface JokeApiQueryParams {
+    category?: EJokeCategory;
+    type?: EJokeType;
+    safe?: boolean;
+}
+/**
+ * HTTP adapter for v2.jokeapi.dev.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * Supports both single and twopart jokes, category filtering, and safe mode.
+ * 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 JokeApiClient {
+    readonly serviceName = "jokeapi";
+    private readonly axiosInstance;
+    constructor(config?: JokeApiClientConfig);
+    getJoke(params?: JokeApiQueryParams): Promise<TLJoke>;
+    private normalise;
+}

package/dist/JokeApiClient.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JokeApiClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = require("crypto");
+const types_1 = require("@thalorlabs/types");
+/** Maps TL categories to JokeAPI v2 category strings. */
+const CATEGORY_MAP = {
+    [types_1.EJokeCategory.PROGRAMMING]: 'Programming',
+    [types_1.EJokeCategory.DARK]: 'Dark',
+    [types_1.EJokeCategory.PUN]: 'Pun',
+    [types_1.EJokeCategory.SPOOKY]: 'Spooky',
+    [types_1.EJokeCategory.CHRISTMAS]: 'Christmas',
+    [types_1.EJokeCategory.GENERAL]: 'Misc',
+    [types_1.EJokeCategory.DAD]: 'Misc',
+};
+/** Maps JokeAPI v2 category strings back to TL categories. */
+const REVERSE_CATEGORY_MAP = {
+    Programming: types_1.EJokeCategory.PROGRAMMING,
+    Dark: types_1.EJokeCategory.DARK,
+    Pun: types_1.EJokeCategory.PUN,
+    Spooky: types_1.EJokeCategory.SPOOKY,
+    Christmas: types_1.EJokeCategory.CHRISTMAS,
+    Misc: types_1.EJokeCategory.GENERAL,
+};
+/**
+ * HTTP adapter for v2.jokeapi.dev.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * Supports both single and twopart jokes, category filtering, and safe mode.
+ * 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 JokeApiClient {
+    constructor(config = {}) {
+        this.serviceName = 'jokeapi';
+        this.axiosInstance = axios_1.default.create({
+            baseURL: config.baseURL ?? 'https://v2.jokeapi.dev',
+            timeout: config.timeout ?? 10000,
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+    }
+    async getJoke(params = {}) {
+        const category = params.category
+            ? (CATEGORY_MAP[params.category] ?? 'Any')
+            : 'Any';
+        const queryParams = {};
+        if (params.type) {
+            queryParams.type =
+                params.type === types_1.EJokeType.SINGLE ? 'single' : 'twopart';
+        }
+        if (params.safe) {
+            queryParams.safe = 'true';
+        }
+        const { data } = await this.axiosInstance.get(`/joke/${category}`, { params: queryParams });
+        if (data.error) {
+            throw new Error(`JokeAPI error: ${data.message}`);
+        }
+        return this.normalise(data);
+    }
+    normalise(raw) {
+        const resolvedCategory = REVERSE_CATEGORY_MAP[raw.category] ?? types_1.EJokeCategory.GENERAL;
+        if (raw.type === 'twopart') {
+            return types_1.TLJoke.parse({
+                id: (0, crypto_1.createHash)('md5')
+                    .update(raw.setup + raw.delivery)
+                    .digest('hex'),
+                type: types_1.EJokeType.TWOPART,
+                setup: raw.setup,
+                delivery: raw.delivery,
+                category: resolvedCategory,
+                safe: raw.safe,
+                provider: this.serviceName,
+            });
+        }
+        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: resolvedCategory,
+            safe: raw.safe,
+            provider: this.serviceName,
+        });
+    }
+}
+exports.JokeApiClient = JokeApiClient;

package/dist/JokeApiTypes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Raw response types from v2.jokeapi.dev.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+export interface JokeApiFlags {
+    nsfw: boolean;
+    religious: boolean;
+    political: boolean;
+    racist: boolean;
+    sexist: boolean;
+    explicit: boolean;
+}
+export interface JokeApiSingleRaw {
+    error: false;
+    category: string;
+    type: 'single';
+    joke: string;
+    flags: JokeApiFlags;
+    id: number;
+    safe: boolean;
+    lang: string;
+}
+export interface JokeApiTwoPartRaw {
+    error: false;
+    category: string;
+    type: 'twopart';
+    setup: string;
+    delivery: string;
+    flags: JokeApiFlags;
+    id: number;
+    safe: boolean;
+    lang: string;
+}
+export type JokeApiRawResponse = JokeApiSingleRaw | JokeApiTwoPartRaw;
+export interface JokeApiErrorResponse {
+    error: true;
+    internalError: boolean;
+    code: number;
+    message: string;
+    causedBy: string[];
+    additionalInfo: string;
+    timestamp: number;
+}

package/dist/JokeApiTypes.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Raw response types from v2.jokeapi.dev.
+ *
+ * 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 { JokeApiClient, JokeApiClientConfig, JokeApiQueryParams, } from './JokeApiClient';
+export declare const JOKE_API_CONFIG: {
+    readonly cacheTtlMs: number;
+    readonly isBillable: false;
+};

package/dist/index.js

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

@@ -0,0 +1,118 @@
+import axios, { AxiosInstance } from 'axios';
+import { createHash } from 'crypto';
+import { TLJoke, EJokeType, EJokeCategory } from '@thalorlabs/types';
+import { JokeApiRawResponse, JokeApiErrorResponse } from './JokeApiTypes';
+
+export interface JokeApiClientConfig {
+  baseURL?: string;
+  timeout?: number;
+}
+
+export interface JokeApiQueryParams {
+  category?: EJokeCategory;
+  type?: EJokeType;
+  safe?: boolean;
+}
+
+/** Maps TL categories to JokeAPI v2 category strings. */
+const CATEGORY_MAP: Partial<Record<EJokeCategory, string>> = {
+  [EJokeCategory.PROGRAMMING]: 'Programming',
+  [EJokeCategory.DARK]: 'Dark',
+  [EJokeCategory.PUN]: 'Pun',
+  [EJokeCategory.SPOOKY]: 'Spooky',
+  [EJokeCategory.CHRISTMAS]: 'Christmas',
+  [EJokeCategory.GENERAL]: 'Misc',
+  [EJokeCategory.DAD]: 'Misc',
+};
+
+/** Maps JokeAPI v2 category strings back to TL categories. */
+const REVERSE_CATEGORY_MAP: Record<string, EJokeCategory> = {
+  Programming: EJokeCategory.PROGRAMMING,
+  Dark: EJokeCategory.DARK,
+  Pun: EJokeCategory.PUN,
+  Spooky: EJokeCategory.SPOOKY,
+  Christmas: EJokeCategory.CHRISTMAS,
+  Misc: EJokeCategory.GENERAL,
+};
+
+/**
+ * HTTP adapter for v2.jokeapi.dev.
+ *
+ * Calls the external API and normalises the raw response to TLJoke.
+ * Supports both single and twopart jokes, category filtering, and safe mode.
+ * 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 JokeApiClient {
+  public readonly serviceName = 'jokeapi';
+  private readonly axiosInstance: AxiosInstance;
+
+  constructor(config: JokeApiClientConfig = {}) {
+    this.axiosInstance = axios.create({
+      baseURL: config.baseURL ?? 'https://v2.jokeapi.dev',
+      timeout: config.timeout ?? 10000,
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  async getJoke(params: JokeApiQueryParams = {}): Promise<TLJoke> {
+    const category = params.category
+      ? (CATEGORY_MAP[params.category] ?? 'Any')
+      : 'Any';
+
+    const queryParams: Record<string, string> = {};
+
+    if (params.type) {
+      queryParams.type =
+        params.type === EJokeType.SINGLE ? 'single' : 'twopart';
+    }
+
+    if (params.safe) {
+      queryParams.safe = 'true';
+    }
+
+    const { data } = await this.axiosInstance.get<
+      JokeApiRawResponse | JokeApiErrorResponse
+    >(`/joke/${category}`, { params: queryParams });
+
+    if (data.error) {
+      throw new Error(
+        `JokeAPI error: ${(data as JokeApiErrorResponse).message}`
+      );
+    }
+
+    return this.normalise(data as JokeApiRawResponse);
+  }
+
+  private normalise(raw: JokeApiRawResponse): TLJoke {
+    const resolvedCategory =
+      REVERSE_CATEGORY_MAP[raw.category] ?? EJokeCategory.GENERAL;
+
+    if (raw.type === 'twopart') {
+      return TLJoke.parse({
+        id: createHash('md5')
+          .update(raw.setup + raw.delivery)
+          .digest('hex'),
+        type: EJokeType.TWOPART,
+        setup: raw.setup,
+        delivery: raw.delivery,
+        category: resolvedCategory,
+        safe: raw.safe,
+        provider: this.serviceName,
+      });
+    }
+
+    return TLJoke.parse({
+      id: createHash('md5').update(raw.joke).digest('hex'),
+      type: EJokeType.SINGLE,
+      joke: raw.joke,
+      category: resolvedCategory,
+      safe: raw.safe,
+      provider: this.serviceName,
+    });
+  }
+}

package/src/JokeApiTypes.ts

@@ -0,0 +1,50 @@
+/**
+ * Raw response types from v2.jokeapi.dev.
+ *
+ * Internal to this package only — never exported from index.ts,
+ * never added to @thalorlabs/types.
+ */
+
+export interface JokeApiFlags {
+  nsfw: boolean;
+  religious: boolean;
+  political: boolean;
+  racist: boolean;
+  sexist: boolean;
+  explicit: boolean;
+}
+
+export interface JokeApiSingleRaw {
+  error: false;
+  category: string;
+  type: 'single';
+  joke: string;
+  flags: JokeApiFlags;
+  id: number;
+  safe: boolean;
+  lang: string;
+}
+
+export interface JokeApiTwoPartRaw {
+  error: false;
+  category: string;
+  type: 'twopart';
+  setup: string;
+  delivery: string;
+  flags: JokeApiFlags;
+  id: number;
+  safe: boolean;
+  lang: string;
+}
+
+export type JokeApiRawResponse = JokeApiSingleRaw | JokeApiTwoPartRaw;
+
+export interface JokeApiErrorResponse {
+  error: true;
+  internalError: boolean;
+  code: number;
+  message: string;
+  causedBy: string[];
+  additionalInfo: string;
+  timestamp: number;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+  JokeApiClient,
+  JokeApiClientConfig,
+  JokeApiQueryParams,
+} from './JokeApiClient';
+
+export const JOKE_API_CONFIG = {
+  cacheTtlMs: 1000 * 60 * 60, // 1h
+  isBillable: false, // jokeapi.dev is free
+} as const;

package/tests/JokeApiClient.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { JokeApiClient } from '../src/JokeApiClient';
+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('JokeApiClient', () => {
+  let client: JokeApiClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new JokeApiClient();
+  });
+
+  describe('constructor', () => {
+    it('sets serviceName to jokeapi', () => {
+      expect(client.serviceName).toBe('jokeapi');
+    });
+
+    it('creates axios instance with default config', () => {
+      expect(axios.create).toHaveBeenCalledWith({
+        baseURL: 'https://v2.jokeapi.dev',
+        timeout: 10000,
+        headers: { Accept: 'application/json' },
+      });
+    });
+  });
+
+  describe('getJoke — single joke', () => {
+    it('normalises a single joke to TLJoke', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: false,
+          category: 'Programming',
+          type: 'single',
+          joke: 'A SQL query walks into a bar, walks up to two tables and asks... can I join you?',
+          flags: {
+            nsfw: false,
+            religious: false,
+            political: false,
+            racist: false,
+            sexist: false,
+            explicit: false,
+          },
+          id: 42,
+          safe: true,
+          lang: 'en',
+        },
+      });
+
+      const joke = await client.getJoke();
+
+      expect(joke.type).toBe(EJokeType.SINGLE);
+      expect(joke.category).toBe(EJokeCategory.PROGRAMMING);
+      expect(joke.joke).toBeDefined();
+      expect(joke.setup).toBeUndefined();
+      expect(joke.delivery).toBeUndefined();
+      expect(joke.safe).toBe(true);
+      expect(joke.provider).toBe('jokeapi');
+    });
+  });
+
+  describe('getJoke — twopart joke', () => {
+    it('normalises a twopart joke to TLJoke', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: false,
+          category: 'Programming',
+          type: 'twopart',
+          setup: 'Why do programmers prefer dark mode?',
+          delivery: 'Because light attracts bugs.',
+          flags: {
+            nsfw: false,
+            religious: false,
+            political: false,
+            racist: false,
+            sexist: false,
+            explicit: false,
+          },
+          id: 58,
+          safe: true,
+          lang: 'en',
+        },
+      });
+
+      const joke = await client.getJoke();
+
+      expect(joke.type).toBe(EJokeType.TWOPART);
+      expect(joke.setup).toBe('Why do programmers prefer dark mode?');
+      expect(joke.delivery).toBe('Because light attracts bugs.');
+      expect(joke.joke).toBeUndefined();
+      expect(joke.category).toBe(EJokeCategory.PROGRAMMING);
+      expect(joke.provider).toBe('jokeapi');
+    });
+  });
+
+  describe('getJoke — category mapping', () => {
+    it('maps PROGRAMMING category to Programming endpoint', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: false,
+          category: 'Programming',
+          type: 'single',
+          joke: 'A joke',
+          flags: {
+            nsfw: false,
+            religious: false,
+            political: false,
+            racist: false,
+            sexist: false,
+            explicit: false,
+          },
+          id: 1,
+          safe: true,
+          lang: 'en',
+        },
+      });
+
+      await client.getJoke({ category: EJokeCategory.PROGRAMMING });
+
+      expect(mockGet).toHaveBeenCalledWith('/joke/Programming', { params: {} });
+    });
+
+    it('uses Any when no category specified', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: false,
+          category: 'Misc',
+          type: 'single',
+          joke: 'A joke',
+          flags: {
+            nsfw: false,
+            religious: false,
+            political: false,
+            racist: false,
+            sexist: false,
+            explicit: false,
+          },
+          id: 1,
+          safe: true,
+          lang: 'en',
+        },
+      });
+
+      await client.getJoke();
+
+      expect(mockGet).toHaveBeenCalledWith('/joke/Any', { params: {} });
+    });
+  });
+
+  describe('getJoke — safe mode', () => {
+    it('passes safe=true query param when requested', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: false,
+          category: 'Misc',
+          type: 'single',
+          joke: 'A joke',
+          flags: {
+            nsfw: false,
+            religious: false,
+            political: false,
+            racist: false,
+            sexist: false,
+            explicit: false,
+          },
+          id: 1,
+          safe: true,
+          lang: 'en',
+        },
+      });
+
+      await client.getJoke({ safe: true });
+
+      expect(mockGet).toHaveBeenCalledWith('/joke/Any', {
+        params: { safe: 'true' },
+      });
+    });
+  });
+
+  describe('getJoke — error handling', () => {
+    it('throws on JokeAPI error response', async () => {
+      const mockGet = getMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          error: true,
+          internalError: false,
+          code: 106,
+          message: 'No matching joke found',
+          causedBy: ['No jokes found'],
+          additionalInfo: '',
+          timestamp: Date.now(),
+        },
+      });
+
+      await expect(client.getJoke()).rejects.toThrow(
+        'JokeAPI error: No matching joke found'
+      );
+    });
+
+    it('propagates network 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"]
+}