v2.0.0

Common types

Foundational building blocks used across the SDK — scalar string aliases, field-metadata shapes (Fields, MultiField, UserFieldType), and the DataType enum.
common

The types in types/common.ts are the small, shared vocabulary the rest of the SDK is built on: string aliases that describe how Bitrix24 encodes scalars over REST, the metadata shapes returned by *.fields calls, and the DataType enum. Everything here is re-exported from @bitrix24/b24jssdk.

Scalar aliases

These are plain string (or string-literal) aliases. They carry no runtime behaviour — they document how Bitrix24 encodes a value so call sites read clearly.

type NumberString = string        // a number sent as text, e.g. '20.23'
type ISODate = string             // ISO 8601 datetime, e.g. '2018-06-07T03:00:00+03:00'
type BoolString = 'Y' | 'N'       // Bitrix24's boolean encoding
type GenderString = 'M' | 'F' | ''

type PlacementViewMode = 'view' | 'edit'
type TextType = 'text' | 'html'

import type { NumberString, BoolString, ISODate } from '@bitrix24/b24jssdk'

interface DealRow {
  ID: NumberString      // '42'
  OPENED: BoolString    // 'Y' | 'N'
  DATE_CREATE: ISODate  // '2018-06-07T03:00:00+03:00'
}

Field-metadata shapes

Fields

The shape of a *.fields response — a map of field name to its metadata. Every entry is readonly.

type Fields = {
  readonly [key: string]: {
    readonly type: string
    readonly isRequired: boolean
    readonly isReadOnly: boolean
    readonly isImmutable: boolean
    readonly isMultiple: boolean
    readonly isDynamic: boolean
    readonly title: string
    readonly upperName?: string
  }
}

MultiField / MultiFieldArray

Where you'll encounter it: the multi-value contact fields (phone, email, IM, web, …) returned by CRM entities such as crm.contact.get. Each value carries its own id and value-type qualifier (WORK, HOME, …). MultiFieldArray is the trimmed form used when writing those fields back — only VALUE and VALUE_TYPE are needed.

type MultiField = {
  readonly ID: NumberString
  readonly VALUE_TYPE: string
  readonly VALUE: string
  readonly TYPE_ID: string
}

type MultiFieldArray = ReadonlyArray<
  Pick<MultiField, 'VALUE' | 'VALUE_TYPE'>
>

UserFieldType

Where you'll encounter it: describes the inline settings of a user field (UF) — the USER_TYPE_ID, its handler, and display metadata. Passed when registering or rendering a custom user-field type.

type UserFieldType = {
  USER_TYPE_ID: string
  HANDLER: string
  TITLE: string
  DESCRIPTION: string
  OPTIONS?: {
    height: number
  }
}

DataType enum

Where it's used: the canonical Bitrix24 field data types (see the data-types reference). It maps a field's type string to a stable enum member, so code can branch on DataType.date, DataType.crmStatus, … instead of magic strings.

enum DataType {
  undefined = 'undefined',
  any = 'any',
  integer = 'integer',
  boolean = 'boolean',
  double = 'double',
  date = 'date',
  datetime = 'datetime',
  string = 'string',
  text = 'text',
  file = 'file',
  array = 'array',
  object = 'object',
  user = 'user',
  location = 'location',
  crmCategory = 'crm_category',
  crmStatus = 'crm_status',
  crmCurrency = 'crm_currency'
}

Resolve a raw type string to a member with getEnumValue:

import { getEnumValue, DataType } from '@bitrix24/b24jssdk'

getEnumValue(DataType, 'crm_status') // DataType.crmStatus
getEnumValue(DataType, 'unknown')    // undefined

Related

  • getEnumValue — turn a raw REST string into a typed DataType (or any) enum member.
  • Payload types — the REST response envelope that wraps results built from these scalars.
  • Text — toB24Format produces the ISODate strings the API expects.