atsfill 0.0.4.dev80__tar.gz → 0.0.4.dev83__tar.gz

{atsfill-0.0.4.dev80 → atsfill-0.0.4.dev83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atsfill
-Version: 0.0.4.dev80
+Version: 0.0.4.dev83
 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:
@@ -132,6 +133,10 @@ A dry run is not invisible: some systems save answers or the resume as they are
 `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`.
 
+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
 
 ```mermaid

{atsfill-0.0.4.dev80 → atsfill-0.0.4.dev83}/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:
@@ -107,6 +107,10 @@ A dry run is not invisible: some systems save answers or the resume as they are
 `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`.
 
+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
 
 ```mermaid

{atsfill-0.0.4.dev80 → atsfill-0.0.4.dev83}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.4.dev80"
+version = "0.0.4.dev83"
 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.dev80 → atsfill-0.0.4.dev83}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "atsfill"
-version = "0.0.4.dev80"
+version = "0.0.4.dev83"
 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.dev80 → atsfill-0.0.4.dev83}/src/atsfill/adapters/oracle.py

@@ -2,7 +2,7 @@
 as docs/adapters/oracle.md observes.
 
 The form opens only past an email step, and an email the employer's Oracle already knows gets an
-emailed code instead. Reading passes the step with a throwaway address; filling starts over with
+emailed OTP instead. Reading passes the step with a throwaway address; filling starts over with
 the answer's. Oracle keeps a draft of the application from then on, autosaved as fields change.
 """
 
@@ -31,7 +31,7 @@ SUBMIT = ".apply-flow-pagination__submit-button"
 PAGINATION = ".apply-flow-pagination__button"
 PAGE_NUMBERS = ".apply-flow-navigation-pages__link:visible"
 LOADING = ".app-loading-spinner, .cx-select--loading, .apply-flow-block .skeleton"
-CODE_PAGE = ".apply-flow-pin-code-required"
+OTP_PAGE = ".apply-flow-pin-code-required"
 CAPTCHA = "iframe[src*='hcaptcha.com']"
 MANUALLY = ".quick-apply-flow__manually--link:visible"  # past an offer to import a profile
 COOKIES = ".cookie-consent button:visible"
@@ -356,7 +356,7 @@ class Oracle:
             if "--checked" not in (box.get_attribute("class") or ""):
                 _click(page, box)
         _click(page, page.locator(NEXT).first)
-        opened = page.locator(f"apply-flow-block, {CODE_PAGE}, {MANUALLY}")
+        opened = page.locator(f"apply-flow-block, {OTP_PAGE}, {MANUALLY}")
         try:
             opened.first.wait_for(timeout=STEP_TIMEOUT_MS)
             if page.locator(MANUALLY).count():
@@ -366,10 +366,10 @@ class Oracle:
             if page.locator(CAPTCHA).count():
                 raise Blocked("captcha: the email step asks for an hCaptcha") from None
             raise RuntimeError("the email step did not open the form") from None
-        if page.locator(CODE_PAGE).count():
+        if page.locator(OTP_PAGE).count():
             raise Blocked(
-                f"email_code: {email} is known to this employer's Oracle, which emails it a"
-                " code before it shows the form"
+                f"email_otp: {email} is known to this employer's Oracle, which emails it an"
+                " OTP before it shows the form"
             )
         page.locator(f"{PAGINATION}:visible").first.wait_for(timeout=STEP_TIMEOUT_MS)
         _settle(page)

{atsfill-0.0.4.dev80 → atsfill-0.0.4.dev83}/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.dev80 → atsfill-0.0.4.dev83}/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.dev80 → atsfill-0.0.4.dev83}/src/atsfill/cli.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 from atsfill import core
 from atsfill.adapters import adapters
-from atsfill.core import browser
+from atsfill.core import browser, paths
 from atsfill.core.adapter import NeedsAccount
 from atsfill.core.results import Result, SessionReport, Status, StatusReport
 
@@ -20,6 +20,22 @@ def session(value: str) -> tuple[str, Path]:
     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",
@@ -42,7 +58,9 @@ def parser() -> argparse.ArgumentParser:
     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 = sub.add_parser(name, help=HELP[name], epilog=EPILOG, formatter_class=p.formatter_class)
+        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",
@@ -65,11 +83,25 @@ def parser() -> argparse.ArgumentParser:
     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)]
-    sub.add_parser(
-        "login", help="sign in, in a visible window, to a system that needs an account"
-    ).add_argument("adapter", choices=accounts)
-    sub.add_parser("logout", help="delete a stored session").add_argument(
-        "adapter", choices=accounts
+    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",
     )
     return p
 
@@ -85,35 +117,60 @@ def answers_file(path: str) -> dict:
 
 
 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, data_dir=args.data_dir, sessions=dict(args.session))
+            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, data_dir=args.data_dir, sessions=dict(args.session)
+                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)
-            signed_out = any(a.session == "signed_out" for a in report.adapters)
+            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":
-            session = core.login(args.adapter, data_dir=args.data_dir)
+        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)
-            return 0 if session.session == "signed_in" else 1
-        case "logout":
-            emit(core.logout(args.adapter, data_dir=args.data_dir))
-            return 0
+            return 0 if args.command == "logout" or session.session == "signed_in" else 1
     emit(result)
     return 0 if result.status in OK else 1
 

atsfill-0.0.4.dev83/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.dev80 → atsfill-0.0.4.dev83}/src/atsfill/core/adapter.py

@@ -6,8 +6,8 @@ from atsfill.core.results import Answer, Field, SideEffect
 
 
 class Blocked(Exception):
-    """The system stopped the command: a captcha, a low reCAPTCHA score, an emailed code, a
-    login wall.
+    """The system stopped the command: a captcha, a low reCAPTCHA score, an OTP, a login
+    wall.
 
     The message is the result's reason, `code` or `code: detail`.
     """
@@ -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.dev80 → atsfill-0.0.4.dev83}/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.dev80 → atsfill-0.0.4.dev83}/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)