@medrunner/api-client 0.3.6 → 0.3.8

package/dist/index.d.mts

@@ -16,9 +16,21 @@ interface DbItem {
 }
 
 interface ApiToken extends DbItem {
+    /**
+     * The user who created the token
+     * */
     userId: string;
+    /**
+     * Human-readable name for the token, assigned by the user
+     * */
     name: string;
+    /**
+     * The timestamp at which the token will expire in Unix seconds
+     * */
     expirationDate?: number;
+    /**
+     *  When the token was last used to generate a new access token, iso-8601 timestamp
+     * */
     lastUsed?: string;
 }
 
@@ -36,10 +48,28 @@ interface TokenGrant {
     refreshTokenExpiration?: string;
 }
 
+/**
+ * Configuration for the Medrunner API.
+ * */
 interface ApiConfig {
+    /**
+     * The base URL of the API - defaults to https://api.medrunner.space
+     * */
     baseUrl?: string;
+    /**
+     * Your API token retrieved after logging in. If none is provided, the refresh token will be used to retrieve an
+     * access token.
+     * */
     accessToken?: string;
+    /**
+     * Your refresh token, used to obtain new API tokens. If none is provided, authenticated requests will not be possible
+     * when the {@link accessToken} expires. If no access token is provided either, only unauthenticated requests are
+     * possible.
+     * */
     refreshToken?: string;
+    /**
+     * Use cookie base auth instead of tokens - defaults to false
+     * */
     cookieAuth?: boolean;
 }
 
@@ -88,48 +118,156 @@ declare abstract class ApiEndpoint {
     private makeRequest;
 }
 
+/**
+ * Request body for creating an api token.
+ * */
 interface CreateApiTokenRequest {
+    /**
+     * Human-readable name for the token
+     * */
     name: string;
+    /**
+     * Optional expiration date for the token
+     * */
     expirationDate?: Date;
 }
 
+/**
+ * Request body for sign-out.
+ * */
 interface SignOutRequest {
+    /**
+     * The refresh token to be invalidated
+     * */
     refreshToken: string;
 }
 
+/**
+ * Endpoints for interacting with auth.
+ * */
 declare class AuthEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Invalidate a refresh token.
+     *
+     * @param oldToken - Token to be invalidated
+     *
+     * */
     signOut(oldToken?: SignOutRequest): Promise<ApiResponse>;
+    /**
+     * Gets all api tokens for the user.
+     *
+     * */
     getApiTokens(): Promise<ApiResponse<ApiToken[]>>;
+    /**
+     * Creates an api token.
+     *
+     * @param newToken - Emergency details for the new emergency
+     * @returns The newly-created api token
+     *
+     * */
     createApiToken(newToken: CreateApiTokenRequest): Promise<ApiResponse<string>>;
+    /**
+     * Delete an api token.
+     *
+     * @param id - The id of the api token to delete
+     *
+     * */
     deleteApiToken(id: string): Promise<ApiResponse>;
 }
 
 interface ChatMessage extends DbItem {
+    /**
+     * The emergency associated with the chat message
+     * */
     emergencyId: string;
+    /**
+     * The user id of the message sender
+     * */
     senderId: string;
+    /**
+     * The timestamp at which the message was sent in Unix seconds
+     * */
     messageSentTimestamp: number;
+    /**
+     * The contents of the message
+     * */
     contents: string;
+    /**
+     * Whether the message has been edited
+     * */
     edited: boolean;
 }
 
+/**
+ * Response data which is paginated and includes the data and a token to get the next page.
+ * */
 interface PaginatedResponse<T = unknown> {
+    /**
+     * The page of data returned by the request
+     * */
     data: T[];
+    /**
+     * The pagination token to get the next page of data in a subsequent request
+     * */
     paginationToken?: string;
 }
 
+/**
+ * Request body for creating a new chat message.
+ * */
 interface ChatMessageRequest {
+    /**
+     * The id of the emergency associated with the message
+     * */
     emergencyId: string;
+    /**
+     * The message contents
+     * */
     contents: string;
 }
 
+/**
+ * Endpoints for interacting with chat messages.
+ * */
 declare class ChatMessageEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Gets the specified amount of chat messages for a given emergency.
