@planqk/planqk-service-sdk 2.1.1 → 2.2.0

package/.gitlab-ci.yml

@@ -1,9 +1,5 @@
 variables:
   TWINE_USERNAME: __token__
-  DATADOG_STATIC_ANALYZER_URL: "https://github.com/DataDog/datadog-static-analyzer/releases/latest/download/datadog-static-analyzer-x86_64-unknown-linux-gnu.zip"
-  DATADOG_OSV_SCANNER_URL: "https://github.com/DataDog/osv-scanner/releases/latest/download/osv-scanner_linux_amd64.zip"
-  DATADOG_ENV: "ci"
-  DATADOG_SERVICE: "planqk-service-sdk"
   UV_VERSION: 0.6
   PYTHON_VERSION: 3.11
   BASE_LAYER: bookworm-slim
@@ -17,41 +13,6 @@ stages:
   - commit-release-check
   - release-package
 
-datadog-static-analyzer:
-  stage: commit-test
-  rules:
-    - if: '$CI_COMMIT_MESSAGE =~ /^chore\(release\):/'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "web"'
-    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-  image: node:lts
-  before_script:
-    - npm install -g @datadog/datadog-ci
-    - curl -L $DATADOG_STATIC_ANALYZER_URL > /tmp/datadog-static-analyzer.zip
-    - unzip /tmp/datadog-static-analyzer.zip -d /tmp
-    - mv /tmp/datadog-static-analyzer /usr/local/datadog-static-analyzer
-  script:
-    - /usr/local/datadog-static-analyzer -i . -o /tmp/report.sarif -f sarif
-    - datadog-ci sarif upload /tmp/report.sarif --service "$DATADOG_SERVICE" --env "$DATADOG_ENV"
-
-datadog-sbom-analyzer:
-  stage: commit-test
-  rules:
-    - if: '$CI_COMMIT_MESSAGE =~ /^chore\(release\):/'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "web"'
-    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-  image: node:lts
-  before_script:
-    - npm install -g @datadog/datadog-ci
-    - mkdir /osv-scanner
-    - curl -L -o /osv-scanner/osv-scanner.zip $DATADOG_OSV_SCANNER_URL
-    - unzip /osv-scanner/osv-scanner.zip -d /osv-scanner
-    - chmod 755 /osv-scanner/osv-scanner
-  script:
-    - /osv-scanner/osv-scanner --skip-git -r --experimental-only-packages --format=cyclonedx-1-5 --paths-relative-to-scan-dir --output=/tmp/sbom.json .
-    - datadog-ci sbom upload --service "$DATADOG_SERVICE" --env "$DATADOG_ENV" /tmp/sbom.json
-
 semantic-release:
   stage: commit-release-check
   rules:
@@ -59,6 +20,13 @@ semantic-release:
       when: never
     - if: '$CI_PIPELINE_SOURCE == "web"'
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  variables:
+    ## Use the gitlab user to create the release commit
+    ## https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#git-environment-variables
+    GIT_AUTHOR_NAME: "$GITLAB_USER_NAME"
+    GIT_AUTHOR_EMAIL: "$GITLAB_USER_EMAIL"
+    GIT_COMMITTER_NAME: "$GITLAB_USER_NAME"
+    GIT_COMMITTER_EMAIL: "$GITLAB_USER_EMAIL"
   image: node:lts
   before_script:
     - apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
@@ -95,6 +63,7 @@ publish-node-sdk:
     - npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
   script:
     - npm ci
+    - cp README-node.md README.md
     - npm run build
     - npm publish
   cache:

package/README-node.md

@@ -17,25 +17,29 @@ const consumerSecret = "..."
 
 const client = new PlanqkServiceClient(serviceEndpoint, consumerKey, consumerSecret)
 
-// prepare your input data and parameters
-const data = {input: {a: 1, b: 2}};
-const params = {param1: "value1", param2: "value2"};
+// List all service executions
+const serviceExecutions = await client.api().getServiceExecutions()
 
-// execute the service
-let serviceExecution = await client.api().execute({data, params})
+// Start a new service execution
+const data = {n_coin_tosses: 2}
+const params = {shots: 100}
+let serviceExecution = await client.api().startExecution({data, params}, {timeoutInSeconds: 60})
 
-// retrieve the status of a service execution
-serviceExecution = await client.api().getStatus(serviceExecution.id!);
+// Check the status of the service execution
+serviceExecution = await client.api().getStatus(serviceExecution.id!)
 
