@truesift/express 0.1.0

package/README.md

@@ -0,0 +1,567 @@
+# TrueSift Express SDK
+
+**TrueSift — Next-Gen Human Verification made in Germany**
+
+Server-side TypeScript SDK client for the TrueSift human verification API.
+
+This package is designed for Node.js and Express backend environments. It can also be used in other server-side Node.js runtimes, as long as secrets remain strictly backend-only.
+
+> Status: internal work in progress  
+> Version: 0.1.0  
+> Runtime: Node.js 20+  
+> Module format: ESM  
+> Language: TypeScript
+
+---
+
+## Purpose
+
+The SDK provides a small, typed, predictable service client for communicating with the TrueSift API.
+
+It is intentionally thin.
+
+The SDK should help backend projects:
+
+- create verification challenges
+- verify submitted challenges
+- normalize TrueSift API responses
+- work with typed decisions
+- handle transport and API errors consistently
+- keep secret credentials out of frontend code
+
+---
+
+## What this SDK is not
+
+This SDK is not:
+
+- a frontend SDK
+- a React package
+- a Next.js framework adapter
+- a UI package
+- an Express application
+- an Express router
+- a form library
+- a CAPTCHA widget
+- a database abstraction
+- a policy engine
+- an admin dashboard client
+
+Project backends remain responsible for their own business logic, request handling, form validation, error responses, telemetry, fail-open/fail-closed behavior, and user-facing messages.
+
+---
+
+## Server-side only
+
+This SDK must only be used in backend/server-side code.
+
+Do not import this package in:
+
+- React client components
+- browser scripts
+- frontend bundles
+- public JavaScript
+- code that exposes secrets through `NEXT_PUBLIC_*` variables
+
+The SDK uses a `secretKey`, which must never leave the backend.
+
+---
+
+## Package name
+
+Current package identity:
+
+```txt
+@truesift/express
+```
+
+The package is currently marked as private and is not published yet.
+
+Possible future distribution options:
+
+- public npm package
+- private npm package
+- GitHub Packages
+- internal registry
+- own package server
+- local workspace package
+
+The SDK architecture is intentionally independent from the final publishing strategy.
+
+---
+
+## Installation
+
+The package is not published yet.
+
+When published, installation will look like:
+
+```bash
+pnpm add @truesift/express
+```
+
+or:
+
+```bash
+npm install @truesift/express
+```
+
+For local development, use the package directly from the project directory or through a workspace setup.
+
+---
+
+## Requirements
+
+```txt
+Node.js >= 20.0.0
+TypeScript
+ESM runtime
+Server-side environment
+```
+
+The SDK uses the native `fetch` available in modern Node.js versions.
+
+No browser runtime is targeted.
+
+---
+
+## Planned public API
+
+The first stable SDK API is planned to expose:
+
+```ts
+createBotGuardClient(config)
+BotGuardClient
+client.createChallenge(input)
+client.verifyChallenge(input)
+
+isAllowed(result)
+isReview(result)
+isBlocked(result)
+
+BotGuardError
+BotGuardConfigError
+BotGuardRequestError
+BotGuardTimeoutError
+BotGuardAuthError
+BotGuardResponseError
+BotGuardApiError
+```
+
+The internal product name is now TrueSift, but the technical API may still use `BotGuard` naming in early versions where it reflects the original backend module and locked architecture.
+
+---
+
+## Configuration
+
+Recommended project environment variables:
+
+```env
+TRUESIFT_API_BASE_URL=https://your-truesift-api.example.com/api/v1/botguard
+TRUESIFT_SITE_KEY=your_site_key
+TRUESIFT_SECRET_KEY=your_secret_key
+TRUESIFT_DEFAULT_ACTION=website_check
+TRUESIFT_DEFAULT_ORIGIN=https://www.example.com
+TRUESIFT_TIMEOUT_MS=2500
+TRUESIFT_FAIL_OPEN=true
+```
+
+The SDK itself does not automatically read `.env` files.
+
+Backend projects should read and validate their own environment variables, then pass a configuration object to the SDK.
+
+Example:
+
+```ts
+import { createBotGuardClient } from '@truesift/express';
+
+const trueSiftClient = createBotGuardClient({
+  apiBaseUrl: process.env.TRUESIFT_API_BASE_URL,
+  siteKey: process.env.TRUESIFT_SITE_KEY,
+  secretKey: process.env.TRUESIFT_SECRET_KEY,
+  defaultAction: 'website_check',
+  defaultOrigin: 'https://www.example.com',
+  timeoutMs: 2500
+});
+```
+
+---
+
+## Secret key rules
+
+The `secretKey` is a backend-only credential.
+
+Never:
+
+- send it to the browser
+- expose it through frontend environment variables
+- log it
+- include it in screenshots
+- include it in client payloads
+- store it in public repositories
+- return it from API responses
+
+The SDK must redact sensitive values from error context and debug context.
+
+---
+
+## Site key rules
+
+The `siteKey` is a public identifier by design, but this SDK treats it as server-side configuration.
+
+A backend project may decide whether the frontend ever needs to know a site key.
+
+For backend-driven flows, the frontend does not need direct access to the site key.
+
+---
+
+## Challenge flow
+
+The SDK does not decide where or when challenges are created.
+
+A project may create challenges:
+
+- when a page loads
+- when a form opens
+- immediately before submit
+- through a server-side session flow
+- through another project-specific flow
+
+The SDK only provides the client operation.
+
+Conceptual usage:
+
+```ts
+const challenge = await trueSiftClient.createChallenge({
+  origin: 'https://www.example.com',
+  action: 'website_check',
+  path: '/website-check',
+  metadata: {
+    form: 'website-check'
+  }
+});
+```
+
+---
+
+## Verify flow
+
+The SDK sends challenge data and client signals to the TrueSift API.
+
+Conceptual usage:
+
+```ts
+const result = await trueSiftClient.verifyChallenge({
+  challengeId: body.challengeId,
+  challengeToken: body.challengeToken,
+  origin: 'https://www.example.com',
+  action: 'website_check',
+  path: '/website-check',
+  clientSignals: {
+    elapsedMs: body.elapsedMs,
+    honeypotValue: body.companyWebsite
+  },
+  metadata: {
+    form: 'website-check'
+  }
+});
+```
+
+The SDK normalizes the response, but the project decides what to do next.
+
+---
+
+## Decision model
+
+TrueSift decisions are normalized to:
+
+```txt
+allow
+review
+block
+```
+
+The SDK exposes helper functions:
+
+```ts
+isAllowed(result)
+isReview(result)
+isBlocked(result)
+```
+
+These helpers do not make business decisions.
+
+They only make backend code easier to read.
+
+---
+
+## Fail-open and fail-closed
+
+The SDK does not decide whether a request should continue when TrueSift is unavailable.
+
+That decision belongs to the project backend.
+
+Typical policies:
+
+```txt
+fail-open:
+  if TrueSift is unavailable, continue the business flow
+
+fail-closed:
+  if TrueSift is unavailable, reject the request
+```
+
+For early observe-mode integrations, fail-open is usually safer because real users should not be blocked by a temporary verification outage.
+
+---
+
+## Observe mode
+
+In observe mode, TrueSift can collect telemetry and return decisions without blocking real users.
+
+The SDK should return normalized result data.
+
+The project backend decides whether to ignore, store, review, or act on that result.
+
+---
+
+## Protect mode
+
+In protect mode, TrueSift may return a block decision.
+
+A block decision is a valid business result, not a transport error.
+
+The SDK must not throw an exception just because the decision is `block`.
+
+Transport errors are different and include:
+
+- network failure
+- timeout
+- invalid JSON
+- unexpected response shape
+- HTTP 401
+- HTTP 5xx
+- malformed API response
+
+---
+
+## Error model
+
+The SDK distinguishes between several error classes:
+
+```txt
+BotGuardConfigError
+BotGuardRequestError
+BotGuardTimeoutError
+BotGuardAuthError
+BotGuardResponseError
+BotGuardApiError
+```
+
+Expected meaning:
+
+```txt
+BotGuardConfigError:
+  missing or invalid SDK configuration
+
+BotGuardRequestError:
+  network-level request failure
+
+BotGuardTimeoutError:
+  request aborted after timeout
+
+BotGuardAuthError:
+  API returned an authentication or authorization error
+
+BotGuardResponseError:
+  API response was malformed or unexpected
+
+BotGuardApiError:
+  API returned a structured error response
+```
+
+---
+
+## Timeout behavior
+
+The SDK supports request timeouts.
+
+Recommended default:
+
+```txt
+2500ms
+```
+
+The timeout is implemented with `AbortController`.
+
+The SDK must clean up timers correctly after each request.
+
+---
+
+## Retry behavior
+
+The first SDK version does not retry requests by default.
+
+Especially important:
+
+```txt
+verifyChallenge() must not be retried automatically
+```
+
+Challenge tokens may be single-use.
+
+Retrying verification can produce incorrect behavior or falsely consume a token.
+
+---
+
+## Express usage concept
+
+The SDK does not provide Express routes or automatic middleware in the first version.
+
+A controller should remain project-specific.
+
+Conceptual controller flow:
+
+```txt
+1. Receive form submit
+2. Normalize request body
+3. Extract challenge fields
+4. Extract client signals
+5. Call verifyChallenge()
+6. If TrueSift transport error and project policy is fail-open:
+     continue business flow and store telemetry if needed
+7. If result is blocked and project is in protect mode:
+     return project-specific rejection response
+8. Otherwise:
+     continue the normal business flow
+```
+
+---
+
+## Next.js backend usage concept
+
+The same SDK may be used in Next.js route handlers, but this package must not import Next.js types.
+
+Conceptual flow:
+
+```txt
+app/api/some-form/route.ts
+        ↓
+server-only environment config
+        ↓
+createBotGuardClient()
+        ↓
+verifyChallenge()
+        ↓
+project-specific response handling
+```
+
+Do not import this SDK into client components.
+
+---
+
+## Security principles
+
+The SDK follows these principles:
+
+- no default logging
+- no secret logging
+- no frontend usage
+- no browser bundle usage
+- no business policy decisions
+- no automatic Express middleware in the first version
+- no automatic retries for challenge verification
+- runtime response validation
+- strict TypeScript types
+- minimal dependencies
+
+---
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Run typecheck:
+
+```bash
+pnpm typecheck
+```
+
+Build package:
+
+```bash
+pnpm build
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+Run all checks:
+
+```bash
+pnpm check
+```
+
+---
+
+## Current build setup
+
+The package currently uses:
+
+```txt
+TypeScript 6
+tsup
+Vitest
+Node.js 20 target
+ESM output
+DTS output
+```
+
+The generated package output is written to:
+
+```txt
+dist/
+```
+
+---
+
+## Repository status
+
+This package directory may later become:
+
+- a standalone Git repository
+- part of a monorepo
+- a private npm package source
+- a public npm package source
+- an internal TrueSift SDK workspace
+
+The package is designed to remain reusable regardless of the final repository and publishing strategy.
+
+---
+
+## License
+
+This package is currently proprietary and unpublished.
+
+See:
+
+```txt
+LICENSE
+```
+
+---
+
+## Product
+
+```txt
+TrueSift — Next-Gen Human Verification made in Germany
+```
+
+Developed by WebDigiTech.

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export { B as BotGuardApiError, c as BotGuardAuthError, d as BotGuardConfigError, e as BotGuardError, j as BotGuardRequestError, k as BotGuardResponseError, l as BotGuardTimeoutError, B as TrueSiftApiError, c as TrueSiftAuthError, d as TrueSiftConfigError, e as TrueSiftError, j as TrueSiftRequestError, k as TrueSiftResponseError, l as TrueSiftTimeoutError } from '../index-DWCqfBfQ.js';

package/dist/errors/index.js

@@ -0,0 +1,158 @@
+// src/errors/BotGuardError.ts
+var BotGuardError = class extends Error {
+  code;
+  statusCode;
+  requestId;
+  context;
+  constructor(options) {
+    const errorOptions = options.cause === void 0 ? void 0 : { cause: options.cause };
+    super(options.message, errorOptions);
+    this.name = new.target.name;
+    this.code = options.code;
+    if (options.statusCode !== void 0) {
+      this.statusCode = options.statusCode;
+    }
+    if (options.requestId !== void 0) {
+      this.requestId = options.requestId;
+    }
+    if (options.context !== void 0) {
+      this.context = options.context;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      ...this.statusCode !== void 0 ? { statusCode: this.statusCode } : {},
+      ...this.requestId !== void 0 ? { requestId: this.requestId } : {},
+      ...this.context !== void 0 ? { context: this.context } : {}
+    };
+  }
+};
+
+// src/errors/BotGuardConfigError.ts
+var DEFAULT_CONFIG_ERROR_MESSAGE = "TrueSift SDK configuration is invalid.";
+var BotGuardConfigError = class extends BotGuardError {
+  constructor(options = {}) {
+    const errorOptions = {
+      code: "TRUESIFT_CONFIG_ERROR",
+      message: options.message ?? DEFAULT_CONFIG_ERROR_MESSAGE,
+      ...options.context !== void 0 ? { context: options.context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+  }
+};
+
+// src/errors/BotGuardRequestError.ts
+var DEFAULT_REQUEST_ERROR_MESSAGE = "TrueSift API request failed.";
+var BotGuardRequestError = class extends BotGuardError {
+  constructor(options = {}) {
+    const errorOptions = {
+      code: "TRUESIFT_REQUEST_ERROR",
+      message: options.message ?? DEFAULT_REQUEST_ERROR_MESSAGE,
+      ...options.statusCode !== void 0 ? { statusCode: options.statusCode } : {},
+      ...options.requestId !== void 0 ? { requestId: options.requestId } : {},
+      ...options.context !== void 0 ? { context: options.context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+  }
+};
+
+// src/errors/BotGuardTimeoutError.ts
+var DEFAULT_TIMEOUT_ERROR_MESSAGE = "TrueSift API request timed out.";
+var BotGuardTimeoutError = class extends BotGuardError {
+  timeoutMs;
+  constructor(options = {}) {
+    const context = {
+      ...options.context ?? {},
+      ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+    };
+    const errorOptions = {
+      code: "TRUESIFT_TIMEOUT_ERROR",
+      message: options.message ?? DEFAULT_TIMEOUT_ERROR_MESSAGE,
+      ...options.requestId !== void 0 ? { requestId: options.requestId } : {},
+      ...Object.keys(context).length > 0 ? { context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+    if (options.timeoutMs !== void 0) {
+      this.timeoutMs = options.timeoutMs;
+    }
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      code: "TRUESIFT_TIMEOUT_ERROR",
+      ...this.timeoutMs !== void 0 ? { timeoutMs: this.timeoutMs } : {}
+    };
+  }
+};
+
+// src/errors/BotGuardAuthError.ts
+var DEFAULT_AUTH_ERROR_MESSAGE = "TrueSift API authentication failed.";
+var BotGuardAuthError = class extends BotGuardError {
+  constructor(options = {}) {
+    const errorOptions = {
+      code: "TRUESIFT_AUTH_ERROR",
+      message: options.message ?? DEFAULT_AUTH_ERROR_MESSAGE,
+      ...options.statusCode !== void 0 ? { statusCode: options.statusCode } : {},
+      ...options.requestId !== void 0 ? { requestId: options.requestId } : {},
+      ...options.context !== void 0 ? { context: options.context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+  }
+};
+
+// src/errors/BotGuardResponseError.ts
+var DEFAULT_RESPONSE_ERROR_MESSAGE = "TrueSift API returned an invalid response.";
+var BotGuardResponseError = class extends BotGuardError {
+  constructor(options = {}) {
+    const errorOptions = {
+      code: "TRUESIFT_RESPONSE_ERROR",
+      message: options.message ?? DEFAULT_RESPONSE_ERROR_MESSAGE,
+      ...options.statusCode !== void 0 ? { statusCode: options.statusCode } : {},
+      ...options.requestId !== void 0 ? { requestId: options.requestId } : {},
+      ...options.context !== void 0 ? { context: options.context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+  }
+};
+
+// src/errors/BotGuardApiError.ts
+var DEFAULT_API_ERROR_MESSAGE = "TrueSift API returned an error response.";
+var BotGuardApiError = class extends BotGuardError {
+  apiError;
+  constructor(options = {}) {
+    const context = {
+      ...options.context ?? {},
+      ...options.apiError !== void 0 ? { apiError: options.apiError } : {}
+    };
+    const errorOptions = {
+      code: "TRUESIFT_API_ERROR",
+      message: options.message ?? DEFAULT_API_ERROR_MESSAGE,
+      ...options.statusCode !== void 0 ? { statusCode: options.statusCode } : {},
+      ...options.requestId !== void 0 ? { requestId: options.requestId } : {},
+      ...Object.keys(context).length > 0 ? { context } : {},
+      ...options.cause !== void 0 ? { cause: options.cause } : {}
+    };
+    super(errorOptions);
+    if (options.apiError !== void 0) {
+      this.apiError = options.apiError;
+    }
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      code: "TRUESIFT_API_ERROR",
+      ...this.apiError !== void 0 ? { apiError: this.apiError } : {}
+    };
+  }
+};
+
+export { BotGuardApiError, BotGuardAuthError, BotGuardConfigError, BotGuardError, BotGuardRequestError, BotGuardResponseError, BotGuardTimeoutError, BotGuardApiError as TrueSiftApiError, BotGuardAuthError as TrueSiftAuthError, BotGuardConfigError as TrueSiftConfigError, BotGuardError as TrueSiftError, BotGuardRequestError as TrueSiftRequestError, BotGuardResponseError as TrueSiftResponseError, BotGuardTimeoutError as TrueSiftTimeoutError };