amo-controller 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Андрей Тулев
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# amo-controller
+
+TypeScript-клиент для [AmoCRM API v4](https://www.amocrm.ru/developers/content/crm_platform/api-reference): сделки, контакты, компании, задачи, заметки, воронки, пользователи, теги, события и др. Запросы идут через **axios**, ограничение частоты — **Bottleneck** (по умолчанию до 6 запросов в секунду).
+
+## Установка
+
+```bash
+npm install
+```
+
+## Сборка
+
+Компиляция в каталог `amo/` (см. `tsconfig.json`):
+
+```bash
+npm run build
+```
+
+Точка входа после сборки: `amo/index.js` (поле `main` в `package.json`).
+
+## Использование
+
+```ts
+import Amo from 'amo-controller'
+
+const amo = new Amo('https://example.amocrm.ru', 'access_token', {
+  rps: 6,
+  logs: {
+    throwErrors: false,
+    // customLogger: myWinstonLogger,
+  },
+})
+
+const leads = await amo.leads.get({ limit: 50 })
+```
+
+- **`rps`** — целевое число запросов в секунду (лимитер на исходящие вызовы).
+- **`logs.throwErrors`** — если `true`, ошибки HTTP после логирования пробрасываются дальше; иначе методы вроде `get` / `create` / `update` часто возвращают `null`.
+- **`logs.customLogger`** — экземпляр winston вместо встроенного логгера.
+
+## Скрипты
+
+| Команда        | Назначение                    |
+| -------------- | ----------------------------- |
+| `npm run build` | Сборка TypeScript → `amo/`   |
+| `npm run lint`  | Проверка ESLint               |
+| `npm run lint:fix` | ESLint с автоисправлением  |
+| `npm run format` | Prettier                      |
+| `npm test`      | Запуск `index.test.ts` (нужен `.env`) |
+
+## Локальная проверка API (`npm test`)
+
+В корне создайте файл `.env`:
+
+```env
+API_URL=https://ваш-поддомен.amocrm.ru
+API_TOKEN=долгосрочный_токен
+```
+
+Скрипт `index.test.ts` обращается к реальному API; используйте только на тестовом аккаунте.
+
+## Разработка
+
+- Исходники: `classes/`, `types/`, `utils/`.
+- Статический анализ: **ESLint** (`eslint.config.mjs`) + **TypeScript** в режиме `strict`.
+
+## Лицензия
+
+ISC

package/classes/Amo.d.ts

@@ -0,0 +1,50 @@
+import { AxiosInstance } from 'axios';
+import Leads from './Leads';
+import Companies from './Companies';
+import Contacts from './Contacts';
+import Users from './Users';
+import Pipelines from './Pipelines';
+import LossReasons from './LossReasons';
+import Notes from './Notes';
+import Tags from './Tags';
+import Events from './Events';
+import Tasks from './Tasks';
+import { Logger } from '../types/logs';
+export default class Amo {
+    private baseURL;
+    private token;
+    readonly options?: {
+        rps?: number;
+        logs?: {
+            customLogger?: Logger;
+            throwErrors?: boolean;
+        };
+    } | undefined;
+    instance: AxiosInstance;
+    private limiter;
+    constructor(baseURL: string, token: string, options?: {
+        rps?: number;
+        logs?: {
+            customLogger?: Logger;
+            throwErrors?: boolean;
+        };
+    } | undefined);
+    leads: Leads;
+    contacts: Contacts;
+    companies: Companies;
+    notes: {
+        leads: Notes<"leads">;
+        contacts: Notes<"contacts">;
+        companies: Notes<"companies">;
+    };
+    tasks: Tasks;
+    pipelines: Pipelines;
+    users: Users;
+    loss_reasons: LossReasons;
+    tags: {
+        leads: Tags<"leads">;
+        contacts: Tags<"contacts">;
+        companies: Tags<"companies">;
+    };
+    events: Events;
+}

package/classes/Amo.js

@@ -0,0 +1,61 @@
+import axios from 'axios';
+import Bottleneck from 'bottleneck';
+import Leads from './Leads';
+import Companies from './Companies';
+import Contacts from './Contacts';
+import Users from './Users';
+import Pipelines from './Pipelines';
+import LossReasons from './LossReasons';
+import Notes from './Notes';
+import Tags from './Tags';
+import Events from './Events';
+import Tasks from './Tasks';
+import qs from 'qs';
+export default class Amo {
+    baseURL;
+    token;
+    options;
+    instance;
+    limiter;
+    constructor(baseURL, token, options) {
+        this.baseURL = baseURL;
+        this.token = token;
+        this.options = options;
+        const rps = this.options?.rps || 6;
+        this.limiter = new Bottleneck({
+            minTime: Math.ceil(1000 / rps),
+            maxConcurrent: rps,
+        });
+        this.instance = axios.create({
+            baseURL: this.baseURL,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            paramsSerializer: (params) => {
+                return qs.stringify(params);
+            },
+        });
+        this.instance.interceptors.request.use(async (config) => {
+            return this.limiter.schedule(async () => config);
+        });
+    }
+    leads = new Leads(this);
+    contacts = new Contacts(this);
+    companies = new Companies(this);
+    notes = {
+        leads: new Notes(this, 'leads'),
+        contacts: new Notes(this, 'contacts'),
+        companies: new Notes(this, 'companies'),
+    };
+    tasks = new Tasks(this);
+    pipelines = new Pipelines(this);
+    users = new Users(this);
+    loss_reasons = new LossReasons(this);
+    tags = {
+        leads: new Tags(this, 'leads'),
+        contacts: new Tags(this, 'contacts'),
+        companies: new Tags(this, 'companies'),
+    };
+    events = new Events(this);
+}

package/classes/Companies.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import { Company } from '../types/company';
+import { DefaultQueryParams } from '../types/query_params';
+import EntityWithCodeFields from './base/EntityWithCodeFields';
+export default class Companies extends EntityWithCodeFields<'companies', Company, DefaultQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Companies.js

@@ -0,0 +1,8 @@
+import EntityWithCodeFields from './base/EntityWithCodeFields';
+export default class Companies extends EntityWithCodeFields {
+    amo;
+    constructor(amo) {
+        super(amo, 'companies');
+        this.amo = amo;
+    }
+}

package/classes/Contacts.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import { Contact } from '../types/contact';
+import { DefaultQueryParams } from '../types/query_params';
+import EntityWithCodeFields from './base/EntityWithCodeFields';
+export default class Contacts extends EntityWithCodeFields<'contacts', Contact, DefaultQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Contacts.js

@@ -0,0 +1,8 @@
+import EntityWithCodeFields from './base/EntityWithCodeFields';
+export default class Contacts extends EntityWithCodeFields {
+    amo;
+    constructor(amo) {
+        super(amo, 'contacts');
+        this.amo = amo;
+    }
+}

package/classes/Events.d.ts

@@ -0,0 +1,8 @@
+import { EventQueryParams } from './../types/query_params';
+import { Event } from './../types/events';
+import Amo from './Amo';
+import EntityGetOnly from './base/EntityGetOnly.js';
+export default class Events extends EntityGetOnly<'events', Event, EventQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Events.js

@@ -0,0 +1,8 @@
+import EntityGetOnly from './base/EntityGetOnly.js';
+export default class Events extends EntityGetOnly {
+    amo;
+    constructor(amo) {
+        super(amo, 'events');
+        this.amo = amo;
+    }
+}

package/classes/Leads.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import { Lead } from '../types/lead';
+import Entity from './base/Entity';
+import { DefaultQueryParams } from '../types/query_params';
+export default class Leads extends Entity<'leads', Lead, DefaultQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Leads.js

@@ -0,0 +1,8 @@
+import Entity from './base/Entity';
+export default class Leads extends Entity {
+    amo;
+    constructor(amo) {
+        super(amo, 'leads');
+        this.amo = amo;
+    }
+}

package/classes/LossReasons.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import EntityGetOnly from './base/EntityGetOnly';
+import { LossReason } from '../types/loss_reason';
+import { LossReasonQueryParams } from '../types/query_params';
+export default class LossReasons extends EntityGetOnly<'leads/loss_reasons', LossReason, LossReasonQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/LossReasons.js

@@ -0,0 +1,8 @@
+import EntityGetOnly from './base/EntityGetOnly';
+export default class LossReasons extends EntityGetOnly {
+    amo;
+    constructor(amo) {
+        super(amo, 'leads/loss_reasons');
+        this.amo = amo;
+    }
+}

package/classes/Notes.d.ts

@@ -0,0 +1,12 @@
+import Amo from './Amo';
+import Entity from './base/Entity';
+import { Note } from '../types/note';
+import { SecondEntityType } from '../types/entity';
+import { NoteQueryParams } from '../types/query_params';
+export default class Notes<S extends SecondEntityType> extends Entity<`${S}/notes`, Note, NoteQueryParams> {
+    protected amo: Amo;
+    protected entity: S;
+    constructor(amo: Amo, entity: S);
+    pin(noteId: number): Promise<import("axios").AxiosResponse<any, any, {}>> | null;
+    unpin(noteId: number): Promise<import("axios").AxiosResponse<any, any, {}>> | null;
+}

package/classes/Notes.js

@@ -0,0 +1,34 @@
+import Entity from './base/Entity';
+import logError from '../utils/error';
+import { AxiosError } from 'axios';
+export default class Notes extends Entity {
+    amo;
+    entity;
+    constructor(amo, entity) {
+        super(amo, `${entity}/notes`);
+        this.amo = amo;
+        this.entity = entity;
+    }
+    pin(noteId) {
+        try {
+            return this.amo.instance.post(`${this.url}/${noteId}/pin`);
+        }
+        catch (error) {
+            logError(`pin ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+            return null;
+        }
+    }
+    unpin(noteId) {
+        try {
+            return this.amo.instance.post(`${this.url}/${noteId}/unpin`);
+        }
+        catch (error) {
+            logError(`unpin ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+            return null;
+        }
+    }
+}

package/classes/Pipelines.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import EntityGetOnly from './base/EntityGetOnly';
+import { Pipeline } from '../types/pipeline';
+import { PipelineQueryParams } from '../types/query_params';
+export default class Pipelines extends EntityGetOnly<'leads/pipelines', Pipeline, PipelineQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Pipelines.js

@@ -0,0 +1,8 @@
+import EntityGetOnly from './base/EntityGetOnly';
+export default class Pipelines extends EntityGetOnly {
+    amo;
+    constructor(amo) {
+        super(amo, 'leads/pipelines');
+        this.amo = amo;
+    }
+}

package/classes/Tags.d.ts

@@ -0,0 +1,10 @@
+import Amo from './Amo';
+import { SecondEntityType } from '../types/entity';
+import { Tag } from '../types/tag';
+import EntityGetOnly from './base/EntityGetOnly';
+import { TagQueryParams } from '../types/query_params';
+export default class Tags<S extends SecondEntityType> extends EntityGetOnly<`${S}/tags`, Tag, TagQueryParams> {
+    protected amo: Amo;
+    protected entity: S;
+    constructor(amo: Amo, entity: S);
+}

package/classes/Tags.js

@@ -0,0 +1,10 @@
+import EntityGetOnly from './base/EntityGetOnly';
+export default class Tags extends EntityGetOnly {
+    amo;
+    entity;
+    constructor(amo, entity) {
+        super(amo, `${entity}/tags`);
+        this.amo = amo;
+        this.entity = entity;
+    }
+}

package/classes/Tasks.d.ts

@@ -0,0 +1,8 @@
+import Amo from './Amo';
+import { Task } from '../types/task';
+import Entity from './base/Entity';
+import { TaskQueryParams } from '../types/query_params';
+export default class Tasks extends Entity<'tasks', Task, TaskQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+}

package/classes/Tasks.js

@@ -0,0 +1,8 @@
+import Entity from './base/Entity';
+export default class Tasks extends Entity {
+    amo;
+    constructor(amo) {
+        super(amo, 'tasks');
+        this.amo = amo;
+    }
+}

package/classes/Users.d.ts

@@ -0,0 +1,10 @@
+import EntityGetOnly from './base/EntityGetOnly';
+import Amo from './Amo';
+import { User } from '../types/user';
+import { UserQueryParams } from '../types/query_params';
+export default class Users extends EntityGetOnly<'users', User, UserQueryParams> {
+    protected amo: Amo;
+    constructor(amo: Amo);
+    getById(id: number): Promise<User | null>;
+    getByName(name: string): Promise<User | null>;
+}

package/classes/Users.js

@@ -0,0 +1,20 @@
+import EntityGetOnly from './base/EntityGetOnly';
+export default class Users extends EntityGetOnly {
+    amo;
+    constructor(amo) {
+        super(amo, 'users');
+        this.amo = amo;
+    }
+    async getById(id) {
+        const users = await this.get();
+        if (!users)
+            return users;
+        return users.find((user) => user.id === id) || null;
+    }
+    async getByName(name) {
+        const users = await this.get();
+        if (!users)
+            return users;
+        return users.find((user) => user.name === name) || null;
+    }
+}

package/classes/base/Entity.d.ts

@@ -0,0 +1,20 @@
+import { QueryParams } from '../../types/query_params';
+import Amo from '../Amo';
+import { CreateResponse, UpdateResponse } from '../../types/responses';
+import { CustomField } from '../../types/custom_fields';
+import { EntitiesType, EntityClass, EntitiesFields, ExtendableEntitiesForUpdate, PartialExcept, SecondEntityType, ToUpdate } from '../../types/entity';
+export default class Entity<N extends EntitiesType, E extends EntitiesFields, Q extends QueryParams> implements EntityClass<E, Q> {
+    protected amo: Amo;
+    protected type: N;
+    constructor(amo: Amo, type: N);
+    readonly url: string;
+    readonly limit: number;
+    get(params?: Q, page?: number, acc?: E[]): Promise<E[] | null>;
+    getCustomFieldById(entity: E, id: number): CustomField | null;
+    getNewest(entities: E[], by: 'created_at' | 'updated_at' | 'closed_at'): E;
+    getOldest(entities: E[], by: 'created_at' | 'updated_at'): E;
+    create(entities: Partial<E>[]): Promise<CreateResponse[] | null>;
+    update(entities: (E extends ExtendableEntitiesForUpdate ? PartialExcept<E, 'id'> & ToUpdate : PartialExcept<E, 'id'>)[]): Promise<UpdateResponse[] | null>;
+    link(entity: SecondEntityType, id: number, linkIds: number[]): Promise<void>;
+    unlink(entity: SecondEntityType, id: number, linkIds: number[]): Promise<void>;
+}

package/classes/base/Entity.js

@@ -0,0 +1,137 @@
+import logError from '../../utils/error';
+import { AxiosError } from 'axios';
+export default class Entity {
+    amo;
+    type;
+    constructor(amo, type) {
+        this.amo = amo;
+        this.type = type;
+        this.url = 'api/v4/' + type;
+        this.type = type.split('/').at(-1);
+        this.limit = 250;
+    }
+    url;
+    limit;
+    async get(params = {}, page = 1, acc = []) {
+        try {
+            const response = await this.amo.instance.get(this.url, {
+                params: {
+                    limit: this.limit,
+                    page,
+                    ...params,
+                },
+            });
+            const entity = response.data._embedded?.[this.type];
+            if (!entity)
+                return acc;
+            const result = acc.concat(entity);
+            if (entity.length === (params.limit || this.limit) && !params.page) {
+                return this.get(params, ++page, result);
+            }
+            return result;
+        }
+        catch (error) {
+            logError(`get ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+            return null;
+        }
+    }
+    getCustomFieldById(entity, id) {
+        const field = entity.custom_fields_values?.find((field) => {
+            if (field.field_id && field.field_id === id)
+                return field;
+        });
+        return field || null;
+    }
+    getNewest(entities, by) {
+        let newest = entities[0];
+        for (const entity of entities) {
+            const newestBy = newest[by];
+            if (!newestBy) {
+                newest = entity;
+                continue;
+            }
+            const entityBy = entity[by];
+            if (!entityBy)
+                continue;
+            if (entityBy > newestBy)
+                newest = entity;
+        }
+        return newest;
+    }
+    getOldest(entities, by) {
+        let oldest = entities[0];
+        for (const entity of entities) {
+            const oldestBy = oldest[by];
+            if (!oldestBy) {
+                oldest = entity;
+                continue;
+            }
+            const entityBy = entity[by];
+            if (!entityBy)
+                continue;
+            if (entityBy < oldestBy)
+                oldest = entity;
+        }
+        return oldest;
+    }
+    async create(entities) {
+        try {
+            const response = await this.amo.instance.post(this.url, entities);
+            return response.data._embedded?.[this.type];
+        }
+        catch (error) {
+            logError(`create ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+            return null;
+        }
+    }
+    async update(entities) {
+        try {
+            const response = await this.amo.instance.patch(this.url, entities);
+            return response.data._embedded?.[this.type];
+        }
+        catch (error) {
+            logError(`update ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+            return null;
+        }
+    }
+    async link(entity, id, linkIds) {
+        try {
+            const data = [];
+            for (const link of linkIds)
+                data.push({
+                    entity_id: id,
+                    to_entity_id: link,
+                    to_entity_type: entity,
+                });
+            await this.amo.instance.post(this.url + '/link', data);
+        }
+        catch (error) {
+            logError(`link ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+        }
+    }
+    async unlink(entity, id, linkIds) {
+        try {
+            const data = [];
+            for (const link of linkIds)
+                data.push({
+                    entity_id: id,
+                    to_entity_id: link,
+                    to_entity_type: entity,
+                });
+            await this.amo.instance.post(this.url + '/unlink', data);
+        }
+        catch (error) {
+            logError(`unlink ${this.type} error`, error, error instanceof AxiosError ? error.response?.data : null, this.amo.options?.logs?.customLogger);
+            if (this.amo.options?.logs?.throwErrors)
+                throw error;
+        }
+    }
+}

package/classes/base/EntityGetOnly.d.ts

@@ -0,0 +1,14 @@
+import { GetOnlyParams } from '../../types/query_params';
+import Amo from '../Amo';
+import { EntitiesGetOnlyType, EntityGetOnlyClass } from '../../types/entity_get_only';
+import type { EntitiesFields } from '../../types/entity';
+export default class EntityGetOnly<N extends EntitiesGetOnlyType, E extends EntitiesFields, Q extends GetOnlyParams> implements EntityGetOnlyClass<E, Q> {
+    protected amo: Amo;
+    protected type: N;
+    constructor(amo: Amo, type: N);
+    readonly url: string;
+    readonly limit: number;
+    get(params?: Q, page?: number, acc?: E[]): Promise<E[] | null>;
+    getNewest(entities: E[], by: 'created_at' | 'updated_at'): E;
+    getOldest(entities: E[], by: 'created_at' | 'updated_at'): E;
+}