forgejo-api-component-nodejs

Transport-neutral, typed Forgejo API Component for Xtrape Widgets and integrations, implemented in Node.js.

Naming per docs#199 · D22: the second-to-last segment is the Artifact type (component), the last is the language. The earlier working name forgejo-api-npm does not conform and is retired (npm is an ecosystem, not an Artifact type or a language).

What this repository is

The reusable Forgejo HTTP/API mechanics extracted from infra/mcp-forgejo-nodejs (migration issue: mcp-forgejo-nodejs#58; extraction set rebaselined 2026-08-02 against the real dependency closure). The extraction set is:

1. the transport-neutral API client/type parts of src/forgejo/client.ts — migrated after a narrow client config/auth contract is defined (base URL, auth scheme + credential, injectable fetch — and nothing else). The Component never depends on the transitional repository's full AppConfig, which mixes in MCP transport, OAuth, ALLOW_* gates, default-repo and protected-path settings. The maxCommit* limits stay with the Widgets too: they are enforced by Action handlers (assertCommitPayloadSize()), not by ForgejoClient — a bounded-execution gate, not client contract;
2. src/forgejo/change-files.ts in full — a pure ChangeFiles API encoding layer that client.ts imports and re-exports, so it is part of the Component's dependency closure (which Widget may call it is decided at the Action/Checkpoint layer, not by splitting the encoder);
3. the Forgejo API error normalization part of src/forgejo/errors.ts (AUTH_FAILED, FORGEJO_NOT_FOUND, FORGEJO_CONFLICT, FORGEJO_RATE_LIMITED, FORGEJO_VALIDATION_FAILED, NETWORK_ERROR, PERMISSION_DENIED, UNSUPPORTED_FILE_TYPE, UNKNOWN_ERROR). TOOL_DISABLED, generic VALIDATION_FAILED, CONTENT_TOO_LARGE (a handoff/commit payload-gate result, not a client error) and the tool-input-validation wording stay with the Widgets/Exposure — they are Action/local-policy semantics, not client error contract.

Artifact identity:

publisher: xtrape
name:      forgejo-api
type:      Component
proposed npm coordinate: @xtrape/forgejo-api@<version>

Publication binds source commit and artifact digest per xtrape-docs reference/06 §10.1 — new publishes require build-system-produced linkage.

What this repository is not

• Not a Capability owner. It owns no Actions, no Checkpoints, no authorization, no approval. Those belong to the single Forgejo Widget, forgejo-ops-widget-nodejs.
• Not a Service. It is a library; nothing here registers with the Platform or holds a Service Token.
• Not an MCP surface. AI-facing projection is Xtrape Exposure's job.
• Not an authorization shortcut. Any consumer — the Forgejo Widget or other integrations — gets typed API mechanics only. Consuming this Component grants no implicit authorization and does not constitute a raw gateway; governed invocation still goes through Platform authorization and the owning Widget's Actions.

Consumers

| Consumer | Uses this for | | --- | --- | | forgejo-ops-widget-nodejs | all Forgejo Actions; each Action selects the least-privileged credential profile it needs | | other integrations | typed Forgejo access without capability semantics |

Status

Complete public REST API implementation for the deployed Forgejo 15 baseline. The package compiles the official Forgejo v15.0.2 schema (314 paths / 491 operations) into a path-, method-, parameter-, body- and response-typed client. Schema provenance and deterministic regeneration are recorded under openapi/.

The earlier ergonomic client, ChangeFiles encoder, injectable fetch transport, authentication mechanics and normalized API errors were extracted from infra/mcp-forgejo-nodejs@25ac3ee495cdd7fcb435a35db6427ad58045a90e and remain available for compatibility. New coverage should use the schema-complete client.

This package is not yet a published production dependency. The transitional forgejo-mcp container remains the running implementation until the Component is released and forgejo-ops-widget-nodejs completes its governed Action migration.

Usage

import { createForgejoOpenApiClient } from '@xtrape/forgejo-api';

const forgejo = createForgejoOpenApiClient({
  baseUrl: 'https://forgejo.example.com',
  authScheme: 'token',
  credential: obtainCredentialFromTheWidgetVault(),
});

const { data: repository } = await forgejo.GET('/repos/{owner}/{repo}', {
  params: { path: { owner: 'xtrape', repo: 'xtrape-docs' } },
});

The Component does not read credentials from the environment, persist them, or choose which credential profile an operation may use. Those decisions stay in the consuming Widget. A client instance binds one credential; per-call headers cannot replace it. Token, bearer and BasicAuth/OTP flows are supported, while authScheme: 'none' permits genuinely public Forgejo API calls without manufacturing a credential.

The complete client covers the public operations present in Forgejo's official swagger.v1.json, including repository collaboration/content/governance, organizations, teams, users, webhooks, releases, packages represented by that schema, Actions administration, runners, quotas and instance administration. Forgejo-internal or undocumented routes are deliberately excluded: an undocumented endpoint is not a stable public API contract.

The stable root exports and npm/Forgejo versioning rules are defined in docs/public-api-and-compatibility.md.