@dx-do/client

TypeScript client for DX Operational Observability SaaS APIs. It wraps tenant/APM, AXA, OI, ACC, dashboards, and related endpoints behind typed service classes. All HTTP traffic goes through DxSaasService, which applies configuration v4 auth, optional proxy settings, and shared logging/error handling.

Configuration: DXDoConfiguration

DXDoConfiguration (DXDoConfiguration.ts) is the shape DxSaasService expects:

| Field | Type | Purpose | |--------|------|--------| | dxConfiguration | DXSaaSConfiguration4 | SaaS auth and routing: user token, cohort, DX gateway host, optional ASM URLs/tokens. | | proxyConfiguration | AxiosProxyConfig (optional) | Standard Axios proxy config (host, port, protocol, auth, etc.) for corporate proxies. |

DXSaaSConfiguration4 (DXSaaSConfiguration.ts) includes:

• configurationVersion: "4"
• userToken: bearer-style user token for API calls
• cohortId: tenant cohort identifier
• dxGatewayHost: base URL for the DX gateway
• Optional: dxASMbaseAPIURL, dxASMToken for ASM-specific routes

Example (replace placeholders with real values from your environment):

import type { DXDoConfiguration } from '@dx-do/client';

const dxDoConfiguration: DXDoConfiguration = {
  dxConfiguration: {
    configurationVersion: '4',
    userToken: process.env.DX_USER_TOKEN!,
    cohortId: process.env.DX_COHORT_ID!,
    dxGatewayHost: process.env.DX_GATEWAY_HOST!, // e.g. https://your-gateway.example.com
  },
  // Optional: AxiosProxyConfig when traffic must go through a proxy
  proxyConfiguration: {
    host: process.env.HTTPS_PROXY_HOST,
    port: Number(process.env.HTTPS_PROXY_PORT),
    protocol: 'https',
  },
};

Two ways to use services

1. Create services on demand (lightweight)

Use one shared DxSaasService and construct only the domain services you need. Each service takes the SaaS client (and usually an optional logger).

Best when: scripts, tests, or tools that touch one or two API areas.

import {
  DxSaasService,
  AlertService,
  DXDoConfiguration,
} from '@dx-do/client';
import { Logging } from '@dx-do/util';

const log = new Logging.NullSimpleLog();
const dxSaaSService = new DxSaasService(dxDoConfiguration, log);
const alerts = new AlertService(dxSaaSService, log);

const list = await alerts.retrieveAllAlertsV2();

2. createServiceMonolith (full surface)

createServiceMonolith(dxDoConfiguration, log?) (service-monolith.ts) builds a single DxSaasService and returns every pre-wired service (dxAlertService, dxAgentService, dxACCService, …) on one object.

Best when: CLIs, long-running apps, or anything that uses many DX APIs and you want one factory call.

import { createServiceMonolith, DXDoConfiguration } from '@dx-do/client';
import { Logging } from '@dx-do/util';

const log = new Logging.NullSimpleLog();
const monolith = createServiceMonolith(dxDoConfiguration, log);

const list = await monolith.dxAlertService.retrieveAllAlertsV2();

Same AlertService behavior as above: monolith.dxAlertService is an AlertService instance sharing monolith.dxSaaSService.

DataStore services

The services/datastore/ namespace contains direct REST clients for the DX SaaS DataStore microservices that sit behind the gateway. Each service mirrors a Java REST controller and is built around hand-authored Zod schemas in model/datastore/<name>/ (see nx run client:generate-datastore-models). All of them validate request bodies with …Schema.parse(...) and lenient-validate responses with safeParse(...) — bad responses are logged via the injected SimpleLog and the raw payload is still returned.

The DataStoreXxxService classes are wired into createServiceMonolith alongside the legacy services. The legacy keys (dxTASService, dxNASSService, dxBlobService) still point to the older TASService / NASSService / BlobService implementations and are retained for backwards compatibility — new code should prefer the dxDataStore… / dxBlobStorageService keys.

| Service | Monolith key | Class | |---------|-------------|-------| | TAS graph queries | dxDataStoreTASService | DataStoreTASService | | NASSQL metric queries | dxDataStoreNASSQLService | DataStoreNASSQLService | | Metrics metadata | dxDataStoreMetricsMetadataService | DataStoreMetricsMetadataService | | States | dxStatesService | DataStoreStatesService | | Authorization views | dxAuthViewsService | DataStoreAuthViewsService | | Audit | dxAuditService | DataStoreAuditService | | Blob storage | dxBlobStorageService | DataStoreBlobStorageService | | Tokens | dxTokensService | DataStoreTokensService | | Features | dxFeaturesService | DataStoreFeaturesService |

DataStoreBlobStorageService covers the full /blobstorage REST surface (store, bulk-store, fetch, query, delete, bulk-delete, schema/list, executeAsync, asyncResult) and should be preferred over the legacy BlobService for new code.

DataStoreStatesService

