proxyverity-widget 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 ProxyVerity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# ProxyVerity Proxy Checker Widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An embeddable proxy checker: one `<script>` tag puts a working checker on your
+page. Your visitors paste proxies, we check them on our side, and the results
+open on a page they can bookmark or share. Free, no account, and nothing to
+install on your server.
+
+**Build your snippet:** <https://proxyverity.github.io/Proxy-Checker-Widget/>
+— pick the theme and colours, see the real widget change as you do, copy the
+tag.
+
+**Reference documentation:** <https://proxyverity.com/proxy-checker-widget/>
+**Hosted checker:** <https://proxyverity.com/proxy-checker/>
+
+---
+
+## Quick start
+
+```html
+<script src="https://api.proxyverity.com/widget/embed.js"
+        async
+        data-width="100%"
+        data-height="520"
+        data-theme="light"></script>
+```
+
+The widget appears where the tag is, followed by a short credit line. That
+line is the condition of use — see below.
+
+## Install from a package registry
+
+The tag above is all you need — these packages only build it for you and
+contain no copy of the loader. The checker always runs from
+`api.proxyverity.com`, so a fix on our side reaches you without a release
+here.
+
+### npm
+
+```sh
+npm install proxyverity-widget
+```
+
+```js
+import { mount } from 'proxyverity-widget';
+
+mount('#checker', { theme: 'auto', accent: '#ff6600', radius: 12 });
+```
+
+`createEmbedScript(options)` returns the element without inserting it, and
+`embedTag(options)` returns the snippet as a string for server-side rendering.
+
+### Composer
+
+```sh
+composer require proxyverity/proxy-checker-widget
+```
+
+```php
+use ProxyVerity\Widget\Embed;
+
+echo Embed::tag(['theme' => 'auto', 'accent' => '#ff6600', 'radius' => 12]);
+```
+
+Option names are the camelCase form of the attributes in [Options](#options):
+`chunkSize` for `data-chunk-size`, and so on. Unknown keys are ignored rather
+than rendered. Values are passed through and validated on our side, where an
+invalid one falls back to the theme's default.
+
+Both packages are MIT-licensed. The credit line described below is a condition
+of using the hosted widget, not of using this code.
+
+
+## The credit line
+
+The widget adds this underneath itself, in your page:
+
+> Proxy checker by [ProxyVerity](https://proxyverity.com/)
+
+**Keeping it visible is the condition of use.** The widget is free and the
+credit is what it costs. It is a plain line of text with a plain link, and it
+inherits your page's colour and typeface, so it reads as part of your design
+rather than a sticker on top of it. `data-credit` and `data-credit-align` move
+it where you want it.
+
+What you may not do is hide it, shrink it below legibility, or make it
+transparent. You could, in two lines of CSS — we are asking, not preventing.
+It is also what Google expects of an attribution link, so a hidden one is a
+problem for both of us.
+
+The credit's text and destination are not configurable, and will not become
+configurable.
+
+## Options
+
+| Attribute | Values | Default | Effect |
+|---|---|---|---|
+| `data-width` | any CSS width; a bare number means px | `100%` | container width |
+| `data-height` | px or percent | `520` | starting height; the widget then resizes itself |
+| `data-theme` | `light`, `dark`, `auto` | `light` | `auto` follows the visitor's OS setting |
+| `data-accent` | `#rgb`, `#rrggbb` | `#2563eb` | button and links |
+| `data-bg` | `#rgb`, `#rrggbb`, `transparent` | theme's | background |
+| `data-fg` | `#rgb`, `#rrggbb` | theme's | main text |
+| `data-border` | `#rgb`, `#rrggbb` | theme's | field and panel borders |
+| `data-radius` | `0`–`24` | `6` | corner radius in px |
+| `data-font` | `system`, `sans`, `serif`, `mono` | `sans` | typeface |
+| `data-threshold` | integer | `50` | lists this size or smaller go in one request |
+| `data-chunk-size` | integer | `50` | proxies per request for longer lists |
+| `data-open-results` | `1`, `0` | `0` | `1` opens the results page in a new tab |
+| `data-credit` | `below`, `above` | `below` | which side of the widget the credit sits on |
+| `data-credit-align` | `left`, `center`, `right` | `left` | credit alignment |
+
+Colours must be hex — `#ff8800` or `#f80`. Named colours and `rgb()` are not
+accepted, and anything unreadable is replaced by the theme's own value, so a
+typo leaves you with a working widget rather than a broken one.
+
+`data-font` defaults to `sans` (Arial), which is what the widget has always
+used. `system` uses the visitor's own interface font and usually blends in
+better; it is recommended for new embeds rather than imposed on existing ones.
+
+## Matching a design
+
+The widget runs in an iframe, so your stylesheet cannot reach inside it —
+these attributes are how your styling gets in.
+
+```html
+<script src="https://api.proxyverity.com/widget/embed.js"
+        async
+        data-theme="auto"
+        data-accent="#ff8800"
+        data-bg="transparent"
+        data-radius="14"
+        data-font="system"></script>
+```
+
+`data-bg="transparent"` lets your page show through instead of a white panel
+sitting on it, which usually looks best on a coloured or patterned background.
+
+Two things look after themselves: `data-theme="auto"` follows the visitor's
+light or dark system setting, and the button's label colour is computed from
+your accent, so a pale accent gets dark text instead of unreadable white.
+
+## How it works
+
+1. The tag loads a small loader script, which inserts a sandboxed iframe plus
+   the credit line.
+2. Visitors enter proxies as `IP:Port`, optionally with a protocol prefix.
+   Lists of `data-threshold` or fewer go in one request; longer ones are sent
+   in batches of `data-chunk-size`, about one a second, with progress shown.
+3. Checking happens on our servers, so your visitors' browsers never connect
+   to the proxies they are testing.
+4. Results open on `/result.php?hash=…`, which has its own address. The widget
+   does not render results row by row.
+5. The iframe reports only its own height back to your page, over
+   `postMessage`. Your page sends it nothing and never handles the proxy data.
+
+If a visitor goes faster than the service allows they see a short wait message
+and the widget retries by itself.
+
+## Support
+
+Questions and problems: <https://proxyverity.com/>

package/index.js

@@ -0,0 +1,126 @@
+/**
+ * proxyverity-widget — a thin wrapper around the hosted ProxyVerity proxy
+ * checker widget.
+ *
+ * This package contains no checking logic and no copy of the loader. It builds
+ * the same <script> tag you would paste by hand and lets the hosted loader at
+ * api.proxyverity.com do the rest, so a change on our side reaches you without
+ * a release on yours.
+ *
+ * Docs: https://proxyverity.com/proxy-checker-widget/
+ * Snippet builder: https://proxyverity.github.io/Proxy-Checker-Widget/
+ */
+
+/** URL of the hosted loader. */
+export const EMBED_SRC = 'https://api.proxyverity.com/widget/embed.js';
+
+/**
+ * Option name -> data attribute. Anything not listed here is ignored, so a
+ * typo cannot silently become an attribute the loader does not understand.
+ *
+ * The credit's anchor text and destination are deliberately absent: they are
+ * fixed in the loader and are not configurable here or anywhere else.
+ */
+const ATTRIBUTES = {
+  width: 'data-width',
+  height: 'data-height',
+  theme: 'data-theme',
+  accent: 'data-accent',
+  bg: 'data-bg',
+  fg: 'data-fg',
+  border: 'data-border',
+  radius: 'data-radius',
+  font: 'data-font',
+  threshold: 'data-threshold',
+  chunkSize: 'data-chunk-size',
+  openResults: 'data-open-results',
+  credit: 'data-credit',
+  creditAlign: 'data-credit-align',
+};
+
+/**
+ * Values are passed through untouched. They are validated server-side, where
+ * an invalid one falls back to the theme's default without an error. Checking
+ * them again here would mean two sets of rules that can disagree.
+ */
+function applyOptions(script, options) {
+  for (const [key, attribute] of Object.entries(ATTRIBUTES)) {
+    const value = options[key];
+    if (value === undefined || value === null || value === '') continue;
+    script.setAttribute(attribute, String(value));
+  }
+}
+
+/**
+ * Build the <script> element without inserting it. Useful when you want to
+ * place it yourself, or to inspect what would be inserted.
+ *
+ * @param {Object} [options] see ATTRIBUTES above
+ * @returns {HTMLScriptElement}
+ */
+export function createEmbedScript(options = {}) {
+  const script = document.createElement('script');
+  script.src = EMBED_SRC;
+  script.async = true;
+  applyOptions(script, options);
+  return script;
+}
+
+/**
+ * Insert the widget into the page.
+ *
+ * The loader places the widget immediately after its own <script> tag, so the
+ * tag is appended inside `target` and the widget appears there.
+ *
+ * @param {Element|string} [target] element or CSS selector; defaults to <body>
+ * @param {Object} [options] see ATTRIBUTES above
+ * @returns {HTMLScriptElement} the inserted script element
+ */
+export function mount(target, options = {}) {
+  if (typeof document === 'undefined') {
+    throw new Error(
+      'proxyverity-widget: mount() needs a DOM. Call it in the browser, not during server rendering.'
+    );
+  }
+
+  // mount({ theme: 'dark' }) — target omitted, options passed first.
+  if (target && typeof target === 'object' && !(target instanceof Element)) {
+    options = target;
+    target = undefined;
+  }
+
+  const element =
+    typeof target === 'string' ? document.querySelector(target) : target || document.body;
+
+  if (!element) {
+    throw new Error(`proxyverity-widget: no element matched ${JSON.stringify(target)}`);
+  }
+
+  const script = createEmbedScript(options);
+  element.appendChild(script);
+  return script;
+}
+
+/**
+ * The snippet as a string, for server-side rendering or for pasting into a
+ * template. Attribute values are escaped for an HTML attribute context.
+ *
+ * @param {Object} [options] see ATTRIBUTES above
+ * @returns {string}
+ */
+export function embedTag(options = {}) {
+  const escape = (value) =>
+    String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+
+  const attributes = Object.entries(ATTRIBUTES)
+    .filter(([key]) => {
+      const value = options[key];
+      return value !== undefined && value !== null && value !== '';
+    })
+    .map(([key, attribute]) => `\n        ${attribute}="${escape(options[key])}"`)
+    .join('');
+
+  return `<script src="${EMBED_SRC}"\n        async${attributes}></script>`;
+}
+
+export default { EMBED_SRC, createEmbedScript, mount, embedTag };

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "proxyverity-widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Embeddable proxy checker widget: one script tag puts a working HTTP/HTTPS/SOCKS proxy checker on your page. No server, no account, no build step.",
+  "keywords": [
+    "proxy",
+    "proxy-checker",
+    "proxy-tester",
+    "proxy-list",
+    "proxy-validator",
+    "socks5",
+    "socks4",
+    "http-proxy",
+    "widget",
+    "embed",
+    "embeddable"
+  ],
+  "homepage": "https://proxyverity.com/proxy-checker-widget/",
+  "bugs": {
+    "url": "https://github.com/ProxyVerity/Proxy-Checker-Widget/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProxyVerity/Proxy-Checker-Widget.git"
+  },
+  "license": "MIT",
+  "author": "ProxyVerity (https://proxyverity.com/)",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false
+}