IssueLoop Node.js and TypeScript Client npm Package

The issueloop npm package is a thin HTTP client — it does not reimplement IssueLoop or embed any Python code. Every method call is a real HTTP round-trip to a issueloop serve process already running on your machine. This means you get the full Python IssueLoop API from Node.js, TypeScript, React, Vue, or React Native without any additional setup.

Installation

Start the Python server

Make sure the Python package is installed and the server is running before making any client calls:

pip install issueloop
issueloop serve

Install the npm package

npm install issueloop

The package requires Node.js 18 or later. It uses the native fetch API built into Node 18+ — no node-fetch or other polyfills are needed.

Getting started

Construct an IssueLoop instance pointing at your running server, then call methods on it. All methods return Promises.

const { IssueLoop } = require('issueloop');

const il = new IssueLoop({ baseUrl: 'http://127.0.0.1:8787' });

// Claim the next pending ticket for a repo
const ticket = await il.getTopError('myrepo');

if (ticket) {
  console.log(`Working on: ${ticket.error_summary}`);

  // ... apply your fix ...

  await il.resolve(ticket.id);
}

The baseUrl option defaults to http://127.0.0.1:8787, so if you’re using the default port you can omit it entirely:

const il = new IssueLoop();

TypeScript support

The package ships index.d.ts with full type declarations. Import the named exports and everything is typed automatically.

import { IssueLoop, Ticket } from 'issueloop';

const il = new IssueLoop();
const tickets: Ticket[] = await il.getAllErrors('myrepo');

The Ticket interface:

export interface Ticket {
  id: string;
  repo: string;
  priority: "blocking" | "high" | "normal" | "low";
  status: "pending" | "in_progress" | "blocked" | "done" | "failed" | "needs_human";
  error_summary: string;
  raw_log_ref: string;
  command: string | null;
  test_id: string | null;
  attempts: number;
  escalation_summary: string | null;
  proposed_fix: string | null;
  created_at: string;
  resolved_at: string | null;
  dispensed_at: string | null;
}

The priority and status fields are typed as union literals, so TypeScript will catch invalid values at compile time.

REST convenience methods

These five methods map directly to the REST endpoints exposed by issueloop serve.

Method	Signature	Returns
`health`	`health()`	`Promise<{ status: string }>`
`getTopError`	`getTopError(repo: string)`	`Promise<Ticket \| null>`
`getAllErrors`	`getAllErrors(repo: string)`	`Promise<Ticket[]>`
`resolve`	`resolve(ticketId: string)`	`Promise<{ status: string }>`
`fail`	`fail(ticketId: string)`	`Promise<{ status: string }>`

// Check the server is up
const { status } = await il.health();

// Get all open tickets
const all: Ticket[] = await il.getAllErrors('myrepo');

// Claim the top ticket and mark it failed if something went wrong
const ticket = await il.getTopError('myrepo');
if (ticket) {
  await il.fail(ticket.id);
}

getTopError returns null (not an empty object) when there are no pending tickets, so a simple if (ticket) guard is safe.

RPC methods

The IssueLoop class exposes 45 additional camelCase methods that call the Python API via a POST /rpc/<function_name> request. Each method accepts a single params object whose keys are the Python function’s snake_case parameter names, and returns the unwrapped result field from the server’s response envelope.

// Call scan_repo with repo_path kwarg
const inventory = await il.scanRepo({ repo_path: '/path/to/repo' });

// Call get_all_bugs with repo kwarg
const bugs = await il.getAllBugs({ repo: 'myrepo' });

// Call propose_fix with ticket_id and patch_or_command kwargs
await il.proposeFix({ ticket_id: ticket.id, patch_or_command: "sed -i 's/old/new/' file.py" });

All 45 RPC methods

Scan & test

Method	Python function	Description
`scanRepo(params)`	`scan_repo`	Build a file inventory for a repo path
`getFileInventory(params)`	`get_file_inventory`	Retrieve the stored file inventory
`runTests(params)`	`run_tests`	Run `test_manifest.json` commands and write the log cache
`runSingleTest(params)`	`run_single_test`	Run a single test command
`createTickets(params)`	`create_tickets`	Split failing log entries into tickets via LLM

Bug query