+     *
+     * @deprecated Use {@link getMessageHistory} instead
+     *
+     * @param emergencyId - The emergency for which to fetch the chat history
+     * @param limit - The number of emergencies to get
+     * @param paginationToken - The number to use for pagination
+     * */
     getHistory(emergencyId: string, limit: number, paginationToken?: string): Promise<ApiResponse<PaginatedResponse<ChatMessage>>>;
+    /**
+     * Gets the specified amount of chat messages for a given emergency.
+     *
+     * @param emergencyId - The emergency for which to fetch the chat history
+     * @param limit - The number of emergencies to get
+     * @param paginationToken - The number to use for pagination
+     * */
     getMessageHistory(emergencyId: string, limit: number, paginationToken?: string): Promise<ApiResponse<PaginatedResponse<ChatMessage>>>;
+    /**
+     * Sends a new chat message
+     *
+     * @param message - The message to send
+     * @returns The newly-created chat message
+     *
+     * */
     sendMessage(message: ChatMessageRequest): Promise<ApiResponse<ChatMessage>>;
+    /**
+     * Update a chat message
+     *
+     * @param id - The id of the message to update
+     * @param contents - The new content of the message
+     * @returns The updated chat message
+     *
+     * */
     updateMessage(id: string, contents: string): Promise<ApiResponse<ChatMessage>>;
 }
 
@@ -162,6 +300,9 @@ interface Person extends WritableDbItem {
     deactivationReason: AccountDeactivationReason;
     clientStats: ClientStats;
     activeEmergency?: string;
+    /**
+     * @deprecated Use {@link Person.clientPortalPreferencesBlob} instead.
+     */
     clientPortalPreferences: Record<string, unknown>;
     clientPortalPreferencesBlob?: string;
     redeemedCodes: RedeemedCode[];
@@ -200,21 +341,67 @@ declare enum CodeType {
     CitizenCon2954 = 1
 }
 
+/**
+ * Endpoints for interacting with clients.
+ * */
 declare class ClientEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Gets the current client.
+     * */
     get(): Promise<ApiResponse<Person>>;
+    /**
+     * Gets the specified amount of emergencies the client has created.
+     * @param limit - The number of emergencies to get
+     * @param paginationToken - The number to use for pagination
+     * */
     getHistory(limit: number, paginationToken?: string): Promise<ApiResponse<PaginatedResponse<ClientHistory>>>;
+    /**
+     * Gets the blocklist status of the current client.
+     * */
     getBlockedStatus(): Promise<ApiResponse<BlockedStatus>>;
-    linkClient(rsiHandle: string): Promise<ApiResponse>;
+    /**
+     * Links the current user to a rsiHandle.
+     *
+     * @param rsiHandle - The RSI handle of the client
+     * @returns The updated Person object of the client
+     *
+     * */
+    linkClient(rsiHandle: string): Promise<ApiResponse<Person>>;
+    /**
+     * Updates the settings of the current user for the Client Portal.
+     *
+     * @deprecated Use {@link setUserSettings} instead
+     * @param settings - The stringfied new object settings that will replace the old one
+     * @returns The updated settings object
+     *
+     * */
     setSettings(settings: Record<string, unknown>): Promise<ApiResponse<Record<string, unknown>>>;
+    /**
+     * Updates the settings of the current user for the Client Portal.
+     *
+     * @param settings - The object settings to add or update
+     *
+     * */
     setUserSettings(settings: string): Promise<ApiResponse>;
+    /**
+     * Deactivate the current client.
+     * */
     deactivate(): Promise<ApiResponse>;
 }
 
+/**
+ * Endpoints for interacting with promotional codes.
+ * */
 declare class CodeEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Redeems the specified promotional code for the current user
+     *
+     * @param code - The code to redeem.
+     * */
     redeem(code: string): Promise<ApiResponse>;
 }
 
