SDK and a working example

@opengit/sdk is published on npm (npm install @opengit/sdk). The source lives in this repo at packages/open-git. The workspace keeps a TypeScript export for local apps; the published package is compiled JavaScript.

It covers minting a token, calling /api/v1, verifying webhooks, and Sign in with open-git (discovery, PKCE, code exchange). You still persist OAuth state yourself.

import {
  createBotAppClient,
  createInstallationClient,
  exchangeOpenGitCode,
  startOpenGitOAuth,
  verifyWebhookSignature,
} from "@opengit/sdk"

createBotAppClient is the JWT client (mint / get / link). createInstallationClient returns that plus an ogi_ client for repository routes. Link also accepts an ogi_ token for that install.

const { api } = await createInstallationClient({
  baseUrl: process.env.OPEN_GIT_URL,
  botId: process.env.OPEN_GIT_BOT_ID!,
  installationId,
  privateKey: process.env.OPEN_GIT_BOT_PRIVATE_KEY!.replace(/\\n/g, "\n"),
})

const { pulls } = await api.listPulls("acme", "api")
const pull = pulls[0]
if (pull?.head_sha) {
  await api.upsertCheck("acme", "api", pull.head_sha, {
    name: "your-bot",
    status: "success",
    summary: pull.title,
  })
}

Set baseUrl to the open-git origin you are talking to. The client defaults to https://open-git.com. Local web is http://localhost:3001.

On a non-2xx response, OpenGitClient throws Error with the JSON error string from the API.

Run the example bot

apps/bot-example is a tiny publisher: Setup URL, webhook receiver, Sign in with open-git, then a check and a comment on each pull request.

1. Start open-git (pnpm dev — web is port 3001).
2. In an org, create a bot:
   • Setup URL: http://localhost:4010/connect
   • Homepage: http://localhost:4010
   • Permissions: checks and comments
   • Webhook URL: a public HTTPS URL that tunnels to localhost:4010/webhooks/open-git (localhost webhooks are rejected)
3. Paste the secrets dump into apps/bot-example/.env:

OPEN_GIT_URL=http://localhost:3001
EXAMPLE_APP_URL=http://localhost:4010
OPEN_GIT_BOT_ID=…
OPEN_GIT_BOT_WEBHOOK_SECRET=…
OPEN_GIT_OAUTH_CLIENT_ID=…
OPEN_GIT_OAUTH_CLIENT_SECRET=…
OPEN_GIT_BOT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----"

4. pnpm --filter bot-example dev → http://localhost:4010.

The linked OAuth redirect is the Setup URL: http://localhost:4010/connect. If you created the bot without a Setup URL, add that redirect on the OAuth app. The example reads OPEN_GIT_OAUTH_CLIENT_ID / OPEN_GIT_OAUTH_CLIENT_SECRET (the names in the dump).

Then:

1. Install the bot on a repo you administer.
2. /connect starts Sign in with open-git. The example stores user.sub as the customer id and POSTs it to /link.
3. Open a pull request. You should see @your-slug[bot] comment and an example-bot check.

The example persists installs in .data/store.json and refreshes the repo list from GET /api/v1/app/installations/{id}. Restarting keeps the dashboard. Localhost still cannot receive webhooks; pull-request checks need a public webhook URL.