Metadata-Version: 2.4
Name: deprecationwatch
Version: 0.1.0
Summary: Declare the APIs your project uses. Get alerted before they break.
Project-URL: Homepage, https://github.com/arunmm8335/DeprecationWatch
Project-URL: Repository, https://github.com/arunmm8335/DeprecationWatch
Project-URL: Issues, https://github.com/arunmm8335/DeprecationWatch/issues
Author-email: Arun <roy8335@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: api,changelog,deprecation,monitoring,openapi,slack
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: feedparser>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: litellm>=1.40
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: typer>=0.12
Provides-Extra: alerts
Requires-Dist: apprise>=1.7; extra == 'alerts'
Provides-Extra: all
Requires-Dist: apprise>=1.7; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'all'
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115; extra == 'dashboard'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: apprise>=1.7; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
Description-Content-Type: text/markdown

# DeprecationWatch

**Declare the APIs your project uses. Get alerted before they break.**

Open-source API deprecation monitoring for developers who *consume* third-party APIs — not the teams that publish them.

Dependabot bumps package versions. It doesn't tell you that OpenAI is removing `gpt-4-turbo` in October or that Stripe deprecated an endpoint your checkout flow still calls. DeprecationWatch closes that gap.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/deprecationwatch.svg)](https://pypi.org/project/deprecationwatch/)

## Why this exists

- **Dependabot / Renovate** — package versions, not API-level deprecations
- **Visualping** — visual page diffs, not structured developer alerts
- **API management platforms** — built for API *producers*, enterprise-priced
- **Optic** — closest prior art; repository archived January 2026

DeprecationWatch monitors official changelogs, SDK releases, and HTTP `Deprecation` / `Sunset` headers — then alerts you at 90, 30, and 7 days before removal.

## Dashboard

<p align="center">
  <img src="docs/images/dashboard.png" alt="DeprecationWatch dashboard showing API providers and deprecation timeline" width="900">
</p>

Local web UI — stat cards, provider health, urgency-sorted timeline:

```bash
pip install "deprecationwatch[dashboard]"
dep-watch dashboard
# → http://127.0.0.1:8080
```

Or from a clone:

```bash
git clone https://github.com/arunmm8335/DeprecationWatch && cd DeprecationWatch
pip install -e ".[dashboard]"
dep-watch dashboard
```

Toggle **Show expired** to include past removal dates:

<p align="center">
  <img src="docs/images/dashboard-expired.png" alt="DeprecationWatch dashboard with expired deprecations visible" width="900">
</p>

## Quick start

```bash
pip install deprecationwatch

# optional extras
pip install "deprecationwatch[alerts]"      # Slack / email
pip install "deprecationwatch[dashboard]"   # local web UI
pip install "deprecationwatch[all]"         # everything

dep-watch init          # creates depwatch.yml
dep-watch check         # scan live sources
```

Install from source (latest main):

```bash
pip install git+https://github.com/arunmm8335/DeprecationWatch.git
```

### Example output

```
✓ Stripe - no deprecations found
⚠ OpenAI gpt-4-turbo - DEPRECATED | removal: 2026-10-23 | 116 days left
  → Guide: https://platform.openai.com/docs/deprecations
✓ GitHub - no deprecations found
```

## Configuration

Copy [`depwatch.yml.example`](depwatch.yml.example) or run `dep-watch init`:

```yaml
version: 1
project: my-app

apis:
  - name: OpenAI
    type: openai
    track:
      - gpt-4
      - gpt-4-turbo

  - name: Stripe
    type: stripe
    track:
      - checkout.sessions.create

  - name: Twilio
    type: generic_changelog
    changelog_url: https://www.twilio.com/en-us/changelog
    track_keywords:
      - SMS

alerts:
  slack_webhook: https://hooks.slack.com/services/XXX/YYY/ZZZ
  days_warning: [90, 30, 7]
```

### Supported adapters

