Enhancement APIs

.dnt.ts

@@ -14,12 +14,16 @@ await invokeDenoNodeJSTransformer({
 		"https://esm.sh/libsodium-wrappers@^0.7.15": {
 			name: "libsodium-wrappers",
 			version: "^0.7.15"
+		},
+		"https://raw.githubusercontent.com/hugoalh/is-json-es/v1.0.4/mod.ts": {
+			name: "@hugoalh/is-json",
+			version: "^1.0.4"
 		}
 	},
 	metadata: {
 		name: configJSR.getName(),
 		version: configJSR.getVersion(),
-		description: "A module to provide an easier sodium for GitHub secrets.",
+		description: "A module to provide an easier and simplified method for encrypt GitHub secrets.",
 		keywords: [
 			"github",
 			"sodium"

README.md

@@ -6,9 +6,7 @@
 [![JSR: @hugoalh/github-sodium](https://img.shields.io/jsr/v/@hugoalh/github-sodium?label=@hugoalh/github-sodium&labelColor=F7DF1E&logo=jsr&logoColor=000000&style=flat "JSR: @hugoalh/github-sodium")](https://jsr.io/@hugoalh/github-sodium)
 [![NPM: @hugoalh/github-sodium](https://img.shields.io/npm/v/@hugoalh/github-sodium?label=@hugoalh/github-sodium&labelColor=CB3837&logo=npm&logoColor=ffffff&style=flat "NPM: @hugoalh/github-sodium")](https://www.npmjs.com/package/@hugoalh/github-sodium)
 
-An ES (JavaScript & TypeScript) module to provide an easier sodium for GitHub secrets.
-
-This project is based on "[libsodium.js](https://github.com/jedisct1/libsodium.js)" with simplify for GitHub secrets.
+An ES (JavaScript & TypeScript) module to provide an easier and simplified method for encrypt GitHub secrets, based on the NPM package [`libsodium.js`](https://www.npmjs.com/package/libsodium-wrappers).
 
 ## 🔰 Begin
 
@@ -54,18 +52,31 @@ This project is based on "[libsodium.js](https://github.com/jedisct1/libsodium.j
 
 *This module does not require any runtime permission.*
 
-## 🧩 APIs
+## 🧩 APIs (Excerpt)
 
 - ```ts
   class GitHubSodiumSealer {
-    constructor(publicKey: string): GitHubSodiumSealer;
+    constructor(publicKey: string, keyID?: string);
     encrypt(value: string): string;
+    encryptToRequestPayload(value: string): GitHubRESTSetPublicKeyRequestBody;
+    getKeyID(): string | undefined;
+    get keyID(): string | undefined;
+    static createFromJSON(input: JSONObject): GitHubSodiumSealer;
+    static async createFromResponse(input: Response): Promise<GitHubSodiumSealer>;
   }
   ```
 - ```ts
-  function seal(publicKey: string, value: string): string;
+  interface GitHubRESTSetPublicKeyRequestBody {
+    encrypted_value: string;
+    key_id: string;
+  }
   ```
 
+> [!NOTE]
+> - For the full or prettier documentation, can visit via:
+>   - [Deno CLI `deno doc`](https://docs.deno.com/runtime/reference/cli/documentation_generator/)
+>   - [JSR](https://jsr.io/@hugoalh/github-sodium)
+
 ## ✍️ Examples
 
 - ```ts

jsr.jsonc

@@ -6,7 +6,8 @@
 		".": "./mod.ts"
 	},
 	"imports": {
-		"https://esm.sh/libsodium-wrappers@^0.7.15": "npm:libsodium-wrappers@^0.7.15"
+		"https://esm.sh/libsodium-wrappers@^0.7.15": "npm:libsodium-wrappers@^0.7.15",
+		"https://raw.githubusercontent.com/hugoalh/is-json-es/v1.0.4/mod.ts": "jsr:@hugoalh/is-json@^1.0.4"
 	},
 	"publish": {
 		"exclude": [

mod.ts

@@ -1,39 +1,110 @@
 import { Buffer } from "node:buffer";
 import libsodium from "https://esm.sh/libsodium-wrappers@^0.7.15";
+import {
+	isJSONObject,
+	type JSONObject
+} from "https://raw.githubusercontent.com/hugoalh/is-json-es/v1.0.4/mod.ts";
 await libsodium.ready;
+export interface GitHubRESTSetPublicKeyRequestBody {
+	encrypted_value: string;
+	key_id: string;
+}
 /**
  * GitHub sodium sealer for encrypt value to the GitHub secret value.
  */
 export class GitHubSodiumSealer {
 	get [Symbol.toStringTag](): string {
 		return "GitHubSodiumSealer";
 	}
+	#keyID?: string;
 	#publicKey: Buffer;
 	/**
 	 * Initialize the GitHub sodium sealer.
-	 * @param {string} publicKey Public key of the GitHub organization or repository, which need for encrypt value to the GitHub secret value before create or update a GitHub secret.
+	 * @param {string} publicKey Public key, which get from the GitHub organization or repository, need for encrypt value to the GitHub secret value before create or update the GitHub secret.
+	 * @param {string} [keyID] ID of the key, which get from the GitHub organization or repository, need for create or update the GitHub secret. This parameter is optional if no need to output as part of the {@linkcode Request} body.
 	 */
-	constructor(publicKey: string) {
+	constructor(publicKey: string, keyID?: string) {
+		if (!(
+			typeof keyID === "undefined" ||
+			(typeof keyID === "string" && keyID.length > 0)
+		)) {
+			throw new SyntaxError(`Parameter \`keyID\` is not \`undefined\`, or a string which is non empty!`);
+		}
 		if (!(publicKey.length > 0)) {
-			throw new SyntaxError(`Parameter \`publicKey\` is not a string which is non-empty!`);
+			throw new SyntaxError(`Parameter \`publicKey\` is not a string which is non empty!`);
 		}
+		this.#keyID = keyID;
 		this.#publicKey = Buffer.from(publicKey, "base64");
 	}
 	/**
 	 * Encrypt value to the GitHub secret value.
-	 * @param {string} value Value that need to encrypt as GitHub secret value.
+	 * @param {string} value Value that need to encrypt as the GitHub secret value.
 	 * @returns {string} An encrypted GitHub secret value.
 	 */
 	encrypt(value: string): string {
 		if (!(value.length > 0)) {
-			throw new SyntaxError(`Parameter \`value\` is not a string which is non-empty!`);
+			throw new SyntaxError(`Parameter \`value\` is not a string which is non empty!`);
 		}
 		return Buffer.from(libsodium.crypto_box_seal(Buffer.from(value), this.#publicKey)).toString("base64");
 	}
+	/**
+	 * Encrypt value to the GitHub secret value, and output as part of the {@linkcode Request} body for create or update GitHub secret via the GitHub REST API.
+	 * @param {string} value Value that need to encrypt as the GitHub secret value.
+	 * @returns {GitHubRESTSetPublicKeyRequestBody} Part of the {@linkcode Request} body for create or update GitHub secret via the GitHub REST API.
+	 */
+	encryptToRequestPayload(value: string): GitHubRESTSetPublicKeyRequestBody {
+		if (this.#keyID !== "string") {
+			throw new Error(`\`keyID\` was not defined at the initialize stage!`);
+		}
+		return {
+			encrypted_value: this.encrypt(value),
+			key_id: this.#keyID
+		};
+	}
+	/**
+	 * Get the ID of the key.
+	 * @returns {string | undefined} ID of the key.
+	 */
+	getKeyID(): string | undefined {
+		return this.#keyID;
+	}
+	/**
+	 * Get the ID of the key.
+	 * @returns {string | undefined} ID of the key.
+	 */
+	get keyID(): string | undefined {
+		return this.#keyID;
+	}
+	/**
+	 * Initialize the GitHub sodium sealer from the {@linkcode Response} JSON body.
+	 * @param {JSONObject} input {@linkcode Response} JSON body.
+	 * @returns {GitHubSodiumSealer} GitHub sodium sealer.
+	 */
+	static createFromJSON(input: JSONObject): GitHubSodiumSealer {
+		if (
+			typeof input.key !== "string" ||
+			typeof input.key_id !== "string"
+		) {
+			throw new Error(`Parameter \`input\` is not a valid response JSON body!`);
+		}
+		return new this(input.key, input.key_id);
+	}
+	/**
+	 * Initialize the GitHub sodium sealer from the {@linkcode Response}.
+	 * @param {Response} input {@linkcode Response}.
+	 * @returns {Promise<GitHubSodiumSealer>} GitHub sodium sealer.
+	 */
+	static async createFromResponse(input: Response): Promise<GitHubSodiumSealer> {
+		const responsePayload = await input.clone().json();
+		if (!isJSONObject(responsePayload)) {
+			throw new Error(`Parameter \`input\` is not a valid response!`);
+		}
+		return GitHubSodiumSealer.createFromJSON(responsePayload);
+	}
 	/**
 	 * Encrypt value to the GitHub secret value.
-	 * @param {string} publicKey Public key of the GitHub organization or repository, which need for encrypt value to the GitHub secret value before create or update a GitHub secret.
-	 * @param {string} value Value that need to encrypt as GitHub secret value.
+	 * @param {string} publicKey Public key, which get from the GitHub organization or repository, need for encrypt value to the GitHub secret value before create or update the GitHub secret.
+	 * @param {string} value Value that need to encrypt as the GitHub secret value.
 	 * @returns {string} An encrypted GitHub secret value.
 	 * @deprecated Migrate to `new GitHubSodiumSealer(publicKey).encrypt(value)`.
 	 */
@@ -44,9 +115,10 @@ export class GitHubSodiumSealer {
 export default GitHubSodiumSealer;
 /**
  * Encrypt value to the GitHub secret value.
- * @param {string} publicKey Public key of the GitHub organization or repository, which need for encrypt value to the GitHub secret value before create or update a GitHub secret.
- * @param {string} value Value that need to encrypt as GitHub secret value.
+ * @param {string} publicKey Public key, which get from the GitHub organization or repository, need for encrypt value to the GitHub secret value before create or update the GitHub secret.
+ * @param {string} value Value that need to encrypt as the GitHub secret value.
  * @returns {string} An encrypted GitHub secret value.
+ * @deprecated Migrate to `new GitHubSodiumSealer(publicKey).encrypt(value)`.
  */
 export function seal(publicKey: string, value: string): string {
 	return new GitHubSodiumSealer(publicKey).encrypt(value);