Admiral SDK for NodeJS

Provides a simple interface for using Admiral's APIs for applications written in server-side JavaScript. Visit us at Admiral for more information.

Requirements

Node.js 18 or later (see engines in package.json).

Installation

Install the package to your project:

npm install @admiral-vrm/sdk-node
# or
yarn add @admiral-vrm/sdk-node

This package has peer dependencies (@edge-runtime/cookies, @noble/hashes v1.x, plus React/Next when using those features). Next.js apps typically satisfy these. If you use the SDK in a non-Next environment (e.g. Express or plain Node), install the peers manually if needed. Use @noble/hashes v1.x; v2.x uses different export paths and is not yet supported.

npm install @edge-runtime/cookies @noble/hashes@^1.7.0

Configuration

• propertyID (required): Your Admiral property ID (e.g. "A-1234-1").
• tokenSecretKey (recommended when using Protect): Secret used to sign visitor tokens. Set a strong, unique value in production; otherwise a default is used (not suitable for production). Can also be set via ADMIRAL_TOKEN_SECRET_KEY.
• proxy: Optional. When using proxyAdmiral: true, set proxy.host (and optionally scheme, prefix).
• protectOptions: Optional. For Protect/Partner API: partnerApiEndpoint, cacheTimeout. API credentials are configured inside the Protect integration (see examples).

Documentation

Admiral

The Admiral class is the main class for the Admiral SDK. It contains configuration for the Admiral object, such as the property ID, environment, enabling Protect and Proxy, and additional parameters.

export const admiral = new Admiral({
  propertyID: "A-1234-1",
  environment: "production",
  protect: true,
  proxyAdmiral: true,
  tokenSecretKey: process.env.ADMIRAL_TOKEN_SECRET_KEY, // recommended for production
  proxy: {
    host: "host.com",
    scheme: "https",
  },
});

The class provides the following methods:

getPossibleHandlers(): string[]

Returns an array of possible Admiral prefix handlers that can be used as prefixes when using the proxy functionality.

getPossibleProxyPathPrefixes(): string[]

Returns path prefixes that match proxy routes (e.g. ["/abcde.../", "/fghij.../"]). No I/O. Use for gate checks or diagnostics. Prefixes rotate over time; treat as runtime routing hints, not static invariants.

getCurrentProxyPathPrefix(): string

Returns the current (today's) proxy path prefix (e.g. "/abcde.../"), or "" if none. Same as getPossibleProxyPathPrefixes()[0]. No I/O.

isProxyRequest(urlOrReq: string | MiddlewareRequest): boolean

Returns true if the request or URL matches a proxy path. Accepts a full URL, pathname, or MiddlewareRequest. No I/O. Use before calling the SDK to skip non-Admiral requests (gate-first pattern).

getProxyRoutingInfo(): { handlers: string[]; prefixes: string[]; currentPrefix: string; generatedAt: number }

Returns current proxy handlers, path prefixes, the current (today's) prefix, and generation time. For admin/debug use only; restrict access and do not expose publicly.

fetchSSRBootstraps(): Promise

Fetches Admiral bootstrap scripts for server-side rendering. Returns a promise containing:

• admiral: Array of bootstrap script strings, each of these should be script tags

fetchBootstraps(): Promise<string[]>

Fetches Admiral bootstrap scripts. Returns a promise containing an array of script strings.

renderSSRBootstraps(payload: AdmiralSSRBootstrapWrapper, format: "html" | "react" = "react"): React.ReactNode[]

Renders the Admiral bootstrap scripts for server-side rendering as React components. Takes a bootstrap wrapper payload from fetchSSRBootstraps and returns an array of React script elements.

Parameters:

• payload: Object containing array of bootstrap scripts under admiral key

handleRequestAsMiddleware(req: MiddlewareRequest): Promise

Handles Admiral middleware functionality including proxy requests and Protect functionality. Returns a promise containing the middleware response with:

• response: Response object (optional)
• headers: Headers object (optional)
• cookies: ResponseCookies object (optional)

Parameters:

• req: MiddlewareRequest object containing the incoming request details

You can instead use the split handlers and a gate for more control:

• handleProxyRequestAsMiddleware(req) – Proxy only. Use when the request is a proxy path (e.g. after isProxyRequest(url)).
• handleProtectRequestAsMiddleware(req) – Protect only (token, cookie reset, admiral-protect-block header). No proxy.

Install API and proxy behavior

• Bootstrap (Install API): You can keep using a cron or build step that fetches bootstrap scripts (e.g. fetchSSRBootstraps() or the Install API) and caches them on your CDN. You do not need to call the Install API at runtime for every user.
• Proxy: A network round-trip in middleware happens only when a request matches one of the proxy path prefixes (Admiral runtime script/beacon traffic). Normal page loads, logins, and app API calls do not hit the proxy if you use a gate: call admiral.isProxyRequest(url) first and only invoke the SDK when it returns true (or when the URL is a Protect token/reset URL). See the nextjs and expressjs examples for a gate-first middleware pattern.
• Why path-based proxy? A CNAME to a third-party host would be blockable by adblockers. The path-based proxy keeps requests on your host (yourdomain.com/<prefix>/...), so the host stays first-party and is not filtered. Expose any routing diagnostics (e.g. getProxyRoutingInfo()) only to admin/debug audiences, not publicly.

Usage with Next.js and React

See the nextjs example for more information with a full example and documentation on how to use the Admiral SDK with Next.js.

The ProtectEmbed component is a React component that can be used to embed the Protect functionality into a React application.

Usage with Express.js / Node.js

See the expressjs example for more information with a full example and documentation on how to use the Admiral SDK with Express.

The ProtectHTMLEmbed library allows embedding HTML with Protect functionality into your application without using React.