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:

```bash
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`

```ts
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`

```ts
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).