npm package: @puttyapp/core
Description: Core network interceptor functionality - open source
Author: Putty
Latest version: 0.1.1

[![npm version](https://img.shields.io/npm/v/@puttyapp/core.svg)](https://www.npmjs.com/package/@puttyapp/core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)


# ⚡ Putty - Network Interceptor Core

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

<p align="center">
  <img src="./demo.gif" alt="Network Interceptor Demo" width="700" />
</p>
<p align="center"><i>See Network Interceptor Core in action!</i></p>

## ✨ 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

```bash
npm install @puttyapp/core
```

### Basic Usage

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

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

### Advanced Usage

```javascript
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](https://network-interceptor-demo.vercel.app).

## 📖 Documentation

### API Reference

#### NetworkInterceptorWidget

The main class for managing network interception.

```typescript
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.

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

### Configuration Options

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

## 🎮 Interactive Demo

<!-- TODO: Add demo video/GIF here -->
<!-- See Network Interceptor in action! Watch how easy it is to intercept and mock API requests. -->

Try the live demo: [Demo App](https://network-interceptor-demo.vercel.app)

## 🛠️ Development

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

### Prerequisites
- Node.js 18+
- npm

### Setup

```bash
# 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](CONTRIBUTING.md) for more details on our development workflow and guidelines.

## 🤝 Contributing

We love contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](LICENSE)

## 🙏 Acknowledgments

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

---

**Made with ❤️ for developers everywhere**


---
<p align="center">
  <img src="./putty-logo.png" alt="Putty Logo" width="120" height="120" />
</p>

<p align="center">
  <b>Learn more and try the Pro version at <a href="https://puttyapp.io">puttyapp.io</a></b>
</p>

---