GitLabWrapperTS

Wrapper fortemente tipado para a API REST do GitLab v4 — Deno 2.0

O GitLabWrapperTS é um wrapper puramente back-end para a API REST do GitLab v4, construído para Deno 2.0 com foco em imutabilidade, rastreabilidade e facilidade de uso. Cada instância é isolada, imutável e pode ser usada simultaneamente em diferentes partes do sistema sem risco de contaminação de estado.

---

📖 Documentação

• Guia de Uso — Exemplos completos para todos os 25 recursos
• Getting Started — Instalação, configuração, primeira chamada
• Guia de Integração — Padrões de uso no dia-a-dia
• Particularidades da API — Quirks e observações importantes
• Referência da API — Lista completa de métodos e tipos
• Catálogo de Erros — Erros RFC 7807 com UUIDv7

🚀 Quick-start

Instalação:

deno    add jsr:@st-all-one/gitlab-wrapper-ts
pnpm      i jsr:@st-all-one/gitlab-wrapper-ts
yarn    add jsr:@st-all-one/gitlab-wrapper-ts
npx     jsr add @st-all-one/gitlab-wrapper-ts
bunx    jsr add @st-all-one/gitlab-wrapper-ts

Configuração:

import { GitLabWrapperTS } from "@st-all-one/gitlab-wrapper-ts";

const gl = GitLabWrapperTS.create({
    baseUrl: Deno.env.get("GITLAB_URL")!,
    token: Deno.env.get("GITLAB_TOKEN")!,
});

Uso básico:

// Projetos onde sou membro, com paginação automática
for await (const project of gl.projects.list({ membership: true })) {
    console.log(`${project.path_with_namespace}: ${project.description}`);
}

// Issues abertas de um projeto
const issues = await gl.issues.listForProject(42, { state: "opened" }).toArray();

// Criar issue
const issue = await gl.issues.createInProject(42, {
    title: "Bug encontrado",
    description: "Passos para reproduzir...",
    labels: "bug,prioridade-alta",
});

Tratamento de erros (RFC 7807):

import { GitLabWrapperError } from "@st-all-one/gitlab-wrapper-ts";

try {
    await gl.projects.get(99999);
} catch (err) {
    if (err instanceof GitLabWrapperError) {
        console.error(`[${err.instance}] ${err.detail}`);
        console.error(err.toJSON());
        // { type, title: "resource-not-found", status: 404,
        //   instance: "urn:uuid:0194d...", context: {...} }
    }
}

🌐 Recursos Cobertos

Resource	Status	Endpoints
Projects	Stable	CRUD, archive/unarchive, fork, transfer, avatar
Groups	Stable	CRUD, subgroups, descendants, projects
Users	Stable	CRUD, status, preferências, ban/activate
Issues	Stable	CRUD, subscribe, move, time estimates
Merge Requests	Stable	CRUD, merge, approve, rebase, commits
Branches	Stable	CRUD, delete merged
Commits	Stable	CRUD, cherry-pick, revert, diff, comments
Tags	Stable	CRUD, release notes
Repository Files	Stable	CRUD, raw, blame
Wikis	Alpha	CRUD, upload attachment
Labels	Alpha	CRUD, promote (project ↔ group)
Milestones	Alpha	CRUD, issues, merge requests
Members	Alpha	CRUD, inherited members
Notes	Alpha	CRUD (issues, MRs, commits, snippets, wikis)
Discussions	Alpha	CRUD, resolve threads
Todos	Alpha	List, mark done, mark all done
Search	Alpha	Global, group, project scoped
Events	Alpha	User events, project events, authenticated user
Pipelines	Alpha	CRUD, retry, cancel, variables, test reports
Jobs	Alpha	List, trace, cancel, retry, play, erase, artifacts
Pipeline Schedules	Alpha	CRUD, variables, take ownership
Runners	Alpha	CRUD, list jobs
Releases	Alpha	CRUD, release links
Deploy Keys	Alpha	CRUD, enable
Environments	Alpha	CRUD, stop

🎯 Principais Características

Imutabilidade e Isolamento

Cada instância é criada com GitLabWrapperTS.create() e sua configuração é congelada — não há setToken() ou setSudo(). Para usar configurações diferentes, crie uma nova instância. Isso permite que múltiplas partes do sistema operem com credenciais e servidores diferentes simultaneamente sem risco de contaminação de estado global.

const glAdmin = GitLabWrapperTS.create({ baseUrl, token: adminToken });
const glUser = GitLabWrapperTS.create({ baseUrl, token: userToken });
const glDev = GitLabWrapperTS.create({ baseUrl: devUrl, token: devToken });

Paginação Dupla (Offset + Keyset)

A API do GitLab suporta paginação offset (página/por página) e keyset (cursor-based). O wrapper gerencia ambas de forma transparente via AsyncIterableIterator:

// Offset pagination (padrão) — faz fetch página a página
for await (const project of gl.projects.list({ per_page: 20 })) {
    process(project);
}

// Keyset pagination — mais estável para grandes datasets
for await (const issue of gl.issues.list({ pagination: "keyset", per_page: 50 })) {
    process(issue);
}

// Coleto tudo em um array
const todas = await gl.issues.list({ state: "opened" }).toArray();

Sistema de Erros RFC 7807

Todos os erros seguem o padrão Problem Details (RFC 7807) com UUIDv7 único para correlação em logs, 12 categorias de erro mapeadas para status HTTP, e contexto rico para auditoria:

{
    "type": "https://github.com/st-all-one/gitlab-wrapper-ts/wiki/error/errors#validation-error",
    "title": "validation-error",
    "status": 422,
    "detail": "Name has already been taken",
    "instance": "urn:uuid:019db142-f59d-7606-9f20-6ebfa53759e0",
    "context": {
        "operation": "POST /projects",
        "httpStatus": 422,
        "apiErrors": ["name has already been taken"]
    }
}

Logs Estruturados

Cada erro é automaticamente registrado via @logtape/logtape com namespace ["@st-all-one/gitlab-wrapper-ts", "error"], incluindo category, status, instance e operation. A configuração do logtape é responsabilidade do consumidor.

TypeScript Rigoroso

• Strict mode: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes
• Zero any — todos os tipos flexíveis usam unknown
• import type obrigatório para imports type-only (verbatim-module-syntax)
• Retornos explícitos em todas as funções

OAuth 2.0

Suporte completo aos fluxos OAuth:

• Authorization Code com PKCE — generateCodeVerifier(), generateCodeChallenge(), authorizationCodeUrl(), exchangeAuthorizationCode()
• Device Grant — requestDeviceAuthorization(), pollForToken(), getToken()
• Token Management — refreshToken(), revokeToken()

🔍 Testes

deno task fmt        # formatação
deno task lint       # lint (69 arquivos, 0 problemas)
deno task check      # type check
deno task test       # 28 testes unitários

❯ deno test
ok | 28 passed | 0 failed (312ms)

Teste manual contra instância real:

export GITLAB_URL="https://gitlab.com/api/v4"
export GITLAB_TOKEN="glpat-xxxx"
deno run --allow-net --allow-env demo/manual-test.ts

❯ deno run --allow-net --allow-env demo/manual-test.ts
Resultado: 40 passaram, 0 falharam

🛠️ Stack

Componente	Tecnologia
Runtime	Deno 2.0+
HTTP	fetch nativo
Erros	RFC 7807 com UUIDv7 (@std/uuid)
Logs	@logtape/logtape
Linguagem	TypeScript 5.x (strict)
Licença	MPL-2.0

---

---

Este projeto é Open Source e Licenciado através da Mozilla Public License v2.0 (MPL-2.0)