Projects Plus SDK

Installation #

npm install projects-plus-sdk

yarn add projects-plus-sdk

Quick Start #

基本的な使用方法:

import { ProjectsPlus } from 'projects-plus-sdk';

const pp = new ProjectsPlus({
  apiKey: process.env.PROJECTS_PLUS_API_KEY,
});

// セッション開始
await pp.sessions.start({ ai: 'claude' });

// コンテキスト取得（テーマ・プロジェクト・タスク情報）
const context = await pp.context.get();
console.log(context.theme.name);
console.log(context.projects);

// アクティブなタスク一覧を取得
const tasks = await pp.tasks.list({ status: 'active' });

// タスクにコメントを追加
await pp.comments.create({
  projectId: 'proj-id',
  taskId: 'task-id',
  content: '## 実装完了\n\n機能Xを実装しました',
  aiName: 'Claude',
});

// タスクを完了
await pp.tasks.complete('task-id', { projectId: 'proj-id' });

// セッション終了
await pp.sessions.end({ handoffNote: '完了サマリー...' });

Workflow Helper #

よくある開発パターンを簡略化するヘルパー関数:

const workflow = pp.workflow({ ai: 'claude' });

// セッション開始 + コンテキスト取得を一度に
const { session, context } = await workflow.start();

// 進捗報告（自動でMarkdownフォーマット）
await workflow.reportProgress('task-id', {
  projectId: 'proj-id',
  changes: ['file1.ts', 'file2.ts'],
  testResults: { passed: 10, failed: 0 },
  note: 'オプションのメモ',
});

// タスク完了 + コンテキスト再取得
const newContext = await workflow.completeAndRefresh('task-id', {
  projectId: 'proj-id',
});

// セッション終了
await workflow.end('完了した作業のサマリー');

API Reference

// テーマの全情報を取得
const context = await pp.context.get();

// context.theme - テーマ情報
// context.projects - プロジェクト一覧（タスク含む）
// context.stats - 統計情報

// セッション開始
const session = await pp.sessions.start({ ai: 'claude' });

// セッション終了（引き継ぎメモ付き）
const endedSession = await pp.sessions.end({
  handoffNote: 'タスクX, Y, Zを完了しました',
});

// 現在のセッション取得
const current = await pp.sessions.current();

// タスク一覧（全体）
const tasks = await pp.tasks.list({ status: 'active' });

// プロジェクト内のタスク一覧
const projectTasks = await pp.tasks.list({
  projectId: 'proj-id',
  status: 'active',
});

// タスク詳細を取得
const task = await pp.tasks.get('task-id', { projectId: 'proj-id' });

// タスクを完了（アーカイブ）
await pp.tasks.complete('task-id', { projectId: 'proj-id' });

// ステータス更新
await pp.tasks.updateStatus('task-id', {
  projectId: 'proj-id',
  status: 'paused',  // 'active' | 'paused' | 'completed'
});

// プロジェクト一覧
const projects = await pp.projects.list();
const activeProjects = await pp.projects.list({ status: 'active' });

// プロジェクト詳細
const project = await pp.projects.get('proj-id');

// プロジェクト内のタスク取得
const tasks = await pp.projects.getTasks('proj-id');

// コメント一覧
const comments = await pp.comments.list({
  projectId: 'proj-id',
  taskId: 'task-id',
});

// コメント作成（Markdown対応）
await pp.comments.create({
  projectId: 'proj-id',
  taskId: 'task-id',
  content: '## 進捗報告\n\n- 機能Aを実装\n- テスト追加',
  aiName: 'Claude',  // AI名（任意）
});

// コメント削除
await pp.comments.delete('comment-id', {
  projectId: 'proj-id',
  taskId: 'task-id',
});

Error Handling #

SDKは用途別のエラークラスを提供します:

import {
  ProjectsPlus,
  ApiError,
  RateLimitError,
  AuthenticationError,
  NotFoundError,
} from 'projects-plus-sdk';

try {
  await pp.tasks.complete('task-id', { projectId: 'proj-id' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`レート制限中。${error.retryAfter}秒後にリトライ`);
  } else if (error instanceof AuthenticationError) {
    console.log('APIキーが無効です');
  } else if (error instanceof NotFoundError) {
    console.log('リソースが見つかりません');
  } else if (error instanceof ApiError) {
    console.log(`APIエラー: ${error.status} - ${error.message}`);
  }
}

Configuration #

SDKの動作をカスタマイズできます:

const pp = new ProjectsPlus({
  apiKey: 'your-api-key',     // 必須
  baseUrl: 'https://...',     // オプション: カスタムエンドポイント
  timeout: 30000,             // オプション: タイムアウト(ms)
  retries: 3,                 // オプション: 最大リトライ回数
  retryDelay: 1000,           // オプション: リトライ間隔(ms)
});

TypeScript Support #

SDKは完全な型定義を提供します:

import type {
  Task,
  Project,
  Comment,
  Session,
  ThemeContext,
  TaskStatus,
  ProjectStatus,
} from 'projects-plus-sdk';

// 型を活用した開発
const handleTask = (task: Task) => {
  console.log(task.title);
  console.log(task.status);  // 'active' | 'paused' | 'completed'
  console.log(task.dueDate); // Date | undefined
};

Environment Variables #

推奨: APIキーは環境変数で管理してください:

# .env または shell
export PROJECTS_PLUS_API_KEY=pp_live_xxx_yyy

// コード内
const pp = new ProjectsPlus({
  apiKey: process.env.PROJECTS_PLUS_API_KEY!,
});