crates.io 2.4.7 → 2.5.1

package/README.md

@@ -2,6 +2,14 @@
 
 A [crates.io](https://crates.io) API client.
 
+API references:
+
+- [Data access policy](https://crates.io/data-access)
+- [OpenAPI specification](https://crates.io/api/openapi.json)
+- [Historical HTTP API reference](https://github.com/hcpl/crates.io-http-api-reference)
+
+Some endpoints in this client require an API token (for example `following`, `follow`, `unfollow`, `yank`, and `unyank`).
+
 ### Installation
 
 Run `yarn add crates.io` or `npm install crates.io`.

package/dist/CratesIO.js

@@ -16,9 +16,9 @@ const Endpoints_1 = require("./Endpoints");
 class CratesIO {
     constructor(options) {
         this.options = typeof options === 'string' ? { apiKey: options } : options || {};
-        this.apiClient = new api_client_1.APIClient('https://crates.io/api/v1');
+        this.apiClient = new api_client_1.APIClient(this.options.apiUrl || 'https://crates.io/api/v1');
         this.api = {
-            crates: new api_1.CratesAPI(this.apiClient),
+            crates: new api_1.CratesAPI(this.apiClient, this.options.apiKey),
         };
     }
     /**

package/dist/Endpoints.d.ts

@@ -1,30 +1,48 @@
 export declare const Endpoint: {
     AUTHORS: string;
+    CATEGORIES: string;
+    Categories: {
+        categories(): string;
+        category(category: string): string;
+    };
     CRATES: string;
     Crates: {
         authors(packageName: string, version: string): string;
         crate(packageName: string): string;
         crates(): string;
         dependencies(packageName: string): string;
+        dependenciesByVersion(packageName: string, version: string): string;
         download(packageName: string, version: string): string;
         downloads(packageName: string): string;
+        follow(packageName: string): string;
         following(packageName: string): string;
         owners(packageName: string): string;
         ownerTeam(packageName: string): string;
         ownerUser(packageName: string): string;
         reverseDependencies(packageName: string): string;
+        unyank(packageName: string, version: string): string;
         version(packageName: string, version: string): string;
+        versionDownloads(packageName: string, version: string): string;
         versions(packageName: string): string;
+        yank(packageName: string, version: string): string;
     };
     DEPENDENCIES: string;
     DOWNLOAD: string;
     DOWNLOADS: string;
+    FOLLOW: string;
     FOLLOWING: string;
+    KEYWORDS: string;
+    Keywords: {
+        keyword(keyword: string): string;
+        keywords(): string;
+    };
     OWNER_TEAM: string;
     OWNER_USER: string;
     OWNERS: string;
     REVERSE_DEPENDENCIES: string;
     SUMMARY: string;
     summary(): string;
+    UNYANK: string;
     VERSIONS: string;
+    YANK: string;
 };

package/dist/Endpoints.js

@@ -2,61 +2,98 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Endpoint = void 0;
 const encode = encodeURIComponent;
+const apiPrefix = '/api/v1';
 exports.Endpoint = {
     AUTHORS: 'authors',
+    CATEGORIES: 'categories',
+    Categories: {
+        categories() {
+            return `${apiPrefix}/${exports.Endpoint.CATEGORIES}`;
+        },
+        category(category) {
+            return `${apiPrefix}/${exports.Endpoint.CATEGORIES}/${encode(category)}`;
+        },
+    },
     CRATES: 'crates',
     Crates: {
         authors(packageName, version) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.AUTHORS}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.AUTHORS}`;
         },
         crate(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}`;
         },
         crates() {
-            return `/${exports.Endpoint.CRATES}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}`;
         },
         dependencies(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.DEPENDENCIES}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.DEPENDENCIES}`;
+        },
+        dependenciesByVersion(packageName, version) {
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.DEPENDENCIES}`;
         },
         download(packageName, version) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.DOWNLOAD}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.DOWNLOAD}`;
         },
         downloads(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.DOWNLOADS}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.DOWNLOADS}`;
+        },
+        follow(packageName) {
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.FOLLOW}`;
         },
         following(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.FOLLOWING}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.FOLLOWING}`;
         },
         owners(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNERS}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNERS}`;
         },
         ownerTeam(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNER_TEAM}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNER_TEAM}`;
         },
         ownerUser(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNER_USER}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.OWNER_USER}`;
         },
         reverseDependencies(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.REVERSE_DEPENDENCIES}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.REVERSE_DEPENDENCIES}`;
+        },
+        unyank(packageName, version) {
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.UNYANK}`;
         },
         version(packageName, version) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}`;
+        },
+        versionDownloads(packageName, version) {
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.DOWNLOADS}`;
         },
         versions(packageName) {
-            return `/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.VERSIONS}`;
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${exports.Endpoint.VERSIONS}`;
+        },
+        yank(packageName, version) {
+            return `${apiPrefix}/${exports.Endpoint.CRATES}/${encode(packageName)}/${encode(version)}/${exports.Endpoint.YANK}`;
         },
     },
     DEPENDENCIES: 'dependencies',
     DOWNLOAD: 'download',
     DOWNLOADS: 'downloads',
+    FOLLOW: 'follow',
     FOLLOWING: 'following',
+    KEYWORDS: 'keywords',
+    Keywords: {
+        keyword(keyword) {
+            return `${apiPrefix}/${exports.Endpoint.KEYWORDS}/${encode(keyword)}`;
+        },
+        keywords() {
+            return `${apiPrefix}/${exports.Endpoint.KEYWORDS}`;
+        },
+    },
     OWNER_TEAM: 'owner_team',
     OWNER_USER: 'owner_user',
     OWNERS: 'owners',
     REVERSE_DEPENDENCIES: 'reverse_dependencies',
     SUMMARY: 'summary',
     summary() {
-        return `/${exports.Endpoint.SUMMARY}`;
+        return `${apiPrefix}/${exports.Endpoint.SUMMARY}`;
     },
+    UNYANK: 'unyank',
     VERSIONS: 'versions',
+    YANK: 'yank',
 };

package/dist/api/CratesAPI.d.ts

@@ -1,9 +1,14 @@
 import type { APIClient } from '@ffflorian/api-client';
-import type { AuthorsResult, CrateResult, DependenciesResult, DownloadsResult, FollowingResult, ReverseDependenciesResult, SearchOptions, SearchResult, TeamsResult, UrlResult, UsersResult, Version } from '../interfaces/';
+import type { AuthorsResult, CategoriesResult, CategoryResult, CrateResult, DependenciesResult, DownloadsResult, FollowingResult, KeywordResult, KeywordsResult, OkResult, PaginationOptions, ReverseDependenciesResult, SearchOptions, SearchResult, TeamsResult, UrlResult, UsersResult, Version, VersionsResult } from '../interfaces/';
 export declare class CratesAPI {
     private readonly apiClient;
     private apiKey?;
     constructor(apiClient: APIClient, apiKey?: string);
+    /**
+     * Follow a crate.
+     * @param packageName The package name
+     */
+    follow(packageName: string): Promise<OkResult>;
     /**
      * Retrieve the owners of a crate.
      * @param packageName The package name
@@ -14,6 +19,16 @@ export declare class CratesAPI {
      * @param packageName The package name
      */
     getAuthors(packageName: string, version: string): Promise<AuthorsResult>;
+    /**
+     * Retrieve categories.
+     * @param options Pagination options
+     */
+    getCategories(options?: PaginationOptions): Promise<CategoriesResult>;
+    /**
+     * Retrieve a category.
+     * @param category The category slug
+     */
+    getCategory(category: string): Promise<CategoryResult>;
     /**
      * Retrieve information of a crate.
      * @param packageName The package name
@@ -40,6 +55,16 @@ export declare class CratesAPI {
      * @param packageName The package name
      */
     getDownloadUrl(packageName: string, version: string): Promise<UrlResult>;
+    /**
+     * Retrieve a keyword.
+     * @param keyword The keyword
+     */
+    getKeyword(keyword: string): Promise<KeywordResult>;
+    /**
+     * Retrieve keywords.
+     * @param options Pagination options
+     */
+    getKeywords(options?: PaginationOptions): Promise<KeywordsResult>;
     /**
      * Retrieve the owners of a crate.
      * @param packageName The package name
@@ -65,16 +90,43 @@ export declare class CratesAPI {
      * @param packageName The package name
      */
     getVersion(packageName: string, version: string): Promise<Version>;
+    /**
+     * Retrieve the dependencies of a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    getVersionDependencies(packageName: string, version: string): Promise<DependenciesResult>;
+    /**
+     * Retrieve download stats for a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    getVersionDownloads(packageName: string, version: string): Promise<DownloadsResult>;
     /**
      * Retrieve all versions of a crate.
      * @param packageName The package name
      */
-    getVersions(packageName: string): Promise<{
-        versions: Version[];
-    }>;
+    getVersions(packageName: string): Promise<VersionsResult>;
     /**
      * Set a new API key.
      * @param apiKey The API key
      */
     setApiKey(apiKey: string): void;
+    /**
+     * Unfollow a crate.
+     * @param packageName The package name
+     */
+    unfollow(packageName: string): Promise<OkResult>;
+    /**
+     * Unyank a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    unyank(packageName: string, version: string): Promise<OkResult>;
+    /**
+     * Yank a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    yank(packageName: string, version: string): Promise<OkResult>;
 }

package/dist/api/CratesAPI.js

@@ -16,6 +16,25 @@ class CratesAPI {
         this.apiClient = apiClient;
         this.apiKey = apiKey;
     }
+    /**
+     * Follow a crate.
+     * @param packageName The package name
+     */
+    follow(packageName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.follow(packageName);
+            if (!this.apiKey) {
+                throw new Error('You need to set an API key to use this endpoint.');
+            }
+            const additionalConfig = {
+                headers: {
+                    Authorization: this.apiKey,
+                },
+            };
+            const { data } = yield this.apiClient.put(endpoint, undefined, additionalConfig);
+            return data;
+        });
+    }
     /**
      * Retrieve the owners of a crate.
      * @param packageName The package name
@@ -46,6 +65,31 @@ class CratesAPI {
             return data;
         });
     }
+    /**
+     * Retrieve categories.
+     * @param options Pagination options
+     */
+    getCategories(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Categories.categories();
+            const additionalConfig = {
+                params: Object.assign({}, options),
+            };
+            const { data } = yield this.apiClient.get(endpoint, additionalConfig);
+            return data;
+        });
+    }
+    /**
+     * Retrieve a category.
+     * @param category The category slug
+     */
+    getCategory(category) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Categories.category(category);
+            const { data } = yield this.apiClient.get(endpoint);
+            return data;
+        });
+    }
     /**
      * Retrieve information of a crate.
      * @param packageName The package name
@@ -107,6 +151,31 @@ class CratesAPI {
             return data;
         });
     }
+    /**
+     * Retrieve a keyword.
+     * @param keyword The keyword
+     */
+    getKeyword(keyword) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Keywords.keyword(keyword);
+            const { data } = yield this.apiClient.get(endpoint);
+            return data;
+        });
+    }
+    /**
+     * Retrieve keywords.
+     * @param options Pagination options
+     */
+    getKeywords(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Keywords.keywords();
+            const additionalConfig = {
+                params: Object.assign({}, options),
+            };
+            const { data } = yield this.apiClient.get(endpoint, additionalConfig);
+            return data;
+        });
+    }
     /**
      * Retrieve the owners of a crate.
      * @param packageName The package name
@@ -159,6 +228,30 @@ class CratesAPI {
         return __awaiter(this, void 0, void 0, function* () {
             const endpoint = Endpoints_1.Endpoint.Crates.version(packageName, version);
             const { data } = yield this.apiClient.get(endpoint);
+            return data.version;
+        });
+    }
+    /**
+     * Retrieve the dependencies of a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    getVersionDependencies(packageName, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.dependenciesByVersion(packageName, version);
+            const { data } = yield this.apiClient.get(endpoint);
+            return data;
+        });
+    }
+    /**
+     * Retrieve download stats for a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    getVersionDownloads(packageName, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.versionDownloads(packageName, version);
+            const { data } = yield this.apiClient.get(endpoint);
             return data;
         });
     }
@@ -180,5 +273,64 @@ class CratesAPI {
     setApiKey(apiKey) {
         this.apiKey = apiKey;
     }
+    /**
+     * Unfollow a crate.
+     * @param packageName The package name
+     */
+    unfollow(packageName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.follow(packageName);
+            if (!this.apiKey) {
+                throw new Error('You need to set an API key to use this endpoint.');
+            }
+            const additionalConfig = {
+                headers: {
+                    Authorization: this.apiKey,
+                },
+            };
+            const { data } = yield this.apiClient.delete(endpoint, additionalConfig);
+            return data;
+        });
+    }
+    /**
+     * Unyank a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    unyank(packageName, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.unyank(packageName, version);
+            if (!this.apiKey) {
+                throw new Error('You need to set an API key to use this endpoint.');
+            }
+            const additionalConfig = {
+                headers: {
+                    Authorization: this.apiKey,
+                },
+            };
+            const { data } = yield this.apiClient.put(endpoint, undefined, additionalConfig);
+            return data;
+        });
+    }
+    /**
+     * Yank a specific crate version.
+     * @param packageName The package name
+     * @param version The version
+     */
+    yank(packageName, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Crates.yank(packageName, version);
+            if (!this.apiKey) {
+                throw new Error('You need to set an API key to use this endpoint.');
+            }
+            const additionalConfig = {
+                headers: {
+                    Authorization: this.apiKey,
+                },
+            };
+            const { data } = yield this.apiClient.delete(endpoint, additionalConfig);
+            return data;
+        });
+    }
 }
 exports.CratesAPI = CratesAPI;

