@cesar-richard/git-connector-sdk 1.28.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.
Files changed (3) hide show
  1. package/README.md +83 -1
  2. package/dist/schema.d.ts +159 -0
  3. 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 four resources: work items, iterations, work-item details, and the unified events stream.
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: {
@@ -460,6 +513,8 @@ export interface operations {
460
513
  source?: string;
461
514
  projectKey?: string;
462
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;
463
518
  label?: string;
464
519
  labelScope?: string;
465
520
  search?: string;
@@ -493,6 +548,7 @@ export interface operations {
493
548
  body: string | null;
494
549
  url: string;
495
550
  state: "open" | "closed" | "unknown";
551
+ author: string | null;
496
552
  createdAt: string;
497
553
  updatedAt: string;
498
554
  iteration: {
@@ -594,6 +650,7 @@ export interface operations {
594
650
  body: string | null;
595
651
  url: string;
596
652
  state: "open" | "closed" | "unknown";
653
+ author: string | null;
597
654
  createdAt: string;
598
655
  updatedAt: string;
599
656
  iteration: {
@@ -695,6 +752,7 @@ export interface operations {
695
752
  body: string | null;
696
753
  url: string;
697
754
  state: "open" | "closed" | "unknown";
755
+ author: string | null;
698
756
  createdAt: string;
699
757
  updatedAt: string;
700
758
  iteration: {
@@ -817,6 +875,7 @@ export interface operations {
817
875
  body: string | null;
818
876
  url: string;
819
877
  state: "open" | "closed" | "unknown";
878
+ author: string | null;
820
879
  createdAt: string;
821
880
  updatedAt: string;
822
881
  iteration: {
@@ -913,6 +972,7 @@ export interface operations {
913
972
  body: string | null;
914
973
  url: string;
915
974
  state: "open" | "closed" | "unknown";
975
+ author: string | null;
916
976
  createdAt: string;
917
977
  updatedAt: string;
918
978
  iteration: {
@@ -1009,6 +1069,7 @@ export interface operations {
1009
1069
  body: string | null;
1010
1070
  url: string;
1011
1071
  state: "open" | "closed" | "unknown";
1072
+ author: string | null;
1012
1073
  createdAt: string;
1013
1074
  updatedAt: string;
1014
1075
  iteration: {
@@ -1194,6 +1255,8 @@ export interface operations {
1194
1255
  limit?: string;
1195
1256
  /** @description Opaque cursor from previous nextCursor. */
1196
1257
  cursor?: string;
1258
+ /** @description ISO datetime; returns only events with occurredAt > since. Combines with from/to. */
1259
+ since?: string;
1197
1260
  };
1198
1261
  header?: never;
1199
1262
  path?: never;
@@ -1289,4 +1352,100 @@ export interface operations {
1289
1352
  };
1290
1353
  };
1291
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
+ };
1292
1451
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cesar-richard/git-connector-sdk",
3
- "version": "1.28.0",
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": {