@eway-crm/connector 1.0.264 → 1.0.266

package/README.md

@@ -1,72 +1,72 @@
-![eWay-CRM Logo](https://www.eway-crm.com/wp-content/themes/eway/img/logo_new-new.svg)
-# eWay-CRM API
-API used for communication with [eWay-CRM](http://www.eway-crm.com/) web service. This library is a wrapper over HTTP/S communication and sessions. See our [documentation](https://kb.eway-crm.com/documentation/6-add-ins/6-7-api-1) for more information.
-
-## Installation
-The simpliest way to start using this library is to get the  [NPM Package](https://www.npmjs.com/package/@eway-crm/connector). To do that, just run this command in your NodeJS project's root dir:
-
-```
-npm i @eway-crm/connector
-```
-
-To get the best dev experience, we also recommend using [TypeScript](https://www.typescriptlang.org/) since this library contains the types headers.
-
-## Usage
-
-This library wraps the communication with JSON API. For HTTP requests, it uses [Axios](https://github.com/axios/axios). To provide the most variability, it lets you input JSON data and fetch JSON data in the same structure as the server uses. The only thing you don't have to care about is the `sessionId`.
-
-The actual usage is then the same as it would be for example with  [PHP](https://github.com/rstefko/eway-crm-php-lib). See the  [documentation](https://kb.eway-crm.com/documentation/6-add-ins/6-7-api-1)  for more.
-
-## Version Compatibility
-
-This library is compatible with **eWay-CRM 6.0.1 and higher**. If you have got a lower version of your eWay-CRM, check the Updates section in the eWay-CRM Administration Application. If there is no update available, contact your eWay-CRM account manager or via other channel listed on our [web page](https://www.eway-crm.com/contact/).
-
-## Establishing Connection
-
-To communicate with eWay-CRM web service, we first have to establish connection. This must be done prior to every action we want to accomplish with use of the web service. To do that, we have to  create new instance of ```ApiConnection``` with seven parameters:
-1. Service url address (same as the one you use in Outlook)
-2. Username
-3. Password hash (md5 of the user's UTF8 password or hash created by the tool from eWay-CRM server component)
-4. App version identifier (name and version of the connecting client app - must consist of alphabet string and digits at the end)
-5. Client machine identifier (unique identifier of the connecting machine - MAC address for instance)
-6. Client machine name (human readable client machine - PC name for instance)
-7. Error handling callback (this callback is called everytime an unexpected error occurs)
-
-```JS
-import ApiConnection from '@eway-crm/connector';
-
-const serviceUrl = 'https://free.eway-crm.com/31994';
-const username = 'api';
-const passwordHash = '470AE7216203E23E1983EF1851E72947';
-
-const connection = ApiConnection.create(serviceUrl, username, passwordHash, 'JSSample1', '00:00:00:00:00', 'SampleTestMachine', (err) => console.error(err));
-```
-
-⚠️ The code above does not support [Microsoft Account Authenticaion](https://kb.eway-crm.com/documentation/2-installation/2-3-installation-the-server-part/adjust-eway-crm-web-service-for-azure-login-office-365?set_language=en). If you log into eWay-CRM with your Microsoft account, you need to implement your own OAuth2 client.
-
-## CORS
-
-If you are developing a web app running on a different host than your eWay-CRM web service, you need to configure your eWay-CRM web service to allow cross-origin requests. To achieve that, put the following setting into `appSettings` section of your web service's web.config file.
-
-```XML
-<add key="AccessControlAllowOrigin" value="https://YOUR-ORIGIN:PORT" />
-```
-
-⚠ If you add the setting above to your web.config, the web-based eWay-CRM Administration Center won't work in Internet Explorer, which will be a huge loss for the whole humankind.
-
-## Using the Connection Object
-
-Once having the `ApiConnection` instance, the API requests look like this searching of our user record.
-
-```JS
-connection.callMethod(
-    'SearchUsers',
-    {
-        transmitObject: { Username: username },
-    },
-    (result) => {
-        console.log('My user detail follows:');
-        console.log(result.Data[0]);
-    }
-);
-```
+![eWay-CRM Logo](https://www.eway-crm.com/wp-content/themes/eway/img/logo_new-new.svg)
+# eWay-CRM API
+API used for communication with [eWay-CRM](http://www.eway-crm.com/) web service. This library is a wrapper over HTTP/S communication and sessions. See our [documentation](https://kb.eway-crm.com/documentation/6-add-ins/6-7-api-1) for more information.
+
+## Installation
+The simpliest way to start using this library is to get the  [NPM Package](https://www.npmjs.com/package/@eway-crm/connector). To do that, just run this command in your NodeJS project's root dir:
+
+```
+npm i @eway-crm/connector
+```
+
+To get the best dev experience, we also recommend using [TypeScript](https://www.typescriptlang.org/) since this library contains the types headers.
+
+## Usage
+
+This library wraps the communication with JSON API. For HTTP requests, it uses [Axios](https://github.com/axios/axios). To provide the most variability, it lets you input JSON data and fetch JSON data in the same structure as the server uses. The only thing you don't have to care about is the `sessionId`.
+
+The actual usage is then the same as it would be for example with  [PHP](https://github.com/rstefko/eway-crm-php-lib). See the  [documentation](https://kb.eway-crm.com/documentation/6-add-ins/6-7-api-1)  for more.
+
+## Version Compatibility
+
+This library is compatible with **eWay-CRM 6.0.1 and higher**. If you have got a lower version of your eWay-CRM, check the Updates section in the eWay-CRM Administration Application. If there is no update available, contact your eWay-CRM account manager or via other channel listed on our [web page](https://www.eway-crm.com/contact/).
+
+## Establishing Connection
+
+To communicate with eWay-CRM web service, we first have to establish connection. This must be done prior to every action we want to accomplish with use of the web service. To do that, we have to  create new instance of ```ApiConnection``` with seven parameters:
+1. Service url address (same as the one you use in Outlook)
+2. Username
+3. Password hash (md5 of the user's UTF8 password or hash created by the tool from eWay-CRM server component)
+4. App version identifier (name and version of the connecting client app - must consist of alphabet string and digits at the end)
+5. Client machine identifier (unique identifier of the connecting machine - MAC address for instance)
+6. Client machine name (human readable client machine - PC name for instance)
+7. Error handling callback (this callback is called everytime an unexpected error occurs)
+
+```JS
+import ApiConnection from '@eway-crm/connector';
+
+const serviceUrl = 'https://free.eway-crm.com/31994';
+const username = 'api';
+const passwordHash = '470AE7216203E23E1983EF1851E72947';
+
+const connection = ApiConnection.create(serviceUrl, username, passwordHash, 'JSSample1', '00:00:00:00:00', 'SampleTestMachine', (err) => console.error(err));
+```
+
+⚠️ The code above does not support [Microsoft Account Authenticaion](https://kb.eway-crm.com/documentation/2-installation/2-3-installation-the-server-part/adjust-eway-crm-web-service-for-azure-login-office-365?set_language=en). If you log into eWay-CRM with your Microsoft account, you need to implement your own OAuth2 client.
+
+## CORS
+
+If you are developing a web app running on a different host than your eWay-CRM web service, you need to configure your eWay-CRM web service to allow cross-origin requests. To achieve that, put the following setting into `appSettings` section of your web service's web.config file.
+
+```XML
+<add key="AccessControlAllowOrigin" value="https://YOUR-ORIGIN:PORT" />
+```
+
+⚠ If you add the setting above to your web.config, the web-based eWay-CRM Administration Center won't work in Internet Explorer, which will be a huge loss for the whole humankind.
+
+## Using the Connection Object
+
+Once having the `ApiConnection` instance, the API requests look like this searching of our user record.
+
+```JS
+connection.callMethod(
+    'SearchUsers',
+    {
+        transmitObject: { Username: username },
+    },
+    (result) => {
+        console.log('My user detail follows:');
+        console.log(result.Data[0]);
+    }
+);
+```

package/lib/cjs/ApiConnection.d.ts

@@ -11,18 +11,31 @@ export interface ISessionHandler {
     getSessionId(connection: ApiConnection, callback: (sessionId: string, loginResponse?: IApiLoginResponse) => void): void;
     lastSuccessfulLoginResponse?: IApiLoginResponse;
 }
+/** Why a call failed - a result the eWay-API refused on the app level, or any other error. */
+export type TCallFailure = TUnionError | IApiResult;
+/**
+ * Notified of every failed ask or call method, so a consumer can react to failures of the connection as a whole.
+ * Left out: rcBadSession (recovered and repeated) and the token endpoint, which OAuthHelper posts on its own.
+ */
+export type TCallFailedCallback = (failure: TCallFailure, methodName: string) => void;
 export declare class ApiConnection {
     private readonly svcUri;
     private readonly baseUri;
     readonly sessionHandler: ISessionHandler;
     private readonly errorCallback;
     private readonly supportGetItemPreviewMethod;
+    private readonly callFailedCallback;
     private sessionId;
-    constructor(apiServiceUri: string, sessionHandler: ISessionHandler, errorCallback?: (error: TUnionError, data?: TInputData | null) => void, supportGetItemPreviewMethod?: boolean);
+    constructor(apiServiceUri: string, sessionHandler: ISessionHandler, errorCallback?: (error: TUnionError, data?: TInputData | null) => void, supportGetItemPreviewMethod?: boolean, callFailedCallback?: TCallFailedCallback);
     get supportsGetItemPreviewMethod(): boolean;
     static create(apiServiceUri: string, username: string, passwordHash: string, appVersion: string, clientMachineIdentifier: string, clientMachineName: string, errorCallback?: (error: TUnionError) => void, supportGetItemPreviewMethod?: boolean): ApiConnection;
     static createAnonymous(apiServiceUri: string, errorCallback?: (error: TUnionError) => void): ApiConnection;
-    static createUsingOAuth(apiServiceUri: string, username: string, clientId: string, clientSecret: string, refreshToken: string, accessToken: string, appVersion: string, errorCallback?: (error: TUnionError) => void, refreshTokenCallback?: (tokenData: ITokenData) => void, supportGetItemPreviewMethod?: boolean): ApiConnection;
+    static createUsingOAuth(apiServiceUri: string, username: string, clientId: string, clientSecret: string, refreshToken: string, accessToken: string, appVersion: string, errorCallback?: (error: TUnionError) => void, refreshTokenCallback?: (tokenData: ITokenData) => void, supportGetItemPreviewMethod?: boolean, callFailedCallback?: TCallFailedCallback): ApiConnection;
+    /**
+     * True when the failure means the web service has moved to another url. App level failures spell the code
+     * `ReturnCode`, errors spell it `returnCode`, so both are checked here instead of in every consumer.
+     */
+    static isWebServiceMovedFailure(failure: unknown): boolean;
     static normalizeWsUrl(wsUrl: string | null): string | null;
     static isCloudUrl(wsUrl: string, allowDev: boolean): boolean;
     static getRootDomain(hostname: string): string;
@@ -32,6 +45,10 @@ export declare class ApiConnection {
      */
     readonly ensureLogin: () => Promise<void>;
     readonly createOpenLink: (isDevEnvironment: boolean, folderName: TFolderName, guid?: string, fileAs?: string) => string;
+    /** Builds the rejection handler shared by the ask* methods. */
+    private readonly createAskRejectionHandler;
+    /** Announces a failed call. The callback only observes, so what it throws must not replace the failure itself. */
+    private readonly notifyCallFailed;
     /**
      * Creates a promise for async file upload using binary stream
      * @param file Single file to be uploaded.
@@ -99,5 +116,9 @@ export declare class ApiConnection {
     readonly getXsltTransformationDefinitionMethodUrl: (transformationGuid: string) => string;
     readonly getActiveSessionId: () => string | null;
     readonly setActiveSessionId: (sessionId: string | null) => void;
-    private static handleCallPromise;
+    /**
+     * The single place every call of this connection ends in, ask* and call* alike, so callFailedCallback is
+     * announced from here to cover them all.
+     */
+    private readonly handleCallPromise;
 }

package/lib/cjs/ReturnCodes.d.ts

@@ -7,4 +7,7 @@ export declare class ReturnCodes {
     static readonly rcLoginUserNameChanged = "rcLoginUserNameChanged";
     static readonly rcLicenseExpired = "rcLicenseExpired";
     static readonly rcBadAccessToken = "rcBadAccessToken";
+    static readonly rcExchangeWebServicesAccountAuthorizationRequired = "rcExchangeWebServicesAccountAuthorizationRequired";
+    static readonly rcGraphAuthorizationRequired = "rcGraphAuthorizationRequired";
+    static readonly rcConsentRequired = "rcConsentRequired";
 }

package/lib/cjs/constants/GlobalSettingsNames.d.ts

@@ -49,6 +49,7 @@ declare class GlobalSettingsNames {
     static readonly notifyAboutPaidInvoiceInPohodaGroup = "NotifyAboutPaidInvoiceInPohodaGroup";
     static readonly notifyAboutProjectDeadline = "NotifyAboutProjectDeadline";
     static readonly numberOfDecimalPlaces = "NumberOfDecimalPlaces";
+    static readonly openFileByDefault = "OpenFileByDefault";
     static readonly phoneListTaskSolverGroup = "PhoneListTaskSolverGroup";
     static readonly projectDeadlineAlert = "ProjectDeadlineAlert";
     static readonly serverUpdateProgressNotificationGroup = "ServerUpdateProgressNotificationGroup";

package/lib/cjs/constants/GroupNames.d.ts

@@ -0,0 +1,7 @@
+declare class GroupNames {
+    static readonly administrator = "Administrator";
+    static readonly everyone = "Everyone";
+    static readonly system = "System";
+    static readonly systemHealthNotification = "SystemHealthNotification";
+}
+export default GroupNames;

package/lib/cjs/index.d.ts

@@ -1,4 +1,4 @@
-import { ApiConnection, ISessionHandler } from './ApiConnection';
+import { ApiConnection, ISessionHandler, TCallFailedCallback, TCallFailure } from './ApiConnection';
 import { HttpMethod } from './HttpMethod';
 import { ReturnCodes } from './ReturnCodes';
 import { ITokenizedApiResult } from './tokenizedServices/ITokenizedApiResult';
@@ -6,6 +6,7 @@ import { TokenizedServiceConnection } from './tokenizedServices/TokenizedService
 import { CommonDataConnection } from './tokenizedServices/CommonDataConnection';
 import { ApiMethods } from './ApiMethods';
 import GlobalSettingsNames from './constants/GlobalSettingsNames';
+import GroupNames from './constants/GroupNames';
 import FieldNames from './constants/FieldNames';
 import { FolderNames, TFolderName } from './constants/FolderNames';
 import { OAuthHelper } from './helpers/OAuthHelper';
@@ -113,4 +114,4 @@ export * from './data/query/IApiQueryFilters';
 export * from './constants/ImportResult';
 export * from './interfaces/ITranslatableString';
 export * from './interfaces/ITokenData';
-export { OpenItemLinkHelper, ImportResult, SentimentTone, HttpMethod, ISessionHandler, ReturnCodes, ITokenizedApiResult, TokenizedServiceConnection, CommonDataConnection, ApiMethods, GlobalSettingsNames, FolderNames, TFolderName, OAuthHelper, HttpRequestError, TUnionError, TInputData, FieldNames, EnumTypes, RelationTypes, RelationTypeIds, TRelationType, ColumnPermissionPermissionRules, ColumnPermissionMandatoryRules, Edition, Feature, Functionality, CustomizationStatsItemKeys, LicenseRestrictionKeys, ExpirationReason, LicenseKeyInvoiceSeverity, ErrorHelper, VersionHelperBase, OAuthSessionHandlerBase, OAuthSessionHandler, FieldTypes, TFieldType, TNumericValidatorType, IApiEvent, IApiSetFieldValueAction, ObjectTypeIds, IApiHubItemsCountsQueryResponseItem, QueryHelper, QuerySources, IApiServiceAuthSettingsResponse, ApiConnection as ApiConnectionAsNonDefaultExport, IApiUnlinkInquiryResult, TApiUnlinkInquiryResultType, VersionHelper, Version, StringHelper, DateHelper, TransformItemFormats, EmailConversionSource, ApiFetchClient };
+export { OpenItemLinkHelper, ImportResult, SentimentTone, HttpMethod, ISessionHandler, TCallFailure, TCallFailedCallback, ReturnCodes, ITokenizedApiResult, TokenizedServiceConnection, CommonDataConnection, ApiMethods, GlobalSettingsNames, GroupNames, FolderNames, TFolderName, OAuthHelper, HttpRequestError, TUnionError, TInputData, FieldNames, EnumTypes, RelationTypes, RelationTypeIds, TRelationType, ColumnPermissionPermissionRules, ColumnPermissionMandatoryRules, Edition, Feature, Functionality, CustomizationStatsItemKeys, LicenseRestrictionKeys, ExpirationReason, LicenseKeyInvoiceSeverity, ErrorHelper, VersionHelperBase, OAuthSessionHandlerBase, OAuthSessionHandler, FieldTypes, TFieldType, TNumericValidatorType, IApiEvent, IApiSetFieldValueAction, ObjectTypeIds, IApiHubItemsCountsQueryResponseItem, QueryHelper, QuerySources, IApiServiceAuthSettingsResponse, ApiConnection as ApiConnectionAsNonDefaultExport, IApiUnlinkInquiryResult, TApiUnlinkInquiryResultType, VersionHelper, Version, StringHelper, DateHelper, TransformItemFormats, EmailConversionSource, ApiFetchClient };