atsfill 0.0.5.dev141__tar.gz → 0.0.5.dev143__tar.gz

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atsfill
-Version: 0.0.5.dev141
+Version: 0.0.5.dev143
 Summary: Read, dry-run and submit job application forms on hiring systems: Ashby, Greenhouse, Teamtailor, Welcome to the Jungle.
 Keywords: job-applications,ats,ashby,greenhouse,teamtailor,ai-agents,cli
 Author: shbernal
@@ -20,6 +20,7 @@ Requires-Dist: camoufox==0.5.8
 Requires-Dist: filelock==4.1.1
 Requires-Dist: keyring==25.7.0
 Requires-Dist: packaging==26.3
+Requires-Dist: posthog==7.78.0
 Requires-Python: >=3.14
 Project-URL: Homepage, https://github.com/shbernal/atsfill
 Project-URL: Repository, https://github.com/shbernal/atsfill
@@ -152,6 +153,8 @@ The core owns every rule about when a send is allowed; an adapter only knows its
 Every result has a `status` (`ready`, `refused`, `submitted`, `blocked`, `unknown`, `unsupported`) and, when it is not clean, a `reason` code.
 The exit code is 0 for `ready` and `submitted`, 1 otherwise, 2 for a usage error.
 
+Each `read`, `fill` and `send` sends one anonymous event (the system, the command, the status, a hash of the posting, never answers or URLs): [what is sent and how to turn it off](docs/telemetry.md).
+
 ## More
 
 - [Architecture decisions](docs/adr/README.md): the contract, the submit gate, the browser, sessions.

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/README.md

@@ -124,6 +124,8 @@ The core owns every rule about when a send is allowed; an adapter only knows its
 Every result has a `status` (`ready`, `refused`, `submitted`, `blocked`, `unknown`, `unsupported`) and, when it is not clean, a `reason` code.
 The exit code is 0 for `ready` and `submitted`, 1 otherwise, 2 for a usage error.
 
+Each `read`, `fill` and `send` sends one anonymous event (the system, the command, the status, a hash of the posting, never answers or URLs): [what is sent and how to turn it off](docs/telemetry.md).
+
 ## More
 
 - [Architecture decisions](docs/adr/README.md): the contract, the submit gate, the browser, sessions.

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.5.dev141"
+version = "0.0.5.dev143"
 description = "Read, dry-run and submit job application forms on hiring systems: Ashby, Greenhouse, Teamtailor, Welcome to the Jungle."
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,7 @@ dependencies = [
     "filelock==4.1.1",
     "keyring==25.7.0",
     "packaging==26.3",
+    "posthog==7.78.0",
 ]
 
 [[project.authors]]

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.5.dev141"
+version = "0.0.5.dev143"
 description = "Read, dry-run and submit job application forms on hiring systems: Ashby, Greenhouse, Teamtailor, Welcome to the Jungle."
 readme = "README.md"
 license = "MIT"
@@ -25,6 +25,7 @@ dependencies = [
     "filelock==4.1.1",
     "keyring==25.7.0",
     "packaging==26.3",
+    "posthog==7.78.0",
 ]
 
 [project.urls]

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/cli.py

@@ -190,6 +190,8 @@ def run(args: argparse.Namespace) -> int:
                 return 2
             emit(session, args.verbose)
             return 0 if args.command == "logout" or session.session == "signed_in" else 1
+    if result.notice:
+        print(f"atsfill: {result.notice}", file=sys.stderr)
     emit(result, args.verbose, args.command)
     return 0 if result.status in OK else 1
 

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/core/commands.py

