@friendlycaptcha/server-sdk 0.1.0 → 0.1.2

package/example/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "friendly-captcha-example",
+  "version": "1.0.0",
+  "description": "Friendly Captcha V2 Javascript SDK integration example",
+  "main": "index.js",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "node --import tsx src/index.ts"
+  },
+  "author": "Friendly Captcha GmbH",
+  "license": "MIT",
+  "dependencies": {
+    "@friendlycaptcha/server-sdk": "^0.1.0",
+    "ejs": "^3.1.9",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.5",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  }
+}

package/example/src/index.ts

@@ -0,0 +1,84 @@
+import express, { Request, Response } from "express";
+import { FriendlyCaptchaClient } from "@friendlycaptcha/server-sdk";
+
+type FormMessage = {
+  subject: string;
+  message: string;
+};
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+const FRC_SITEKEY = process.env.FRC_SITEKEY;
+const FRC_APIKEY = process.env.FRC_APIKEY;
+
+// Optionally we can pass in custom endpoints to be used, such as "eu".
+const FRC_SITEVERIFY_ENDPOINT = process.env.FRC_SITEVERIFY_ENDPOINT;
+const FRC_WIDGET_ENDPOINT = process.env.FRC_WIDGET_ENDPOINT;
+
+if (!FRC_SITEKEY || !FRC_APIKEY) {
+  console.error(
+    "Please set the FRC_SITEKEY and FRC_APIKEY environment values before running this example to your Friendly Captcha sitekey and API key respectively.",
+  );
+  process.exit(1);
+}
+
+const frcClient = new FriendlyCaptchaClient({
+  apiKey: FRC_APIKEY,
+  sitekey: FRC_SITEKEY,
+  siteverifyEndpoint: FRC_SITEVERIFY_ENDPOINT, // optional, defaults to "global"
+});
+
+app.set("view engine", "ejs");
+app.use(express.urlencoded({ extended: true }));
+
+app.get("/", (req: Request, res: Response) => {
+  res.render("index", {
+    message: "",
+    sitekey: FRC_SITEKEY,
+    widgetEndpoint: FRC_WIDGET_ENDPOINT,
+  });
+});
+
+app.post("/", async (req: Request, res: Response) => {
+  const formData = req.body;
+  const formMessage = formData as FormMessage;
+
+  const frcCaptchaResponse = formData["frc-captcha-response"];
+  const result = await frcClient.verifyCaptchaResponse(frcCaptchaResponse);
+  if (!result.wasAbleToVerify()) {
+    // In this case we were not actually able to verify the response embedded in the form, but we may still want to accept it.
+    // It could mean there is a network issue or that the service is down. In those cases you generally want to accept submissions anyhow.
+    // That's why we use `shouldAccept()` below to actually accept or reject the form submission. It will return true in these cases.
+
+    if (result.isClientError()) {
+      // Something is wrong with our configuration, check your API key!
+      // Send yourself an alert to fix this! Your site is unprotected until you fix this.
+      console.error("CAPTCHA CONFIG ERROR: ", result.getErrorCode(), result.getResponseError());
+    } else {
+      console.error("Failed to verify captcha response: ", result.getErrorCode(), result.getResponseError());
+    }
+  }
+
+  if (!result.shouldAccept()) {
+    res.render("index", {
+      message: "❌ Anti-robot check failed, please try again.",
+      sitekey: FRC_SITEKEY,
+      widgetEndpoint: FRC_WIDGET_ENDPOINT,
+    });
+    return;
+  }
+
+  // The captcha was OK, process the form.
+  formMessage; // Normally we would use the form data in `formMessage` here and submit it to our database.
+
+  res.render("index", {
+    message: "✅ Your message has been submitted successfully.",
+    sitekey: FRC_SITEKEY,
+    widgetEndpoint: FRC_WIDGET_ENDPOINT,
+  });
+});
+
+app.listen(port, () => {
+  console.log(`Server running at http://localhost:${port}`);
+});

package/example/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/example/views/index.ejs

