@rowanmanning/package-json-github 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+
+# @rowanmanning/package-json-github
+
+Load and parse `package.json` and `package-lock.json` files from GitHub repositories.
+
+* [Requirements](#requirements)
+* [Usage](#usage)
+  * [`packageJson.fromGitHub()`](#packagejsonfromgithub)
+  * [`packageLock.fromGitHub()`](#packagelockfromgithub)
+  * [Options](#options)
+* [Contributing](#contributing)
+* [License](#license)
+
+
+## Requirements
+
+This library requires the following to run:
+
+  * [Node.js](https://nodejs.org/) 18+
+
+
+## Usage
+
+Install with [npm](https://www.npmjs.com/):
+
+```sh
+npm install @rowanmanning/package-json-github
+```
+
+Load into your code with `import` or `require`:
+
+```js
+import { packageJson, packageLock } from '@rowanmanning/package-json-github';
+// or
+const { packageJson, packageLock } = require('@rowanmanning/package-json-github');
+```
+
+The following exports are available.
+
+### `packageJson.fromGitHub()`
+
+Load the `package.json` file present in a GitHub repo.
+
+```ts
+(options: GitHubOptions) => Promise<PackageJson>
+```
+
+The `options` argument must be an object. [The available options are documented here](#options).
+
+```js
+const pkg = await packageJson.fromGitHub({
+    auth: process.env.GITHUB_AUTH_TOKEN,
+    owner: 'rowanmanning',
+    repo: 'yeehaw'
+});
+// { name: '@rowanmanning/yeehaw', version: '2.0.0', ... }
+```
+
+### `packageLock.fromGitHub()`
+
+Load the `package-lock.json` file present in a GitHub repo.
+
+```ts
+(options: GitHubOptions) => Promise<PackageLock>
+```
+
+The `options` argument must be an object. [The available options are documented here](#options).
+
+```js
+const pkg = await packageLock.fromGitHub({
+    auth: process.env.GITHUB_AUTH_TOKEN,
+    owner: 'rowanmanning',
+    repo: 'yeehaw'
+});
+// { lockfileVersion: 2, name: '@rowanmanning/yeehaw', version: '2.0.0', ... }
+```
+
+### Options
+
+The `options` argument must be an object. It's required and has the following properties. These are passed directly to the GitHub REST API, please [consult the API documentation for more information](https://docs.github.com/en/rest/repos/contents?apiVersion=2022-11-28#get-repository-content).
+
+  * `auth` (`string`, required). A [GitHub token](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api) with read access to the repo you specify
+
+  * `owner` (`string`, required). The name of the GitHub user or organisation that the repo belongs to
+
+  * `repo` (`string`, required). The name of the GitHub repo
+
+  * `path` (`string`, optional). The path to the file you'd like to read. Defaults to `package.json` or `package-lock.json` depending on the method you're using
+
+  * `ref` (`string`, optional). The name of the commit, branch, or tag to fetch the file from. Defaults to the repo's default branch
+
+
+## Contributing
+
+[See the central README for a contribution guide and code of conduct](https://github.com/rowanmanning/repo-tools#contributing).
+
+
+## License
+
+Licensed under the [MIT](https://github.com/rowanmanning/repo-tools/blob/main/LICENSE) license.<br/>
+Copyright &copy; 2024, Rowan Manning

package/index.d.ts

@@ -0,0 +1,30 @@
+import type { AnyPackageLock, PackageJson } from '@rowanmanning/package-json';
+
+declare module '@rowanmanning/package-json-github' {
+	export type {
+		PackageJson,
+		PackageLockV1,
+		PackageLockV2,
+		PackageLockV3,
+		AnyPackageLock
+	} from '@rowanmanning/package-json';
+
+	export interface GitHubOptions {
+		auth: string;
+		owner: string;
+		repo: string;
+		path?: string | undefined;
+		ref?: string | undefined;
+	}
+
+	interface PackageJsonMethods {
+		fromGitHubRepo(options: GitHubOptions): Promise<PackageJson>;
+	}
+
+	interface PackageLockMethods {
+		fromGitHubRepo(options: GitHubOptions): Promise<AnyPackageLock>;
+	}
+
+	export const packageJson: PackageJsonMethods;
+	export const packageLock: PackageLockMethods;
+}

package/index.js

@@ -0,0 +1,4 @@
+'use strict';
+
+exports.packageJson = require('./lib/package-json');
+exports.packageLock = require('./lib/package-lock-json');

package/lib/github.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { name, version, homepage } = require('../package.json');
+
+/**
+ * @import { GitHubOptions } from '@rowanmanning/package-json-github'
+ */
+
+const userAgent = `${name}/${version} (${homepage})`;
+
+/**
+ * @param {GitHubOptions & { path: string }} options
+ * @returns {Promise<string>}
+ */
+exports.getRepoContent = async function getRepoContent(options) {
+	if (!options || typeof options !== 'object' || Array.isArray(options)) {
+		throw new TypeError('Invalid argument: options must be an object');
+	}
+	const { auth, owner, repo, path, ref } = options;
+	if (typeof auth !== 'string') {
+		throw new TypeError('Invalid argument: options.auth must be a string');
+	}
+	if (typeof owner !== 'string') {
+		throw new TypeError('Invalid argument: options.owner must be a string');
+	}
+	if (typeof repo !== 'string') {
+		throw new TypeError('Invalid argument: options.repo must be a string');
+	}
+	if (typeof path !== 'string') {
+		throw new TypeError('Invalid argument: options.path must be a string');
+	}
+	if (ref !== undefined && typeof ref !== 'string') {
+		throw new TypeError('Invalid argument: options.ref must be a string or undefined');
+	}
+	const endpoint = new URL(`https://api.github.com/repos/${owner}/${repo}/contents/${path}`);
+	if (ref) {
+		endpoint.searchParams.set('ref', ref);
+	}
+	const headers = {
+		accept: 'application/vnd.github.raw+json',
+		authorization: `Bearer ${auth}`,
+		'x-github-api-version': '2022-11-28',
+		'user-agent': userAgent
+	};
+	const response = await fetch(endpoint.toString(), { headers });
+	if (!response.ok) {
+		throw Object.assign(
+			new Error(`GitHub API responded with a ${response.status} status code`),
+			{
+				code: 'GITHUB_API_ERROR',
+				status: response.status,
+				statusCode: response.status
+			}
+		);
+	}
+	return await response.text();
+};

package/lib/package-json.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { getRepoContent } = require('./github');
+const {
+	packageJson: { fromString }
+} = require('@rowanmanning/package-json');
+
+/**
+ * @import { packageJson } from '@rowanmanning/package-json-github'
+ */
+
+/** @type {packageJson['fromGitHubRepo']} */
+exports.fromGitHubRepo = async function fromGitHubRepo(options) {
+	const optionsWithPath = Object.assign({ path: 'package.json' }, options);
+	return fromString(await getRepoContent(optionsWithPath));
+};

package/lib/package-lock-json.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { getRepoContent } = require('./github');
+const {
+	packageLock: { fromString }
+} = require('@rowanmanning/package-json');
+
+/**
+ * @import { packageLock } from '@rowanmanning/package-json-github'
+ */
+
+/** @type {packageLock['fromGitHubRepo']} */
+exports.fromGitHubRepo = async function fromGitHubRepo(options) {
+	const optionsWithPath = Object.assign({ path: 'package-lock.json' }, options);
+	return fromString(await getRepoContent(optionsWithPath));
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rowanmanning/package-json-github",
+  "version": "1.0.0",
+  "description": "Load and parse package.json and package-lock.json files from GitHub repositories",
+  "keywords": [],
+  "author": "Rowan Manning (https://rowanmanning.com/)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowanmanning/repo-tools.git",
+    "directory": "packages/package-json-github"
+  },
+  "homepage": "https://github.com/rowanmanning/repo-tools/tree/main/packages/package-json-github#readme",
+  "bugs": "https://github.com/rowanmanning/repo-tools/issues",
+  "license": "MIT",
+  "engines": {
+    "node": "18.x || 20.x || 22.x"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "dependencies": {
+    "@rowanmanning/package-json": "^1.0.0"
+  }
+}