npms.io 2.4.6 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # npms.io [![npm version](https://img.shields.io/npm/v/npms.io.svg)](https://www.npmjs.com/package/npms.io)
 
-A [npms.io](https://npms.io) API client. For a documentation on the API see https://api-docs.npms.io/.
+A [npms.io](https://npms.io) API client. For a documentation on the API see [the npms.io API reference](https://api-docs.npms.io).
 
 ### Installation
 

package/dist/Endpoints.d.ts

@@ -0,0 +1,15 @@
+export declare const Endpoint: {
+    API_VERSION: string;
+    MGET: string;
+    PACKAGE: string;
+    Package: {
+        multiPackageInfo(): string;
+        packageInfo(packageName: string): string;
+    };
+    SEARCH: string;
+    Search: {
+        search(): string;
+        suggestions(): string;
+    };
+    SUGGESTIONS: string;
+};

package/dist/Endpoints.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Endpoint = void 0;
+exports.Endpoint = {
+    API_VERSION: 'v2',
+    MGET: 'mget',
+    PACKAGE: 'package',
+    Package: {
+        multiPackageInfo() {
+            return `${exports.Endpoint.API_VERSION}/${exports.Endpoint.PACKAGE}/${exports.Endpoint.MGET}`;
+        },
+        packageInfo(packageName) {
+            return `${exports.Endpoint.API_VERSION}/${exports.Endpoint.PACKAGE}/${encodeURIComponent(packageName)}`;
+        },
+    },
+    SEARCH: 'search',
+    Search: {
+        search() {
+            return `${exports.Endpoint.API_VERSION}/${exports.Endpoint.SEARCH}`;
+        },
+        suggestions() {
+            return `${exports.Endpoint.API_VERSION}/${exports.Endpoint.SEARCH}/${exports.Endpoint.SUGGESTIONS}`;
+        },
+    },
+    SUGGESTIONS: 'suggestions',
+};

package/dist/NpmsIO.d.ts

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

package/dist/NpmsIO.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NpmsIO = void 0;
+const api_client_1 = require("@ffflorian/api-client");
+const api_1 = require("./api");
+class NpmsIO {
+    constructor(options = {}) {
+        this.apiClient = new api_client_1.APIClient(options.apiUrl || 'https://api.npms.io');
+        this.api = {
+            package: new api_1.PackageAPI(this.apiClient),
+            search: new api_1.SearchAPI(this.apiClient),
+        };
+    }
+    /**
+     * Set a new API URL.
+     * @param newURL The new API url
+     */
+    setApiUrl(newURL) {
+        this.apiClient.setBaseURL(newURL);
+        this.api.package = new api_1.PackageAPI(this.apiClient);
+        this.api.search = new api_1.SearchAPI(this.apiClient);
+    }
+}
+exports.NpmsIO = NpmsIO;

package/dist/api/PackageAPI.d.ts

@@ -0,0 +1,18 @@
+import type { APIClient } from '@ffflorian/api-client';
+import type { PackageInfo } from '../interfaces/';
+export declare class PackageAPI {
+    private readonly apiClient;
+    constructor(apiClient: APIClient);
+    /**
+     * Get various packages info.
+     * @param packageNames The package names
+     * @see https://api-docs.npms.io/#api-Package-GetMultiPackageInfo
+     */
+    multiPackageInfo(packageNames: string[]): Promise<Record<string, PackageInfo>>;
+    /**
+     * Get package info.
+     * @param packageName The package name
+     * @see https://api-docs.npms.io/#api-Package-GetPackageInfo
+     */
+    packageInfo(packageName: string): Promise<PackageInfo>;
+}

package/dist/api/PackageAPI.js

@@ -0,0 +1,43 @@
+"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.PackageAPI = void 0;
+const Endpoints_1 = require("../Endpoints");
+class PackageAPI {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * Get various packages info.
+     * @param packageNames The package names
+     * @see https://api-docs.npms.io/#api-Package-GetMultiPackageInfo
+     */
+    multiPackageInfo(packageNames) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Package.multiPackageInfo();
+            const { data } = yield this.apiClient.post(endpoint, packageNames);
+            return data;
+        });
+    }
+    /**
+     * Get package info.
+     * @param packageName The package name
+     * @see https://api-docs.npms.io/#api-Package-GetPackageInfo
+     */
+    packageInfo(packageName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Package.packageInfo(packageName);
+            const { data } = yield this.apiClient.get(endpoint);
+            return data;
+        });
+    }
+}
+exports.PackageAPI = PackageAPI;

