@kravets/t-kassa-api@0.1.1

Built and signed on GitHub Actions

Built and signed on GitHub Actions

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
# t-kassa-api

[![npm](https://img.shields.io/npm/v/t-kassa-api?logo=npm&style=flat&labelColor=000&color=3b82f6)](https://www.npmjs.org/package/t-kassa-api)
[![JSR](https://jsr.io/badges/@kravets/t-kassa-api)](https://jsr.io/@kravets/t-kassa-api)
[![JSR Score](https://jsr.io/badges/@kravets/t-kassa-api/score)](https://jsr.io/@kravets/t-kassa-api)

</div>

Библиотека для взаимодействия с [API Т-Кассы](https://www.tbank.ru/kassa/dev/payments/index.html).

```ts
import { TKassa } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {
    server: "https://rest-api-test.tinkoff.ru",
});

const result = await ткасса.init({
    Amount: 1000,
    OrderId: "12",
});

console.log(result);
```

[API Reference](https://jsr.io/@kravets/t-kassa-api/doc)

### Фичи

-   Генерируется исходя из **OpenAPI** спецификации
-   Очень удобная работа с нотификацией (webhook) с умными фильтрами
-   Имеет в себе [webhook адаптеры для самых популярных фреймворков](#поддерживаемые-webhook-адаптеры)
-   Удобна и для [нескольких касс](#режим-мульти-кассы)
-   Отличная документация кода с помощью **JSDoc** (сгенерировано из **OpenAPI**)
-   Современная и с **умнейшими** типами
-   0 зависимостей
-   Берёт работу с [подписью запроса](https://www.tbank.ru/kassa/dev/payments/index.html#section/Podpis-zaprosa) на себя
-   [Есть на JSR](https://jsr.io/@kravets/t-kassa-api)

### Webhook

Пример использования webhook с фреймворком [Hono](https://hono.dev/)

```ts
import { Hono } from "hono";
import { TKassa, webhookHandler, filters } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD);

ткасса.on(
    filters.and(
        filters.equal("Status", "SUCCESS"),
        filters.notNullable("RebillId")
    ),
    (context) => {
        // при этом типы понимают фильтры
    }
);

const app = new Hono();

app.get("/", webhookHandler("hono"));
```

### Поддерживаемые webhook адаптеры

-   [Elysia](https://elysiajs.com/)
-   [Fastify](https://fastify.dev/)
-   [Hono](https://hono.dev/)
-   [Express](https://expressjs.com/)
-   [Koa](https://koajs.com/)
-   [node:http](https://nodejs.org/api/http.html)
-   [Bun.serve](https://bun.sh/docs/api/http)
-   [std/http (Deno.serve)](https://docs.deno.com/runtime/manual/runtime/http_server_apis#http-server-apis)

или любой другой фреймворк

```ts
// a non-existing framework for the example
import { App } from "some-http-framework";
import { TKassa } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {
    server: "https://rest-api-test.tinkoff.ru",
});

const app = new App().post("/t-kassa", async (req) => {
    // req.body must be json equivalent to Webhook notification body
    await ткасса.emit(req.body);
});

app.listen(80);
```

### Режим мульти-кассы

Не всегда бывает удобным передача параметров одной кассы в конструктор класса, поэтому и появился режим мульти-кассы. Он позволяет вам не указывать `TerminalKey` и `Password`.

```ts
import { TKassa } from "t-kassa-api";

const ткасса = new TKassa();

const result = await ткасса.init({
    Amount: 1000,
    OrderId: "12",
    TerminalKey: "12312sf",
    Password: "123123231",
});

console.log(result);
```

И как вы можете заметить, теперь требуется указывать `TerminalKey` и `Password` в теле запроса. И в типах это тоже выражено! Магия? Не иначе.

Но как тогда получать webhook события? (нотификацию)

Для этого вам понадобится указать функцию первым аргументом конструктора.

```ts
import { TKassa } from "t-kassa-api";

const ткасса = new TKassa((body) => {
    const [kassa] = await db
        .select()
        .from(kassaTable)
        .where(eq(kassaTable.terminalKey, body.TerminalKey));

    if (!kassa) throw new Error("Касса не найдена");

    return {
        Password: kassa.password,
        custom: { kassa },
    };
});

ткасса.on(
    filters.and(
        filters.equal("Status", "SUCCESS"),
        filters.notNullable("RebillId")
    ),
    (context, { kassa }) => {
        // и тут появляется вторым аргументов переданное вами значение в custom
    }
);
```

И типы опять же совсем не глупы и делают вам благое дело, указывая верный путь.

### TODO:

-   поддержать `application/x-www-form-urlencoded`