@ffflorian/icanhazdadjoke 2.4.6 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # ICanHazDadJoke [![npm version](https://img.shields.io/npm/v/@ffflorian/icanhazdadjoke.svg)](https://www.npmjs.com/package/@ffflorian/icanhazdadjoke)
 
-An [ICanHazDadJoke](https://icanhazdadjoke.com) API client with a CLI.
+An [ICanHazDadJoke](https://icanhazdadjoke.com) API client with a CLI. For a documentation on the API see [the icanhazdadjoke API reference](https://icanhazdadjoke.com/api).
 
 ## Usage
 

package/dist/ICanHazDadJoke.d.ts

@@ -0,0 +1,13 @@
+import type { ClientOptions } from './Interfaces';
+import { ICanHazDadJokeAPI } from './ICanHazDadJokeAPI';
+export declare class ICanHazDadJoke {
+    readonly api: ICanHazDadJokeAPI;
+    private readonly apiClient;
+    private readonly options;
+    constructor(options?: ClientOptions);
+    /**
+     * Set a new API URL.
+     * @param url The new API URL.
+     */
+    setApiUrl(url: string): void;
+}

package/dist/ICanHazDadJoke.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICanHazDadJoke = void 0;
+const api_client_1 = require("@ffflorian/api-client");
+const ICanHazDadJokeAPI_1 = require("./ICanHazDadJokeAPI");
+class ICanHazDadJoke {
+    constructor(options) {
+        this.options = Object.assign({ apiUrl: 'https://icanhazdadjoke.com' }, options);
+        this.apiClient = new api_client_1.APIClient(this.options.apiUrl, {
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': 'icanhazdadjoke.com API Client (https://github.com/ffflorian/api-clients/tree/main/packages/icanhazdadjoke)',
+            },
+        });
+        this.api = new ICanHazDadJokeAPI_1.ICanHazDadJokeAPI(this.apiClient, this.options);
+    }
+    /**
+     * Set a new API URL.
+     * @param url The new API URL.
+     */
+    setApiUrl(url) {
+        this.apiClient.setBaseURL(url);
+    }
+}
+exports.ICanHazDadJoke = ICanHazDadJoke;

package/dist/ICanHazDadJokeAPI.d.ts

@@ -0,0 +1,49 @@
+import type { APIClient } from '@ffflorian/api-client';
+import type { ClientOptions, GraphQLResponse, JokeResult, JokeResultWithImage, JokeSearchResult, RequestOptions, SearchOptions, SlackJokeResult } from './Interfaces';
+export declare class ICanHazDadJokeAPI {
+    protected readonly apiClient: APIClient;
+    protected readonly options: ClientOptions;
+    constructor(apiClient: APIClient, options: ClientOptions);
+    /**
+     * Fetch a dad joke by ID.
+     * @see https://icanhazdadjoke.com/api#fetch-a-dad-joke
+     */
+    getById(id: string, options: {
+        withImage: true;
+    }): Promise<JokeResultWithImage>;
+    getById(id: string, options?: RequestOptions): Promise<JokeResult>;
+    /**
+     * Fetch a dad joke by ID.
+     * @see https://icanhazdadjoke.com/api#fetch-a-dad-joke
+     */
+    getByID(id: string, options: {
+        withImage: true;
+    }): Promise<JokeResultWithImage>;
+    getByID(id: string, options?: RequestOptions): Promise<JokeResult>;
+    /**
+     * Fetch a random dad joke.
+     * @see https://icanhazdadjoke.com/api#fetch-a-random-dad-joke
+     */
+    getRandom(options: {
+        withImage: true;
+    }): Promise<JokeResultWithImage>;
+    getRandom(options?: RequestOptions): Promise<JokeResult>;
+    /**
+     * Fetch a random dad joke as a Slack message.
+     * @see https://icanhazdadjoke.com/api#fetch-a-random-dad-joke-as-a-slack-message
+     */
+    getSlack(): Promise<SlackJokeResult>;
+    /**
+     * Execute a GraphQL query.
+     * @see https://icanhazdadjoke.com/api#graphql
+     */
+    graphql(query: string): Promise<GraphQLResponse>;
+    /**
+     * Search for dad jokes.
+     * @param options Search options (default: list all jokes)
+     * @see https://icanhazdadjoke.com/api#search-for-dad-jokes
+     */
+    search(options: SearchOptions): Promise<JokeSearchResult>;
+    search(query: string, options?: Omit<SearchOptions, 'term'>): Promise<JokeSearchResult>;
+    private getImage;
+}

package/dist/ICanHazDadJokeAPI.js

@@ -0,0 +1,89 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICanHazDadJokeAPI = void 0;
+const MIN_SEARCH_LIMIT = 1;
+const MAX_SEARCH_LIMIT = 30;
+class ICanHazDadJokeAPI {
+    constructor(apiClient, options) {
+        this.apiClient = apiClient;
+        this.options = options;
+    }
+    getById(id, options = {}) {
+        return this.getByID(id, options);
+    }
+    getByID(id_1) {
+        return __awaiter(this, arguments, void 0, function* (id, options = {}) {
+            const { data: metaData } = yield this.apiClient.get(`/j/${id}`);
+            if (options.withImage) {
+                const imageData = yield this.getImage(`/j/${id}.png`);
+                return Object.assign(Object.assign({}, metaData), { image: imageData });
+            }
+            return metaData;
+        });
+    }
+    getRandom() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const { data: metaData } = yield this.apiClient.get('/');
+            if (options.withImage) {
+                const imageData = yield this.getImage(`/j/${metaData.id}.png`);
+                return Object.assign(Object.assign({}, metaData), { image: imageData });
+            }
+            return metaData;
+        });
+    }
+    /**
+     * Fetch a random dad joke as a Slack message.
+     * @see https://icanhazdadjoke.com/api#fetch-a-random-dad-joke-as-a-slack-message
+     */
+    getSlack() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.apiClient.get('/slack');
+            return data;
+        });
+    }
+    /**
+     * Execute a GraphQL query.
+     * @see https://icanhazdadjoke.com/api#graphql
+     */
+    graphql(query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.apiClient.post('/graphql', { query });
+            return data;
+        });
+    }
+    search(query_1) {
+        return __awaiter(this, arguments, void 0, function* (query, options = {}) {
+            if (typeof query === 'string') {
+                options.term = query;
+            }
+            if (options.limit !== undefined && (options.limit < MIN_SEARCH_LIMIT || options.limit > MAX_SEARCH_LIMIT)) {
+                throw new Error(`The search limit must be between ${MIN_SEARCH_LIMIT} and ${MAX_SEARCH_LIMIT}, got ${options.limit}.`);
+            }
+            const { data } = yield this.apiClient.get('/search', {
+                params: options,
+            });
+            return data;
+        });
+    }
+    getImage(imageUrl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.apiClient.get(imageUrl, {
+                headers: {
+                    Accept: 'image/png',
+                },
+                responseType: 'arraybuffer',
+            });
+            return data;
+        });
+    }
+}
+exports.ICanHazDadJokeAPI = ICanHazDadJokeAPI;

