@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 Chained Credential Provider, which is a function that will return the first provider successfully instantiated. It uses environment variables with the prefix BYU_OIT_ to attempt instantiation. If a different credential provider is needed, or if you would like to specify which credential provider should be used, 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})

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

[!NOTE] Even though we've allowed for a small piece of backwards compatibility, it is STRONGLY recommended that you update your requests to follow the usage of the Fetch API package, as this is the API package node has officially implemented.

This has been modified to remove the need for hardcoding the domain name in your repo. By default, it will infer that you are using the prod endpoint (api.byu.edu), but if you need to switch environments, you will need to declare a variable in your .env file name ENVIRONMENT_NAME. This can be any of the three:

• prd: Uses the production endpoint (api.byu.edu).
• sandbox: Uses the sandbox endpoint (api-sandbox.byu.edu).
• dev: Uses the development endpoint (api-dev.byu.edu).

[!NOTE] The dev environment is intended solely for testing and development in Tyk.

Additionally, ensure that BYU_OIT_CLIENT_ID and BYU_OIT_CLIENT_SECRET are also defined in your environment or configuration. No other environment variables are needed.

Here is an example of how to call the echo endpoint:

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

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

/** Call the request function with the listne path you wish to hit */
const response = await client.request({url: 'echo/v1/echo/test'}) // i.e. https://api.byu.edu/echo/v1/echo/test

This will return to full response from this API call. The request function always expects an object with at least an url variable declared within it. By default, though, the request function assumes the following:

const defaultSettings = {
  method: 'GET',
  json: true,
  resolveWithFullResponse: true,
  encoding: 'utf8',
  headers: {
    Accept: 'application/json'
  }
}

Each of these fields are completely changeable though and will react accordingly if any other method, such as PUT or POST, is passed in. Though not specifically stated as a default setting, a body variable can also be added to the object being passed into the function's object for any method requiring one. Here is an example of a post to try and get a token:

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

  const reqHeaders = { 'Content-Type': 'application/json', Accept: '*/*' }
  const reqBody = {
    "basic": {
      "id": 123456,
      "citationId": 1234567,
      "appealStatus": "LTRSENT",
      "appealedByByuId": "123456789",
      "appealReasonCode": "OTHER",
      "appealText": "This is a test appeal",
      "appealFineAmount": 1.00,
      "appealDate": "2020-06-29T18:19:56",
      "appealRelToOwner": "SELF",
      "decisionDate": null,
      "decisionCode": null,
      "decisionNotes": null,
      "updatedByByuId": "123456789",
      "dateTimeUpdated": "2020-06-29T12:19:57"
    },
    "flags": [ "SEND_EMAIL" ]
}
  const request = {
    url: '/domains/parking/rest/v3/appeals/123456',
    method: 'PUT',
    headers: reqHeaders,
    body: reqBody
  }

  const response = await client.request(request)

Finally, there is a variable called resolveWithFullResponse which, if set to false, will automatically only return the body of a request. This was a feature used in byu-wso2-request as part of its usage of the now deprecated Request package.