@2bad/bitrix 3.0.0-beta.0 → 3.0.0

package/README.md

@@ -1,213 +1,120 @@
-![@2bad/bitrix](https://user-images.githubusercontent.com/4460311/64487745-c4a1ea00-d246-11e9-9d6e-a0b0227c801c.png)
-
-# Bitrix24 REST API client that doesn't suck
+# @2bad/bitrix
 
 [![NPM version](https://img.shields.io/npm/v/@2bad/bitrix)](https://www.npmjs.com/package/@2bad/bitrix)
 [![License](https://img.shields.io/npm/l/@2bad/bitrix)](https://www.npmjs.com/package/@2bad/bitrix)
 [![Code coverage](https://img.shields.io/codecov/c/github/2BAD/bitrix)](https://codecov.io/gh/2BAD/bitrix)
 [![GitHub Build Status](https://img.shields.io/github/actions/workflow/status/2BAD/bitrix/build.yml)](https://github.com/2BAD/bitrix/actions/workflows/build.yml)
-[![Written in TypeScript](https://img.shields.io/github/languages/top/2BAD/bitrix)](https://github.com/2BAD/bitrix/search?l=typescript)
-
-- 🔥 No bullshit
-- ✨ Expressive API
-- 💪 Strongly typed methods and requests results with TypeScript
-- 🚀 Handles records batching and rate limiting for you
-- ❤️ Promise-based
-
-![@2bad/bitrix usage example](https://user-images.githubusercontent.com/4460311/64130824-7798c080-cdcd-11e9-99f0-7ded87541a85.png)
-
-### Install
-
-```shell
-npm install @2bad/bitrix
-```
-
-### Usage
-
-Init client with Bitrix API endpoint and access token and use the client to ease your Bitrix pain:
-
-```typescript
-import Bitrix from '@2bad/bitrix'
-// or for ESM
-import { Bitrix } from '@2bad/bitrix'
-
-const bitrix = Bitrix('https://PORTAL_NAME.bitrix24.ru/rest', 'ACCESS_TOKEN')
-
-// Get deal
-bitrix.deals.get('77')
-  .then(({ result }) => {
-    // Get typed payload
-    const { TITLE } = result // string
-    console.log(TITLE)
-  })
-  .catch(console.error)
-
-// Get all deals
-bitrix.deals.list({ select: ["*", "UF_*"] })
-  .then(({ result }) => {
-    const titles = result.map((e) => e.TITLE)
-    console.log(titles)
-  })
-  .catch(console.error)
-```
-
-### Authentication
-
-Before you'll be able to use Bitrix REST API, you need to authenticate.
-
-There are two ways to do that:
-
-1. **A harder, but proper way** — create a Bitrix application and then authenticate with an OAuth.
-
-   Authentication with an OAuth requires some additional steps and that's up to you to deal with it using a lambda function, some server or a Postman.
-
-   That will yield an access token. Use it to init the client:
-
-   ```typescript
-   const bitrix = Bitrix('https://PORTAL_NAME.bitrix24.ru/rest', 'ACCESS_TOKEN')
-   ```
-
-   Note, that access token lives only 30 minutes and should be refreshed periodically with provided by OAuth refresh token, which in turn lives 1 month.
-
-2. **An easier way** — create a Bitrix inbound webhook with required permissions.
-
-   It will instantly give you an endpoint with a token inside of it. No additional authentication or access tokens required to use it:
-
-   ```typescript
-   const bitrix = Bitrix('https://PORTAL_NAME.bitrix24.ru/rest/1/WEBHOOK_TOKEN')
-   ```
-
-   That endpoint lives indefinitely. Rejoice and hope that it won't backfire on you.
-
-### API
 
-- Generic
-  - [`call()`](docs/methods.md#call)
-  - [`list()`](docs/methods.md#list)
-  - [`batch()`](docs/methods.md#batch)
-- CRM
-  - [Company](docs/services/companies.md)
-  - [Contact](docs/services/contacts.md)
-  - [Currency](docs/services/currencies.md)
-  - [Deal](docs/services/deals.md)
-  - [Lead](docs/services/leads.md)
-  - [Status](docs/services/statuses.md)
-- [User](docs/services/users.md)
+Bitrix24 REST API client for TypeScript with zero runtime dependencies.
 
-### How it works
+## Why
 
-The client tries hard to provide a consistent, strongly typed and at the same time effortless experience.
+Bitrix24 ships half-finished APIs to production and leaves you to find out how they actually work. Every module has its own field names, error formats and paging rules. The documentation is incomplete, out of date or wrong, a good part of the behavior isn't documented at all, and support won't help you. Every integration turns into reverse engineering, fixing one broken assumption at a time.
 
-It takes care of the any necessary batching to run "large" commands, like retrieving all deals or leads with least possible network request. That allows achieving a reading of the 250 000 and updating of 5000 entries per minute with a single line of code.
+We did that work so you don't have to. This client takes whatever Bitrix throws at it and gives you something you can actually build on.
 
-All client methods are automatically rate-limited and queued if needed to cope with Bitrix REST API limitation of 2 requests per second, so you should never see Bitrix errors about exceeding rate limits.
+## What you get
 
-Methods required params and returned payload types are automatically resolved based on [Methods](source/types.ts) interface, which effectively describes all currently supported methods.
+- No bullshit
+- Expressive API
+- Strongly typed, including the custom fields of your portal
+- Handles batching, rate limits and retries for you
+- Zero dependencies, runs anywhere `fetch` does
 
-To facilitate better architecture, the client divided into layers:
+## Install
 
-1. **Methods** — a mostly generic [methods](docs/methods.md) like `call` to work with Bitrix API methods. They take care of the routine and provide a foundation for more complex operations.
-2. **Client** — a generic [client](source/client/README.md), which takes care of some additional routine tasks like setting access token on every request, setting up a queue for the rate limiting, and providing generic methods.
-3. **Services** — each [service](docs/services/README.md) provides an expressive interface to work with a specific group of Bitrix REST API operations. In essence, they do orchestrate generic client methods and parameters to get proper results.
-4. **Bitrix client** — a top-level [provider](source/bitrix.ts) of generic method and services. An effortless way to deal with Bitrix REST API by using an intuitive API, which takes care of all underlying complexity.
-
-### FAQ
-
-> Is it finished?
-
-The core is ready and stable. It can be used to arbitrary invoke any Bitrix REST API methods.
-
-However, not all Bitrix REST API methods are exposed as convenient client services yet \(the ones like `bitrix.deals.list()`\).
-
-If you need specific service, add one by making a Pull Request, following the structure of already existing [services](source/services/README.md) and ["Adding new methods"](./#adding-new-methods) instructions.
-
-> I'm not a Typed Language Master Race user. Can I use it with a regular JavaScript?
-
-Sure. Just install and import it as any other NPM module. But The Type Police is already on the way for you.
-
-Note that this library wasn't designed with regular JavaScript in mind, so it doesn't make unnecessary dynamic checks. Don't be too persistent in passing on wrong parameters — it might yield unexpected results. After all, TypeScript is a recommended way to use it.
-
-> Should I check payloads `error` properties for errors?
-
-You shouldn't. Catch rejections instead, as the library will reject if there are any errors in a payload.
-
-> List method does not return user fields!
-
-Bitrix API doesn't do that by default. Use wildcards in `select` param to force inclusion of user fields:
-
-```typescript
-bitrix.deals.list({ select: ['*', 'UF_*'] })
+```sh
+npm install @2bad/bitrix
 ```
 
-> User fields are not typed properly
+ESM only. Requires Node.js 26 or later.
 
-Client can't know about non-default properties in payloads. Because of that, it assumes that any payload can have any additional fields of type `[key: string]: string`:
+## Quick start
 
-```typescript
-bitrix.leads.get({ ID: '77' })
-  .then(({ result }) => {
-    // known property of type `string`
-    const title = result.TITLE
-
-    // unknown property of type `string`
-    const someData = result.UF_23232323
-
-    console.log(title, someData)
-  })
-```
+```ts
+import { createClient } from '@2bad/bitrix'
 
-> I need to call a Bitrix method which isn't supported yet
+const bitrix = createClient({ url: 'https://portal.bitrix24.com/rest/1/WEBHOOK_TOKEN' })
 
-Use appropriate low-level client methods with a casting, like so:
+const deal = await bitrix.deals.get(77)
+console.log(deal.TITLE, deal.STAGE_ID) // Pump delivery C2:WON
 
-```typescript
-bitrix.call('some.new.get' as any, { ID: '77' } as any)
-  .then((payload) => payload as GetPayload<NewPayload>)
-
-bitrix.list('some.new.list' as any, { select: ["TITLE"] })
-  .then((payload) => payload as ListPayload<NewPayload>)
+const open = await bitrix.deals.list({ filter: { CLOSED: 'N' }, select: ['ID', 'TITLE'] })
 ```
 
-> I need to call a specific set of commands. How to do that effectively?
-
-Use the `batch` method. It will handle all routine:
-
-```typescript
-bitrix.batch({
-  lead: { method: Method.GET_LEAD, params: { ID: '77' } },
-  deals: { method: Method.LIST_DEALS, params: {} }
-})
+## Examples
+
+- [Connecting](examples/connecting.md): webhooks, OAuth, rate limits, logging and custom `fetch`
+- [Services](examples/services.md): deals, leads, contacts, companies, activities, smart processes, linked contacts, products, statuses, currencies and users
+- [Lists](examples/lists.md): pagination modes, changes since the last sync and progress
+- [Batch and bulk writes](examples/batch.md): many commands per request, `createMany`, `updateMany`, `deleteMany`
+- [Types](examples/types.md): user field types from your portal and typing other methods
+- [Errors](examples/errors.md): `BitrixError`, retries and cancellation
+- [Migrating from 2.x](examples/migrating.md)
+
+## API
+
+```ts
+function createClient(options: ClientOptions): Client
+
+type Client = {
+  call(method, params?, options?: { raw?; signal? }): Promise<Result> // the whole response with { raw: true }
+  list(method, params?, options?: PaginateOptions): Promise<Row[]>
+  paginate(method, params?, options?: PaginateOptions): AsyncGenerator<Row>
+  batch(commands, options?: { halt?; signal? }): Promise<{ results; errors }>
+
+  activities: CrmService<Activity>
+  companies: CrmService<Company> & { contacts: Links }
+  contacts: CrmService<Contact> & { companies: Links }
+  currencies: CurrenciesService
+  deals: CrmService<Deal> & { productRows: ProductRows; contacts: Links }
+  items(entityTypeId): ItemsService // smart processes and other crm.item.* types
+  leads: CrmService<Lead> & { productRows: ProductRows; contacts: Links }
+  products: ProductsService
+  statuses: StatusesService
+  users: UsersService
+}
+
+type CrmService<Entity> = {
+  fields(): Promise<Fields>
+  get(id): Promise<Entity>
+  list(params?, options?: PaginateOptions): Promise<Entity[]> // rows typed by params.select
+  paginate(params?, options?: PaginateOptions): AsyncGenerator<Entity>
+  changedSince(since: Date | string, params?, options?): AsyncGenerator<Entity> // oldest change first
+  create(fields, params?): Promise<number>
+  update(id, fields, params?): Promise<boolean>
+  delete(id): Promise<boolean>
+  createMany(items, params?): Promise<BulkResult<number>>
+  updateMany(items: { id; fields }[], params?): Promise<BulkResult<boolean>>
+  deleteMany(ids): Promise<BulkResult<boolean>>
+}
+
+type ProductRows = { get(id): Promise<ProductRow[]>; set(id, rows): Promise<boolean> }
+type Links = { get(id); set(id, links); add(id, link); delete(id, linkedId); clear(id) }
+type ItemsService = { fields(); get(id); list(params?); paginate(params?); changedSince(since, params?); create(fields); update(id, fields); delete(id) }
+type ProductsService = { fields(iblockId); get(id); list(params); paginate(params); create(fields); update(id, fields); delete(id) }
+type StatusesService = { fields(); get(id); list(params?); create(fields); update(id, fields); delete(id, { forced? }) }
+type CurrenciesService = { fields(); get(code); list(params?); create(fields); update(code, fields); delete(code); base(); setBase(code) }
+type UsersService = { fields(); current(); get(id); list(params?); paginate(params?) }
+
+type PaginateOptions = {
+  mode?: 'cursor' | 'offset' | 'modified' // cursor by default, modified needs since
+  since?: Date | string
+  modifiedField?: string // DATE_MODIFY by default
+  idField?: string // ID by default
+  signal?: AbortSignal
+  onProgress?: (progress: { read: number; total?: number }) => void
+}
+
+type BulkResult<R> = { results: (R | undefined)[]; errors: (BitrixError | undefined)[] } // in input order
 ```
 
-> I'm using a self-signed SSL certificate and I'm getting a `[RequestError]: self signed certificate`. What should I do?
+```sh
+bitrix-types [--url <rest url>] [--out <file>] [--entities deal,lead,contact,company]
+```
 
-Override [`got options`](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md) in constructor:
+Every error is a `BitrixError` with `code`, `description`, `method` and `status`.
 
-```typescript
-const bitrix = Bitrix('https://PORTAL_NAME.bitrix24.ru/rest', 'ACCESS_TOKEN', {https: { rejectUnauthorized: false }})
-```
+## License
 
-### Development
-
-- `npm test` — run all tests and collect full coverage report
-- `npm run test:unit` — run unit tests and collect coverage report
-- `npm run test:integration` — run integration tests and collect coverage report
-- `npm run test:watch` — watch for changes and run all tests
-- `npm run test:unit:watch` — watch for changes and run unit tests
-- `npm run test:integration:watch` — watch for changes and run integration tests
-- `npm run build` — build the library for the release
-
-#### Adding new methods
-
-Proper method parameters and payload types handling requires some routine when adding any new method. Hopefully, we can do it better in future, but for now follow those steps:
-
-1. Add new method into the [`Method`](source/methods.ts) enum.
-2. Add it into the [`LISTABLE_METHODS`](source/methods.ts) array if it is listable \(paginated\). Not everything that lists is listable, so check it.
-3. Add or update related [service](source/services/README.md):
-   1. Put exposed by the service public methods into the `index.ts` file. Ensure that you're properly mapping service method arguments to `call` or `list` params.
-   2. Add related entities into the `entities.ts`.
-   3. Add interface describing service methods into the `methods.ts`. Test and check method payload type to be sure you've described it correctly!
-   4. Extend [`Methods`](source/methods.ts) interface with the added service-specific interface. That way the client will know how to resolve parameters and payload types for the added method.
-   5. Add tests into the `index.unit.test.ts`.
-4. Re-export service public types like Entities in the [bitrix.ts](source/bitrix.ts) to make them available to the end-users.
-5. Document addition in the [docs](docs/README.md).
+MIT

package/build/bin.d.ts

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

package/build/bin.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { t as createClient } from "./client-Bk76ySik.js";
+import { writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+// source/user-fields.ts
+const USER_FIELD_ENTITIES = {
+	deal: "DealUserFields",
+	lead: "LeadUserFields",
+	contact: "ContactUserFields",
+	company: "CompanyUserFields"
+};
+const STRING_TYPES = /* @__PURE__ */ new Set([
+	"string",
+	"url",
+	"address",
+	"money",
+	"date",
+	"datetime",
+	"employee",
+	"crm",
+	"crm_status",
+	"iblock_element",
+	"iblock_section"
+]);
+/**
+* Value type as Bitrix returns it in `get` and `list`: enumerations as item ids, strings in single fields
+* and numbers in multiple ones, multiple fields as arrays or `false` when empty
+* @param field field description from `crm.<entity>.fields`
+*/
+const valueType = (field) => {
+	const multiple = field.isMultiple;
+	const items = field.items ?? [];
+	const single = (() => {
+		if (field.type === "enumeration" && items.length > 0) return items.map(({ ID }) => multiple ? String(Number(ID)) : `'${ID.replaceAll("'", "\\'")}'`).join(" | ");
+		if (field.type === "boolean") return `'0' | '1'`;
+		if (field.type === "integer" || field.type === "double") return "number | string";
+		if (field.type === "file") return "UserFieldFile";
+		if (field.type === "enumeration" || STRING_TYPES.has(field.type)) return "string";
+		return "unknown";
+	})();
+	const usesFile = field.type === "file";
+	if (single === "unknown") return {
+		type: single,
+		usesFile
+	};
+	return multiple ? {
+		type: `ReadonlyArray<${single}> | false`,
+		usesFile
+	} : {
+		type: `${single} | null`,
+		usesFile
+	};
+};
+const comment = (field, indent) => {
+	const lines = [field.formLabel || field.listLabel || field.title, ...(field.items ?? []).map(({ ID, VALUE }) => `- ${ID}: ${VALUE}`)].map((line) => line.replaceAll(/\s+/g, " ").trim().replaceAll("*/", "*\\/"));
+	return lines.length === 1 ? `${indent}/** ${lines[0]} */` : [
+		`${indent}/**`,
+		...lines.map((line) => `${indent} * ${line}`),
+		`${indent} */`
+	].join("\n");
+};
+/**
+* Renders a declaration file that augments the client entity types with the user fields of a portal
+* @param fields `crm.<entity>.fields` results by entity
+* @param origin portal origin for the header, without any token
+*/
+const renderUserFields = (fields, origin) => {
+	let usesFile = false;
+	const interfaces = Object.entries(USER_FIELD_ENTITIES).flatMap(([entity, name]) => {
+		const entityFields = fields[entity];
+		if (!entityFields) return [];
+		const members = Object.entries(entityFields).filter(([key]) => key.startsWith("UF_")).toSorted(([a], [b]) => a.localeCompare(b)).map(([key, field]) => {
+			const value = valueType(field);
+			usesFile ||= value.usesFile;
+			return `${comment(field, "    ")}\n    readonly ${key}: ${value.type}`;
+		});
+		return [members.length === 0 ? `  interface ${name} {}` : `  interface ${name} {\n${members.join("\n")}\n  }`];
+	});
+	return [
+		`// Generated by bitrix-types from ${origin}. Run it again instead of editing this file.`,
+		...usesFile ? [`import type { UserFieldFile } from '@2bad/bitrix'`] : [],
+		"",
+		`declare module '@2bad/bitrix' {`,
+		interfaces.join("\n\n"),
+		"}",
+		"",
+		"export {}",
+		""
+	].join("\n");
+};
+// source/cli.ts
+const USAGE = `Usage: bitrix-types [--url <rest url>] [--out <file>] [--entities deal,lead,contact,company]
+
+Writes TypeScript declarations for the user fields of a Bitrix24 portal to stdout or --out.
+The url can also come from BITRIX_URL, an OAuth access token from BITRIX_TOKEN.`;
+const isEntity = (entity) => Object.hasOwn(USER_FIELD_ENTITIES, entity);
+/**
+* Runs `bitrix-types` and resolves with the exit code
+* @param args command line arguments without the node binary and script
+* @param env environment variables
+* @param io output streams, file writer and an optional fetch
+*/
+const run = async (args, env, io) => {
+	const fail = (message) => {
+		io.stderr(`${message}\n`);
+		return 1;
+	};
+	let values;
+	try {
+		({values} = parseArgs({
+			args: [...args],
+			options: {
+				url: { type: "string" },
+				out: { type: "string" },
+				entities: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			}
+		}));
+	} catch (error) {
+		return fail(`${error.message}\n\n${USAGE}`);
+	}
+	if (values.help) {
+		io.stdout(`${USAGE}\n`);
+		return 0;
+	}
+	const url = values.url ?? env["BITRIX_URL"];
+	if (!url) return fail(`Missing the portal url\n\n${USAGE}`);
+	const entities = values.entities?.split(",").map((entity) => entity.trim()) ?? Object.keys(USER_FIELD_ENTITIES);
+	const unknown = entities.filter((entity) => !isEntity(entity));
+	if (unknown.length > 0) return fail(`Unknown entities: ${unknown.join(", ")}\n\n${USAGE}`);
+	const token = env["BITRIX_TOKEN"];
+	try {
+		const { results, errors } = await createClient({
+			url,
+			...token && { auth: token },
+			...io.fetch && { fetch: io.fetch }
+		}).batch(Object.fromEntries(entities.map((entity) => [entity, { method: `crm.${entity}.fields` }])));
+		const failed = Object.values(errors).filter((error) => error !== void 0);
+		if (failed.length > 0) return fail(failed.map((error) => error.message).join("\n"));
+		const output = renderUserFields(results, new URL(url).origin);
+		if (values.out === void 0) io.stdout(output);
+		else {
+			await io.writeFile(values.out, output);
+			io.stderr(`Wrote user field types for ${entities.join(", ")} to ${values.out}\n`);
+		}
+		return 0;
+	} catch (error) {
+		return fail(error.message);
+	}
+};
+// source/bin.ts
+process.exitCode = await run(process.argv.slice(2), process.env, {
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text),
+	writeFile
+});
+export {};