@cesar-richard/git-connector-sdk 1.21.0 → 1.22.0

package/README.md

@@ -1,45 +1,200 @@
 # @cesar-richard/git-connector-sdk
 
-TypeScript SDK for the [git-connector](https://github.com/cesar-richard-ei/git-connector) v1 API. Read aggregated GitHub/GitLab PR/MR ↔ issue linkage data.
+[![npm version](https://img.shields.io/npm/v/@cesar-richard/git-connector-sdk.svg)](https://www.npmjs.com/package/@cesar-richard/git-connector-sdk)
+[![license](https://img.shields.io/npm/l/@cesar-richard/git-connector-sdk.svg)](https://github.com/cesar-richard-ei/git-connector/blob/main/LICENSE)
 
-The version of this package always matches the version of the git-connector server it targets.
+TypeScript SDK for [**git-connector**](https://github.com/cesar-richard-ei/git-connector) — a server that aggregates GitHub + GitLab activity (PRs, MRs, issues, commits, comments, reviews, CI runs) and exposes a unified, ticket-correlated read API.
+
+This SDK is a thin, fully-typed wrapper around the server's `/v1/*` HTTP API, generated from its OpenAPI spec via [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/).
+
+> **Version policy:** the SDK version always tracks the git-connector server release it was generated against. Pinning the same major+minor as your server is recommended.
+
+---
 
 ## Install
 
 ```bash
 npm install @cesar-richard/git-connector-sdk
+# or
+pnpm add @cesar-richard/git-connector-sdk
+# or
+bun add @cesar-richard/git-connector-sdk
 ```
 
-## Usage
+## Quick start
 
 ```ts
 import { createGitConnectorClient } from "@cesar-richard/git-connector-sdk";
 
 const client = createGitConnectorClient({
   baseUrl: "https://git-connector.example.com",
-  token: process.env.GIT_CONNECTOR_TOKEN!,
+  token: process.env.GIT_CONNECTOR_TOKEN!, // gck_…
 });
 
 const { data, error } = await client.GET("/v1/work-items", {
   params: { query: { state: "open", iteration: "current" } },
 });
 
-if (error) throw new Error(`API error: ${error}`);
-console.log(`${data.total} open work items in the current iteration`);
+if (error) throw new Error(`git-connector error: ${JSON.stringify(error)}`);
+
+for (const item of data.items) {
+  console.log(`${item.source}/${item.projectKey}#${item.number} — ${item.title}`);
+  for (const pr of item.linkedActivities) {
+    console.log(`  ↳ ${pr.type.toUpperCase()} ${pr.url} (${pr.state})`);
+  }
+}
+```
+
+The client is fully typed: request params, query strings, and response bodies are all derived from the server's OpenAPI schema. Hover any field in your editor to see its shape.
+
+## Authentication
+
+The SDK sends `Authorization: Bearer <token>` on every request. Mint a token from the git-connector control UI or via:
+
+```bash
+curl -X POST https://git-connector.example.com/admin/api-keys \
+     -H "Content-Type: application/json" \
+     -d '{"name":"my-integration"}'
+# → { "token": "gck_…", "id": 12, "name": "my-integration", "createdAt": "…" }
 ```
 
-## Auth
+Tokens with the `gck_` prefix are immutable once minted; revoke and reissue via the same endpoint.
+
+---
+
+## API surface
+
+The `/v1/*` API exposes three resources:
+
+### `GET /v1/work-items` — list aggregated work items
+
+Issues from GitHub + GitLab, with linked PRs/MRs resolved server-side via ticket-reference correlation. Filter by `state`, `iteration` (id or `"current"`), `assignee`, `label`, `source`.
+
+```ts
+const { data } = await client.GET("/v1/work-items", {
+  params: {
+    query: {
+      state: "open",
+      iteration: "current",
+      assignee: "alice",
+    },
+  },
+});
+// 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).
+
+### `GET /v1/work-items/{source}/{projectKey}/{number}` — detail
+
+```ts
+const { data } = await client.GET(
+  "/v1/work-items/{source}/{projectKey}/{number}",
+  { params: { path: { source: "gitlab", projectKey: "acme/ops", number: 42 } } },
+);
+```
+
+### `GET /v1/iterations` — list iterations
+
+```ts
+const { data } = await client.GET("/v1/iterations");
+// data: IterationWithCount[] — each carries workItemCount across all linked WorkItems
+```
+
+### `GET /v1/events` — unified activity stream
+
+Daily-bucketed (Paris-TZ) chronological event stream. Mixes commits, comments, reviews, state-transitions, and CI runs across both providers. Cursor-paginated.
+
+```ts
+const { data } = await client.GET("/v1/events", {
+  params: {
+    query: {
+      from: "2026-05-01",
+      to: "2026-05-17",
+      type: "ci-run,review", // CSV
+      user: "alice",
+      limit: "200",
+    },
+  },
+});
+// data: { events: GitEvent[]; total: number; nextCursor: string | null }
+
+// Paginate:
+if (data.nextCursor) {
+  const { data: next } = await client.GET("/v1/events", {
+    params: { query: { from: "2026-05-01", to: "2026-05-17", cursor: data.nextCursor } },
+  });
+}
+```
+
+Event types in the stream:
+
+| `type` | Source | `parentActivityId` | Notable `meta` keys |
+|--------|--------|--------------------|---------------------|
+| `commit` | Default branch | null | `fullMessage` |
+| `comment` | Issue/PR/MR notes | resolves to PR/MR/issue | `body` |
+| `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` |
+
+---
+
+## Schema as a separate import
+
+If you need the raw OpenAPI types without the client (e.g. for codegen or for non-`openapi-fetch` consumers), import directly:
+
+```ts
+import type { components } from "@cesar-richard/git-connector-sdk/schema";
+
+type WorkItem = components["schemas"]["WorkItem"];
+type GitEvent = components["schemas"]["GitEvent"];
+```
+
+The full OpenAPI document is also published in the package — see [`openapi.json`](https://github.com/cesar-richard-ei/git-connector/blob/main/packages/sdk/openapi.json) for the contract.
+
+## Error handling
+
+`openapi-fetch` never throws on HTTP-level errors — it returns `{ data, error, response }`. Always check `error` before using `data`:
+
+```ts
+const { data, error, response } = await client.GET("/v1/work-items");
+if (error) {
+  if (response.status === 401) throw new Error("Missing/invalid gck_ token");
+  if (response.status === 403) throw new Error("Token revoked");
+  throw new Error(`git-connector ${response.status}: ${JSON.stringify(error)}`);
+}
+// data is non-null and fully typed from here
+```
+
+Network errors (DNS, timeout, connection refused) reject the promise as usual.
+
+## Custom fetch
+
+Pass your own `fetch` implementation to wire up retries, telemetry, or a non-global fetch (e.g. inside Cloudflare Workers):
+
+```ts
+import { fetch as undiciFetch } from "undici";
+
+const client = createGitConnectorClient({
+  baseUrl: "https://git-connector.example.com",
+  token: process.env.GIT_CONNECTOR_TOKEN!,
+  fetch: undiciFetch,
+});
+```
 
-Get an API token via `POST /admin/api-keys` on your git-connector instance. Tokens have format `gck_*`.
+## Compatibility
 
-## Endpoints
+- Node ≥ 18 (uses global `fetch`).
+- Bun ≥ 1.0.
+- Modern browsers (no Node-only APIs).
+- ESM only.
 
-- `GET /v1/work-items` — list aggregated work items with linked PRs/MRs
-- `GET /v1/work-items/{source}/{projectKey}/{number}` — detail
-- `GET /v1/iterations` — list iterations with work-item counts
+## Related
 
-See [`openapi.json`](https://github.com/cesar-richard-ei/git-connector/blob/main/packages/sdk/openapi.json) for the full contract (or consume it directly from non-TS languages).
+- **Server / control UI:** [git-connector](https://github.com/cesar-richard-ei/git-connector)
+- **OpenAPI spec:** ships with this package as [`openapi.json`](https://github.com/cesar-richard-ei/git-connector/blob/main/packages/sdk/openapi.json) — generated server-side, the SDK types derive from it via `openapi-typescript`.
+- **Releases:** SDK and server release in lockstep via semantic-release on every merge to `main`.
 
 ## License
 
-MIT
+[MIT](https://github.com/cesar-richard-ei/git-connector/blob/main/LICENSE)

package/dist/index.js

@@ -1,5 +1,11 @@
 import createClient from "openapi-fetch";
 export function createGitConnectorClient(opts) {
+    if (!opts.baseUrl) {
+        throw new Error("createGitConnectorClient: baseUrl is required");
+    }
+    if (!opts.token) {
+        throw new Error("createGitConnectorClient: token is required (mint via POST /admin/api-keys)");
+    }
     const client = createClient({
         baseUrl: opts.baseUrl.replace(/\/$/, ""),
         fetch: opts.fetch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesar-richard/git-connector-sdk",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "TypeScript SDK for the git-connector v1 API (work items + iterations aggregated from GitHub/GitLab). Version published on npm tracks server releases.",
   "license": "MIT",
   "repository": {