@truesift/express 0.1.0 → 0.1.1

package/README.md

@@ -4,13 +4,15 @@
 
 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.
+`@truesift/express` is designed for backend environments such as Express, Node.js services, and server-side route handlers. It must not be imported into browser/client code.
 
-> Status: internal work in progress  
-> Version: 0.1.0  
-> Runtime: Node.js 20+  
-> Module format: ESM  
-> Language: TypeScript
+```txt
+Package: @truesift/express
+Runtime: Node.js 20+
+Module format: ESM
+Language: TypeScript
+License: MIT
+```
 
 ---
 
@@ -18,9 +20,7 @@ This package is designed for Node.js and Express backend environments. It can al
 
 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:
+It helps backend projects:
 
 - create verification challenges
 - verify submitted challenges
@@ -29,6 +29,8 @@ The SDK should help backend projects:
 - handle transport and API errors consistently
 - keep secret credentials out of frontend code
 
+The SDK is intentionally thin. It does not own your application logic.
+
 ---
 
 ## What this SDK is not
@@ -37,7 +39,7 @@ This SDK is not:
 
 - a frontend SDK
 - a React package
-- a Next.js framework adapter
+- a Next.js client package
 - a UI package
 - an Express application
 - an Express router
@@ -47,7 +49,7 @@ This SDK is not:
 - 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.
+Your backend remains responsible for request handling, validation, storage, user-facing messages, telemetry, fail-open/fail-closed behavior, and business decisions.
 
 ---
 
@@ -61,41 +63,15 @@ Do not import this package in:
 - 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
+- files using `NEXT_PUBLIC_*` secrets
+- any code that can be shipped to the browser
 
-The SDK architecture is intentionally independent from the final publishing strategy.
+The SDK uses a `secretKey`. That key must never leave the backend.
 
 ---
 
 ## Installation
 
-The package is not published yet.
-
-When published, installation will look like:
-
 ```bash
 pnpm add @truesift/express
 ```
@@ -106,168 +82,249 @@ or:
 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
+## Environment configuration
 
-The first stable SDK API is planned to expose:
+The SDK does **not** automatically read `.env` files.
 
-```ts
-createBotGuardClient(config)
-BotGuardClient
-client.createChallenge(input)
-client.verifyChallenge(input)
+Your backend application must read and validate environment variables, then pass the resolved values to `createTrueSiftClient()` or `createBotGuardClient()`.
 
-isAllowed(result)
-isReview(result)
-isBlocked(result)
+Recommended backend environment variables:
 
-BotGuardError
-BotGuardConfigError
-BotGuardRequestError
-BotGuardTimeoutError
-BotGuardAuthError
-BotGuardResponseError
-BotGuardApiError
+```env
+TRUESIFT_API_BASE_URL=https://your-truesift-api.example.com/api/v1/botguard
+TRUESIFT_SITE_KEY=site_xxxxxxxxxxxxxxxxxxxx
+TRUESIFT_SECRET_KEY=secret_xxxxxxxxxxxxxxxxxxxx
+TRUESIFT_DEFAULT_ORIGIN=https://www.example.com
+TRUESIFT_DEFAULT_ACTION=website_check
+TRUESIFT_TIMEOUT_MS=2500
+TRUESIFT_FAIL_OPEN=true
 ```
 
-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.
+`TRUESIFT_FAIL_OPEN` is **not** an SDK option. It is a project-level policy flag. Your backend decides what to do when TrueSift is unavailable.
 
 ---
 
-## Configuration
+## Where do the keys come from?
 
-Recommended project environment variables:
+The SDK does not generate `siteKey` or `secretKey`.
 
-```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
+They must be issued by the TrueSift service owner, admin panel, provisioning script, or trusted internal configuration process.
+
+Typical provisioning model:
+
+```txt
+1. A site/application is registered in the TrueSift service.
+2. The service issues a siteKey and secretKey for that site.
+3. The backend stores these values in its private environment configuration.
+4. The backend creates the SDK client using these values.
+5. The frontend never receives the secretKey.
+```
+
+Credential meaning:
+
+```txt
+TRUESIFT_API_BASE_URL
+  Base URL of the TrueSift API service.
+
+TRUESIFT_SITE_KEY
+  Site/application identifier. It identifies which protected site or app is making the request.
+
+TRUESIFT_SECRET_KEY
+  Backend-only credential used to verify trusted server-side requests.
+
+TRUESIFT_DEFAULT_ORIGIN
+  The default public origin of the protected site.
+
+TRUESIFT_DEFAULT_ACTION
+  A stable action name such as website_check, contact_form, lead_form, ticket_public_submit.
+
+TRUESIFT_TIMEOUT_MS
+  SDK request timeout in milliseconds. Recommended default: 2500.
+
+TRUESIFT_FAIL_OPEN
+  Optional application policy. If true, your app may continue the business flow when TrueSift is unavailable.
 ```
 
