@2bad/bitrix 2.4.0 → 2.5.1

package/build/main/services/users/index.integration.test.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const bitrix_1 = __importDefault(require("./../../bitrix"));
+const WEBHOOK_URL = process.env['WEBHOOK_URL'];
+if (!WEBHOOK_URL) {
+    throw Error('Integration tests require environmental variable `WEBHOOK_URL` to be set');
+}
+const { users } = (0, bitrix_1.default)(WEBHOOK_URL);
+describe('Users', () => {
+    describe('fields', () => {
+        it('should get all fields', async () => {
+            const { result } = await users.fields();
+            expect(result).toMatchSnapshot();
+        });
+    });
+    describe('get', () => {
+        it('should get all users', async () => {
+            const { result } = await users.get();
+            expect(result).toMatchSnapshot();
+        });
+        it('should get entry with ID = 1', async () => {
+            const { result } = await users.get('1');
+            expect(result).toMatchSnapshot();
+        });
+        it('should return an error in case non existent ID is requested', async () => {
+            const { result } = await users.get('1001');
+            expect(result).toEqual([]);
+        });
+    });
+});

package/build/main/services/users/index.js

@@ -5,4 +5,3 @@ exports.default = ({ call }) => ({
     fields: () => call(methods_1.Method.USER_FIELDS, {}),
     get: (id) => call(methods_1.Method.USER_GET, { id })
 });
-//# sourceMappingURL=index.js.map

package/build/main/services/users/index.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/main/services/users/index.unit.test.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const _1 = __importDefault(require("."));
+const mockCall = jest.fn(() => Promise.resolve());
+const mockList = jest.fn(() => Promise.resolve());
+const users = (0, _1.default)({ call: mockCall });
+const ID = '77';
+describe('Users', () => {
+    beforeEach(() => {
+        mockCall.mockClear();
+        mockList.mockClear();
+    });
+    it('should expose API methods', () => {
+        expect(users).toMatchSnapshot();
+    });
+    describe('`get`', () => {
+        it('should invoke `call`', async () => {
+            await users.get(ID);
+            expect(mockCall.mock.calls).toMatchSnapshot();
+        });
+    });
+});

package/build/main/services/users/methods.js

@@ -1,4 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const methods_1 = require("../../methods");
-//# sourceMappingURL=methods.js.map

package/build/main/utils/Diff.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=Diff.js.map

package/build/main/utils/ExtractValue.d.ts

@@ -1 +1,6 @@
+/**
+ * Extract value from the `MAP` following the `KEY`
+ * It works with `enum` as a `KEY` when matched against dict as `enum` values as a keys,
+ * which justifies whole existence of that helper.
+ */
 export declare type ExtractValue<MAP extends Record<string, unknown>, KEY extends string | number | symbol, MAPKEY extends keyof MAP = KEY extends keyof MAP ? KEY : never> = MAP[MAPKEY];

package/build/main/utils/ExtractValue.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ExtractValue.js.map

package/build/main/utils/isArray.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// Because `Array.isArray` itself give a strange result with `any[]`
 exports.default = (x) => Array.isArray(x);
-//# sourceMappingURL=isArray.js.map

package/build/module/bitrix.d.ts

@@ -1,5 +1,13 @@
 import { ExtendOptions } from 'got';
