@commitkey/sdk

Official CommitKey SDK for JavaScript/TypeScript. Build AI agents and SaaS platforms with Git infrastructure.

Installation

npm install @commitkey/sdk

Quick Start

import { CommitKey } from '@commitkey/sdk'

const commitKey = new CommitKey({
  baseUrl: 'https://api.commitkey.com', // optional, defaults to production
  apiKey: 'your-api-key' // optional, for authentication
})

// Create a new repository
const repo = await commitKey.repo.create({
  name: 'my-repo',
  template: 'commitkey/vite-shadcn-tailwind' // optional
})

// Get temporary access to the repository
const access = await repo.issueToken()

// Use the git URL to securely interact with the repo
console.log(`git clone ${access.gitUrl}`)

Configuration

Environment Variables

You can configure the SDK using environment variables:

export COMMITKEY_BASE_URL=https://api.commitkey.com
export COMMITKEY_API_KEY=your-api-key

Getting an API Key

Important: API keys are required for all operations. You must create one through the web interface first.

1. Start the development server: npm run dev
2. Sign in to the web app at http://localhost:3000
3. Go to Settings → API Keys
4. Click Create New Key
5. Give your key a descriptive name
6. Select the appropriate permissions (default is fine for most use cases)
7. Click Create Key
8. Copy the API key immediately - it won't be shown again for security reasons
9. Set it as an environment variable: export COMMITKEY_API_KEY=your_api_key_here

Note: The API key in the examples is fake and will not work. You must use a real API key from your account.

Constructor Options

const commitKey = new CommitKey({
  baseUrl: 'https://api.commitkey.com', // Base URL for the API
  apiKey: 'your-api-key' // API key for authentication
})

API Reference

CommitKey

Main SDK class for interacting with CommitKey services.

Constructor

new CommitKey(config?: CommitKeyConfig)

Methods

• repo.create(options): Create a new repository

Repository

Repository instance returned by commitKey.repo.create().

Properties

• name: Repository name
• gitUrl: Git URL for cloning
• info: Complete repository information

Methods

• issueToken(): Get temporary access token and git URL

Types

interface CreateRepositoryOptions {
  name: string;
  template?: string;
}

interface AccessToken {
  token: string;
  gitUrl: string;
  expiresAt: Date;
}

interface RepositoryInfo {
  name: string;
  url: string;
  gitUrl: string;
}

Examples

Basic Usage

import { CommitKey } from '@commitkey/sdk'

const commitKey = new CommitKey()

// Create repository
const repo = await commitKey.repo.create({
  name: 'my-project'
})

// Get access
const access = await repo.issueToken()
console.log(`Clone with: git clone ${access.gitUrl}`)

With Template

const repo = await commitKey.repo.create({
  name: 'my-vite-app',
  template: 'commitkey/vite-shadcn-tailwind'
})

Sandbox Integration

// Perfect for AI agents and sandbox environments
const repo = await commitKey.repo.create({
  name: `sandbox-${Date.now()}`,
  template: 'commitkey/vite-shadcn-tailwind'
})

const access = await repo.issueToken()

// Execute in sandbox
sandbox.exec(`git clone ${access.gitUrl}`)
sandbox.exec('cd project && npm install')
sandbox.exec('npm run dev')

Error Handling

The SDK throws CommitKeyError for API errors:

import { CommitKey, CommitKeyError } from '@commitkey/sdk'

try {
  const repo = await commitKey.repo.create({ name: 'my-repo' })
} catch (error) {
  if (error instanceof CommitKeyError) {
    console.error('API Error:', error.message)
    console.error('Status:', error.status)
    console.error('Code:', error.code)
  }
}

Development

Building

npm run build

Testing

# Run tests once
npm run test:run

# Run tests in watch mode
npm run test

# Run tests with UI
npm run test:ui

Test Configuration

Create a .env.local file in the project root with:

COMMITKEY_BASE_URL=http://localhost:3001
COMMITKEY_API_KEY=your-api-key-here

To get an API key for testing:

1. Start the development server: npm run dev
2. Sign in to the web app at http://localhost:3000
3. Go to Settings → API Keys
4. Click Create New Key
5. Copy the API key and set it as COMMITKEY_API_KEY

License

MIT