-The SDK itself does not automatically read `.env` files.
+Never create or hard-code fake production secrets in source code.
 
-Backend projects should read and validate their own environment variables, then pass a configuration object to the SDK.
+---
 
-Example:
+## Minimal backend configuration example
 
 ```ts
-import { createBotGuardClient } from '@truesift/express';
+import { createTrueSiftClient } from '@truesift/express';
 
-const trueSiftClient = createBotGuardClient({
+const trueSiftClient = createTrueSiftClient({
   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
+  defaultOrigin: process.env.TRUESIFT_DEFAULT_ORIGIN,
+  defaultAction: process.env.TRUESIFT_DEFAULT_ACTION,
+  timeoutMs: Number(process.env.TRUESIFT_TIMEOUT_MS ?? 2500),
 });
 ```
 
+For production projects, validate these values with your existing config layer before creating the client.
+
 ---
 
-## Secret key rules
+## Optional configuration pattern
 
-The `secretKey` is a backend-only credential.
+For observe-mode or staged integrations, you may keep TrueSift optional in the host backend.
 
-Never:
+Example policy:
 
-- 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
+```txt
+if TrueSift config is missing:
+  do not create the SDK client
+  continue the main business flow
+  log a short non-secret warning in development only
+
+if TrueSift request fails:
+  use project policy:
+    fail-open  -> continue flow
+    fail-closed -> reject request
+```
 
-The SDK must redact sensitive values from error context and debug context.
+This policy belongs to your backend application, not the SDK.
 
 ---
 
-## Site key rules
+## Public API
 
-The `siteKey` is a public identifier by design, but this SDK treats it as server-side configuration.
+Main client API:
 
-A backend project may decide whether the frontend ever needs to know a site key.
+```ts
+createTrueSiftClient(config)
+createBotGuardClient(config)
 
-For backend-driven flows, the frontend does not need direct access to the site key.
+TrueSiftClient
+BotGuardClient
 
----
+client.createChallenge(input)
+client.verifyChallenge(input)
+```
 
-## Challenge flow
+Decision helpers:
 
-The SDK does not decide where or when challenges are created.
+```ts
+isAllowed(result)
+isReview(result)
+isBlocked(result)
 
-A project may create challenges:
+isAllowedDecision(decision)
+isReviewDecision(decision)
+isBlockedDecision(decision)
 
-- when a page loads
-- when a form opens
-- immediately before submit
-- through a server-side session flow
-- through another project-specific flow
+createDecisionFlags(decision)
+normalizeDecision(value)
+isTrueSiftDecision(value)
+```
 
-The SDK only provides the client operation.
+Error classes:
 
-Conceptual usage:
+```ts
+TrueSiftError
+TrueSiftConfigError
+TrueSiftRequestError
+TrueSiftTimeoutError
+TrueSiftAuthError
+TrueSiftResponseError
+TrueSiftApiError
+```
+
+Compatibility aliases with the original technical BotGuard naming are also exported:
+
+```ts
+BotGuardError
+BotGuardConfigError
+BotGuardRequestError
+BotGuardTimeoutError
+BotGuardAuthError
+BotGuardResponseError
+BotGuardApiError
+```
+
+---
+
+## Creating a challenge
 
 ```ts
 const challenge = await trueSiftClient.createChallenge({
-  origin: 'https://www.example.com',
-  action: 'website_check',
   path: '/website-check',
   metadata: {
-    form: 'website-check'
-  }
+    form: 'website-check',
+  },
 });
 ```
 
