@qbraid-core/ibm-cloud 0.7.0

package/README.md

@@ -0,0 +1,47 @@
+<img align="right" width="100" alt="qbraid" src="https://qbraid-static.s3.amazonaws.com/logos/qbraid.png">
+
+# [@qbraid-core/ibm-cloud](https://qbraid.github.io/qbraid-core-js/modules/_qbraid-core_ibm-cloud.html)
+
+[![Stable][preview-stability]](https://qbraid.github.io/qbraid-core-js/#launch-stages)
+[![npm](https://img.shields.io/npm/v/@qbraid-core/ibm-cloud?color=blue)](https://npm.im/@qbraid-core/ibm/cloud)
+
+IBM Cloud API client used for interacting with IBM's Qiskit Runtime Service API.
+
+## Installation
+
+```bash
+npm install @qbraid-core/ibm-cloud
+```
+
+## Usage Example
+
+```typescript
+import { IBMCloudClient} from '@qbraid-core/ibm-cloud';
+
+const apiKey = 'my-api-key';
+const serviceCRN = 'my-service-crn';
+
+const client = new IBMCloudClient(apiKey: apiKey, serviceCRN: serviceCRN);
+
+// Get a Job
+const jobID = 'my-ibm-job-id';
+const jobResponse = await client.getJob(jobID);
+console.log("Job details: ", jobResponse);
+
+// Get all devices
+const backends = await client.getBackends();
+console.log("Available backends: ", backends);
+
+// Get a backend status
+const backendName = 'ibm_marrakesh';
+const backendStatus = await client.getBackendStatus(backendName);
+console.log("Backend status: ", backendStatus);
+```
+
+## License
+
+This software is proprietary and subject to the terms of the [qBraid Commercial Software License](https://qbraid.github.io/qbraid-core-js/#license).
+
+[stable-stability]: https://img.shields.io/badge/stability-stable-green
+[preview-stability]: https://img.shields.io/badge/stability-preview-orange
+[deprecated-stability]: https://img.shields.io/badge/stability-deprecated-red

package/dist/src/client.d.ts

@@ -0,0 +1,21 @@
+import { AllDevicesResponse, DeviceProperties, DeviceConfiguration, DeviceStatus, JobList, Job, GetJobParams, CancelJobResponse, DeleteJobResponse } from './types';
+export declare class IBMCloudClient {
+    private apiKey?;
+    private token?;
+    private crn;
+    private baseUrl;
+    private client;
+    constructor({ apiKey, token, crn }: {
+        apiKey?: string;
+        token?: string;
+        crn: string;
+    });
+    getBackends(): Promise<AllDevicesResponse>;
+    getBackendProperties(backendName: string, updatedBefore?: string): Promise<DeviceProperties>;
+    getBackendConfiguration(backendName: string): Promise<DeviceConfiguration>;
+    getBackendStatus(backendName: string): Promise<DeviceStatus>;
+    getJobs(params?: GetJobParams): Promise<JobList>;
+    getJob(jobId: string, excludeParams?: boolean): Promise<Job>;
+    deleteJob(jobId: string): Promise<DeleteJobResponse>;
+    cancelJob(jobId: string, parentJobId?: string): Promise<CancelJobResponse>;
+}

package/dist/src/client.js

@@ -0,0 +1,88 @@
+"use strict";
+// Copyright (c) 2025, qBraid Development Team
+// All rights reserved.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IBMCloudClient = void 0;
+const https_1 = require("https");
+const axios_1 = __importDefault(require("axios"));
+class IBMCloudClient {
+    apiKey;
+    token;
+    crn;
+    baseUrl;
+    client;
+    constructor({ apiKey, token, crn }) {
+        if (!apiKey && !token) {
+            throw new Error('Either apiKey or token must be provided');
+        }
+        this.apiKey = apiKey;
+        this.token = token;
+        this.crn = crn;
+        this.baseUrl = 'https://us-east.quantum-computing.cloud.ibm.com/';
+        const headers = {
+            'Service-CRN': this.crn,
+            Authorization: this.apiKey ? `apikey ${this.apiKey}` : `Bearer ${this.token}`,
+        };
+        const axiosInstance = axios_1.default.create({
+            baseURL: this.baseUrl,
+            headers,
+            httpsAgent: new https_1.Agent({ keepAlive: true }),
+        });
+        this.client = axiosInstance;
+    }
+    // 1. GET /backends - get all backends from IBM
+    async getBackends() {
+        const response = await this.client.get('/backends');
+        return response.data;
+    }
+    // 2. GET /backends/:backend_name/properties - get all properties of a specific backend
+    async getBackendProperties(backendName, updatedBefore // format : YYYY-MM-DDThh:mm:ssZ
+    ) {
+        const params = updatedBefore ? { updated_before: updatedBefore } : undefined;
+        const response = await this.client.get(`/backends/${backendName}/properties`, { params: params });
+        return response.data;
+    }
+    // 3. GET /backends/:backend_name/configuration - get all configuration of a specific backend
+    async getBackendConfiguration(backendName) {
+        const response = await this.client.get(`/backends/${backendName}/configuration`);
+        return response.data;
+    }
+    // 4. GET /backends/:backend_name/status - get the status of a specific backend
+    async getBackendStatus(backendName) {
+        const response = await this.client.get(`/backends/${backendName}/status`);
+        return response.data;
+    }
+    // 5. GET /jobs - get all jobs from IBM
+    async getJobs(params) {
+        const response = await this.client.get('/jobs', { params });
+        return response.data;
+    }
+    // 6. GET /jobs/:job_id - get a specific job from IBM
+    async getJob(jobId, excludeParams) {
+        const response = await this.client.get(`/jobs/${jobId}`, {
+            params: { exclude_params: excludeParams }, // true will omit the params field in response
+        });
+        return response.data;
+    }
+    // 7. DELETE /jobs/:job_id - delete a specific job from IBM
+    async deleteJob(jobId) {
+        const response = await this.client.delete(`/jobs/${jobId}`);
+        return response.data;
+    }
+    // 8. POST /jobs/:job_id/cancel - cancel a specific job from IBM
+    async cancelJob(jobId, parentJobId) {
+        const customHeader = parentJobId ? { 'parent-job-id': parentJobId } : {};
+        const response = await this.client.post(`/jobs/${jobId}/cancel`, null, {
+            headers: {
+                ...this.client.defaults.headers.common,
+                ...customHeader,
+            },
+        });
+        return response.data;
+    }
+}
+exports.IBMCloudClient = IBMCloudClient;
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module ibm-cloud
+ */
+export { IBMCloudClient } from './client';
+export type { DeleteJobResponse, CancelJobResponse, RunJobResponse, Job, JobList, DeviceProperties, DeviceStatus, DeviceConfiguration, } from './types';

package/dist/src/index.js

@@ -0,0 +1,11 @@
+"use strict";
+// Copyright (c) 2025, qBraid Development Team
+// All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IBMCloudClient = void 0;
+/**
+ * @module ibm-cloud
+ */
+var client_1 = require("./client");
+Object.defineProperty(exports, "IBMCloudClient", { enumerable: true, get: function () { return client_1.IBMCloudClient; } });
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,8CAA8C;AAC9C,uBAAuB;;;AAEvB;;GAEG;AACH,mCAA0C;AAAjC,wGAAA,cAAc,OAAA"}

package/dist/src/types.d.ts

@@ -0,0 +1,217 @@
+export interface AllDevicesResponse {
+    devices: string[];
+}
+export interface GateParam {
+    date: string;
+    name: string;
+    unit: string;
+    value: number;
+}
+export interface Gate {
+    gate: string;
+    name: string;
+    parameters: GateParam[];
+    qubits: number[];
+}
+export interface Property {
+    date: string;
+    name: string;
+    unit: string;
+    value: number;
+}
+export type Qubit = Property[];
+export interface QList {
+    name: string;
+    qubits: number[];
+}
+export interface DeviceProperties {
+    backend_name: string;
+    backend_version: string;
+    gates: Gate[];
+    general: Property[];
+    general_qlists: QList[];
+    last_update_date: string;
+    qubits: Qubit[];
+}
+export type QubitMap = {
+    [key: string]: number;
+};
+export type VarMap = {
+    [key: string]: number;
+};
+export interface Channel {
+    operates: {
+        qubits: number[];
+    };
+    purpose: string;
+    type: string;
+}
+export type ChannelsMap = {
+    [key: string]: Channel;
+};
+export interface Hamiltonian {
+    description: string;
+    h_latex: string;
+    h_str: string[];
+    osc: any;
+    qub: QubitMap;
+    vars: VarMap;
+}
+export interface ProcessorType {
+    family: string;
+    revision: number;
+}
+export interface PhysicalGate {
+    name: string;
+    parameters: string[];
+    qasm_def: string;
+    coupling_map: number[][];
+}
+export interface UChannelLo {
+    q: number;
+    scale: number[];
+}
+export interface DeviceConfiguration {
+    allow_q_object: boolean;
+    backend_name: string;
+    backend_version: string;
+    clops: null;
+    clops_h: number;
+    clops_v: string;
+    conditional: boolean;
+    credits_required: boolean;
+    default_rep_delay: number;
+    description: string;
+    dt: number;
+    dtm: number;
+    dynamic_reprate_enabled: boolean;
+    local: boolean;
+    max_experiments: number;
+    max_shots: number;
+    measure_esp_enabled: boolean;
+    memory: boolean;
+    multi_meas_enabled: boolean;
+    n_qubits: number;
+    n_registers: number;
+    n_uchannels: number;
+    online_date: string;
+    open_pulse: boolean;
+    parallel_compilation: boolean;
+    quantum_volume: number;
+    sample_name: string;
+    simulator: boolean;
+    timing_constraints: {
+        acquire_alignment: number;
+        granularity: number;
+        min_length: number;
+        pulse_alignment: number;
+    };
+    uchannels_enabled: boolean;
+    url: string;
+    basis_gates: string[];
+    channels: ChannelsMap;
+    acquisition_latency: number[][];
+    conditional_latency: number[][];
+    coords: number[][];
+    coupling_map: number[][];
+    discriminators: string[];
+    gates: PhysicalGate[];
+    hamiltonian: Hamiltonian;
+    meas_levels: number[];
+    meas_kernels: string[];
+    meas_lo_range: number[][];
+    meas_map: number[][];
+    parametric_pulses: string[];
+    processor_type: ProcessorType;
+    qubit_channel_mapping: string[][];
+    qubit_lo_range: number[][];
+    rep_delay_range: number[];
+    rep_times: number[];
+    supported_features: string[];
+    supported_instructions: string[];
+    u_channel_lo: UChannelLo[][];
+}
+export interface DeviceStatus {
+    state: boolean;
+    status: string;
+    message: string;
+    length_queue: number;
+    backend_version: string;
+}
+export interface JobState {
+    status: string;
+    reason?: string;
+    reason_code?: number;
+    reason_solution?: string;
+}
+export interface RemoteStorage {
+    type: string;
+    region: string;
+    region_type: string;
+    bucket_crn: string;
+    job_params: {
+        type: string;
+        region: string;
+        region_type: string;
+        bucket_crn: string;
+        object_name: string;
+    };
+}
+export interface Job {
+    id: string;
+    state: JobState;
+    status: string;
+    program: {
+        id: string;
+    };
+    created: string;
+    cost: number;
+    backend?: string;
+    params?: any;
+    runtime?: string;
+    tags?: string[];
+    remote_storage?: RemoteStorage;
+    session_id?: string;
+    user_id?: string;
+    usage?: {
+        seconds: number;
+    };
+}
+export interface JobList {
+    limit: number;
+    offset: number;
+    jobs?: Job[];
+    count?: number;
+}
+export interface GetJobParams {
+    limit?: number;
+    offset?: number;
+    pending?: boolean;
+    program?: string;
+    backend?: string;
+    created_after?: string;
+    created_before?: string;
+    sort?: string;
+    tags?: string[];
+    session_id?: string;
+    exclude_params?: boolean;
+}
+export interface RunJobResponse {
+    id: string;
+    backend: string;
+    session_id?: string;
+}
+export interface ErrorResponse {
+    code: number;
+    message: string;
+    solution: string;
+    more_info: string;
+}
+export interface CancelJobResponse {
+    errors?: ErrorResponse[];
+    trace?: string;
+}
+export interface DeleteJobResponse {
+    errors?: ErrorResponse[];
+    trace?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Copyright (c) 2025, qBraid Development Team
+// All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,8CAA8C;AAC9C,uBAAuB"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@qbraid-core/ibm-cloud",
+  "version": "0.7.0",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "description": "Functionality for interacting with Qiskit Runtime services on qBraid Cloud.",
+  "author": "qBraid Development Team",
+  "license": "Proprietary",
+  "files": [
+    "dist/src"
+  ],
+  "keywords": [
+    "qbraid",
+    "qbraid-core",
+    "qbraid-core-js",
+    "qbraid ibm",
+    "qbraid cloud",
+    "qbraid api",
+    "qbraid apis",
+    "cloud",
+    "quantum",
+    "quantum computing",
+    "ibm"
+  ],
+  "repository": {
+    "type": "git",
+    "directory": "packages/ibm-cloud",
+    "url": "git+https://github.com/qBraid/qbraid-core-js.git"
+  },
+  "homepage": "https://qbraid.github.io/qbraid-core-js/modules/ibm-cloud.html",
+  "dependencies": {
+    "axios": "^1.7.9",
+    "fs": "^0.0.1-security",
+    "ini": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/ini": "^4.1.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo src/*.js",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.{ts,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,json}\"",
+    "docs": "typedoc"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}