Nexus API client

Typed client for the Odyssey Nexus platform with automatic OAuth token handling, correlation headers, and helper methods for the most common read endpoints.

Install & build

bun install
# Optional sanity check
bunx tsc --noEmit
# Emit ESM + types into dist/
bun run build
# Build and publish to npm (requires npm auth)
bun run deploy

Sources live in index.ts, and bun run build emits the published ESM bundle plus .d.ts files under dist/ (referenced by the package entry points).

Quick start

import { NexusApi } from "nexus-api-client";

const nexus = new NexusApi({
    baseUrl: "https://{apigateway}.ody.cloud",
    clientId: process.env.NEXUS_CLIENT_ID!,
    clientSecret: process.env.NEXUS_CLIENT_SECRET!,
    // Optional overrides
    services: {
        membership: {
            scope: "nexus.membership",
            basePath: "nexus.membership/v1",
        },
    },
});

const { data: preferences } = await nexus.membership.listContactPreferences({
    activeOnly: true,
    pageSize: 100,
});

const { data: points } = await nexus.points.getPointTransactions(12345, {
    dateFrom: new Date("2024-01-01T00:00:00Z"),
    transactionType: "Credit",
});

const { data: member } = await nexus.membership.getMember(12345);
await nexus.membership.updateMember(member.memberId, {
    email: "[email protected]",
});

await nexus.membership.addMemberToGroup(member.memberId, 42);

const { data: egmGroups } = await nexus.gaming.listEgmGroups();

const { data: promoEvents } = await nexus.promotions.listPromotionEvents({
    isActive: true,
});

const { data: sessionAudits } = await nexus.session.listSessionAudits({
    from: new Date("2024-06-01T00:00:00Z"),
    to: new Date("2024-06-30T23:59:59Z"),
    pageSize: 50,
});

console.log("member contact prefs", preferences.length);
console.log("point tx count", points.length);
console.log("egm groups", egmGroups.length);
console.log("promo events", promoEvents.length);
console.log("audits this month", sessionAudits.length);

What the client provides

• Token management – OAuth client credential flow with automatic caching and jitter-free refresh ahead of the one-minute expiry window.
• Request metadata – required X-Request-Id and X-Request-TimeStamp headers automatically generated for every call.
• Retry policy – configurable exponential back-off for transient status codes (429, 503, 504).
• Strong typing – helper methods for membership (member CRUD/search, contact preferences, citations, suspensions, groups), points (transactions), gaming (EGM groups), promotions (events, device groups, entry balances), and session (ReserveIt, sessions, audits) APIs, plus a generic service(name).request(...) escape hatch for every other endpoint described in docs/.
• Scope aware – GET requests default to the .read variant of each Nexus scope (e.g. nexus.membership.read), while mutations fall back to the full-access scope unless you override per request.
• Configurable services – override per-service scopes or base paths when your venue uses a different routing convention.

Making custom calls

const gaming = nexus.service("gaming");
const result = await gaming.request<{ egmMeters: unknown[] }>({
    path: "/egms/123/meters",
});

console.log(result.requestId, result.data);

const membership = nexus.service("membership");
const genericMemberCall = await membership.request<{ members: unknown[] }>({
    path: "/members",
    query: { PageSize: 10 },
});

console.log(genericMemberCall.status, genericMemberCall.data);

path should be relative to the service base path (nexus.{service}/v1 by default). Pass expects: "text" for textual payloads or parseResponse to take full control over deserialization.

Configuration reference

| Option | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | baseUrl | Venue-specific gateway host, e.g. https://demo.ody.cloud. | | clientId / clientSecret | Credentials issued by Odyssey. | | services | Overrides like { membership: { scope: "nexus.membership", readScope: "nexus.membership.read", basePath: "custom-path" } }. | | requestIdFactory | Supply your own UUID generator for tracing compliance. | | tokenCacheBufferSeconds | Time (seconds) to subtract from the OAuth expiry while caching (default 5). | | retry | { retries: number; initialDelayMs?: number; factor?: number } controlling exponential backoff. |

Development

• Source lives in index.ts; adjust or extend service helpers as new swagger definitions become available under docs/.
• Run bunx tsc --noEmit to type-check before publishing.
• No runtime build step is required (the module field points to the TypeScript entry file).
• Use bun run deploy to run the build and npm publish together once you have logged in with npm login and set the right access permissions.