-// wait for the service execution to finish
-const finalStates = ["SUCCEEDED", "CANCELLED", "FAILED"];
+// Wait for the service execution to finish
+const finalStates = ["SUCCEEDED", "CANCELLED", "FAILED"]
 while (!finalStates.includes(serviceExecution.status!)) {
-  serviceExecution = await client.api().getStatus(serviceExecution.id!);
+  serviceExecution = await client.api().getStatus(serviceExecution.id!)
 }
 
-// retrieve the result
+// Get the result of the service execution
 const result = await client.api().getResult(serviceExecution.id!)
 
-// retrieve the logs
+// Get the logs of the service execution
 const logs = await client.api().getLogs(serviceExecution.id!)
+
+// Cancel the service execution if it is still pending or running
+await client.api().cancelExecution(serviceExecution.id!)
 ```

package/README.md

@@ -1,56 +1,45 @@
-# planqk-service-sdk
+# PLANQK Service SDK
 
-This repository contains the SDK clients to execute PLANQK Managed Services.
-The clients are generated from a very general [OpenAPI](https://swagger.io/specification) description using [Fern](https://buildwithfern.com).
-The generated clients are a baseline, and the idea is to adapt and extend them to our specific needs.
+## Installation
 
-## Generate the SDK clients with Fern
-
-> <https://buildwithfern.com/docs/getting-started>
-
-```bash
-npm install -g fern-api
-fern upgrade
-fern generate
-```
-
-## Python Setup
-
-To create a new virtual environment and install the dependencies, run:
+The package can be installed using `npm`:
 
 ```bash
-uv venv
-source .venv/bin/activate
-
-uv sync
-```
-
-Update dependencies and lock files:
-
-```bash
-uv sync -U
+npm install @planqk/planqk-service-sdk
 ```
 
-## How to update the Python client?
+## Usage
 
-After generating the SDK clients with Fern, the Python client needs to be copied manually.
+```typescript
+const serviceEndpoint = "..."
+const consumerKey = "..."
+const consumerSecret = "..."
 
-Copy the content of `./generated/python` to `./planqk/service/sdk`.
-Make sure you overwrite any existing files.
-It is recommended to remove the old files first.
+const client = new PlanqkServiceClient(serviceEndpoint, consumerKey, consumerSecret)
 
-Next, check by executing `pytest` if the changes are compatible with our wrapper.
+// List all service executions
+const serviceExecutions = await client.api().getServiceExecutions()
 
-## How to update the TypeScript client?
+// Start a new service execution
+const data = {n_coin_tosses: 2}
+const params = {shots: 100}
+let serviceExecution = await client.api().startExecution({data, params}, {timeoutInSeconds: 60})
 
-After generating the SDK clients with Fern, the TypeScript client needs to be copied manually.
+// Check the status of the service execution
+serviceExecution = await client.api().getStatus(serviceExecution.id!)
 
-Copy the content of `./generated/typescript` to `./typescript/src/sdk`.
-Make sure you overwrite any existing files.
-It is recommended to remove the old files first.
+// Wait for the service execution to finish
+const finalStates = ["SUCCEEDED", "CANCELLED", "FAILED"]
+while (!finalStates.includes(serviceExecution.status!)) {
+  serviceExecution = await client.api().getStatus(serviceExecution.id!)
+}
 
-Next, check by executing `npm test` if the changes are compatible with our wrapper.
+// Get the result of the service execution
+const result = await client.api().getResult(serviceExecution.id!)
 
-## License
+// Get the logs of the service execution
+const logs = await client.api().getLogs(serviceExecution.id!)
 
