@forge-glance/sdk 0.1.0

package/dist/GitLabProvider.js

@@ -0,0 +1,359 @@
+// src/logger.ts
+var noopLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {}
+};
+
+// src/MRDetailFetcher.ts
+class MRDetailFetcher {
+  baseURL;
+  token;
+  log;
+  constructor(baseURL, token, options = {}) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+    this.log = options.logger ?? noopLogger;
+  }
+  async fetchDetail(projectId, mrIid) {
+    const url = `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/discussions?per_page=100`;
+    const res = await fetch(url, {
+      headers: { "PRIVATE-TOKEN": this.token }
+    });
+    if (!res.ok) {
+      throw new Error(`MR discussions fetch failed: ${res.status} ${res.statusText}`);
+    }
+    const raw = await res.json();
+    const discussions = raw.map((d) => ({
+      id: d.id,
+      resolvable: null,
+      resolved: null,
+      notes: d.notes.map(toNote)
+    }));
+    this.log.debug("MRDetailFetcher.fetchDetail", {
+      projectId,
+      mrIid,
+      discussionCount: discussions.length
+    });
+    return { mrIid, repositoryId: `gitlab:${projectId}`, discussions };
+  }
+}
+function toNote(n) {
+  return {
+    id: n.id,
+    body: n.body,
+    author: toAuthor(n.author),
+    createdAt: n.created_at,
+    system: n.system,
+    type: n.type,
+    resolvable: n.resolvable ?? null,
+    resolved: n.resolved ?? null,
+    position: n.position ? toPosition(n.position) : null
+  };
+}
+function toAuthor(a) {
+  return {
+    id: `gitlab:user:${a.id}`,
+    username: a.username,
+    name: a.name,
+    avatarUrl: a.avatar_url
+  };
+}
+function toPosition(p) {
+  return {
+    newPath: p.new_path ?? null,
+    oldPath: p.old_path ?? null,
+    newLine: p.new_line ?? null,
+    oldLine: p.old_line ?? null,
+    positionType: p.position_type ?? null
+  };
+}
+
+// src/GitLabProvider.ts
+function parseGitLabRepoId(repositoryId) {
+  const parts = repositoryId.split(":");
+  return parseInt(parts.at(-1) ?? "0", 10);
+}
+var MR_DASHBOARD_FRAGMENT = `
+  fragment MRDashboardFields on MergeRequest {
+    id iid projectId title description state draft
+    sourceBranch targetBranch webUrl
+    diffHeadSha
+    updatedAt createdAt
+    conflicts
+    detailedMergeStatus
+    approved
+    diffStatsSummary { additions deletions fileCount }
+    author { id username name avatarUrl }
+    assignees(first: 20) { nodes { id username name avatarUrl } }
+    reviewers(first: 20) { nodes { id username name avatarUrl } }
+    approvedBy(first: 20) { nodes { id username name avatarUrl } }
+    approvalsLeft
+    resolvableDiscussionsCount
+    resolvedDiscussionsCount
+    headPipeline {
+      id iid status
+      createdAt
+      path
+      stages(first: 20) { nodes {
+        name
+        jobs(first: 50) { nodes {
+          id name status
+          allowFailure
+          webPath
+          stage { name }
+        }}
+      }}
+    }
+  }
+`;
+var AUTHORED_QUERY = `
+  query GlanceDashboardAuthored {
+    currentUser {
+      authoredMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+var REVIEWING_QUERY = `
+  query GlanceDashboardReviewing {
+    currentUser {
+      reviewRequestedMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+var ASSIGNED_QUERY = `
+  query GlanceDashboardAssigned {
+    currentUser {
+      assignedMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+function numericId(gid) {
+  const parts = gid.split("/");
+  return parseInt(parts[parts.length - 1] ?? "0", 10);
+}
+function domainId(type, id) {
+  return `gitlab:${type}:${id}`;
+}
+function toUserRef(u) {
+  return {
+    id: `gitlab:user:${numericId(u.id)}`,
+    username: u.username,
+    name: u.name,
+    avatarUrl: u.avatarUrl
+  };
+}
+function toPipeline(p, baseURL) {
+  const allJobs = p.stages.nodes.flatMap((stage) => stage.jobs.nodes.map((job) => ({
+    id: `gitlab:job:${numericId(job.id)}`,
+    name: job.name,
+    stage: job.stage.name,
+    status: job.status,
+    allowFailure: job.allowFailure,
+    webUrl: job.webPath ? `${baseURL}${job.webPath}` : null
+  })));
+  return {
+    id: domainId("pipeline", numericId(p.id)),
+    status: normalizePipelineStatus(p),
+    createdAt: p.createdAt,
+    webUrl: p.path ? `${baseURL}${p.path}` : null,
+    jobs: allJobs
+  };
+}
+function normalizePipelineStatus(p) {
+  const allJobs = p.stages.nodes.flatMap((s) => s.jobs.nodes);
+  const hasAllowFailFailed = allJobs.some((j) => j.allowFailure && j.status === "failed");
+  if (p.status === "success" && hasAllowFailFailed) {
+    return "success_with_warnings";
+  }
+  return p.status;
+}
+function toMR(gql, role, baseURL) {
+  const resolvable = gql.resolvableDiscussionsCount ?? 0;
+  const resolved = gql.resolvedDiscussionsCount ?? 0;
+  const unresolvedThreadCount = Math.max(0, resolvable - resolved);
+  const diffStats = gql.diffStatsSummary ? {
+    additions: gql.diffStatsSummary.additions,
+    deletions: gql.diffStatsSummary.deletions,
+    filesChanged: gql.diffStatsSummary.fileCount
+  } : null;
+  return {
+    id: `gitlab:mr:${numericId(gql.id)}`,
+    iid: parseInt(gql.iid, 10),
+    repositoryId: `gitlab:${gql.projectId}`,
+    title: gql.title,
+    description: gql.description ?? null,
+    state: gql.state,
+    draft: gql.draft,
+    conflicts: gql.conflicts || gql.detailedMergeStatus === "conflict",
+    webUrl: gql.webUrl,
+    sourceBranch: gql.sourceBranch,
+    targetBranch: gql.targetBranch,
+    createdAt: gql.createdAt,
+    updatedAt: gql.updatedAt,
+    sha: gql.diffHeadSha,
+    author: toUserRef(gql.author),
+    assignees: gql.assignees.nodes.map(toUserRef),
+    reviewers: gql.reviewers.nodes.map(toUserRef),
+    roles: [role],
+    pipeline: gql.headPipeline ? toPipeline(gql.headPipeline, baseURL) : null,
+    unresolvedThreadCount,
+    approvalsLeft: gql.approvalsLeft ?? 0,
+    approved: gql.approved ?? false,
+    approvedBy: gql.approvedBy.nodes.map(toUserRef),
+    diffStats,
+    detailedMergeStatus: gql.detailedMergeStatus ?? null
+  };
+}
+var MR_DETAIL_QUERY = `
+  query GlanceMRDetail($projectPath: ID!, $iid: String!) {
+    project(fullPath: $projectPath) {
+      mergeRequest(iid: $iid) {
+        ...MRDashboardFields
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+
+class GitLabProvider {
+  providerName = "gitlab";
+  baseURL;
+  token;
+  log;
+  mrDetailFetcher;
+  constructor(baseURL, token, options = {}) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+    this.log = options.logger ?? noopLogger;
+    this.mrDetailFetcher = new MRDetailFetcher(this.baseURL, token, { logger: this.log });
+  }
+  async validateToken() {
+    const url = `${this.baseURL}/api/v4/user`;
+    const res = await fetch(url, {
+      headers: { "PRIVATE-TOKEN": this.token }
+    });
+    if (!res.ok) {
+      throw new Error(`Token validation failed: ${res.status} ${res.statusText}`);
+    }
+    const user = await res.json();
+    return {
+      id: `gitlab:user:${user.id}`,
+      username: user.username,
+      name: user.name,
+      avatarUrl: user.avatar_url
+    };
+  }
+  async fetchSingleMR(projectPath, mrIid, currentUserNumericId) {
+    let resp;
+    try {
+      resp = await this.runQuery(MR_DETAIL_QUERY, {
+        projectPath,
+        iid: String(mrIid)
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log.warn("fetchSingleMR failed", { projectPath, mrIid, message });
+      return null;
+    }
+    const gql = resp.project?.mergeRequest;
+    if (!gql)
+      return null;
+    const roles = [];
+    if (currentUserNumericId !== null) {
+      const userGqlId = `gid://gitlab/User/${currentUserNumericId}`;
+      if (gql.author.id === userGqlId)
+        roles.push("author");
+      if (gql.assignees.nodes.some((u) => u.id === userGqlId))
+        roles.push("assignee");
+      if (gql.reviewers.nodes.some((u) => u.id === userGqlId))
+        roles.push("reviewer");
+    }
+    const pr = toMR(gql, roles[0] ?? "author", this.baseURL);
+    pr.roles = roles.length > 0 ? roles : pr.roles;
+    return pr;
+  }
+  async fetchPullRequests() {
+    const [authored, reviewing, assigned] = await Promise.all([
+      this.runQuery(AUTHORED_QUERY),
+      this.runQuery(REVIEWING_QUERY),
+      this.runQuery(ASSIGNED_QUERY)
+    ]);
+    const byId = new Map;
+    const addAll = (mrs, role) => {
+      for (const gql of mrs) {
+        const existing = byId.get(gql.id);
+        if (existing) {
+          if (!existing.roles.includes(role)) {
+            existing.roles.push(role);
+          }
+        } else {
+          byId.set(gql.id, toMR(gql, role, this.baseURL));
+        }
+      }
+    };
+    addAll(authored.currentUser.authoredMergeRequests.nodes, "author");
+    addAll(reviewing.currentUser.reviewRequestedMergeRequests.nodes, "reviewer");
+    addAll(assigned.currentUser.assignedMergeRequests.nodes, "assignee");
+    const prs = [...byId.values()];
+    this.log.debug("fetchPullRequests", { count: prs.length });
+    return prs;
+  }
+  async fetchMRDiscussions(repositoryId, mrIid) {
+    const projectId = parseGitLabRepoId(repositoryId);
+    return this.mrDetailFetcher.fetchDetail(projectId, mrIid);
+  }
+  async restRequest(method, path, body) {
+    const url = `${this.baseURL}${path}`;
+    const headers = {
+      "PRIVATE-TOKEN": this.token
+    };
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+    return fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined
+    });
+  }
+  async runQuery(query, variables) {
+    const url = `${this.baseURL}/api/graphql`;
+    const body = JSON.stringify({ query, variables: variables ?? {} });
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`
+      },
+      body
+    });
+    if (!res.ok) {
+      throw new Error(`GraphQL request failed: ${res.status} ${res.statusText}`);
+    }
+    const envelope = await res.json();
+    if (envelope.errors?.length) {
+      const msg = envelope.errors.map((e) => e.message).join("; ");
+      throw new Error(`GraphQL errors: ${msg}`);
+    }
+    if (!envelope.data) {
+      throw new Error("GraphQL response missing data");
+    }
+    return envelope.data;
+  }
+}
+export {
+  parseGitLabRepoId,
+  MR_DASHBOARD_FRAGMENT,
+  GitLabProvider
+};

package/dist/GitProvider.d.ts

@@ -0,0 +1,50 @@
+import type { MRDetail, PullRequest, UserRef } from "./types.ts";
+/**
+ * Provider-agnostic interface for a Git hosting service.
+ *
+ * `GitLabProvider` implements this today; `GitHubProvider` will follow.
+ * `Connection` stores a `GitProvider` and uses only this interface — it never
+ * reaches into provider-specific internals.
+ */
+export interface GitProvider {
+    /** The provider slug stored in `connected_accounts.provider`. */
+    readonly providerName: string;
+    /** The base URL for this provider instance, e.g. "https://gitlab.com". */
+    readonly baseURL: string;
+    /** Validate the stored credentials and return the authenticated user. */
+    validateToken(): Promise<UserRef>;
+    /**
+     * Fetch all pull/merge requests the current user is involved in
+     * (authored, assigned, reviewing).
+     */
+    fetchPullRequests(): Promise<PullRequest[]>;
+    /**
+     * Fetch a single MR/PR by project path and IID.
+     * Returns null if the project or MR doesn't exist.
+     * Used by SubscriptionManager for real-time update handling.
+     */
+    fetchSingleMR(projectPath: string, mrIid: number, currentUserNumericId: number | null): Promise<PullRequest | null>;
+    /**
+     * Fetch discussions (comments, threads) for a specific MR/PR.
+     * Returns the MRDetail with discussions populated.
+     */
+    fetchMRDiscussions(repositoryId: string, mrIid: number): Promise<MRDetail>;
+    /**
+     * Make an authenticated REST API request to the provider.
+     * Used for operations that don't have a typed method yet (job traces,
+     * pipeline retries, etc.).
+     *
+     * Implementations translate the path to the provider's API URL format.
+     */
+    restRequest(method: string, path: string, body?: unknown): Promise<Response>;
+}
+/**
+ * Parse the numeric project/repo ID from a scoped repositoryId string.
+ * e.g. "gitlab:42" → 42, "github:12345" → 12345
+ */
+export declare function parseRepoId(repositoryId: string): number;
+/**
+ * Extract the provider prefix from a scoped repositoryId.
+ * e.g. "gitlab:42" → "gitlab", "github:12345" → "github"
+ */
+export declare function repoIdProvider(repositoryId: string): string;

package/dist/GitProvider.js

@@ -0,0 +1,12 @@
+// src/GitProvider.ts
+function parseRepoId(repositoryId) {
+  const parts = repositoryId.split(":");
+  return parseInt(parts.at(-1) ?? "0", 10);
+}
+function repoIdProvider(repositoryId) {
+  return repositoryId.split(":")[0] ?? "unknown";
+}
+export {
+  repoIdProvider,
+  parseRepoId
+};

package/dist/MRDetailFetcher.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fetches MR detail (discussions) from GitLab via the REST API.
+ *
+ * Accepts numeric projectId for REST URL construction; returns DomainMRDetail
+ * with a scoped repositoryId string (e.g. "gitlab:42").
+ * Endpoint: GET /api/v4/projects/:id/merge_requests/:iid/discussions?per_page=100
+ */
+import type { MRDetail } from "./types.ts";
+import { type ForgeLogger } from "./logger.ts";
+export declare class MRDetailFetcher {
+    private readonly baseURL;
+    private readonly token;
+    private readonly log;
+    constructor(baseURL: string, token: string, options?: {
+        logger?: ForgeLogger;
+    });
+    fetchDetail(projectId: number, mrIid: number): Promise<MRDetail>;
+}

package/dist/MRDetailFetcher.js

@@ -0,0 +1,74 @@
+// src/logger.ts
+var noopLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {}
+};
+
+// src/MRDetailFetcher.ts
+class MRDetailFetcher {
+  baseURL;
+  token;
+  log;
+  constructor(baseURL, token, options = {}) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+    this.log = options.logger ?? noopLogger;
+  }
+  async fetchDetail(projectId, mrIid) {
+    const url = `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/discussions?per_page=100`;
+    const res = await fetch(url, {
+      headers: { "PRIVATE-TOKEN": this.token }
+    });
+    if (!res.ok) {
+      throw new Error(`MR discussions fetch failed: ${res.status} ${res.statusText}`);
+    }
+    const raw = await res.json();
+    const discussions = raw.map((d) => ({
+      id: d.id,
+      resolvable: null,
+      resolved: null,
+      notes: d.notes.map(toNote)
+    }));
+    this.log.debug("MRDetailFetcher.fetchDetail", {
+      projectId,
+      mrIid,
+      discussionCount: discussions.length
+    });
+    return { mrIid, repositoryId: `gitlab:${projectId}`, discussions };
+  }
+}
+function toNote(n) {
+  return {
+    id: n.id,
+    body: n.body,
+    author: toAuthor(n.author),
+    createdAt: n.created_at,
+    system: n.system,
+    type: n.type,
+    resolvable: n.resolvable ?? null,
+    resolved: n.resolved ?? null,
+    position: n.position ? toPosition(n.position) : null
+  };
+}
+function toAuthor(a) {
+  return {
+    id: `gitlab:user:${a.id}`,
+    username: a.username,
+    name: a.name,
+    avatarUrl: a.avatar_url
+  };
+}
+function toPosition(p) {
+  return {
+    newPath: p.new_path ?? null,
+    oldPath: p.old_path ?? null,
+    newLine: p.new_line ?? null,
+    oldLine: p.old_line ?? null,
+    positionType: p.position_type ?? null
+  };
+}
+export {
+  MRDetailFetcher
+};

package/dist/NoteMutator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare class NoteMutator {
+    private readonly baseURL;
+    private readonly token;
+    constructor(baseURL: string, token: string);
+    /**
+     * 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.
+     */
+    createNote(projectId: number, mrIid: number, body: string, discussionId?: string): Promise<CreatedNote>;
+    /** Edit the body of an existing note. */
+    updateNote(projectId: number, mrIid: number, noteId: number, body: string): Promise<void>;
+    /** Permanently delete a note. */
+    deleteNote(projectId: number, mrIid: number, noteId: number): Promise<void>;
+}

package/dist/NoteMutator.js

@@ -0,0 +1,54 @@
+// src/NoteMutator.ts
+class NoteMutator {
+  baseURL;
+  token;
+  constructor(baseURL, token) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+  }
+  async createNote(projectId, mrIid, body, discussionId) {
+    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();
+  }
+  async updateNote(projectId, mrIid, noteId, body) {
+    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}` : ""}`);
+    }
+  }
+  async deleteNote(projectId, mrIid, noteId) {
+    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}` : ""}`);
+    }
+  }
+}
+export {
+  NoteMutator
+};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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();
+ */
+export type { PullRequest, PullRequestsSnapshot, Pipeline, PipelineJob, UserRef, DiffStats, Discussion, Note, NoteAuthor, NotePosition, MRDetail, FeedEvent, FeedSnapshot, ServerNotification, } from "./types.ts";
+export type { GitProvider } from "./GitProvider.ts";
+export { parseRepoId, repoIdProvider } from "./GitProvider.ts";
+export type { ForgeLogger } from "./logger.ts";
+export { noopLogger } from "./logger.ts";
+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";
+export { ActionCableClient } from "./ActionCableClient.ts";
+export type { ActionCableCallbacks } from "./ActionCableClient.ts";
+export { MRDetailFetcher } from "./MRDetailFetcher.ts";
+export { NoteMutator } from "./NoteMutator.ts";
+export type { CreatedNote } from "./NoteMutator.ts";