----
+If `siteKey`, `origin`, or `action` are not provided in the input, the SDK uses the configured defaults.
 
-## Verify flow
+Expected successful result shape:
+
+```ts
+{
+  success: true,
+  challengeId: string,
+  challengeToken: string,
+  expiresAt: string,
+  requestId?: string,
+  raw?: unknown
+}
+```
 
-The SDK sends challenge data and client signals to the TrueSift API.
+---
 
-Conceptual usage:
+## Verifying a challenge
 
 ```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
+    honeypotValue: body.companyWebsite,
   },
   metadata: {
-    form: 'website-check'
-  }
+    form: 'website-check',
+  },
 });
 ```
 
-The SDK normalizes the response, but the project decides what to do next.
+Expected successful result shape:
+
+```ts
+{
+  success: true,
+  decision: 'allow' | 'review' | 'block',
+  score: number,
+  reasonCodes: string[],
+  isAllowed: boolean,
+  isReview: boolean,
+  isBlocked: boolean,
+  mode?: 'observe' | 'protect',
+  calculatedDecision?: 'allow' | 'review' | 'block',
+  effectiveDecision?: 'allow' | 'review' | 'block',
+  challengeId?: string,
+  requestId?: string,
+  raw?: unknown
+}
+```
 
 ---
 
@@ -281,102 +338,95 @@ review
 block
 ```
 
-The SDK exposes helper functions:
-
-```ts
-isAllowed(result)
-isReview(result)
-isBlocked(result)
-```
-
-These helpers do not make business decisions.
+A `block` decision is a valid business result, not a transport error.
 
-They only make backend code easier to read.
+The SDK does not automatically block users. Your backend decides how to react.
 
 ---
 
-## Fail-open and fail-closed
-
-The SDK does not decide whether a request should continue when TrueSift is unavailable.
+## Observe mode
 
-That decision belongs to the project backend.
+In observe mode, TrueSift can return decisions without your application blocking users.
 
-Typical policies:
+This is recommended for early integrations:
 
 ```txt
-fail-open:
-  if TrueSift is unavailable, continue the business flow
-
-fail-closed:
-  if TrueSift is unavailable, reject the request
+1. call verifyChallenge()
+2. record or inspect the decision
+3. continue the user flow
+4. only switch to protect behavior after enough confidence
 ```
 
-For early observe-mode integrations, fail-open is usually safer because real users should not be blocked by a temporary verification outage.
-
 ---
 
-## Observe mode
+## Protect mode
 
-In observe mode, TrueSift can collect telemetry and return decisions without blocking real users.
+In protect mode, your backend may act on `block` decisions.
 
-The SDK should return normalized result data.
+Example policy:
 
-The project backend decides whether to ignore, store, review, or act on that result.
+```txt
+allow  -> continue
+review -> continue, flag, or apply extra checks
+block  -> reject or slow down according to your business rules
+```
+
+The SDK only returns normalized data. It does not enforce this policy.
 
 ---
 
-## Protect mode
+## Fail-open and fail-closed
 
-In protect mode, TrueSift may return a block decision.
+The SDK does not decide whether a request should continue when TrueSift is unavailable.
 
-A block decision is a valid business result, not a transport error.
+Typical backend policies:
 
-The SDK must not throw an exception just because the decision is `block`.
+```txt
+fail-open:
+  if TrueSift is unavailable, continue the business flow
 
-Transport errors are different and include:
+fail-closed:
+  if TrueSift is unavailable, reject the request
+```
 
-- network failure
-- timeout
-- invalid JSON
-- unexpected response shape
-- HTTP 401
-- HTTP 5xx
-- malformed API response
+For public lead forms, website checks, and early observe-mode integrations, fail-open is usually safer because real users should not be blocked by a temporary verification outage.
+
+For sensitive endpoints, your backend may choose fail-closed.
 
 ---
 
 ## Error model
 
-The SDK distinguishes between several error classes:
+The SDK distinguishes between these error classes:
 
 ```txt