@@ -0,0 +1,86 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+  <title>Friendly Captcha Javascript SDK example</title>
+  <style>
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans",
+        "Helvetica Neue", sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 100vh;
+      width: 100vw;
+      background-color: #f2f2f2;
+    }
+
+    h1 {
+      font-size: 1.4em;
+    }
+
+    main {
+      width: 100%;
+      max-width: 680px;
+    }
+
+    .message {
+      width: 100%;
+      padding: 0.5em 2em;
+      margin: 1.5em 0;
+      border-radius: 8px;
+    }
+
+    .message h2 {
+      margin-bottom: 0;
+    }
+
+    label {
+      display: block;
+    }
+  </style>
+
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@0.1.8/site.min.js" async defer></script>
+  <script nomodule src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@0.1.8/site.compat.min.js" async
+    defer></script>
+
+  <!-- You can change the data-api-endpoint via this tag. More info here https://developer.friendlycaptcha.com/docs/sdk/configuration -->
+  <!-- <meta name="frc-api-endpoint" content=".">  -->
+</head>
+
+<body>
+  <main>
+    <h1>Friendly Captcha JavaScript SDK form</h1>
+    <% if (message) { %>
+      <p>
+        <%= message %>
+      </p>
+      <% } %>
+        <form method="POST">
+          <div class="form-group">
+            <label>Subject:</label><br />
+            <input type="text" name="subject" /><br />
+            <label>Message:</label><br />
+            <textarea name="message"></textarea><br />
+            <div class="frc-captcha" data-sitekey="<%= sitekey %>" <% if (widgetEndpoint) { %> data-api-endpoint="<%=
+                widgetEndpoint %>" <% } %>></div>
+            <input style="margin-top: 1em" type="submit" value="Submit" />
+          </div>
+        </form>
+  </main>
+
+  <script>
+    if (window.history.replaceState) {
+      window.history.replaceState(null, null, window.location.href);
+    }
+  </script>
+</body>
+
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friendlycaptcha/server-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Serverside client SDK for the Friendly Captcha V2 API",
   "main": "dist/index.js",
   "type": "module",
@@ -12,7 +12,8 @@
     "build:docs": "rm -rf build/docs && api-documenter markdown --output-folder docs --input temp/",
     "test": "ava test/**/*.ts --timeout=1m",
     "api-extractor": "api-extractor",
-    "fmt": "prettier src/**/*.ts test/**/*.ts package.json --write"
+    "fmt": "prettier src/**/*.ts test/**/*.ts example/**/*.ts package.json --write",
+    "fmt:ci": "prettier src/**/*.ts test/**/*.ts example/**/*.ts package.json --check"
   },
   "author": "Friendly Captcha GmbH",
   "license": "MIT",

package/src/api/index.ts

@@ -1 +1 @@
-export * from "./types";
+export * from "./types.js";

package/src/client/client.ts

