@forge-glance/sdk 0.1.0

package/src/NoteMutator.ts

@@ -0,0 +1,108 @@
+/**
+ * REST API helpers for GitLab note mutations.
+ *
+ * Uses numeric projectId + mrIid so callers don't need the project full path.
+ * Mirrors the GitLab REST API:
+ *   POST   /api/v4/projects/:id/merge_requests/:mrIid/notes
+ *   POST   /api/v4/projects/:id/merge_requests/:mrIid/discussions/:discussionId/notes
+ *   PUT    /api/v4/projects/:id/merge_requests/:mrIid/notes/:noteId
+ *   DELETE /api/v4/projects/:id/merge_requests/:mrIid/notes/:noteId
+ */
+
+export interface CreatedNote {
+  id: number;
+  body: string;
+  author: {
+    id: number;
+    username: string;
+    name: string;
+    avatar_url: string | null;
+  };
+  created_at: string;
+  resolvable: boolean | null;
+  resolved: boolean | null;
+}
+
+export class NoteMutator {
+  private readonly baseURL: string;
+  private readonly token: string;
+
+  constructor(baseURL: string, token: string) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+  }
+
+  /**
+   * Create a note on an MR, optionally within an existing discussion thread.
+   * If `discussionId` is provided the note is posted as a reply to that thread.
+   */
+  async createNote(
+    projectId: number,
+    mrIid: number,
+    body: string,
+    discussionId?: string,
+  ): Promise<CreatedNote> {
+    const url = discussionId
+      ? `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/discussions/${discussionId}/notes`
+      : `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/notes`;
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PRIVATE-TOKEN": this.token,
+      },
+      body: JSON.stringify({ body }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `createNote failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`,
+      );
+    }
+
+    return (await res.json()) as CreatedNote;
+  }
+
+  /** Edit the body of an existing note. */
+  async updateNote(
+    projectId: number,
+    mrIid: number,
+    noteId: number,
+    body: string,
+  ): Promise<void> {
+    const url = `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/notes/${noteId}`;
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        "PRIVATE-TOKEN": this.token,
+      },
+      body: JSON.stringify({ body }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `updateNote failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`,
+      );
+    }
+  }
+
+  /** Permanently delete a note. */
+  async deleteNote(projectId: number, mrIid: number, noteId: number): Promise<void> {
+    const url = `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/notes/${noteId}`;
+    const res = await fetch(url, {
+      method: "DELETE",
+      headers: { "PRIVATE-TOKEN": this.token },
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `deleteNote failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`,
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @forge-glance/sdk — GitHub & GitLab API client.
+ *
+ * Provides provider-agnostic types, REST/GraphQL clients, and real-time
+ * ActionCable subscriptions for GitLab. Designed for use in any Node/Bun
+ * runtime.
+ *
+ * @example
+ * import { GitLabProvider, ActionCableClient, type PullRequest } from '@forge-glance/sdk';
+ *
+ * const provider = new GitLabProvider('https://gitlab.com', token, { logger: console });
+ * const prs = await provider.fetchPullRequests();
+ */
+
+// ── Domain types ──────────────────────────────────────────────────────────────
+export type {
+  PullRequest,
+  PullRequestsSnapshot,
+  Pipeline,
+  PipelineJob,
+  UserRef,
+  DiffStats,
+  Discussion,
+  Note,
+  NoteAuthor,
+  NotePosition,
+  MRDetail,
+  FeedEvent,
+  FeedSnapshot,
+  ServerNotification,
+} from "./types.ts";
+
+// ── Provider interface ────────────────────────────────────────────────────────
+export type { GitProvider } from "./GitProvider.ts";
+export { parseRepoId, repoIdProvider } from "./GitProvider.ts";
+
+// ── Logger ────────────────────────────────────────────────────────────────────
+export type { ForgeLogger } from "./logger.ts";
+export { noopLogger } from "./logger.ts";
+
+// ── Providers ─────────────────────────────────────────────────────────────────
+export { GitLabProvider, parseGitLabRepoId, MR_DASHBOARD_FRAGMENT } from "./GitLabProvider.ts";
+export { GitHubProvider } from "./GitHubProvider.ts";
+export { createProvider, SUPPORTED_PROVIDERS } from "./providers.ts";
+export type { ProviderSlug } from "./providers.ts";
+
+// ── GitLab real-time ──────────────────────────────────────────────────────────
+export { ActionCableClient } from "./ActionCableClient.ts";
+export type { ActionCableCallbacks } from "./ActionCableClient.ts";
+
+// ── GitLab detail + mutations ─────────────────────────────────────────────────
+export { MRDetailFetcher } from "./MRDetailFetcher.ts";
+export { NoteMutator } from "./NoteMutator.ts";
+export type { CreatedNote } from "./NoteMutator.ts";

package/src/logger.ts

@@ -0,0 +1,26 @@
+/**
+ * Logger interface for @forge-glance/sdk.
+ *
+ * All providers and clients accept an optional `logger` in their constructor
+ * that must satisfy this interface. Defaults to `noopLogger` when omitted,
+ * so the SDK is silent out of the box.
+ *
+ * Consumers can pass any compatible logger — pino, winston, console, etc.
+ *
+ * @example
+ * import pino from 'pino';
+ * const provider = new GitLabProvider(url, token, { logger: pino() });
+ */
+export interface ForgeLogger {
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export const noopLogger: ForgeLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};

package/src/providers.ts

@@ -0,0 +1,40 @@
+/**
+ * Provider factory (Phase C1).
+ *
+ * Creates the correct GitProvider implementation based on the provider slug
+ * from `connected_accounts.provider`.
+ */
+
+import type { GitProvider } from "./GitProvider.ts";
+import { GitLabProvider } from "./GitLabProvider.ts";
+import { GitHubProvider } from "./GitHubProvider.ts";
+import type { ForgeLogger } from "./logger.ts";
+
+/**
+ * Create a GitProvider for the given provider slug.
+ *
+ * @param provider - The provider slug from the DB, e.g. "gitlab" or "github".
+ * @param baseURL  - The base URL for the provider instance.
+ * @param token    - The decrypted PAT for the provider.
+ * @returns A GitProvider implementation.
+ * @throws If the provider slug is unknown.
+ */
+export function createProvider(
+  provider: string,
+  baseURL: string,
+  token: string,
+  options: { logger?: ForgeLogger } = {},
+): GitProvider {
+  switch (provider) {
+    case "gitlab":
+      return new GitLabProvider(baseURL, token, options);
+    case "github":
+      return new GitHubProvider(baseURL, token, options);
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}
+
+/** List of all supported provider slugs. */
+export const SUPPORTED_PROVIDERS = ["gitlab", "github"] as const;
+export type ProviderSlug = (typeof SUPPORTED_PROVIDERS)[number];

package/src/types.ts

@@ -0,0 +1,196 @@
+/**
+ * Provider-agnostic domain types.
+ *
+ * These are the canonical types sent to Swift clients via the WebSocket protocol.
+ * No raw provider payloads leave the provider layer — only these types.
+ *
+ * Field names match the Swift DomainXxx structs in Sources/GlanceLib/Models/Domain/.
+ */
+
+export interface UserRef {
+  /** Scoped provider ID, e.g. "gitlab:12345". */
+  id: string;
+  username: string;
+  name: string;
+  avatarUrl: string | null;
+}
+
+export interface PipelineJob {
+  /** Scoped provider ID, e.g. "gitlab:12345". */
+  id: string;
+  name: string;
+  stage: string;
+  /** Normalized status: "success" | "failed" | "running" | "pending" | "canceled" | "skipped" | "manual" | etc. */
+  status: string;
+  allowFailure: boolean;
+  webUrl: string | null;
+}
+
+export interface Pipeline {
+  /** Scoped provider ID, e.g. "gitlab:pipeline:12345". */
+  id: string;
+  /** Normalized status. */
+  status: string;
+  createdAt: string | null;
+  webUrl: string | null;
+  jobs: PipelineJob[];
+}
+
+export interface DiffStats {
+  additions: number;
+  deletions: number;
+  filesChanged: number;
+}
+
+export interface PullRequest {
+  /** Scoped provider ID, e.g. "gitlab:12345". */
+  id: string;
+  /** Numeric MR/PR number within the project. */
+  iid: number;
+  /** Scoped repository ID, e.g. "gitlab:42". */
+  repositoryId: string;
+  title: string;
+  /** Full MR description body. Used by AI summarization and the MR header. */
+  description: string | null;
+  /** "opened" | "merged" | "closed" */
+  state: string;
+  draft: boolean;
+  conflicts: boolean;
+  webUrl: string | null;
+  sourceBranch: string;
+  targetBranch: string;
+  createdAt: string | null;
+  updatedAt: string | null;
+  /** Head commit SHA. */
+  sha: string | null;
+
+  author: UserRef;
+  assignees: UserRef[];
+  reviewers: UserRef[];
+  /** Roles the current authenticated user has on this MR. Values: "author" | "reviewer" | "assignee". */
+  roles: string[];
+
+  pipeline: Pipeline | null;
+  unresolvedThreadCount: number;
+  approvalsLeft: number;
+  /** True when the MR has met its approval requirements. */
+  approved: boolean;
+  approvedBy: UserRef[];
+  diffStats: DiffStats | null;
+  /**
+   * Raw GitLab detailedMergeStatus value, e.g. "mergeable", "conflict",
+   * "not_approved", "discussions_not_resolved". Null for non-GitLab providers.
+   */
+  detailedMergeStatus: string | null;
+}
+
+/** Snapshot payload sent when a client first connects. */
+export interface PullRequestsSnapshot {
+  items: PullRequest[];
+}
+
+/** Feed event emitted as `feed_event` (incremental) or inside `feed_snapshot` (initial batch). */
+export interface FeedEvent {
+  /** Stable event ID, e.g. "note-1234" or "projEvent-5678". */
+  id: string;
+  /** MR IID within the project. */
+  mrIid: number;
+  /** Scoped repository ID, e.g. "gitlab:42". */
+  repositoryId: string;
+  /** Actor's GitLab username. */
+  actor: string;
+  actorAvatarUrl: string | null;
+  body: string | null;
+  /** ISO 8601 timestamp. */
+  createdAt: string;
+  /**
+   * View scope the event was fetched under.
+   * "authored_by_me" | "reviewing" | "assigned_to_me" | "any"
+   */
+  scope: string;
+  /** Normalized action: "commented" | "approved" | "merged" | "closed" | etc. */
+  action: string;
+  /** Normalized target type, e.g. "merge_request". */
+  targetType: string;
+  /** Note ID when the event originates from a note; null for action-only events. */
+  noteId: number | null;
+  /** MR title — the primary title shown in the Swift feed row. */
+  title: string;
+  /** Short human-readable line, e.g. "username commented". */
+  subtitle: string;
+  /** MR web URL for deep-linking. */
+  webUrl: string | null;
+  /**
+   * True for events within the initial history window (not new since last poll).
+   * Swift uses this to set event state to `.read` on insertion.
+   */
+  isHistorical: boolean;
+}
+
+/** Payload for a `feed_snapshot` event sent on first connect. */
+export interface FeedSnapshot {
+  items: FeedEvent[];
+}
+
+// ---------------------------------------------------------------------------
+// D3: MR Detail types (discussions, notes, positions)
+// ---------------------------------------------------------------------------
+
+export interface NoteAuthor {
+  /** Scoped provider ID, e.g. "gitlab:user:12345". */
+  id: string;
+  username: string;
+  name: string;
+  avatarUrl: string | null;
+}
+
+export interface NotePosition {
+  newPath: string | null;
+  oldPath: string | null;
+  newLine: number | null;
+  oldLine: number | null;
+  positionType: string | null;
+}
+
+export interface Note {
+  id: number;
+  body: string;
+  author: NoteAuthor;
+  createdAt: string;
+  system: boolean;
+  /** "DiffNote" | "DiscussionNote" | null */
+  type: string | null;
+  resolvable: boolean | null;
+  resolved: boolean | null;
+  position: NotePosition | null;
+}
+
+export interface Discussion {
+  id: string;
+  resolvable: boolean | null;
+  resolved: boolean | null;
+  notes: Note[];
+}
+
+export interface MRDetail {
+  mrIid: number;
+  /** Scoped repository ID, e.g. "gitlab:42". */
+  repositoryId: string;
+  discussions: Discussion[];
+}
+
+/**
+ * Payload for a `notification` event emitted by the server to connected clients.
+ *
+ * Rules are intentionally simple for Phase A6 (prefs stubbed).
+ * When per-user preferences land (Phase B), the server will evaluate a proper
+ * rules engine before deciding whether to emit this event.
+ */
+export interface ServerNotification {
+  title: string;
+  body: string;
+  /** Scoped PR id, e.g. "gitlab:mr:12345". Omitted for non-MR notifications. */
+  mrId?: string;
+  /** Deep-link URL to open when the notification is tapped. */
+  webUrl?: string | null;
+}