-BotGuardConfigError
-BotGuardRequestError
-BotGuardTimeoutError
-BotGuardAuthError
-BotGuardResponseError
-BotGuardApiError
+TrueSiftConfigError
+TrueSiftRequestError
+TrueSiftTimeoutError
+TrueSiftAuthError
+TrueSiftResponseError
+TrueSiftApiError
 ```
 
-Expected meaning:
+Meaning:
 
 ```txt
-BotGuardConfigError:
+TrueSiftConfigError:
   missing or invalid SDK configuration
 
-BotGuardRequestError:
+TrueSiftRequestError:
   network-level request failure
 
-BotGuardTimeoutError:
+TrueSiftTimeoutError:
   request aborted after timeout
 
-BotGuardAuthError:
+TrueSiftAuthError:
   API returned an authentication or authorization error
 
-BotGuardResponseError:
+TrueSiftResponseError:
   API response was malformed or unexpected
 
-BotGuardApiError:
+TrueSiftApiError:
   API returned a structured error response
 ```
 
@@ -394,23 +444,43 @@ Recommended default:
 
 The timeout is implemented with `AbortController`.
 
-The SDK must clean up timers correctly after each request.
+The SDK does not retry requests automatically.
+
+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.
 
 ---
 
-## Retry behavior
+## Secret key rules
+
+The `secretKey` is a backend-only credential.
+
+Never:
 
-The first SDK version does not retry requests by default.
+- 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
 
-Especially important:
+The SDK includes redaction helpers, but your application should still avoid logging full request bodies, headers, cookies, tokens, and environment dumps.
 
-```txt
-verifyChallenge() must not be retried automatically
-```
+---
+
+## Site key rules
+
+The `siteKey` identifies a protected site/application.
 
-Challenge tokens may be single-use.
+It is less sensitive than `secretKey`, but backend-driven integrations normally do not need to expose it to the frontend.
 
-Retrying verification can produce incorrect behavior or falsely consume a token.
+If a future frontend challenge widget needs a public site key, expose only the site key and never the secret key.
 
 ---
 
@@ -429,18 +499,18 @@ Conceptual controller flow:
 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
+     continue business flow
 7. If result is blocked and project is in protect mode:
      return project-specific rejection response
 8. Otherwise:
-     continue the normal business flow
+     continue 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.
+The SDK may be used in Next.js route handlers, but this package must not import Next.js types.
 
 Conceptual flow:
 
@@ -449,7 +519,7 @@ app/api/some-form/route.ts
         ↓
 server-only environment config
         ↓
-createBotGuardClient()
+createTrueSiftClient()
         ↓
 verifyChallenge()
         ↓
@@ -460,20 +530,27 @@ Do not import this SDK into client components.
 
 ---
 
-## Security principles
+## Safe logging
 
-The SDK follows these principles:
+Recommended logging behavior:
 
-- 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
+```txt
+development:
+  short warnings are acceptable
+  never log secretKey, challengeToken, cookies, authorization headers, or full request bodies
+
+production:
+  log only high-level failure category, requestId, endpoint/action, and non-sensitive context
+```
+
+The SDK exposes redaction helpers:
+
+```ts
+redactTrueSiftClientConfig(config)
+redactBotGuardConfig(config)
+redactSensitiveRecord(record)
+redactSensitiveValue(value)
+```
 
 ---
 
@@ -491,16 +568,16 @@ Run typecheck:
 pnpm typecheck
 ```
 
-Build package:
+Run tests:
 
 ```bash
-pnpm build
+pnpm test
 ```
 
-Run tests:
+Build package:
 
 ```bash
-pnpm test
+pnpm build
 ```
 
 Run all checks:
@@ -509,52 +586,28 @@ Run all checks:
 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:
+Create package preview:
 
-```txt
-dist/
+```bash
+npm pack --dry-run
 ```
 
 ---
 
-## 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.
+## Security principles
 
-See:
+The SDK follows these principles:
 
-```txt
-LICENSE
-```
+- server-side only
+- no default logging
+- no secret logging
+- 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 runtime surface
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truesift/express",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Server-side TypeScript SDK client for TrueSift human verification API.",
   "type": "module",
   "license": "MIT",
@@ -57,4 +57,4 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   }
-}
+}