integration-template

The ProxyHat Integration Standard — how every *-proxyhat package is built, so all 20+ integrations look, behave, test, and self-update the same way.

New integration? Don't start from scratch. Copy the nearest living reference and adapt:

• Node / TypeScript → crawlee-proxyhat
• Python → scrapy-proxyhat

This repo holds the shared CI / compat / Renovate files and the checklist. See CHECKLIST.md.

Principles

1. Integrate, never fork. Depend on the upstream tool and plug into its first-class extension point (middleware, provider, plugin, transport, loader). Upstream's updates then reach users for free; we never rebase a fork.
2. One repo per tool, named <tool>-proxyhat (npm may also scope @proxyhat/<tool>). Maximises discovery and org-profile visibility.
3. Depth, not a URL-builder. Every integration exposes: geo (country/region/city/filter), sticky sessions, rotation, and — where the tool has a session concept — a mapping of that session to a pinned ProxyHat IP. Reuse the proxyhat SDK's connection helpers; never re-implement the username grammar.
4. Config parity. Options win over env. Support apiKey/PROXYHAT_API_KEY (auto-pick an active sub-user), or explicit username+password (PROXYHAT_USERNAME/PROXYHAT_PASSWORD), plus optional subUser/PROXYHAT_SUBUSER.
5. Honest READMEs. Same sections and tone as the references; UTM link https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=<tool>; no overclaiming.
6. Autonomous updates. Renovate opens upstream-bump PRs; a weekly compat job tests against <upstream>@latest; green CI auto-merges. That is how we "track updates automatically" — not by forking.

Autonomy engine

upstream releases → Renovate PR → CI + compat matrix (tests vs latest)
      → green: auto-merge + (on Release/tag) auto-publish
      → red:  compat job opens a tracking issue

• Node publishes to npm on a GitHub Release (release.yml, org NPM_TOKEN, provenance).
• Python publishes to PyPI on a v* tag via Trusted Publisher / OIDC (no token).

Layout of a finished integration

<tool>-proxyhat/
├── README.md            # standard sections + badges (CI, compat, npm/PyPI, MIT)
├── LICENSE              # MIT © ProxyHat
├── src/…                # the integration (thin, deep, tested)
├── test|tests/…         # mock the network & SDK; test URL/config building, sticky vs rotating, geo, creds
├── examples/…           # one runnable example
├── renovate.json
└── .github/workflows/   # ci.yml, compat.yml, (+ release.yml for npm)

Copy the shared files from templates/node or templates/python.

License

MIT © ProxyHat