rudder-js-sdk/skills/rudder-web-sdk/reference/modules.md

Modules

Source: src/domains/ModulesDomain.ts. Calls an installed module function as the signed-in player through POST /sdk/v1/modules/{module}/{fn}.

Generated clients

Use rudder client generate from liveops-module-sdk/cli instead of calling modules by name:

export RUDDER_URL=https://api.rudder.build RUDDER_TOKEN=... RUDDER_PROJECT=...
rudder client generate --lang ts --out src/rudder.modules.ts            # staging by default
rudder client generate --lang ts --out src/rudder.modules.ts --environment prod
rudder client generate --lang ts --manifests ./modules --out src/rudder.modules.ts  # local manifests

The file reads the manifests of the installed modules, generates only trigger: client functions, and lists every module with its version in the header. It exports:

• modules(client): { <module>: { <fn>(args): Promise<Result> } }
• <Module><Fn>Args / <Module><Fn>Result types from the manifest schemas
• <Module><Fn>Error: the function's declared codes plus RudderKernelError

import { createClient, RudderModuleError } from '@rudder/sdk';
import { modules, type StoreBuyError } from './rudder.modules';

const m = modules(createClient({ projectKey }));
try {
  const result = await m.store.buy({ offer: 'starter_pack' });
} catch (error) {
  if (error instanceof RudderModuleError) {
    switch (error.code as StoreBuyError) {
      case 'insufficient_funds': /* ... */ break;
      case 'offer_not_found': /* ... */ break;
    }
  }
}

Commit the generated file and regenerate it when installed modules change. Do not edit it by hand.

modules.call

client.modules.call<T = unknown>(
  module: string,
  fn: string,
  args?: unknown,
  options?: { moduleVersion?: string },
): Promise<T>

• Sends { args }; args is {} when omitted. Resolves to the response result. Console output and the kernel call log never reach players.
• Idempotency: each call generates one Idempotency-Key (UUID v4) and sends the same key on every retry, so the server runs the function at most once and returns the stored response for a repeated key. A new call() gets a new key.
• Retries: up to 2, with jittered exponential backoff, on network errors, 5xx and 409 with code conflict. Other 4xx responses (including other 409 codes) are never retried.
• moduleVersion (set by generated clients) is sent as X-Rudder-Module-Version: <module>@<version>. A major mismatch with the installed module is logged on the backend; the call still runs.

Errors

• 422 { error, code, requestId } rejects with RudderModuleError<C> (status 422, code, message from error, requestId). C defaults to string; use the generated union to narrow it.
• A trap is a 500 and a timeout a 504, both RudderHttpError without details (after the retries above).
• 401 follows the normal refresh flow (RudderAuthError when it fails).