@midnightntwrk/faucet-client 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# Faucet Client
+
+A small package, allowing to use Faucet functionality in a programmatic way.
+Its API is mostly a factory function to initialize the client, which can later
+be used to request tokens from the faucet.
+
+## Example
+
+```ts
+import { FaucetClient } from '@midnightntwrk/faucet-client';
+
+const client = FaucetClient("http://localhost:5300/api");
+const authToken = await client.login("<username>", "<password>");
+const initialized = client.init(authToken);
+const { transactionIdentifier } = initialized.requestTokens("<my wallet address>");
+```

package/dist/FaucetClient.d.ts

@@ -0,0 +1,30 @@
+import { ErrorResponse, FaucetClientRequests } from "@midnightntwrk/faucet-internal-api";
+/**
+ * FaucetClient-specific subclass of `Error`
+ */
+export declare class ClientError extends Error {
+    /**
+     * Error type. Following values are expected:
+     *
+     * - "decoding_error" -- to indicate decoding of request or response payload failed (is generally not expected when using the client)
+     * - "error" -- to indicate general/unexpected error that occurred when processing a request
+     * - "auth_error" -- to indicate authentication error
+     * - "rate_limit_error" -- to indicate exceeding rate limit set in place
+     */
+    readonly type: ErrorResponse["status"];
+    constructor(type: ErrorResponse["status"], message: string);
+}
+/**
+ * Client's entrypoint. It takes  and (optionally) fetch function to use.
+ * @param url - API url, like `http://localhost:5300/api` in local development
+ * @param pollInterval - how often check request status
+ * @param fetchFn - fetch function to use. By default it is `global.fetch`, but in case of additional
+ *   configurations needed it is possible to override it with any compatible function
+ */
+interface FaucetClientI {
+    url: string;
+    pollInterval: number;
+}
+export declare const FaucetClient: ({ url, pollInterval, }: FaucetClientI) => FaucetClientRequests;
+export {};
+//# sourceMappingURL=FaucetClient.d.ts.map

package/dist/FaucetClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaucetClient.d.ts","sourceRoot":"","sources":["../src/FaucetClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,aAAa,EAEb,oBAAoB,EAErB,MAAM,oCAAoC,CAAC;AAM5C;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC;;;;;;;OAOG;IACH,SAAgB,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;gBAElC,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM;CAI3D;AAsDD;;;;;;GAMG;AAEH,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AACD,eAAO,MAAM,YAAY,GAAI,wBAG1B,aAAa,KAAG,oBAuFlB,CAAC"}

package/dist/FaucetClient.js

