Manage Organization Invitations (#1424)

* feat(organization): add Invitations method to OrganizationAPI

- Implemented the Invitations method in the OrganizationAPI interface to list invitations for an organization.
- Generated corresponding mock methods in organization_mock.go for testing.
- This change enhances the API's functionality by allowing retrieval of organization invitations, aligning with the management API documentation.

* feat(invitations): add commands to list organization invitations

- Introduced `invitationsOrganizationCmd` to handle invitations management.
- Added `listInvitationsOrganizationCmd` for listing organization invitations with options for pagination and output formats.
- Implemented `getOrgInvitationsWithSpinner` and `getOrgInvitations` methods for fetching invitations from the API.
- Created `invitationsView` struct for displaying invitation details in a structured format.

* feat(invitations): add documentation for managing organization invitations

- Introduced a new section for managing invitations within organizations.
- Added a new file `auth0_orgs_invitations.md` detailing the invitation management commands.
- Created `auth0_orgs_invitations_list.md` to document the command for listing invitations.
- Updated existing documentation files to include links to the new invitations section.

This change enhances the usability of the Auth0 CLI by providing clear guidance on managing organization invitations.

* feat(organization): add CreateInvitation method to OrganizationAPI

- Implemented CreateInvitation method in OrganizationAPI interface to facilitate creating invitations for organizations.
- Added corresponding mock methods in organization_mock.go for testing purposes.
- This change enhances the API's functionality, allowing users to manage organization invitations more effectively.

* feat(invitations): implement create invitation command and update docs

- Added `create` command to manage organization invitations, allowing users to create new invitations.
- Introduced flags for inviter name, invitee email, client ID, connection ID, TTL seconds, and metadata.
- Updated `auth0_orgs_invitations.md` to include the new command.
- Created detailed documentation in `auth0_orgs_invitations_create.md` for usage and examples.
- Enhanced `auth0_orgs_invitations_list.md` to reference the new create command.
- Updated `invitations.go` to reflect changes in field names for consistency.

* feat(invitations): add delete invitation command and related functionality

- Implemented the DeleteInvitation method in the OrganizationAPI interface to allow deletion of invitations.
- Added DeleteInvitation mock methods in organization_mock.go for testing purposes.
- Created a new delete command in organizations.go to handle invitation deletions, including interactive and non-interactive modes.
- Introduced invitationPickerOptions method to facilitate selection of invitations for deletion.
- Added unit tests for invitationPickerOptions to ensure correct behavior under various scenarios.

* fix(arguments): ensure if user can be prompted before fetching picker options

- Fixed PickMany to validate if the command can prompt for required arguments.
- This prevents making redundant GET api calls to list picker options.
- Removed the unused selectArgument function to streamline the code.

* feat(invitations): add show invitation command and related functionality

- Implemented the `show` command for displaying organization invitations.
- Added `Invitation` method to the `OrganizationAPI` interface in `organization.go`.
- Created mock methods in `organization_mock.go` for testing the new functionality.
- Updated `invitations.go` to include a new renderer method for showing invitations.

* feat(invitations): add aliase invs for invitations commands

- Introduced aliases for the invitations commands to enhance usability:
- Updated examples in the command documentation to reflect the new aliases.
- This change aims to streamline command usage and improve user experience.

* feat(invitations): add integration tests for organization invitations

- Implemented new test cases for listing, creating, showing, and deleting organization invitations.
- Added tests to verify behavior with valid and invalid inputs, including edge cases for missing arguments and invalid IDs.
- Created a new script `get-org-invitation-id.sh` to facilitate the retrieval of invitation IDs for testing.
- Updated existing `get-app-id.sh` script to ensure compatibility with the organization-invitation functionality.

* feat(invitations): add required scopes for organization invitations

- Added new required scopes for managing organization invitations:
  - `read:organization_invitations`
  - `create:organization_invitations`
  - `delete:organization_invitations`

This change is necessary to ensure that the application has the appropriate permissions
to handle organization invitations effectively.

* feat(tests): Use generic extra scopes for testing instead of organization_invitations

- Replaced the previous organization invitation scopes with generic extra scopes for better test coverage.

* chore(invitations): increase retry count for organization invitation tests

* feat(tests): add cleanup script for app identifier after deletion

- Introduced a new script `delete-app-id.sh` to remove the app identifier file created during integration tests.
- This script ensures that the identifier file is deleted only if the app is successfully removed, preventing stale data in subsequent test runs.
- Updated the test case for app deletion to call this cleanup script after the app is deleted.

* chore(invitations): remove TODO comment regarding additional fields in invitationsView

* chore(invitations): remove the short form for the `--client-id` flag in the command

- Updated example commands in the documentation to reflect the removal of the short form.
- Ensured consistency in the command usage by using the long form for `--client-id`.

* fix(invitations): update invitation retrieval method in organizationPickerOptions

- Changed the method of fetching organization invitations from a local function to a direct API call.
- Updated the variable names for clarity, changing `invitations` to `orgInvitations` and `value` to `id`.

* fix(invitations): update metadata handling in invitation creation

- Changed AppMetadata and UserMetadata from map[string]string to string to accept JSON formatted input.
- Updated help text for flags to clarify expected data format.
- Adjusted JSON unmarshalling logic in createInvitationOrganizationCmd to handle new string format.
- Ensured compatibility with existing functionality while improving data handling for user and app metadata.

* fix(invitations): enhance documentation for organization invitations

- Updated the long descriptions for commands related to organization invitations to provide clearer guidance on usage.
- Added interactive and non-interactive usage instructions for the following commands:
  - `auth0 orgs invs create`
  - `auth0 orgs invs list`
  - `auth0 orgs invs show`
- Improved user understanding of how to manage invitations effectively.

* chore(invitations): improve organization invitation commands

- Changed the variable name from `ID` to `OrgID` for clarity in `listInvitationsOrganizationCmd`.
- Removed the `getOrgInvitationsWithSpinner` function as it was redundant.
- Added sorting flag to invitation list API req.

* fix(invitations): update invitation list has next logic

- Enhanced the logic in `getOrgInvitations` to determine if there are more
  invitations based on whether the current page is empty, using a new helper
  function `isEmptyInvitationList`.

* feat(invitations): enhance organization invitation commands to read org and inv id as flags

- Added new flags for Organization ID and Invitation ID to improve command usability.
- Updated command arguments to use flags instead of positional arguments for better clarity.
- Revised command descriptions and examples to reflect the new flag usage.
- Ensured that the commands now support interactive and non-interactive modes consistently.

* chore(invitations): add an example to disable email sending for invitations

* fix(invitations): remove CreatedAt field from invitations view

- Removed the CreatedAt field from the invitationsView struct and its related methods.
- Updated AsTableHeader, AsTableRow, and KeyValues methods to reflect this change.
- This simplifies the invitation display by focusing on relevant fields, improving clarity for users.

* feat(invitations): add unit tests for invitationsView methods

- Implemented unit tests for the invitationsView struct to ensure proper functionality.
- Added tests for AsTableHeader, AsTableRow, KeyValues, Object, and makeInvitationsView methods.
- These tests validate the expected output for various invitation attributes, enhancing code reliability and maintainability.

* chore(invitations): replace auth0.String with pointer function for invitation fields

* feat(arguments, flags, input): introduced `PickMany` and `PickManyU` methods in the `Flag` struct to handle multiple flag selections.

- Updated `askMultiSelect` to accept an `isUpdate` parameter for better control over input validation.
- Modified `PickMany` in the `Argument` struct to support the new multi-select behavior.

* refactor(invitations): update invs delete to accept org and inv ids as flag.

- Enhanced the delete command to accept multiple invitation IDs in flag for deletion.
- Improved command examples for clarity on usage.

* refactor(invitations): update test commands to use org-id on invitation-id flags

- Updated test cases for listing, creating, showing, and deleting organization invitations to reflect this change.

* refactor(invitations): update error messages and command flags

- Changed error messages for missing Org ID and Invitation ID to be more descriptive.
- Updated the command for creating an invitation to explicitly include the `--org-id` flag for clarity.
- Adjusted the command for listing invitations to use the `--org-id` flag instead of positional arguments.

* refactor(invitations): reorder Connection ID in invitations display

- Updated the invitationsView struct to move ConnectionID to the end of the fields.
- Adjusted the AsTableHeader, AsTableRow, and KeyValues methods to reflect the new order.
- This change improves the consistency of the output format when displaying invitation details.

* refactor(tests): update organization invitation tests and remove unused script

- Refactored organization invitation test cases for clarity and consistency.
- Removed the `delete-app-id.sh` script as it was no longer needed.
- Introduced `get-org-inv-app-id.sh` to handle organization invitation app ID creation and management.
- Ensured that the new script enables organization support for the created app.

* refactor(flags, input): simplify flag multi-selection methods

- Removed the isUpdate parameter from PickMany and pickManyFlag methods to streamline the flag selection process.
- Updated askMultiSelect to directly use prompt.AskMultiSelect

* refactor(scripts): update app_id retrieval in get-org-invitation-id.sh

- Changed the app_id retrieval in get-org-invitation-id.sh to use
  get-org-inv-app-id.sh instead of get-app-id.sh.
- This change ensures that the correct application ID is used for
  organization invitations, improving the accuracy of the integration
  tests.

Author: bkiran6398

docs/auth0_orgs.md

@@ -11,6 +11,7 @@ The Auth0 Organizations feature best supports business-to-business (B2B) impleme
 
 - [auth0 orgs create](auth0_orgs_create.md) - Create a new organization
 - [auth0 orgs delete](auth0_orgs_delete.md) - Delete an organization
+- [auth0 orgs invitations](auth0_orgs_invitations.md) - Manage invitations of an organization
 - [auth0 orgs list](auth0_orgs_list.md) - List your organizations
 - [auth0 orgs members](auth0_orgs_members.md) - Manage members of an organization
 - [auth0 orgs open](auth0_orgs_open.md) - Open the settings page of an organization

docs/auth0_orgs_create.md

@@ -55,6 +55,7 @@ auth0 orgs create [flags]
 
 - [auth0 orgs create](auth0_orgs_create.md) - Create a new organization
 - [auth0 orgs delete](auth0_orgs_delete.md) - Delete an organization
+- [auth0 orgs invitations](auth0_orgs_invitations.md) - Manage invitations of an organization
 - [auth0 orgs list](auth0_orgs_list.md) - List your organizations
 - [auth0 orgs members](auth0_orgs_members.md) - Manage members of an organization
 - [auth0 orgs open](auth0_orgs_open.md) - Open the settings page of an organization

docs/auth0_orgs_delete.md

@@ -49,6 +49,7 @@ auth0 orgs delete [flags]
 
 - [auth0 orgs create](auth0_orgs_create.md) - Create a new organization
 - [auth0 orgs delete](auth0_orgs_delete.md) - Delete an organization
+- [auth0 orgs invitations](auth0_orgs_invitations.md) - Manage invitations of an organization
 - [auth0 orgs list](auth0_orgs_list.md) - List your organizations
 - [auth0 orgs members](auth0_orgs_members.md) - Manage members of an organization
 - [auth0 orgs open](auth0_orgs_open.md) - Open the settings page of an organization

docs/auth0_orgs_invitations.md

@@ -0,0 +1,16 @@
+---
+layout: default
+has_toc: false
+has_children: true
+---
+# auth0 orgs invitations
+
+Manage invitations of an organization. Invitations enable adding users to an organization by sending an email containing the join link. To learn more, read [Invite Members to Organizations](https://auth0.com/docs/manage-users/organizations/configure-organizations/invite-members).
+
+## Commands
+
+- [auth0 orgs invitations create](auth0_orgs_invitations_create.md) - Create a new invitation to an organization
+- [auth0 orgs invitations delete](auth0_orgs_invitations_delete.md) - Delete invitation(s) from an organization
+- [auth0 orgs invitations list](auth0_orgs_invitations_list.md) - List invitations of an organization
+- [auth0 orgs invitations show](auth0_orgs_invitations_show.md) - Show an organization invitation
+

docs/auth0_orgs_invitations_create.md

@@ -0,0 +1,66 @@
+---
+layout: default
+parent: auth0 orgs invitations
+has_toc: false
+---
+# auth0 orgs invitations create
+
+Create a new invitation to an organization with required and optional parameters.
+
+To create interactively, use `auth0 orgs invs create` with no flags and answer the prompts.
+
+To create non-interactively, supply the organization id and the other parameters through flags.
+
+## Usage
+```
+auth0 orgs invitations create [flags]
+```
+
+## Examples
+
+```
+  auth0 orgs invs create
+  auth0 orgs invs create --org-id <org-id>
+  auth0 orgs invs create --org-id <org-id> --inviter-name "Inviter Name" --invitee-email "invitee@example.com"
+  auth0 orgs invs create --org-id <org-id> --invitee-email "invitee@example.com" --client-id "client_id"
+  auth0 orgs invs create --org-id <org-id> -n "Inviter Name" -e "invitee@example.com" --client-id "client_id" --connection-id "connection_id" -t 86400
+  auth0 orgs invs create --org-id <org-id> --json --send-email=false --inviter-name "Inviter Name"
+```
+
+
+## Flags
+
+```
+  -a, --app-metadata string    Data related to the user that affects the application's core functionality, formatted as JSON
+      --client-id string       Auth0 client ID. Used to resolve the application's login initiation endpoint.
+      --connection-id string   The id of the connection to force invitee to authenticate with.
+  -e, --invitee-email string   Email address of the person being invited.
+  -n, --inviter-name string    Name of the person sending the invitation.
+      --json                   Output in json format.
+      --json-compact           Output in compact json format.
+      --org-id string          ID of the organization.
+  -r, --roles strings          Roles IDs to associate with the user.
+  -s, --send-email             Whether to send the invitation email to the invitee. (default true)
+  -t, --ttl-sec int            Number of seconds for which the invitation is valid before expiration.
+  -u, --user-metadata string   Data related to the user that does not affect the application's core functionality, formatted as JSON
+```
+
+
+## Inherited Flags
+
+```
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 orgs invitations create](auth0_orgs_invitations_create.md) - Create a new invitation to an organization
+- [auth0 orgs invitations delete](auth0_orgs_invitations_delete.md) - Delete invitation(s) from an organization
+- [auth0 orgs invitations list](auth0_orgs_invitations_list.md) - List invitations of an organization
+- [auth0 orgs invitations show](auth0_orgs_invitations_show.md) - Show an organization invitation
+
+

docs/auth0_orgs_invitations_delete.md

@@ -0,0 +1,56 @@
+---
+layout: default
+parent: auth0 orgs invitations
+has_toc: false
+---
+# auth0 orgs invitations delete
+
+Delete invitation(s) from an organization.
+
+To delete interactively, use `auth0 orgs invs delete` with no flags.
+
+To delete non-interactively, supply the organization id, invitation id(s) and the `--force` flag to skip confirmation.
+
+## Usage
+```
+auth0 orgs invitations delete [flags]
+```
+
+## Examples
+
+```
+  auth0 orgs invs delete
+  auth0 orgs invs rm
+  auth0 orgs invs delete --org-id <org-id> --invitation-id <invitation-id>
+  auth0 orgs invs delete --org-id <org-id> --invitation-id <inv-id1>,<inv-id2>,<inv-id3>
+  auth0 orgs invs delete --org-id <org-id> --invitation-id <invitation-id> --force
+```
+
+
+## Flags
+
+```
+      --force                   Skip confirmation.
+  -i, --invitation-id strings   ID of the invitation.
+      --org-id string           ID of the organization.
+```
+
+
+## Inherited Flags
+
+```
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 orgs invitations create](auth0_orgs_invitations_create.md) - Create a new invitation to an organization
+- [auth0 orgs invitations delete](auth0_orgs_invitations_delete.md) - Delete invitation(s) from an organization
+- [auth0 orgs invitations list](auth0_orgs_invitations_list.md) - List invitations of an organization
+- [auth0 orgs invitations show](auth0_orgs_invitations_show.md) - Show an organization invitation
+
+

docs/auth0_orgs_invitations_list.md

@@ -0,0 +1,59 @@
+---
+layout: default
+parent: auth0 orgs invitations
+has_toc: false
+---
+# auth0 orgs invitations list
+
+List the invitations of an organization.
+
+To list interactively, use `auth0 orgs invs list` with no flags.
+
+To list non-interactively, supply the organization id through the flags.
+
+## Usage
+```
+auth0 orgs invitations list [flags]
+```
+
+## Examples
+
+```
+  auth0 orgs invs list
+  auth0 orgs invs ls --org-id <org-id>
+  auth0 orgs invs list --org-id <org-id> --number 100
+  auth0 orgs invs ls --org-id <org-id> -n 50 --json
+  auth0 orgs invs ls --org-id <org-id> -n 500 --json-compact
+  auth0 orgs invs ls --org-id <org-id> --csv
+```
+
+
+## Flags
+
+```
+      --csv             Output in csv format.
+      --json            Output in json format.
+      --json-compact    Output in compact json format.
+  -n, --number int      Number of organization invitations to retrieve. Minimum 1, maximum 1000. (default 100)
+      --org-id string   ID of the organization.
+```
+
+
+## Inherited Flags
+
+```
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 orgs invitations create](auth0_orgs_invitations_create.md) - Create a new invitation to an organization
+- [auth0 orgs invitations delete](auth0_orgs_invitations_delete.md) - Delete invitation(s) from an organization
+- [auth0 orgs invitations list](auth0_orgs_invitations_list.md) - List invitations of an organization
+- [auth0 orgs invitations show](auth0_orgs_invitations_show.md) - Show an organization invitation
+
+

docs/auth0_orgs_invitations_show.md

@@ -0,0 +1,57 @@
+---
+layout: default
+parent: auth0 orgs invitations
+has_toc: false
+---
+# auth0 orgs invitations show
+
+Display information about an organization invitation.
+
+To show interactively, use `auth0 orgs invs show` with no flags.
+
+To show non-interactively, supply the organization id and invitation id through the flags.
+
+## Usage
+```
+auth0 orgs invitations show [flags]
+```
+
+## Examples
+
+```
+  auth0 orgs invs show
+  auth0 orgs invs show --org-id <org-id>
+  auth0 orgs invs show --org-id <org-id> --invitation-id <invitation-id>
+  auth0 orgs invs show --org-id <org-id> --invitation-id <invitation-id> --json
+  auth0 orgs invs show --org-id <org-id> --i <invitation-id> --json-compact
+```
+
+
+## Flags
+
+```
+  -i, --invitation-id string   ID of the invitation.
+      --json                   Output in json format.
+      --json-compact           Output in compact json format.
+      --org-id string          ID of the organization.
+```
+
+
+## Inherited Flags
+
+```
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 orgs invitations create](auth0_orgs_invitations_create.md) - Create a new invitation to an organization
+- [auth0 orgs invitations delete](auth0_orgs_invitations_delete.md) - Delete invitation(s) from an organization
+- [auth0 orgs invitations list](auth0_orgs_invitations_list.md) - List invitations of an organization
+- [auth0 orgs invitations show](auth0_orgs_invitations_show.md) - Show an organization invitation
+
+

docs/auth0_orgs_list.md

@@ -48,6 +48,7 @@ auth0 orgs list [flags]
 
 - [auth0 orgs create](auth0_orgs_create.md) - Create a new organization
 - [auth0 orgs delete](auth0_orgs_delete.md) - Delete an organization
+- [auth0 orgs invitations](auth0_orgs_invitations.md) - Manage invitations of an organization
 - [auth0 orgs list](auth0_orgs_list.md) - List your organizations
 - [auth0 orgs members](auth0_orgs_members.md) - Manage members of an organization
 - [auth0 orgs open](auth0_orgs_open.md) - Open the settings page of an organization

docs/auth0_orgs_open.md

@@ -36,6 +36,7 @@ auth0 orgs open [flags]
 
 - [auth0 orgs create](auth0_orgs_create.md) - Create a new organization
 - [auth0 orgs delete](auth0_orgs_delete.md) - Delete an organization
+- [auth0 orgs invitations](auth0_orgs_invitations.md) - Manage invitations of an organization
 - [auth0 orgs list](auth0_orgs_list.md) - List your organizations
 - [auth0 orgs members](auth0_orgs_members.md) - Manage members of an organization
 - [auth0 orgs open](auth0_orgs_open.md) - Open the settings page of an organization