package/dist/api/SearchAPI.d.ts

@@ -0,0 +1,34 @@
+import type { APIClient } from '@ffflorian/api-client';
+import type { SearchOptions, SearchResult, SuggestionsOptions, SuggestionsResult } from '../interfaces';
+export declare class SearchAPI {
+    private readonly apiClient;
+    constructor(apiClient: APIClient);
+    /**
+     * Fetch suggestions.
+     * @param query Perform a search query
+     * @see https://api-docs.npms.io/#api-Search-SearchSuggestions
+     */
+    getSuggestions(query: string, options?: SuggestionsOptions): Promise<SuggestionsResult>;
+    /**
+     * Perform a search query.
+     * @param query Besides normal text, `query` supports qualifiers to express filters and other modifiers:
+     * - `scope:types` Show/filter results that belong to the `@types` scope
+     * - `author:sindresorhus` Show/filter results in which `sindresorhus` is the author
+     * - `maintainer:sindresorhus` Show/filter results in which `sindresorhus` is qualifier as a maintainer
+     * - `keywords:gulpplugin` Show/filter results that have `gulpplugin` in the keywords (separate multiple keywords with commas, you may also exclude keywords e.g.: `-framework`)
+     * - `not:deprecated` Exclude deprecated packages from the results
+     * - `not:unstable` Exclude packages whose version is `< 1.0.0`
+     * - `not:insecure` Exclude packages that are insecure or have vulnerable dependencies (as per [nsp](https://nodesecurity.io/))
+     * - `is:deprecated` Show/filter is deprecated packages
+     * - `is:unstable` Show/filter packages whose version is `< 1.0.0`
+     * - `is:insecure` Show/filter packages that are insecure or have vulnerable dependencies (as per [nsp](https://nodesecurity.io/))
+     * - `boost-exact:false` Do not boost exact matches, defaults to `true`
+     * - `score-effect:14` Set the effect that package scores have for the final search score, defaults to `15.3`
+     * - `quality-weight:1` Set the weight that quality has for the each package score, defaults to `1.95`
+     * - `popularity-weight:1` Set the weight that popularity has for the each package score, defaults to `3.3`
+     * - `maintenance-weight:1` Set the weight that the quality has for the each package score, defaults to `2.05`
+     * @param options Additional search options
+     * @see https://api-docs.npms.io/#api-Search-ExecuteSearchQuery
+     */
+    searchPackage(query: string, options?: SearchOptions): Promise<SearchResult>;
+}

package/dist/api/SearchAPI.js

@@ -0,0 +1,65 @@
+"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.SearchAPI = void 0;
+const Endpoints_1 = require("../Endpoints");
+class SearchAPI {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * Fetch suggestions.
+     * @param query Perform a search query
+     * @see https://api-docs.npms.io/#api-Search-SearchSuggestions
+     */
+    getSuggestions(query_1) {
+        return __awaiter(this, arguments, void 0, function* (query, options = {}) {
+            const endpoint = Endpoints_1.Endpoint.Search.suggestions();
+            const params = Object.assign({ 
+                // eslint-disable-next-line id-length
+                q: query }, (options.size && { size: options.size }));
+            const { data } = yield this.apiClient.get(endpoint, { params });
+            return data;
+        });
+    }
+    /**
+     * Perform a search query.
+     * @param query Besides normal text, `query` supports qualifiers to express filters and other modifiers:
+     * - `scope:types` Show/filter results that belong to the `@types` scope
+     * - `author:sindresorhus` Show/filter results in which `sindresorhus` is the author
+     * - `maintainer:sindresorhus` Show/filter results in which `sindresorhus` is qualifier as a maintainer
+     * - `keywords:gulpplugin` Show/filter results that have `gulpplugin` in the keywords (separate multiple keywords with commas, you may also exclude keywords e.g.: `-framework`)
+     * - `not:deprecated` Exclude deprecated packages from the results
+     * - `not:unstable` Exclude packages whose version is `< 1.0.0`
+     * - `not:insecure` Exclude packages that are insecure or have vulnerable dependencies (as per [nsp](https://nodesecurity.io/))
+     * - `is:deprecated` Show/filter is deprecated packages
+     * - `is:unstable` Show/filter packages whose version is `< 1.0.0`
+     * - `is:insecure` Show/filter packages that are insecure or have vulnerable dependencies (as per [nsp](https://nodesecurity.io/))
+     * - `boost-exact:false` Do not boost exact matches, defaults to `true`
+     * - `score-effect:14` Set the effect that package scores have for the final search score, defaults to `15.3`
+     * - `quality-weight:1` Set the weight that quality has for the each package score, defaults to `1.95`
+     * - `popularity-weight:1` Set the weight that popularity has for the each package score, defaults to `3.3`
+     * - `maintenance-weight:1` Set the weight that the quality has for the each package score, defaults to `2.05`
+     * @param options Additional search options
+     * @see https://api-docs.npms.io/#api-Search-ExecuteSearchQuery
+     */
+    searchPackage(query_1) {
+        return __awaiter(this, arguments, void 0, function* (query, options = {}) {
+            const endpoint = Endpoints_1.Endpoint.Search.search();
+            const params = Object.assign(Object.assign({ 
+                // eslint-disable-next-line id-length
+                q: query }, (options.from && { from: options.from })), (options.size && { size: options.size }));
+            const { data } = yield this.apiClient.get(endpoint, { params });
+            return data;
+        });
+    }
+}
+exports.SearchAPI = SearchAPI;

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from './PackageAPI';
+export * from './SearchAPI';