@@ -0,0 +1,125 @@
+import { dripRequestCodec, dripResponseCodec, errorResponseCodec, } from "@midnightntwrk/faucet-internal-api";
+import { either } from "fp-ts";
+import * as t from "io-ts";
+import { PathReporter } from "io-ts/lib/PathReporter.js";
+import { catchError, distinctUntilChanged, from, of, shareReplay, switchMap, timer } from "rxjs";
+/**
+ * FaucetClient-specific subclass of `Error`
+ */
+export class ClientError extends Error {
+    /**
+     * Error type. Following values are expected:
+     *
+     * - "decoding_error" -- to indicate decoding of request or response payload failed (is generally not expected when using the client)
+     * - "error" -- to indicate general/unexpected error that occurred when processing a request
+     * - "auth_error" -- to indicate authentication error
+     * - "rate_limit_error" -- to indicate exceeding rate limit set in place
+     */
+    type;
+    constructor(type, message) {
+        super(message);
+        this.type = type;
+    }
+}
+const parseResponse = (codec) => (response) => {
+    const decodeResult = codec.decode(response);
+    return either.fold((errors) => Promise.resolve(errors)
+        .then(t.failures)
+        .then(PathReporter.report)
+        .then((array) => array.join("\n"))
+        .then((message) => Promise.reject(new Error(message))), (value) => Promise.resolve(value))(decodeResult);
+};
+const parseDripResponse = parseResponse(dripResponseCodec);
+const parseJSON = async (response) => {
+    if (response.ok) {
+        return response.json();
+    }
+    else if (!response.ok && response.status === 401) {
+        return response.text().then((text) => Promise.reject(new ClientError("auth_error", text)));
+    }
+    else if (!response.ok && response.status === 429) {
+        return response
+            .text()
+            .then((text) => Promise.reject(new ClientError("rate_limit_error", text)));
+    }
+    else {
+        return response.json().then((parsed) => {
+            const maybeKnownError = errorResponseCodec.decode(parsed);
+            const error = either.fold(() => {
+                // Try to extract error message from drip API error format
+                const dripError = parsed;
+                if (dripError.error) {
+                    return new ClientError("error", dripError.error);
+                }
+                return new ClientError("decoding_error", JSON.stringify(parsed));
+            }, (err) => new ClientError(err.status, err.message))(maybeKnownError);
+            return Promise.reject(error);
+        });
+    }
+};
+export const FaucetClient = ({ url, pollInterval = 10_000, }) => {
+    const pollForResponse = (dripId, errorRetriesLeft = 100) => {
+        const makeCall = () => {
+            return fetch(`${url}/drips/${dripId}`, {
+                headers: {
+                    "Content-Type": "application/json",
+                },
+            })
+                .then(parseJSON)
+                .then(parseDripResponse);
+        };
+        const delay = () => new Promise((resolve) => {
+            setTimeout(resolve, pollInterval + Math.round((Math.random() * 2 * pollInterval) / 5 - pollInterval / 5)); // By default every 10s +/- 2s
+        });
+        return delay()
+            .then(() => makeCall())
+            .then((drip) => {
+            switch (drip.status) {
+                case "PENDING":
+                    return pollForResponse(dripId, errorRetriesLeft);
+                case "CONFIRMED":
+                    return Promise.resolve(drip);
+                case "FAILED":
+                    return Promise.reject(new ClientError("error", drip.error ?? "Drip failed"));
+            }
+        }, (error) => {
+            // eslint-disable-next-line no-console
+            console.error("Got error from faucet", error);
+            if (errorRetriesLeft >= 1) {
+                return pollForResponse(dripId, errorRetriesLeft - 1);
+            }
+            else {
+                throw new ClientError("error", String(error));
+            }
+        });
+    };
+    const healthStatus$ = timer(0, 30_000).pipe(switchMap(() => from(fetch(`${url}/health`)
+        .then((response) => response.json())
+        .then((data) => {
+        const status = data.status === "SERVING"
+            ? "ok"
+            : "not_ok";
+        return { status };
+    })).pipe(catchError(() => of({ status: "not_ok" })))), distinctUntilChanged((prev, curr) => prev.status === curr.status), shareReplay(1));
+    return {
+        requestTokens(address, captchaToken, amount) {
+            const request = {
+                recipientAddress: address,
+                amount: BigInt(amount),
+            };
+            return fetch(`${url}/drips`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Captcha-Token": captchaToken,
+                },
+                body: JSON.stringify(dripRequestCodec.encode(request)),
+            })
+                .then(parseJSON)
+                .then(parseDripResponse)
+                .then((drip) => pollForResponse(drip?.dripId));
+        },
+        healthStatus$,
+    };
+};
+//# sourceMappingURL=FaucetClient.js.map

package/dist/FaucetClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaucetClient.js","sourceRoot":"","sources":["../src/FaucetClient.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./FaucetClient.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./FaucetClient.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@midnightntwrk/faucet-client",
+  "version": "1.0.0",
+  "description": "Midnight faucet library",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/midnightntwrk/midnight-faucet-api.git"
+  },
+  "author": "IOHK",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint --max-warnings=0",
+    "build": "tsc -b ./tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "yarn build",
+    "do-publish": "yarn npm publish"
+  },
+  "files": [
+    "dist/"
+  ],
+  "devDependencies": {
+    "eslint": "10.10.0",
+    "fast-check": "4.9.0",
+    "testcontainers": "12.1.0",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@midnightntwrk/faucet-internal-api": "^1.0.0",
+    "luxon": "^3.4.3"
+  },
+  "peerDependencies": {
+    "fp-ts": "^2.16.0",
+    "io-ts": "^2.2.20",
+    "rxjs": "^7.5.5"
+  }
+}