@cesar-richard/git-connector-sdk 1.56.5 → 1.58.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 +50 -0
  2. package/dist/schema.d.ts +159 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -265,6 +265,56 @@ The phrase prefix lets the SDK detect refs even when the number is **bare**
265
265
 
266
266
  Code blocks (fenced ```` ``` ```` and inline `` ` ``) are stripped before scanning.
267
267
 
268
+ ### Correlation confidence & billing flags (`attributable`, `resolves`)
269
+
270
+ Every `linkedActivities[]` entry carries billing-grade correlation metadata so a
271
+ client app can decide, **auditably**, what to impute and how to display issue
272
+ status. All fields are optional (only present once an entity has been
273
+ (re)synced under scoring algo `corr-2026.06`).
274
+
275
+ | field | type | meaning |
276
+ |---|---|---|
277
+ | `linkKind` | `"reference" \| "resolution" \| "reverse_comment"` | how the link reads: a mention, an explicit closure, or a link discovered from the issue's own comments |
278
+ | `confidence` | `number \| null` | `[0,1]`. Driven by the **form** of the evidence: canonical URL `0.95` > cross-ref (`group/repo#N`) `0.85` > bare short ref `0.78`; `−0.13` in a title, `+0.07` for a resolution verb; ambiguous heuristic-resolved refs capped at `0.60` |
279
+ | `status` | `"confirmed" \| "candidate"` | `confirmed` when `confidence ≥ 0.75` and unambiguous (or confirmed via bidirectional evidence) |
280
+ | `attributable` | `boolean` | **the flag to use for imputation / billing.** `true` ⇔ `status==='confirmed'`, **any** `linkKind`. A PR that merely references an issue (preparatory work) — or is only linked from the issue's comments — still counts as contribution |
281
+ | `resolves` | `boolean` | `true` ⇔ `confirmed && linkKind==='resolution'`. Use for **issue status**, never for billing |
282
+ | `evidence` | `{ field, text, matchStart, matchEnd } \| null` | the matched snippet + offsets, for human audit |
283
+
284
+ > **Migration note (was `billable`):** the short-lived `billable` field (SDK
285
+ > `1.57.0`) was **removed**. It conflated two questions. Replace it as follows:
286
+ >
287
+ > - imputation / "who worked on this issue" → use **`attributable`** (NOT the
288
+ > old `billable`, which only fired on closures and missed preparatory work and
289
+ > reverse-linked PRs);
290
+ > - "what closed the issue" / status → use **`resolves`** (this is what the old
291
+ > `billable` actually computed).
292
+
293
+ ```ts
294
+ const { data } = await client.GET("/v1/work-items", {
295
+ params: { query: { state: "open" } },
296
+ });
297
+ for (const wi of data.items) {
298
+ // Everyone who contributed to this issue (for a CRA / billing sheet):
299
+ const contributors = new Set(
300
+ wi.linkedActivities
301
+ .filter((pr) => pr.attributable)
302
+ .map((pr) => pr.authorResolved?.login ?? pr.author)
303
+ .filter(Boolean),
304
+ );
305
+
306
+ // Is the issue actually resolved by a merged PR?
307
+ const resolved = wi.linkedActivities.some((pr) => pr.resolves && pr.isMerged);
308
+
309
+ console.log(`${wi.title}: worked on by [${[...contributors].join(", ")}]`, { resolved });
310
+ }
311
+ ```
312
+
313
+ Two PRs in different repos (e.g. a GitHub PR for terraform groundwork + a GitLab
314
+ MR for the feature) that both reference the same issue both show up as
315
+ `attributable` linked activities on that one work item — that's how cross-repo,
316
+ cross-provider work is consolidated: the issue is the pivot.
317
+
268
318
  ### PR review status (`reviewStatus`)
269
319
 
270
320
  Each `LinkedActivity` carries an optional `reviewStatus` field with 8 possible
package/dist/schema.d.ts CHANGED
@@ -203,6 +203,12 @@ export interface components {
203
203
  name: string;
204
204
  color: string | null;
205
205
  };
206
+ LinkEvidence: {
207
+ field: string;
208
+ text: string;
209
+ matchStart: string | number;
210
+ matchEnd: string | number;
211
+ };
206
212
  LinkSource: {
207
213
  hintSource: string;
208
214
  kind: string;
@@ -275,6 +281,23 @@ export interface components {
275
281
  hintSource: string;
276
282
  kind: string;
277
283
  };
284
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
285
+ linkKind?: string;
286
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
287
+ confidence?: number | null;
288
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
289
+ status?: string;
290
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
291
+ attributable?: boolean;
292
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
293
+ resolves?: boolean;
294
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
295
+ evidence?: {
296
+ field: string;
297
+ text: string;
298
+ matchStart: string | number;
299
+ matchEnd: string | number;
300
+ } | null;
278
301
  };
279
302
  Provider: "github" | "gitlab";
