Skip to content

Latest commit

 

History

History
118 lines (91 loc) · 4.46 KB

README.md

File metadata and controls

118 lines (91 loc) · 4.46 KB
Raw

Build Status npm-version semantic-release CLA assistant

IBM Node.js SDK Core

This project contains core functionality required by Node.js code generated by the IBM Cloud OpenAPI SDK Generator (openapi-sdkgen).

Installation

`npm install ibm-cloud-sdk-core`

Prerequisites

  • Node.js version 18 or newer

Usage

This package exports a single object containing a number of modules as top level properties.

Example:

// this is TypeScript, since the `openapi-sdkgen` project generates TypeScript
import { BaseService } from 'ibm-cloud-sdk-core';

class YourSDK extends BaseService { ... }

Authentication

The node-sdk-core project supports the following types of authentication:

  • Basic Authentication
  • Bearer Token Authentication
  • Identity and Access Management (IAM) Authentication (grant type: apikey)
  • Identity and Access Management (IAM) Authentication (grant type: assume)
  • Container Authentication
  • VPC Instance Authentication
  • Cloud Pak for Data Authentication
  • No Authentication (for testing)

There are two ways to create an authenticator:

  1. Creating an instance and providing credentials programmatically
  2. Using the getAuthenticatorFromEnvironment function to create an authenticator from externally-provided configuration

For more information about the various authentication types and how to use them with your services, click here.

Examples

Programmatic

import { IamAuthenticator } from 'ibm-cloud-sdk-core';

const authenticator = new IamAuthenticator({
  apikey: '{apikey}',
});

External configuration

import { getAuthenticatorFromEnvironment } from 'ibm-cloud-sdk-core';

// env vars
// MY_SERVICE_AUTH_TYPE=iam
// MY_SERVICE_APIKEY=<apikey>
const iamAuthenticator = getAuthenticatorFromEnvironment('my-service');

Logging

This package uses debug for logging.

  • Logging is disabled by default.
  • Logging has been configured to use log levels which are assumed to be numerically ascending from most important to least important.
  • In order to see the log output, set the environment variable DEBUG including the desired log level.
    • DEBUG=ibm-cloud-sdk-core:error enables error logs
    • DEBUG=ibm-cloud-sdk-core:warning enables warning logs and below
    • DEBUG=ibm-cloud-sdk-core:info enables info logs and below
    • DEBUG=ibm-cloud-sdk-core:verbose enables verbose logs and below
    • DEBUG=ibm-cloud-sdk-core:debug enables debug logs and below

To see the output from all of the debugging levels you can use:

DEBUG=ibm-cloud-sdk-core*

The debug logger can be configured to be used for more than one library. For example, you can set a comma-separated string:

DEBUG=ibm-cloud-sdk-core:debug,other-lib:debug

Cookie Jar Support

By default, cookies are not supported in the SDK requests. If your SDK would benefit from this functionality, simply edit your code to instantiate a cookie jar (or instruct your users to do so) and pass it in the object containing configuration options to the BaseService class, as shown below. If the Boolean value true is given for the jar field, the SDK core will create a default instance of a Tough Cookie.

import tough = require('tough-cookie');

class MyClass extends BaseService {
  constructor(options: MyOptions) {
    // pass the cookie jar object or simply pass the value `true`
    // and a tough-cookie instance will be created by default
    options.jar = new tough.CookieJar();
    super(options);
  }
}

Issues

If you encounter an issue with this project, you are welcome to submit a bug report. Before opening a new issue, please search for similar issues. It's possible that someone has already reported it.

Tests

Run all test suites:

npm test

Contributing

See CONTRIBUTING.

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.