@mentingo/phishing-simulation-sdk

Server-side SDK for the Mentingo phishing plugin. Requires Node.js 22.15 or newer. The package contains the HTTP client, API types and a webhook payload type guard. The hosted phishing engine and Mission Control UI are deployed separately.

Installation

Install from npmjs.com:

pnpm add @mentingo/[email protected]

Usage

import { createPhishingClient } from "@mentingo/phishing-simulation-sdk";

const client = createPhishingClient({
  baseURL: process.env.PHISHING_BASE_URL!,
  apiKey: process.env.PHISHING_API_KEY!,
  tenantId: tenant.id,
});

const configuration = await client.configuration.get();
const campaigns = await client.campaigns.list();
const report = await client.reports.get(campaignId);

const summary = await client.reports.summary(campaignId, { groupIds });
const { recipients, pagination } = await client.reports.recipients(campaignId, {
  groupIds,
  search: "ada",
  groupId,
  filter: "atRisk",
  sort: "-clickedAt",
  page: 1,
  perPage: 20,
});

reports.get returns every recipient. reports.summary returns totals, per-group totals and the latest risky actions without recipient rows. reports.recipients searches name and email, filters by group or risk, sorts by name, sentAt, clickedAt or submittedAt (prefix - for descending; missing dates sort last) and pages the results (perPage up to 100).

Keep credentials on the server. Bind each client to its tenant and corresponding plugin API key. Requests include the bearer key and x-tenant-id header, reject redirects and time out after 15 seconds. Non-success HTTP responses throw PhishingApiError, containing the HTTP status without the response body. Network, timeout and JSON parsing errors propagate from the transport. A custom fetch can be supplied for testing.

The client exposes configuration, scenarios, campaign creation/listing/lookup/ cancellation and reports. Types are exported from the package root and @mentingo/phishing-simulation-sdk/types.

isPhishingRiskyActionEvent validates a webhook payload's shape. Authenticate webhooks separately using the configured secret, timestamp and signature; the type guard does not verify signatures.

Release preparation

From this package directory:

pnpm pack --pack-destination /tmp/mentingo-sdk-release

The prepack hook builds, checks types and runs the SDK tests before packing or publishing. The tarball includes only the client and type exports, this README, the MIT license and package metadata. It excludes tests, backend code, environment files and data. Publishing targets npmjs.com with public access. The publisher needs permission for the @mentingo npm scope. From this directory, after reviewing the tarball:

pnpm publish --access public

Once published, update Mentingo to the published version and regenerate its pnpm lockfile. Published versions cannot be reused; increment the version for subsequent releases.

License

MIT. See LICENSE.