@@ -84,7 +84,10 @@ export class FriendlyCaptchaClient {
    *   * `sitekey`: The sitekey to use for this request. Defaults to the sitekey passed to the constructor (if any).
    * @returns A promise that always resolves to a `VerifyResult` object, which contains the fields `shouldAccept()` and `wasAbleToVerify()`. This promise never rejects.
    */
-  public verifyCaptchaResponse(response: string, opts: { timeout?: number, sitekey?: string } = {}): Promise<VerifyResult> {
+  public verifyCaptchaResponse(
+    response: string,
+    opts: { timeout?: number; sitekey?: string } = {},
+  ): Promise<VerifyResult> {
     const siteverifyRequest: SiteverifyRequest = {
       response,
     };
@@ -105,7 +108,7 @@ export class FriendlyCaptchaClient {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json",
-      "X-Frc-Sdk": "friendly-captcha-javascript-sdk@" + SDK_VERSION,
+      "Frc-Sdk": "friendly-captcha-javascript-sdk@" + SDK_VERSION,
       "X-Api-Key": this.apiKey,
     };
 

package/src/client/errors.ts

@@ -1,33 +1,33 @@
 /**
  * Failed to encode the captcha response. This means the captcha response was invalid and should never be accepted.
- * 
+ *
  * @public
  */
 export const FAILED_TO_ENCODE_ERROR_CODE = "failed_to_encode_request";
 /**
- * 
+ *
  * The request couldn't be made, perhaps there is a network outage, DNS issue, or the API is unreachable.
- * 
+ *
  * @public
  */
 export const REQUEST_FAILED_ERROR_CODE = "request_failed";
 /**
- * 
+ *
  * The request couldn't be made, perhaps there is a network outage, DNS issue, or the API is unreachable.
- * 
+ *
  * @public
  */
 export const REQUEST_FAILED_TIMEOUT_ERROR_CODE = "request_failed_due_to_timeout";
 /**
  * An error occured on the client side that could've been prevented. This generally means your configuration is wrong.
- * 
+ *
  * Check your API key and sitekey.
  * @public
  */
 export const FAILED_DUE_TO_CLIENT_ERROR_CODE = "request_failed_due_to_client_error";
 /**
  * The response from the Friendly Captcha API could not be decoded.
- * 
+ *
  * @public
  */
 export const FAILED_TO_DECODE_RESPONSE_ERROR_CODE = "verification_response_could_not_be_decoded";

package/src/client/index.ts

@@ -1,3 +1,3 @@
 export * from "./client.js";
 export * from "./result.js";
-export * from "./errors.js";
+export * from "./errors.js";

package/src/client/result.ts

@@ -1,4 +1,4 @@
-import type { SiteverifyErrorResponseErrorData, SiteverifyResponse } from "../api";
+import type { SiteverifyErrorResponseErrorData, SiteverifyResponse } from "../api/index.js";
 import {
   FAILED_DUE_TO_CLIENT_ERROR_CODE,
   FAILED_TO_DECODE_RESPONSE_ERROR_CODE,
@@ -10,14 +10,13 @@ import {
 
 /**
  * The result of a captcha siteverify request.
- * 
+ *
  * @public
  */
 export class VerifyResult {
-
   private strict: boolean;
   /**
-   * The HTTP status code of the response.  
+   * The HTTP status code of the response.
    * `-1` if there was no response.
    */
   public status: number = -1;
@@ -40,7 +39,7 @@ export class VerifyResult {
   }
 
   /**
-   * @returns Whether the captcha should be accepted.   
+   * @returns Whether the captcha should be accepted.
    * Note that this does not necessarily mean it was verified.
    */
   public shouldAccept(): boolean {
@@ -96,7 +95,9 @@ export class VerifyResult {
    * Something went wrong making the request to the Friendly Captcha API, perhaps there is a network connection issue?
    */
   public isRequestOrTimeoutError(): boolean {
-    return this.clientErrorType === REQUEST_FAILED_ERROR_CODE || this.clientErrorType === REQUEST_FAILED_TIMEOUT_ERROR_CODE;
+    return (
+      this.clientErrorType === REQUEST_FAILED_ERROR_CODE || this.clientErrorType === REQUEST_FAILED_TIMEOUT_ERROR_CODE
+    );
   }
 
   /**
@@ -139,7 +140,7 @@ export class VerifyResult {
    * If this is false, you should notify yourself and use `getErrorCode()` and `getResponseError()` to see what is wrong.
    */
   public wasAbleToVerify(): boolean {
-    // If we failed to encode, we actually consider `wasAbleToVerify` to be true. This is because we don't want to 
+    // If we failed to encode, we actually consider `wasAbleToVerify` to be true. This is because we don't want to
     // alert on failed encoding: an attacker could send such malformed data that it fails to encode.
     if (this.isEncodeError()) {
       return true;

package/src/client/version.gen.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated by scripts/updateVersion.mjs
 // Do not edit this file directly
-export const SDK_VERSION = "0.1.0";
+export const SDK_VERSION = "0.1.2";

package/test/client/client.test.ts

@@ -34,15 +34,14 @@ test("unencodable response gets rejected", async (t) => {
 });
 
 test("request failure gets accepted", async (t) => {
-    const client = new FriendlyCaptchaClient({ apiKey: "my-api-key", siteverifyEndpoint: "http://localhost:9999" }); // Assumes nothing is listening on port 9999
-    const result = await client.verifyCaptchaResponse("something");
-  
-    t.false(result.isEncodeError());
-    t.false(result.isClientError());
-    t.true(result.isRequestOrTimeoutError());
-    t.false(result.isDecodeError());
-  
-    t.true(result.shouldAccept());
-    t.false(result.shouldReject());
-  });
-  
+  const client = new FriendlyCaptchaClient({ apiKey: "my-api-key", siteverifyEndpoint: "http://localhost:9999" }); // Assumes nothing is listening on port 9999
+  const result = await client.verifyCaptchaResponse("something");
+
+  t.false(result.isEncodeError());
+  t.false(result.isClientError());
+  t.true(result.isRequestOrTimeoutError());
+  t.false(result.isDecodeError());
+
+  t.true(result.shouldAccept());
+  t.false(result.shouldReject());
+});