280
303
  ResolvedUser: {
@@ -445,6 +468,23 @@ export interface components {
445
468
  hintSource: string;
446
469
  kind: string;
447
470
  };
471
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
472
+ linkKind?: string;
473
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
474
+ confidence?: number | null;
475
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
476
+ status?: string;
477
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
478
+ attributable?: boolean;
479
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
480
+ resolves?: boolean;
481
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
482
+ evidence?: {
483
+ field: string;
484
+ text: string;
485
+ matchStart: string | number;
486
+ matchEnd: string | number;
487
+ } | null;
448
488
  }[];
449
489
  statusHistory: {
450
490
  label: {
@@ -566,6 +606,23 @@ export interface components {
566
606
  hintSource: string;
567
607
  kind: string;
568
608
  };
609
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
610
+ linkKind?: string;
611
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
612
+ confidence?: number | null;
613
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
614
+ status?: string;
615
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
616
+ attributable?: boolean;
617
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
618
+ resolves?: boolean;
619
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
620
+ evidence?: {
621
+ field: string;
622
+ text: string;
623
+ matchStart: string | number;
624
+ matchEnd: string | number;
625
+ } | null;
569
626
  }[];
570
627
  statusHistory: {
571
628
  label: {
@@ -736,6 +793,23 @@ export interface operations {
736
793
  hintSource: string;
737
794
  kind: string;
738
795
  };
796
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
797
+ linkKind?: string;
798
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
799
+ confidence?: number | null;
800
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
801
+ status?: string;
802
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
803
+ attributable?: boolean;
804
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
805
+ resolves?: boolean;
806
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
807
+ evidence?: {
808
+ field: string;
809
+ text: string;
810
+ matchStart: string | number;
811
+ matchEnd: string | number;
812
+ } | null;
739
813
  }[];
740
814
  statusHistory: {
741
815
  label: {
@@ -861,6 +935,23 @@ export interface operations {
861
935
  hintSource: string;
862
936
  kind: string;
863
937
  };
938
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
939
+ linkKind?: string;
940
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
941
+ confidence?: number | null;
942
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
943
+ status?: string;
944
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
945
+ attributable?: boolean;
946
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
947
+ resolves?: boolean;
948
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
949
+ evidence?: {
950
+ field: string;
951
+ text: string;
952
+ matchStart: string | number;
953
+ matchEnd: string | number;
954
+ } | null;
864
955
  }[];
865
956
  statusHistory: {
866
957
  label: {
@@ -986,6 +1077,23 @@ export interface operations {
986
1077
  hintSource: string;
987
1078
  kind: string;
988
1079
  };
1080
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
1081
+ linkKind?: string;
1082
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
1083
+ confidence?: number | null;
1084
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
1085
+ status?: string;
1086
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
1087
+ attributable?: boolean;
1088
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
1089
+ resolves?: boolean;
1090
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
1091
+ evidence?: {
1092
+ field: string;
1093
+ text: string;
1094
+ matchStart: string | number;
1095
+ matchEnd: string | number;
1096
+ } | null;
989
1097
  }[];
990
1098
  statusHistory: {
991
1099
  label: {
@@ -1135,6 +1243,23 @@ export interface operations {
1135
1243
  hintSource: string;
1136
1244
  kind: string;
1137
1245
  };
1246
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
1247
+ linkKind?: string;
1248
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
1249
+ confidence?: number | null;
1250
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
1251
+ status?: string;
1252
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
1253
+ attributable?: boolean;
1254
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
1255
+ resolves?: boolean;
1256
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
1257
+ evidence?: {
1258
+ field: string;
1259
+ text: string;
1260
+ matchStart: string | number;
1261
+ matchEnd: string | number;
1262
+ } | null;
1138
1263
  }[];
1139
1264
  statusHistory: {
1140
1265
  label: {
@@ -1255,6 +1380,23 @@ export interface operations {
1255
1380
  hintSource: string;
1256
1381
  kind: string;
1257
1382
  };
1383
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
1384
+ linkKind?: string;
1385
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
1386
+ confidence?: number | null;
1387
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
1388
+ status?: string;
1389
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
1390
+ attributable?: boolean;
1391
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
1392
+ resolves?: boolean;
1393
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
1394
+ evidence?: {
1395
+ field: string;
1396
+ text: string;
1397
+ matchStart: string | number;
1398
+ matchEnd: string | number;
1399
+ } | null;
1258
1400
  }[];
1259
1401
  statusHistory: {
1260
1402
  label: {
@@ -1375,6 +1517,23 @@ export interface operations {
1375
1517
  hintSource: string;
1376
1518
  kind: string;
1377
1519
  };
1520
+ /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
1521
+ linkKind?: string;
1522
+ /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
1523
+ confidence?: number | null;
1524
+ /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
1525
+ status?: string;
1526
+ /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
1527
+ attributable?: boolean;
1528
+ /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
1529
+ resolves?: boolean;
1530
+ /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
1531
+ evidence?: {
1532
+ field: string;
1533
+ text: string;
1534
+ matchStart: string | number;
1535
+ matchEnd: string | number;
1536
+ } | null;
1378
1537
  }[];
1379
1538
  statusHistory: {
1380
1539
  label: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cesar-richard/git-connector-sdk",
3
- "version": "1.56.5",
3
+ "version": "1.58.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": {