-Apache-2.0 | Copyright 2023-2024 Kipu Quantum GmbH
+// Cancel the service execution if it is still pending or running
+await client.api().cancelExecution(serviceExecution.id!)
+```

package/dist/sdk/Client.d.ts

@@ -1,13 +1,17 @@
 /**
  * This file was auto-generated by Fern from our API Definition.
  */
-import * as environments from "./environments";
-import * as core from "./core";
-import { ServiceApi } from "./api/resources/serviceApi/client/Client";
+import * as environments from "./environments.js";
+import * as core from "./core/index.js";
+import { ServiceApi } from "./api/resources/serviceApi/client/Client.js";
 export declare namespace PlanqkServiceApiClient {
     interface Options {
         environment?: core.Supplier<environments.PlanqkServiceApiEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
         token: core.Supplier<core.BearerToken>;
+        /** Additional headers to include in requests. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
     }
     interface RequestOptions {
         /** The maximum time to wait for a response in seconds. */
@@ -16,11 +20,13 @@ export declare namespace PlanqkServiceApiClient {
         maxRetries?: number;
         /** A hook to abort the request. */
         abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
     }
 }
 export declare class PlanqkServiceApiClient {
     protected readonly _options: PlanqkServiceApiClient.Options;
-    constructor(_options: PlanqkServiceApiClient.Options);
     protected _serviceApi: ServiceApi | undefined;
+    constructor(_options: PlanqkServiceApiClient.Options);
     get serviceApi(): ServiceApi;
 }

package/dist/sdk/Client.js

@@ -2,17 +2,59 @@
 /**
  * This file was auto-generated by Fern from our API Definition.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanqkServiceApiClient = void 0;
-const Client_1 = require("./api/resources/serviceApi/client/Client");
+const core = __importStar(require("./core/index.js"));
+const headers_js_1 = require("./core/headers.js");
+const Client_js_1 = require("./api/resources/serviceApi/client/Client.js");
 class PlanqkServiceApiClient {
     _options;
+    _serviceApi;
     constructor(_options) {
-        this._options = _options;
+        this._options = {
+            ..._options,
+            headers: (0, headers_js_1.mergeHeaders)({
+                "X-Fern-Language": "JavaScript",
+                "X-Fern-Runtime": core.RUNTIME.type,
+                "X-Fern-Runtime-Version": core.RUNTIME.version,
+            }, _options?.headers),
+        };
     }
-    _serviceApi;
     get serviceApi() {
-        return (this._serviceApi ??= new Client_1.ServiceApi(this._options));
+        return (this._serviceApi ??= new Client_js_1.ServiceApi(this._options));
     }
 }
 exports.PlanqkServiceApiClient = PlanqkServiceApiClient;

package/dist/sdk/api/index.d.ts

@@ -1,3 +1,2 @@
-export * from "./resources";
-export * from "./types";
-export * from "./errors";
+export * from "./resources/index.js";
+export * from "./types/index.js";

package/dist/sdk/api/index.js

@@ -14,6 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./resources"), exports);
-__exportStar(require("./types"), exports);
-__exportStar(require("./errors"), exports);
+__exportStar(require("./resources/index.js"), exports);
+__exportStar(require("./types/index.js"), exports);

package/dist/sdk/api/resources/index.d.ts

@@ -1,2 +1,2 @@
-export * as serviceApi from "./serviceApi";
-export * from "./serviceApi/types";
+export * as serviceApi from "./serviceApi/index.js";
+export * from "./serviceApi/types/index.js";

package/dist/sdk/api/resources/index.js

@@ -37,5 +37,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serviceApi = void 0;
-exports.serviceApi = __importStar(require("./serviceApi"));
-__exportStar(require("./serviceApi/types"), exports);
+exports.serviceApi = __importStar(require("./serviceApi/index.js"));
+__exportStar(require("./serviceApi/types/index.js"), exports);

package/dist/sdk/api/resources/serviceApi/client/Client.d.ts

@@ -1,14 +1,17 @@
 /**
  * This file was auto-generated by Fern from our API Definition.
  */
-import * as environments from "../../../../environments";
-import * as core from "../../../../core";
-import * as PlanqkServiceApi from "../../../index";
-import * as stream from "stream";
+import * as environments from "../../../../environments.js";
+import * as core from "../../../../core/index.js";
+import * as PlanqkServiceApi from "../../../index.js";
 export declare namespace ServiceApi {
     interface Options {
         environment?: core.Supplier<environments.PlanqkServiceApiEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
         token: core.Supplier<core.BearerToken>;
+        /** Additional headers to include in requests. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
     }
     interface RequestOptions {
         /** The maximum time to wait for a response in seconds. */
@@ -17,108 +20,91 @@ export declare namespace ServiceApi {
         maxRetries?: number;
         /** A hook to abort the request. */
         abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
     }
 }
 export declare class ServiceApi {
     protected readonly _options: ServiceApi.Options;
     constructor(_options: ServiceApi.Options);
     /**
-     * This method checks the health of the service.
+     * Retrieves a list of all service executions.
+     * The response includes links to each service execution, allowing for further queries on their status and results.
      *
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @example
-     *     await client.serviceApi.healthCheck()
+     *     await client.serviceApi.getServiceExecutions()
      */
-    healthCheck(requestOptions?: ServiceApi.RequestOptions): Promise<PlanqkServiceApi.HealthCheckResponse>;
+    getServiceExecutions(requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<PlanqkServiceApi.ServiceExecution[]>;
+    private __getServiceExecutions;
     /**
-     * This method starts a service execution, which in turn is processed asynchronously by PLANQK.
+     * Starts a service execution, which in turn is processed asynchronously.
      * The location header of the response contains the URL which can be used to query the status and the result of the service execution.
      *
-     * @param {Record<string, Record<string, any>>} request
+     * @param {Record<string, any>} request
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
-     * @throws {@link PlanqkServiceApi.BadRequestError}
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
-     *
      * @example
-     *     await client.serviceApi.execute({
-     *         "key": {
-     *             "key": "value"
-     *         }
+     *     await client.serviceApi.startExecution({
+     *         "key": "value"
      *     })
      */
-    execute(request: Record<string, Record<string, any>>, requestOptions?: ServiceApi.RequestOptions): Promise<PlanqkServiceApi.ServiceExecution>;
+    startExecution(request: Record<string, any>, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<PlanqkServiceApi.ServiceExecution>;
+    private __startExecution;
     /**
-     * This method checks the status of a service execution.
+     * Retrieves the status of a service execution.
+     * The status can be one of the following: UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED.
      *
      * @param {string} id - The id of a service execution
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
-     *
      * @example
      *     await client.serviceApi.getStatus("id")
      */
-    getStatus(id: string, requestOptions?: ServiceApi.RequestOptions): Promise<PlanqkServiceApi.ServiceExecution>;
+    getStatus(id: string, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<PlanqkServiceApi.ServiceExecution>;
+    private __getStatus;
     /**
-     * This method retrieves the result of a service execution.
+     * Retrieves the result of a service execution.
+     * The result is returned as a JSON object containing the status and any additional data.
+     * The result may include links to download specific result files.
      *
      * @param {string} id - The id of a service execution
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
-     *
      * @example
      *     await client.serviceApi.getResult("id")
      */
-    getResult(id: string, requestOptions?: ServiceApi.RequestOptions): Promise<PlanqkServiceApi.GetResultResponse>;
+    getResult(id: string, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<PlanqkServiceApi.GetResultResponse>;
+    private __getResult;
     /**
-     * This method downloads a result file of a service execution.
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
+     * Retrieves a specific result file of a service execution.
+     * The file name is provided in the path parameter.
+     * The result file is returned as a binary stream.
      */
-    getResultFile(id: string, file: string, requestOptions?: ServiceApi.RequestOptions): Promise<stream.Readable>;
+    getResultFile(id: string, file: string, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<core.BinaryResponse>;
+    private __getResultFile;
     /**
-     * This method retrieves the log output of a service execution.
+     * Returns a list of log entries for a service execution in chronological order, where the first entry is the oldest.
      *
      * @param {string} id - The id of a service execution
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
-     *
      * @example
      *     await client.serviceApi.getLogs("id")
      */
-    getLogs(id: string, requestOptions?: ServiceApi.RequestOptions): Promise<string[]>;
+    getLogs(id: string, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<string[]>;
+    private __getLogs;
     /**
-     * This method cancels a service execution.
+     * Cancel a pending or running service execution.
      *
      * @param {string} id - The id of a service execution
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
-     * @throws {@link PlanqkServiceApi.UnauthorizedError}
-     * @throws {@link PlanqkServiceApi.ForbiddenError}
-     * @throws {@link PlanqkServiceApi.NotFoundError}
-     * @throws {@link PlanqkServiceApi.InternalServerError}
-     *
      * @example
-     *     await client.serviceApi.cancel("id")
+     *     await client.serviceApi.cancelExecution("id")
      */
-    cancel(id: string, requestOptions?: ServiceApi.RequestOptions): Promise<PlanqkServiceApi.ServiceExecution>;
+    cancelExecution(id: string, requestOptions?: ServiceApi.RequestOptions): core.HttpResponsePromise<PlanqkServiceApi.ServiceExecution>;
+    private __cancelExecution;
     protected _getAuthorizationHeader(): Promise<string>;
 }