@cesar-richard/git-connector-sdk 1.61.0 → 1.62.0

package/README.md

@@ -354,7 +354,7 @@ for (const wi of data.items) {
 
 ## API surface
 
-The `/v1/*` API exposes five resources: work items, iterations, work-item details, the unified events stream, and raw activities.
+The `/v1/*` API exposes these resources: work items, iterations, work-item details, the unified events stream, raw activities, deliverables, and per-project delivery rules.
 
 ### `GET /v1/work-items` — list aggregated work items
 
@@ -427,6 +427,77 @@ Event types in the stream:
 | `state-transition` | Derived from activity state diff | resolves to PR/MR/issue | `from`, `to` |
 | `ci-run` | GH Actions job / GL pipeline job | resolves to PR/MR via head SHA | `runId`, `jobName`, `conclusion`, `durationSec`, `sha`, `branch` |
 
+### `GET /v1/deliverables` — classified deliverables of a window
+
+Issues classified as **delivered**, **in_progress**, or **not_delivered** over a
+time window, driven by a per-project label convention (see delivery-rules below).
+`not_delivered` issues are always dropped from the response.
+
+Query params:
+
+| param | required | meaning |
+|-------|----------|---------|
+| `from` | **yes** | Window start. ISO date (`YYYY-MM-DD`) or datetime. |
+| `to` | **yes** | Window end. ISO date (inclusive end-of-day) or datetime. |
+| `projectKey` | no | CSV of project keys to restrict to. |
+| `author` | no | CSV of author login aliases (case-insensitive). When set, only issues attributable to one of the aliases are returned and `attribution` is populated. When **absent**, every window deliverable is returned with `attribution: null`. |
+| `source` | no | `github` or `gitlab`. |
+
+Each `DeliverableIssue` carries `deliveryState`, `deliveredAt`, `deliveryLabel`,
+`attribution` (`{ isAssignee, hasOwnCommit, isMergedPRAuthor, result }` with
+`result` precedence `assigned > committer > pr_author > none`), `linkedActivities`,
+and an `evidence` blob (`deliveryTransitions`, `consideredCommits`, `consideredPRs`)
+for human audit.
+
+```ts
+// Monthly CRA: who delivered what this month, attributed to me.
+const { data } = await client.GET("/v1/deliverables", {
+  params: {
+    query: {
+      from: "2026-05-01",
+      to: "2026-05-31",
+      projectKey: "id/cohort360/gestion-de-projet",
+      author: "cesar-richard,crichard",
+    },
+  },
+});
+// data.issues: DeliverableIssue[] — deliveryState, deliveredAt, attribution, evidence
+for (const issue of data.issues) {
+  console.log(
+    `${issue.projectKey}#${issue.number} — ${issue.deliveryState} ` +
+      `(${issue.attribution?.result ?? "n/a"}) @ ${issue.deliveredAt ?? "?"}`,
+  );
+}
+```
+
+When `author` is omitted you get the full set of window deliverables with
+`attribution: null` — useful for a team-wide "what shipped this month" view.
+
+### `GET` / `PATCH /v1/projects/{source}/{projectKey}/delivery-rules` — label convention
+
+The classification above is configurable per project. `deliveryLabels` are the
+scoped labels whose "added" transition marks an issue **delivered** (e.g. the
+GitLab scoped label `=::Pushed en dev`); `openedLabels` mark **in_progress**. When
+no rule row exists (or `deliveryLabels` is empty) the endpoint falls back to a
+native closed-state heuristic.
+
+```ts
+// Read the current convention (empty defaults when unset).
+const { data: rules } = await client.GET(
+  "/v1/projects/{source}/{projectKey}/delivery-rules",
+  { params: { path: { source: "gitlab", projectKey: "acme/ops" } } },
+);
+// { source, projectKey, deliveryLabels, openedLabels, updatedAt }
+
+// PATCH is partial — omitted keys keep their stored value.
+await client.PATCH("/v1/projects/{source}/{projectKey}/delivery-rules", {
+  params: { path: { source: "gitlab", projectKey: "acme/ops" } },
+  body: { deliveryLabels: ["=::Pushed en dev"], openedLabels: ["=::En cours"] },
+});
+```
+
+`projectKey` segments containing `/` must be URL-encoded (e.g. `acme%2Fops`).
+
 ---
 
 ## Schema as a separate import