package/dist/api/index.js

@@ -0,0 +1,18 @@
+"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("./PackageAPI"), exports);
+__exportStar(require("./SearchAPI"), exports);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './api/';
+export * from './interfaces/';
+export * from './NpmsIO';

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("./api/"), exports);
+__exportStar(require("./interfaces/"), exports);
+__exportStar(require("./NpmsIO"), exports);

package/dist/interfaces/API.d.ts

@@ -0,0 +1,5 @@
+import { PackageAPI, SearchAPI } from '../api/';
+export interface API {
+    package: PackageAPI;
+    search: SearchAPI;
+}

package/dist/interfaces/API.js

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

package/dist/interfaces/ClientOptions.d.ts

@@ -0,0 +1,3 @@
+export interface ClientOptions {
+    apiUrl?: string;
+}

package/dist/interfaces/ClientOptions.js

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

package/dist/interfaces/PackageInfo.d.ts

@@ -0,0 +1,151 @@
+export interface Badge {
+    info: Info;
+    urls: Urls;
+}
+export interface Collected {
+    github?: GitHub;
+    metadata: Metadata;
+    npm: Npm;
+    source?: Source;
+}
+export interface Error {
+    code: string;
+    message: string;
+}
+export interface Evaluation {
+    maintenance: Maintenance;
+    popularity: Popularity;
+    quality: Quality;
+}
+export interface PackageInfo {
+    /** The date in which the package was last analyzed */
+    analyzedAt: string;
+    /** The collected information from all sources */
+    collected: Collected;
+    /** The error associated with the last analyze attempt */
+    error?: Error;
+    /** The package evaluation */
+    evaluation: Evaluation;
+    /** The package score */
+    score: Score;
+}
+export interface Score {
+    detail: Detail;
+    final: number;
+}
+interface Contributor {
+    commitsCount: number;
+    username: string;
+}
+interface Detail {
+    maintenance: number;
+    popularity: number;
+    quality: number;
+}
+interface Files {
+    hasChangelog: boolean;
+    readmeSize: number;
+    testsSize: number;
+}
+interface GitHub {
+    commits: Release[];
+    contributors: Contributor[];
+    forksCount: number;
+    homepage?: string;
+    issues: Issues;
+    starsCount: number;
+    statuses: Status[];
+    subscribersCount: number;
+}
+interface Info {
+    modifiers?: Modifiers;
+    service: string;
+    type: string;
+}
+interface Issues {
+    count: number;
+    distribution: Record<string, number>;
+    isDisabled: boolean;
+    openCount: number;
+}
+interface Links {
+    bugs?: string;
+    homepage?: string;
+    npm: string;
+    repository?: string;
+}
+interface Maintenance {
+    commitsFrequency: number;
+    issuesDistribution: number;
+    openIssues: number;
+    releasesFrequency: number;
+}
+interface Metadata {
+    date: string;
+    dependencies: Record<string, string>;
+    description: string;
+    hasSelectiveFiles?: boolean;
+    hasTestScript?: boolean;
+    keywords: string[];
+    license: string;
+    links: Links;
+    maintainers: Publisher[];
+    name: string;
+    publisher: Publisher;
+    readme?: string;
+    releases: Release[];
+    repository: Repository;
+    scope: string;
+    version: string;
+}
+interface Modifiers {
+    type: string;
+}
+interface Npm {
+    dependentsCount: number;
+    downloads: Release[];
+    starsCount: number;
+}
+interface Popularity {
+    communityInterest: number;
+    dependentsCount: number;
+    downloadsAcceleration: number;
+    downloadsCount: number;
+}
+interface Publisher {
+    email?: string;
+    username: string;
+}
+interface Quality {
+    branding: number;
+    carefulness: number;
+    health: number;
+    tests: number;
+}
+interface Release {
+    count: number;
+    from: string;
+    to: string;
+}
+interface Repository {
+    directory: string;
+    type?: string;
+    url: string;
+}
+interface Source {
+    badges: Badge[];
+    coverage: number;
+    files: Files;
+    linters: string[];
+}
+interface Status {
+    context: string;
+    state: string;
+}
+interface Urls {
+    content: string;
+    original: string;
+    service?: string;
+    shields: string;
+}
+export {};

