MVP-276: Component docs

mkdocs.yml

@@ -11,6 +11,31 @@ nav:
       - Environment Variables: getting-started/environment-variables.md
       - SSO Settings & CSS API Account: getting-started/sso-settings.md
   - Using the Package:
+      - APIs & Components:
+          - getIntegration: using-the-package/apis-&-components/get-integration.md
+          - Roles:
+              - getRoles: using-the-package/apis-&-components/roles/get-roles.md
+              - createRole: using-the-package/apis-&-components/roles/create-role.md
+              - getRole: using-the-package/apis-&-components/roles/get-role.md
+              - updateRole: using-the-package/apis-&-components/roles/update-role.md
+              - deleteRole: using-the-package/apis-&-components/roles/delete-role.md
+              - getRoleComposites: using-the-package/apis-&-components/roles/get-role-composites.md
+              - addRoleComposite: using-the-package/apis-&-components/roles/add-role-composite.md
+              - getRoleComposite: using-the-package/apis-&-components/roles/get-role-composite.md
+              - deleteRoleComposite: using-the-package/apis-&-components/roles/delete-role-composite.md
+          - Role Mapping:
+              - getUserRoles: using-the-package/apis-&-components/role-mapping/get-user-roles.md
+              - assignUserRoles: using-the-package/apis-&-components/role-mapping/assign-user-roles.md
+              - unassignUserRole: using-the-package/apis-&-components/role-mapping/unassign-user-role.md
+              - getUsersWithRole: using-the-package/apis-&-components/role-mapping/get-users-with-role.md
+          - Users:
+              - getIDIRUsers: using-the-package/apis-&-components/users/get-idir-users.md
+              - getAzureIDIRUsers: using-the-package/apis-&-components/users/get-azure-idir-users.md
+              - getGitHubBCGovUsers: using-the-package/apis-&-components/users/get-github-bcgov-users.md
+              - getGitHubPublicUsers: using-the-package/apis-&-components/users/get-github-public-users.md
+              - getBasicBCeIDUser: using-the-package/apis-&-components/users/get-basic-bceid-user.md
+              - getBusinessBCeIDUser: using-the-package/apis-&-components/users/get-business-bceid-user.md
+              - getBothBCeIDUser: using-the-package/apis-&-components/users/get-both-bceid-user.md
       - Module Exports: using-the-package/module-exports.md
       - TypeScript Types: using-the-package/typescript-types.md
       - Troubleshooting: using-the-package/troubleshooting.md

src/roleMapping.ts