@@ -297,6 +484,9 @@ interface Emergency extends WritableDbItem {
     clientMessage?: MessageCache;
     coordinationThread?: MessageCache;
     afterActionReportMessage?: MessageCache;
+    /**
+     * @deprecated Will be removed in a future update.
+     */
     interactionMessageId?: string;
     respondingTeam: Team;
     respondingTeams: RespondingTeam[];
@@ -363,27 +553,87 @@ interface RespondingTeam {
     teamName: string;
 }
 
+/**
+ * Request body for creating a new emergency.
+ * */
 interface CreateEmergencyRequest {
+    /**
+     * Additional details or remarks to include
+     * */
     remarks?: string;
+    /**
+     * The location of the emergency
+     * */
     location: Location;
+    /**
+     * The threat level of the emergency
+     *
+     * @remarks
+     * This will be removed in the future.
+     * */
     threatLevel: ThreatLevel;
+    /**
+     * The rsiHandle of the client
+     *
+     * @remarks
+     * This is optional, if the client already has an RSI handle set on his profile, this will be ignored.
+     * */
     rsiHandle?: string;
 }
+/**
+ * Only real matching locations will be accepted (see /emergency/meta/locations).
+ * */
 interface Location {
+    /**
+     * The star system the emergency is located in
+     * */
     system: string;
+    /**
+     * The nearest planetary body to the emergency
+     * */
     subsystem: string;
+    /**
+     * The nearest moon to the emergency, if applicable
+     * */
     tertiaryLocation?: string;
 }
 
+/**
+ * A supported location from which an emergency may be submitted.
+ * */
 interface LocationDetail {
+    /**
+     * The name of this location
+     * */
     name: string;
+    /**
+     * The type of this location
+     * */
     type: LocationType;
+    /**
+     * Additional locations which are within this location (e.g. moons of a planet, or planets of a system)
+     * */
     children: LocationDetail[];
 }
+/**
+ * The type of location.
+ * */
 declare enum LocationType {
+    /**
+     * The location type is not known
+     * */
     UNKNOWN = 0,
+    /**
+     * A system, e.g. Stanton
+     * */
     SYSTEM = 1,
+    /**
+     * A planet, e.g. Crusader
+     * */
     PLANET = 2,
+    /**
+     * A moon, e.g. Daymar
+     * */
     MOON = 3
 }
 
@@ -421,26 +671,98 @@ declare enum Level {
     Tier10Section3 = 1003
 }
 
+/**
+ * Details about a team responding to an alert.
+ * */
 interface TeamDetailsResponse {
+    /**
+     * Details about each individual responder.
+     * */
     stats: ResponderDetails[];
+    /**
+     * The aggregated mission success rate from all responders, appropriately weighted by number of missions.
+     * */
     aggregatedSuccessRate: number;
 }
+/**
+ * Details about an alert responder.
+ * */
 interface ResponderDetails {
+    /**
+     * The responder's id.
+     * */
     id: string;
+    /**
+     * The responder's level.
+     * */
     level: Level;
+    /**
+     * The success rate of all prior missions this staff member has responded to.
+     * */
     missionSuccessRate: number;
+    /**
+     * The success rate of all prior missions this staff member has acted as a dispatcher for.
+     * */
     dispatchSuccessRate: number;
 }
 
+/**
+ * Endpoints for interacting with emergencies.
+ * */
 declare class EmergencyEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Gets an emergency by id.
+     *
+     * @param id - The id of the emergency to retrieve
+     * */
     getEmergency(id: string): Promise<ApiResponse<Emergency>>;
+    /**
+     * Bulk fetches emergencies by id.
+     *
+     * @param ids - a list of emergencies to retrieve
+     * */
     getEmergencies(ids: string[]): Promise<ApiResponse<Emergency[]>>;
+    /**
+     * Creates a new emergency.
+     *
+     * @param newEmergency - Emergency details for the new emergency
+     * @returns The newly-created emergency
+     *
+     * */
     createEmergency(newEmergency: CreateEmergencyRequest): Promise<ApiResponse<Emergency>>;
+    /**
+     * Cancels an existing emergency.
+     *
+     * @remarks
+     * Emergency must still be in the {@link MissionStatus.RECEIVED} state in order to be canceled.
+     *
+     * @param id - The id of the emergency to cancel
+     * @param reason - The reason the emergency was canceled
+     * */
     cancelEmergencyWithReason(id: string, reason: CancellationReason): Promise<ApiResponse>;
+    /**
+     * Allows the client to rate their emergency.
+     *
+     * @param id - The id of the emergency to rate
+     * @param rating - The rating to give the services provided
+     * @param remarks - Additional remarks provided by the client
+     *
+     * @internal
+     * */
     rateServices(id: string, rating: ResponseRating, remarks?: string): Promise<ApiResponse>;
+    /**
+     * Fetches additional details about the responding team for an alert.
+     *
+     * @param id - The id of the emergency to get team details about
+     * */
     teamDetails(id: string): Promise<ApiResponse<TeamDetailsResponse>>;
+    /**
+     * Gets a tree of valid locations from which an emergency may be submitted.
+     *
+     * @deprecated Use {@link getPublicSettings} instead.
+     * */
     emergencyLocations(): Promise<ApiResponse<LocationDetail[]>>;
 }
 