Method	Python function	Description
`getAllBugs(params)`	`get_all_bugs`	Return all tickets for a repo
`getUnresolvedBugs(params)`	`get_unresolved_bugs`	Return tickets that are not yet resolved
`getResolvedBugs(params)`	`get_resolved_bugs`	Return tickets with status `done`
`getFailedBugs(params)`	`get_failed_bugs`	Return tickets with status `failed`
`getBugsNeedingHuman(params)`	`get_bugs_needing_human`	Return tickets escalated to `needs_human`
`getBugsByStatus(params)`	`get_bugs_by_status`	Filter tickets by a specific status string
`getBugsByPriority(params)`	`get_bugs_by_priority`	Filter tickets by priority level
`getBug(params)`	`get_bug`	Fetch a single ticket by ID
`getBugCount(params)`	`get_bug_count`	Return the total number of tickets for a repo
`getBugCountByStatus(params)`	`get_bug_count_by_status`	Return ticket counts grouped by status
`searchBugs(params)`	`search_bugs`	Full-text search over ticket summaries
`getOldestBug(params)`	`get_oldest_bug`	Return the oldest ticket for a repo
`getNewestBug(params)`	`get_newest_bug`	Return the most recently created ticket

Ticket lifecycle

Method	Python function	Description
`escalate(params)`	`escalate`	Escalate a ticket with a reason
`reassign(params)`	`reassign`	Reset a ticket back to pending
`retryBug(params)`	`retry_bug`	Increment attempts and reset a failed ticket to pending
`getBugAttempts(params)`	`get_bug_attempts`	Return the attempt count for a ticket
`bulkResolve(params)`	`bulk_resolve`	Resolve multiple tickets at once

Fix-apply

Method	Python function	Description
`proposeFix(params)`	`propose_fix`	Store a proposed patch or command on a ticket
`applyFix(params)`	`apply_fix`	Apply the stored fix and re-run the associated test
`checkPermission(params)`	`check_permission`	Check whether a command is on the allowlist
`getPermissionAuditLog(params)`	`get_permission_audit_log`	Retrieve the full permission audit log

Live monitoring

Method	Python function	Description
`watchProcess(params)`	`watch_process`	Spawn a process and watch its output for errors
`watchLogFile(params)`	`watch_log_file`	Tail an existing log file for errors
`stopWatch(params)`	`stop_watch`	Stop a live watcher by handle
`listActiveWatchers(params)`	`list_active_watchers`	List all currently running watchers

LLM & tokens

Method	Python function	Description
`getTokenConsumption(params)`	`get_token_consumption`	Return total token usage
`getTokenConsumptionByProvider(params)`	`get_token_consumption_by_provider`	Return token usage broken down by LLM provider
`getLlmCallHistory(params)`	`get_llm_call_history`	Return the history of LLM calls
`getLlmProviderStatus(params)`	`get_llm_provider_status`	Return the status of configured LLM providers

Database & maintenance

Method	Python function	Description
`cleanup(params)`	`cleanup`	Delete resolved/failed tickets older than N days
`purgeRepo(params)`	`purge_repo`	Delete all data for a repo
`getDatabaseStats(params)`	`get_database_stats`	Return database size and record counts
`exportBugs(params)`	`export_bugs`	Export tickets to a JSON file
`reapStaleBugs(params)`	`reap_stale_bugs`	Mark long-stale in-progress tickets as failed
`rotateLogs(params)`	`rotate_logs`	Rotate the raw log cache for a repo

Notifications & config

Method	Python function	Description
`getCrashLog(params)`	`get_crash_log`	Return the IssueLoop internal crash log
`getNotificationConfig(params)`	`get_notification_config`	Return the current notification configuration
`listRepos(params)`	`list_repos`	Return all repo names known to the database
`healthCheck(params)`	`health_check`	Run a full internal health check

The Node.js client requires the Python IssueLoop server to be running first. Start it with issueloop serve (or issueloop serve --port <n> for a custom port) before constructing an IssueLoop instance. See the HTTP Server page for details on the server itself.

Get Started

Guides

Configuration

Client SDKs

IssueLoop Node.js and TypeScript Client npm Package

Installation

Getting started

TypeScript support

REST convenience methods

RPC methods

Build docs developers (and LLMs) love

Get Started

Guides

Configuration

Client SDKs

Documentation Index

​Installation

​Getting started

​TypeScript support

​REST convenience methods

​RPC methods

Build docs developers (and LLMs) love

Installation

Getting started

TypeScript support

REST convenience methods

RPC methods