forgedoe

"for forgejo does"

this is a very light typescript wrapper around the forgejo http api

it uses the openapi/swagger spec, forgejo version 16.0.3+gitea-1.22.0

source code available on git at https://git.vixen.computer/era/forgedoe

how to use it

install

npm install forgedoe # or your preferred package genre

instantiate with an access token

import { createClient } from 'forgedoe';

const forgejo = await createClient("YOUR.FORGEJO.HOST", {
  kind: 'token',
  token: process.env.YOUR_ACCESS_TOKEN
});

instantiate with username and password

import { createClient } from 'forgedoe';

// Note that Basic Auth is more dangerous (it cannot be scoped) but is required for certain endpoints (e.g. deleting an access token from a user)
const forgejo = await createClient("YOUR.FORGEJO.HOST", {
  kind: 'basic',
  username: 'doof',
  password: process.env.YOUR_PASSWORD,
});

now you can fetch with awesome intellisense !!!

examples

type await forgejo.fetch(' and all available endpoints will populate typescript autosuggest

type await forgejo.fetch('/some/endpoint', ' and the available methods for the given endpoint will populate

type await forgejo.fetch('/some/endpoint', 'method', {}) and the object will have the proper type enforced for the given query. the response object will be typed as a discriminated union of the possible response bodies for each possible http status code

const response = await forgejo.fetch('/repos/{owner}/{repo}/branches', 'post', {
  path: { owner: 'doof', repo: 'projectinator' },
  body: { new_branch_name: 'feature/self-destruct-button' },
});

if (response.status == 201) {
  // Now response.body is properly typed as
  // {
  //   commit: {
  //     added: string[];
  //     author: {
  //       email: string;
  //       name: string;
  //       username: string;
  //     };
  //     committer: {
  //       email: string;
  //       name: string;
  //       username: string;
  //     };
  //     id: string;
  //     message: string;
  //     modified: string[];
  //     removed: string[];
  //     timestamp: string;
  //     url: string;
  //     verification: {
  //       payload: string;
  //       reason: string;
  //       signature: string;
  //       signer: {
  //         email: string;
  //         name: string;
  //         username: string;
  //       };
  //       verified: boolean;
  //     };
  //   };
  //   effective_branch_protection_name: string;
  //   enable_status_check: boolean;
  //   name: string;
  //   protected: boolean;
  //   required_approvals: number;
  //   status_check_contexts: string[];
  //   user_can_merge: boolean;
  //   user_can_push: boolean;
  // };
}

caveats

for endpoints that return binary data, response.body will be an ArrayBuffer containing said data, but will have type unknown. i should fix this probably.

i think this should also work with CommonJS require but idk

attribution

hoof-made with <3 by era 𐂂 in vancouver, canada

thx to all forgejo contributors for making awesome open source software

thx to https://vixen.computer/ for hosting this project and the forgejo instance it was built for