{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "esModuleInterop": true
  }
}

5. No Babel transforms are required. The library targets Node.js CommonJS with no ESM syntax.

Public API

FusionAuthClient

const client = new FusionAuthClient(apiKey: string, host: string);
client.setTenantId(tenantId: string): FusionAuthClient;
client.actionUser(request: ActionRequest): Promise<ClientResponse<ActionResponse>>;
// + one method per FusionAuth API endpoint (login, register, retrieveUser, etc.)

FusionAuthClient is the primary entry point. Construct it once with your API key and host URL, optionally call setTenantId for multi-tenant deployments, then call any endpoint method. Every method returns a native Promise resolving to a ClientResponse.

ClientResponse

class ClientResponse<T> {
  statusCode: number | null;
  successResponse: T | null;
  errorResponse: Errors | null;
  exception: Error | null;
  wasSuccessful(): boolean;
}

Returned by every FusionAuthClient method. Call wasSuccessful() to check for a 2xx status with no exception, then read successResponse for the typed payload or errorResponse for FusionAuth validation errors. Inspect exception for network-level failures.

JWTManager

const JWTManager: {
  revokedJWTs: Record<string, number>;
  isValid(jwt: { sub: string; exp: number }): boolean;
  revoke(userId: string, durationSeconds: number): void;
};

A singleton in-process revocation store. Call revoke when a user logs out or changes credentials. Call isValid in your middleware before accepting a decoded JWT. Note this is purely in-memory — it does not persist across restarts or share state between processes.

RESTClient

const rc = new RESTClient();
rc.authorization(key: string): RESTClient;
rc.uri(path: string): RESTClient;
rc.setJSONBody(body: object): RESTClient;
rc.post(): RESTClient;
rc.go(handler: Function): void;

Used internally by FusionAuthClient. You would only use RESTClient directly if you need to call a FusionAuth endpoint not yet wrapped by the client, or to add custom certificate/key material via rc.certificate and rc.key.

Working examples

Scenario - Authenticate a user (login)

Call the FusionAuth Login API with application credentials and handle the response. Use this in an Express POST /login route.

const FusionAuthClient = require('./fusionauth/FusionAuthClient');

const client = new FusionAuthClient(
  process.env.FUSIONAUTH_API_KEY,
  process.env.FUSIONAUTH_HOST
);

async function loginUser(loginId: string, password: string, applicationId: string) {
  const response = await client.login({
    loginId,
    password,
    applicationId,
  });

  if (response.wasSuccessful()) {
    const { token, user } = response.successResponse;
    console.log('JWT:', token);
    console.log('User id:', user.id);
    return response.successResponse;
  } else {
    console.error('Login failed:', response.statusCode, response.errorResponse);
    throw new Error('Authentication failed');
  }
}

Scenario - Register a new user

Create a user and register them to an application in a single call. Use during sign-up flows.

const FusionAuthClient = require('./fusionauth/FusionAuthClient');

const client = new FusionAuthClient(
  process.env.FUSIONAUTH_API_KEY,
  process.env.FUSIONAUTH_HOST
);

async function registerUser(email: string, password: string, applicationId: string) {
  const response = await client.register(null, {
    user: {
      email,
      password,
    },
    registration: {
      applicationId,
    },
  });

  if (response.wasSuccessful()) {
    console.log('New user id:', response.successResponse.user.id);
    return response.successResponse;
  } else {
    console.error('Registration error:', response.errorResponse);
    throw new Error('Registration failed');
  }
}

Scenario - Revoke and validate JWTs locally

After a user logs out, revoke their JWTs in the local cache. In subsequent requests, validate a decoded JWT before allowing access.

const JWTManager = require('./fusionauth/JWTManager');

// On logout: revoke for the JWT's remaining lifetime (e.g. 3600 seconds)
function onUserLogout(userId: string, jwtDurationSeconds: number) {
  JWTManager.revoke(userId, jwtDurationSeconds);
}

