From a7cbf84eaf78404b16e7063f3482b9792715d286 Mon Sep 17 00:00:00 2001 From: Oleksandr Pravosudko Date: Tue, 6 Jul 2021 14:57:28 +0000 Subject: [PATCH] chore: add GH templates doc: adopt common management SDK README template OKTA-404875 <<>> Artifact: okta-sdk-nodejs Files changed count: 6 PR Link: "https://github.com/okta/okta-sdk-nodejs/pull/262" --- .github/ISSUE_TEMPLATE/bug_report.md | 35 +++++++ .github/ISSUE_TEMPLATE/config.yaml | 0 .github/ISSUE_TEMPLATE/feature_request.md | 29 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 43 +++++++++ CONTRIBUTING.md | 4 +- README.md | 107 ++++++++++++++-------- 6 files changed, 179 insertions(+), 39 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yaml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..816408ee0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,35 @@ +--- +name: Bug report +about: Report a bug + +--- + + + + +## Current behavior + + + +## Expected behavior + + + +## Minimal reproduction of the problem with instructions + + + +## Environment + +- OS: +- Node.js version: +- Other: + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml new file mode 100644 index 000000000..e69de29bb diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..d6da8ae14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,29 @@ +--- +name: Feature request +about: Suggest an idea for this project + +--- + + + + +## User story + + + +## Proposed solution + + + +## Alternatives considered + + + +## Additional information + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..6407296b4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,43 @@ +## PR Checklist +Please check if your PR fulfills the following requirements: + +- [ ] The commit message follows our [guidelines](/okta/okta-sdk-nodejs/blob/master/CONTRIBUTING.md) +- [ ] Tests for the changes have been added (for bug fixes / features) +- [ ] Docs have been added / updated (for bug fixes / features) + + +## PR Type +What kind of change does this PR introduce? + +- [ ] Bugfix +- [ ] Feature +- [ ] Code style update (formatting, local variables) +- [ ] Refactoring (no functional changes, no api changes) +- [ ] Adding Tests +- [ ] Build related changes +- [ ] CI related changes +- [ ] Documentation changes +- [ ] Other... Please describe: + + +## What is the current behavior? + + +Issue Number: N/A + + +## What is the new behavior? + + +## Does this PR introduce a breaking change? +- [ ] Yes +- [ ] No + + + + +## Other information + + +## Reviewers + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9589b1b0..0659e75f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Some of this SDK is auto-generated from our API Spec, defined as an Open API JSO To re-build the auto generated files, use this command in a cloned copy of this repo (after ensuring the dev dependencies have been installed): ```sh -npm run build +yarn build ``` If there are modifications to the auto-generated files, please include those changes in your pull request. @@ -26,5 +26,5 @@ OKTA_CLIENT_TOKEN=xxxx_api_token Then run the tests: ```bash -npm test +yarn test ``` diff --git a/README.md b/README.md index 54a31b787..637f847e6 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,54 @@ -# okta-sdk-nodejs - +[](https://devforum.okta.com/) +[![npm](https://img.shields.io/npm/v/@okta/okta-sdk-nodejs)](https://www.npmjs.com/package/@okta/okta-sdk-nodejs) +[![Support](https://img.shields.io/badge/support-Developer%20Forum-blue.svg)][devforum] +[![API Reference](https://img.shields.io/badge/docs-reference-lightgrey.svg)][nodejsdocs] + +# Okta Node.js Management SDK + +* [Release status](#release-status) +* [Need help?](#need-help) +* [Getting started](#getting-started) +* [Usage guide](#usage-guide) +* [Configuration reference](#configuration-reference) +* [Building the SDK](#building-the-sdk) +* [TypeScript usage](#typescript-usage) + +* [Contributing](#contributing) + +## Release status + +This library uses semantic versioning and follows Okta's [library version policy](https://developer.okta.com/code/library-versions/). + +✔️: The current stable major version series is: 4.x.x + +| Version | Status | +| ------- | ------------------------- | +| 1.x | :x: Retired | +| 2.x | :x: Retired | +| 3.x | :x: Retired | +| 4.x | :heavy_check_mark: Stable ([migration guide](#from-3x-to-40)) | + +The latest release can always be found on the [releases page][github-releases]. + +## Need help? + +If you run into problems using the SDK, you can + +* Ask questions on the [Okta Developer Forums][devforum] +* Post [issues][github-issues] here on GitHub (for code errors) Node.js API Client for the [Okta Platform API]. -Requires Node.js version 10.0.0 or higher. -Need help? Contact [developers@okta.com](mailto:developers@okta.com) or use the [Okta Developer Forum]. +## Getting started + +Requires Node.js version 10.0.0 or higher. -## Installation ```sh npm install @okta/okta-sdk-nodejs ``` -## JsDocs - -You can view the entire JsDocs for this project here: https://developer.okta.com/okta-sdk-nodejs/jsdocs/ - -## Usage +## Usage guide All usage of this SDK begins with the creation of a client, the client handles the authentication and communication with the Okta API. To create a client, you need to provide it with your Okta Domain and an API token. To obtain those, see [Getting Started With the Okta APIs](https://developer.okta.com/code/rest/). @@ -61,10 +93,12 @@ The `privateKey` can be passed in the following ways: > Note: in case OAuth client app uses multiple JWKs, `privateKey` should specify `kid` attribute. -## Table of Contents -* [Examples](#examples) - * [Users](#users) +## Examples + +This library is a wrapper for the [Okta Platform API], which should be referred to as the source-of-truth for what is and isn't possible with the API. In the following sections we show you how to use your client to perform some common operations with the [Okta Platform API]. + + * [Users](#users) * [Create a User](#create-a-user) * [Get a User](#get-a-user) * [Update a User](#update-a-user) @@ -84,20 +118,6 @@ The `privateKey` can be passed in the following ways: * [Collection](#collection) * [each](#each) * [subscribe](#subscribeconfig) -* [Configuration](#configuration) -* [Caching](#caching) -* [Rate Limiting](#rate-limiting) - * [Built-In Retry](#built-in-retry) - * [Manual Retry](#manual-retry) -* [Request Executor](#request-executor) - * [Default Request Executor](#default-request-executor) - * [Base Request Executor](#base-request-executor) -* [Migrating between versions](#migrating-between-versions) - - -## Examples - -This library is a wrapper for the [Okta Platform API], which should be referred to as the source-of-truth for what is and isn't possible with the API. In the following sections we show you how to use your client to perform some common operations with the [Okta Platform API]. ### Users @@ -414,15 +434,15 @@ client.http.http(url, request) }); ``` -## Collection +### Collection When the client is used to fetch collections of resources, a collection instance is returned. The collection encapsulates the work of paginating the API to fetch all resources in the collection (see [Pagination]). The collection provides the `each()` method for iterating over the collection, as described below. -### `each()` +#### `each()` Allows you to visit every item in the collection, while optionally doing work at each item. All calls to `each()` will return a promise that is resolved when all items have been visited or rejected if you return a rejected promise from your iterator. Iteration can be stopped by rejecting a returned promise, or by returning `false` (will not cause a promise rejection). The following examples show you the various use-cases. -#### Serial or Parallel Synchronous Work +##### Serial or Parallel Synchronous Work If no value is returned, `each()` will continue to the next item: @@ -436,7 +456,7 @@ client.listUsers().each(user => { }); ``` -#### Serial Asynchronous Work +##### Serial Asynchronous Work Returning a promise will pause the iterator until the promise is resolved: @@ -448,7 +468,7 @@ client.listUsers().each(user => { }); ``` -#### Ending Iteration +##### Ending Iteration Returning `false` will end iteration: @@ -485,7 +505,7 @@ return client.listUsers().each(user => { }); ``` -### `subscribe(config)` +#### `subscribe(config)` A subscription allows you to continue paginating a collection until new items are available, if the REST API supports it for the collection. The only supported collection is the [System Log API] at this time. @@ -493,7 +513,7 @@ A subscription fetches pages until the first empty page is reached. From that po Depending on the polling interval you choose, you may run into rate limiting exceptions. In that case you should enable our rate limiting retry strategy, see [Rate Limiting](#rate-limiting). -#### Simple subscription example +##### Simple subscription example ```javascript const subscription = collection.subscribe({ interval: 5000, @@ -509,7 +529,7 @@ const subscription = collection.subscribe({ subscription.unsubscribe() ``` -## Configuration +## Configuration Reference There are several ways to provide configuration to the client constructor. When creating a new client, the following locations are searched in order, in a last-one-wins fashion: @@ -770,7 +790,10 @@ const client = new okta.Client({ }) ``` -### TypeScript usage examples (>=4.5.0) +## TypeScript usage + +### 4.5.x + ```typescript import { Client } from '@okta/okta-sdk-nodejs' @@ -821,7 +844,7 @@ client.createApplication(bookmarkAppOptions).then((createdApp: Application) => { }); ``` -#### TypeScript usage examples (>=4.6.0) +### >=4.6.x Models can be imported from library root: @@ -848,6 +871,10 @@ This version 4.0 release also updated APIs latest `@okta/openapi` (v2.0.0) that - Model and Client methods change for `User` related operations - Model and Client methods change for `Rule` related operations +## Building the SDK + +Run `yarn build` from repository root. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) if you would like to propose changes to this library. @@ -877,3 +904,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) if you would like to propose changes to t [Users: List Users]: https://developer.okta.com/docs/api/resources/users#list-users [Users: Update User]: https://developer.okta.com/docs/api/resources/users#update-user [Okta NodeJS Management SDK JSDoc Site]: https://developer.okta.com/okta-sdk-nodejs/jsdocs/ + +[devforum]: https://devforum.okta.com/ +[nodejsdocs]: https://developer.okta.com/okta-sdk-nodejs/jsdocs/ +[github-issues]: https://github.com/okta/okta-sdk-nodejs/issues +[github-releases]: https://github.com/okta/okta-sdk-nodejs/releases +