⚡ Putty - Network Interceptor Core

Intercept, mock, and debug network requests in real-time with a beautiful developer tool

✨ Features

🚀 Real-time Request Interception - Capture and inspect all HTTP requests as they happen
🎯 Smart Request Matching - Intercept requests by URL patterns, methods, or custom rules
🔄 Dynamic Response Mocking - Replace API responses with custom JSON, status codes, and headers
⚡ Zero Configuration - Works out of the box with any web application
🎨 Beautiful UI - Modern, intuitive interface that feels native to your development workflow
🔧 Developer Friendly - Built with TypeScript, React, and modern web standards
📦 Lightweight - Minimal bundle size with no external dependencies
🌐 Framework Agnostic - Works with React, Vue, Angular, vanilla JS, and more

🎯 Use Cases

• API Development - Test your frontend against mock APIs before backend is ready
• Error Testing - Simulate network errors, timeouts, and edge cases
• Performance Testing - Mock slow responses to test loading states
• Offline Development - Continue development when APIs are down
• QA Testing - Create consistent test scenarios for different API states
• Debugging - Inspect request/response data in real-time

🚀 Quick Start

Installation

npm install @puttyapp/core

Basic Usage

import { NetworkInterceptorWidget } from '@puttyapp/core';

// Initialize the widget
const interceptor = new NetworkInterceptorWidget();
interceptor.init();

Advanced Usage

import { NetworkInterceptorWidget } from '@puttyapp/core';

// Create interceptor with custom options
const interceptor = new NetworkInterceptorWidget({
  position: 'bottom-right', // Widget position
  theme: 'dark',            // UI theme
  autoStart: true,          // Start intercepting immediately
});

// Initialize and start intercepting
interceptor.init();

// Programmatically add intercept rules
interceptor.addInterceptRule({
  url: '/api/users/*',
  method: 'GET',
  responseStatus: 200,
  responseBody: JSON.stringify({ users: [] }),
  enabled: true
});

🎮 Interactive Demo

See the demo above or try the live demo.

📖 Documentation

API Reference

NetworkInterceptorWidget

The main class for managing network interception.

class NetworkInterceptorWidget {
  constructor(options?: WidgetOptions)
  init(): void
  destroy(): void
  addInterceptRule(rule: InterceptRule): void
  removeInterceptRule(id: string): void
  toggleInterceptRule(id: string): void
  getRequests(): NetworkRequest[]
  clearRequests(): void
  setGlobalPassthrough(enabled: boolean): void
}

InterceptRule

Define how requests should be intercepted and mocked.

interface InterceptRule {
  id?: string
  url: string
  method: string
  enabled: boolean
  responseStatus: number
  responseBody: string
  responseHeaders?: Record<string, string>
  createdAt?: number
}

Configuration Options

interface WidgetOptions {
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
  theme?: 'light' | 'dark' | 'auto'
  autoStart?: boolean
  globalPassthrough?: boolean
  maxRequests?: number
}

🎮 Interactive Demo

Try the live demo: Demo App

🛠️ Development

We welcome contributions! To develop or test changes to this package:

Prerequisites

• Node.js 18+
• npm

Setup

# Clone the repository
git clone https://github.com/puttyapp/core.git
cd core

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

See CONTRIBUTING.md for more details on our development workflow and guidelines.

🤝 Contributing

We love contributions! Please see our Contributing Guide for how to get started.

📦 Packages

• @puttyapp/core – This package (open source)

🏗️ Architecture

• TypeScript, React, Tailwind CSS, Web Components, Service Workers

🎯 Roadmap

• [ ] Request History Persistence - Save and restore intercept rules
• [ ] Import/Export Rules - Share configurations between team members
• [ ] Advanced Matching - Regex patterns, custom matchers
• [ ] Response Templates - Pre-built response templates
• [ ] Performance Metrics - Request timing and performance insights
• [ ] Plugin System - Extend functionality with plugins
• [ ] Team Collaboration - Share rules across team members

📄 License

MIT License – see LICENSE

🙏 Acknowledgments

• Built with ❤️ by the Putty team
• Inspired by Postman, Charles Proxy, browser dev tools

Made with ❤️ for developers everywhere