@simplysf/simply-gitlab-core 0.1.0

package/lib/errors.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Base class for every error this CLI raises deliberately. Commands surface these through
+ * oclif's `this.error(message, { exit })` so users get formatted output rather than a stack
+ * trace for expected failure modes.
+ */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+/** Missing, malformed, or self-contradictory configuration. */
+export class ConfigError extends CliError {
+    constructor(message) {
+        super(message, 2);
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * The instance rejected our credentials. Carries the status because 401 and 403 call for
+ * different responses: bad credentials versus a valid account without the needed permission.
+ */
+export class AuthError extends CliError {
+    status;
+    constructor(message, status) {
+        super(message, 3);
+        this.name = 'AuthError';
+        this.status = status;
+    }
+}
+/** The instance never answered: timeout, DNS miss, refused connection, or an untrusted certificate. */
+export class NetworkError extends CliError {
+    constructor(message) {
+        super(message, 1);
+        this.name = 'NetworkError';
+    }
+}
+/** Any other non-2xx response, carrying the status and whatever body came back. */
+export class HttpError extends CliError {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message, 1);
+        this.name = 'HttpError';
+        this.status = status;
+        this.body = body;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjB,QAAQ,CAAS;IAEjC,YAAmB,OAAe,EAAE,QAAQ,GAAG,CAAC;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,WAAY,SAAQ,QAAQ;IACvC,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrB,MAAM,CAAS;IAE/B,YAAmB,OAAe,EAAE,MAAc;QAChD,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,uGAAuG;AACvG,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrB,MAAM,CAAS;IACf,IAAI,CAAU;IAE9B,YAAmB,OAAe,EAAE,MAAc,EAAE,IAAc;QAChE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/lib/gitlab-client.d.ts

@@ -0,0 +1,137 @@
+import type { GitLabConfig } from './config.js';
+/** Everything a caller needs after following pages: the items plus why paging stopped. */
+export interface ListResult<T = unknown> {
+    readonly items: readonly T[];
+    /** The instance's reported match count, when it reports one. */
+    readonly total?: number;
+    readonly pages: number;
+    /** False when the caller's limit cut the results short. */
+    readonly complete: boolean;
+}
+export type ProjectRef = string | number;
+export interface ListProjectsOptions {
+    readonly membership?: boolean;
+    readonly owned?: boolean;
+    readonly simple?: boolean;
+    readonly search?: string;
+    readonly orderBy?: string;
+    readonly sort?: 'asc' | 'desc';
+}
+export interface ListBranchesOptions {
+    readonly search?: string;
+}
+export interface ListTagsOptions {
+    readonly search?: string;
+    readonly orderBy?: string;
+    readonly sort?: 'asc' | 'desc';
+}
+export interface ListCommitsOptions {
+    readonly ref?: string;
+    readonly since?: string;
+    readonly until?: string;
+    readonly path?: string;
+    readonly author?: string;
+    readonly withStats?: boolean;
+}
+export type MergeRequestState = 'opened' | 'closed' | 'locked' | 'merged' | 'all';
+export interface ListMergeRequestsOptions {
+    readonly state?: MergeRequestState;
+    readonly sourceBranch?: string;
+    readonly targetBranch?: string;
+    readonly search?: string;
+    readonly authorUsername?: string;
+    readonly reviewerUsername?: string;
+    readonly labels?: readonly string[];
+    readonly orderBy?: string;
+    readonly sort?: 'asc' | 'desc';
+}
+export type JobScope = 'created' | 'pending' | 'running' | 'failed' | 'success' | 'canceled' | 'skipped' | 'waiting_for_resource' | 'manual';
+export interface ListJobsOptions {
+    readonly scope?: readonly JobScope[];
+}
+export interface ListEnvironmentsOptions {
+    readonly name?: string;
+    readonly search?: string;
+    readonly states?: 'available' | 'stopped';
+}
+export type SearchScope = 'projects' | 'issues' | 'merge_requests' | 'milestones' | 'wiki_blobs' | 'commits' | 'blobs' | 'notes' | 'users' | 'snippet_titles';
+export interface SearchOptions {
+    readonly scope: SearchScope;
+    readonly search: string;
+    /** Narrow to one project. Mutually exclusive with `group`. */
+    readonly project?: ProjectRef;
+    /** Narrow to one group. Mutually exclusive with `project`. */
+    readonly group?: ProjectRef;
+    /** Only meaningful for the `blobs` scope: a `filename:`/`path:`-style filter GitLab understands. */
+    readonly ref?: string;
+}
+export interface FileOptions {
+    readonly ref: string;
+}
+export interface WriteFileInput {
+    readonly branch: string;
+    readonly content: string;
+    readonly commitMessage: string;
+    readonly encoding?: 'text' | 'base64';
+    readonly authorEmail?: string;
+    readonly authorName?: string;
+    readonly startBranch?: string;
+    /** Update only: the last known commit id for the file, so a concurrent edit is rejected. */
+    readonly lastCommitId?: string;
+}
+export interface CommitAction {
+    readonly action: 'create' | 'delete' | 'move' | 'update' | 'chmod';
+    readonly file_path: string;
+    readonly previous_path?: string;
+    readonly content?: string;
+    readonly encoding?: 'text' | 'base64';
+    readonly last_commit_id?: string;
+    readonly execute_filemode?: boolean;
+}
+/**
+ * GitLab REST client. Owns the two things callers should never have to think about: addressing a
+ * project by path rather than id, and following offset pagination to a caller's limit while
+ * reporting honestly whether anything was left behind.
+ */
+export declare class GitLabClient {
+    /** The instance this client talks to, for callers that need to render a URL beside a result. */
+    readonly url: string;
+    private readonly transport;
+    constructor(config: GitLabConfig);
+    listProjects(options?: ListProjectsOptions, limit?: number): Promise<ListResult>;
+    getProject(project: ProjectRef): Promise<unknown>;
+    getFile(project: ProjectRef, filePath: string, options: FileOptions): Promise<unknown>;
+    createFile(project: ProjectRef, filePath: string, input: WriteFileInput): Promise<unknown>;
+    updateFile(project: ProjectRef, filePath: string, input: WriteFileInput): Promise<unknown>;
+    listBranches(project: ProjectRef, options?: ListBranchesOptions, limit?: number): Promise<ListResult>;
+    createBranch(project: ProjectRef, branch: string, ref: string): Promise<unknown>;
+    listCommits(project: ProjectRef, options?: ListCommitsOptions, limit?: number): Promise<ListResult>;
+    getCommit(project: ProjectRef, sha: string): Promise<unknown>;
+    getCommitDiff(project: ProjectRef, sha: string): Promise<unknown>;
+    createCommit(project: ProjectRef, body: Record<string, unknown>): Promise<unknown>;
+    listMergeRequests(project: ProjectRef, options?: ListMergeRequestsOptions, limit?: number): Promise<ListResult>;
+    getMergeRequest(project: ProjectRef, iid: number): Promise<unknown>;
+    createMergeRequest(project: ProjectRef, body: Record<string, unknown>): Promise<unknown>;
+    updateMergeRequest(project: ProjectRef, iid: number, body: Record<string, unknown>): Promise<unknown>;
+    listTags(project: ProjectRef, options?: ListTagsOptions, limit?: number): Promise<ListResult>;
+    listJobs(project: ProjectRef, options?: ListJobsOptions, limit?: number): Promise<ListResult>;
+    /** A job's trace is plain text, sometimes megabytes of it, and is never JSON. */
+    getJobLog(project: ProjectRef, jobId: number): Promise<string>;
+    listVariables(project: ProjectRef, limit?: number): Promise<ListResult>;
+    listEnvironments(project: ProjectRef, options?: ListEnvironmentsOptions, limit?: number): Promise<ListResult>;
+    listReleases(project: ProjectRef, limit?: number): Promise<ListResult>;
+    /**
+     * Global, group, or project search. GitLab exposes these as three separate endpoints rather
+     * than one endpoint with a filter, and the scopes each accepts differ, so the caller's choice
+     * of `project` or `group` selects the route instead of becoming a query parameter.
+     */
+    search(options: SearchOptions, limit?: number): Promise<ListResult>;
+    private request;
+    /**
+     * Follows offset pagination until the limit is reached or the instance says there is no next
+     * page, and reports which of the two happened. A caller that gets `complete: false` was cut
+     * short by its own limit and knows more exists — the alternative, returning a short list with
+     * no signal, is how a partial answer gets mistaken for the whole one.
+     */
+    private collect;
+}

package/lib/gitlab-client.js

@@ -0,0 +1,250 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { buildAuthHeaders } from './auth.js';
+import { ConfigError } from './errors.js';
+import { HttpTransport } from './http.js';
+/** GitLab's own ceiling on `per_page`; asking for more is silently clamped to it. */
+const MAX_PER_PAGE = 100;
+/** How many pages one list call will follow before giving up, however small the page size. */
+const MAX_PAGES = 100;
+const API_BASE = '/api/v4';
+/**
+ * A path segment built from user input. GitLab addresses a project either by numeric id or by its
+ * URL-encoded full path, so `group/project` has to arrive as `group%2Fproject` — an un-encoded
+ * slash reads as a different route entirely and answers 404 with nothing pointing at the cause.
+ */
+function segment(value) {
+    const text = String(value).trim();
+    if (text === '')
+        throw new ConfigError('A project id or path is required, but an empty value was given.');
+    return encodeURIComponent(text);
+}
+/** Drops the entries a caller left unset so they never reach the query string as "undefined". */
+function query(pairs) {
+    return Object.fromEntries(Object.entries(pairs).filter(([, value]) => value !== undefined));
+}
+/**
+ * GitLab REST client. Owns the two things callers should never have to think about: addressing a
+ * project by path rather than id, and following offset pagination to a caller's limit while
+ * reporting honestly whether anything was left behind.
+ */
+export class GitLabClient {
+    /** The instance this client talks to, for callers that need to render a URL beside a result. */
+    url;
+    transport;
+    constructor(config) {
+        this.url = config.url;
+        this.transport = new HttpTransport({
+            baseUrl: config.url,
+            headers: buildAuthHeaders(config),
+        });
+    }
+    // --- Projects ---
+    listProjects(options = {}, limit = 20) {
+        return this.collect('/projects', query({
+            membership: options.membership,
+            owned: options.owned,
+            simple: options.simple,
+            search: options.search,
+            order_by: options.orderBy,
+            sort: options.sort,
+        }), limit);
+    }
+    async getProject(project) {
+        return this.request(`/projects/${segment(project)}`, { method: 'GET' });
+    }
+    // --- Repository files ---
+    async getFile(project, filePath, options) {
+        return this.request(`/projects/${segment(project)}/repository/files/${segment(filePath)}`, {
+            method: 'GET',
+            query: { ref: options.ref },
+        });
+    }
+    async createFile(project, filePath, input) {
+        return this.request(`/projects/${segment(project)}/repository/files/${segment(filePath)}`, {
+            method: 'POST',
+            body: fileBody(input),
+            mutating: true,
+        });
+    }
+    async updateFile(project, filePath, input) {
+        return this.request(`/projects/${segment(project)}/repository/files/${segment(filePath)}`, {
+            method: 'PUT',
+            body: fileBody(input),
+            mutating: true,
+        });
+    }
+    // --- Branches ---
+    async listBranches(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/repository/branches`, query({ search: options.search }), limit);
+    }
+    async createBranch(project, branch, ref) {
+        return this.request(`/projects/${segment(project)}/repository/branches`, {
+            method: 'POST',
+            body: { branch, ref },
+            mutating: true,
+        });
+    }
+    // --- Commits ---
+    async listCommits(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/repository/commits`, query({
+            ref_name: options.ref,
+            since: options.since,
+            until: options.until,
+            path: options.path,
+            author: options.author,
+            with_stats: options.withStats,
+        }), limit);
+    }
+    async getCommit(project, sha) {
+        return this.request(`/projects/${segment(project)}/repository/commits/${segment(sha)}`, { method: 'GET' });
+    }
+    async getCommitDiff(project, sha) {
+        return this.request(`/projects/${segment(project)}/repository/commits/${segment(sha)}/diff`, { method: 'GET' });
+    }
+    async createCommit(project, body) {
+        return this.request(`/projects/${segment(project)}/repository/commits`, { method: 'POST', body, mutating: true });
+    }
+    // --- Merge requests ---
+    async listMergeRequests(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/merge_requests`, query({
+            state: options.state,
+            source_branch: options.sourceBranch,
+            target_branch: options.targetBranch,
+            search: options.search,
+            author_username: options.authorUsername,
+            reviewer_username: options.reviewerUsername,
+            labels: options.labels === undefined ? undefined : options.labels.join(','),
+            order_by: options.orderBy,
+            sort: options.sort,
+        }), limit);
+    }
+    async getMergeRequest(project, iid) {
+        return this.request(`/projects/${segment(project)}/merge_requests/${iid}`, { method: 'GET' });
+    }
+    async createMergeRequest(project, body) {
+        return this.request(`/projects/${segment(project)}/merge_requests`, { method: 'POST', body, mutating: true });
+    }
+    async updateMergeRequest(project, iid, body) {
+        return this.request(`/projects/${segment(project)}/merge_requests/${iid}`, {
+            method: 'PUT',
+            body,
+            mutating: true,
+        });
+    }
+    // --- Tags ---
+    async listTags(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/repository/tags`, query({ search: options.search, order_by: options.orderBy, sort: options.sort }), limit);
+    }
+    // --- CI/CD ---
+    async listJobs(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/jobs`, query({ scope: options.scope }), limit);
+    }
+    /** A job's trace is plain text, sometimes megabytes of it, and is never JSON. */
+    async getJobLog(project, jobId) {
+        return this.transport.text({
+            method: 'GET',
+            path: `${API_BASE}/projects/${segment(project)}/jobs/${jobId}/trace`,
+        });
+    }
+    async listVariables(project, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/variables`, {}, limit);
+    }
+    async listEnvironments(project, options = {}, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/environments`, query({ name: options.name, search: options.search, states: options.states }), limit);
+    }
+    // --- Releases ---
+    async listReleases(project, limit = 20) {
+        return this.collect(`/projects/${segment(project)}/releases`, {}, limit);
+    }
+    // --- Search ---
+    /**
+     * Global, group, or project search. GitLab exposes these as three separate endpoints rather
+     * than one endpoint with a filter, and the scopes each accepts differ, so the caller's choice
+     * of `project` or `group` selects the route instead of becoming a query parameter.
+     */
+    async search(options, limit = 20) {
+        if (options.project !== undefined && options.group !== undefined) {
+            throw new ConfigError('Search within a project or within a group, not both.');
+        }
+        const path = options.project !== undefined
+            ? `/projects/${segment(options.project)}/search`
+            : options.group !== undefined
+                ? `/groups/${segment(options.group)}/search`
+                : '/search';
+        return this.collect(path, query({ scope: options.scope, search: options.search, ref: options.ref }), limit);
+    }
+    // --- Plumbing ---
+    request(path, call) {
+        return this.transport.json({ ...call, path: `${API_BASE}${path}` });
+    }
+    /**
+     * Follows offset pagination until the limit is reached or the instance says there is no next
+     * page, and reports which of the two happened. A caller that gets `complete: false` was cut
+     * short by its own limit and knows more exists — the alternative, returning a short list with
+     * no signal, is how a partial answer gets mistaken for the whole one.
+     */
+    async collect(path, params, limit) {
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new ConfigError(`A limit must be a positive whole number, got ${limit}.`);
+        }
+        const items = [];
+        let page = 1;
+        let pages = 0;
+        let total;
+        /* Paging is sequential by definition: each request needs the previous page's cursor. */
+        /* eslint-disable no-await-in-loop */
+        while (items.length < limit && pages < MAX_PAGES) {
+            const response = await this.transport.jsonPaged({
+                method: 'GET',
+                path: `${API_BASE}${path}`,
+                query: { ...params, per_page: Math.min(MAX_PER_PAGE, limit - items.length), page },
+            });
+            pages += 1;
+            total = response.pagination.total ?? total;
+            // Every list endpoint answers with a JSON array. A non-array here means the route matched
+            // something else — a redirect to a sign-in page, most often — and slicing it would produce
+            // a confidently empty list rather than an error.
+            if (!Array.isArray(response.data)) {
+                throw new ConfigError(`GET ${path} did not return a list. Check that the URL points at a GitLab instance.`);
+            }
+            items.push(...response.data);
+            const nextPage = response.pagination.nextPage;
+            // No next-page header, an empty page, or a cursor that fails to advance all mean the same
+            // thing: this was the last page. The last of the three matters because a misconfigured
+            // reverse proxy that strips or pins the header would otherwise loop until MAX_PAGES.
+            if (response.data.length === 0 || nextPage === undefined || nextPage <= page) {
+                return { items: items.slice(0, limit), total, pages, complete: true };
+            }
+            page = nextPage;
+        }
+        /* eslint-enable no-await-in-loop */
+        return { items: items.slice(0, limit), total, pages, complete: false };
+    }
+}
+function fileBody(input) {
+    return {
+        branch: input.branch,
+        content: input.content,
+        commit_message: input.commitMessage,
+        ...(input.encoding === undefined ? {} : { encoding: input.encoding }),
+        ...(input.authorEmail === undefined ? {} : { author_email: input.authorEmail }),
+        ...(input.authorName === undefined ? {} : { author_name: input.authorName }),
+        ...(input.startBranch === undefined ? {} : { start_branch: input.startBranch }),
+        ...(input.lastCommitId === undefined ? {} : { last_commit_id: input.lastCommitId }),
+    };
+}
+//# sourceMappingURL=gitlab-client.js.map

package/lib/gitlab-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitlab-client.js","sourceRoot":"","sources":["../src/gitlab-client.ts"],"names":[],"mappings":"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"}

package/lib/http.d.ts

@@ -0,0 +1,82 @@
+/** A single query value, or a repeated one — GitLab spells repeats `scope[]=a&scope[]=b`. */
+export type QueryValue = string | number | boolean | undefined | ReadonlyArray<string | number>;
+/** One REST call, relative to the transport's base URL. */
+export interface JsonCall {
+    readonly method: string;
+    readonly path: string;
+    readonly query?: Record<string, QueryValue>;
+    readonly body?: unknown;
+    /**
+     * Whether this call changes data. Declared by the caller rather than guessed from the verb,
+     * because the verb is not a reliable signal: GitLab's global search is a GET that a `read_api`
+     * token can run, while its markdown renderer is a POST that changes nothing. Guessing wrong
+     * here is worse than not guessing — see the 403 handling below.
+     */
+    readonly mutating?: boolean;
+}
+/** Where and how a transport talks: fixed per client instance. */
+export interface TransportTarget {
+    readonly baseUrl: string;
+    readonly headers: Record<string, string>;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+}
+/**
+ * GitLab's offset-pagination headers, as far as they were sent. Keyset-paginated endpoints and
+ * any endpoint whose result set is too large for GitLab to count omit the totals, so every field
+ * here is optional and a caller must treat a missing one as "unknown", never as zero.
+ */
+export interface Pagination {
+    readonly nextPage?: number;
+    readonly total?: number;
+    readonly totalPages?: number;
+    readonly perPage?: number;
+}
+/** A response body together with the pagination GitLab reported alongside it. */
+export interface Paged<T> {
+    readonly data: T;
+    readonly pagination: Pagination;
+}
+/**
+ * JSON-over-HTTPS transport bound to one GitLab instance. Each client owns one; everything that
+ * would otherwise be an argument (base URL, auth headers, timing) is fixed at construction so
+ * call sites stay small.
+ *
+ * Certificate verification is always on. An instance behind an internal or agency CA is
+ * supported by pointing Node at that CA — `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` — which keeps
+ * verification intact rather than turning it off.
+ */
+export declare class HttpTransport {
+    private readonly target;
+    private readonly timeoutMs;
+    private readonly maxAttempts;
+    constructor(target: TransportTarget);
+    /**
+     * Executes a call and parses the JSON response. 401/403 become `AuthError` immediately;
+     * 429/5xx retry with exponential backoff, deferring to a (capped) `Retry-After` when one is
+     * sent; other non-2xx become `HttpError`. Timeouts, DNS misses, and certificate failures
+     * become `NetworkError` without pointless retries; transient socket failures retry. The
+     * timeout covers the whole exchange, response body included.
+     */
+    json<T>(call: JsonCall): Promise<T>;
+    /**
+     * The same call as {@link json}, keeping the pagination headers GitLab answered with. Separate
+     * from `json` because pagination is only meaningful for list endpoints, and a caller that
+     * ignored the headers on one would silently return a first page as if it were everything.
+     */
+    jsonPaged<T>(call: JsonCall): Promise<Paged<T>>;
+    /**
+     * Executes a call whose response is not JSON and returns it verbatim.
+     *
+     * Job traces are plain text and repository file contents can be raw bytes; parsing either as
+     * JSON would fail on the successful case. Errors on these endpoints still come back as JSON,
+     * and are still raised as `HttpError`, because the failure path is shared.
+     */
+    text(call: JsonCall): Promise<string>;
+    private send;
+    /** Runs one attempt under a deadline that spans connection, headers, AND body. */
+    private attempt;
+    /** Wraps raw transport failures in typed, user-explainable errors; rethrows deliberate ones. */
+    private triage;
+    private resolve;
+}