patchwork-os 0.2.0-alpha.34 → 0.2.0-alpha.36

package/dist/connectors/gitlab.d.ts

@@ -0,0 +1,180 @@
+/**
+ * GitLab connector — read-only: projects, issues, merge requests, current user.
+ *
+ * OAuth 2.0 Authorization Code Grant. GitLab is a confidential client (bridge
+ * holds client secret), so PKCE is not used here. Refresh tokens are issued;
+ * access tokens default to 2 hours.
+ *
+ * Auth: standard OAuth 2.0 with `client_id` + `client_secret` + `redirect_uri`.
+ *   - Env vars: GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET (mirrors asana/discord)
+ *   - Optional: GITLAB_BASE_URL — override base for self-hosted GitLab.
+ *               Default https://gitlab.com. `/api/v4` is appended internally.
+ *   - Stored: getSecretJsonSync("gitlab") → GitLabTokens
+ *   - Header: Authorization: Bearer <access_token>
+ *
+ * Read-only scopes: read_user read_api read_repository.
+ *
+ * Read tools: getCurrentUser, listProjects, listIssues, getIssue,
+ *   listMergeRequests.
+ * Write methods (createIssue, createMergeRequestNote) are deferred to a
+ * follow-up PR.
+ *
+ * HTTP routes (wired in src/server.ts):
+ *   GET    /connections/gitlab/auth     — redirect to GitLab consent
+ *   GET    /connections/gitlab/callback — exchange code for tokens
+ *   POST   /connections/gitlab/test     — ping GitLab API
+ *   DELETE /connections/gitlab          — best-effort revoke + clear local
+ *
+ * Extends BaseConnector for unified auth, retry, rate-limit, error handling.
+ * Token refresh is delegated to BaseConnector.refreshToken() via apiCall.
+ */
+import { type AuthContext, BaseConnector, type ConnectorError, type ConnectorStatus, type OAuthConfig } from "./baseConnector.js";
+/**
+ * Base host for the GitLab instance, e.g. `https://gitlab.com` (default) or
+ * `https://gitlab.example.com` for self-hosted. Trailing slash trimmed; the
+ * `/api/v4` path is appended internally so users only configure host.
+ */
+export declare function gitlabBaseUrl(): string;
+export interface GitLabTokens {
+    access_token: string;
+    refresh_token?: string;
+    /** ms since epoch; absolute, not relative */
+    expires_at?: number;
+    scope?: string;
+    token_type?: string;
+    /** stored at auth time so refresh works even if env vars are absent */
+    _client_id?: string;
+    _client_secret?: string;
+    /** snapshot of base URL at connect time so refresh hits the right host */
+    _base_url?: string;
+    username?: string;
+    user_id?: number;
+    email?: string;
+    connected_at: string;
+}
+export interface GitLabUser {
+    id: number;
+    username: string;
+    name?: string;
+    email?: string;
+    avatar_url?: string | null;
+}
+export interface GitLabProject {
+    id: number;
+    name: string;
+    path_with_namespace: string;
+    description?: string | null;
+    web_url?: string;
+    default_branch?: string | null;
+    visibility?: string;
+    archived?: boolean;
+}
+export interface GitLabIssue {
+    id: number;
+    iid: number;
+    project_id: number;
+    title: string;
+    description?: string | null;
+    state: string;
+    web_url?: string;
+    author?: {
+        id: number;
+        username: string;
+        name?: string;
+    };
+    assignees?: Array<{
+        id: number;
+        username: string;
+        name?: string;
+    }>;
+    labels?: string[];
+    created_at?: string;
+    updated_at?: string;
+}
+export interface GitLabMergeRequest {
+    id: number;
+    iid: number;
+    project_id: number;
+    title: string;
+    description?: string | null;
+    state: string;
+    source_branch?: string;
+    target_branch?: string;
+    web_url?: string;
+    author?: {
+        id: number;
+        username: string;
+        name?: string;
+    };
+    draft?: boolean;
+    merge_status?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export declare function loadTokens(): GitLabTokens | null;
+export declare function saveTokens(tokens: GitLabTokens): void;
+export declare function clearTokens(): void;
+export declare function isConnected(): boolean;
+export declare class GitLabConnector extends BaseConnector {
+    readonly providerName = "gitlab";
+    protected getOAuthConfig(): OAuthConfig | null;
+    authenticate(): Promise<AuthContext>;
+    /**
+     * Persist refreshed tokens after BaseConnector.refreshToken() updates
+     * `this.auth`. Mirror to our GitLab-specific JSON so loadTokens() keeps
+     * working for HTTP probes.
+     */
+    saveTokens(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        error?: ConnectorError;
+    }>;
+    normalizeError(error: unknown): ConnectorError;
+    getStatus(): ConnectorStatus;
+    getCurrentUser(): Promise<GitLabUser>;
+    listProjects(params?: {
+        membership?: boolean;
+        owned?: boolean;
+        search?: string;
+        limit?: number;
+    }): Promise<GitLabProject[]>;
+    listIssues(params?: {
+        projectId?: string | number;
+        assignedToMe?: boolean;
+        state?: "opened" | "closed" | "all";
+        limit?: number;
+    }): Promise<GitLabIssue[]>;
+    getIssue(projectId: string | number, issueIid: number): Promise<GitLabIssue>;
+    listMergeRequests(params?: {
+        projectId?: string | number;
+        state?: "opened" | "closed" | "merged" | "all";
+        scope?: "created_by_me" | "assigned_to_me" | "all";
+        limit?: number;
+    }): Promise<GitLabMergeRequest[]>;
+    private buildHeaders;
+    private captureRateLimit;
+}
+export declare function getGitLabConnector(): GitLabConnector;
+export { getGitLabConnector as gitlab };
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+    redirect?: string;
+}
+/**
+ * GET /connections/gitlab/auth — redirect to GitLab consent screen.
+ */
+export declare function handleGitLabAuthorize(): ConnectorHandlerResult;
+/**
+ * GET /connections/gitlab/callback — exchange code for tokens.
+ */
+export declare function handleGitLabCallback(code: string | null, state: string | null, error: string | null): Promise<ConnectorHandlerResult>;
+/**
+ * POST /connections/gitlab/test — verify stored token works.
+ */
+export declare function handleGitLabTest(): Promise<ConnectorHandlerResult>;
+/**
+ * DELETE /connections/gitlab — best-effort revoke at GitLab + drop locally.
+ */
+export declare function handleGitLabDisconnect(): Promise<ConnectorHandlerResult>;