package/dist/Interfaces.d.ts

@@ -0,0 +1,54 @@
+export interface ClientOptions {
+    apiUrl?: string;
+}
+export interface GraphQLData {
+    joke: GraphQLJokeResult;
+}
+export interface GraphQLJokeResult {
+    id: string;
+    joke: string;
+    permalink: string;
+}
+export interface GraphQLResponse {
+    data: GraphQLData;
+}
+export interface JokeResult {
+    id: string;
+    joke: string;
+    status: number;
+}
+export interface JokeResultWithImage extends JokeResult {
+    image: Buffer;
+}
+export interface JokeSearchResult {
+    current_page: number;
+    limit: number;
+    next_page: number;
+    previous_page: number;
+    results: JokeResult[];
+    search_term: string;
+    status: number;
+    total_jokes: number;
+    total_pages: number;
+}
+export interface RequestOptions {
+    withImage?: boolean;
+}
+export interface SearchOptions {
+    /** number of results to return per page (default: 20) (max: 30) */
+    limit?: number;
+    /** which page of results to fetch (default: 1) */
+    page?: number;
+    /** search term to use (default: list all jokes) */
+    term?: string;
+}
+export interface SlackAttachment {
+    fallback: string;
+    footer: string;
+    text: string;
+}
+export interface SlackJokeResult {
+    attachments: SlackAttachment[];
+    response_type: string;
+    username: string;
+}

