@forge-glance/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * 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[];
+}
+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;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@forge-glance/sdk",
+  "version": "0.1.0",
+  "description": "GitHub & GitLab API client — REST, GraphQL, and real-time ActionCable subscriptions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts src/types.ts src/logger.ts src/GitProvider.ts src/GitLabProvider.ts src/GitHubProvider.ts src/ActionCableClient.ts src/MRDetailFetcher.ts src/NoteMutator.ts src/providers.ts --outdir dist --root src --target node && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m4ttheweric/Glance",
+    "directory": "packages/sdk"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/ActionCableClient.ts

@@ -0,0 +1,237 @@
+/**
+ * ActionCableClient — outgoing WebSocket client for GitLab's ActionCable endpoint.
+ *
+ * Connects to wss://{baseURL}/-/cable, implements the ActionCable protocol
+ * (subscribe/unsubscribe/ping/confirm), and auto-reconnects with exponential backoff.
+ *
+ * Mirrors Swift's ActionCableClient.swift.
+ */
+
+import { type ForgeLogger, noopLogger } from "./logger.ts";
+
+export interface ActionCableCallbacks {
+  onConnected(): void;
+  onDisconnected(intentional: boolean, reason: string): void;
+  onMessage(identifier: string, message: unknown): void;
+  onConfirm(identifier: string): void;
+  onReject(identifier: string): void;
+}
+
+const BASE_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 120_000;
+const MAX_RECONNECT_ATTEMPTS = 8;
+
+export class ActionCableClient {
+  private ws: WebSocket | null = null;
+  private reconnectAttempt = 0;
+  private intentionalDisconnect = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly wsUrl: string;
+  private readonly originUrl: string;
+  private readonly log: ForgeLogger;
+  private readonly logContext: string;
+
+  constructor(
+    baseURL: string,
+    private readonly token: string,
+    private readonly callbacks: ActionCableCallbacks,
+    options: { logger?: ForgeLogger; logContext?: string } = {},
+  ) {
+    this.log = options.logger ?? noopLogger;
+    this.logContext = options.logContext ?? "";
+    const stripped = baseURL.replace(/\/$/, "");
+    this.originUrl = stripped;
+    this.wsUrl =
+      stripped.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://") + "/-/cable";
+  }
+
+  connect(): void {
+    this.intentionalDisconnect = false;
+    this.reconnectAttempt = 0;
+    this.performConnect();
+  }
+
+  disconnect(): void {
+    this.intentionalDisconnect = true;
+    this.cleanup();
+    this.log.info("ActionCable intentionally disconnected", {
+      url: this.wsUrl,
+      ctx: this.logContext,
+    });
+  }
+
+  subscribe(identifier: string): void {
+    this.send({ command: "subscribe", identifier });
+  }
+
+  unsubscribe(identifier: string): void {
+    this.send({ command: "unsubscribe", identifier });
+  }
+
+  private performConnect(): void {
+    this.cleanup();
+
+    let ws: WebSocket;
+    try {
+      // Bun extends the standard WebSocket constructor to accept an options object
+      // with a `headers` field (Bun-specific, not in the browser WebSocket API).
+      ws = new WebSocket(
+        this.wsUrl,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        {
+          headers: {
+            Authorization: `Bearer ${this.token}`,
+            Origin: this.originUrl,
+          },
+        } as any,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log.error("ActionCable failed to create WebSocket", {
+        url: this.wsUrl,
+        message,
+        ctx: this.logContext,
+      });
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws = ws;
+
+    ws.onmessage = (event: MessageEvent) => {
+      const raw = typeof event.data === "string" ? event.data : String(event.data);
+      this.handleMessage(raw);
+    };
+
+    ws.onclose = (event: CloseEvent) => {
+      if (this.intentionalDisconnect) {
+        this.callbacks.onDisconnected(true, "intentional disconnect");
+      } else {
+        const reason = event.reason || `code ${event.code}`;
+        this.log.warn("ActionCable disconnected", {
+          url: this.wsUrl,
+          reason,
+          ctx: this.logContext,
+        });
+        this.callbacks.onDisconnected(false, reason);
+        this.scheduleReconnect();
+      }
+    };
+
+    ws.onerror = () => {
+      // onclose always fires after onerror and handles the reconnect schedule.
+      this.log.warn("ActionCable WebSocket error", { url: this.wsUrl, ctx: this.logContext });
+    };
+
+    this.log.info("ActionCable connecting", { url: this.wsUrl, ctx: this.logContext });
+  }
+
+  private handleMessage(raw: string): void {
+    let msg: {
+      type?: string;
+      identifier?: string;
+      message?: unknown;
+      reason?: string;
+      reconnect?: boolean;
+    };
+    try {
+      msg = JSON.parse(raw) as typeof msg;
+    } catch {
+      return;
+    }
+
+    if (!msg.type) {
+      // Data message — no "type" field present.
+      if (typeof msg.identifier === "string" && msg.message !== undefined) {
+        this.callbacks.onMessage(msg.identifier, msg.message);
+      }
+      return;
+    }
+
+    switch (msg.type) {
+      case "welcome":
+        this.reconnectAttempt = 0;
+        this.log.info("ActionCable connected (welcome)", { url: this.wsUrl, ctx: this.logContext });
+        this.callbacks.onConnected();
+        break;
+
+      case "ping":
+        // Server heartbeat — no response needed.
+        break;
+
+      case "confirm_subscription":
+        if (typeof msg.identifier === "string") {
+          this.log.debug("ActionCable subscription confirmed", { ctx: this.logContext });
+          this.callbacks.onConfirm(msg.identifier);
+        }
+        break;
+
+      case "reject_subscription":
+        if (typeof msg.identifier === "string") {
+          this.log.warn("ActionCable subscription rejected", { ctx: this.logContext });
+          this.callbacks.onReject(msg.identifier);
+        }
+        break;
+
+      case "disconnect": {
+        const shouldReconnect = msg.reconnect !== false;
+        this.log.info("ActionCable server disconnect", {
+          reason: msg.reason,
+          reconnect: shouldReconnect,
+          ctx: this.logContext,
+        });
+        if (!shouldReconnect) this.intentionalDisconnect = true;
+        this.callbacks.onDisconnected(!shouldReconnect, msg.reason ?? "server disconnect");
+        break;
+      }
+    }
+  }
+
+  private send(obj: Record<string, unknown>): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(obj));
+    }
+  }
+
+  private cleanup(): void {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws !== null) {
+      this.ws.onmessage = null;
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempt >= MAX_RECONNECT_ATTEMPTS) {
+      this.log.error("ActionCable max reconnect attempts reached", {
+        url: this.wsUrl,
+        ctx: this.logContext,
+      });
+      return;
+    }
+
+    const base = BASE_RECONNECT_DELAY_MS * Math.pow(2, this.reconnectAttempt);
+    const jitter = Math.random() * base * 0.3;
+    const delayMs = Math.min(base + jitter, MAX_RECONNECT_DELAY_MS);
+    this.reconnectAttempt++;
+
+    this.log.info("ActionCable scheduling reconnect", {
+      attempt: this.reconnectAttempt,
+      delayMs: Math.round(delayMs),
+      ctx: this.logContext,
+    });
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (!this.intentionalDisconnect) {
+        this.performConnect();
+      }
+    }, delayMs);
+  }
+}