@ffflorian/xkcdjs 3.4.6 → 3.5.0

package/README.md

@@ -1,6 +1,6 @@
 # xkcdjs [![npm version](https://img.shields.io/npm/v/@ffflorian/xkcdjs.svg)](https://www.npmjs.com/package/@ffflorian/xkcdjs)
 
-An [xkcd](https://xkcd.com) API client with a CLI.
+An [xkcd](https://xkcd.com) API client with a CLI. For a documentation on the API see [the xkcd API reference](https://xkcd.com/json.html).
 
 ## Usage
 
@@ -45,7 +45,7 @@ xkcd.api.getRandom().then(result => {
   // XKCDResult
 });
 
-xkcd.api.getById(2036).then(result => {
+xkcd.api.getByIndex(2036).then(result => {
   // XKCDResult
 });
 
@@ -57,7 +57,7 @@ xkcd.api.getRandom({withData: true}).then(result => {
   // XKCDResultWithData
 });
 
-xkcd.api.getById(2036, {withData: true}).then(result => {
+xkcd.api.getByIndex(2036, {withData: true}).then(result => {
   // XKCDResultWithData
 });
 ```

package/dist/Interfaces.d.ts

@@ -0,0 +1,26 @@
+export interface ClientOptions {
+    apiUrl?: string;
+}
+export interface ImageData {
+    data: Buffer;
+    mimeType?: string;
+}
+export interface RequestOptions {
+    withData?: boolean;
+}
+export interface XKCDResult {
+    alt: string;
+    day: string;
+    img: string;
+    link: string;
+    month: string;
+    news: string;
+    num: number;
+    safe_title: string;
+    title: string;
+    transcript: string;
+    year: string;
+}
+export interface XKCDResultWithData extends XKCDResult {
+    data: ImageData;
+}

package/dist/Interfaces.js

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

package/dist/XKCD.d.ts

@@ -0,0 +1,13 @@
+import type { ClientOptions } from './Interfaces';
+import { XKCDAPI } from './XKCDAPI';
+export declare class XKCD {
+    readonly api: XKCDAPI;
+    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/XKCD.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XKCD = void 0;
+const api_client_1 = require("@ffflorian/api-client");
+const XKCDAPI_1 = require("./XKCDAPI");
+class XKCD {
+    constructor(options) {
+        this.options = Object.assign({ apiUrl: 'https://xkcd.com' }, options);
+        this.apiClient = new api_client_1.APIClient(this.options.apiUrl);
+        this.api = new XKCDAPI_1.XKCDAPI(this.apiClient, this.options);
+    }
+    /**
+     * Set a new API URL.
+     * @param url The new API URL.
+     */
+    setApiUrl(url) {
+        this.apiClient.setBaseURL(url);
+    }
+}
+exports.XKCD = XKCD;

package/dist/XKCDAPI.d.ts

@@ -0,0 +1,35 @@
+import type { APIClient } from '@ffflorian/api-client';
+import type { ClientOptions, RequestOptions, XKCDResult, XKCDResultWithData } from './Interfaces';
+export declare class XKCDAPI {
+    protected readonly apiClient: APIClient;
+    protected readonly options: ClientOptions;
+    private readonly JSON_INFO_FILE;
+    private readonly lowestIndex;
+    constructor(apiClient: APIClient, options: ClientOptions);
+    /**
+     * Get a comic by index.
+     * @param index Index number
+     * @param options Request options
+     */
+    getByIndex(index: number, options: {
+        withData: true;
+    }): Promise<XKCDResultWithData>;
+    getByIndex(index: number, options?: RequestOptions): Promise<XKCDResult>;
+    /**
+     * Get the latest comic.
+     * @param options Request options
+     */
+    getLatest(options: {
+        withData: true;
+    }): Promise<XKCDResultWithData>;
+    getLatest(options?: RequestOptions): Promise<XKCDResult>;
+    /**
+     * Get a random comic.
+     * @param options Request options
+     */
+    getRandom(options: {
+        withData: true;
+    }): Promise<XKCDResultWithData>;
+    getRandom(options?: RequestOptions): Promise<XKCDResult>;
+    private getImage;
+}

package/dist/XKCDAPI.js

@@ -0,0 +1,68 @@
+"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.XKCDAPI = void 0;
+class XKCDAPI {
+    constructor(apiClient, options) {
+        this.apiClient = apiClient;
+        this.options = options;
+        this.lowestIndex = 1;
+        this.JSON_INFO_FILE = 'info.0.json';
+    }
+    getByIndex(index_1) {
+        return __awaiter(this, arguments, void 0, function* (index, options = {}) {
+            if (index < this.lowestIndex) {
+                throw new Error(`Index is lower than the lowest index of ${this.lowestIndex}.`);
+            }
+            const { data: metaData } = yield this.apiClient.get(`/${index}/${this.JSON_INFO_FILE}`);
+            if (options.withData === true) {
+                const imageData = yield this.getImage(metaData.img);
+                return Object.assign(Object.assign({}, metaData), { data: imageData });
+            }
+            return metaData;
+        });
+    }
+    getLatest() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const { data: metaData } = yield this.apiClient.get(`/${this.JSON_INFO_FILE}`);
+            if (options.withData) {
+                const imageData = yield this.getImage(metaData.img);
+                return Object.assign(Object.assign({}, metaData), { data: imageData });
+            }
+            return metaData;
+        });
+    }
+    getRandom() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const latest = yield this.getLatest();
+            const randomIndex = Math.floor(Math.random() * (latest.num - this.lowestIndex + 1)) + this.lowestIndex;
+            const metaData = yield this.getByIndex(randomIndex);
+            if (options.withData === true) {
+                const imageData = yield this.getImage(metaData.img);
+                return Object.assign(Object.assign({}, metaData), { data: imageData });
+            }
+            return metaData;
+        });
+    }
+    getImage(imageUrl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data, headers } = yield this.apiClient.get(imageUrl, {
+                responseType: 'arraybuffer',
+            });
+            const contentType = headers.get('content-type');
+            return {
+                data,
+                mimeType: contentType ? String(contentType) : undefined,
+            };
+        });
+    }
+}
+exports.XKCDAPI = XKCDAPI;

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,135 @@
+#!/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 xkcd = new _1.XKCD();
+            return [resolvedPath, xkcd];
+        }
+        catch (_a) {
+            throw new Error('The specified path does not exist or is not writable.');
+        }
+    });
+}
+function save(filePath, imageResult) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { data, num, safe_title } = imageResult;
+        const extension = data.mimeType ? data.mimeType.replace('image/', '') : 'png';
+        const resolvedFilePath = path.resolve(filePath, `xkcd #${num} - ${safe_title}.${extension}`);
+        yield node_fs_1.promises.writeFile(resolvedFilePath, data.data);
+        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('-o, --output <dir>', 'Specify the output directory', path.resolve('.'));
+commander_1.program
+    .command('latest')
+    .description('Save the latest comic')
+    .action((command) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const [resolvedPath, xkcd] = yield init(command.parent.output);
+        const imageData = yield xkcd.api.getLatest({ withData: true });
+        yield save(resolvedPath, imageData);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        commander_1.program.outputHelp();
+        process.exit(1);
+    }
+}));
+commander_1.program
+    .command('random')
+    .description('Save a random comic')
+    .action((command) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const [resolvedPath, xkcd] = yield init(command.parent.output);
+        const imageData = yield xkcd.api.getRandom({ withData: true });
+        yield save(resolvedPath, imageData);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        commander_1.program.outputHelp();
+        process.exit(1);
+    }
+}));
+commander_1.program
+    .command('number <index>')
+    .description('Save comic by index number')
+    .action((index, command) => __awaiter(void 0, void 0, void 0, function* () {
+    let parsedIndex;
+    try {
+        parsedIndex = parseInt(index, 10);
+    }
+    catch (_a) {
+        throw new Error('Invalid number specified.');
+    }
+    try {
+        const [resolvedPath, xkcd] = yield init(command.parent.output);
+        const imageData = yield xkcd.api.getByIndex(parsedIndex, { withData: true });
+        yield save(resolvedPath, imageData);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        commander_1.program.outputHelp();
+        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 './Interfaces';
+export * from './XKCD';
+export * from './XKCDAPI';

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("./Interfaces"), exports);
+__exportStar(require("./XKCD"), exports);
+__exportStar(require("./XKCDAPI"), exports);

package/package.json

@@ -2,19 +2,19 @@
   "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 xkcd API client with a CLI.",
   "devDependencies": {
     "@types/node": "~24",
     "http-status-codes": "2.3.0",
-    "nock": "14.0.11",
+    "nock": "14.0.12",
     "rimraf": "6.1.3",
     "tsx": "4.21.0",
-    "typedoc": "0.28.18",
-    "typescript": "6.0.2",
-    "vitest": "4.1.0"
+    "typedoc": "0.28.19",
+    "typescript": "6.0.3",
+    "vitest": "4.1.5"
   },
   "engines": {
     "node": ">= 21"
@@ -34,12 +34,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/xkcdjs src/index.ts",
     "clean": "rimraf dist",
-    "dist": "yarn clean && yarn build:ts",
+    "dist": "yarn clean && yarn build",
     "start": "tsx src/cli.ts",
     "test": "vitest"
   },
-  "version": "3.4.6"
+  "version": "3.5.0"
 }