worklittle 1.1.0__tar.gz

worklittle-1.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+*.pyc

worklittle-1.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: worklittle
+Version: 1.1.0
+Summary: Official Worklittle Python SDK and CLI for api.worklittle.com
+Project-URL: Homepage, https://docs.worklittle.com/libraries/sdk?lang=python
+Project-URL: Documentation, https://docs.worklittle.com/libraries/overview
+Author: Worklittle
+License-Expression: MIT
+Keywords: api,ats,cli,jobs,sdk,worklittle
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# worklittle
+
+Python SDK and CLI for [api.worklittle.com](https://api.worklittle.com).
+
+Registry publish is not live yet. Install from this package:
+
+```bash
+cd packages/sdk-python
+pip install -e .
+export WORKLITTLE_API_KEY=sk-wl-api01-...
+worklittle jobs search --q="software engineer" --limit 1 --pretty
+worklittle jobs search --title="software engineer, -senior" --company="-lucid-motors,-tesla" --limit 5 --pretty
+```
+
+`--company` accepts bare slugs (include) or leading-dash slugs (exclude). Title negatives use `--title` / `--q`. Other `GET /jobs` flags pass through the same way (`--workplace_type`, `--posted_within_days`, …).
+
+```python
+from worklittle import Worklittle
+
+wl = Worklittle()
+jobs = wl.jobs.search(q="software engineer", limit=5)
+filtered = wl.jobs.search(
+    title="software engineer, -senior",
+    company="-lucid-motors,-tesla",
+    limit=5,
+)
+```
+
+CLI output is JSON on stdout by default.
+
+Docs: https://docs.worklittle.com/libraries/sdk?lang=python  
+OpenAPI: https://docs.worklittle.com/openapi/openapi.yaml

worklittle-1.1.0/README.md

@@ -0,0 +1,32 @@
+# worklittle
+
+Python SDK and CLI for [api.worklittle.com](https://api.worklittle.com).
+
+Registry publish is not live yet. Install from this package:
+
+```bash
+cd packages/sdk-python
+pip install -e .
+export WORKLITTLE_API_KEY=sk-wl-api01-...
+worklittle jobs search --q="software engineer" --limit 1 --pretty
+worklittle jobs search --title="software engineer, -senior" --company="-lucid-motors,-tesla" --limit 5 --pretty
+```
+
+`--company` accepts bare slugs (include) or leading-dash slugs (exclude). Title negatives use `--title` / `--q`. Other `GET /jobs` flags pass through the same way (`--workplace_type`, `--posted_within_days`, …).
+
+```python
+from worklittle import Worklittle
+
+wl = Worklittle()
+jobs = wl.jobs.search(q="software engineer", limit=5)
+filtered = wl.jobs.search(
+    title="software engineer, -senior",
+    company="-lucid-motors,-tesla",
+    limit=5,
+)
+```
+
+CLI output is JSON on stdout by default.
+
+Docs: https://docs.worklittle.com/libraries/sdk?lang=python  
+OpenAPI: https://docs.worklittle.com/openapi/openapi.yaml

worklittle-1.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worklittle"
+version = "1.1.0"
+description = "Official Worklittle Python SDK and CLI for api.worklittle.com"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Worklittle" }]
+keywords = ["worklittle", "jobs", "ats", "api", "sdk", "cli"]
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+worklittle = "worklittle.cli:main"
+
+[project.urls]
+Homepage = "https://docs.worklittle.com/libraries/sdk?lang=python"
+Documentation = "https://docs.worklittle.com/libraries/overview"
+
+[tool.hatch.build.targets.wheel]
+packages = ["worklittle"]
+
+[tool.hatch.build.targets.sdist]
+include = ["worklittle", "README.md", "pyproject.toml", "tests"]

worklittle-1.1.0/tests/test_webhooks.py

@@ -0,0 +1,17 @@
+import hashlib
+import hmac
+import time
+
+from worklittle.webhooks import verify_webhook_signature
+
+
+def test_verify_webhook_signature():
+    secret = "whsec_test"
+    timestamp = str(int(time.time()))
+    raw = '{"ok":true}'
+    sig = "v1=" + hmac.new(
+        secret.encode(), f"{timestamp}.{raw}".encode(), hashlib.sha256
+    ).hexdigest()
+    assert verify_webhook_signature(
+        signature_header=sig, timestamp=timestamp, raw_body=raw, secret=secret
+    )

worklittle-1.1.0/worklittle/__init__.py

@@ -0,0 +1,13 @@
+from .client import Worklittle, create_worklittle
+from .errors import PaymentRequiredError, QuotaExceededError, WorklittleError
+from .webhooks import verify_webhook_signature
+
+__all__ = [
+    "Worklittle",
+    "create_worklittle",
+    "WorklittleError",
+    "PaymentRequiredError",
+    "QuotaExceededError",
+    "verify_webhook_signature",
+]
+__version__ = "1.1.0"

worklittle-1.1.0/worklittle/cli.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+from .client import Worklittle
+from .errors import WorklittleError
+
+# Reserved CLI flags — not forwarded as API query params.
+_RESERVED = frozenset(
+    {
+        "api-key",
+        "base-url",
+        "pretty",
+        "json",
+        "body",
+        "id",
+        "name",
+        "field",
+        "h",
+        "help",
+    }
+)
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = argparse.ArgumentParser(
+        prog="worklittle",
+        description="Worklittle CLI. JSON on stdout by default.",
+        add_help=False,
+    )
+    parser.add_argument("group", nargs="?", default="help")
+    parser.add_argument("action", nargs="?", default="")
+    parser.add_argument("rest", nargs="*")
+    parser.add_argument("--api-key", default=os.environ.get("WORKLITTLE_API_KEY"))
+    parser.add_argument("--base-url", default="https://api.worklittle.com")
+    parser.add_argument("--pretty", action="store_true")
+    parser.add_argument("--body", default="{}")
+    parser.add_argument("--id")
+    parser.add_argument("--name")
+    parser.add_argument("--field")
+    # Declared for help / common flags; also merged into query params below.
+    parser.add_argument("--q")
+    parser.add_argument("--title")
+    parser.add_argument("--company")
+    parser.add_argument("--limit", type=int)
+    parser.add_argument("--cursor")
+    parser.add_argument("--include")
+    args, unknown = parser.parse_known_args(argv)
+
+    if args.group in ("help", "", None) or args.group in ("-h", "--help"):
+        _out(
+            {
+                "name": "worklittle",
+                "version": "1.1.0",
+                "usage": "worklittle <group> <action> [flags]",
+                "groups": [
+                    "jobs",
+                    "companies",
+                    "stats",
+                    "boards",
+                    "apply",
+                    "apply-with-ai",
+                    "applied",
+                    "candidates",
+                    "employees",
+                    "email",
+                    "documents",
+                    "attendance",
+                    "surveys",
+                    "webhooks",
+                    "listings",
+                    "resumes",
+                    "usage",
+                    "billing",
+                    "limits",
+                    "agent",
+                ],
+                "note": (
+                    "JSON stdout by default. Query flags match GET /jobs param names "
+                    "(e.g. --company=-lucid-motors, --title='engineer, -senior'). "
+                    "JS CLI (Homebrew) is canonical; Python CLI is a subset."
+                ),
+            },
+            pretty=True,
+        )
+        return
+
+    client = Worklittle(api_key=args.api_key, base_url=args.base_url)
+    params = _query_params(args, unknown)
+    body = json.loads(args.body)
+    company = args.company or (args.rest[0] if args.rest else None)
+    id_ = args.id or (args.rest[0] if args.rest else None)
+
+    try:
+        result = _dispatch(
+            client, args.group, args.action or "", args.rest, params, body, company, id_, args
+        )
+    except WorklittleError as err:
+        print(
+            json.dumps({"error": {"code": err.code, "message": str(err), "status": err.status}}),
+            file=sys.stderr,
+        )
+        raise SystemExit(2 if err.status in (401, 403) else 1) from err
+    except Exception as err:  # noqa: BLE001
+        print(json.dumps({"error": {"code": "CLI_ERROR", "message": str(err)}}), file=sys.stderr)
+        raise SystemExit(1) from err
+
+    _out(result, pretty=args.pretty)
+
+
+def _query_params(args: argparse.Namespace, unknown: list[str]) -> dict[str, Any]:
+    """Forward declared + unknown --flags as API query params (JS CLI parity)."""
+    params: dict[str, Any] = {}
+    for key in ("q", "title", "company", "limit", "cursor", "include"):
+        val = getattr(args, key, None)
+        if val is not None and val != "":
+            params[key] = val
+    params.update(_parse_unknown_flags(unknown))
+    return params
+
+
+def _parse_unknown_flags(unknown: list[str]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    i = 0
+    while i < len(unknown):
+        token = unknown[i]
+        if token in ("-h", "--help"):
+            i += 1
+            continue
+        if not token.startswith("--"):
+            i += 1
+            continue
+        raw = token[2:]
+        if "=" in raw:
+            key, value = raw.split("=", 1)
+            if key and key not in _RESERVED and value != "":
+                out[key] = _coerce(value)
+            i += 1
+            continue
+        key = raw
+        nxt = unknown[i + 1] if i + 1 < len(unknown) else None
+        if key in _RESERVED:
+            i += 1
+            continue
+        if nxt is None or nxt.startswith("--"):
+            out[key] = True
+            i += 1
+        else:
+            if nxt != "":
+                out[key] = _coerce(nxt)
+            i += 2
+    return out
+
+
+def _coerce(value: str) -> Any:
+    if value.isdigit() or (value.startswith("-") and value[1:].isdigit()):
+        try:
+            return int(value)
+        except ValueError:
+            return value
+    try:
+        if "." in value:
+            return float(value)
+    except ValueError:
+        pass
+    low = value.lower()
+    if low == "true":
+        return True
+    if low == "false":
+        return False
+    return value
+
+
+def _out(data: object, *, pretty: bool) -> None:
+    print(json.dumps(data, indent=2 if pretty else None, default=str))
+
+
+def _dispatch(client, group, action, rest, params, body, company, id_, args):
+    key = f"{group} {action}".strip()
+    # Public jobs index
+    if key == "jobs search":
+        return client.jobs.search(**params)
+    if key == "jobs get":
+        return client.jobs.get(id_ or rest[0])
+    if key == "jobs map":
+        return client.jobs.map(**params)
+    if key == "jobs salary-average":
+        return client.jobs.salary_average(**params)
+    if key == "companies search":
+        return client.companies.search(**params)
+    if key == "stats get":
+        return client.stats.get(**params)
+    # Public boards + apply
+    if key in ("boards get", "boards list"):
+        return client.boards.get(company or rest[0], **params)
+    if key == "boards jobs":
+        return client.boards.list_jobs(company or rest[0], **params)
+    if key == "boards job":
+        return client.boards.get_job(company or rest[0], id_ or rest[1], **params)
+    if key == "boards facets":
+        return client.boards.facets(company or rest[0], **params)
+    if key == "boards apply":
+        return client.boards.apply(company or rest[0], id_ or rest[1], body)
+    if key == "apply submit":
+        return client.apply.submit(id_ or rest[0], body)
+    if key == "apply-with-ai start":
+        return client.apply.start_with_ai(body)
+    if key in ("apply-with-ai status", "apply-with-ai get"):
+        return client.apply.get_with_ai_session(id_ or rest[0])
+    if key == "apply-with-ai continue":
+        answers = body.get("answers") if isinstance(body.get("answers"), dict) else body
+        return client.apply.continue_with_ai(
+            id_ or rest[0],
+            answers if isinstance(answers, dict) else {},
+        )
+    if key == "apply-with-ai approve":
+        return client.apply.approve_with_ai_submit(id_ or rest[0])
+    if key == "apply-with-ai stop":
+        return client.apply.stop_with_ai(id_ or rest[0])
+    if key in ("applied list", "applied-jobs list"):
+        return client.candidates.list(**params)
+    if key == "candidates get":
+        return client.candidates.get(id_ or rest[0])
+    if key == "employees list":
+        return client.employees.list(**params)
+    if key == "employees get":
+        return client.employees.get(id_ or rest[0])
+    if key == "email list":
+        return client.email.list_messages(**params)
+    if key == "email send":
+        return client.email.send(body)
+    if key == "email sends":
+        return client.email.list_sends(**params)
+    if key == "email send-get":
+        return client.email.get_send(id_ or rest[0])
+    if key == "email send-events":
+        return client.email.list_send_events(id_ or rest[0])
+    if key == "usage list":
+        return client.usage.list(**params)
+    if key == "billing balance":
+        return client.billing.balance()
+    if key == "billing invoices":
+        return client.billing.invoices(**params)
+    if key == "limits get":
+        return client.limits.get()
+    if key == "limits budget":
+        return client.limits.get_budget()
+    if key == "documents list":
+        return client.documents.list(**params)
+    if key == "attendance list":
+        return client.attendance.list(**params)
+    if key == "surveys list":
+        return client.surveys.list(**params)
+    if key == "surveys get":
+        return client.surveys.get(id_ or rest[0])
+    if key == "webhooks list":
+        return client.webhooks.list()
+    if key == "listings list":
+        return client.job_listings.list(**params)
+    if key == "resumes create":
+        return client.resumes.create(body)
+    if key == "agent tools":
+        return client.agent.list_tools()
+    if key == "agent tool":
+        return client.agent.run_tool(args.name or rest[0], body)
+    raise ValueError(f"Unknown command: {key}. Run: worklittle help")
+
+
+if __name__ == "__main__":
+    main()

worklittle-1.1.0/worklittle/client.py

@@ -0,0 +1,462 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from .errors import PaymentRequiredError, QuotaExceededError, WorklittleError
+from .webhooks import verify_webhook_signature
+
+
+class _Http:
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int = 3,
+        timeout: float = 60.0,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        auth: bool = True,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        headers: dict[str, str] = {}
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        attempt = 0
+        while True:
+            res = self._client.request(method, url, params=_clean(params), json=json, headers=headers)
+            if res.status_code == 429 and attempt < self.max_retries:
+                retry_after = int(res.headers.get("retry-after", "1") or "1")
+                time.sleep(max(1, retry_after))
+                attempt += 1
+                continue
+            request_id = res.headers.get("x-request-id") or res.headers.get("cf-ray")
+            if res.status_code == 204:
+                return None
+            try:
+                body = res.json() if res.content else None
+            except Exception:
+                body = {"raw": res.text}
+            if res.is_error:
+                err = (body or {}).get("error") if isinstance(body, dict) else None
+                message = (
+                    (err or {}).get("message")
+                    if isinstance(err, dict)
+                    else f"{method} {path} failed ({res.status_code})"
+                )
+                code = (
+                    (err or {}).get("code", str(res.status_code))
+                    if isinstance(err, dict)
+                    else str(res.status_code)
+                )
+                if res.status_code == 402 or code == "PAYMENT_REQUIRED":
+                    raise PaymentRequiredError(
+                        message,
+                        code=code,
+                        request_id=request_id,
+                        body=body,
+                    )
+                if code == "QUOTA_EXCEEDED":
+                    raise QuotaExceededError(
+                        message,
+                        code=code,
+                        request_id=request_id,
+                        body=body,
+                    )
+                raise WorklittleError(
+                    message,
+                    status=res.status_code,
+                    code=code,
+                    request_id=request_id,
+                    body=body,
+                )
+            return body
+
+    def get(self, path: str, params: dict[str, Any] | None = None, auth: bool = True) -> Any:
+        return self.request("GET", path, params=params, auth=auth)
+
+    def post(self, path: str, json: Any = None, params: dict[str, Any] | None = None, auth: bool = True) -> Any:
+        return self.request("POST", path, params=params, json=json, auth=auth)
+
+    def put(self, path: str, json: Any = None, auth: bool = True) -> Any:
+        return self.request("PUT", path, json=json, auth=auth)
+
+    def patch(self, path: str, json: Any = None, params: dict[str, Any] | None = None, auth: bool = True) -> Any:
+        return self.request("PATCH", path, params=params, json=json, auth=auth)
+
+    def delete(self, path: str, params: dict[str, Any] | None = None, auth: bool = True) -> Any:
+        return self.request("DELETE", path, params=params, auth=auth)
+
+
+def _clean(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not params:
+        return None
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+class Worklittle:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://api.worklittle.com",
+        max_retries: int = 3,
+    ) -> None:
+        self.http = _Http(
+            api_key=api_key or os.environ.get("WORKLITTLE_API_KEY"),
+            base_url=base_url,
+            max_retries=max_retries,
+        )
+        h = self.http
+        self.jobs = _Jobs(h)
+        self.companies = _Companies(h)
+        self.stats = _Stats(h)
+        self.boards = _Boards(h)
+        self.apply = _Apply(h)
+        self.applied_jobs = _AppliedJobs(h)
+        self.resumes = _Resumes(h)
+        self.cover_letters = _CoverLetters(h)
+        self.agent = _Agent(h)
+        self.job_listings = _JobListings(h)
+        self.employer_jobs = _EmployerJobs(h)
+        self.organization = _Organization(h)
+        self.candidates = _Candidates(h)
+        self.employees = _Employees(h)
+        self.email = _Email(h)
+        self.offers = _Offers(h)
+        self.webhooks = _Webhooks(h)
+        self.documents = _Documents(h)
+        self.attendance = _Attendance(h)
+        self.surveys = _Surveys(h)
+        self.usage = _Usage(h)
+        self.billing = _Billing(h)
+        self.limits = _Limits(h)
+        self.verify_webhook_signature = verify_webhook_signature
+
+
+def create_worklittle(**kwargs: Any) -> Worklittle:
+    return Worklittle(**kwargs)
+
+
+class _Jobs:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def search(self, **params: Any) -> Any:
+        return self._h.get("/jobs", params)
+
+    def get(self, id: str) -> Any:
+        return self._h.get(f"/jobs/{id}")
+
+    def map(self, **params: Any) -> Any:
+        return self._h.get("/jobs/map", params)
+
+    def salary_average(self, **params: Any) -> Any:
+        return self._h.get("/jobs/salary-average", params)
+
+
+class _Companies:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def search(self, **params: Any) -> Any:
+        return self._h.get("/companies", params)
+
+
+class _Stats:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def get(self, **params: Any) -> Any:
+        return self._h.get("/stats", params)
+
+
+class _Boards:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def get(self, company: str, **params: Any) -> Any:
+        return self._h.get(f"/job-boards/{company}/board", params, auth=bool(self._h.api_key))
+
+    def list_jobs(self, company: str, **params: Any) -> Any:
+        return self._h.get(f"/job-boards/{company}/jobs", params, auth=bool(self._h.api_key))
+
+    def facets(self, company: str, **params: Any) -> Any:
+        return self._h.get(f"/job-boards/{company}/facets", params, auth=bool(self._h.api_key))
+
+    def get_job(self, company: str, id_or_slug: str, **params: Any) -> Any:
+        return self._h.get(
+            f"/job-boards/{company}/jobs/{id_or_slug}", params, auth=bool(self._h.api_key)
+        )
+
+    def apply(self, company: str, id_or_slug: str, body: dict[str, Any]) -> Any:
+        return self._h.post(f"/job-boards/{company}/jobs/{id_or_slug}/apply", body, auth=False)
+
+    def parse_resume(self, company: str, id_or_slug: str, resume_file: dict[str, Any]) -> Any:
+        return self._h.post(
+            f"/job-boards/{company}/jobs/{id_or_slug}/parse-resume",
+            {"resume_file": resume_file},
+            auth=False,
+        )
+
+
+class _Apply:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def submit(self, job_id: str, body: dict[str, Any]) -> Any:
+        return self._h.post(f"/jobs/{job_id}/apply", body)
+
+    def start_with_ai(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/v1/apply-with-ai", body)
+
+    def get_with_ai_session(self, session_id: str) -> Any:
+        return self._h.get(f"/v1/apply-with-ai/{session_id}")
+
+    def approve_with_ai_submit(self, session_id: str) -> Any:
+        return self._h.post(f"/v1/apply-with-ai/{session_id}/approve-submit", {})
+
+    def continue_with_ai(self, session_id: str, answers: dict[str, str] | None = None) -> Any:
+        return self._h.post(
+            f"/v1/apply-with-ai/{session_id}/continue",
+            {"answers": answers or {}},
+        )
+
+    def stop_with_ai(self, session_id: str) -> Any:
+        return self._h.post(f"/v1/apply-with-ai/{session_id}/stop", {})
+
+
+class _AppliedJobs:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/applied-jobs", params)
+
+
+class _Resumes:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/v1/resumes", body)
+
+
+class _CoverLetters:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/v1/cover-letters", body)
+
+
+class _Agent:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list_tools(self) -> Any:
+        return self._h.get("/v1/agent/tools")
+
+    def run_tool(self, name: str, arguments: dict[str, Any] | None = None) -> Any:
+        return self._h.post("/v1/agent/tool", {"name": name, "arguments": arguments or {}})
+
+
+class _JobListings:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/job-listings", params)
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/job-listings", body)
+
+    def update(self, id: str, body: dict[str, Any]) -> Any:
+        return self._h.patch(f"/job-listings/{id}", body)
+
+    def delete(self, id: str) -> Any:
+        return self._h.delete(f"/job-listings/{id}")
+
+
+class _EmployerJobs:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/jobs/post", params)
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/jobs/post", body)
+
+    def update(self, id: str, body: dict[str, Any]) -> Any:
+        return self._h.patch(f"/jobs/post/{id}", body)
+
+
+class _Organization:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list_company_orgs(self, **params: Any) -> Any:
+        return self._h.get("/company-organizations", params)
+
+    def list_interview_questions(self, **params: Any) -> Any:
+        return self._h.get("/interview-questions", params)
+
+
+class _Candidates:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/candidates", params)
+
+    def get(self, id: str) -> Any:
+        return self._h.get(f"/candidates/{id}")
+
+
+class _Employees:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/employees", params)
+
+    def get(self, id: str) -> Any:
+        return self._h.get(f"/employees/{id}")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/employees", body)
+
+
+class _Email:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list_messages(self, **params: Any) -> Any:
+        return self._h.get("/email-messages", params)
+
+    def send(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/email/send", body)
+
+    def list_sends(self, **params: Any) -> Any:
+        return self._h.get("/email/sends", params)
+
+    def get_send(self, id: str) -> Any:
+        return self._h.get(f"/email/sends/{id}")
+
+    def list_send_events(self, id: str) -> Any:
+        return self._h.get(f"/email/sends/{id}/events")
+
+
+class _Usage:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        """GET /usage — org audit logs (metered + org activity).
+
+        Optional params: source (all|public_api|platform_ai|org_activity),
+        since, until, cursor, limit, api_key_id.
+        Rows include where_label / where_href (Chat, Voice, job title, Private, …;
+        Chat/Voice hrefs are absolute when a chat id is known).
+        Activity rows have ledger_type=org_activity and charged_usd=0.
+        """
+        return self._h.get("/usage", params)
+
+
+class _Billing:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def balance(self) -> Any:
+        return self._h.get("/billing/balance")
+
+    def invoices(self, **params: Any) -> Any:
+        return self._h.get("/billing/invoices", params)
+
+
+class _Limits:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def get(self) -> Any:
+        return self._h.get("/limits")
+
+    def get_budget(self) -> Any:
+        return self._h.get("/limits/budget")
+
+    def set_budget(self, body: dict[str, Any]) -> Any:
+        return self._h.put("/limits/budget", body)
+
+
+class _Offers:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/offers", params)
+
+
+class _Webhooks:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self) -> Any:
+        return self._h.get("/webhooks")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/webhooks", body)
+
+    def test(self, id: str) -> Any:
+        return self._h.post(f"/webhooks/{id}/test", {})
+
+
+class _Documents:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/platform/documents", params)
+
+    def templates(self, **params: Any) -> Any:
+        return self._h.get("/platform/documents/templates", params)
+
+
+class _Attendance:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/attendance", params)
+
+    def me(self, **params: Any) -> Any:
+        return self._h.get("/attendance/me", params)
+
+
+class _Surveys:
+    def __init__(self, http: _Http) -> None:
+        self._h = http
+
+    def list(self, **params: Any) -> Any:
+        return self._h.get("/platform/surveys", params)
+
+    def get(self, id: str) -> Any:
+        return self._h.get(f"/platform/surveys/{id}")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._h.post("/platform/surveys", body)

worklittle-1.1.0/worklittle/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+
+class WorklittleError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str = "UNKNOWN",
+        request_id: str | None = None,
+        body: object = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.body = body
+
+
+class PaymentRequiredError(WorklittleError):
+    """HTTP 402 — do not retry metered requests until billing is fixed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: str | None = None,
+        body: object = None,
+        code: str = "PAYMENT_REQUIRED",
+    ) -> None:
+        super().__init__(message, status=402, code=code, request_id=request_id, body=body)
+
+
+class QuotaExceededError(WorklittleError):
+    """HTTP 429 + QUOTA_EXCEEDED — monthly free quota exhausted; inquire for higher limits."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: str | None = None,
+        body: object = None,
+        code: str = "QUOTA_EXCEEDED",
+    ) -> None:
+        super().__init__(message, status=429, code=code, request_id=request_id, body=body)

worklittle-1.1.0/worklittle/webhooks.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+
+def verify_webhook_signature(
+    *,
+    signature_header: str,
+    timestamp: str,
+    raw_body: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> bool:
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        return False
+    if abs(int(time.time()) - ts) > tolerance_seconds:
+        return False
+    received = signature_header.removeprefix("v1=").strip()
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        f"{timestamp}.{raw_body}".encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return hmac.compare_digest(expected, received)