@cesar-richard/git-connector-sdk 1.27.0 → 1.29.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/README.md +83 -1
- package/dist/schema.d.ts +164 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -62,9 +62,91 @@ Tokens with the `gck_` prefix are immutable once minted; revoke and reissue via
|
|
|
62
62
|
|
|
63
63
|
---
|
|
64
64
|
|
|
65
|
+
## Activity tracking / CRA workflow
|
|
66
|
+
|
|
67
|
+
The `/v1/*` surface is designed to power activity reports (CRA, billable-time sheets, "what did I do this month"). The primitives below let you slice your data per-user, per-day, per-type.
|
|
68
|
+
|
|
69
|
+
### What did I do today?
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
const today = new Date().toISOString().slice(0, 10);
|
|
73
|
+
const { data } = await client.GET("/v1/events", {
|
|
74
|
+
params: { query: { from: today, to: today, user: "cesar" } },
|
|
75
|
+
});
|
|
76
|
+
for (const e of data.events) {
|
|
77
|
+
console.log(`[${e.day}] ${e.type} — ${e.title} (${e.repo})`);
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### List my open PRs / MRs
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
const { data } = await client.GET("/v1/activities", {
|
|
85
|
+
params: {
|
|
86
|
+
query: { author: "cesar", state: "open,draft", type: "pr,mr" },
|
|
87
|
+
},
|
|
88
|
+
});
|
|
89
|
+
for (const a of data.items) {
|
|
90
|
+
console.log(`${a.source}/${a.repo}#${a.number} — ${a.title} (${a.state})`);
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### List issues I opened
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
const { data } = await client.GET("/v1/work-items", {
|
|
98
|
+
params: { query: { author: "cesar", state: "open" } },
|
|
99
|
+
});
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Incremental polling (every 5 minutes)
|
|
103
|
+
|
|
104
|
+
Use `?since=<ISO>` to fetch only events newer than your last cursor:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
let cursor = "2026-05-18T00:00:00Z";
|
|
108
|
+
const { data } = await client.GET("/v1/events", {
|
|
109
|
+
params: {
|
|
110
|
+
query: { from: "2026-05-01", to: "2026-05-31", since: cursor },
|
|
111
|
+
},
|
|
112
|
+
});
|
|
113
|
+
if (data.events.length > 0) {
|
|
114
|
+
cursor = data.events[data.events.length - 1].occurredAt;
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Monthly CRA: count events per day
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const { data } = await client.GET("/v1/events", {
|
|
122
|
+
params: {
|
|
123
|
+
query: {
|
|
124
|
+
from: "2026-05-01",
|
|
125
|
+
to: "2026-05-31",
|
|
126
|
+
user: "cesar",
|
|
127
|
+
type: "commit,review,comment,state-transition",
|
|
128
|
+
},
|
|
129
|
+
},
|
|
130
|
+
});
|
|
131
|
+
const byDay: Record<string, number> = {};
|
|
132
|
+
for (const e of data.events) {
|
|
133
|
+
byDay[e.day] = (byDay[e.day] ?? 0) + 1;
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Reliability of the `author` field
|
|
138
|
+
|
|
139
|
+
`author` (on Activity and Event) is the **GitHub or GitLab account login** (e.g. `cesar`, never `César Richard`). If the underlying provider payload doesn't expose a login — rare cases like a git commit by an email not linked to any account — `author` is `null`. The git-config commit-author name is never used for `author`; it lives in `meta.commitAuthorName` when available, for display purposes only.
|
|
140
|
+
|
|
141
|
+
Filters like `?author=cesar` (on `/v1/activities` and `/v1/work-items`) and `?user=cesar` (on `/v1/events`) match the login exactly (case-insensitive). They do NOT fuzzy-match display names. This is a deliberate design choice for auditable activity tracking.
|
|
142
|
+
|
|
143
|
+
**Known limitation:** GitLab REST commits API doesn't expose the GL user login without a per-commit round-trip. Commits ingested via GL polling have `author: null` + `meta.commitAuthorName` set. Commits ingested via webhook (Push Hook) have `author: <pusher.username>` reliably.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
65
147
|
## API surface
|
|
66
148
|
|
|
67
|
-
The `/v1/*` API exposes
|
|
149
|
+
The `/v1/*` API exposes five resources: work items, iterations, work-item details, the unified events stream, and raw activities.
|
|
68
150
|
|
|
69
151
|
### `GET /v1/work-items` — list aggregated work items
|
|
70
152
|
|
package/dist/schema.d.ts
CHANGED
|
@@ -68,10 +68,61 @@ export interface paths {
|
|
|
68
68
|
patch?: never;
|
|
69
69
|
trace?: never;
|
|
70
70
|
};
|
|
71
|
+
"/v1/activities": {
|
|
72
|
+
parameters: {
|
|
73
|
+
query?: never;
|
|
74
|
+
header?: never;
|
|
75
|
+
path?: never;
|
|
76
|
+
cookie?: never;
|
|
77
|
+
};
|
|
78
|
+
get: operations["getV1Activities"];
|
|
79
|
+
put?: never;
|
|
80
|
+
post?: never;
|
|
81
|
+
delete?: never;
|
|
82
|
+
options?: never;
|
|
83
|
+
head?: never;
|
|
84
|
+
patch?: never;
|
|
85
|
+
trace?: never;
|
|
86
|
+
};
|
|
71
87
|
}
|
|
72
88
|
export type webhooks = Record<string, never>;
|
|
73
89
|
export interface components {
|
|
74
90
|
schemas: {
|
|
91
|
+
ActivitiesListResponse: {
|
|
92
|
+
items: {
|
|
93
|
+
id: string;
|
|
94
|
+
source: "github" | "gitlab";
|
|
95
|
+
repo: string;
|
|
96
|
+
type: "pr" | "mr" | "issue";
|
|
97
|
+
number: string | number;
|
|
98
|
+
title: string;
|
|
99
|
+
body: string | null;
|
|
100
|
+
url: string;
|
|
101
|
+
state: "open" | "draft" | "merged" | "closed" | "unknown";
|
|
102
|
+
author: string | null;
|
|
103
|
+
createdAt: string;
|
|
104
|
+
updatedAt: string;
|
|
105
|
+
mergedAt: string | null;
|
|
106
|
+
}[];
|
|
107
|
+
total: string | number;
|
|
108
|
+
limit: string | number;
|
|
109
|
+
offset: string | number;
|
|
110
|
+
};
|
|
111
|
+
Activity: {
|
|
112
|
+
id: string;
|
|
113
|
+
source: "github" | "gitlab";
|
|
114
|
+
repo: string;
|
|
115
|
+
type: "pr" | "mr" | "issue";
|
|
116
|
+
number: string | number;
|
|
117
|
+
title: string;
|
|
118
|
+
body: string | null;
|
|
119
|
+
url: string;
|
|
120
|
+
state: "open" | "draft" | "merged" | "closed" | "unknown";
|
|
121
|
+
author: string | null;
|
|
122
|
+
createdAt: string;
|
|
123
|
+
updatedAt: string;
|
|
124
|
+
mergedAt: string | null;
|
|
125
|
+
};
|
|
75
126
|
ActivityIteration: {
|
|
76
127
|
id: string | number;
|
|
77
128
|
title: string;
|
|
@@ -254,6 +305,7 @@ export interface components {
|
|
|
254
305
|
body: string | null;
|
|
255
306
|
url: string;
|
|
256
307
|
state: "open" | "closed" | "unknown";
|
|
308
|
+
author: string | null;
|
|
257
309
|
createdAt: string;
|
|
258
310
|
updatedAt: string;
|
|
259
311
|
iteration: {
|
|
@@ -351,6 +403,7 @@ export interface components {
|
|
|
351
403
|
body: string | null;
|
|
352
404
|
url: string;
|
|
353
405
|
state: "open" | "closed" | "unknown";
|
|
406
|
+
author: string | null;
|
|
354
407
|
createdAt: string;
|
|
355
408
|
updatedAt: string;
|
|
356
409
|
iteration: {
|
|
@@ -440,6 +493,7 @@ export interface components {
|
|
|
440
493
|
}[];
|
|
441
494
|
total: string | number;
|
|
442
495
|
limit: string | number;
|
|
496
|
+
offset?: string | number;
|
|
443
497
|
};
|
|
444
498
|
};
|
|
445
499
|
responses: never;
|
|
@@ -459,10 +513,13 @@ export interface operations {
|
|
|
459
513
|
source?: string;
|
|
460
514
|
projectKey?: string;
|
|
461
515
|
assignee?: string;
|
|
516
|
+
/** @description Filter by issue author login (case-insensitive). Useful for CRA: list issues opened by a specific user. */
|
|
517
|
+
author?: string;
|
|
462
518
|
label?: string;
|
|
463
519
|
labelScope?: string;
|
|
464
520
|
search?: string;
|
|
465
521
|
limit?: string;
|
|
522
|
+
offset?: string;
|
|
466
523
|
updatedSince?: string;
|
|
467
524
|
updatedBefore?: string;
|
|
468
525
|
/** @description If 'true', returns only work items where AT LEAST ONE linked open PR/MR has reviews.approvedCount === 0. Useful for dashboards showing pending review work. */
|
|
@@ -491,6 +548,7 @@ export interface operations {
|
|
|
491
548
|
body: string | null;
|
|
492
549
|
url: string;
|
|
493
550
|
state: "open" | "closed" | "unknown";
|
|
551
|
+
author: string | null;
|
|
494
552
|
createdAt: string;
|
|
495
553
|
updatedAt: string;
|
|
496
554
|
iteration: {
|
|
@@ -580,6 +638,7 @@ export interface operations {
|
|
|
580
638
|
}[];
|
|
581
639
|
total: string | number;
|
|
582
640
|
limit: string | number;
|
|
641
|
+
offset?: string | number;
|
|
583
642
|
};
|
|
584
643
|
"multipart/form-data": {
|
|
585
644
|
items: {
|
|
@@ -591,6 +650,7 @@ export interface operations {
|
|
|
591
650
|
body: string | null;
|
|
592
651
|
url: string;
|
|
593
652
|
state: "open" | "closed" | "unknown";
|
|
653
|
+
author: string | null;
|
|
594
654
|
createdAt: string;
|
|
595
655
|
updatedAt: string;
|
|
596
656
|
iteration: {
|
|
@@ -680,6 +740,7 @@ export interface operations {
|
|
|
680
740
|
}[];
|
|
681
741
|
total: string | number;
|
|
682
742
|
limit: string | number;
|
|
743
|
+
offset?: string | number;
|
|
683
744
|
};
|
|
684
745
|
"text/plain": {
|
|
685
746
|
items: {
|
|
@@ -691,6 +752,7 @@ export interface operations {
|
|
|
691
752
|
body: string | null;
|
|
692
753
|
url: string;
|
|
693
754
|
state: "open" | "closed" | "unknown";
|
|
755
|
+
author: string | null;
|
|
694
756
|
createdAt: string;
|
|
695
757
|
updatedAt: string;
|
|
696
758
|
iteration: {
|
|
@@ -780,6 +842,7 @@ export interface operations {
|
|
|
780
842
|
}[];
|
|
781
843
|
total: string | number;
|
|
782
844
|
limit: string | number;
|
|
845
|
+
offset?: string | number;
|
|
783
846
|
};
|
|
784
847
|
};
|
|
785
848
|
};
|
|
@@ -812,6 +875,7 @@ export interface operations {
|
|
|
812
875
|
body: string | null;
|
|
813
876
|
url: string;
|
|
814
877
|
state: "open" | "closed" | "unknown";
|
|
878
|
+
author: string | null;
|
|
815
879
|
createdAt: string;
|
|
816
880
|
updatedAt: string;
|
|
817
881
|
iteration: {
|
|
@@ -908,6 +972,7 @@ export interface operations {
|
|
|
908
972
|
body: string | null;
|
|
909
973
|
url: string;
|
|
910
974
|
state: "open" | "closed" | "unknown";
|
|
975
|
+
author: string | null;
|
|
911
976
|
createdAt: string;
|
|
912
977
|
updatedAt: string;
|
|
913
978
|
iteration: {
|
|
@@ -1004,6 +1069,7 @@ export interface operations {
|
|
|
1004
1069
|
body: string | null;
|
|
1005
1070
|
url: string;
|
|
1006
1071
|
state: "open" | "closed" | "unknown";
|
|
1072
|
+
author: string | null;
|
|
1007
1073
|
createdAt: string;
|
|
1008
1074
|
updatedAt: string;
|
|
1009
1075
|
iteration: {
|
|
@@ -1189,6 +1255,8 @@ export interface operations {
|
|
|
1189
1255
|
limit?: string;
|
|
1190
1256
|
/** @description Opaque cursor from previous nextCursor. */
|
|
1191
1257
|
cursor?: string;
|
|
1258
|
+
/** @description ISO datetime; returns only events with occurredAt > since. Combines with from/to. */
|
|
1259
|
+
since?: string;
|
|
1192
1260
|
};
|
|
1193
1261
|
header?: never;
|
|
1194
1262
|
path?: never;
|
|
@@ -1284,4 +1352,100 @@ export interface operations {
|
|
|
1284
1352
|
};
|
|
1285
1353
|
};
|
|
1286
1354
|
};
|
|
1355
|
+
getV1Activities: {
|
|
1356
|
+
parameters: {
|
|
1357
|
+
query?: {
|
|
1358
|
+
/** @description Exact match (case-insensitive) on the activity author's GitHub/GitLab login. Does NOT match display names. */
|
|
1359
|
+
author?: string;
|
|
1360
|
+
/** @description CSV: open,draft,merged,closed,unknown. Default returns all states. */
|
|
1361
|
+
state?: string;
|
|
1362
|
+
/** @description CSV: pr,mr,issue. Default returns all. */
|
|
1363
|
+
type?: string;
|
|
1364
|
+
repo?: string;
|
|
1365
|
+
/** @description github | gitlab */
|
|
1366
|
+
provider?: string;
|
|
1367
|
+
/** @description ISO datetime; activity.updatedAt >= since. */
|
|
1368
|
+
updatedSince?: string;
|
|
1369
|
+
/** @description ISO datetime; activity.updatedAt < before. */
|
|
1370
|
+
updatedBefore?: string;
|
|
1371
|
+
/** @description Default 100, max 500. */
|
|
1372
|
+
limit?: string;
|
|
1373
|
+
/** @description Default 0. */
|
|
1374
|
+
offset?: string;
|
|
1375
|
+
};
|
|
1376
|
+
header?: never;
|
|
1377
|
+
path?: never;
|
|
1378
|
+
cookie?: never;
|
|
1379
|
+
};
|
|
1380
|
+
requestBody?: never;
|
|
1381
|
+
responses: {
|
|
1382
|
+
200: {
|
|
1383
|
+
headers: {
|
|
1384
|
+
[name: string]: unknown;
|
|
1385
|
+
};
|
|
1386
|
+
content: {
|
|
1387
|
+
"application/json": {
|
|
1388
|
+
items: {
|
|
1389
|
+
id: string;
|
|
1390
|
+
source: "github" | "gitlab";
|
|
1391
|
+
repo: string;
|
|
1392
|
+
type: "pr" | "mr" | "issue";
|
|
1393
|
+
number: string | number;
|
|
1394
|
+
title: string;
|
|
1395
|
+
body: string | null;
|
|
1396
|
+
url: string;
|
|
1397
|
+
state: "open" | "draft" | "merged" | "closed" | "unknown";
|
|
1398
|
+
author: string | null;
|
|
1399
|
+
createdAt: string;
|
|
1400
|
+
updatedAt: string;
|
|
1401
|
+
mergedAt: string | null;
|
|
1402
|
+
}[];
|
|
1403
|
+
total: string | number;
|
|
1404
|
+
limit: string | number;
|
|
1405
|
+
offset: string | number;
|
|
1406
|
+
};
|
|
1407
|
+
"multipart/form-data": {
|
|
1408
|
+
items: {
|
|
1409
|
+
id: string;
|
|
1410
|
+
source: "github" | "gitlab";
|
|
1411
|
+
repo: string;
|
|
1412
|
+
type: "pr" | "mr" | "issue";
|
|
1413
|
+
number: string | number;
|
|
1414
|
+
title: string;
|
|
1415
|
+
body: string | null;
|
|
1416
|
+
url: string;
|
|
1417
|
+
state: "open" | "draft" | "merged" | "closed" | "unknown";
|
|
1418
|
+
author: string | null;
|
|
1419
|
+
createdAt: string;
|
|
1420
|
+
updatedAt: string;
|
|
1421
|
+
mergedAt: string | null;
|
|
1422
|
+
}[];
|
|
1423
|
+
total: string | number;
|
|
1424
|
+
limit: string | number;
|
|
1425
|
+
offset: string | number;
|
|
1426
|
+
};
|
|
1427
|
+
"text/plain": {
|
|
1428
|
+
items: {
|
|
1429
|
+
id: string;
|
|
1430
|
+
source: "github" | "gitlab";
|
|
1431
|
+
repo: string;
|
|
1432
|
+
type: "pr" | "mr" | "issue";
|
|
1433
|
+
number: string | number;
|
|
1434
|
+
title: string;
|
|
1435
|
+
body: string | null;
|
|
1436
|
+
url: string;
|
|
1437
|
+
state: "open" | "draft" | "merged" | "closed" | "unknown";
|
|
1438
|
+
author: string | null;
|
|
1439
|
+
createdAt: string;
|
|
1440
|
+
updatedAt: string;
|
|
1441
|
+
mergedAt: string | null;
|
|
1442
|
+
}[];
|
|
1443
|
+
total: string | number;
|
|
1444
|
+
limit: string | number;
|
|
1445
|
+
offset: string | number;
|
|
1446
|
+
};
|
|
1447
|
+
};
|
|
1448
|
+
};
|
|
1449
|
+
};
|
|
1450
|
+
};
|
|
1287
1451
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cesar-richard/git-connector-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.29.0",
|
|
4
4
|
"description": "TypeScript SDK for the git-connector v1 API (work items + iterations aggregated from GitHub/GitLab). Version published on npm tracks server releases.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|