package/dist/interfaces/Crate.d.ts

@@ -1,18 +1,14 @@
 export interface Crate {
-    badges: {
-        [key: string]: {
-            [key: string]: string;
-        };
-    } | null;
-    categories: null | string;
+    badges: object[];
+    categories: null | string[];
     created_at: string;
-    description: string;
+    description: null | string;
     documentation: null | string;
     downloads: number;
     exact_match: boolean;
     homepage: null | string;
     id: string;
-    keywords: null | string;
+    keywords: null | string[];
     links: {
         owner_team: string;
         owner_user: string;
@@ -25,6 +21,8 @@ export interface Crate {
     name: string;
     recent_downloads: null | number;
     repository: null | string;
+    trustpub_only: boolean;
     updated_at: string;
     versions: null | number[];
+    yanked: boolean;
 }

package/dist/interfaces/Keyword.d.ts

@@ -1,6 +1,6 @@
 export interface Keyword {
-    crated_at: string;
     crates_cnt: number;
+    created_at: string;
     id: string;
     keyword: string;
 }

package/dist/interfaces/Options.d.ts

@@ -2,8 +2,18 @@ export interface ClientOptions {
     apiKey?: string;
     apiUrl?: string;
 }
+export interface PaginationOptions {
+    page?: number;
+    per_page?: number;
+}
 export interface SearchOptions {
+    category?: string;
+    following?: string;
+    keyword?: string;
+    letter?: string;
     page?: number;
     per_page?: number;
     sort?: string;
+    team_id?: number;
+    user_id?: number;
 }

package/dist/interfaces/Result.d.ts

@@ -3,7 +3,16 @@ export interface AuthorsResult {
     meta: {
         names: string[];
     };
-    users: string[];
+    users: User[];
+}
+export interface CategoriesResult {
+    categories: Category[];
+    meta: {
+        total: number;
+    };
+}
+export interface CategoryResult {
+    category: Category;
 }
 export interface CrateResult {
     categories: Category[];
@@ -14,15 +23,31 @@ export interface DependenciesResult {
     dependencies: Dependency[];
 }
 export interface DownloadsResult {
+    meta?: {
+        extra_downloads?: Download[];
+    };
     version_downloads: Download[];
 }
 export interface FollowingResult {
     following: boolean;
 }
-export interface ReverseDependenciesResult extends DependenciesResult, VersionResult {
+export interface KeywordResult {
+    keyword: Keyword;
+}
+export interface KeywordsResult {
+    keywords: Keyword[];
+    meta: {
+        total: number;
+    };
+}
+export interface OkResult {
+    ok: boolean;
+}
+export interface ReverseDependenciesResult extends DependenciesResult {
     meta: {
         total: number;
     };
+    versions: Version[];
 }
 export interface SearchResult {
     crates: Crate[];

package/dist/interfaces/Team.d.ts

@@ -1,2 +1,8 @@
 export interface Team {
+    avatar: null | string;
+    id: number;
+    kind?: string;
+    login: string;
+    name: null | string;
+    url: null | string;
 }

package/dist/interfaces/User.d.ts

@@ -1,7 +1,7 @@
 export interface User {
     avatar: null | string;
     id: number;
-    kind: string;
+    kind?: string;
     login: string;
     name: null | string;
     url: null | string;

package/dist/interfaces/Version.d.ts

@@ -1,3 +1,4 @@
+import type { User } from './User';
 export interface Version {
     crate: string;
     crate_size: number;
@@ -15,7 +16,7 @@ export interface Version {
         version_downloads: string;
     };
     num: string;
-    published_by: null | string;
+    published_by: null | User;
     readme_path: string;
     updated_at: string;
     yanked: boolean;

package/package.json

@@ -1,14 +1,17 @@
 {
   "author": "Florian Imdahl <git@ffflorian.de>",
   "dependencies": {
-    "@ffflorian/api-client": "2.5.1"
+    "@ffflorian/api-client": "2.5.3"
   },
   "description": "A crates.io API client",
   "devDependencies": {
-    "@types/node": "~24",
+    "@types/node": "~26",
+    "nock": "14.0.17",
     "rimraf": "6.1.3",
-    "typedoc": "0.28.18",
-    "typescript": "6.0.2"
+    "typedoc": "0.28.20",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vitest": "5.0.0"
   },
   "engines": {
     "node": ">= 21"
@@ -27,14 +30,17 @@
   "license": "GPL-3.0",
   "name": "crates.io",
   "readme": "https://github.com/ffflorian/api-clients#readme",
-  "repository": "https://github.com/ffflorian/api-clients.git",
+  "repository": {
+    "type": "git",
+    "url": "git+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/crates.io src/index.ts",
     "clean": "rimraf dist",
     "dist": "yarn clean && yarn build",
-    "test": "exit 0"
+    "test": "vitest"
   },
-  "version": "2.4.7"
+  "version": "2.5.1"
 }