Замените {Название пакета} на реальное название (например: "@integ/core", "@integ/telegram", "integ-utils")

Краткое описание пакета в 1-2 предложения. Что делает пакет и когда его использовать.

Установка

# npm
npm install @integ/package-name

# yarn
yarn add @integ/package-name

# pnpm
pnpm add @integ/package-name

Быстрый старт

import { MainClass } from "@integ/package-name";

const instance = new MainClass({
	option: "value"
});

const result = await instance.doSomething();
console.log(result);

Обзор

Назначение

Пакет предназначен для:

• Задача 1 - описание
• Задача 2 - описание
• Задача 3 - описание

Когда использовать

• ✅ Используйте когда нужно делать X
• ✅ Используйте для задачи Y
• ❌ Не используйте для Z (используйте другой-пакет вместо)

Архитектура

graph TB
    YourApp[Ваше приложение]
    Package[@integ/package-name]
    API[Integ API]

    YourApp --> Package
    Package --> API

Требования

• Node.js >= 18
• TypeScript >= 5.0 (рекомендуется)

Peer Dependencies

{
	"peerDependencies": {
		"typescript": ">=5.0.0"
	}
}

Конфигурация

Опции инициализации

interface PackageOptions {
	/** URL API (по умолчанию: http://localhost:3000/api) */
	baseUrl?: string;

	/** Токен авторизации */
	accessToken: string;

	/** Таймаут запросов в ms (по умолчанию: 5000) */
	timeout?: number;

	/** Количество повторных попыток (по умолчанию: 3) */
	retries?: number;

	/** Включить логирование (по умолчанию: false) */
	debug?: boolean;
}

Пример конфигурации

import { Client } from "@integ/package-name";

const client = new Client({
	baseUrl: process.env.INTEG_API_URL,
	accessToken: process.env.INTEG_ACCESS_TOKEN,
	timeout: 10000,
	retries: 5,
	debug: process.env.NODE_ENV === "development"
});

Переменные окружения

Переменная	Описание	Обязательно
INTEG_API_URL	URL Integ API	Нет
INTEG_ACCESS_TOKEN	Access Token	Да

API Reference

Классы

Client

Основной класс для работы с пакетом.

class Client {
	constructor(options: ClientOptions);

	// Методы
	async connect(): Promise<void>;
	async disconnect(): Promise<void>;
	async send(data: SendData): Promise<SendResult>;
}

Пример:

const client = new Client({ accessToken: "token" });

await client.connect();
const result = await client.send({ message: "Hello" });
await client.disconnect();

Функции

createClient(options)

Фабрика для создания клиента.

function createClient(options: ClientOptions): Client;

Параметры:

Параметр	Тип	Описание
options	ClientOptions	Опции клиента

Возвращает: Client

Пример:

const client = createClient({
	accessToken: "token",
	timeout: 10000
});

validateConfig(config)

Валидация конфигурации.

function validateConfig(config: unknown): config is ValidConfig;

Пример:

const config = { accessToken: "token" };

if (validateConfig(config)) {
	const client = createClient(config);
}

Типы

ClientOptions

interface ClientOptions {
	accessToken: string;
	baseUrl?: string;
	timeout?: number;
	retries?: number;
	debug?: boolean;
}

SendData

interface SendData {
	message: string;
	metadata?: Record<string, unknown>;
}

SendResult

interface SendResult {
	success: boolean;
	id: string;
	timestamp: Date;
}

Enums

Status

enum Status {
	Pending = "pending",
	Processing = "processing",
	Completed = "completed",
	Failed = "failed"
}

Константы

export const DEFAULT_TIMEOUT = 5000;
export const DEFAULT_RETRIES = 3;
export const DEFAULT_BASE_URL = "http://localhost:3000/api";

Примеры использования

Базовый пример

import { createClient } from "@integ/package-name";

async function main() {
	const client = createClient({
		accessToken: process.env.TOKEN!
	});

	const result = await client.send({
		message: "Hello, World!"
	});

	console.log("Sent:", result.id);
}

main().catch(console.error);

С обработкой ошибок

import { createClient, PackageError } from "@integ/package-name";

async function sendWithRetry(message: string) {
	const client = createClient({
		accessToken: process.env.TOKEN!,
		retries: 5
	});

	try {
		return await client.send({ message });
	} catch (error) {
		if (error instanceof PackageError) {
			console.error("Package error:", error.code, error.message);

			if (error.code === "RATE_LIMITED") {
				// Подождать и повторить
				await new Promise((r) => setTimeout(r, 1000));
				return await client.send({ message });
			}
		}
		throw error;
	}
}

С TypeScript

import { createClient, SendData, SendResult, ClientOptions } from "@integ/package-name";

const options: ClientOptions = {
	accessToken: process.env.TOKEN!,
	timeout: 10000
};

const client = createClient(options);

async function sendMessage(data: SendData): Promise<SendResult> {
	return client.send(data);
}

// Использование
const result = await sendMessage({
	message: "Typed message",
	metadata: { source: "example" }
});

В NestJS

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
import { createClient, Client } from "@integ/package-name";

@Injectable()
export class IntegService implements OnModuleInit, OnModuleDestroy {
	private client: Client;

	async onModuleInit() {
		this.client = createClient({
			accessToken: process.env.TOKEN!
		});
		await this.client.connect();
	}

	async onModuleDestroy() {
		await this.client.disconnect();
	}

	async send(message: string) {
		return this.client.send({ message });
	}
}

Обработка ошибок

Типы ошибок

import { PackageError, NetworkError, ValidationError } from "@integ/package-name";

try {
	await client.send({ message: "" });
} catch (error) {
	if (error instanceof ValidationError) {
		console.error("Invalid data:", error.details);
	} else if (error instanceof NetworkError) {
		console.error("Network issue:", error.message);
	} else if (error instanceof PackageError) {
		console.error("Package error:", error.code);
	}
}

Коды ошибок

Код	Описание
UNAUTHORIZED	Неверный access token
RATE_LIMITED	Превышен лимит запросов
TIMEOUT	Таймаут запроса
NETWORK_ERROR	Сетевая ошибка
INVALID_DATA	Неверные входные данные

Миграция

С версии 1.x на 2.x

// v1.x
import Package from "@integ/package-name";
const pkg = new Package({ token: "xxx" });

// v2.x
import { createClient } from "@integ/package-name";
const client = createClient({ accessToken: "xxx" });

Основные изменения:

• token → accessToken
• Default export → Named export createClient
• Package → Client

Changelog

2.0.0 (2024-XX-XX)

Breaking Changes:

• Renamed token to accessToken
• Changed to named exports

Features:

• Added TypeScript 5 support
• Added retry logic

1.1.0 (2024-XX-XX)

• Added debug option
• Fixed timeout handling

1.0.0 (2024-XX-XX)

• Initial release

Troubleshooting

Cannot find module

Error: Cannot find module '@integ/package-name'

Решение:

npm install @integ/package-name

Type errors with TypeScript < 5

error TS2307: Cannot find module '@integ/package-name'

Решение: Обновите TypeScript до версии 5.0+

npm install typescript@latest

UNAUTHORIZED error

PackageError: UNAUTHORIZED - Invalid access token

Решение:

1. Проверьте что accessToken установлен
2. Проверьте что токен не истёк
3. Получите новый токен через API

Связанные документы

• Integ API Documentation
• Access Tokens
• GitHub Repository
• npm Package