@@ -486,27 +808,56 @@ declare enum ServiceStatus {
     OFFLINE = 4
 }
 
+/**
+ * Endpoints for interacting with the public org settings.
+ * */
 declare class OrgSettingsEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Get the public org settings.
+     *
+     * */
     getPublicSettings(): Promise<ApiResponse<PublicOrgSettings>>;
 }
 
+/**
+ * Information about a medal
+ * */
 interface MedalInformation {
+    /**
+     * The level linked to the medal
+     * */
     level: Level;
+    /**
+     * The number of successful missions required to earn the medal
+     * */
     successfulMissions: number;
 }
 
+/**
+ * Endpoints for interacting with staff.
+ * */
 declare class StaffEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     protected endpoint(): string;
+    /**
+     * Gets detailed information about medals.
+     * */
     medalsInformation(): Promise<ApiResponse<MedalInformation[]>>;
 }
 
+/**
+ * Endpoints for interacting with emergencies.
+ * */
 declare class WebsocketEndpoint extends ApiEndpoint {
     constructor(config: DefaultApiConfig, tokenManager: TokenManager, log?: Logger, headerProvider?: HeaderProvider);
     private websocketManager;
     protected endpoint(): string;
+    /**
+     * Gets realtime updates.
+     *
+     * */
     initialize(): Promise<HubConnection>;
 }
 
@@ -521,6 +872,9 @@ interface ApiClient<TEmergency extends EmergencyEndpoint = EmergencyEndpoint, TC
     websocket: TWebsocket;
 }
 
+/**
+ * An API client for basic client interactions with the Medrunner API.
+ * */
 declare class MedrunnerApiClient<TEmergency extends EmergencyEndpoint = EmergencyEndpoint, TClient extends ClientEndpoint = ClientEndpoint, TStaff extends StaffEndpoint = StaffEndpoint, TOrgSettings extends OrgSettingsEndpoint = OrgSettingsEndpoint, TChatMessage extends ChatMessageEndpoint = ChatMessageEndpoint, TCode extends CodeEndpoint = CodeEndpoint, TAuth extends AuthEndpoint = AuthEndpoint, TWebsocket extends WebsocketEndpoint = WebsocketEndpoint> implements ApiClient<TEmergency, TClient, TStaff, TOrgSettings, TChatMessage, TCode, TAuth, TWebsocket> {
     readonly emergency: TEmergency;
     readonly client: TClient;
@@ -531,6 +885,13 @@ declare class MedrunnerApiClient<TEmergency extends EmergencyEndpoint = Emergenc
     readonly auth: TAuth;
     readonly websocket: TWebsocket;
     protected constructor(emergency: TEmergency, client: TClient, staff: TStaff, orgSettings: TOrgSettings, chatMessage: TChatMessage, code: TCode, auth: TAuth, websocket: TWebsocket);
+    /**
+     * Constructs a new API client.
+     *
+     * @param config - The API configuration
+     * @param refreshCallback - a callback function called whenever a refresh token exchange is performed
+     * @param log - A logger which logs request details
+     * */
     static buildClient(config: ApiConfig, refreshCallback?: AsyncAction<TokenGrant>, log?: Logger): MedrunnerApiClient;
 }