yclients-api 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/LICENSE +21 -0
- package/README.md +213 -2
- package/README.ru.md +214 -0
- package/dist/client.d.ts +137 -0
- package/dist/client.js +214 -0
- package/dist/errors.d.ts +62 -0
- package/dist/errors.js +101 -0
- package/dist/http.d.ts +75 -0
- package/dist/http.js +208 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +4 -0
- package/dist/pagination.d.ts +27 -0
- package/dist/pagination.js +54 -0
- package/dist/types.d.ts +296 -0
- package/dist/types.js +8 -0
- package/package.json +56 -4
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { Page } from './types.js';
|
|
2
|
+
export interface PaginateOptions {
|
|
3
|
+
/** Items per page. */
|
|
4
|
+
count?: number;
|
|
5
|
+
/** First page to read (1-based). Default `1`. */
|
|
6
|
+
startPage?: number;
|
|
7
|
+
/**
|
|
8
|
+
* Safety limit. When it is reached before the list ends, a
|
|
9
|
+
* `YclientsPaginationError` is thrown instead of returning a truncated list.
|
|
10
|
+
* Default `1000`.
|
|
11
|
+
*/
|
|
12
|
+
maxPages?: number;
|
|
13
|
+
signal?: AbortSignal | undefined;
|
|
14
|
+
}
|
|
15
|
+
export type PageFetcher<T> = (page: number, count: number, signal?: AbortSignal) => Promise<Page<T>>;
|
|
16
|
+
/**
|
|
17
|
+
* Walk a page-numbered YCLIENTS list until it provably ends:
|
|
18
|
+
* - an empty page, or
|
|
19
|
+
* - a page shorter than `count`, or
|
|
20
|
+
* - the number of items read reaches `meta.total_count`.
|
|
21
|
+
*
|
|
22
|
+
* Throws `YclientsPaginationError` if `maxPages` is hit first or if the server
|
|
23
|
+
* returns the same non-empty page twice in a row (a stalled cursor).
|
|
24
|
+
*/
|
|
25
|
+
export declare function paginate<T>(fetchPage: PageFetcher<T>, defaultCount: number, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;
|
|
26
|
+
/** Collect every item of an async iterable into an array. */
|
|
27
|
+
export declare function collect<T>(iterable: AsyncIterable<T>): Promise<T[]>;
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { YclientsPaginationError } from './errors.js';
|
|
2
|
+
/**
|
|
3
|
+
* Walk a page-numbered YCLIENTS list until it provably ends:
|
|
4
|
+
* - an empty page, or
|
|
5
|
+
* - a page shorter than `count`, or
|
|
6
|
+
* - the number of items read reaches `meta.total_count`.
|
|
7
|
+
*
|
|
8
|
+
* Throws `YclientsPaginationError` if `maxPages` is hit first or if the server
|
|
9
|
+
* returns the same non-empty page twice in a row (a stalled cursor).
|
|
10
|
+
*/
|
|
11
|
+
export async function* paginate(fetchPage, defaultCount, options = {}) {
|
|
12
|
+
const count = options.count ?? defaultCount;
|
|
13
|
+
if (!Number.isInteger(count) || count <= 0)
|
|
14
|
+
throw new RangeError('count must be a positive integer');
|
|
15
|
+
const startPage = options.startPage ?? 1;
|
|
16
|
+
const maxPages = options.maxPages ?? 1000;
|
|
17
|
+
let itemsRead = 0;
|
|
18
|
+
let pagesRead = 0;
|
|
19
|
+
let previousFingerprint;
|
|
20
|
+
for (let page = startPage;; page += 1) {
|
|
21
|
+
if (pagesRead >= maxPages) {
|
|
22
|
+
throw new YclientsPaginationError(`Stopped after ${pagesRead} pages without reaching the end of the list (maxPages=${maxPages})`, { pagesRead, itemsRead });
|
|
23
|
+
}
|
|
24
|
+
options.signal?.throwIfAborted();
|
|
25
|
+
const result = await fetchPage(page, count, options.signal);
|
|
26
|
+
pagesRead += 1;
|
|
27
|
+
const items = result.data;
|
|
28
|
+
if (items.length > 0) {
|
|
29
|
+
const fingerprint = JSON.stringify(items);
|
|
30
|
+
if (fingerprint === previousFingerprint) {
|
|
31
|
+
throw new YclientsPaginationError(`Page ${page} repeated the previous page; the list cannot be read completely`, { pagesRead, itemsRead });
|
|
32
|
+
}
|
|
33
|
+
previousFingerprint = fingerprint;
|
|
34
|
+
}
|
|
35
|
+
for (const item of items) {
|
|
36
|
+
itemsRead += 1;
|
|
37
|
+
yield item;
|
|
38
|
+
}
|
|
39
|
+
const total = result.meta.total_count;
|
|
40
|
+
if (items.length === 0)
|
|
41
|
+
return;
|
|
42
|
+
if (items.length < count)
|
|
43
|
+
return;
|
|
44
|
+
if (typeof total === 'number' && Number.isFinite(total) && itemsRead + (startPage - 1) * count >= total)
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
/** Collect every item of an async iterable into an array. */
|
|
49
|
+
export async function collect(iterable) {
|
|
50
|
+
const items = [];
|
|
51
|
+
for await (const item of iterable)
|
|
52
|
+
items.push(item);
|
|
53
|
+
return items;
|
|
54
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Entity shapes returned by the YCLIENTS REST API.
|
|
3
|
+
*
|
|
4
|
+
* YCLIENTS returns many more fields than are listed here and adds new ones over time,
|
|
5
|
+
* so every entity keeps an index signature: listed fields are typed, the rest stay
|
|
6
|
+
* reachable as `unknown`. Fields are optional unless the API reliably sends them.
|
|
7
|
+
*/
|
|
8
|
+
/** Calendar date in `YYYY-MM-DD` format, as YCLIENTS expects in query parameters. */
|
|
9
|
+
export type IsoDate = string;
|
|
10
|
+
/** Numeric IDs are sent as numbers by YCLIENTS; the client also accepts numeric strings. */
|
|
11
|
+
export type Id = number | string;
|
|
12
|
+
/** Standard YCLIENTS response envelope. */
|
|
13
|
+
export interface YclientsEnvelope<T> {
|
|
14
|
+
success: boolean;
|
|
15
|
+
data: T;
|
|
16
|
+
meta?: YclientsMeta;
|
|
17
|
+
[key: string]: unknown;
|
|
18
|
+
}
|
|
19
|
+
export interface YclientsMeta {
|
|
20
|
+
/** Total number of items matching a list request, when the endpoint reports it. */
|
|
21
|
+
total_count?: number;
|
|
22
|
+
message?: string;
|
|
23
|
+
[key: string]: unknown;
|
|
24
|
+
}
|
|
25
|
+
/** One page of a list endpoint. */
|
|
26
|
+
export interface Page<T> {
|
|
27
|
+
data: T[];
|
|
28
|
+
meta: YclientsMeta;
|
|
29
|
+
page: number;
|
|
30
|
+
count: number;
|
|
31
|
+
}
|
|
32
|
+
export interface Company {
|
|
33
|
+
id: number;
|
|
34
|
+
title: string;
|
|
35
|
+
public_title?: string;
|
|
36
|
+
short_descr?: string;
|
|
37
|
+
country_id?: number;
|
|
38
|
+
city_id?: number;
|
|
39
|
+
city?: string;
|
|
40
|
+
timezone?: number;
|
|
41
|
+
timezone_name?: string;
|
|
42
|
+
address?: string;
|
|
43
|
+
coordinate_lat?: number;
|
|
44
|
+
coordinate_lon?: number;
|
|
45
|
+
phone?: string;
|
|
46
|
+
phones?: string[];
|
|
47
|
+
site?: string;
|
|
48
|
+
currency_short_title?: string;
|
|
49
|
+
main_group_id?: number;
|
|
50
|
+
active?: number;
|
|
51
|
+
[key: string]: unknown;
|
|
52
|
+
}
|
|
53
|
+
export interface StaffPosition {
|
|
54
|
+
id: number;
|
|
55
|
+
title: string;
|
|
56
|
+
[key: string]: unknown;
|
|
57
|
+
}
|
|
58
|
+
export interface Staff {
|
|
59
|
+
id: number;
|
|
60
|
+
name: string;
|
|
61
|
+
specialization?: string;
|
|
62
|
+
position?: StaffPosition | [] | null;
|
|
63
|
+
avatar?: string;
|
|
64
|
+
avatar_big?: string;
|
|
65
|
+
rating?: number;
|
|
66
|
+
votes_count?: number;
|
|
67
|
+
bookable?: boolean;
|
|
68
|
+
fired?: number;
|
|
69
|
+
hidden?: number;
|
|
70
|
+
status?: number;
|
|
71
|
+
is_deleted?: boolean;
|
|
72
|
+
user_id?: number | null;
|
|
73
|
+
weight?: number;
|
|
74
|
+
[key: string]: unknown;
|
|
75
|
+
}
|
|
76
|
+
export interface Service {
|
|
77
|
+
id: number;
|
|
78
|
+
title: string;
|
|
79
|
+
category_id?: number;
|
|
80
|
+
price_min?: number;
|
|
81
|
+
price_max?: number;
|
|
82
|
+
discount?: number;
|
|
83
|
+
comment?: string;
|
|
84
|
+
weight?: number;
|
|
85
|
+
active?: number | boolean;
|
|
86
|
+
/** Duration in seconds. */
|
|
87
|
+
duration?: number;
|
|
88
|
+
staff?: Array<{
|
|
89
|
+
id: number;
|
|
90
|
+
seance_length?: number;
|
|
91
|
+
[key: string]: unknown;
|
|
92
|
+
}>;
|
|
93
|
+
[key: string]: unknown;
|
|
94
|
+
}
|
|
95
|
+
export interface RecordService {
|
|
96
|
+
id: number;
|
|
97
|
+
title: string;
|
|
98
|
+
cost?: number;
|
|
99
|
+
cost_to_pay?: number;
|
|
100
|
+
manual_cost?: number;
|
|
101
|
+
first_cost?: number;
|
|
102
|
+
discount?: number;
|
|
103
|
+
amount?: number;
|
|
104
|
+
[key: string]: unknown;
|
|
105
|
+
}
|
|
106
|
+
export interface RecordClient {
|
|
107
|
+
id: number;
|
|
108
|
+
name?: string;
|
|
109
|
+
surname?: string;
|
|
110
|
+
patronymic?: string;
|
|
111
|
+
display_name?: string;
|
|
112
|
+
phone?: string;
|
|
113
|
+
email?: string;
|
|
114
|
+
[key: string]: unknown;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* A booking ("запись").
|
|
118
|
+
* `attendance` / `visit_attendance`: 2 = client confirmed, 1 = client came,
|
|
119
|
+
* 0 = waiting, -1 = client did not come.
|
|
120
|
+
*/
|
|
121
|
+
export interface YclientsRecord {
|
|
122
|
+
id: number;
|
|
123
|
+
company_id: number;
|
|
124
|
+
staff_id: number;
|
|
125
|
+
services?: RecordService[];
|
|
126
|
+
staff?: Partial<Staff>;
|
|
127
|
+
client?: RecordClient | null;
|
|
128
|
+
/** Local date-time of the visit, e.g. `2026-05-01 14:00:00`. */
|
|
129
|
+
date?: string;
|
|
130
|
+
datetime?: string;
|
|
131
|
+
create_date?: string;
|
|
132
|
+
last_change_date?: string;
|
|
133
|
+
comment?: string;
|
|
134
|
+
/** Visit length in seconds. */
|
|
135
|
+
seance_length?: number;
|
|
136
|
+
length?: number;
|
|
137
|
+
attendance?: number;
|
|
138
|
+
visit_attendance?: number;
|
|
139
|
+
confirmed?: number;
|
|
140
|
+
online?: boolean;
|
|
141
|
+
visit_id?: number;
|
|
142
|
+
deleted?: boolean;
|
|
143
|
+
paid_full?: number;
|
|
144
|
+
[key: string]: unknown;
|
|
145
|
+
}
|
|
146
|
+
export interface Client {
|
|
147
|
+
id: number;
|
|
148
|
+
name?: string;
|
|
149
|
+
surname?: string;
|
|
150
|
+
patronymic?: string;
|
|
151
|
+
display_name?: string;
|
|
152
|
+
phone?: string;
|
|
153
|
+
email?: string;
|
|
154
|
+
sex_id?: number;
|
|
155
|
+
sex?: string;
|
|
156
|
+
birth_date?: string;
|
|
157
|
+
discount?: number;
|
|
158
|
+
card?: string;
|
|
159
|
+
comment?: string;
|
|
160
|
+
categories?: Array<{
|
|
161
|
+
id: number;
|
|
162
|
+
title: string;
|
|
163
|
+
[key: string]: unknown;
|
|
164
|
+
}>;
|
|
165
|
+
visits_count?: number;
|
|
166
|
+
sold_amount?: number;
|
|
167
|
+
paid?: number;
|
|
168
|
+
spent?: number;
|
|
169
|
+
balance?: number;
|
|
170
|
+
last_change_date?: string;
|
|
171
|
+
custom_fields?: Record<string, unknown> | unknown[];
|
|
172
|
+
[key: string]: unknown;
|
|
173
|
+
}
|
|
174
|
+
export interface FinanceTransaction {
|
|
175
|
+
id: number;
|
|
176
|
+
document_id?: number;
|
|
177
|
+
date?: string;
|
|
178
|
+
type_id?: number;
|
|
179
|
+
expense_id?: number;
|
|
180
|
+
account_id?: number;
|
|
181
|
+
amount?: number;
|
|
182
|
+
client_id?: number;
|
|
183
|
+
master_id?: number;
|
|
184
|
+
supplier_id?: number;
|
|
185
|
+
comment?: string;
|
|
186
|
+
record_id?: number;
|
|
187
|
+
visit_id?: number;
|
|
188
|
+
sold_item_id?: number;
|
|
189
|
+
sold_item_type?: string;
|
|
190
|
+
deleted?: boolean;
|
|
191
|
+
[key: string]: unknown;
|
|
192
|
+
}
|
|
193
|
+
export interface Good {
|
|
194
|
+
good_id: number;
|
|
195
|
+
title: string;
|
|
196
|
+
value?: string;
|
|
197
|
+
label?: string;
|
|
198
|
+
article?: string;
|
|
199
|
+
category?: string;
|
|
200
|
+
category_id?: number;
|
|
201
|
+
cost?: number;
|
|
202
|
+
actual_cost?: number;
|
|
203
|
+
unit_id?: number;
|
|
204
|
+
barcode?: string;
|
|
205
|
+
[key: string]: unknown;
|
|
206
|
+
}
|
|
207
|
+
export interface Storage {
|
|
208
|
+
id: number;
|
|
209
|
+
title: string;
|
|
210
|
+
for_services?: number;
|
|
211
|
+
for_sale?: number;
|
|
212
|
+
[key: string]: unknown;
|
|
213
|
+
}
|
|
214
|
+
/** One working day in a staff schedule. */
|
|
215
|
+
export interface ScheduleDay {
|
|
216
|
+
date: IsoDate;
|
|
217
|
+
is_working?: boolean | number;
|
|
218
|
+
slots?: Array<{
|
|
219
|
+
from: string;
|
|
220
|
+
to: string;
|
|
221
|
+
[key: string]: unknown;
|
|
222
|
+
}>;
|
|
223
|
+
[key: string]: unknown;
|
|
224
|
+
}
|
|
225
|
+
/** Response of `POST /auth`. */
|
|
226
|
+
export interface UserAuthResult {
|
|
227
|
+
id?: number;
|
|
228
|
+
user_token: string;
|
|
229
|
+
name?: string;
|
|
230
|
+
phone?: string;
|
|
231
|
+
login?: string;
|
|
232
|
+
email?: string;
|
|
233
|
+
[key: string]: unknown;
|
|
234
|
+
}
|
|
235
|
+
export interface PaginationParams {
|
|
236
|
+
/** 1-based page number. */
|
|
237
|
+
page?: number | undefined;
|
|
238
|
+
/** Items per page. YCLIENTS caps this per endpoint (commonly 200–1000). */
|
|
239
|
+
count?: number | undefined;
|
|
240
|
+
}
|
|
241
|
+
export interface ListRecordsParams extends PaginationParams {
|
|
242
|
+
start_date?: IsoDate | undefined;
|
|
243
|
+
end_date?: IsoDate | undefined;
|
|
244
|
+
staff_id?: Id | undefined;
|
|
245
|
+
client_id?: Id | undefined;
|
|
246
|
+
/** Only records changed after this moment (`YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss`). */
|
|
247
|
+
changed_after?: string | undefined;
|
|
248
|
+
changed_before?: string | undefined;
|
|
249
|
+
c_start_date?: IsoDate | undefined;
|
|
250
|
+
c_end_date?: IsoDate | undefined;
|
|
251
|
+
/** `1` to include deleted records. */
|
|
252
|
+
with_deleted?: 0 | 1 | undefined;
|
|
253
|
+
[key: string]: QueryValue;
|
|
254
|
+
}
|
|
255
|
+
export interface ListClientsParams extends PaginationParams {
|
|
256
|
+
/** Phone number filter (digits). */
|
|
257
|
+
phone?: string | undefined;
|
|
258
|
+
fullname?: string | undefined;
|
|
259
|
+
email?: string | undefined;
|
|
260
|
+
changed_after?: string | undefined;
|
|
261
|
+
[key: string]: QueryValue;
|
|
262
|
+
}
|
|
263
|
+
export interface ListTransactionsParams extends PaginationParams {
|
|
264
|
+
start_date?: IsoDate | undefined;
|
|
265
|
+
end_date?: IsoDate | undefined;
|
|
266
|
+
master_id?: Id | undefined;
|
|
267
|
+
client_id?: Id | undefined;
|
|
268
|
+
account_id?: Id | undefined;
|
|
269
|
+
type?: number | undefined;
|
|
270
|
+
real_money?: 0 | 1 | undefined;
|
|
271
|
+
deleted?: 0 | 1 | undefined;
|
|
272
|
+
[key: string]: QueryValue;
|
|
273
|
+
}
|
|
274
|
+
export interface ListCompaniesParams {
|
|
275
|
+
/** `1` returns only companies the user token has access to. */
|
|
276
|
+
my?: 0 | 1 | undefined;
|
|
277
|
+
group_id?: Id | undefined;
|
|
278
|
+
active?: 0 | 1 | undefined;
|
|
279
|
+
city_id?: Id | undefined;
|
|
280
|
+
[key: string]: QueryValue;
|
|
281
|
+
}
|
|
282
|
+
export interface ListGoodsParams extends PaginationParams {
|
|
283
|
+
term?: string | undefined;
|
|
284
|
+
category_id?: Id | undefined;
|
|
285
|
+
[key: string]: QueryValue;
|
|
286
|
+
}
|
|
287
|
+
export interface AnalyticsParams {
|
|
288
|
+
date_from: IsoDate;
|
|
289
|
+
date_to: IsoDate;
|
|
290
|
+
staff_id?: Id | undefined;
|
|
291
|
+
user_id?: Id | undefined;
|
|
292
|
+
[key: string]: QueryValue;
|
|
293
|
+
}
|
|
294
|
+
export type QueryScalar = string | number | boolean;
|
|
295
|
+
export type QueryValue = QueryScalar | readonly QueryScalar[] | null | undefined;
|
|
296
|
+
export type QueryParams = Record<string, QueryValue>;
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Entity shapes returned by the YCLIENTS REST API.
|
|
3
|
+
*
|
|
4
|
+
* YCLIENTS returns many more fields than are listed here and adds new ones over time,
|
|
5
|
+
* so every entity keeps an index signature: listed fields are typed, the rest stay
|
|
6
|
+
* reachable as `unknown`. Fields are optional unless the API reliably sends them.
|
|
7
|
+
*/
|
|
8
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,58 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "yclients-api",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Typed, zero-dependency TypeScript client for the YCLIENTS REST API (api.yclients.ru) with pagination and rate-limit retries.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"yclients",
|
|
7
|
+
"api",
|
|
8
|
+
"client",
|
|
9
|
+
"sdk",
|
|
10
|
+
"typescript",
|
|
11
|
+
"booking",
|
|
12
|
+
"crm"
|
|
13
|
+
],
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"author": "davronovkhayom (https://github.com/davronovkhayom)",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/davronovkhayom/yclients-api.git"
|
|
19
|
+
},
|
|
20
|
+
"homepage": "https://github.com/davronovkhayom/yclients-api#readme",
|
|
21
|
+
"bugs": {
|
|
22
|
+
"url": "https://github.com/davronovkhayom/yclients-api/issues"
|
|
23
|
+
},
|
|
24
|
+
"type": "module",
|
|
25
|
+
"main": "./dist/index.js",
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"exports": {
|
|
28
|
+
".": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"import": "./dist/index.js"
|
|
31
|
+
},
|
|
32
|
+
"./package.json": "./package.json"
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"dist",
|
|
36
|
+
"README.md",
|
|
37
|
+
"README.ru.md",
|
|
38
|
+
"LICENSE",
|
|
39
|
+
"CHANGELOG.md"
|
|
40
|
+
],
|
|
41
|
+
"sideEffects": false,
|
|
42
|
+
"engines": {
|
|
43
|
+
"node": ">=20"
|
|
44
|
+
},
|
|
45
|
+
"scripts": {
|
|
46
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
47
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
48
|
+
"test": "vitest run",
|
|
49
|
+
"test:watch": "vitest",
|
|
50
|
+
"check": "npm run typecheck && npm test && npm run build",
|
|
51
|
+
"prepublishOnly": "npm run check"
|
|
52
|
+
},
|
|
53
|
+
"devDependencies": {
|
|
54
|
+
"@types/node": "^22.20.5",
|
|
55
|
+
"typescript": "^5.9.3",
|
|
56
|
+
"vitest": "^3.2.7"
|
|
57
|
+
}
|
|
58
|
+
}
|