package/dist/interfaces/PackageInfo.js

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

package/dist/interfaces/SearchOptions.d.ts

@@ -0,0 +1,22 @@
+export interface SearchOptions extends SuggestionsOptions {
+    /**
+     * The offset in which to start searching from (max of 5000)
+     *
+     * Default value: `0`
+     */
+    from?: string;
+    /**
+     * The total number of results to return (max of 250)
+     *
+     * Default value: `25`
+     */
+    size?: string;
+}
+export interface SuggestionsOptions {
+    /**
+     * The total number of results to return (max of 100)
+     *
+     * Default value: `25`
+     */
+    size?: string;
+}

package/dist/interfaces/SearchOptions.js

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

package/dist/interfaces/SearchResult.d.ts

@@ -0,0 +1,62 @@
+export interface Author {
+    email?: string;
+    name: string;
+    url?: string;
+    username?: string;
+}
+export interface Flags {
+    deprecated?: boolean;
+    insecure?: boolean;
+    unstable?: boolean;
+}
+export interface Package {
+    author?: Author;
+    date: string;
+    description: string;
+    keywords?: string[];
+    links: Links;
+    maintainers: Publisher[];
+    name: string;
+    publisher: Publisher;
+    scope: string;
+    version: string;
+}
+export interface Publisher {
+    email: string;
+    username: string;
+}
+export interface Result {
+    /** The package flags (deprecated, unstable, insecure) */
+    flags?: Flags;
+    /** The package data which contains the name, version and other useful information */
+    package: Package;
+    /** The package score */
+    score: Score;
+    /** The computed search score (from Elasticsearch) */
+    searchScore: number;
+}
+export interface SearchResult {
+    results: Result[];
+    total: number;
+}
+export interface SuggestionResult extends Result {
+    /** A string containing highlighted matched text */
+    highlight?: string;
+}
+export type SuggestionsResult = SuggestionResult[];
+interface Detail {
+    maintenance: number;
+    popularity: number;
+    quality: number;
+}
+interface Links {
+    bugs?: string;
+    homepage?: string;
+    npm: string;
+    repository?: string;
+}
+interface Score {
+    detail: Detail;
+    final: number;
+}
+export {};

package/dist/interfaces/SearchResult.js

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

package/dist/interfaces/index.d.ts

@@ -0,0 +1,5 @@
+export * from './API';
+export * from './ClientOptions';
+export * from './PackageInfo';
+export * from './SearchOptions';
+export * from './SearchResult';

package/dist/interfaces/index.js

@@ -0,0 +1,21 @@
+"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("./API"), exports);
+__exportStar(require("./ClientOptions"), exports);
+__exportStar(require("./PackageInfo"), exports);
+__exportStar(require("./SearchOptions"), exports);
+__exportStar(require("./SearchResult"), exports);

package/package.json

@@ -1,14 +1,16 @@
 {
   "author": "Florian Imdahl <git@ffflorian.de>",
   "dependencies": {
-    "@ffflorian/api-client": "2.5.0"
+    "@ffflorian/api-client": "2.5.1"
   },
   "description": "A npms.io API client",
   "devDependencies": {
     "@types/node": "~24",
+    "nock": "14.0.12",
     "rimraf": "6.1.3",
-    "typedoc": "0.28.18",
-    "typescript": "6.0.2"
+    "typedoc": "0.28.19",
+    "typescript": "6.0.3",
+    "vitest": "4.1.4"
   },
   "engines": {
     "node": ">= 21"
@@ -29,11 +31,12 @@
   "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/npms.io src/index.ts",
     "clean": "rimraf dist",
-    "dist": "yarn clean && yarn build:ts",
-    "test": "exit 0"
+    "dist": "yarn clean && yarn build",
+    "test": "vitest run"
   },
-  "version": "2.4.6"
+  "version": "2.5.0"
 }