@molecule/api-git-provider-gitea 1.0.2

package/README.md

@@ -0,0 +1,86 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-07T00:19:25.239Z
+-->
+
+# @molecule/api-git-provider-gitea
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/api-git-provider-gitea` — a `@molecule/api-git-provider` bond.
+
+Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+then never names this host. See the core package for the interface and for
+why `basicAuthUsername` may be null.
+
+## Quick Start
+
+```typescript
+import { registerGitProvider } from '@molecule/api-git-provider'
+import { provider } from '@molecule/api-git-provider-gitea'
+
+registerGitProvider(provider)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-git-provider-gitea @molecule/api-git-provider @molecule/api-http
+```
+
+## API
+
+### Constants
+
+#### `provider`
+
+The Gitea provider.
+
+`defaultHost` is `gitea.com`, the project's own hosted instance, but Gitea is
+overwhelmingly SELF-HOSTED — Forgejo and Codeberg are the same API. Point a
+deployment at its own instance by overriding the host; the API paths below are
+identical across all of them.
+
+```typescript
+const provider: GitProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-git-provider` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { registerGitProvider } from '@molecule/api-git-provider'
+import { provider } from '@molecule/api-git-provider-gitea'
+
+export function setupGitProviderGitea(): void {
+  registerGitProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-git-provider` ^1.0.2
+- `@molecule/api-http` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-git-provider`
+- `@molecule/api-http`

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@molecule/api-git-provider-gitea` — a `@molecule/api-git-provider` bond.
+ *
+ * Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+ * then never names this host. See the core package for the interface and for
+ * why `basicAuthUsername` may be null.
+ *
+ * @example
+ * ```typescript
+ * import { registerGitProvider } from '@molecule/api-git-provider'
+ * import { provider } from '@molecule/api-git-provider-gitea'
+ *
+ * registerGitProvider(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@molecule/api-git-provider-gitea` — a `@molecule/api-git-provider` bond.
+ *
+ * Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+ * then never names this host. See the core package for the interface and for
+ * why `basicAuthUsername` may be null.
+ *
+ * @example
+ * ```typescript
+ * import { registerGitProvider } from '@molecule/api-git-provider'
+ * import { provider } from '@molecule/api-git-provider-gitea'
+ *
+ * registerGitProvider(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Gitea git-hosting provider — also covers Forgejo and Codeberg.
+ *
+ * @module
+ */
+import type { GitProvider } from '@molecule/api-git-provider';
+/**
+ * The Gitea provider.
+ *
+ * `defaultHost` is `gitea.com`, the project's own hosted instance, but Gitea is
+ * overwhelmingly SELF-HOSTED — Forgejo and Codeberg are the same API. Point a
+ * deployment at its own instance by overriding the host; the API paths below are
+ * identical across all of them.
+ */
+export declare const provider: GitProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,4BAA4B,CAAA;AAmCnC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,WA2DtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,87 @@
+/**
+ * Gitea git-hosting provider — also covers Forgejo and Codeberg.
+ *
+ * @module
+ */
+/**
+ * Normalize Gitea's repository shape.
+ *
+ * Gitea models its API on GitHub's, so the field names line up — but `size` is
+ * KB here as it is there, and `updated_at` stands in for GitHub's `pushed_at`.
+ *
+ * @param repo - Gitea's repository JSON.
+ * @returns The normalized repository, or null when unusable.
+ */
+const normalize = (repo) => repo.full_name && repo.clone_url
+    ? {
+        fullName: repo.full_name,
+        url: repo.clone_url,
+        private: typeof repo.private === 'boolean' ? repo.private : null,
+        defaultBranch: repo.default_branch ?? null,
+        sizeKb: typeof repo.size === 'number' ? repo.size : null,
+        updatedAt: repo.updated_at ?? null,
+        description: repo.description ?? null,
+    }
+    : null;
+/**
+ * The Gitea provider.
+ *
+ * `defaultHost` is `gitea.com`, the project's own hosted instance, but Gitea is
+ * overwhelmingly SELF-HOSTED — Forgejo and Codeberg are the same API. Point a
+ * deployment at its own instance by overriding the host; the API paths below are
+ * identical across all of them.
+ */
+export const provider = {
+    id: 'gitea',
+    label: 'Gitea',
+    defaultHost: 'gitea.com',
+    auth: {
+        kind: 'oauth',
+        // Instance-relative: every Gitea/Forgejo install serves these paths, so the
+        // public host is only a default. A self-hosted deployment overrides both.
+        authorizeUrl: 'https://gitea.com/login/oauth/authorize',
+        tokenUrl: 'https://gitea.com/login/oauth/access_token',
+        // Gitea's scopes are coarser than GitHub's: `write:repository` covers push
+        // and implies read.
+        scope: 'write:repository',
+    },
+    basicAuthUsername: 'x-access-token',
+    apiBaseForHost(host) {
+        return `https://${host}/api/v1`;
+    },
+    apiHeaders(token) {
+        const headers = {
+            'user-agent': 'molecule-dev',
+            accept: 'application/json',
+        };
+        if (token)
+            headers.authorization = `token ${token}`;
+        return headers;
+    },
+    async listRepositories(input) {
+        const { get } = await import('@molecule/api-http');
+        const base = this.apiBaseForHost(input.host);
+        const response = await get(`${base}/user/repos?limit=${input.perPage}&page=${input.page}`, { headers: this.apiHeaders(input.token), timeout: 15_000 });
+        return (response.data ?? []).flatMap((repo) => {
+            const normalized = normalize(repo);
+            return normalized ? [normalized] : [];
+        });
+    },
+    async getRepository(input) {
+        const { get } = await import('@molecule/api-http');
+        const base = this.apiBaseForHost(input.host);
+        try {
+            const response = await get(`${base}/repos/${input.path}`, {
+                headers: this.apiHeaders(input.token),
+                timeout: 15_000,
+            });
+            return response.data ? normalize(response.data) : null;
+        }
+        catch (error) {
+            const status = error?.response?.status;
+            if (status === 404)
+                return null;
+            throw error;
+        }
+    },
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/api-git-provider-gitea",
+  "version": "1.0.2",
+  "description": "Git hosting provider for Gitea (gitea.com) — OAuth endpoints, token auth shape, repository listing and lookup.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "git",
+    "provider",
+    "gitea"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/git-provider/gitea"
+  },
+  "devDependencies": {
+    "@molecule/api-git-provider": "1.0.2",
+    "@molecule/api-http": "1.0.1",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-git-provider": "^1.0.2",
+    "@molecule/api-http": "^1.0.1"
+  }
+}