@@ -72,7 +72,7 @@ export const getUsersWithRole = async (
  * @returns No Content.
  * @example unassignUserRole('fohe4m5pn8clhkxmlho33sn1r7vr7m67@idir', 'admin');
  */
-export const unassignUserRole = async (username: string, roleName: string) => {
+export const unassignUserRole = async (username: string, roleName: string): Promise<void> => {
   debug.functionCalled('unassignUserRole');
   return await request({
     integrationEndpoint: true,

src/roles.ts

@@ -67,7 +67,7 @@ export const updateRole = async (
  * @returns No Content
  * @example deleteRole('admin');
  */
-export const deleteRole = async (roleName: string) => {
+export const deleteRole = async (roleName: string): Promise<void> => {
   debug.functionCalled('deleteRole');
   return await request({
     integrationEndpoint: true,
@@ -135,7 +135,10 @@ export const getRoleComposite = async (
  * @returns No Content
  * @example deleteRoleComposite('admin', 'admin-dashboard');
  */
-export const deleteRoleComposite = async (roleName: string, compositeRoleName: string) => {
+export const deleteRoleComposite = async (
+  roleName: string,
+  compositeRoleName: string,
+): Promise<void> => {
   debug.functionCalled('deleteRoleComposite');
   return await request({
     integrationEndpoint: true,

techdocs/docs/using-the-package/apis-&-components/get-integration.md

@@ -0,0 +1,50 @@
+# getIntegration
+
+The `getIntegration` function is used to get details about your integration from Common Hosted Single Sign-on service.
+
+!!! warning "Reminder"
+    This function is asynchronous and must be awaited in order to get a response.
+
+## Import
+
+```JavaScript
+// ESModule Syntax (preferred)
+import { getIntegration } from "@bcgov/citz-imb-sso-css-api";
+
+// CommonJS Syntax
+const { getIntegration } = require('@bcgov/citz-imb-sso-css-api');
+```
+
+## Usage
+
+A basic example of using the `getIntegration` function.
+
+```JavaScript
+import { getIntegration } from "@bcgov/citz-imb-sso-css-api";
+
+(async () => {
+  console.log(await getIntegration().projectName);
+})();
+```
+
+## TypeScript Type
+
+```TypeScript
+() => Promise<GetIntegrationResponse>;
+```
+
+### Response Type
+
+The type `GetIntegrationResponse` of `Promise<GetIntegrationResponse>`:
+
+```TypeScript
+{
+    id: number;
+    projectName: string;
+    authType: string;
+    environments: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+```

techdocs/docs/using-the-package/apis-&-components/role-mapping/assign-user-roles.md

@@ -0,0 +1,87 @@
+# assignUserRoles
+
+The `assignUserRoles` function is used to assign roles to a user in your integration from Common Hosted Single Sign-on service. 
+
+!!! warning "Reminder"
+    This function is asynchronous and must be awaited in order to get a response.
+
+## Import
+
+```JavaScript
+// ESModule Syntax (preferred)
+import { assignUserRoles } from "@bcgov/citz-imb-sso-css-api";
+
+// CommonJS Syntax
+const { assignUserRoles } = require('@bcgov/citz-imb-sso-css-api');
+```
+
+## Usage
+
+A basic example of using the `assignUserRoles` function.
+
+```JavaScript
+import { assignUserRoles } from "@bcgov/citz-imb-sso-css-api";
+
+(async () => {
+  console.log(await assignUserRoles('fohe4m5pn8clhkxmlho33sn1r7vr7m67@idir', ['Admin']));
+})();
+```
+
+## TypeScript Type
+
+```TypeScript
+(username: string, roleNames: string[]) => Promise<RolesArrayWithoutCompositeResponse>;
+```
+
+### Response Type
+
+The type `RolesArrayWithoutCompositeResponse` of `Promise<RolesArrayWithoutCompositeResponse>`:
+
+```TypeScript
+{
+    data: RoleResponseWithoutComposite[];
+}
+```
+
+The type `RoleResponseWithoutComposite`:
+
+```TypeScript
+{
+    name: string;
+}
+```
+
+## Parameters
+
+An API reference for the parameters of the `assignUserRoles` function.
+
+!!! note "Note"
+    The Name column starting with `*` means the parameter is required.
+
+<table>
+  <!-- Table columns -->
+  <thead>
+    <tr>
+      <th style="background: #6f19d9; color: white;">Name</th>
+      <th style="background: #6f19d9; color: white;">Type</th>
+      <th style="background: #6f19d9; color: white;">Default</th>
+      <th style="background: #6f19d9; color: white;">Description</th>
+    </tr>
+  </thead>
+
+  <!-- Table rows -->
+  <tbody>
+    <tr>
+      <td>* username</td>
+      <td>string</td>
+      <td>-</td>
+      <td>The preferred_username value of the user.</td>
+    </tr>
+    <tr>
+      <td>* roleNames</td>
+      <td>string[]</td>
+      <td>-</td>
+      <td>The role names to assign to the user.</td>
+    </tr>
+  </tbody>
+</table>

techdocs/docs/using-the-package/apis-&-components/role-mapping/get-user-roles.md

@@ -0,0 +1,82 @@
+# getUserRoles
+
+The `getUserRoles` function is used to get all roles associated with a user in your integration from Common Hosted Single Sign-on service. 
+
+!!! warning "Reminder"
+    This function is asynchronous and must be awaited in order to get a response.
+
+## Import
+
+```JavaScript
+// ESModule Syntax (preferred)
+import { getUserRoles } from "@bcgov/citz-imb-sso-css-api";
+
+// CommonJS Syntax
+const { getUserRoles } = require('@bcgov/citz-imb-sso-css-api');
+```
+
+## Usage
+
+A basic example of using the `getUserRoles` function.
+
+```JavaScript
+import { getUserRoles } from "@bcgov/citz-imb-sso-css-api";
+
+(async () => {
+  console.log(await getUserRoles('fohe4m5pn8clhkxmlho33sn1r7vr7m67@idir'));
+})();
+```
+
+## TypeScript Type
+
+```TypeScript
+(username: string) => Promise<RolesArrayResponse>;
+```
+
+### Response Type
+
+The type `RolesArrayResponse` of `Promise<RolesArrayResponse>`:
+
+```TypeScript
+{
+    data: RoleResponse[];
+}
+```
+
+The type `RoleResponse`:
+
+```TypeScript
+{
+    name: string;
+    composite: boolean;
+}
+```
+
+## Parameters
+
+An API reference for the parameters of the `getUserRoles` function.
+
+!!! note "Note"
+    The Name column starting with `*` means the parameter is required.
+
+<table>
+  <!-- Table columns -->
+  <thead>
+    <tr>
+      <th style="background: #6f19d9; color: white;">Name</th>
+      <th style="background: #6f19d9; color: white;">Type</th>
+      <th style="background: #6f19d9; color: white;">Default</th>
+      <th style="background: #6f19d9; color: white;">Description</th>
+    </tr>
+  </thead>
+
+  <!-- Table rows -->
+  <tbody>
+    <tr>
+      <td>* username</td>
+      <td>string</td>
+      <td>-</td>
+      <td>The preferred_username value of the user.</td>
+    </tr>
+  </tbody>
+</table>

techdocs/docs/using-the-package/apis-&-components/role-mapping/get-users-with-role.md

@@ -0,0 +1,98 @@
+# getUsersWithRole
+
+The `getUsersWithRole` function is used to find users with a specific role in your integration from Common Hosted Single Sign-on service. 
+
+!!! warning "Reminder"
+    This function is asynchronous and must be awaited in order to get a response.
+
+## Import
+
+```JavaScript
+// ESModule Syntax (preferred)
+import { getUsersWithRole } from "@bcgov/citz-imb-sso-css-api";
+
+// CommonJS Syntax
+const { getUsersWithRole } = require('@bcgov/citz-imb-sso-css-api');
+```
+
+## Usage
+
+A basic example of using the `getUsersWithRole` function.
+
+```JavaScript
+import { getUsersWithRole } from "@bcgov/citz-imb-sso-css-api";
+
+(async () => {
+  console.log(await getUsersWithRole('Admin'));
+})();
+```
+
+## TypeScript Type
+
+```TypeScript
+(roleName: string, page?: number, maxCount?: number) => Promise<GetUsersWithRoleResponse>;
+```
+
+### Response Type
+
+The type `GetUsersWithRoleResponse` of `Promise<GetUsersWithRoleResponse>`:
+
+```TypeScript
+{
+    page?: number;
+    data: UserResponse[];
+}
+```
+
+The type `UserResponse`:
+
+```TypeScript
+{
+    username: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    attributes: unknown;
+}
+```
+
+## Parameters
+
+An API reference for the parameters of the `getUsersWithRole` function.
+
+!!! note "Note"
+    The Name column starting with `*` means the parameter is required.
+
+<table>
+  <!-- Table columns -->
+  <thead>
+    <tr>
+      <th style="background: #6f19d9; color: white;">Name</th>
+      <th style="background: #6f19d9; color: white;">Type</th>
+      <th style="background: #6f19d9; color: white;">Default</th>
+      <th style="background: #6f19d9; color: white;">Description</th>
+    </tr>
+  </thead>
+
+  <!-- Table rows -->
+  <tbody>
+    <tr>
+      <td>* roleName</td>
+      <td>string</td>
+      <td>-</td>
+      <td>The role name to query.</td>
+    </tr>
+    <tr>
+      <td>page</td>
+      <td>number</td>
+      <td>1</td>
+      <td>The page of data to query.</td>
+    </tr>
+    <tr>
+      <td>maxCount</td>
+      <td>number</td>
+      <td>50</td>
+      <td>The max count of items per page.</td>
+    </tr>
+  </tbody>
+</table>