@i4mi/js-on-fhir
Version:
A JavaScript wrapper for the I4MI FHIR library.
260 lines (259 loc) • 12.7 kB
TypeScript
import { HttpMethod, Resource, Bundle } from '@i4mi/fhir_r4';
/**
* A response to successful oauth request
* ACCORDING http://www.hl7.org/fhir/smart-app-launch/index.html
*/
export interface AuthResponse {
state: string;
access_token: string;
token_type: 'Bearer';
expires_in: number;
scope: string;
id_token?: string;
patient: string;
refresh_token: string;
}
export declare enum FHIR_VERSION {
'STU3' = "3.0.2",
'R4' = "4.0.1",
'R4B' = "4.3.0",
'R5' = "5.0.0"
}
export declare class JSOnFhir {
private iife;
private apiMethods;
private storageKey;
/**
* Creates a new JSOnFhir object and persists it in the sessionStorage so that is
* still available after a page reload.
* @param serverUrl The URL of the fhir server, e.g. 'https://test.midata.coop'.
* @param clientId The ID of your fhir application as registered with the fhir server.
* @param redirectUrl The URL where the callback of the OAuth 2.0 can be directed.
* @param options? Optional parameter. Options object literal.
* @param options.doesNotNeedAuth? Optional parameter. Set to true when the FHIR server you're
* using doesn't require authentication (e.g. when connecting to
* the EPD playground via MobileAccessGateway). In this case, the
* parameters clientId and redirectUrl do not matter (but still
* have to be set.)
* @param options.disablePkce? Optional parameter. Set to true if you want to use the OAuth 2.0
* authorization code flow instead of the recommended and more secure PKCE flow
* or the server does not support PKCE.
* @param options.fhirVersion? Set FHIR version to use. Support of versions can be limited on the server used.
* Defaults to R4 / 4.0.1.
* Possibilities: STU3 (3.0.2), R4 (4.0.1), R4B (4.3.0), R5 (5.0.0)
*/
constructor(serverUrl: string, clientId: string, redirectUrl: string, options?: {
doesNotNeedAuth?: boolean;
disablePkce?: boolean;
fhirVersion?: FHIR_VERSION;
});
/**
* This function starts the OAuth 2.0 authentication procedure, by opening the auth
* page for the client to enter his login credentials. Default OAuth 2.0 PKCE grant type is used.
* @param params? Optional parameter. An object with key/value pairs.
* Can be used to control the login process or may be used
* to pre-fill the login or registration form.
* @returns nothing
* @throws An Error if the conformance statement could not be fetched from the server.
*/
authenticate(params?: {
[key: string]: string;
}): void;
/**
* This function handles the authorization response from the auth server according
* to rfc6749 section 4.1.2 after the authenticate() function was called. This function must be
* called from the same page that the redirectUrl (as defined in the constructor) refers to.
* This function then makes an authorization request to the token endpoint as described in
* rfc6749 section 4.1.3.
* @returns A promise when called after authenticate():
* - fulfilled: Response of token endpoint.
* - rejected: An error message.
*/
handleAuthResponse(): Promise<AuthResponse | null>;
/**
* Given the prerequisite that the local state and server response state are the same
* and therefore no cross-site request forgery attack is being performed, this function
* makes a request to the token endpoint as described in rfc6749 section 4.1.3, or if PKCE isn't disabled
* as described in rfc7636 section 4.5.
* The token endpoints response is then handled by the handleTokenResponse() function.
* @param state An opaque value used by the client to maintain state between the request and callback.
* @param authCode The authorization code received from the authorization server.
* @returns A promise:
* - fulfilled: Response of the token endpoint.
* - rejected: Error message.
*/
private tokenRequest;
/**
* Refreshes an access token, given that the client is in possession of a refresh token
* issued by the authorization server. The token endpoint's response is then handled by
* the handleTokenResponse() function.
* @returns A promise:
* - fulfilled: Response from token endpoint or empty promise if server doesn't require authentication.
* - rejected: Error message.
*/
refreshAuth(refreshToken: string): Promise<any>;
/**
* Checks whether an access token is set and has not yet expired.
* @returns boolean:
* - true: Access token is valid.
* - false: Access token is invalid. Will also return
* false when doesNotNeedAuth? was set true in the constructor.
*/
isLoggedIn(): boolean;
/**
* Logs out the user by deleting certain settings and permission properties.
*/
logout(): void;
/**
* Helper function to get a ApiConfig object consisting of the access token, authorization type and the base URL.
* @returns ApiConfig object.
*/
private getApiConfig;
/**
* Creates a resource on the fhir server.
* @param resource Resource to be saved.
* @returns A promise:
* - fulfilled: Representation of fhir resource in JSON format.
* - rejected: Error message.
*/
create(resource: Resource | string): Promise<Resource>;
/**
* Updates a resource on the fhir server.
* @param resource Resource to be updated.
* @returns A promise:
* - fulfilled: Representation of fhir resource in JSON format.
* - rejected: Error message.
*/
update(resource: Resource): Promise<Resource>;
/**
* Searches for resources matching the given criteria in params.
* @param resourceType ResourceType to be searched.
* @param params? Optional parameter. Search parameters according to fhir resource guide.
* @returns A promise:
* - fulfilled: Bundle of type searchset containing the fhir resource(s).
* - rejected: Error message.
*/
search(resourceType: string, params?: {
[key: string]: string;
}): Promise<Bundle>;
/**
* Fetches a given known resource.
* @param resourceType ResourceType of the resource.
* @param id The unique id of the resource.
* @returns A promise:
* - fulfilled: Bundle of type searchset containing the fhir resource(s).
* - rejected: Error message.
*/
getResource(resourceType: string, id: string): Promise<Resource>;
/**
* Performs a given operation on the fhir server.
* @param operation The type of the operation (e.g 'process-message').
* @param payload? Optional Parameter. A resource or other payload to process in the operation.
* @param httpMethod Optional Parameter. The HTTP method to be used (GET|POST|PUT|DELETE). Default is HTTP method (POST).
* @param params? Optional Parameter. Parameters, either as key/value pair or as a string.
* @param resourceType? Optional Parameter. Specify the resource type on which the operation is to be performed (mandatory if resourceId is used).
* @param resourceId? Optional Parameter. Specify an instance of a resource for which the operation is to be performed.
* @returns A promise:
* - fulfilled: Response of the fhir server.
* - rejected: Error message.
*/
performOperation(operation: string, payload?: Resource | string, httpMethod?: HttpMethod, params?: {
[key: string]: string;
}, resourceType?: string, resourceId?: string): Promise<Resource>;
/**
* Sets the language for the authorization request window.
* @param lang The language as two-char string (eg. 'de', 'en', 'fr' or 'it').
*/
setLanguage(lang: string): void;
/**
* Sets the conformance URL, if it differs from the default (serverURL + '/fhir/metadata').
* @param conformanceUrl The new conformance statement URL.
*/
setConformanceUrl(conformanceUrl: string): void;
/**
* Sets the scope when it differs from the default 'user/*.*'.
* @param scope The scope as string.
*/
setScope(scope: string): void;
/**
* Returns the resource id of the Patient or Practitioner resource of the logged in user
* @return the Patient Resource ID as a string, if logged in
* @return undefined if not logged in
* @deprecated use getUserId() instead
*/
getPatient(): string;
/**
* Returns the resource id of the of the logged in user. With this id, you can then fetch the
* Patient (for normal user) or Practitioner (for health professionals or researcher).
* @return the Patient Resource ID as a string, if logged in
* undefined if not logged in
*/
getUserId(): string;
/**
* Creates an opaque value used by the client to maintain state
* between the request and callback. Is used for preventing
* cross-site request forgery according to rfc 6749 section 4.1.1.
* @returns state (url-safe) with a length of 128 characters.
*/
generateState(): string;
/**
* Generates a code verifier according to rfc7636 section 4.1.
* The code verifier is a high-entropy cryptographic URL safe random string
* using the unreserved characters from rfc3986 section 2.3,
* with a minimum length of 43 characters and a maximum length of 128 characters.
* @returns code verifier (url-safe) with a length of 128 characters.
*/
private generateCodeVerifier;
/**
* Creates a code challenge derived from the code verifier according to rfc 7636 section 4.2.
* The code transformation used on the code verifier is SHA256. The result is then Base64 encoded.
* @param codeVerifier high-entropy cryptographic URL safe random string using the unreserved characters from rfc3986 section 2.3.
* @returns code challenge (hashed and Base64 encoded code verifier).
*/
private generateCodeChallenge;
/**
* Fetches the auth and token URL as well as the supported fhir version from the conformance statement endpoint (default=/fhir/metadata).
* Also fetches the fhir version supported by the server.
* @returns A promise:
* - fulfilled: Response of the conformance statement request.
* - rejected: Error message.
*/
private fetchConformanceStatement;
/**
* Getter Function that returns the current access token, if available.
* @returns access Token
*/
getAccessToken(): string;
/**
* Changes the FHIR version used to do the requests to the server.
* Note that the available versions may be restricted on your server.
* @param version The FHIR version to use. Support of versions can be restricted on the server used.
* Supported versions: STU3 (3.0.2), R4 (4.0.1), R4B (4.3.0), R5 (5.0.0)
*/
changeFhirVersion(version: FHIR_VERSION): void;
/**
* Handles the response of the conformance statement request by saving the relevant data.
* @param response Response of the conformance Request.
*/
private handleConformanceStatementResponse;
/**
* Handles the token endpoint response by saving the relevant data from the access token request.
* @param response Response of the access token request.
*/
private handleTokenResponse;
/**
* Helper function for creating a storage key that is unique for a server / client combination.
*/
private createStorageKey;
/**
* Helper function that saves the JSOnFhir object to sessionStorage. It is used to restore
* the JSOnFhir object after a page reload (e.g. after the authenticate() function was called).
*/
private persist;
private getFromStorage;
/**
* Helper function to handle errors (e.g. expired access token).
* @param error Error object.
*/
private handleError;
}