// In Express middleware: validate a decoded JWT payload
function jwtMiddleware(req: any, res: any, next: Function) {
  const decodedJwt = req.decodedJwt; // assume upstream JWT decode already ran
  if (!decodedJwt || !JWTManager.isValid(decodedJwt)) {
    return res.status(401).json({ error: 'Token revoked or invalid' });
  }
  next();
}

Scenario - Multi-tenant request

Scope all API calls to a specific FusionAuth tenant by chaining setTenantId.

const FusionAuthClient = require('./fusionauth/FusionAuthClient');

const client = new FusionAuthClient(
  process.env.FUSIONAUTH_API_KEY,
  process.env.FUSIONAUTH_HOST
).setTenantId(process.env.FUSIONAUTH_TENANT_ID);

async function retrieveUser(userId: string) {
  const response = await client.retrieveUser(userId);
  if (response.wasSuccessful()) {
    return response.successResponse.user;
  }
  throw new Error(`Failed to retrieve user: ${response.statusCode}`);
}

File walkthrough

• FusionAuthClient.js — Defines the FusionAuthClient constructor and its prototype, which contains one method per FusionAuth REST API endpoint. Each method uses RESTClient internally and returns a Promise<ClientResponse>.
• RESTClient.js — Builder-pattern HTTP client. Chainable methods configure the URL, headers, query parameters, and body; .go() executes the request and passes the parsed ClientResponse to a callback.
• ClientResponse.js — Simple response envelope constructor with statusCode, successResponse, errorResponse, exception fields, and a wasSuccessful() helper.
• JWTManager.js — Singleton object managing an in-memory map of revoked user JWTs keyed by user id. Exposes isValid, revoke, and a private _cleanUp method.

Common pitfalls and fixes

• FUSIONAUTH_HOST must include the scheme and no trailing slash — use https://auth.example.com, not auth.example.com/. A missing scheme causes http.request to throw immediately.
• setTenantId must be called before any API method — it mutates the client; if called after a concurrent request starts it may affect the wrong request. Create a new client instance per tenant in concurrent scenarios.
• JWTManager state is not shared across processes or restarts — in multi-process deployments (cluster mode, pm2, containers), revocations in one process are invisible to others. Use FusionAuth's server-side logout API (client.logout) as the authoritative revocation path.
• wasSuccessful() returns false for 401/403 even without a network error — check response.errorResponse for FusionAuth-level messages; do not assume a non-successful response means an exception was thrown.
• CommonJS only — no named ESM exports — import { FusionAuthClient } from './FusionAuthClient.js' will fail. Use const FusionAuthClient = require('./FusionAuthClient.js') or add a wrapper barrel with export =.
• The promise package must be installed — FusionAuthClient.js explicitly requires it (var Promise = require('promise')); relying on the global Promise is not enough as it is shadowed at module scope.

Vibe-coding prompt template

I have dropped the FusionAuth Node.js client source files into src/fusionauth/.
The files are: FusionAuthClient.js, RESTClient.js, ClientResponse.js, JWTManager.js.
The upstream package is @fusionauth/node-client@1.51.0.
A USAGE.md file in that directory explains the full API, constructors, and working examples.

Please help me integrate this into my project step by step:
1. Read USAGE.md and the file excerpts to understand the real exports and signatures.
2. Add the `promise` npm dependency if it is not already installed.
3. Create a singleton FusionAuthClient instance using FUSIONAUTH_API_KEY and FUSIONAUTH_HOST env vars.
4. Wire up the following features in my existing Express app: [describe your login/register/logout routes here].
5. Add JWT revocation middleware using JWTManager.isValid() on protected routes.
6. Do not invent any methods — only use methods visible in FusionAuthClient.js and the USAGE.md examples.

License and credit

The source is licensed under the Apache License 2.0. See source/ file headers for the full copyright notice.

Upstream package: @fusionauth/node-client by FusionAuth. Upstream repository: https://github.com/FusionAuth/fusionauth-node-client.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。