@cesar-richard/git-connector-sdk 2.5.0 → 2.7.0

package/README.md

@@ -354,7 +354,26 @@ for (const wi of data.items) {
 
 ## API surface
 
-The `/v1/*` API exposes these resources: work items, iterations, work-item details, the unified events stream, raw activities, deliverables, and per-project delivery rules.
+The `/v1/*` API exposes these resources: tracked projects, work items, iterations, work-item details, the unified events stream (polled or server-sent), raw activities, deliverables, and per-project delivery rules.
+
+### `GET /v1/projects` — list tracked projects
+
+Every project the operator tracks, sorted by `(source, projectKey)`.
+
+```ts
+const { data } = await client.GET("/v1/projects");
+// data: { projects: { source, projectKey, name, webUrl, lastSyncedAt }[] }
+```
+
+This is the **only correct way** to enumerate projects. Deriving the list by
+paginating `/v1/work-items` or `/v1/activities` and deduplicating
+`(source, projectKey)` is wrong by construction: a tracked project with no
+activity in the window read is invisible that way, so it can never be configured
+downstream. `lastSyncedAt` is `null` when the project has never completed a sync
+— that means *never ingested*, not *quiet*.
+
+Pair `source` + `projectKey` to call
+`GET /v1/projects/{source}/{projectKey}/labels`.
 
 ### `GET /v1/work-items` — list aggregated work items
 
@@ -373,7 +392,24 @@ const { data } = await client.GET("/v1/work-items", {
 // data: { items: WorkItem[]; total: number; limit: number }
 ```
 
-Each `WorkItem` includes its `linkedActivities` (PRs/MRs with full enrichment: reviews summary, unresolved threads, volume, status history, reviewRequestedAt, mergedAt).
+Each `WorkItem` includes its `linkedActivities` (PRs/MRs with full enrichment: reviews summary, unresolved threads, volume, status history, reviewRequestedAt, mergedAt, and the current CI status).
+
+#### `linkedActivities[].ci` — current CI status
+
+The latest known CI **pipeline** for that PR/MR (not per-job `ci-run`), always
+computed on both the list and the detail route:
+
+```ts
+ci?: {
+  status: "success" | "failed" | "running" | "canceled" | "unknown";
+  url: string | null;
+  finishedAt: string | null;
+} | null
+```
+
+`null` means *no pipeline is known* — never read it as "green". Together with
+`hasConflicts`, `reviews` and `unresolvedThreads`, `status: "failed"` is the
+fourth signal for rendering a work item as blocked.
 
 ### `GET /v1/work-items/{source}/{projectKey}/{number}` — detail
 
@@ -426,6 +462,44 @@ Event types in the stream:
 | `review` | GH PR review / GL MR approval | resolves to PR/MR | `state`, `reviewer` |
 | `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` |
+| `ci-pipeline` | GH Actions run / GL pipeline | resolves to PR/MR via head SHA | `runId`, `conclusion`, `status`, `durationSec`, `sha`, `branch` |
+
+#### Fetching one activity's events — `?parentActivityId`
+
+Pass `parentActivityId` (CSV for several) to get every event attached to a PR/MR
+— commits, pipelines, comments — without guessing a date window. **When this
+filter is given, `from`/`to` become optional**, and omitting them is usually what
+you want: a window silently drops anything older than it, which for a CI pipeline
+means reading "no pipeline" where there is a red one.
+
+```ts
+const { data } = await client.GET("/v1/events", {
+  params: {
+    query: {
+      parentActivityId: "github:acme/web:pr:42,github:acme/web:pr:43",
+      type: "ci-pipeline",
+    },
+  },
+});
+```
+
+### `GET /v1/events/stream` — server-sent events
+
+SSE on the consumer scope, authenticated with the same `gck_` Bearer token. It
+emits `events.ingested` frames only — operator-scope traffic (sync progress,
+config changes, provider-auth staleness) never crosses this boundary. A `:ping`
+comment every 30 s keeps proxies from dropping the socket.
+
+```ts
+const res = await fetch(`${baseUrl}/v1/events/stream`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+// text/event-stream: `event: events.ingested` frames whose data is
+// { type: "events.ingested", payload: { events: GitEvent[] } }
+```
+
+Polling `GET /v1/events?since=<ISO>` stays the simpler option and is cheap enough
+for most consumers; reach for the stream when you want push latency.
 
 ### `GET /v1/deliverables` — classified deliverables of a window