atsfill 0.0.4.dev81__tar.gz → 0.0.4.dev84__tar.gz

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atsfill
-Version: 0.0.4.dev81
+Version: 0.0.4.dev84
 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
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business
 Classifier: Typing :: Typed
 Requires-Dist: camoufox==0.5.8
+Requires-Dist: keyring==25.7.0
 Requires-Dist: packaging==26.3
 Requires-Python: >=3.14
 Project-URL: Homepage, https://github.com/shbernal/atsfill
@@ -119,7 +120,7 @@ Every push to `main` that passes CI is also published as a dev release; `uvx --p
 4. Allow the system to submit in `~/.config/atsfill/config.toml`:
 
    ```toml
-   submit = ["greenhouse"]
+   submit-allowed = ["greenhouse"]
    ```
 
 5. Send. A `submitted` result carries the evidence of the send:
@@ -130,7 +131,11 @@ Every push to `main` that passes CI is also published as a dev release; `uvx --p
 
 A dry run is not invisible: some systems save answers or the resume as they are typed.
 `atsfill status` lists each system's side effects, whether it is allowed to submit, and how far atsfill has verified it: [the systems](docs/adapters/README.md).
-A `send` through an adapter no send was verified on goes ahead with a `warning`.
+A dry run or a `send` through an adapter no send was verified on carries a `warning`; the send goes ahead anyway.
+
+One home can apply for more than one person: `--user <name>` gives each their own sessions, double-send guard and `[users.<name>]` section in the config file ([ADR 0015](docs/adr/0015-users-and-accounts.md)).
+Given an account's email (`atsfill login <adapter> --email`) and a password source (a `[password-commands]` entry such as `rbw get example.com {email}`, or `--password -` on stdin), atsfill signs in by itself, and again whenever a form command finds the session signed out.
+Where a system's sign-up allows it, `atsfill login <adapter> --create --email <address>` creates the account with a password atsfill generates and keeps in the system's secret store, never printed; creating an account is a side effect, never part of `fill` or `send`.
 
 ## How it works
 

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/README.md

@@ -94,7 +94,7 @@ Every push to `main` that passes CI is also published as a dev release; `uvx --p
 4. Allow the system to submit in `~/.config/atsfill/config.toml`:
 
    ```toml
-   submit = ["greenhouse"]
+   submit-allowed = ["greenhouse"]
    ```
 
 5. Send. A `submitted` result carries the evidence of the send:
@@ -105,7 +105,11 @@ Every push to `main` that passes CI is also published as a dev release; `uvx --p
 
 A dry run is not invisible: some systems save answers or the resume as they are typed.
 `atsfill status` lists each system's side effects, whether it is allowed to submit, and how far atsfill has verified it: [the systems](docs/adapters/README.md).
-A `send` through an adapter no send was verified on goes ahead with a `warning`.
+A dry run or a `send` through an adapter no send was verified on carries a `warning`; the send goes ahead anyway.
+
+One home can apply for more than one person: `--user <name>` gives each their own sessions, double-send guard and `[users.<name>]` section in the config file ([ADR 0015](docs/adr/0015-users-and-accounts.md)).
+Given an account's email (`atsfill login <adapter> --email`) and a password source (a `[password-commands]` entry such as `rbw get example.com {email}`, or `--password -` on stdin), atsfill signs in by itself, and again whenever a form command finds the session signed out.
+Where a system's sign-up allows it, `atsfill login <adapter> --create --email <address>` creates the account with a password atsfill generates and keeps in the system's secret store, never printed; creating an account is a side effect, never part of `fill` or `send`.
 
 ## How it works
 

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.4.dev81"
+version = "0.0.4.dev84"
 description = "Read, dry-run and submit job application forms on hiring systems: Ashby, Greenhouse, Teamtailor, Welcome to the Jungle."
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,7 @@ classifiers = [
 ]
 dependencies = [
     "camoufox==0.5.8",
+    "keyring==25.7.0",
     "packaging==26.3",
 ]
 

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.4.dev81"
+version = "0.0.4.dev84"
 description = "Read, dry-run and submit job application forms on hiring systems: Ashby, Greenhouse, Teamtailor, Welcome to the Jungle."
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "camoufox==0.5.8",
+    "keyring==25.7.0",
     "packaging==26.3",
 ]
 

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/src/atsfill/adapters/paycor.py

@@ -259,7 +259,7 @@ class Paycor:
             named.nth(n).evaluate(_CHECK, option in labels)
 
     def _walk(self, page: Page, answers: dict[str, Answer] | None) -> None:
-        """Opens the apply page and answers the pages before the form: the persona's picks
+        """Opens the apply page and answers the pages before the form: the Test user's picks
         when filling, the last option and Yes when only reading, which list the fields."""
         if self._start is None:
             raise RuntimeError("no Paycor job in the page")

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/src/atsfill/adapters/wttj.py

@@ -57,7 +57,7 @@ _READ_BACK = """(form, ids) => Object.fromEntries(ids.map(id => {
 
 class WelcomeToTheJungle:
     name = "wttj"
-    login_url = f"https://{HOST}/en/signin"
+    per_employer = False
     known_gaps: dict[str, Gap] = {}
     side_effects = [SideEffect("submit", "employer", "the application reaches the employer")]
 
@@ -75,7 +75,13 @@ class WelcomeToTheJungle:
         match = JOB.match(urlsplit(url).path)
         return f"https://{HOST}/companies/{match[1]}/jobs/{match[2]}" if match else url
 
-    def signed_in(self, request: Request) -> bool:
+    def account_scope(self, url: str) -> None:
+        return None
+
+    def login_url(self, scope: str | None) -> str:
+        return f"https://{HOST}/en/signin"
+
+    def signed_in(self, request: Request, scope: str | None) -> bool:
         """`users/me` answers 200 for an account, 204 for a visitor."""
         return request.get(ME).status == 200
 

atsfill-0.0.4.dev84/src/atsfill/cli.py

@@ -0,0 +1,223 @@
+import argparse
+import dataclasses
+import json
+import sys
+from pathlib import Path
+
+from atsfill import core
+from atsfill.adapters import adapters
+from atsfill.core import browser, paths
+from atsfill.core.adapter import NeedsAccount
+from atsfill.core.results import Result, SessionReport, Status, StatusReport
+
+OK = {Status.READY, Status.SUBMITTED}
+
+
+def session(value: str) -> tuple[str, Path]:
+    adapter, sep, path = value.partition("=")
+    if not (sep and adapter and path):
+        raise argparse.ArgumentTypeError(f"expected <adapter>=<path>, got {value!r}")
+    return adapter, Path(path)
+
+
+def user(value: str) -> str:
+    if not paths.USER_NAME.fullmatch(value):
+        raise argparse.ArgumentTypeError(f"lowercase letters, digits and -, got {value!r}")
+    return value
+
+
+def with_user(command: argparse.ArgumentParser) -> argparse.ArgumentParser:
+    command.add_argument(
+        "--user",
+        type=user,
+        default=paths.DEFAULT_USER,
+        help="the user applications are sent for (default: %(default)s)",
+    )
+    return command
+
+
+HELP = {
+    "read": "list a posting's form fields",
+    "fill": "dry run: fill the form and read it back, never submit",
+    "send": "fill, read back, and submit when every answer matches",
+}
+EPILOG = """\
+A dry run is visible to the hiring system: some save each answer or the resume as it is
+typed (`status` lists each adapter's side effects). A `send` that ends `submitted` is a real
+application, final. Each command prints one JSON result on one line, without the keys that
+are null, false or empty, and after `fill` and `send` only the checks that failed; `-v`
+prints all of it. Exit 0 for ready and submitted, 1 for any other status, 2 for a usage
+error."""
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="atsfill",
+        description="Read, dry-run and submit job application forms on hiring systems.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--data-dir", type=Path, help="default: $ATSFILL_DATA_DIR, then the state dir")
+    sub = p.add_subparsers(dest="command", required=True)
+    for name in ("read", "fill", "send"):
+        c = with_user(
+            sub.add_parser(name, help=HELP[name], epilog=EPILOG, formatter_class=p.formatter_class)
+        )
+        c.add_argument("url")
+        c.add_argument(
+            "--session",
+            type=session,
+            action="append",
+            default=[],
+            metavar="ADAPTER=PATH",
+            help="storage state for an adapter that needs an account",
+        )
+        if name != "read":
+            c.add_argument(
+                "--answers",
+                type=answers_file,
+                required=True,
+                help="JSON {field_id: value} file, - for stdin",
+            )
+    sub.choices["send"].add_argument(
+        "--resend", action="store_true", help="send even though an earlier send may have gone"
+    )
+    sub.add_parser("status", help="version, paths, browser, and each adapter's state")
+    sub.add_parser("install-browser", help="download the Camoufox build atsfill is pinned to")
+    accounts = [a.name for a in adapters() if isinstance(a, NeedsAccount)]
+    for name, text in (
+        ("login", "sign in to a system that needs an account"),
+        ("logout", "delete a stored session"),
+    ):
+        c = with_user(sub.add_parser(name, help=text))
+        c.add_argument("adapter", choices=accounts)
+        c.add_argument("--url", help="a posting, for a system with an account per employer")
+    login = sub.choices["login"]
+    login.add_argument("--email", help="the account's email, remembered for it")
+    login.add_argument(
+        "--password", choices=["-"], help="read the password from stdin, for this sign-in only"
+    )
+    login.add_argument(
+        "--window", action="store_true", help="sign in in a visible window, by a person"
+    )
+    login.add_argument(
+        "--create",
+        action="store_true",
+        help="create the account with --email and a password atsfill generates and stores",
+    )
+    for name in ("read", "fill", "send", "status", "login", "logout"):
+        sub.choices[name].add_argument(
+            "-v", "--verbose", action="store_true", help="the whole result, every key, indented"
+        )
+    return p
+
+
+def answers_file(path: str) -> dict:
+    try:
+        answers = json.load(sys.stdin) if path == "-" else json.loads(Path(path).read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        raise argparse.ArgumentTypeError(str(e)) from e
+    if not isinstance(answers, dict):
+        raise argparse.ArgumentTypeError("expected a JSON object {field_id: value}")
+    return answers
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        paths.config(getattr(args, "user", paths.DEFAULT_USER))
+    except paths.ConfigError as e:
+        print(f"atsfill: {e}", file=sys.stderr)
+        return 2
+    match args.command:
+        case "read":
+            result = core.read(
+                args.url, user=args.user, data_dir=args.data_dir, sessions=dict(args.session)
+            )
+        case "fill":
+            result = core.fill(
+                args.url,
+                args.answers,
+                user=args.user,
+                data_dir=args.data_dir,
+                sessions=dict(args.session),
+            )
+        case "send":
+            result = core.send(
+                args.url,
+                args.answers,
+                resend=args.resend,
+                user=args.user,
+                data_dir=args.data_dir,
+                sessions=dict(args.session),
+            )
+        case "status":
+            report = core.status(data_dir=args.data_dir)
+            emit(report, args.verbose)
+            signed_out = any(s.session == "signed_out" for s in report.sessions)
+            return 1 if signed_out or report.browser != report.browser_pinned else 0
+        case "install-browser":
+            return browser.install()
+        case "login" | "logout":
+            where = {"user": args.user, "url": args.url, "data_dir": args.data_dir}
+            try:
+                if args.command == "logout":
+                    session = core.logout(args.adapter, **where)
+                else:
+                    password = sys.stdin.readline().rstrip("\n") if args.password else None
+                    session = core.login(
+                        args.adapter,
+                        email=args.email,
+                        password=password,
+                        window=args.window,
+                        create=args.create,
+                        **where,
+                    )
+            except ValueError as e:
+                print(f"atsfill: {e}", file=sys.stderr)
+                return 2
+            emit(session, args.verbose)
+            return 0 if args.command == "logout" or session.session == "signed_in" else 1
+    emit(result, args.verbose, args.command)
+    return 0 if result.status in OK else 1
+
+
+def emit(
+    value: Result | StatusReport | SessionReport, verbose: bool, command: str | None = None
+) -> None:
+    """Prints the whole value with `verbose`; else what its consumer acts on, on one line."""
+    data = dataclasses.asdict(value)
+    if verbose:
+        json.dump(data, sys.stdout, default=str, ensure_ascii=False, indent=2)
+    else:
+        if isinstance(value, Result):
+            data = _slim(data, command)
+        json.dump(_sparse(data), sys.stdout, default=str, ensure_ascii=False, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+
+def _slim(result: dict, command: str | None) -> dict:
+    """A form command's result without what the consumer already has: the URL it passed and,
+    after `read`, the fields, the side effects and each answer it gave."""
+    del result["url"]
+    if command != "read":
+        del result["fields"], result["side_effects"]
+        result["checks"] = [
+            {"field_id": c["field_id"], "read_back": c["read_back"]}
+            for c in result["checks"]
+            if not c["match"]
+        ]
+    return result
+
+
+def _sparse(value: object) -> object:
+    """Drops the keys whose value is null, false or empty, at every depth."""
+    if isinstance(value, dict):
+        kept = {k: _sparse(v) for k, v in value.items()}
+        return {k: v for k, v in kept.items() if v not in (None, False, [], {})}
+    if isinstance(value, list):
+        return [_sparse(v) for v in value]
+    return value
+
+
+def main() -> None:
+    sys.exit(run(parser().parse_args()))

atsfill-0.0.4.dev84/src/atsfill/core/accounts.py

@@ -0,0 +1,111 @@
+"""Stored sessions for the systems that need an account (ADRs 0007, 0015)."""
+
+import json
+import re
+import time
+from pathlib import Path
+
+from atsfill.core import browser
+from atsfill.core.adapter import CreatesAccount, NeedsAccount, SignsIn, Unsupported
+from atsfill.core.browser import Page
+from atsfill.core.passwords import account_key
+
+LOGIN_TIMEOUT_S = 600
+POLL_MS = 1000
+SCOPE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")  # one path segment
+EMAILS = "accounts.json"  # in the user's directory, each account's email
+
+
+def session_file(user_dir: Path, adapter: str, scope: str | None) -> Path:
+    """`sessions/<adapter>.json`, or `sessions/<adapter>/<scope>.json` for a scoped account."""
+    if scope is None:
+        return user_dir / "sessions" / f"{adapter}.json"
+    if not SCOPE.fullmatch(scope):
+        raise ValueError(f"{scope!r} is not an account scope")
+    return user_dir / "sessions" / adapter / f"{scope}.json"
+
+
+def stored(user_dir: Path, adapter: str) -> list[tuple[str | None, Path]]:
+    """Every session the user stored for the adapter, with its scope."""
+    sessions = user_dir / "sessions"
+    whole = (
+        [(None, sessions / f"{adapter}.json")] if (sessions / f"{adapter}.json").exists() else []
+    )
+    return whole + [(p.stem, p) for p in sorted((sessions / adapter).glob("*.json"))]
+
+
+def email(user_dir: Path, adapter: str, scope: str | None) -> str | None:
+    path = user_dir / EMAILS
+    emails = json.loads(path.read_text()) if path.exists() else {}
+    return emails.get(account_key(adapter, scope))
+
+
+def remember(user_dir: Path, adapter: str, scope: str | None, address: str) -> None:
+    path = user_dir / EMAILS
+    emails = json.loads(path.read_text()) if path.exists() else {}
+    path.write_text(json.dumps(emails | {account_key(adapter, scope): address}, indent=2))
+
+
+def sign_in(
+    page: Page,
+    adapter: SignsIn,
+    scope: str | None,
+    address: str,
+    password: str,
+    session: Path,
+    create: bool = False,
+) -> None:
+    """Signs in, or creates the account, from the system's login page and stores the session.
+    Raises what the adapter raises, without the password in it."""
+    page.goto(adapter.login_url(scope))
+    try:
+        if create:
+            assert isinstance(adapter, CreatesAccount)
+            adapter.sign_up(page, address, password)
+        else:
+            adapter.sign_in(page, address, password)
+    except Exception as e:
+        if password in str(e):
+            raise redacted(e, password) from None
+        raise
+    if not adapter.signed_in(page.request, scope):
+        raise Unsupported("unhandled_rendering: still signed out after signing in")
+    browser.save_session(page, session)
+
+
+def redacted(error: Exception, password: str) -> Exception:
+    message = str(error).replace(password, "<password>")
+    try:
+        return type(error)(message)
+    except TypeError:
+        return RuntimeError(f"{type(error).__name__}: {message}")
+
+
+def state(adapter: NeedsAccount, session: Path, scope: str | None) -> str:
+    """`signed_in` or `signed_out` from the system itself, `missing` with no session stored."""
+    if not session.exists():
+        return "missing"
+    with browser.session_request(session) as request:
+        return "signed_in" if adapter.signed_in(request, scope) else "signed_out"
+
+
+def wait_for_person(
+    adapter: NeedsAccount, scope: str | None, data_dir: Path, session: Path
+) -> str | None:
+    """Waits for a person to sign in in the login window, then stores the session.
+
+    Returns the reason it did not: `window_closed` or `login_timeout`; None once stored.
+    """
+    with browser.login_window(data_dir, adapter.login_url(scope)) as page:
+        deadline = time.monotonic() + LOGIN_TIMEOUT_S
+        try:
+            while time.monotonic() < deadline:
+                if adapter.signed_in(page.request, scope):
+                    browser.save_session(page, session)
+                    return None
+                page.wait_for_timeout(POLL_MS)
+        except browser.BrowserError:
+            if page.is_closed():
+                return "window_closed"
+            raise
+    return "login_timeout"

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/src/atsfill/core/adapter.py

@@ -38,6 +38,14 @@ def out_of_scope(field_id: str, what: str) -> str:
     return f"out_of_scope: {field_id} is {what}"
 
 
+class Refused(Exception):
+    """The system turned down a sign-in or a sign-up for a reason it states:
+    `email_in_use`, `email_domain_rejected`, `password_rule`, `wrong_password`.
+
+    The message is the result's reason, `code` or `code: detail`.
+    """
+
+
 class NotTaken(Exception):
     """The page would not take an answer the user gave: no suggestion or option holds it.
 
@@ -78,15 +86,46 @@ class Adapter(Protocol):
 
 @runtime_checkable
 class NeedsAccount(Protocol):
-    """An adapter whose system needs a signed-in session (ADR 0007)."""
+    """An adapter whose system needs a signed-in session, one per user and account scope
+    (ADR 0015)."""
 
-    login_url: str
+    name: str
+    per_employer: bool  # each employer keeps its own accounts, so a scope is always given
+
+    def account_scope(self, url: str) -> str | None:
+        """The account scope of a posting's URL: None where an account covers the whole system,
+        the employer where each keeps its own, the same for every URL of that employer."""
+        ...
 
-    def signed_in(self, request: Request) -> bool:
+    def login_url(self, scope: str | None) -> str: ...
+
+    def signed_in(self, request: Request, scope: str | None) -> bool:
         """Whether the cookies `request` carries are signed in, from one request to the system."""
         ...
 
 
+@runtime_checkable
+class SignsIn(NeedsAccount, Protocol):
+    """An adapter atsfill can sign in through with an email and a password (ADR 0015)."""
+
+    def sign_in(self, page: Page, email: str, password: str) -> None:
+        """Signs in on the page `login_url` loaded. Raises `Blocked` for what the system waits
+        for (`email_link`, `email_otp`, `sms_otp`, `captcha`), `Refused` for what it turns down,
+        `Unsupported` for a page it does not know."""
+        ...
+
+
+@runtime_checkable
+class CreatesAccount(SignsIn, Protocol):
+    """An adapter atsfill can create an account through, where the system's sign-up allows it.
+    Account creation is a side effect it declares (ADR 0008)."""
+
+    def sign_up(self, page: Page, email: str, password: str) -> None:
+        """Creates the account from the page `login_url` loaded, signed in once it returns.
+        Raises as `sign_in` does; `Refused` names the rule a `password_rule` page showed."""
+        ...
+
+
 @runtime_checkable
 class ReadsOverHttp(Adapter, Protocol):
     """An adapter that can list a form's fields over HTTP, without a browser (ADR 0011)."""

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/src/atsfill/core/attempts.py

@@ -1,4 +1,4 @@
-"""The double-send guard: `attempts.jsonl` in the data directory (ADR 0006)."""
+"""The double-send guard: `attempts.jsonl` in the user's directory (ADRs 0006, 0015)."""
 
 import json
 from datetime import UTC, datetime
@@ -9,8 +9,8 @@ from atsfill.core.results import Status
 PENDING = "clicked"  # appended before the click; a later line records the outcome
 
 
-def last(data_dir: Path, posting: str) -> str | None:
-    path = data_dir / "attempts.jsonl"
+def last(user_dir: Path, posting: str) -> str | None:
+    path = user_dir / "attempts.jsonl"
     if not path.exists():
         return None
     outcomes = [
@@ -21,12 +21,12 @@ def last(data_dir: Path, posting: str) -> str | None:
     return outcomes[-1] if outcomes else None
 
 
-def blocks_send(data_dir: Path, posting: str) -> bool:
+def blocks_send(user_dir: Path, posting: str) -> bool:
     """A last attempt that was clicked without an outcome counts as `unknown`."""
-    return last(data_dir, posting) in (Status.SUBMITTED, Status.UNKNOWN, PENDING)
+    return last(user_dir, posting) in (Status.SUBMITTED, Status.UNKNOWN, PENDING)
 
 
-def record(data_dir: Path, posting: str, status: str, **extra: str | None) -> None:
+def record(user_dir: Path, posting: str, status: str, **extra: str | None) -> None:
     line = {"at": datetime.now(UTC).isoformat(), "posting": posting, "status": status, **extra}
-    with (data_dir / "attempts.jsonl").open("a") as f:
+    with (user_dir / "attempts.jsonl").open("a") as f:
         f.write(json.dumps(line, ensure_ascii=False) + "\n")

{atsfill-0.0.4.dev81 → atsfill-0.0.4.dev84}/src/atsfill/core/browser.py

@@ -179,7 +179,7 @@ def login_window(data_dir: Path, url: str, headless: bool = False) -> Generator[
 
 
 def save_session(page: Page, path: Path) -> None:
-    path.parent.mkdir(mode=0o700, exist_ok=True)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
     path.touch(mode=0o600)
     page.context.storage_state(path=path)