Wraps /states/state/{store,fetch,range,republish}. Filters use the VertexStateFilter discriminated union (ALL | AND | OR | ALERT | METRIC | STATE | VERTEX_ID | NAMESPACE | MANAGEMENT_MODULE | EMPTY | COLLECT_GROUPS). fetchStates supports incremental polling via version and projections DETAILED | BRIEF | EXTRA_IDS. republishStates is intended for recovering from Kafka outages and re-emits state-change events.

DataStoreAuthViewsService

Wraps the data-store-level authorization views API at /views/{view,default,query,queryView}. Note: this is distinct from the higher-level APM Universe API (/atc/views/view) wrapped by ApmUniverseService. Per view-rest.adoc, mutation endpoints (createView, updateView, deleteView, setDefaultView) require admin/MA roles. Filters use the ALL | ID | ACTIVE | ATTRIBUTE | AND | OR discriminated union.

DataStoreAuditService

Wraps /audit/{store,query,globalquery}. storeAudit requires the documented audit-record fields (eventTime, serviceId, resource, action, result); other fields are validated as optional. queryAudit and globalQueryAudit are exposed by AuditController but their request/response shapes are kept loose (z.looseObject({})) until upstream docs firm up. globalQueryAudit requires master/global-admin privileges.

DataStoreBlobStorageService

Wraps the full /blobstorage REST surface. Notes:

• storeBlob(params, body, attributes) POSTs the raw body with required query params schema, id, ttl plus free-form attribute query params, matching the Java BlobStorageController contract.
• fetchBlob(schema, id, version?) POSTs an empty body with the params on the query string and returns the raw response — fixing the legacy BlobService.fetchBlob quirk that cast an AxiosResponse directly.
• executeAsync initiates async commands such as DELETE_SCHEMA, returning a correlationKey to poll via asyncResult.
• The legacy BlobService and model/blob/blob.model.ts are intentionally retained side-by-side and are not coupled to this service.

DataStoreTokensService

Wraps /session/validate and the full /tenants/token/... lifecycle (verify, getAndVerify, query, publicKey, user/agent/tenant/internal create+update, revoke/cancelRevoke/delete/import). Per tokens-rest.adoc:

• Operations are role-gated server-side (MA/GA/TA/PU/UZ/AGENT). The client does not enforce these checks; callers must hold a token with the right role.
• queryTokens accepts either the query string grammar or the filter JSON, but not both — this is enforced via refine on TokenQueryRequestSchema.
• createTenantToken(request, impersonate?) accepts an optional Auth-Impersonate header value, used by internal tokens to impersonate a tenant scope.
• getPublicKey() returns the JSON form. Use getPublicKeyText() for the raw PEM (sets Accept: text/plain).
• createInternalToken and importToken require the master token.

DataStoreFeaturesService

Wraps /features/{store,delete,query,toggles,queryToggles,deleteToggles}. Features form a hierarchical authorization tree with optional API regex lists and datascopes (filter templates of types TAS | NASS | ES | REST). MA/GA can toggle features globally; TA can override per-tenant but cannot undo MA/GA-set toggles. toggleFeatures accepts a flat array of feature ids; deleteToggles([]) resets all toggles.

Imports

Public API is re-exported from the package root (@dx-do/client). Prefer:

import { createServiceMonolith, DxSaasService, AlertService, DXDoConfiguration } from '@dx-do/client';

For configuration shape variants and helpers, see exports under ./lib/model/config/ in the source tree (also re-exported from the package index where applicable).

API Reference

Full generated API documentation lives in docs/client/api/ at the repository root.

To regenerate after source changes:

nx run client:docs

The docs target requires typedoc and typedoc-rhineai-theme to be installed. Run bun install (or npm install) first.

Deprecated symbols

The following symbols are retained for backwards compatibility but should not be used in new code:

| Symbol | Replacement | |--------|-------------| | AlertResponse.Alert / AlertResponse.AlertList | AlertResponseV2.* | | AlertResponse.AllAlertsRequestBody | AlertResponseV2.AllAlertsRequestBody | | DXSaaSConfigurationLegacy | DXSaaSConfiguration4 | | DXSaaSConfiguration3 | DXSaaSConfiguration4 | | ChannelResponse.WebhookSpec | DXChannelWebhookSpecificConfiguration | | TemplatesResponse.LinkedEntity | PolicyResponse.LinkedEntity | | BlobService (monolith.dxBlobService) | DataStoreBlobStorageService (monolith.dxBlobStorageService) | | TASService (monolith.dxTASService) | DataStoreTASService (monolith.dxDataStoreTASService) | | NASSService.query (monolith.dxNASSService.query) | DataStoreNASSQLService.query (monolith.dxDataStoreNASSQLService.query) |

ASM integration

The ASM (Application Security Manager) SDK (src/lib/model/asm/client/) is auto-generated from the OpenAPI spec and is excluded from the TypeDoc output. To regenerate:

nx run client:generate-asm-client

The source spec is at: https://api.asm.saas.broadcom.com/v3/documentation.

ASM API calls are routed through AsmService. Set dxASMbaseAPIURL and dxASMToken in DXSaaSConfiguration4 to enable them.