projects-plus-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,674 @@
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    retries: number;
+    retryDelay: number;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    skipRetry?: boolean;
+}
+declare class HttpClient {
+    private config;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make an HTTP request with automatic retries
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Build URL with query parameters
+     */
+    private buildUrl;
+    /**
+     * Fetch with timeout
+     */
+    private fetchWithTimeout;
+    /**
+     * Handle response and parse JSON
+     */
+    private handleResponse;
+    /**
+     * Extract error message from response data
+     */
+    private extractErrorMessage;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for the specified duration
+     */
+    private sleep;
+}
+
+interface Task {
+    id: string;
+    themeId: string;
+    projectId: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    ownerId: string | null;
+    memberIds: string[];
+    memberCompletions: Record<string, boolean>;
+    dueDate: string | null;
+    order: number;
+    createdAt: string;
+    updatedAt: string;
+}
+type TaskStatus = 'active' | 'paused' | 'archived';
+interface Project {
+    id: string;
+    themeId: string;
+    title: string;
+    description: string;
+    status: ProjectStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+type ProjectStatus = 'active' | 'paused' | 'archived';
+interface Comment {
+    id: string;
+    content: string;
+    commentedBy: string;
+    commentedAt: string;
+    mentionedUserIds: string[];
+    updatedAt: string | null;
+}
+interface Session {
+    id: string;
+    ai: string;
+    startedAt: string;
+    status: SessionStatus;
+    handoffNote: string | null;
+    endedAt: string | null;
+}
+type SessionStatus = 'active' | 'ended';
+interface Theme {
+    id: string;
+    name: string;
+    description: string;
+    status: ThemeStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+type ThemeStatus = 'active' | 'paused' | 'archived';
+interface ThemeContext {
+    theme: ThemeSummary;
+    projects: ProjectWithTasks[];
+    stats: ThemeStats;
+}
+interface ThemeSummary {
+    id: string;
+    name: string;
+    description: string;
+}
+interface ProjectWithTasks {
+    id: string;
+    title: string;
+    description: string;
+    status: ProjectStatus;
+    tasks: TaskSummary[];
+}
+interface TaskSummary {
+    id: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    ownerId: string | null;
+    dueDate: string | null;
+}
+interface ThemeStats {
+    totalProjects: number;
+    activeProjects: number;
+    totalTasks: number;
+    activeTasks: number;
+    pausedTasks: number;
+    archivedTasks: number;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        total: number;
+        page: number;
+        pageSize: number;
+        hasMore: boolean;
+    };
+}
+interface StartSessionRequest {
+    ai: string;
+}
+interface StartSessionResponse {
+    session: Session;
+}
+interface EndSessionRequest {
+    handoffNote?: string;
+}
+interface EndSessionResponse {
+    session: Session;
+}
+interface ListTasksParams {
+    status?: TaskStatus;
+    projectId?: string;
+    ownerId?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface CompleteTaskRequest {
+    projectId: string;
+}
+interface CreateCommentRequest {
+    projectId: string;
+    taskId: string;
+    content: string;
+    aiName?: string;
+}
+interface CreateCommentResponse {
+    comment: Comment;
+}
+interface WorkflowStartResult {
+    session: Session;
+    context: ThemeContext;
+}
+interface ReportProgressParams {
+    projectId: string;
+    changes?: string[];
+    testResults?: {
+        passed?: number;
+        failed?: number;
+        skipped?: number;
+    };
+    note?: string;
+}
+interface ProjectsPlusConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+
+/**
+ * Context resource for getting theme overview
+ */
+declare class ContextResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get theme context including all projects and tasks
+     *
+     * @example
+     * ```ts
+     * const context = await pp.context.get();
+     * console.log(context.theme.name);
+     * console.log(context.projects);
+     * ```
+     */
+    get(): Promise<ThemeContext>;
+}
+
+/**
+ * Sessions resource for managing AI development sessions
+ */
+declare class SessionsResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Start a new AI development session
+     *
+     * @param params - Session parameters
+     * @returns The created session
+     *
+     * @example
+     * ```ts
+     * const session = await pp.sessions.start({ ai: 'claude' });
+     * console.log(session.id);
+     * ```
+     */
+    start(params: StartSessionRequest): Promise<Session>;
+    /**
+     * End the current AI development session
+     *
+     * @param params - Optional handoff note
+     * @returns The ended session
+     *
+     * @example
+     * ```ts
+     * const session = await pp.sessions.end({
+     *   handoffNote: 'Completed tasks X, Y, Z. Remaining: A, B.'
+     * });
+     * ```
+     */
+    end(params?: EndSessionRequest): Promise<Session>;
+    /**
+     * Get the current active session if any
+     *
+     * @returns The current session or null
+     */
+    current(): Promise<Session | null>;
+}
+
+/**
+ * Tasks resource for managing tasks
+ */
+declare class TasksResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List tasks with optional filters
+     *
+     * @param params - Filter parameters
+     * @returns List of tasks
+     *
+     * @example
+     * ```ts
+     * // Get all active tasks
+     * const tasks = await pp.tasks.list({ status: 'active' });
+     *
+     * // Get tasks for a specific project
+     * const projectTasks = await pp.tasks.list({
+     *   projectId: 'proj-123',
+     *   status: 'active'
+     * });
+     * ```
+     */
+    list(params?: ListTasksParams): Promise<Task[]>;
+    /**
+     * Get a specific task
+     *
+     * @param taskId - Task ID
+     * @param params - Additional parameters (projectId required)
+     * @returns The task
+     *
+     * @example
+     * ```ts
+     * const task = await pp.tasks.get('task-123', {
+     *   projectId: 'proj-123'
+     * });
+     * ```
+     */
+    get(taskId: string, params: {
+        projectId: string;
+    }): Promise<Task>;
+    /**
+     * Mark a task as completed (archived)
+     *
+     * @param taskId - Task ID
+     * @param params - Additional parameters (projectId required)
+     * @returns The updated task
+     *
+     * @example
+     * ```ts
+     * await pp.tasks.complete('task-123', {
+     *   projectId: 'proj-123'
+     * });
+     * ```
+     */
+    complete(taskId: string, params: CompleteTaskRequest): Promise<Task>;
+    /**
+     * Update task status
+     *
+     * @param taskId - Task ID
+     * @param params - Status and projectId
+     * @returns The updated task
+     *
+     * @example
+     * ```ts
+     * await pp.tasks.updateStatus('task-123', {
+     *   projectId: 'proj-123',
+     *   status: 'paused'
+     * });
+     * ```
+     */
+    updateStatus(taskId: string, params: {
+        projectId: string;
+        status: 'active' | 'paused' | 'archived';
+    }): Promise<Task>;
+}
+
+/**
+ * Projects resource for managing projects
+ */
+declare class ProjectsResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all projects
+     *
+     * @param params - Filter parameters
+     * @returns List of projects
+     *
+     * @example
+     * ```ts
+     * const projects = await pp.projects.list();
+     *
+     * // Filter by status
+     * const activeProjects = await pp.projects.list({ status: 'active' });
+     * ```
+     */
+    list(params?: {
+        status?: 'active' | 'paused' | 'archived';
+    }): Promise<Project[]>;
+    /**
+     * Get a specific project
+     *
+     * @param projectId - Project ID
+     * @returns The project
+     *
+     * @example
+     * ```ts
+     * const project = await pp.projects.get('proj-123');
+     * ```
+     */
+    get(projectId: string): Promise<Project>;
+    /**
+     * Get tasks for a specific project
+     *
+     * @param projectId - Project ID
+     * @param params - Filter parameters
+     * @returns List of tasks
+     *
+     * @example
+     * ```ts
+     * const tasks = await pp.projects.getTasks('proj-123');
+     *
+     * // Filter by status
+     * const activeTasks = await pp.projects.getTasks('proj-123', {
+     *   status: 'active'
+     * });
+     * ```
+     */
+    getTasks(projectId: string, params?: {
+        status?: 'active' | 'paused' | 'archived';
+    }): Promise<Task[]>;
+}
+
+/**
+ * Comments resource for managing task comments
+ */
+declare class CommentsResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List comments for a task
+     *
+     * @param params - Task identifiers
+     * @returns List of comments
+     *
+     * @example
+     * ```ts
+     * const comments = await pp.comments.list({
+     *   projectId: 'proj-123',
+     *   taskId: 'task-123'
+     * });
+     * ```
+     */
+    list(params: {
+        projectId: string;
+        taskId: string;
+    }): Promise<Comment[]>;
+    /**
+     * Create a new comment on a task
+     *
+     * @param params - Comment data
+     * @returns The created comment
+     *
+     * @example
+     * ```ts
+     * await pp.comments.create({
+     *   projectId: 'proj-123',
+     *   taskId: 'task-123',
+     *   content: '## 実装完了\n\n### 変更内容\n- file1.ts\n- file2.ts',
+     *   aiName: 'Claude'
+     * });
+     * ```
+     */
+    create(params: CreateCommentRequest): Promise<Comment>;
+    /**
+     * Delete a comment
+     *
+     * @param commentId - Comment ID
+     * @param params - Task identifiers
+     *
+     * @example
+     * ```ts
+     * await pp.comments.delete('comment-123', {
+     *   projectId: 'proj-123',
+     *   taskId: 'task-123'
+     * });
+     * ```
+     */
+    delete(commentId: string, params: {
+        projectId: string;
+        taskId: string;
+    }): Promise<void>;
+}
+
+/**
+ * Workflow helper for common development patterns
+ *
+ * @example
+ * ```ts
+ * const workflow = pp.workflow({ ai: 'claude' });
+ *
+ * const { session, context } = await workflow.start();
+ * await workflow.reportProgress('task-id', {
+ *   projectId: 'proj-id',
+ *   changes: ['file1.ts'],
+ *   testResults: { passed: 10 },
+ * });
+ * await workflow.completeAndRefresh('task-id', { projectId: 'proj-id' });
+ * await workflow.end('Summary');
+ * ```
+ */
+declare class Workflow {
+    private client;
+    private ai;
+    private currentSession;
+    private currentContext;
+    constructor(client: ProjectsPlus, ai: string);
+    /**
+     * Start session and get context in one call
+     *
+     * @returns Session and context
+     */
+    start(): Promise<WorkflowStartResult>;
+    /**
+     * Report progress with auto-formatted markdown comment
+     *
+     * @param taskId - Task ID
+     * @param params - Progress details
+     */
+    reportProgress(taskId: string, params: ReportProgressParams): Promise<void>;
+    /**
+     * Complete a task and refresh context
+     *
+     * @param taskId - Task ID
+     * @param params - Project ID
+     * @returns Updated context
+     */
+    completeAndRefresh(taskId: string, params: {
+        projectId: string;
+    }): Promise<ThemeContext>;
+    /**
+     * Refresh context without completing a task
+     *
+     * @returns Updated context
+     */
+    refresh(): Promise<ThemeContext>;
+    /**
+     * End the session with optional handoff note
+     *
+     * @param handoffNote - Summary for next session
+     * @returns Ended session
+     */
+    end(handoffNote?: string): Promise<Session>;
+    /**
+     * Get the current session
+     */
+    getSession(): Session | null;
+    /**
+     * Get the current context
+     */
+    getContext(): ThemeContext | null;
+    /**
+     * Format a progress comment from params
+     */
+    private formatProgressComment;
+}
+
+/**
+ * Projects Plus SDK Client
+ *
+ * @example
+ * ```ts
+ * import { ProjectsPlus } from '@projects-plus/sdk';
+ *
+ * const pp = new ProjectsPlus({
+ *   apiKey: process.env.PROJECTS_PLUS_API_KEY,
+ * });
+ *
+ * // Start session
+ * await pp.sessions.start({ ai: 'claude' });
+ *
+ * // Get context
+ * const context = await pp.context.get();
+ *
+ * // List tasks
+ * const tasks = await pp.tasks.list({ status: 'active' });
+ *
+ * // Add comment
+ * await pp.comments.create({
+ *   projectId: 'proj-id',
+ *   taskId: 'task-id',
+ *   content: '## Done\n\nImplemented feature X',
+ *   aiName: 'Claude'
+ * });
+ *
+ * // Complete task
+ * await pp.tasks.complete('task-id', { projectId: 'proj-id' });
+ *
+ * // End session
+ * await pp.sessions.end({ handoffNote: 'Summary...' });
+ * ```
+ */
+declare class ProjectsPlus {
+    private http;
+    /** Context resource for getting theme overview */
+    readonly context: ContextResource;
+    /** Sessions resource for managing AI development sessions */
+    readonly sessions: SessionsResource;
+    /** Tasks resource for managing tasks */
+    readonly tasks: TasksResource;
+    /** Projects resource for managing projects */
+    readonly projects: ProjectsResource;
+    /** Comments resource for managing task comments */
+    readonly comments: CommentsResource;
+    /**
+     * Create a new Projects Plus client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config: ProjectsPlusConfig);
+    /**
+     * Create a workflow helper for common development patterns
+     *
+     * @param params - Workflow parameters
+     * @returns Workflow instance
+     *
+     * @example
+     * ```ts
+     * const workflow = pp.workflow({ ai: 'claude' });
+     *
+     * // Start session and get context in one call
+     * const { session, context } = await workflow.start();
+     *
+     * // Report progress with auto-formatted markdown
+     * await workflow.reportProgress('task-id', {
+     *   projectId: 'proj-id',
+     *   changes: ['file1.ts', 'file2.ts'],
+     *   testResults: { passed: 10, failed: 0 },
+     * });
+     *
+     * // Complete task and refresh context
+     * const newContext = await workflow.completeAndRefresh('task-id', {
+     *   projectId: 'proj-id'
+     * });
+     *
+     * // End session
+     * await workflow.end('Summary...');
+     * ```
+     */
+    workflow(params: {
+        ai: string;
+    }): Workflow;
+}
+
+/**
+ * Base error class for all API errors
+ */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status: number, code?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Thrown when the API key is invalid or missing
+ */
+declare class AuthenticationError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Thrown when the requested resource is not found
+ */
+declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request is invalid
+ */
+declare class ValidationError extends ApiError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Thrown when there's a server error
+ */
+declare class ServerError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request times out
+ */
+declare class TimeoutError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the network is unavailable
+ */
+declare class NetworkError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Create the appropriate error based on status code
+ */
+declare function createApiError(status: number, message: string, details?: unknown): ApiError;
+
+export { ApiError, type ApiResponse, AuthenticationError, type Comment, type CompleteTaskRequest, type CreateCommentRequest, type CreateCommentResponse, type EndSessionRequest, type EndSessionResponse, type ListTasksParams, NetworkError, NotFoundError, type PaginatedResponse, type Project, type ProjectStatus, type ProjectWithTasks, ProjectsPlus, type ProjectsPlusConfig, RateLimitError, type ReportProgressParams, ServerError, type Session, type SessionStatus, type StartSessionRequest, type StartSessionResponse, type Task, type TaskStatus, type TaskSummary, type Theme, type ThemeContext, type ThemeStats, type ThemeStatus, type ThemeSummary, TimeoutError, ValidationError, Workflow, type WorkflowStartResult, createApiError };