@oqtopus-team/qdash-client

@oqtopus-team/qdash-client is the TypeScript client for the QDash API. It provides an Orval-generated API for every OpenAPI operation and a stable high-level client for common QDash and agent-calibration workflows.

Installation

npm install @oqtopus-team/qdash-client

The package requires Node.js 20 or later.

Quick Start

import { QDashClient } from "@oqtopus-team/qdash-client";

const client = await QDashClient.fromProfile("default");
const chip = await client.getDefaultChip();
const metrics = await client.getChipMetrics(chip.chip_id);

console.log(metrics.qubit_metrics);

fromProfile() reads the same ~/.config/qdash/config.ini file as the Python client. When XDG_CONFIG_HOME is set, it reads $XDG_CONFIG_HOME/qdash/config.ini instead.

Configuration

Create a client from the standard QDash environment variables:

const client = QDashClient.fromEnv();

Supported variables include:

• QDASH_BASE_URL
• QDASH_API_TOKEN
• QDASH_PROJECT_ID
• QDASH_CF_ACCESS_CLIENT_ID
• QDASH_CF_ACCESS_CLIENT_SECRET
• QDASH_TIMEOUT_SECONDS
• QDASH_RETRY_MAX_ATTEMPTS
• QDASH_RETRY_BACKOFF_SECONDS
• QDASH_RETRY_MAX_BACKOFF_SECONDS
• QDASH_VERIFY_TLS
• QDASH_PROXY
• QDASH_USER_AGENT

Legacy QDASH_USERNAME, QDASH_PASSWORD_ENV, and password environment variables are also supported.

A profile has the same format as qdash-client for Python:

[mackerel]
base_url = https://example.qdash/api
api_token = your-token
project_id = your-project-id
cf_access_client_id = your-client-id
cf_access_client_secret = your-client-secret

Profile files written with QDashConfig.save() use owner-only permissions (0600). A custom fetch implementation is required when using proxy or disabling TLS verification.

Generated API

All OpenAPI operations are available through the Orval-generated API bound to the client's transport:

const chips = await client.api.listChips();
const posts = await client.api.listForumPosts({ limit: 20 });

Use the high-level methods for stable domain operations and polling helpers. Use client.api when an endpoint does not yet need a convenience method.

Agent Calibration

const session = await client.createAgentSession({
  chipId: "chip-1",
  policy,
  skillName: "pi-extension",
  skillVersion: "0.1.0",
});

const action = await client.submitAgentAction(session.session_id, {
  idempotencyKey: crypto.randomUUID(),
  expectedStateVersion: session.state_version,
  actionType: "execute_task",
  taskName: "qubit_spectroscopy",
  qids: ["32"],
});

The client also provides helpers for waiting on action dispatch, QDash execution linkage, candidate commits, campaign commits, and backend application.

Figures and Binary Files

Calibration figures can be downloaded through the authenticated client transport without manually building headers:

const figure = await client.getExecutionFigure("/app/calib_data/.../fig/CheckRabi_33_0.png");
console.log(figure.mediaType, figure.filename, figure.data.byteLength);

const taskFigure = await client.getTaskResultFigure("task-id", { index: 0 });

Use getTaskResultFigure(..., { preferJson: true }) to fetch a JSON figure path when available.

Development

The OpenAPI client and models are generated by Orval from docs/oas/openapi.json. Do not edit src/generated/ manually.

bun install
bun run generate
bun run check
bun run build

The first publish uses a temporary NPM_TOKEN repository secret because npm requires the package to exist before Trusted Publishing can be configured. After the first publish, configure publish-qdash-typescript-client.yml as the package trusted publisher and delete the secret. Release tags use qdash-client-ts-v<version>; the workflow derives the package version from the tag.