Phase G: SDK - Unified API Wrapper

Overview

Phase G provides a unified TypeScript SDK wrapper for all GitHub API operations with built-in rate limiting, caching, and error handling. This phase was largely completed during Phase A and Phase D implementations.

Status

• Status: Complete
• Priority: Medium
• Duration: 0 hours (already implemented in Phase A/D)
• Agent: CodeGenAgent

GitHub as OS Mapping

GitHub OS SDK → System Call Interface
- REST API Wrapper → Low-level System Calls
- GraphQL Client → High-performance Queries
- Rate Limiting → Resource Management
- Caching → Memory Management

Goals and Objectives

Primary Goals

1. Provide unified SDK for Issues, PRs, Projects
2. Implement rate limit handling
3. Add caching layer (5-minute TTL)
4. Ensure TypeScript type safety
5. Complete API documentation

Success Metrics

• All GitHub API operations covered
• Rate limit handling success rate 100%
• Cache hit rate > 70%
• TypeScript coverage 100%
• Documentation complete

Implementation Details

1. GitHub OS SDK

Location: packages/github-projects/

Already implemented as part of Projects V2 integration.

Key Files:

• src/client.ts: GraphQL client with rate limiting
• src/types.ts: TypeScript definitions
• src/setup.ts: Project creation utilities

2. Enhanced GitHub Client

File: packages/miyabi-agent-sdk/src/github-client.ts

import { Octokit } from '@octokit/rest';
import { graphql } from '@octokit/graphql';

export class GitHubClient {
  private octokit: Octokit;
  private graphqlWithAuth: typeof graphql;
  private cache: Map<string, CacheEntry> = new Map();

  constructor(token: string) {
    this.octokit = new Octokit({ auth: token });
    this.graphqlWithAuth = graphql.defaults({
      headers: { authorization: `token ${token}` },
    });
  }

  // Projects V2
  async projects.create(owner: string, repo: string, options: ProjectOptions) {
    return this.graphqlWithAuth(CREATE_PROJECT_MUTATION, {
      owner,
      title: options.title,
    });
  }

  // Issues
  async issues.list(owner: string, repo: string, options?: IssueListOptions) {
    const cacheKey = `issues:${owner}/${repo}:${JSON.stringify(options)}`;
    const cached = this.getFromCache(cacheKey);
    if (cached) return cached;

    const { data } = await this.octokit.rest.issues.listForRepo({
      owner,
      repo,
      ...options,
    });

    this.setCache(cacheKey, data, 5 * 60 * 1000); // 5 min TTL
    return data;
  }

  async issues.create(owner: string, repo: string, options: IssueCreateOptions) {
    await this.checkRateLimit();

    return this.octokit.rest.issues.create({
      owner,
      repo,
      ...options,
    });
  }

  // Pull Requests
  async pullRequests.create(owner: string, repo: string, options: PRCreateOptions) {
    await this.checkRateLimit();

    return this.octokit.rest.pulls.create({
      owner,
      repo,
      ...options,
    });
  }

  // Rate Limiting
  private async checkRateLimit() {
    const { data } = await this.octokit.rest.rateLimit.get();

    if (data.rate.remaining < 100) {
      const resetTime = data.rate.reset * 1000;
      const waitTime = resetTime - Date.now();

      if (waitTime > 0) {
        console.log(`Rate limit low. Waiting ${waitTime}ms...`);
        await this.sleep(waitTime);
      }
    }
  }

  // Caching
  private getFromCache(key: string): any | null {
    const entry = this.cache.get(key);
    if (!entry) return null;

    if (Date.now() > entry.expiry) {
      this.cache.delete(key);
      return null;
    }

    return entry.data;
  }

  private setCache(key: string, data: any, ttl: number) {
    this.cache.set(key, {
      data,
      expiry: Date.now() + ttl,
    });
  }
}

3. Usage Examples

import { GitHubClient } from '@miyabi/agent-sdk';

const client = new GitHubClient(process.env.GITHUB_TOKEN);

// Projects V2
const project = await client.projects.create('owner', 'repo', {
  title: 'Agent Task Board'
});

// Issues
const issues = await client.issues.list('owner', 'repo', {
  state: 'open',
  labels: ['bug']
});

// Pull Requests
const pr = await client.pullRequests.create('owner', 'repo', {
  title: 'Fix bug',
  head: 'feature-branch',
  base: 'main'
});

Completion Criteria and KPIs

Acceptance Criteria

Key Performance Indicators

Configuration Reference

Rate Limiting Configuration

const client = new GitHubClient(token, {
  rateLimitThreshold: 100,     // Start checking at 100 remaining
  rateLimitWaitStrategy: 'exponential', // or 'linear'
});

Caching Configuration

const client = new GitHubClient(token, {
  caching: {
    enabled: true,
    ttl: 5 * 60 * 1000,  // 5 minutes
    maxSize: 1000,        // Max cache entries
  },
});

References and Resources

Official Documentation

• Octokit REST API
• GitHub GraphQL API

Internal Documentation

• Phase A: Projects V2 SDK
• Package: @miyabi/agent-sdk

Credits

Implemented by: CodeGenAgent (Phase A/D) Issue: #5 Phase G Model: Claude Sonnet 4 Date: 2025-10-08 Duration: 0 hours (already implemented)

Status: ✅ Complete Next Phase: Phase H - Environments