@@ -15,6 +15,7 @@ from atsfill.core import (
     passwords,
     paths,
     registry,
+    telemetry,
 )
 from atsfill.core.adapter import (
     Adapter,
@@ -353,6 +354,11 @@ def read(
 ) -> Result:
     """Lists the form's fields by a request read when an adapter has one (ADR 0011), else by a
     browser read."""
+    data = paths.data_dir(data_dir)
+    return telemetry.sent("read", _read(data, user, url, sessions), data)
+
+
+def _read(data: Path, user: str, url: str, sessions: Sessions | None) -> Result:
     for adapter in adapters():
         if not isinstance(adapter, ReadsByRequest):
             continue
@@ -364,7 +370,6 @@ def read(
                 return Result(Status.UNSUPPORTED, url, adapter.name, f"adapter_error: {e}")
             _unfillable(result)
             return result
-    data = paths.data_dir(data_dir)
     return _in_budget(url, lambda seen: _browser_read(data, user, url, sessions, seen))
 
 
@@ -377,9 +382,10 @@ def fill(
     sessions: Sessions | None = None,
 ) -> Result:
     data = paths.data_dir(data_dir)
-    return _in_budget(
+    result = _in_budget(
         url, lambda seen: _form_command(data, user, url, answers, sessions, False, False, seen)
     )
+    return telemetry.sent("fill", result, data)
 
 
 def send(
@@ -392,9 +398,10 @@ def send(
     sessions: Sessions | None = None,
 ) -> Result:
     data = paths.data_dir(data_dir)
-    return _in_budget(
+    result = _in_budget(
         url, lambda seen: _form_command(data, user, url, answers, sessions, True, resend, seen)
     )
+    return telemetry.sent("send", result, data)
 
 
 def _sessions(data: Path, users: list[str], candidates: list[Adapter]) -> list[SessionReport]:

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/core/paths.py

@@ -12,6 +12,7 @@ TEST_USER = "test"
 USER_NAME = re.compile(r"[a-z0-9-]+")
 RENAMED = {"submit": "submit-allowed", "ack_side_effects": "mute-side-effect-warnings"}
 MOVED = ("sessions", "attempts.jsonl")  # a data directory from before users, the default's
+TELEMETRY = ("off", "basic", "detailed")  # the first is no telemetry (ADR 0016)
 
 
 class ConfigError(Exception):
@@ -72,6 +73,8 @@ def _config() -> dict:
         for old, new in RENAMED.items():
             if old in section:
                 raise ConfigError(f"`{old}` in {path} is now `{new}`")
+    if (level := whole.get("telemetry", "basic")) not in TELEMETRY:
+        raise ConfigError(f"telemetry = {level!r} in {path}: one of {', '.join(TELEMETRY)}")
     return whole
 
 
@@ -84,6 +87,11 @@ def config(user: str) -> dict:
     return whole.get("users", {}).get(user, {})
 
 
+def telemetry() -> str:
+    """The home's telemetry level, a top-level key: `basic` unless the config says otherwise."""
+    return _config().get("telemetry", "basic")
+
+
 def submit_enabled(adapter: str, user: str) -> bool:
     """Whether the user's `submit-allowed` lists the adapter: there is no other way to enable
     it."""

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/core/registry.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, fields
 from datetime import date
 from functools import cache
 from importlib.resources import files
+from urllib.parse import urlsplit
 
 KINDS = ("ats", "board", "aggregator", "custom")
 ACCOUNTS = ("none", "to_send", "to_read")  # also the backlog order (ADR 0013)
@@ -46,6 +47,7 @@ class Source:
     account: str
     hosting: tuple[str, ...]
     adapter: str | None = None
+    hosts: tuple[str, ...] = ()  # a source without an adapter: where its postings are
     share: float | None = None
     links_to: tuple[str, ...] = ()  # an aggregator's: the sources its postings link to
     block: Block | None = None
@@ -80,6 +82,7 @@ def _source(name: str, entry: dict) -> Source:
         entry["account"],
         tuple(entry.get("hosting", [])),
         entry.get("adapter"),
+        tuple(entry.get("hosts", [])),
         entry.get("share"),
         tuple(entry.get("links_to", [])),
         block,
@@ -121,6 +124,13 @@ def for_adapter(name: str) -> Source | None:
     return next((s for s in sources().values() if s.adapter == name), None)
 
 
+def for_url(url: str) -> Source | None:
+    """The source whose `hosts` a URL is on, a subdomain included."""
+    host = urlsplit(url).hostname or ""
+    on = lambda h: host == h or host.endswith(f".{h}")  # noqa: E731
+    return next((s for s in sources().values() if any(map(on, s.hosts))), None)
+
+
 def _backlog_key(s: Source) -> tuple:
     stopped = s.block is not None or s.scope.reason is not None
     return (stopped, ACCOUNTS.index(s.account), -(s.share or 0), s.name)

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/core/results.py

@@ -101,6 +101,7 @@ class Result:
     checks: list[Check] = field(default_factory=list)
     side_effects: list[SideEffect] = field(default_factory=list)
     evidence: str | None = None
+    notice: str | None = None  # telemetry's, the first time it is on (ADR 0016)
 
 
 @dataclass

atsfill-0.0.5.dev143/src/atsfill/core/telemetry.py

@@ -0,0 +1,163 @@
+"""Anonymous telemetry (ADR 0016): one `run` event per `read`, `fill` and `send`, built from
+the command's result. Never in the way: any failure is dropped and the result goes back as it
+came, but for the first-run notice."""
+
+import hashlib
+import json
+import logging
+import os
+import subprocess
+import sys
+import uuid
+from contextlib import suppress
+from functools import cache
+from importlib.metadata import PackageNotFoundError, distribution, version
+from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from posthog import Posthog
+
+from atsfill.adapters import adapters
+from atsfill.core import paths, registry
+from atsfill.core.results import Result, Status
+
+PROJECT_KEY = "phc_xmrdiXySbbZCdUzdbdNUtjMco3rLL2Ko5j4hFrX9fUQ8"  # ingestion only, safe to ship
+HOST = "https://eu.i.posthog.com"
+REQUEST_TIMEOUT_SECONDS = 3
+MAX_RETRIES = 1
+FLUSH_TIMEOUT_SECONDS = 2  # the SDK's shutdown() waits without one
+GIT_TIMEOUT_SECONDS = 2
+ROOT = Path(__file__).parents[3]  # the checkout, for an editable install
+NOTICE_FILE = "telemetry-notice"  # in the data directory, once the notice was shown
+NOTICE = (
+    "telemetry: atsfill sends an anonymous event per read, fill and send, no answers or URLs;"
+    ' set telemetry = "off" in {config} or DO_NOT_TRACK=1 to stop it:'
+    " https://github.com/shbernal/atsfill/blob/main/docs/telemetry.md"
+)
+# Reason codes that say nothing about the adapter: the user's input or a fact about the posting
+EXCLUDED = (
+    "invalid_answers",
+    "answer_not_taken",
+    "not_qualified",
+    "already_sent",
+    "submit_not_enabled",
+    "out_of_scope",
+    "posting_gone",
+    "external_step",
+)
+
+logging.getLogger("posthog").disabled = True
+
+
+def _code(reason: str | None) -> str | None:
+    return reason.partition(":")[0] if reason else None
+
+
+def verdict(result: Result) -> str:
+    """What the run says about its adapter: `pass`, `fail`, `excluded` or `unsupported`."""
+    if result.status in (Status.READY, Status.SUBMITTED):
+        return "pass"
+    code = _code(result.reason)
+    if code in EXCLUDED:
+        return "excluded"
+    return "unsupported" if code == "no_adapter" else "fail"
+
+
+def posting_hash(url: str) -> str:
+    """The URL hashed without its fragment and `utm_` parameters, scheme and host lowercased."""
+    parts = urlsplit(url)
+    query = urlencode([(k, v) for k, v in parse_qsl(parts.query) if not k.startswith("utm_")])
+    normal = urlunsplit((parts.scheme.lower(), parts.netloc.lower(), parts.path, query, ""))
+    return hashlib.sha256(normal.encode()).hexdigest()
+
+
+def _posting(result: Result) -> str:
+    """The posting's key where its adapter gives one, as the double-send guard keys it, so
+    every URL of a posting hashes the same; else its URL."""
+    adapter = next((a for a in adapters() if a.name == result.system), None)
+    return adapter.posting(result.url) if adapter else result.url
+
+
+def _system(result: Result) -> str:
+    if result.system:
+        return result.system
+    source = registry.for_url(result.url)
+    return source.name if source else "unknown"
+
+
+def _in_tests_or_ci() -> bool:
+    return "pytest" in sys.modules or any(
+        os.environ.get(v) for v in ("PYTEST_VERSION", "PYTEST_CURRENT_TEST", "CI")
+    )
+
+
+def level() -> str:
+    """`off` under DO_NOT_TRACK, the test suite and CI, whatever the config says."""
+    if os.environ.get("DO_NOT_TRACK", "") not in ("", "0") or _in_tests_or_ci():
+        return "off"
+    return paths.telemetry()
+
+
+@cache
+def origin() -> tuple[str, str | None]:
+    """`dev` and HEAD for an editable install (HEAD only on a clean tree), else `user`."""
+    try:
+        direct = json.loads(distribution("atsfill").read_text("direct_url.json") or "{}")
+    except PackageNotFoundError, json.JSONDecodeError:
+        direct = {}
+    if not direct.get("dir_info", {}).get("editable"):
+        return "user", None
+    try:
+        git = lambda *a: subprocess.run(  # noqa: E731
+            ["git", *a], capture_output=True, text=True, cwd=ROOT, timeout=GIT_TIMEOUT_SECONDS
+        ).stdout.strip()
+        return "dev", None if git("status", "--porcelain") else git("rev-parse", "HEAD") or None
+    except OSError, subprocess.SubprocessError:
+        return "dev", None
+
+
+def event(command: str, result: Result) -> dict:
+    source, commit = origin()
+    properties = {
+        "system": _system(result),
+        "command": command,
+        "verdict": verdict(result),
+        "status": result.status.value,
+        "reason": _code(result.reason),
+        "version": version("atsfill"),
+        "posting": posting_hash(_posting(result)),
+        "source": source,
+        "commit": commit,
+    }
+    return {k: v for k, v in properties.items() if v is not None}
+
+
+def _capture(properties: dict) -> None:
+    client = Posthog(
+        PROJECT_KEY,
+        host=HOST,
+        timeout=REQUEST_TIMEOUT_SECONDS,
+        max_retries=MAX_RETRIES,
+        disable_geoip=True,
+    )
+    properties = {**properties, "$process_person_profile": False}
+    client.capture("run", distinct_id=str(uuid.uuid4()), properties=properties)
+    client.flush(timeout_seconds=FLUSH_TIMEOUT_SECONDS)
+
+
+def _notice(data: Path) -> str | None:
+    """The notice, the first time telemetry is on for this data directory."""
+    marker = data / NOTICE_FILE
+    if marker.exists():
+        return None
+    marker.touch()
+    return NOTICE.format(config=paths.config_file())
+
+
+def sent(command: str, result: Result, data: Path) -> Result:
+    """The result, its event sent at `basic` and `detailed`."""
+    with suppress(Exception):  # never in the way
+        if level() != "off":
+            result.notice = _notice(data)
+            _capture(event(command, result))
+    return result

{atsfill-0.0.5.dev141 → atsfill-0.0.5.dev143}/src/atsfill/registry.toml

@@ -7,6 +7,8 @@
 # hosting   hosted, embedded: where the form is found
 # links_to  an aggregator's: the sources its postings were followed to
 # adapter   the adapter's name, when there is one
+# hosts     a source without an adapter: the hosts its postings are on, subdomains included,
+#           so a run with no adapter still names its source
 # block     vendor, signal, step (posting | form | upload), date, version, camoufox, browser
 # scope     is (ADR 0016), `in_scope` when absent:
 #           supported     date, commit: a dev dry run passed the adapter gate, never demoted
@@ -58,6 +60,7 @@ kind = "board"
 share = 0.1006
 account = "to_read"
 hosting = ["hosted"]
+hosts = ["trudvsem.ru"]
 block = { vendor = "unknown", signal = "empty response to the browser, http 460 to curl, from outside Russia", step = "posting", date = 2026-10-20, version = "0.0.2", camoufox = "0.5.8", browser = "156.0.1-beta.36" }
 
 [oracle]
@@ -97,6 +100,7 @@ kind = "ats"
 share = 0.0244
 account = "none"
 hosting = ["hosted"]
+hosts = ["paycomonline.net"]
 block = { vendor = "hCaptcha", signal = "image challenge on Continue To Application, the step before the form, 3 of 3 employers headless, and again on a virtual display and headed", step = "form", date = 2026-10-20, version = "0.0.3", camoufox = "0.5.8", browser = "156.0.1-beta.36" }
 
 [icims]
@@ -104,6 +108,7 @@ kind = "ats"
 share = 0.0190
 account = "to_read"
 hosting = ["hosted"]
+hosts = ["icims.com"]
 block = { vendor = "hCaptcha", signal = "image challenge on the email step that starts sign-in and sign-up, before the form, 4 employers headless, Next disabled on 2 more", step = "form", date = 2026-10-26, version = "0.0.3", camoufox = "0.5.8", browser = "156.0.1-beta.36" }
 
 [manatal]
@@ -149,6 +154,7 @@ kind = "board"
 share = 0.0157
 account = "to_read"  # Log in to Apply goes to Singpass, Singapore's national digital identity; there is no email sign-up
 hosting = ["hosted"]
+hosts = ["mycareersfuture.gov.sg"]
 scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: national_id_login: applying needs a Singpass sign-in, whose account takes a Singapore NRIC or FIN number; no account can be made for the Test user (7 of 7 employers)" }
 
 [adzuna]
@@ -169,6 +175,7 @@ kind = "ats"
 share = 0.0125
 account = "to_read"
 hosting = ["hosted"]
+hosts = ["taleo.net"]
 scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_rendering: location_levels: a place's state and city list their options only once the level above is picked, so a fresh profile's are not listed (3 of 4 zones walked)" }
 
 [jazzhr]
@@ -190,9 +197,10 @@ scope = { is = "supported", date = 2026-10-20, commit = "d35da0b" }
 [adp]
 kind = "ats"
 share = 0.0108
-account = "to_read"  # Apply opens a talent community step, name, email and mobile number, verified with a one-time code before the form
+account = "to_read"  # Apply opens a talent community step, name, email and a required mobile number, verified with an OTP before the form
 hosting = ["hosted"]
-scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_up_otp: the talent community step before the form sends a one-time code to the email or mobile number, on every employer that showed it (14 of 15 employers)" }
+hosts = ["workforcenow.adp.com"]
+scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_up_phone: the talent community step before the form requires a mobile number, even when its OTP goes to the email (14 of 15 employers)" }
 
 [eures]
 kind = "aggregator"
@@ -228,14 +236,16 @@ kind = "ats"
 share = 0.0085
 account = "to_read"  # the sign-in's Create a new account sets a password, asking the name, country and zip code
 hosting = ["hosted"]
+hosts = ["workforceready.com", "yourpayrollhr.com", "saashr.com", "entertimeonline.com"]
 scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: profile_wizard: signed in, the form is the applicant portal's profile wizard, items of a dozen types edited in cards, entry lists, a security question and an electronic signature; not built within the round (1 tenant walked)" }
 
 [adpmyjobs]
 kind = "ats"
 share = 0.0084
-account = "to_read"  # the posting loads only signed in; the sign-in has no password, a one-time code each time
+account = "to_read"  # the posting loads only signed in; the sign-in has no password, an OTP alone each time
 hosting = ["hosted"]
-scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_in_otp: every sign-in, the sign-up's included, is a one-time code sent to the email or phone, and the posting loads only signed in (11 of 11 employers)" }
+hosts = ["myjobs.adp.com"]
+scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_in_otp_only: no password, every sign-in, the sign-up's included, is an OTP alone, and the posting loads only signed in (11 of 11 employers)" }
 
 [phenom]
 kind = "ats"
@@ -266,6 +276,7 @@ kind = "ats"
 share = 0.0059
 account = "to_read"
 hosting = ["hosted"]
+hosts = ["hrmdirect.com"]
 scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: screening_first: the form's first page comes before the sign-up step (4 of 14 orgs); a reCAPTCHA box on the sign-up step (1 of 17); 3 orgs signed in, under the 5 dry runs the gate needs" }
 
 [applicantpro]
@@ -273,6 +284,7 @@ kind = "ats"
 share = 0.0057
 account = "none"
 hosting = ["hosted"]
+hosts = ["applicantpro.com"]
 
 [rippling]
 kind = "ats"
@@ -293,9 +305,10 @@ scope = { is = "supported", date = 2026-10-26, commit = "867de7d" }
 [jobstreet]
 kind = "board"
 share = 0.0047
-account = "to_read"  # Apply needs a SEEK account; its sign-in and sign-up have no password, an emailed one-time code each time
+account = "to_read"  # Apply needs a SEEK account; its sign-in and sign-up have no password, an emailed OTP alone each time
 hosting = ["hosted"]
-scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_in_otp: Apply goes to the SEEK sign-in, whose every sign-in and sign-up is a six-digit code emailed to the address, with no password (14 of 15 employers)" }
+hosts = ["jobstreet.com", "jobsdb.com"]
+scope = { is = "in_scope", date = 2026-10-26, reason = "unsupported_flow: sign_in_otp_only: Apply goes to the SEEK sign-in, with no password, every sign-in and sign-up a six-digit OTP emailed to the address, alone (14 of 15 employers)" }
 
 [whatjobs-uk]
 kind = "aggregator"