✨ openapi-typescript (#1)

* ✨ openapi-typescript

* 🐛 Fix base64 encoding in browser

* 🚨 Fix pnpm lint

* 🐛 Fix environment variables in node.js.yaml and update test assertion in repositories.test.ts

Author: NatoBoram

.env

@@ -0,0 +1,6 @@
+BITBUCKET_CLOUD_URL=https://api.bitbucket.org/2.0
+BITBUCKET_CLOUD_USERNAME=
+BITBUCKET_CLOUD_APP_PASSWORD=
+
+BITBUCKET_SERVER_URL=
+BITBUCKET_SERVER_TOKEN=

.github/workflows/node.js.yaml

@@ -23,3 +23,8 @@ jobs:
       - run: pnpm run build --noEmit
       - run: pnpm run lint
       - run: pnpm run test run
+        env:
+          BITBUCKET_CLOUD_USERNAME: ${{ secrets.BITBUCKET_CLOUD_USERNAME }}
+          BITBUCKET_CLOUD_APP_PASSWORD: ${{ secrets.BITBUCKET_CLOUD_APP_PASSWORD }}
+          BITBUCKET_SERVER_URL: ${{ secrets.BITBUCKET_SERVER_URL }}
+          BITBUCKET_SERVER_TOKEN: ${{ secrets.BITBUCKET_SERVER_TOKEN }}

.markdownlint.yaml

@@ -1,3 +1,6 @@
 default: true
 line-length: false
 no-inline-html: false
+no-hard-tabs:
+  code_blocks: false
+  spaces_per_tab: 2

README.md

@@ -3,3 +3,49 @@
 [![Node.js CI](https://github.com/coderabbitai/bitbucket/actions/workflows/node.js.yaml/badge.svg)](https://github.com/coderabbitai/bitbucket/actions/workflows/node.js.yaml) [![Dependabot Updates](https://github.com/coderabbitai/bitbucket/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/coderabbitai/bitbucket/actions/workflows/dependabot/dependabot-updates) [![GitHub Pages](https://github.com/coderabbitai/bitbucket/actions/workflows/github-pages.yaml/badge.svg)](https://github.com/coderabbitai/bitbucket/actions/workflows/github-pages.yaml)
 
 CodeRabbit's TypeScript API client for connecting to Bitbucket Cloud and Bitbucker Data Center.
+
+- Bitbucket Cloud API docs: <https://developer.atlassian.com/cloud/bitbucket/rest>
+- Bitbucket Data Center API docs: <https://developer.atlassian.com/server/bitbucket/rest>
+
+This client is auto-generated by [https://github.com/openapi-ts/openapi-typescript](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-typescript) using the OpenAPI schema from the documentation above.
+
+## Usage
+
+```sh
+pnpm i @coderabbitai/bitbucket
+```
+
+### Cloud
+
+```ts
+import { createBitbucketCloudClient, toBase64 } from "@coderabbitai/bitbucket"
+import {
+	BITBUCKET_CLOUD_APP_PASSWORD,
+	BITBUCKET_CLOUD_URL,
+	BITBUCKET_CLOUD_USERNAME,
+} from "./env.js"
+
+const basic = toBase64(
+	BITBUCKET_CLOUD_USERNAME + ":" + BITBUCKET_CLOUD_APP_PASSWORD,
+)
+
+export const client = createBitbucketCloudClient({
+	baseUrl: BITBUCKET_CLOUD_URL.toString(),
+	headers: { Accept: "application/json", Authorization: `Basic ${basic}` },
+})
+```
+
+### Server
+
+```ts
+import { createBitbucketServerClient } from "@coderabbitai/bitbucket"
+import { BITBUCKET_SERVER_TOKEN, BITBUCKET_SERVER_URL } from "./env.js"
+
+export const server = createBitbucketServerClient({
+	baseUrl: BITBUCKET_SERVER_URL,
+	headers: {
+		Accept: "application/json",
+		Authorization: `Bearer ${BITBUCKET_SERVER_TOKEN}`,
+	},
+})
+```

package.json

@@ -36,7 +36,14 @@
 		"lint": "eslint . && markdownlint-cli2 \"**/*.md\" && prettier --check .",
 		"lint:fix": "eslint --fix --quiet .; markdownlint-cli2 \"**/*.md\" --fix; prettier --list-different --write .",
 		"start": "node dist/main.js",
-		"test": "vitest"
+		"test": "vitest",
+		"openapi-typescript": "pnpm run openapi-typescript:cloud && pnpm run openapi-typescript:server",
+		"preopenapi-typescript:cloud": "curl --output ./src/cloud/openapi/swagger.v3.json https://dac-static.atlassian.com/cloud/bitbucket/swagger.v3.json",
+		"openapi-typescript:cloud": "openapi-typescript ./src/cloud/openapi/swagger.v3.json --output ./src/cloud/openapi/openapi-typescript.ts --immutable --empty-objects-unknown --alphabetize --root-types",
+		"postopenapi-typescript:cloud": "ts-autofix ./src/cloud/openapi && pnpm run lint:fix",
+		"preopenapi-typescript:server": "curl --output ./src/server/openapi/swagger.v3.json https://dac-static.atlassian.com/server/bitbucket/9.1.swagger.v3.json",
+		"openapi-typescript:server": "openapi-typescript ./src/server/openapi/swagger.v3.json --output ./src/server/openapi/openapi-typescript.ts --immutable --empty-objects-unknown --alphabetize --root-types",
+		"postopenapi-typescript:server": "ts-autofix ./src/server/openapi && pnpm run lint:fix"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.10.0",
@@ -46,6 +53,7 @@
 		"eslint-config-prettier": "^9.1.0",
 		"globals": "^15.9.0",
 		"markdownlint-cli2": "^0.14.0",
+		"openapi-typescript": "^7.4.0",
 		"prettier": "^3.3.3",
 		"tsx": "^4.19.1",
 		"typedoc": "^0.26.7",
@@ -61,5 +69,8 @@
 		}
 	},
 	"types": "dist/index.d.ts",
-	"module": "dist/index.js"
+	"module": "dist/index.js",
+	"dependencies": {
+		"openapi-fetch": "^0.12.0"
+	}
 }

pnpm-lock.yaml

@@ -0,0 +1,12 @@
+import { test } from "vitest"
+import { fromBase64, toBase64 } from "./base64.js"
+
+test("toBase64", ({ expect }) => {
+	const based = toBase64("Copyright © 2024 CodeRabbit")
+	expect(based).toBe("Q29weXJpZ2h0IMKpIDIwMjQgQ29kZVJhYmJpdA==")
+})
+
+test("fromBase64", ({ expect }) => {
+	const debased = fromBase64("Q29weXJpZ2h0IMKpIDIwMjQgQ29kZVJhYmJpdA==")
+	expect(debased).toBe("Copyright © 2024 CodeRabbit")
+})

src/base64.test.ts

@@ -0,0 +1,11 @@
+export function toBase64(input: string): string {
+	const bytes = new TextEncoder().encode(input)
+	const string = String.fromCodePoint(...bytes)
+	return btoa(string)
+}
+
+export function fromBase64(base64: string): Buffer | Uint8Array | string {
+	const string = atob(base64)
+	const bytes = Uint8Array.from(string, v => v.codePointAt(0) ?? 0)
+	return new TextDecoder().decode(bytes)
+}

src/base64.ts

@@ -0,0 +1,7 @@
+import { test } from "vitest"
+import { createBitbucketCloudClient } from "./client.js"
+
+test("createBitbucketCloudClient", ({ expect }) => {
+	const client = createBitbucketCloudClient()
+	expect(client).toBeDefined()
+})

src/cloud/client.test.ts

@@ -0,0 +1,16 @@
+import type { Client, ClientOptions } from "openapi-fetch"
+import createClient from "openapi-fetch"
+import type { paths } from "./openapi/index.js"
+
+/**
+ * Creates an `openapi-fetch` client using {@link createClient}.
+ *
+ * @example
+ * export client = createBitbucketCloudClient({
+ * 	baseUrl: "https://api.bitbucket.org/2.0",
+ * 	headers: { Accept: "application/json", Authorization: `Basic ${basic}` },
+ * })
+ */
+export const createBitbucketCloudClient: (
+	clientOptions?: ClientOptions,
+) => Client<paths, "application/json"> = createClient<paths, "application/json">

src/cloud/client.ts

@@ -0,0 +1,2 @@
+export * from "./client.js"
+export * as cloud from "./openapi/index.js"

src/cloud/index.ts

@@ -0,0 +1 @@
+export * from "./openapi-typescript.js"

src/cloud/openapi/index.ts

@@ -0,0 +1,3 @@
+export * from "./base64.js"
+export * from "./cloud/index.js"
+export * from "./server/index.js"

src/cloud/openapi/openapi-typescript.ts

@@ -1 +1 @@
-console.log("CLI mode not supported.")
+console.log("@coderabbitai/bitbucket")

src/cloud/openapi/swagger.v3.json

@@ -0,0 +1,7 @@
+import { test } from "vitest"
+import { createBitbucketServerClient } from "./client.js"
+
+test("createBitbucketServerClient", ({ expect }) => {
+	const client = createBitbucketServerClient()
+	expect(client).toBeDefined()
+})

src/index.ts

@@ -0,0 +1,19 @@
+import type { Client, ClientOptions } from "openapi-fetch"
+import createClient from "openapi-fetch"
+import type { paths } from "./openapi/index.js"
+
+/**
+ * Creates an `openapi-fetch` client using {@link createClient}.
+ *
+ * @example
+ * export const client = createBitbucketServerClient({
+ * 	baseUrl: "https://example.org/rest",
+ * 	headers: {
+ * 		Accept: "application/json",
+ * 		Authorization: `Bearer ${BITBUCKET_SERVER_TOKEN}`,
+ * 	},
+ * })
+ */
+export const createBitbucketServerClient: (
+	clientOptions?: ClientOptions,
+) => Client<paths, "application/json"> = createClient<paths, "application/json">

src/main.ts

@@ -0,0 +1,2 @@
+export * from "./client.js"
+export * as server from "./openapi/index.js"

src/server/client.test.ts

@@ -0,0 +1 @@
+export * from "./openapi-typescript.js"

src/server/client.ts

@@ -0,0 +1,15 @@
+import { createBitbucketCloudClient, toBase64 } from "../../src/index.js"
+import {
+	BITBUCKET_CLOUD_APP_PASSWORD,
+	BITBUCKET_CLOUD_URL,
+	BITBUCKET_CLOUD_USERNAME,
+} from "../env.js"
+
+const basic = toBase64(
+	BITBUCKET_CLOUD_USERNAME + ":" + BITBUCKET_CLOUD_APP_PASSWORD,
+)
+
+export const cloud = createBitbucketCloudClient({
+	baseUrl: BITBUCKET_CLOUD_URL.toString(),
+	headers: { Accept: "application/json", Authorization: `Basic ${basic}` },
+})

src/server/index.ts

@@ -0,0 +1,10 @@
+import { test } from "vitest"
+import { cloud } from "./client.js"
+
+test("GET /repositories", async ({ expect }) => {
+	const got = await cloud.GET("/repositories")
+
+	expect(got.data?.next).toBeTypeOf("string")
+	expect(got.data?.pagelen).toBeTypeOf("number")
+	expect(got.data?.values).toBeDefined()
+})

src/server/openapi/index.ts

@@ -8,27 +8,27 @@ import path from "path"
 export type NodeEnv = (typeof nodeEnvs)[keyof typeof nodeEnvs]
 export type ProcessEnv = typeof process.env
 
-export function isNodeEnv(value: unknown): value is NodeEnv {
-	return Object.values<unknown>(nodeEnvs).includes(value)
+interface LoadedEnv extends ProcessEnv {
+	readonly NODE_ENV: NodeEnv
 }
 
-export function toNodeEnv(value: unknown): NodeEnv {
-	if (isNodeEnv(value)) return value
-	return nodeEnvs.development
+function envString(key: string) {
+	const value = parsed[key]
+	if (!value) throw new Error(`$${key} is missing`)
+	return value
 }
 
-const nodeEnvs = {
-	development: "development",
-	production: "production",
-	/**
-	 * Vitest sets `NODE_ENV` to `test` if it wasn't set before.
-	 * @see https://vitest.dev/guide/migration.html#envs
-	 */
-	test: "test",
-} as const
+function envUrl(key: string) {
+	const str = envString(key)
+	try {
+		return new URL(str)
+	} catch (error) {
+		throw new Error(`$${key} is not a URL: ${str}`, { cause: error })
+	}
+}
 
-interface LoadedEnv extends ProcessEnv {
-	readonly NODE_ENV: NodeEnv
+export function isNodeEnv(value: unknown): value is NodeEnv {
+	return Object.values<unknown>(nodeEnvs).includes(value)
 }
 
 /** Loads environment variables from the `.env` files. `NODE_ENV` has to be
@@ -66,13 +66,25 @@ function loadEnv(): LoadedEnv {
 	return merged
 }
 
-const parsed = loadEnv()
-
-function envString(key: string) {
-	const value = parsed[key]
-	if (!value) throw new Error(`$${key} is missing`)
-	return value
+export function toNodeEnv(value: unknown): NodeEnv {
+	if (isNodeEnv(value)) return value
+	return nodeEnvs.development
 }
 
-export const BITBUCKET_CLOUD_URL = envString("BITBUCKET_CLOUD_URL")
-export const BITBUCKET_CLOUD_TOKEN = envString("BITBUCKET_CLOUD_TOKEN")
+const nodeEnvs = {
+	development: "development",
+	production: "production",
+	/**
+	 * Vitest sets `NODE_ENV` to `test` if it wasn't set before.
+	 * @see https://vitest.dev/guide/migration.html#envs
+	 */
+	test: "test",
+} as const
+const parsed = loadEnv()
+export const BITBUCKET_CLOUD_URL = envUrl("BITBUCKET_CLOUD_URL")
+export const BITBUCKET_CLOUD_USERNAME = envString("BITBUCKET_CLOUD_USERNAME")
+export const BITBUCKET_CLOUD_APP_PASSWORD = envString(
+	"BITBUCKET_CLOUD_APP_PASSWORD",
+)
+export const BITBUCKET_SERVER_URL = envUrl("BITBUCKET_SERVER_URL")
+export const BITBUCKET_SERVER_TOKEN = envString("BITBUCKET_SERVER_TOKEN")

src/server/openapi/openapi-typescript.ts

@@ -0,0 +1,10 @@
+import { createBitbucketServerClient } from "../../src/index.js"
+import { BITBUCKET_SERVER_TOKEN, BITBUCKET_SERVER_URL } from "../env.js"
+
+export const server = createBitbucketServerClient({
+	baseUrl: BITBUCKET_SERVER_URL.toString(),
+	headers: {
+		Accept: "application/json",
+		Authorization: `Bearer ${BITBUCKET_SERVER_TOKEN}`,
+	},
+})

src/server/openapi/swagger.v3.json

@@ -0,0 +1,8 @@
+import { test } from "vitest"
+import { server } from "./client.js"
+
+test("GET /api/latest/repos", async ({ expect }) => {
+	const got = await server.GET("/api/latest/repos")
+
+	expect(got.data?.size).toBeTypeOf("number")
+})

tests/cloud/client.ts

@@ -1,6 +1,62 @@
 {
-	"extends": "./tsconfig.json",
-	"compilerOptions": { "checkJs": true },
-	"include": ["src", "tests"],
-	"files": ["eslint.config.js", "./tests/env.ts"]
+	"compilerOptions": {
+		/* Projects */
+		"incremental": true,
+		"composite": true,
+
+		/* Language and Environment */
+		"target": "ESNext",
+		"lib": ["DOM", "ESNext"],
+		"useDefineForClassFields": true,
+		"moduleDetection": "force",
+
+		/* Modules */
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"typeRoots": ["./node_modules/@types", "./src/types"],
+		"resolvePackageJsonExports": true,
+		"resolvePackageJsonImports": true,
+		"resolveJsonModule": true,
+
+		/* JavaScript Support */
+		"checkJs": true,
+
+		/* Emit */
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+
+		/* Interop Constraints */
+		"isolatedModules": true,
+		"verbatimModuleSyntax": true,
+		"isolatedDeclarations": true,
+		"forceConsistentCasingInFileNames": true,
+
+		/* Type Checking */
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"strictFunctionTypes": true,
+		"strictBindCallApply": true,
+		"strictPropertyInitialization": true,
+		"noImplicitThis": true,
+		"useUnknownInCatchVariables": true,
+		"alwaysStrict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"exactOptionalPropertyTypes": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"allowUnusedLabels": false,
+		"allowUnreachableCode": false,
+
+		/* Completeness */
+		"skipDefaultLibCheck": true,
+		"skipLibCheck": true
+	},
+	"include": ["eslint.config.js", "src", "tests"]
 }

tests/cloud/repositories.test.ts

@@ -59,5 +59,5 @@
 		"skipLibCheck": true
 	},
 	"include": ["src"],
-	"exclude": ["tests", "eslint.config.js"]
+	"exclude": ["eslint.config.js", "tests"]
 }