@bitrix24/b24jssdk/dist/cjs/core/actions/v3/call-tail.cjs

Bitrix24 REST API JavaScript SDK

/**
 * @package @bitrix24/b24jssdk
 * @version 2.0.0
 * @copyright (c) 2026 Bitrix24
 * @license MIT
 * @see https://github.com/bitrix24/b24jssdk
 * @see https://bitrix24.github.io/b24jssdk/
 */
'use strict';

const abstractAction = require('../abstract-action.cjs');
const result = require('../../result.cjs');
const sdkError = require('../../sdk-error.cjs');
const _keysetPaginate = require('./_keyset-paginate.cjs');

var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
class CallTailV3 extends abstractAction.AbstractAction {
  static {
    __name(this, "CallTailV3");
  }
  /**
   * Returns every record of a `tail` method as one array.
   *
   * @template T - The type of the elements of the returned array (default is `unknown`).
   *
   * @param {ActionCallTailV3} options - parameters for executing the request.
   *     - `method: string` - A REST API `tail` method name (for example: `main.eventlog.tail`).
   *     - `params?: Omit<TypeCallParams, 'pagination' | 'order' | 'cursor'>` - Request parameters
   *         (`filter`, `select`). `pagination`, `order` and `cursor` are managed by this helper.
   *         The cursor field must NOT be used in `filter`.
   *     - `cursorField?: string` - The DTO field that drives the cursor. Default is `id`.
   *     - `order?: 'ASC' | 'DESC'` - Cursor direction. Default is `ASC`. For `DESC` you MUST pass
   *         `initialValue` (the server pages by `field < value`, so the default `0` returns nothing).
   *     - `customKeyForResult?: string` - The key the response groups rows under. Default is `items`.
   *     - `requestId?: string` - Unique request identifier for tracking.
   *     - `limit?: number` - How many records to retrieve at a time. Default is `50`. Maximum is `1000`.
   *     - `initialValue?: number | string` - Cursor start value for the first page. Default is `0`
   *         (valid for ascending numeric fields); required for `DESC` and for non-numeric fields.
   *
   * @returns {Promise<Result<T[]>>} A promise that resolves to the result of an REST API call.
   *
   * @example
   * const response = await b24.actions.v3.callTail.make<{ id: string }>({
   *   method: 'main.eventlog.tail',
   *   params: { select: ['id', 'auditType'] },
   *   cursorField: 'id',
   *   customKeyForResult: 'items'
   * })
   * if (!response.isSuccess) {
   *   throw new Error(`Problem: ${response.getErrorMessages().join('; ')}`)
   * }
   * console.log(`Result: ${response.getData()?.length}`)
   */
  async make(options) {
    const batchSize = options?.limit ?? 50;
    const result$1 = new result.Result();
    const cursorField = options?.cursorField ?? "id";
    const order = options?.order ?? "ASC";
    const customKeyForResult = options?.customKeyForResult ?? "items";
    const params = options?.params ?? {};
    if (/desc/i.test(order) && options?.initialValue === void 0) {
      throw new sdkError.SdkError({
        code: "JSSDK_CORE_B24_CALL_TAIL_DESC_REQUIRES_INITIAL_VALUE",
        description: 'callTail.make: order "DESC" requires an explicit `initialValue` (the server pages by `field < value`, so the default 0 returns nothing). Pass `initialValue` set to the type maximum / newest value.',
        status: 500
      });
    }
    if (Array.isArray(params["filter"]) && params["filter"].some((c) => Array.isArray(c) && c[0] === cursorField)) {
      this._logger.warning(`callTail.make: the cursor field "${cursorField}" must not appear in \`filter\` \u2014 the server orders and pages by it and will reject a filter on the same field (INVALIDFILTEREXCEPTION). Remove it from \`filter\`.`);
    }
    let select = params["select"];
    if (Array.isArray(select)) {
      if (!select.includes(cursorField)) {
        select = [...select, cursorField];
      }
    } else if (cursorField !== "id") {
      this._logger.warning(`callTail.make: no \`select\` provided with a non-default cursorField "${cursorField}" \u2014 make sure it is in the server's default field set, otherwise pass \`select\` including "${cursorField}" so the cursor can advance.`);
    }
    const { select: _ignoredSelect, ...restParams } = params;
    const allItems = [];
    try {
      for await (const page of _keysetPaginate.keysetPaginate(this._b24, this._logger, {
        method: options.method,
        requestId: options.requestId,
        customKeyForResult,
        initialCursor: options?.initialValue ?? 0,
        // Native keyset: drive the server's `cursor: { field, value, order, limit }`.
        buildParams: /* @__PURE__ */ __name((cursor) => ({
          ...restParams,
          ...select ? { select } : {},
          cursor: { field: cursorField, value: cursor, order, limit: batchSize }
        }), "buildParams"),
        // Advance by the raw cursor-field value from the last item; a missing
        // value (cursorField not selected / wrong name) stops the walk.
        readNextCursor: /* @__PURE__ */ __name((lastItem) => lastItem[cursorField] ?? null, "readNextCursor"),
        noCursorWarning: `callTail.make: pagination stops here \u2014 no value could be read from the returned items via cursorField "${cursorField}". Make sure cursorField matches a field present in the response (and in \`select\`).`,
        errorLabel: "callTailMethod"
      })) {
        for (const item of page) {
          allItems.push(item);
        }
      }
    } catch (error) {
      if (error instanceof _keysetPaginate.KeysetPaginationError) {
        for (const [index, err] of error.errors) {
          result$1.addError(err, index);
        }
      } else {
        throw error;
      }
    }
    return result$1.setData(allItems);
  }
}

exports.CallTailV3 = CallTailV3;
//# sourceMappingURL=call-tail.cjs.map