B24jssdk Recipes

b24jssdk recipes

Twelve end-to-end programs. Every recipe runs on B24Hook (Node.js), but each function body takes $b24: TypeB24 so the same code works in-frame too — just swap the boot for initializeB24Frame().

All recipes use the canonical $b24.actions.v{2,3}.*.make() surface. The legacy callMethod / callBatch / callListMethod / fetchListMethod was removed in 3.0.0 — do not generate code against it.

Shared library (lib/)

Pure, I/O-free helpers extracted from recipes so they can be unit-tested without a live portal.

lib/ is for helpers where a second hand-written copy is a defect — a security primitive, or logic with edge cases a test pins. It is not for shared plumbing: these are recipes, and every extraction costs a reader the ability to lift one file and run it. When in doubt, leave the code in the recipe.

Worked example of the rule: bootB24() is byte-identical in eleven of the twelve recipes and stays that way on purpose. It has no edge cases to pin and no security weight, and it is the first thing a reader needs to see when they open a recipe — hiding it behind an import would cost more than the duplication does.

Recipes 06 and 12 end with a guard instead of a bare main() call:

import { pathToFileURL } from 'node:url'

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main().catch((e: unknown) => {
    // Raw console.error, so structured-logger formatting cannot hide the trace.
    console.error('\n[recipe failed]', e instanceof Error ? `${e.name}: ${e.message}` : String(e))
    process.exitCode = 1
  })
}

npx tsx 06-telegram-bot.ts still runs exactly as before — the guard is only false when the file is imported, which is what the unit tests do to exercise tick's cursor logic and the uninstall token check without opening a Telegram connection or binding a port. Keep it when copying those two recipes. Before adding it to a third, prefer the lib/ route above: extract the logic and test it there. Reach for the guard only when the function cannot reasonably leave the recipe — tick closes over a live bot and the poll cursor, handleUninstall is an Express handler — because two shapes of recipe is already one more than ideal, and the guard spreading to all twelve would quietly retire the lib/ convention. The exported functions in those files are exported for the same reason, and export is inert when the file runs directly.

One deployment caveat: the guard compares import.meta.url against process.argv[1]. Under an exotic launcher that rewrites either — a wrapper CLI, some loader shims — the comparison can come out false, and the process would exit 0 having started nothing. Check for the recipe's startup log line rather than trusting the exit code.

baseStage(s) strips the multi-funnel category prefix ("C2:WON" → "WON"), falling back to the original string when the part after the colon is empty ("C2:" → "C2:"). Import it from lib/funnel rather than re-declaring it in a recipe: 03 and 06 each carried their own copy that returned "" for that case. No recipe's control flow actually differed — neither "" nor "C2:" matches a stage key — but the copies had drifted from the tested one unnoticed, and the next divergence might not be harmless.
analyseFunnel(deals) groups deals by raw stageId key, summing counts and opportunity amounts.

safeEqual(a, b) is a constant-time compare for secrets and tokens. It had the same two-copy problem as baseStage, in recipes 07 and 12. Never re-declare this one: a constant-time compare that drifts in one of two forks is a vulnerability that reads like a refactor, and === on a token is the bug it exists to prevent.

Boot snippet (shared by all recipes)

import { B24Hook, ConsoleV2Handler, LogLevel, Logger, type TypeB24 } from '@bitrix24/b24jssdk'

export function bootB24(): TypeB24 {
  const url = process.env.B24_HOOK
  if (!url) throw new Error('B24_HOOK env var is required (incoming webhook URL)')
  const $b24 = B24Hook.fromWebhookUrl(url)
  return $b24
}

// Recipes run under Node, so the console handler is created explicitly with
// `useStyles: false` — the browser factory emits ANSI-free CSS styling that a
// terminal prints as literal noise.
export const logger = Logger.create('Recipe')
logger.pushHandler(new ConsoleV2Handler(
  process.env.NODE_ENV === 'production' ? LogLevel.ERROR : LogLevel.INFO,
  { useStyles: false }
))

The snippet is inlined into each recipe file for copy-paste convenience.

API-version split — quick reference

Inside the recipes the split is:

The SDK no longer gates v3 by a hardcoded allowlist: actions.v3.* sends any method to the v3 endpoint and the server validates it (an unknown method returns METHODNOTFOUNDEXCEPTION as a soft error on the AjaxResult, not an SDK throw). The recipes pick a surface per method by what reads cleanest for that data, not by a whitelist.

Field-naming choice

The newer CRM methods (crm.item.list) use camelCase fields: stageId, assignedById, opportunity, createdTime. The classic ones (tasks.task.add, crm.activity.list, crm.timeline.comment.add) use uppercase: TITLE, DESCRIPTION, OWNER_TYPE_ID. Recipes follow this split. Both are restApi:v2 — crm.item.* is camelCase for reasons of its own, not because it is v3; the v3 endpoint publishes no crm.item.*. Under restApi:v3 camelCase is the rule everywhere, and <entity>.field.list answers it per entity — see Discovering entity fields.

Running

# 1. Install: at the repo root or in a fresh project
pnpm add @bitrix24/b24jssdk
# Copying a single recipe out of this repo? Some recipes import a shared
# helper and need it copied alongside, keeping the ../lib/ path:
#   recipes 1, 3, 6:  lib/funnel.ts  (baseStage)
#   recipes 7, 12:    lib/crypto.ts  (safeEqual)
# Every other recipe is standalone.
# Recipe-specific deps as needed:
#   recipe 4: pnpm add node-cron
#   recipe 6: pnpm add grammy node-cron
#   recipe 7: pnpm add express
#   recipe 8: pnpm add openai
#   recipe 9: pnpm add openai
#   recipe 12: pnpm add express
# Recipe 12 also honours B24_OAUTH_STORE — where to write the OAuth token
# store. Defaults to .oauth-store.json in the working directory, which is
# rarely where portal credentials should live on a real server.

# 2. Set env
export B24_HOOK='https://YOUR_PORTAL.bitrix24.com/rest/1/k32t88gf3azpmwv3'

# 3. Run with tsx (no build step)
npx tsx examples/01-crm-analytics.ts

Caveats applied across recipes

• Multi-funnel pipelines: stage IDs may carry a category prefix (C2:WON, C4:LOSE). Recipes 1, 3, and 6 strip the prefix when checking the base stage.
• order in callList.make: silently dropped (the action forces cursorIdKey ASC, defaulting to idKey, for cursor stability). Use filter to narrow.
• customKeyForResult: 'items' for crm.item.list, omit or 'tasks' for classic methods. Wrong value → silent empty array.
• idKey / cursorIdKey: idKey: 'id' for crm.item.list; 'ID' (default) for classic methods. tasks.task.list is the exception on v2 — it returns lowercase id but sorts by ID, so use idKey: 'id', cursorIdKey: 'ID' (and customKeyForResult: 'tasks'); on v3 it is all-lowercase: idKey: 'id' (default), no cursorIdKey, customKeyForResult: 'items'.
• Error handling: failed calls throw AjaxError for REST errors; recipes log and continue where it makes sense. Tune via setRestrictionManagerParams if you need different retry behaviour (see b24jssdk-core).
• Webhook events (recipe 7): registration of the outbound webhooks themselves (which events go where) is a one-off setup. Recipe 11 (11-event-registration.ts) is a small CLI for that: list / bind / unbind via event.get / event.bind / event.unbind.

Cross-reference

For v3 wire-level details (filter grammar, batch $ref/$refArray, cursor pagination), use the b24jssdk-rest and b24jssdk-filtering skills.