Invitations.ts

/*---------------------------------------------------------------------------------------------
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/

import type { Links } from "./links";
import type { Role } from "./Role";

/**
 * Represents an invitation sent to a user to join an iTwin as a member.
 *
 * @remarks
 * Member invitations are created when external users (not in the same organization as the iTwin)
 * are invited to join an iTwin. The invited user receives an email invitation and must accept it
 * to become a member. Invitations have expiration dates and can be in various states.
 *
 * @example
 * ```typescript
 * const invitation: MemberInvitation = {
 *   id: "550e8400-e29b-41d4-a716-446655440000",
 *   email: "external.user@othercompany.com",
 *   invitedByEmail: "admin@mycompany.com",
 *   status: "Pending",
 *   createdDate: "2023-10-15T10:30:00Z",
 *   expirationDate: "2023-11-15T10:30:00Z",
 *   roles: [
 *     { id: "viewer-role", displayName: "Project Viewer", description : "Can view project details" }
 *   ]
 * };
 * ```
 */
export interface MemberInvitation {
  /** Unique identifier for the invitation */
  id: string;
  /** Email address of the invited user */
  email: string;
  /** Email address of the user who sent the invitation */
  invitedByEmail: string;
  /** Current status of the invitation */
  status: MemberInvitationStatus;
  /** ISO 8601 timestamp when the invitation was created */
  createdDate: string;
  /** ISO 8601 timestamp when the invitation expires */
  expirationDate: string;
  /** Optional array of roles that will be assigned upon acceptance (excludes permissions) */
  roles?: Role[];
  /** Given name of the user that sent the invitation.*/
  inviterGivenName: string;
  /** Surname of the user that sent the invitation.*/
  inviterSurname: string;
  /** Organization of the user that sent the invitation.*/
  inviterOrganization: string;
  /** Display name of the project associated with the invitation.*/
  projectDisplayName: string;
}

/**
 * Represents the current state of a member invitation.
 *
 * @remarks
 * Invitations start as "Pending" when first sent and transition to "Accepted"
 * when the invited user accepts the invitation.
 */
export type MemberInvitationStatus = "Pending" | "Accepted";

/**
 * API response wrapper for multiple member invitations with pagination support.
 *
 * @remarks
 * This interface is used for API responses that return collections of member invitations,
 * such as GET /invitations operations. Includes HAL-style navigation links for pagination
 * to handle large numbers of invitations efficiently.
 *
 * @example
 * ```typescript
 * const response: MultipleMemberInvitationResponse = {
 *   invitations: [
 *     { id: "inv1", email: "user1@external.com", status: "Pending", ... },
 *     { id: "inv2", email: "user2@external.com", status: "Accepted", ... }
 *   ],
 *   _links: {
 *     self: { href: "/members/invitations?$skip=0&$top=100" },
 *     next: { href: "/members/invitations?$skip=100&$top=100" },
 *     prev: { href: "/members/invitations?$skip=0&$top=100" }
 *   }
 * };
 * ```
 */
export interface MultipleMemberInvitationResponse {
  /** Array of member invitations in the current page */
  invitations: MemberInvitation[];
  /** HAL-style navigation links for pagination (first, next, prev, last) */
  // eslint-disable-next-line @typescript-eslint/naming-convention
  _links: Links;
}

/**
 * API response wrapper for a member invitation.
 *
 * @remarks
 * This interface is used for API responses that a single member invitation,
 * such as GET /invitations operations.
 *
 * @example
 * ```typescript
 * const response: MultipleMemberInvitationResponse = {
 *   invitation: {{ id: "inv1", email: "user1@external.com", status: "Pending", ... }} ,
 * };
 * ```
 */
export interface SingleMemberInvitationResponse {
  /** The member invitation */
  invitation: MemberInvitation;
}

/**
 * Represents an invitation sent to a group member to join an iTwin.
 *
 * @remarks
 * Retrieves a list of iTwin group member invitations. By default, users will receive the invitations they have sent.
 * If the user is an iTwin Owner, they will receive all invitations for the iTwin.
 * Invitations have an expiration of 7 days after their creation. Once that expiration passes, the invitation will not be returned.
 *
 * @example
 * ```typescript
 * const groupInvitation: GroupMemberInvitation = {
 *   id: "550e8400-e29b-41d4-a716-446655440000",
 *   email: "group.member@external.com",
 *   invitedByEmail: "admin@mycompany.com",
 *   status: "Pending",
 *   createdDate: "2023-10-15T10:30:00Z",
 *   expirationDate: "2023-11-15T10:30:00Z"
 * };
 * ```
 */
export type GroupMemberInvitation = Omit<MemberInvitation, "roles">;

/**
 * API response wrapper for multiple group member invitations with pagination support.
 *
 * @remarks
 * This interface is used for API responses that return collections of group member invitations.
 * Includes HAL-style navigation links for pagination to handle large numbers of group invitations efficiently.
 *
 * @example
 * ```typescript
 * const response: MultipleGroupMemberInvitationResponse = {
 *   invitations: [
 *     { id: "inv1", email: "user1@external.com", status: "Pending", ... },
 *     { id: "inv2", email: "user2@external.com", status: "Accepted", ... }
 *   ],
 *   _links: {
 *     self: { href: "/groups/invitations?$skip=0&$top=100" },
 *     next: { href: "/groups/invitations?$skip=100&$top=100" },
 *     prev: { href: "/groups/invitations?$skip=0&$top=100" }
 *   }
 * };
 * ```
 */
export interface MultipleGroupMemberInvitationResponse {
  /** Array of group member invitations in the current page */
  invitations: GroupMemberInvitation[];
  /** HAL-style navigation links for pagination (first, next, prev, last) */
  // eslint-disable-next-line @typescript-eslint/naming-convention
  _links: Links;
}