| Type | Source | LLM needed |
|---|---|---|
| `openai` | [OpenAI deprecations page](https://platform.openai.com/docs/deprecations) | No |
| `stripe` | Stripe changelog RSS | Optional |
| `github_rest` | GitHub changelog RSS | Optional |
| `generic_changelog` | Any changelog URL | Yes (for diffs) |
| `http_headers` | Live endpoint `Deprecation` / `Sunset` headers | No |

Add more providers — see [CONTRIBUTING.md](CONTRIBUTING.md).

### HTTP header probes

Many APIs send standard [Deprecation and Sunset headers](https://www.rfc-editor.org/rfc/rfc9745.html) on live responses. Probe endpoints you call in production:

```yaml
  - name: Example API
    type: http_headers
    track:
      - https://api.example.com/v1/users
    request_headers:
      Authorization: "Bearer ${YOUR_TOKEN}"
```

## Daemon mode

Run checks on a schedule locally (cron alternative):

```bash
dep-watch watch --interval 24h
dep-watch watch --interval 30m --once   # single run
```

Pairs with alerts — get Slack/email when thresholds are crossed without setting up cron.

## Alerts

Email and Slack via [Apprise](https://github.com/caronc/apprise). Deduplicated — you won't get the same 30-day warning twice.

```bash
pip install "deprecationwatch[alerts]"

dep-watch check --alert-dry-run   # test without sending
dep-watch check                   # sends when thresholds hit
dep-watch check --no-alerts       # skip (for CI)
```

## CI / GitHub Action

Fail the build when a tracked API is within 30 days of sunset:

```yaml
# .github/workflows/dep-watch.yml
name: API Deprecation Check

on:
  schedule:
    - cron: "0 9 * * 1"
  pull_request:
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: arunmm8335/DeprecationWatch/action@v1
        with:
          config: depwatch.yml
          fail-on: breaking
          days-threshold: "30"
```

Or run locally in CI mode:

```bash
dep-watch check --fail-on breaking --days-threshold 30
```

Emits GitHub workflow annotations when running in Actions.

## LLM classification

Unstructured changelogs use [LiteLLM](https://github.com/BerriAI/litellm) — bring your own model:

```bash
export DEPWATCH_LLM_MODEL=ollama/llama3              # free, local
export DEPWATCH_LLM_MODEL=anthropic/claude-haiku-4-5 # ~$0.001/run
export DEPWATCH_LLM_MODEL=none                         # skip LLM (OpenAI adapter still works)
```

## What we can't detect (yet)

Be honest about limits — PRs welcome:

- Providers that don't publish deprecations anywhere
- Changes buried in blog posts with no changelog
- Undocumented breaking changes with no headers
- False positives from LLM classification on generic changelogs

We optimize for **precision over recall**. A missed deprecation is bad; a false alarm every week is worse.

## Development

```bash
git clone https://github.com/arunmm8335/DeprecationWatch
cd DeprecationWatch
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,alerts,dashboard]"

pytest
dep-watch check --config depwatch.yml.example --fail-on none
```

## Project layout

```
dep-watch check      CLI — scan & alert
dep-watch watch      Daemon — scheduled checks
dep-watch dashboard  Local web UI
dep-watch report     JSON/table export
action/              GitHub Action composite
src/dep_watch/
  adapters/          One module per API provider
  alerts.py          Apprise + deduplication
  classifier.py      LiteLLM fallback
```

## Roadmap

- [x] Config parser, SQLite storage, OpenAI adapter
- [x] Stripe / GitHub / generic changelog adapters
- [x] Apprise alerts with deduplication
- [x] GitHub Action, local dashboard, expired filter
- [x] HTTP `Deprecation` / `Sunset` header monitor
- [x] `dep-watch watch` daemon mode
- [x] PyPI packaging (`pip install deprecationwatch`) — see [PUBLISHING.md](PUBLISHING.md)
- [ ] Community adapters (AWS, Azure, Razorpay, …)

## Contributing

Contributions are welcome — especially new **adapters**. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter pattern and PR guidelines.

## License

MIT — see [LICENSE](LICENSE).