-declare const _default: (restURI: string, accessToken?: string | undefined, clientOptions?: ExtendOptions | undefined) => {
+/**
+ * Construct a Bitrix client with generic methods
+ * @param restURI REST endpoint, like a `https://hello.bitrix24.ua/rest` or an inbound webhook endpoint,
+ *                like a `https://hello.bitrix24.ua/rest/1/WEBHOOK_TOKEN`.
+ * @param accessToken Bitrix application Access Token. Do not specify in case inbound webhook endpoint used.
+ * @param clientOptions an object that will overwrite underlying configuration for HTTP client,
+ *                see `https://github.com/sindresorhus/got/blob/main/documentation/2-options.md`.
+ */
+export declare const Bitrix: (restURI: string, accessToken?: string, clientOptions?: ExtendOptions) => {
     call: import("./client/methods/call").Call;
     batch: import("./client/methods/batch").Batch;
     list: import("./client/methods/list").List;
@@ -93,7 +101,7 @@ declare const _default: (restURI: string, accessToken?: string | undefined, clie
         get: (id?: string | undefined) => Promise<import("./payloads").GetPayload<readonly import("./services/users/entities").User[]>>;
     };
 };
-export default _default;
+export default Bitrix;
 export * from './methods';
 export * from './commands';
 export * from './services/common';

package/build/module/bitrix.integration.test.js

@@ -0,0 +1,31 @@
+"use strict";
+describe('Bitrix API', () => {
+    describe('`get` method', () => {
+        it.todo('should get result');
+        it.todo('should reject on error');
+    });
+    describe('`batch` method', () => {
+        it.todo('should execute the batch');
+        it.todo('should reject on errors');
+    });
+    describe('`deals`', () => {
+        describe('`get` method', () => {
+            it.todo('should get entry');
+            it.todo('should reject on error');
+        });
+        describe('`list` method', () => {
+            it.todo('should all entries');
+            it.todo('should reject on error');
+        });
+    });
+    describe('`leads`', () => {
+        describe('`get` method', () => {
+            it.todo('should get entry');
+            it.todo('should reject on error');
+        });
+        describe('`list` method', () => {
+            it.todo('should get all entries');
+            it.todo('should reject on error');
+        });
+    });
+});

package/build/module/bitrix.js

@@ -5,7 +5,15 @@ import DealsService from './services/deals';
 import LeadsService from './services/leads';
 import StatusesService from './services/statuses';
 import UsersService from './services/users';
-export default (restURI, accessToken, clientOptions) => {
+/**
+ * Construct a Bitrix client with generic methods
+ * @param restURI REST endpoint, like a `https://hello.bitrix24.ua/rest` or an inbound webhook endpoint,
+ *                like a `https://hello.bitrix24.ua/rest/1/WEBHOOK_TOKEN`.
+ * @param accessToken Bitrix application Access Token. Do not specify in case inbound webhook endpoint used.
+ * @param clientOptions an object that will overwrite underlying configuration for HTTP client,
+ *                see `https://github.com/sindresorhus/got/blob/main/documentation/2-options.md`.
+ */
+export const Bitrix = (restURI, accessToken, clientOptions) => {
     const { call, batch, list } = Client(restURI, accessToken, clientOptions);
     return {
         call,
@@ -19,6 +27,7 @@ export default (restURI, accessToken, clientOptions) => {
         users: UsersService({ call })
     };
 };
+export default Bitrix;
 export * from './methods';
 export * from './commands';
 export * from './services/common';
@@ -29,4 +38,3 @@ export * from './services/deals/entities';
 export * from './services/leads/entities';
 export * from './services/statuses/entities';
 export * from './services/users/entities';
-//# sourceMappingURL=bitrix.js.map

package/build/module/bitrix.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/module/bitrix.unit.test.js

@@ -0,0 +1,16 @@
+import Bitrix from './bitrix';
+import * as client from './client';
+describe('Bitrix', () => {
+    it('should init', () => {
+        expect(() => Bitrix('https://test.com', 'test_token')).not.toThrow();
+    });
+    it('should pass endpoint and access token to the client', () => {
+        const SpiedClient = jest.spyOn(client, 'default');
+        Bitrix('https://test.com', 'test_token');
+        expect(SpiedClient.mock.calls).toMatchSnapshot();
+    });
+    it('should expose API methods', () => {
+        const bitrix = Bitrix('https://test.com', 'test_token');
+        expect(bitrix).toMatchSnapshot();
+    });
+});

package/build/module/client/client.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/module/client/client.unit.test.js

@@ -0,0 +1,65 @@
+import got from 'got';
+import nock from 'nock';
+import Queue from 'p-queue';
+import { Method } from '../methods';
+import Client from './index';
+const TEST_URI = 'https://test.com/rest';
+const TEST_ACCESS_TOKEN = 'test_access_token';
+const RESPONSE_200 = 200;
+const spiedQueueAdd = jest.spyOn(Queue.prototype, 'add');
+const client = Client(TEST_URI, TEST_ACCESS_TOKEN);
+describe('Client', () => {
+    beforeEach(() => {
+        spiedQueueAdd.mockClear();
+    });
+    it('should init', () => {
+        expect(() => Client(TEST_URI, TEST_ACCESS_TOKEN)).not.toThrow();
+    });
+    it('should extend `Got` instance with a specified parameters', () => {
+        const spiedGotExtend = jest.spyOn(got, 'extend');
+        Client('https://test.com', 'test_token', { https: { rejectUnauthorized: false } });
+        expect(spiedGotExtend.mock.calls).toMatchSnapshot();
+    });
+    it('should expose API methods', () => {
+        expect(client).toMatchSnapshot();
+    });
+    describe('`call`', () => {
+        // @todo restore test when issue is resolved (https://github.com/nock/nock/issues/1832)
+        it.skip('should add to queue', async () => {
+            const payload = {};
+            const method = Method.CRM_DEAL_LIST;
+            nock(TEST_URI)
+                .get(`/${method}?access_token=${TEST_ACCESS_TOKEN}`)
+                .twice()
+                .reply(RESPONSE_200, payload);
+            await client.call(method, {});
+            await client.call(method, {});
+            expect(spiedQueueAdd.mock.calls).toMatchSnapshot();
+        });
+    });
+    describe('`batch`', () => {
+        // @todo restore test when issue is resolved (https://github.com/nock/nock/issues/1832)
+        it.skip('should add to queue', async () => {
+            const payload = {
+                result: {
+                    result: ['done'],
+                    result_error: []
+                }
+            };
+            const commands = [
+                { method: Method.CRM_DEAL_GET },
+                { method: Method.CRM_DEAL_LIST }
+            ];
+            nock(TEST_URI)
+                // @todo We'd want to use `query` object here as it is much more readable, but nock for some reason
+                //       fails to match request when it contains `cmd[someName]`. The issue definitely connected
+                //       to the `[]`, since it does not appear when only one bracket present
+                .get(`/${Method.BATCH}?cmd%5B0%5D=${commands[0].method}&access_token=${TEST_ACCESS_TOKEN}`)
+                .reply(RESPONSE_200, payload)
+                .get(`/${Method.BATCH}?cmd%5B0%5D=${commands[1].method}&access_token=${TEST_ACCESS_TOKEN}`)
+                .reply(RESPONSE_200, payload);
+            await client.batch(commands, 1);
+            expect(spiedQueueAdd.mock.calls).toMatchSnapshot();
+        });
+    });
+});

package/build/module/client/hooks/addAccessToken.d.ts

@@ -1,3 +1,6 @@
 import { BeforeRequestHook } from 'got';
-declare const _default: (accessToken?: string | undefined) => BeforeRequestHook;
+/**
+ * Got can't merge `query` option with other queries if they are string. But that hook can.
+ */
+declare const _default: (accessToken?: string) => BeforeRequestHook;
 export default _default;

package/build/module/client/hooks/addAccessToken.js

@@ -1,3 +1,6 @@
+/**
+ * Got can't merge `query` option with other queries if they are string. But that hook can.
+ */
 export default (accessToken) => (options) => {
     if (!accessToken)
         return;
@@ -6,4 +9,3 @@ export default (accessToken) => (options) => {
     const hasQuery = options.path.includes('?');
     options.path = `${options.path}${hasQuery ? '&' : '?'}access_token=${accessToken}`;
 };
-//# sourceMappingURL=addAccessToken.js.map

package/build/module/client/hooks/addAccessToken.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/module/client/hooks/addAccessToken.unit.test.js

@@ -0,0 +1,26 @@
+import got from 'got';
+import addAccessToken from './addAccessToken';
+const token = 'mock_token';
+const merge = got.mergeOptions;
+describe('Client `addAccessToken` hook', () => {
+    it('should add access token to URL without a query', () => {
+        const options = merge({ path: 'test', responseType: 'json' });
+        addAccessToken(token)(options);
+        expect(options.path).toBe(`test?access_token=${token}`);
+    });
+    it('should add access token to URL with a query', () => {
+        const options = merge({ path: 'test?value=1', responseType: 'json' });
+        addAccessToken(token)(options);
+        expect(options.path).toBe(`test?value=1&access_token=${token}`);
+    });
+    it('should not add access token when it is undefined', () => {
+        const options = merge({ path: 'test', responseType: 'json' });
+        addAccessToken()(options);
+        expect(options.path).toBe('test');
+    });
+    it('should not add access token when URL is undefined', () => {
+        const options = merge({ path: undefined, responseType: 'json' });
+        addAccessToken(token)(options);
+        expect(options.path).toBe(undefined);
+    });
+});

package/build/module/client/index.d.ts

@@ -1,5 +1,13 @@
 import { ExtendOptions } from 'got';
-declare const _default: (restURI: string, accessToken?: string | undefined, options?: ExtendOptions | undefined) => {
+/**
+ * Construct a Bitrix client with generic methods
+ * @param restURI REST endpoint, like a `https://hello.bitrix24.ru/rest` or an inbound webhook endpoint,
+ *                like a `https://hello.bitrix24.ru/rest/1/WEBHOOK_TOKEN`.
+ * @param accessToken Bitrix application Access Token. Do not specify in case inbound webhook endpoint used.
+ * @param options an object that will overwrite underlying configuration for HTTP client,
+ *                see `https://github.com/sindresorhus/got/blob/main/documentation/2-options.md`.
+ */
+declare const _default: (restURI: string, accessToken?: string, options?: ExtendOptions) => {
     call: import("./methods/call").Call;
     batch: import("./methods/batch").Batch;
     list: import("./methods/list").List;

package/build/module/client/index.js

@@ -5,7 +5,15 @@ import Batch from './methods/batch';
 import Call from './methods/call';
 import List from './methods/list';
 const BITRIX_API_RATE_LIMIT = 2;
-const BITRIX_API_RATE_INTERVAL = 1000;
+const BITRIX_API_RATE_INTERVAL = 1000; // 1 second
+/**
+ * Construct a Bitrix client with generic methods
+ * @param restURI REST endpoint, like a `https://hello.bitrix24.ru/rest` or an inbound webhook endpoint,
+ *                like a `https://hello.bitrix24.ru/rest/1/WEBHOOK_TOKEN`.
+ * @param accessToken Bitrix application Access Token. Do not specify in case inbound webhook endpoint used.
+ * @param options an object that will overwrite underlying configuration for HTTP client,
+ *                see `https://github.com/sindresorhus/got/blob/main/documentation/2-options.md`.
+ */
 export default (restURI, accessToken, options) => {
     const client = got.extend({
         prefixUrl: restURI,
@@ -18,14 +26,18 @@ export default (restURI, accessToken, options) => {
                 addAccessToken(accessToken)
             ]
         },
-        ...options !== null && options !== void 0 ? options : {}
+        ...options ?? {}
     });
     const queue = new Queue({
         intervalCap: BITRIX_API_RATE_LIMIT,
         interval: BITRIX_API_RATE_INTERVAL
     });
     const queuedGet = (...args) => queue.add(() => client.get(...args));
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error @todo remove after issue is resolved (https://github.com/sindresorhus/got/issues/954)
     const call = Call({ get: queuedGet });
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error @todo remove after issue is resolved (https://github.com/sindresorhus/got/issues/954)
     const batch = Batch({ get: queuedGet });
     const list = List({ call, batch });
     return {
@@ -34,4 +46,3 @@ export default (restURI, accessToken, options) => {
         list
     };
 };
-//# sourceMappingURL=index.js.map

package/build/module/client/methods/batch.d.ts

@@ -3,8 +3,20 @@ import { Commands } from '../../commands';
 import { Method, MethodPayloadType } from '../../methods';
 import { BatchPayload } from '../../payloads';
 export declare const MAX_COMMANDS_PER_BATCH = 50;
+/**
+ * Split any number of commands into the chunks with max commands per batch in each chunk
+ */
 export declare const chunkCommands: <C extends Commands>(commands: C, size?: number) => readonly C[];
+/**
+ * Prepares list of commands to be used in requests to the Bitrix
+ * @note We could avoid that function... if only Bitrix API would support posting of the batch commands as
+ *       plain objects, like it does with other methods. Instead, it should be a dict or array of string queries
+ */
 export declare const prepareCommandsQueries: <C extends Commands, R = { [K in keyof C]: string; }>(commands: C) => R;
+/**
+ * Merges list of batch responses into a single batch
+ * @todo Generics inference is complicated here and might be not super accurate
+ */
 export declare const mergeBatchPayloads: <B extends BatchPayload<unknown>, P = B extends BatchPayload<infer U> ? U : never>(payloads: readonly B[]) => BatchPayload<P>;
 export declare type CommandsPayloads<C extends Commands, CM = {
     [K in keyof C]: C[K] extends {
@@ -17,5 +29,12 @@ export declare type Batch = <C extends Commands, P = CommandsPayloads<C>>(comman
 declare type Dependencies = {
     readonly get: typeof got.get;
 };
+/**
+ * Dispatches a batch request with specified commands. Will fill figure out payload type based on the Methods.
+ * Supports unlimited number of commands. If they do exceed max amount of commands per batch, will dispatch
+ * multiple request and merge result into single batch payload
+ * @todo For now due to issues with types it won't check `params` of command, so any Method can be used
+ *       with any (even wrong) params
+ */
 declare const _default: ({ get }: Dependencies) => Batch;
 export default _default;

package/build/module/client/methods/batch.js

@@ -5,22 +5,40 @@ import { Method } from '../../methods';
 import isArray from '../../utils/isArray';
 import { handlePayload } from './call';
 export const MAX_COMMANDS_PER_BATCH = 50;
+/**
+ * Split any number of commands into the chunks with max commands per batch in each chunk
+ */
 export const chunkCommands = (commands, size = MAX_COMMANDS_PER_BATCH) => {
     const commandsIsArray = isArray(commands);
     const chunks = chunk(Object.entries(commands), size);
+    // @todo Generated return type isn't very accurate since it says that it will make array of <C>, while
+    //       in fact <C> will be distributed among chunks. That gives wrong hints with named commands and arrays as const.
     return chunks.map((c) => commandsIsArray
+        // @todo Figure out how to avoid unsafe casting to <C> here
+        //       Without `<C>` generic it won't work with complex functions like `batch`
         ? c.map(([_key, command]) => command)
         : fromPairs(c));
 };
+/**
+ * Prepares list of commands to be used in requests to the Bitrix
+ * @note We could avoid that function... if only Bitrix API would support posting of the batch commands as
+ *       plain objects, like it does with other methods. Instead, it should be a dict or array of string queries
+ */
 export const prepareCommandsQueries = (commands) => Object.entries(commands).reduce((calls, [name, { method, params }]) => {
     const stringifiedParams = params ? `?${toQuery(params)}` : '';
     return {
         ...calls,
         [`cmd[${name}]`]: `${method}${stringifiedParams}`
     };
+    // eslint-disable-next-line @typescript-eslint/prefer-reduce-type-parameter
 }, {});
+/**
+ * Merges list of batch responses into a single batch
+ * @todo Generics inference is complicated here and might be not super accurate
+ */
 export const mergeBatchPayloads = (payloads) => {
     const merge = (a, b) => isArray(a) && isArray(b)
+        // @todo Gotta find way to avoid unsafe casting here
         ? [...a, ...b]
         : ({ ...a, ...b });
     return payloads.reduce((merged, payload) => ({
@@ -32,8 +50,16 @@ export const mergeBatchPayloads = (payloads) => {
             result_total: merge(merged.result.result_total || [], payload.result.result_total)
         },
         time: { ...merged.time, ...payload.time }
+        // eslint-disable-next-line @typescript-eslint/prefer-reduce-type-parameter
     }), { result: {}, time: {} });
 };
+/**
+ * Dispatches a batch request with specified commands. Will fill figure out payload type based on the Methods.
+ * Supports unlimited number of commands. If they do exceed max amount of commands per batch, will dispatch
+ * multiple request and merge result into single batch payload
+ * @todo For now due to issues with types it won't check `params` of command, so any Method can be used
+ *       with any (even wrong) params
+ */
 export default ({ get }) => {
     const batch = async (commands, commandsPerRequest = MAX_COMMANDS_PER_BATCH) => {
         const call = (c) => get(Method.BATCH, { searchParams: prepareCommandsQueries(c) })
@@ -48,4 +74,3 @@ export default ({ get }) => {
     };
     return batch;
 };
-//# sourceMappingURL=batch.js.map

package/build/module/client/methods/batch.unit.test.d.ts

@@ -0,0 +1 @@
+export {};