@byu-oit-sdk/client-byu

An OAuth 2.0-compliant library, effectively replacing byu-wso2-request.

Requirements:

• Node.js 18+
  • or Node.js 10+ with fetch and crypto polyfills
• npm v9+

Features

• Isomorphic (work in NodeJS and the browser)
• Automatically fetches and refreshes access tokens
• Automatic retries for 401 responses with a 100ms delay
• Automatically add headers to help identify the request
  • byu-oit-sdk-request supplies the attempt number and maximum number of requests
  • byu-oit-sdk-invocation-id supplies a unique identifier to track requests

Client

Initializing the client is simple. The BYU Client can be configured with some options to override the default behavior if desired.

const client = new Client()
// or
const client = new Client({ /* options here */ })

Here are a list of supported options:

| Option | Type | Default Value | Purpose | |-------------|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| | logger | Logger, from pino | ByuLogger() | (Optional) Logging information from client functionality | | credentials | CredentialProvider (or false) | ChainedCredentialProvider() | (Optional) The credential provider used resolving access tokens | | retry | { strategy: RetryMiddlewareConfiguration } | { strategy: new RetryStrategy() } | (Optional) Configures the retry middleware. The default configuration will attempt one retry when the response contains a 401 HTTP status code. |

The default credential provider is the Client Credentials provider. Any of the parameters that it accepts may be supplied via environment variables with the prefix BYU_OIT_. If a different credential provider is needed, such as the Authorization Code provider, it should be configured and passed into the BYU Client constructor.

The default retry strategy retries once on 401 HTTP response codes after a 100-millisecond delay. The token middleware will try to get a new token before the request is sent. Any middleware added after the retry middleware will also be invoked prior to each request retry.

Note Disable automatic authentication by setting the credentials option to false

const client = new Client({credentials: false})

Command

The Command class is a wrapper for the fetch options. Every command has a middleware stack that is merged into the client middleware stake upon sending a request. To instantiate a command, use the same options as the fetch API.

const command = new Command('https://example.com', { method: 'POST' })

Middleware

Middleware can be placed on the middleware stack on a command or client. If placed on the command's middleware stack, only that command will run the middleware. When placed on the client, all commands using that client instance will run the middleware.

Usage

import { Client, Command } from '@byu-oit-sdk/client-byu'

/** Instantiate the client with environment variables */
const client = new Client()

/** The issuer must be downloaded from the discovery endpoint */
const issuer = await client.issuer()
const uri = new URL('echo/v1/echo/test', issuer) // i.e. https://api.byu.edu/echo/v1/echo/test
const command = new Command(uri/**, Addtional fetch options */)

/** Send the command */
const response = await client.send(command)