feat(organizations): migrate source storage to polymorphic records

2026-05-19 10:23:53 +02:00
parent 19a7d5a91c
commit 4ca2fa25d5
44 changed files with 7129 additions and 1551 deletions
--- a/ts_client/.gitignore
+++ b/ts_client/.gitignore
@@ -0,0 +1,2 @@
+dist/
+node_modules/
--- a/ts_client/README.md
+++ b/ts_client/README.md
@@ -0,0 +1,192 @@
+# TypeScript-клиент API организаций Mostovik
+
+Клиент покрывает два endpoint API v2:
+
+- `GET /api/v2/organizations/` — список организаций.
+- `GET /api/v2/organizations/{uid}/` — карточка одной организации.
+
+Пакет не имеет runtime-зависимостей и использует `fetch`. В `settings.dev` backend открывает эти endpoint без JWT, в остальных окружениях можно передать `accessToken` или свои headers.
+
+```ts
+import { MostovikOrganizationsClient } from "@mostovik/organizations-api-client";
+
+const client = new MostovikOrganizationsClient({
+  baseUrl: "https://backend.example.com",
+  accessToken: "<jwt>",
+});
+
+const page = await client.listOrganizations({
+  page: 1,
+  page_size: 20,
+  search: "мост",
+  has_registry: true,
+  has_industrial: true,
+  data: ["industrial", "fns_reports"],
+});
+
+const item = await client.getOrganization(page.data[0].uid, {
+  data_sources: ["industrial", "fns_reports"],
+});
+```
+
+## Методы
+
+### `listOrganizations(params?, options?)`
+
+Вызывает `GET /api/v2/organizations/`.
+
+Возвращает пагинированный ответ:
+
+```ts
+{
+  success: true,
+  data: Organization[],
+  errors: null,
+  meta: {
+    pagination: {
+      page: number,
+      page_size: number,
+      total_count: number,
+      total_pages: number,
+      has_next: boolean,
+      has_previous: boolean,
+    },
+  },
+}
+```
+
+Важно: backend по умолчанию применяет `has_registry=true` для list endpoint, если параметр `has_registry` не передан. Чтобы получить организации без активного участия в реестрах, передайте `has_registry: false`.
+
+### `getOrganization(uid, params?, options?)`
+
+Вызывает `GET /api/v2/organizations/{uid}/`.
+
+Возвращает сам объект `Organization`, без wrapper `success/data/meta`.
+
+## Параметры списка
+
+| Параметр | Тип | Назначение |
+| --- | --- | --- |
+| `page` | `number` | Номер страницы пагинации. Backend default: `1`. |
+| `page_size` | `number` | Размер страницы. Backend default: `20`, максимум `100`. |
+| `search` | `string` | Поиск по наименованию, ИНН, КПП, ОГРН и ОГРИП. |
+| `ordering` | `OrganizationOrdering` | Сортировка по `uid`, `name`, `inn`, `kpp`, `ogrn`, `ogrip`; префикс `-` включает обратный порядок, например `-name`. |
+| `name` | `string` | Фильтр по части полного наименования организации. |
+| `inn` | `string` | Точный фильтр по ИНН. |
+| `kpp` | `string` | Точный фильтр по КПП. |
+| `ogrn` | `string` | Точный фильтр по ОГРН. |
+| `ogrip` | `string` | Точный фильтр по ОГРИП. |
+| `registry` | `string` | UUID реестра. Возвращает организации с активным участием в этом реестре. |
+| `registry_name` | `string` | Фильтр по части наименования реестра. |
+| `has_registry` | `boolean` | Фильтр наличия активного участия в любом реестре. |
+| `has_industrial` | `boolean` | Наличие данных источника `industrial`. |
+| `has_industrial_products` | `boolean` | Наличие данных источника `industrial_products`. |
+| `has_manufactures` | `boolean` | Наличие данных источника `manufactures`. |
+| `has_inspections` | `boolean` | Наличие данных источника `inspections`. |
+| `has_procurements` | `boolean` | Наличие данных источника `procurements`. |
+| `has_procurements_44fz` | `boolean` | Наличие данных источника `procurements_44fz`. |
+| `has_procurements_223fz` | `boolean` | Наличие данных источника `procurements_223fz`. |
+| `has_contracts` | `boolean` | Наличие данных источника `contracts`. |
+| `has_unfair_suppliers` | `boolean` | Наличие данных источника `unfair_suppliers`. |
+| `has_fas_goz` | `boolean` | Наличие данных источника `fas_goz`. |
+| `has_arbitration` | `boolean` | Наличие данных источника `arbitration`. |
+| `has_fedresurs_bankruptcy` | `boolean` | Наличие данных источника `fedresurs_bankruptcy`. |
+| `has_fstec` | `boolean` | Наличие данных источника `fstec`. |
+| `has_vacancies` | `boolean` | Наличие данных публичного источника API v2 `vacancies`. Внутренний backend source — `trudvsem`. |
+| `has_trudvsem` | `boolean` | Deprecated alias backend для `has_vacancies`; оставлен в типах, но новый код должен использовать `has_vacancies`. |
+| `has_fns_reports` | `boolean` | Наличие данных источника `fns_reports`. |
+| `data` | `OrganizationDataSource \| OrganizationDataSource[]` | Вернуть в блоке `data` только указанные источники. |
+| `data_sources` | `OrganizationDataSource \| OrganizationDataSource[]` | Alias для `data`. |
+| `exclude_data` | `OrganizationDataSource \| OrganizationDataSource[]` | Исключить указанные источники из блока `data`. |
+| `exclude_data_sources` | `OrganizationDataSource \| OrganizationDataSource[]` | Alias для `exclude_data`. |
+
+## Параметры карточки
+
+`getOrganization(uid, params)` принимает path-параметр `uid` и параметры управления блоком `data`:
+
+| Параметр | Тип | Назначение |
+| --- | --- | --- |
+| `uid` | `string` | UID организации в path: `/api/v2/organizations/{uid}/`. |
+| `data` | `OrganizationDataSource \| OrganizationDataSource[]` | Вернуть в блоке `data` только указанные источники. |
+| `data_sources` | `OrganizationDataSource \| OrganizationDataSource[]` | Alias для `data`. |
+| `exclude_data` | `OrganizationDataSource \| OrganizationDataSource[]` | Исключить указанные источники из блока `data`. |
+| `exclude_data_sources` | `OrganizationDataSource \| OrganizationDataSource[]` | Alias для `exclude_data`. |
+
+Backend также принимает CSV-строки для `data`/`exclude_data`, но в клиенте лучше передавать массив: так TypeScript проверит допустимые source keys.
+
+## Источники данных
+
+Допустимые публичные source keys API v2:
+
+- `arbitration`
+- `contracts`
+- `fas_goz`
+- `fedresurs_bankruptcy`
+- `fns_reports`
+- `fstec`
+- `industrial`
+- `industrial_products`
+- `inspections`
+- `manufactures`
+- `procurements`
+- `procurements_44fz`
+- `procurements_223fz`
+- `unfair_suppliers`
+- `vacancies`
+
+Публичный ключ для Работа России — `vacancies`. Параметры `data=trudvsem` и `data_sources=trudvsem` backend API v2 отклоняет.
+
+## Структуры ответа
+
+`Organization` содержит:
+
+- `uid`, `name`, `normalized_name`, `inn`, `kpp`, `ogrn`, `ogrip`
+- `registries` — активные реестры организации: `{ id, name }[]`
+- `data_sources` — краткая сводка непустых источников: `{ source, count }[]`
+- `data` — объект, где ключи являются source keys, а значения — массивы записей источников
+
+В `types.ts` описаны структуры всех возвращаемых блоков `data`:
+
+- `IndustrialCertificateRecord` для `industrial`
+- `IndustrialProductRecord` для `industrial_products`
+- `ManufacturerRecord` для `manufactures`
+- `InspectionRecord` для `inspections`
+- `ProcurementRecord` для `procurements`
+- `GenericOrganizationSourceRecord` для `procurements_44fz`, `procurements_223fz`, `contracts`, `unfair_suppliers`, `fas_goz`, `arbitration`, `fedresurs_bankruptcy`, `fstec`, `vacancies`
+- `FinancialReportRecord` и `FinancialReportLineValue` для `fns_reports`
+
+Для `GenericOrganizationSourceRecord.payload` используется отдельный тип `GenericSourcePayload`. Это JSON-object, потому что backend сохраняет в этом поле исходный нормализованный документ внешнего generic-источника как `dict`.
+
+## Ошибки
+
+Для HTTP-ответов вне диапазона `2xx` клиент бросает `ApiClientError`:
+
+```ts
+import { ApiClientError } from "@mostovik/organizations-api-client";
+
+try {
+  await client.getOrganization(uid, { data: ["industrial"] });
+} catch (error) {
+  if (error instanceof ApiClientError) {
+    console.log(error.status);
+    console.log(error.payload);
+  }
+}
+```
+
+`ApiClientError.payload` типизирован как `ApiErrorPayload`:
+
+```ts
+{
+  success: false,
+  data: null,
+  errors: Array<{
+    code: string,
+    message: string,
+    details?: JsonObject,
+  }>,
+  meta: {
+    request_id?: string,
+  } | null,
+}
+```
--- a/ts_client/package.json
+++ b/ts_client/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@mostovik/organizations-api-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for Mostovik organizations API v2",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test dist/test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typescript": "^5.9.3"
+  }
+}
--- a/ts_client/src/client.ts
+++ b/ts_client/src/client.ts
@@ -0,0 +1,257 @@
+import type {
+  ApiErrorPayload,
+  Organization,
+  OrganizationDetailParams,
+  OrganizationListParams,
+  OrganizationListResponse,
+  QueryListValue,
+  JsonValue,
+} from "./types.js";
+
+export type FetchLike = (
+  input: RequestInfo,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface MostovikOrganizationsClientOptions {
+  baseUrl: string | URL;
+  fetch?: FetchLike;
+  headers?: HeadersInit;
+  accessToken?: string;
+}
+
+export interface ApiRequestOptions {
+  headers?: HeadersInit;
+  signal?: AbortSignal;
+}
+
+export class ApiClientError extends Error {
+  readonly status: number;
+  readonly payload: ApiErrorPayload;
+
+  constructor(message: string, status: number, payload: ApiErrorPayload) {
+    super(message);
+    this.name = "ApiClientError";
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+type QueryParamValue = string | number | boolean | null | undefined;
+type QueryParam = QueryParamValue | readonly QueryParamValue[];
+type QueryParams = Record<string, QueryParam>;
+
+export class MostovikOrganizationsClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly defaultHeaders: HeadersInit | undefined;
+  private readonly accessToken: string | undefined;
+
+  constructor(options: MostovikOrganizationsClientOptions) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.fetchImpl = options.fetch ?? defaultFetch();
+    this.defaultHeaders = options.headers;
+    this.accessToken = options.accessToken;
+  }
+
+  listOrganizations(
+    params: OrganizationListParams = {},
+    options: ApiRequestOptions = {},
+  ): Promise<OrganizationListResponse> {
+    return this.request<OrganizationListResponse>(
+      "api/v2/organizations/",
+      params as QueryParams,
+      options,
+    );
+  }
+
+  getOrganization(
+    uid: string,
+    params: OrganizationDetailParams = {},
+    options: ApiRequestOptions = {},
+  ): Promise<Organization> {
+    return this.request<Organization>(
+      `api/v2/organizations/${encodeURIComponent(uid)}/`,
+      params as QueryParams,
+      options,
+    );
+  }
+
+  private async request<T>(
+    path: string,
+    params: QueryParams,
+    options: ApiRequestOptions,
+  ): Promise<T> {
+    const url = this.buildUrl(path, params);
+    const init: RequestInit = {
+      method: "GET",
+      headers: this.buildHeaders(options.headers),
+    };
+    if (options.signal !== undefined) {
+      init.signal = options.signal;
+    }
+
+    const response = await this.fetchImpl(url.toString(), init);
+    const payload = await parseResponsePayload(response);
+
+    if (!response.ok) {
+      const errorPayload = toApiErrorPayload(payload, response.status);
+      throw new ApiClientError(
+        `GET ${url.pathname} failed with HTTP ${response.status}`,
+        response.status,
+        errorPayload,
+      );
+    }
+
+    return payload as T;
+  }
+
+  private buildUrl(path: string, params: QueryParams): URL {
+    const url = new URL(path, this.baseUrl);
+    appendQueryParams(url, params);
+    return url;
+  }
+
+  private buildHeaders(requestHeaders?: HeadersInit): Headers {
+    const headers = new Headers(this.defaultHeaders);
+    headers.set("Accept", "application/json");
+
+    if (this.accessToken !== undefined && !headers.has("Authorization")) {
+      headers.set("Authorization", `Bearer ${this.accessToken}`);
+    }
+
+    if (requestHeaders !== undefined) {
+      new Headers(requestHeaders).forEach((value, key) => {
+        headers.set(key, value);
+      });
+    }
+
+    return headers;
+  }
+}
+
+function normalizeBaseUrl(baseUrl: string | URL): string {
+  const value = String(baseUrl);
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function defaultFetch(): FetchLike {
+  if (typeof globalThis.fetch !== "function") {
+    throw new Error(
+      "No fetch implementation is available. Pass fetch in client options.",
+    );
+  }
+
+  return (input, init) => globalThis.fetch(input, init);
+}
+
+function appendQueryParams(url: URL, params: QueryParams): void {
+  Object.entries(params).forEach(([key, value]) => {
+    if (isQueryParamArray(value)) {
+      value.forEach((item) => appendQueryParam(url, key, item));
+      return;
+    }
+
+    appendQueryParam(url, key, value);
+  });
+}
+
+function isQueryParamArray(value: QueryParam): value is readonly QueryParamValue[] {
+  return Array.isArray(value);
+}
+
+function appendQueryParam(url: URL, key: string, value: QueryParamValue): void {
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  url.searchParams.append(key, String(value));
+}
+
+async function parseResponsePayload(response: Response): Promise<JsonValue | null> {
+  const contentType = response.headers.get("content-type") ?? "";
+  const body = await response.text();
+  if (body === "") {
+    return null;
+  }
+
+  if (contentType.includes("application/json")) {
+    return JSON.parse(body) as JsonValue;
+  }
+
+  try {
+    return JSON.parse(body) as JsonValue;
+  } catch {
+    return body;
+  }
+}
+
+function toApiErrorPayload(
+  payload: JsonValue | null,
+  status: number,
+): ApiErrorPayload {
+  if (
+    isJsonObject(payload) &&
+    payload.success === false &&
+    payload.data === null &&
+    Array.isArray(payload.errors)
+  ) {
+    const meta = payload.meta ?? null;
+    return {
+      success: false,
+      data: null,
+      errors: payload.errors.map(toApiErrorDetail),
+      meta: isJsonObject(meta) ? meta : null,
+    };
+  }
+
+  return {
+    success: false,
+    data: null,
+    errors: [
+      {
+        code: `http_${status}`,
+        message: "HTTP request failed",
+        details: {
+          payload,
+        },
+      },
+    ],
+    meta: null,
+  };
+}
+
+function toApiErrorDetail(value: JsonValue): {
+  code: string;
+  message: string;
+  details?: { readonly [key: string]: JsonValue };
+} {
+  if (isJsonObject(value)) {
+    const details = value.details ?? null;
+    const code = typeof value.code === "string" ? value.code : "error";
+    const message =
+      typeof value.message === "string" ? value.message : JSON.stringify(value);
+    if (isJsonObject(details)) {
+      return {
+        code,
+        message,
+        details,
+      };
+    }
+    return {
+      code,
+      message,
+    };
+  }
+
+  return {
+    code: "error",
+    message: String(value),
+  };
+}
+
+function isJsonObject(value: JsonValue | null): value is {
+  readonly [key: string]: JsonValue;
+} {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
--- a/ts_client/src/index.ts
+++ b/ts_client/src/index.ts
@@ -0,0 +1,8 @@
+export {
+  ApiClientError,
+  MostovikOrganizationsClient,
+  type ApiRequestOptions,
+  type FetchLike,
+  type MostovikOrganizationsClientOptions,
+} from "./client.js";
+export * from "./types.js";
--- a/ts_client/src/types.ts
+++ b/ts_client/src/types.ts
@@ -0,0 +1,343 @@
+export type UuidString = string;
+export type IsoDateString = string;
+export type IsoDateTimeString = string;
+export type DecimalString = string;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | JsonObject;
+export type JsonObject = { readonly [key: string]: JsonValue };
+export type GenericSourcePayload = JsonObject;
+
+export interface ApiErrorPayload {
+  success: false;
+  data: null;
+  errors: ApiErrorDetail[];
+  meta: ApiErrorMeta | null;
+}
+
+export interface ApiErrorDetail {
+  code: string;
+  message: string;
+  details?: JsonObject;
+}
+
+export interface ApiErrorMeta {
+  request_id?: string;
+}
+
+export const ORGANIZATION_DATA_SOURCES = [
+  "arbitration",
+  "contracts",
+  "fas_goz",
+  "fedresurs_bankruptcy",
+  "fns_reports",
+  "fstec",
+  "industrial",
+  "industrial_products",
+  "inspections",
+  "manufactures",
+  "procurements",
+  "procurements_44fz",
+  "procurements_223fz",
+  "unfair_suppliers",
+  "vacancies",
+] as const;
+
+export type OrganizationDataSource = (typeof ORGANIZATION_DATA_SOURCES)[number];
+
+export type OrganizationGenericInternalSource =
+  | "arbitration"
+  | "contracts"
+  | "fas_goz"
+  | "fedresurs_bankruptcy"
+  | "fstec"
+  | "procurements_44fz"
+  | "procurements_223fz"
+  | "trudvsem"
+  | "unfair_suppliers";
+
+export type OrganizationOrderingField =
+  | "uid"
+  | "name"
+  | "inn"
+  | "kpp"
+  | "ogrn"
+  | "ogrip";
+
+export type OrganizationOrdering =
+  | OrganizationOrderingField
+  | `-${OrganizationOrderingField}`;
+
+export type QueryListValue<T> = T | readonly T[];
+
+export interface OrganizationDataSelectionParams {
+  /** Ограничивает блок `data` указанными источниками. В клиенте лучше передавать массив вместо CSV-строки. */
+  data?: QueryListValue<OrganizationDataSource>;
+  /** Alias для `data`: явно задает набор источников, которые нужно вернуть в `data`. */
+  data_sources?: QueryListValue<OrganizationDataSource>;
+  /** Исключает указанные источники из блока `data`. */
+  exclude_data?: QueryListValue<OrganizationDataSource>;
+  /** Alias для `exclude_data`: явно задает набор источников, которые нужно исключить из `data`. */
+  exclude_data_sources?: QueryListValue<OrganizationDataSource>;
+}
+
+export interface OrganizationListParams extends OrganizationDataSelectionParams {
+  /** Номер страницы пагинации. Backend default: 1. */
+  page?: number;
+  /** Размер страницы. Backend default: 20, максимум 100. */
+  page_size?: number;
+  /** Поиск по наименованию, ИНН, КПП, ОГРН и ОГРИП. */
+  search?: string;
+  /** Сортировка по `uid`, `name`, `inn`, `kpp`, `ogrn`, `ogrip`; префикс `-` включает обратный порядок. */
+  ordering?: OrganizationOrdering;
+  /** Фильтр по части полного наименования организации. */
+  name?: string;
+  /** Точный фильтр по ИНН. */
+  inn?: string;
+  /** Точный фильтр по КПП. */
+  kpp?: string;
+  /** Точный фильтр по ОГРН. */
+  ogrn?: string;
+  /** Точный фильтр по ОГРИП. */
+  ogrip?: string;
+  /** UUID реестра: возвращает организации с активным участием в этом реестре. */
+  registry?: UuidString;
+  /** Фильтр по части наименования реестра. */
+  registry_name?: string;
+  /** Наличие активного участия в любом реестре. Для list backend по умолчанию применяет `true`, если параметр не передан. */
+  has_registry?: boolean;
+  /** Наличие данных источника `industrial`. */
+  has_industrial?: boolean;
+  /** Наличие данных источника `industrial_products`. */
+  has_industrial_products?: boolean;
+  /** Наличие данных источника `manufactures`. */
+  has_manufactures?: boolean;
+  /** Наличие данных источника `inspections`. */
+  has_inspections?: boolean;
+  /** Наличие данных источника `procurements`. */
+  has_procurements?: boolean;
+  /** Наличие данных источника `procurements_44fz`. */
+  has_procurements_44fz?: boolean;
+  /** Наличие данных источника `procurements_223fz`. */
+  has_procurements_223fz?: boolean;
+  /** Наличие данных источника `contracts`. */
+  has_contracts?: boolean;
+  /** Наличие данных источника `unfair_suppliers`. */
+  has_unfair_suppliers?: boolean;
+  /** Наличие данных источника `fas_goz`. */
+  has_fas_goz?: boolean;
+  /** Наличие данных источника `arbitration`. */
+  has_arbitration?: boolean;
+  /** Наличие данных источника `fedresurs_bankruptcy`. */
+  has_fedresurs_bankruptcy?: boolean;
+  /** Наличие данных источника `fstec`. */
+  has_fstec?: boolean;
+  /** Наличие данных публичного API v2 источника `vacancies` (внутренний backend source: `trudvsem`). */
+  has_vacancies?: boolean;
+  /** @deprecated Внутренний alias backend для `has_vacancies`; используйте `has_vacancies`. */
+  has_trudvsem?: boolean;
+  /** Наличие данных источника `fns_reports`. */
+  has_fns_reports?: boolean;
+}
+
+export interface OrganizationDetailParams extends OrganizationDataSelectionParams {}
+
+export interface OrganizationListResponse {
+  success: true;
+  data: Organization[];
+  errors: null;
+  meta: {
+    pagination: PagePagination;
+  };
+}
+
+export interface PagePagination {
+  page: number;
+  page_size: number;
+  total_count: number;
+  total_pages: number;
+  has_next: boolean;
+  has_previous: boolean;
+}
+
+export interface Organization {
+  uid: UuidString;
+  name: string;
+  normalized_name: string;
+  inn: string;
+  kpp: string;
+  ogrn: string;
+  ogrip: string;
+  data: OrganizationData;
+  data_sources: OrganizationDataSourceSummary[];
+  registries: OrganizationRegistry[];
+}
+
+export interface OrganizationRegistry {
+  id: UuidString;
+  name: string;
+}
+
+export interface OrganizationDataSourceSummary {
+  source: OrganizationDataSource;
+  count: number;
+}
+
+export type OrganizationData = Partial<OrganizationDataBySource>;
+
+export interface OrganizationDataBySource {
+  arbitration: GenericOrganizationSourceRecord[];
+  contracts: GenericOrganizationSourceRecord[];
+  fas_goz: GenericOrganizationSourceRecord[];
+  fedresurs_bankruptcy: GenericOrganizationSourceRecord[];
+  fns_reports: FinancialReportRecord[];
+  fstec: GenericOrganizationSourceRecord[];
+  industrial: IndustrialCertificateRecord[];
+  industrial_products: IndustrialProductRecord[];
+  inspections: InspectionRecord[];
+  manufactures: ManufacturerRecord[];
+  procurements: ProcurementRecord[];
+  procurements_44fz: GenericOrganizationSourceRecord[];
+  procurements_223fz: GenericOrganizationSourceRecord[];
+  unfair_suppliers: GenericOrganizationSourceRecord[];
+  vacancies: GenericOrganizationSourceRecord[];
+}
+
+export interface OrganizationTimedRecord {
+  id: number;
+  load_batch: number;
+  registry_organization: number | null;
+  created_at: IsoDateTimeString;
+  updated_at: IsoDateTimeString;
+}
+
+export interface IndustrialCertificateRecord extends OrganizationTimedRecord {
+  issue_date: string;
+  issue_date_normalized: IsoDateString | null;
+  certificate_number: string;
+  expiry_date: string;
+  expiry_date_normalized: IsoDateString | null;
+  certificate_file_url: string;
+  organisation_name: string;
+  inn: string;
+  ogrn: string;
+}
+
+export interface IndustrialProductRecord extends OrganizationTimedRecord {
+  full_organisation_name: string;
+  ogrn: string;
+  inn: string;
+  registry_number: string;
+  product_name: string;
+  product_model: string;
+  okpd2_code: string;
+  tnved_code: string;
+  regulatory_document: string;
+}
+
+export interface ManufacturerRecord extends OrganizationTimedRecord {
+  full_legal_name: string;
+  inn: string;
+  ogrn: string;
+  address: string;
+}
+
+export interface InspectionRecord extends OrganizationTimedRecord {
+  registration_number: string;
+  inn: string;
+  ogrn: string;
+  organisation_name: string;
+  control_authority: string;
+  inspection_type: string;
+  inspection_form: string;
+  start_date: string;
+  start_date_normalized: IsoDateString | null;
+  end_date: string;
+  end_date_normalized: IsoDateString | null;
+  status: string;
+  legal_basis: string;
+  result: string;
+  is_federal_law_248: boolean;
+  data_year: number | null;
+  data_month: number | null;
+}
+
+export interface ProcurementRecord extends OrganizationTimedRecord {
+  purchase_number: string;
+  purchase_name: string;
+  customer_inn: string;
+  customer_kpp: string;
+  customer_ogrn: string;
+  customer_name: string;
+  max_price: string;
+  max_price_amount: DecimalString | null;
+  currency_code: string;
+  placement_method: string;
+  publish_date: string;
+  publish_date_normalized: IsoDateString | null;
+  end_date: string;
+  end_date_normalized: IsoDateString | null;
+  status: string;
+  law_type: string;
+  purchase_object_info: string;
+  href: string;
+  region_code: string;
+  data_year: number | null;
+  data_month: number | null;
+}
+
+export interface GenericOrganizationSourceRecord extends OrganizationTimedRecord {
+  source: OrganizationGenericInternalSource;
+  external_id: string;
+  inn: string;
+  ogrn: string;
+  organisation_name: string;
+  title: string;
+  record_date: string;
+  amount: DecimalString | null;
+  status: string;
+  url: string;
+  payload: GenericSourcePayload;
+}
+
+export type FinancialReportStatus =
+  | "failed"
+  | "pending"
+  | "processing"
+  | "success";
+
+export type FinancialReportSource = "api" | "file_watch";
+
+export interface FinancialReportRecord {
+  id: number;
+  external_id: string;
+  ogrn: string;
+  registry_organization: number | null;
+  file_name: string;
+  file_hash: string;
+  load_batch: number;
+  status: FinancialReportStatus;
+  source: FinancialReportSource;
+  error_message: string;
+  created_at: IsoDateTimeString;
+  updated_at: IsoDateTimeString;
+  lines_count: number;
+  lines: FinancialReportLinesByYear;
+}
+
+export type FinancialReportSection = "active" | "balance" | "passive" | `form_${string}`;
+
+export type FinancialReportLinesByYear = Record<
+  string,
+  Partial<Record<FinancialReportSection, Record<string, FinancialReportLineValue>>>
+>;
+
+export interface FinancialReportLineValue {
+  form_code: string;
+  name: string;
+  period_start: number | null;
+  period_end: number | null;
+}
--- a/ts_client/test/client.test.ts
+++ b/ts_client/test/client.test.ts
@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MostovikOrganizationsClient,
+  type ApiErrorPayload,
+  type FetchLike,
+  type GenericSourcePayload,
+  type Organization,
+  type OrganizationListResponse,
+} from "../src/index.js";
+
+function jsonResponse(payload: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(payload), {
+    status: init.status ?? 200,
+    headers: {
+      "content-type": "application/json",
+      ...init.headers,
+    },
+  });
+}
+
+test("listOrganizations serializes all supported organization filters", async () => {
+  const calls: RequestInfo[] = [];
+  const fetchImpl: FetchLike = async (input) => {
+    calls.push(input);
+    const payload: OrganizationListResponse = {
+      success: true,
+      data: [],
+      errors: null,
+      meta: {
+        pagination: {
+          page: 2,
+          page_size: 50,
+          total_count: 0,
+          total_pages: 0,
+          has_next: false,
+          has_previous: true,
+        },
+      },
+    };
+    return jsonResponse(payload);
+  };
+  const client = new MostovikOrganizationsClient({
+    baseUrl: "https://api.example.test/",
+    fetch: fetchImpl,
+    headers: { Authorization: "Bearer static-token" },
+  });
+
+  const response = await client.listOrganizations({
+    page: 2,
+    page_size: 50,
+    search: "мост",
+    ordering: "-name",
+    name: "Северный",
+    inn: "7711111111",
+    kpp: "771101001",
+    ogrn: "1027700132111",
+    ogrip: "304500116000157",
+    registry: "8e7a3cb8-6fb2-43a8-b847-62d84ea9f34f",
+    registry_name: "Росатом",
+    has_registry: false,
+    has_industrial: true,
+    has_industrial_products: false,
+    has_manufactures: true,
+    has_inspections: false,
+    has_procurements: true,
+    has_procurements_44fz: false,
+    has_procurements_223fz: true,
+    has_contracts: false,
+    has_unfair_suppliers: true,
+    has_fas_goz: false,
+    has_arbitration: true,
+    has_fedresurs_bankruptcy: false,
+    has_fstec: true,
+    has_vacancies: true,
+    has_trudvsem: false,
+    has_fns_reports: false,
+    data: ["industrial", "fns_reports"],
+    exclude_data_sources: "vacancies",
+  });
+
+  assert.equal(response.success, true);
+  assert.equal(calls.length, 1);
+
+  const url = new URL(String(calls[0]));
+  assert.equal(url.origin, "https://api.example.test");
+  assert.equal(url.pathname, "/api/v2/organizations/");
+  assert.equal(url.searchParams.get("page"), "2");
+  assert.equal(url.searchParams.get("page_size"), "50");
+  assert.equal(url.searchParams.get("ordering"), "-name");
+  assert.equal(url.searchParams.get("has_registry"), "false");
+  assert.deepEqual(url.searchParams.getAll("data"), ["industrial", "fns_reports"]);
+  assert.equal(url.searchParams.get("exclude_data_sources"), "vacancies");
+  assert.equal(url.searchParams.get("has_vacancies"), "true");
+  assert.equal(url.searchParams.get("has_trudvsem"), "false");
+});
+
+test("getOrganization requests detail endpoint and returns typed source data", async () => {
+  const calls: RequestInfo[] = [];
+  const uid = "5dc142b3-dcf4-4b90-807a-a80e883dd05c";
+  const payload: Organization = {
+    uid,
+    name: "ООО \"Данные\"",
+    normalized_name: "ООО \"Данные\"",
+    inn: "7777777777",
+    kpp: "777701001",
+    ogrn: "1027700132777",
+    ogrip: "",
+    registries: [
+      {
+        id: "0b85bf08-c6d9-4c07-98c3-a057630e3a35",
+        name: "Росатом ГОЗ",
+      },
+    ],
+    data_sources: [
+      {
+        source: "industrial",
+        count: 1,
+      },
+      {
+        source: "fns_reports",
+        count: 1,
+      },
+    ],
+    data: {
+      industrial: [
+        {
+          id: 1,
+          load_batch: 10,
+          issue_date: "01.01.2025",
+          issue_date_normalized: "2025-01-01",
+          certificate_number: "CERT-1",
+          expiry_date: "",
+          expiry_date_normalized: null,
+          certificate_file_url: "https://example.test/cert.pdf",
+          organisation_name: "ООО \"Данные\"",
+          inn: "7777777777",
+          ogrn: "1027700132777",
+          registry_organization: null,
+          created_at: "2026-05-01T10:00:00Z",
+          updated_at: "2026-05-01T10:00:00Z",
+        },
+      ],
+      fns_reports: [
+        {
+          id: 2,
+          external_id: "fin-1",
+          ogrn: "1027700132777",
+          registry_organization: null,
+          file_name: "fin.xlsx",
+          file_hash: "a".repeat(64),
+          load_batch: 11,
+          status: "success",
+          source: "api",
+          error_message: "",
+          created_at: "2026-05-01T10:00:00Z",
+          updated_at: "2026-05-01T10:00:00Z",
+          lines_count: 1,
+          lines: {
+            "2024": {
+              active: {
+                "1100": {
+                  form_code: "1",
+                  name: "Внеоборотные активы",
+                  period_start: 100,
+                  period_end: 200,
+                },
+              },
+            },
+          },
+        },
+      ],
+    },
+  };
+  const fetchImpl: FetchLike = async (input) => {
+    calls.push(input);
+    return jsonResponse(payload);
+  };
+  const client = new MostovikOrganizationsClient({
+    baseUrl: "https://api.example.test",
+    fetch: fetchImpl,
+  });
+
+  const organization = await client.getOrganization(uid, {
+    data_sources: ["industrial", "fns_reports"],
+  });
+
+  assert.equal(organization.uid, uid);
+  assert.equal(organization.data.industrial?.[0]?.certificate_number, "CERT-1");
+  assert.equal(
+    organization.data.fns_reports?.[0]?.lines["2024"]?.active?.["1100"]?.period_end,
+    200,
+  );
+  const url = new URL(String(calls[0]));
+  assert.equal(url.pathname, `/api/v2/organizations/${uid}/`);
+  assert.deepEqual(url.searchParams.getAll("data_sources"), [
+    "industrial",
+    "fns_reports",
+  ]);
+});
+
+test("throws ApiClientError with status and payload for non-2xx responses", async () => {
+  const errorPayload: ApiErrorPayload = {
+    success: false,
+    data: null,
+    errors: [
+      {
+        code: "validation_error",
+        message: "Validation failed",
+        details: {
+          fields: {
+            data: ["Unknown data source(s): unknown"],
+          },
+        },
+      },
+    ],
+    meta: {
+      request_id: "test-request-id",
+    },
+  };
+  const fetchImpl: FetchLike = async () =>
+    jsonResponse(errorPayload, { status: 400 });
+  const client = new MostovikOrganizationsClient({
+    baseUrl: "https://api.example.test",
+    fetch: fetchImpl,
+  });
+
+  await assert.rejects(
+    () => client.getOrganization("uid", { data: "industrial" }),
+    (error: unknown) => {
+      assert.equal(error instanceof Error, true);
+      assert.equal((error as { name?: string }).name, "ApiClientError");
+      assert.equal((error as { status?: number }).status, 400);
+      assert.deepEqual((error as { payload?: ApiErrorPayload }).payload, errorPayload);
+      return true;
+    },
+  );
+});
+
+test("generic source payload is represented as a typed JSON object", () => {
+  const payload: GenericSourcePayload = {
+    provider: "checko",
+    target: {
+      inn: "7711111199",
+      ogrn: "1027700132199",
+    },
+    suppliers: [
+      {
+        inn: "7722222299",
+        amount: 1000,
+      },
+    ],
+  };
+
+  assert.equal(payload.provider, "checko");
+});
--- a/ts_client/tsconfig.json
+++ b/ts_client/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "rootDir": ".",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}