package/dist/Interfaces.js

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const package_json_1 = require("../package.json");
+const _1 = require("./");
+function init() {
+    return __awaiter(this, arguments, void 0, function* (dir = '.') {
+        const resolvedPath = path.resolve(dir);
+        try {
+            yield node_fs_1.promises.access(resolvedPath, node_fs_1.constants.F_OK | node_fs_1.constants.R_OK);
+            const iCanHazDadJoke = new _1.ICanHazDadJoke();
+            return [resolvedPath, iCanHazDadJoke];
+        }
+        catch (_a) {
+            throw new Error('The specified path does not exist or is not writable.');
+        }
+    });
+}
+function save(filePath_1, imageResult_1) {
+    return __awaiter(this, arguments, void 0, function* (filePath, imageResult, silent = false) {
+        const { id, image } = imageResult;
+        const resolvedFilePath = path.resolve(filePath, `dad_joke_${id}.png`);
+        yield node_fs_1.promises.writeFile(resolvedFilePath, image);
+        if (!silent) {
+            console.info(`Saved image to "${resolvedFilePath}".`);
+        }
+    });
+}
+commander_1.program.on('command:*', () => commander_1.program.help());
+commander_1.program
+    .name(package_json_1.name.replace(/^@[^/]+\//, ''))
+    .version(package_json_1.version, '-v, --version')
+    .description(package_json_1.description)
+    .option('-i, --image', 'Save the joke as image')
+    .option('-o, --output <dir>', 'Specify the output directory', path.resolve('.'))
+    .option('-s, --silent', `Don't output save messages`);
+commander_1.program
+    .command('random')
+    .description('Fetch a random joke')
+    .action(() => __awaiter(void 0, void 0, void 0, function* () {
+    const options = commander_1.program.opts();
+    try {
+        const [resolvedPath, iCanHazDadJoke] = yield init(options.output);
+        const result = yield iCanHazDadJoke.api.getRandom({ withImage: !!options.image });
+        console.info(result.joke);
+        if (options.image) {
+            yield save(resolvedPath, result, !!options.silent);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}));
+commander_1.program
+    .command('id')
+    .argument('<id>', 'The joke ID')
+    .description('Fetch joke by ID')
+    .action((id) => __awaiter(void 0, void 0, void 0, function* () {
+    const options = commander_1.program.opts();
+    try {
+        const [resolvedPath, iCanHazDadJoke] = yield init(options.output);
+        const result = yield iCanHazDadJoke.api.getById(id, { withImage: !!options.image });
+        console.info(result.joke);
+        if (options.image) {
+            yield save(resolvedPath, result, !!options.silent);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}));
+commander_1.program.parse(process.argv);
+if (!process.argv.slice(2).length) {
+    commander_1.program.outputHelp();
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ICanHazDadJoke';
+export * from './ICanHazDadJokeAPI';
+export * from './Interfaces';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ICanHazDadJoke"), exports);
+__exportStar(require("./ICanHazDadJokeAPI"), exports);
+__exportStar(require("./Interfaces"), exports);

package/package.json

@@ -2,16 +2,18 @@
   "author": "Florian Imdahl <git@ffflorian.de>",
   "bin": "dist/cli.js",
   "dependencies": {
-    "@ffflorian/api-client": "2.5.0",
+    "@ffflorian/api-client": "2.5.1",
     "commander": "14.0.3"
   },
   "description": "An icanhazdadjoke.com API client with a CLI.",
   "devDependencies": {
     "@types/node": "~24",
+    "nock": "14.0.12",
     "rimraf": "6.1.3",
     "tsx": "4.21.0",
-    "typedoc": "0.28.18",
-    "typescript": "6.0.2"
+    "typedoc": "0.28.19",
+    "typescript": "6.0.2",
+    "vitest": "4.1.4"
   },
   "engines": {
     "node": ">= 21"
@@ -31,12 +33,13 @@
   "readme": "https://github.com/ffflorian/api-clients#readme",
   "repository": "https://github.com/ffflorian/api-clients.git",
   "scripts": {
+    "build": "yarn build:ts",
     "build:ts": "tsc -p tsconfig.build.json",
     "build:docs": "typedoc --tsconfig tsconfig.build.json --options ../../typedoc.json --out ../../docs/packages/icanhazdadjoke src/index.ts",
     "clean": "rimraf dist",
-    "dist": "yarn clean && yarn build:ts",
+    "dist": "yarn clean && yarn build",
     "start": "tsx src/cli.ts",
-    "test": "exit 0"
+    "test": "vitest"
   },
-  "version": "2.4.6"
+  "version": "2.5.0"
 }