tickwire-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ """The ``tickwire`` command line (``docs/public/cli.md``)."""
2
+ from ._version import __version__
3
+
4
+ __all__ = ["__version__"]
@@ -0,0 +1,14 @@
1
+ """``python -m tickwire_cli`` and the ``tickwire`` console script."""
2
+ from __future__ import annotations
3
+
4
+ import sys
5
+
6
+ from .app import run
7
+
8
+
9
+ def main() -> None:
10
+ raise SystemExit(run(sys.argv[1:]))
11
+
12
+
13
+ if __name__ == "__main__":
14
+ main()
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
tickwire_cli/app.py ADDED
@@ -0,0 +1,174 @@
1
+ """Argument parsing, the shared context, and error handling for every command.
2
+
3
+ Exit codes:
4
+
5
+ ==== ==========================================================
6
+ 0 done (for ``trade``: ``applied`` or ``no_change``)
7
+ 1 the API answered with an error, or the request failed
8
+ 2 usage or configuration problem (no login, bad flags)
9
+ 3 ``trade``: ``rejected`` (not executed)
10
+ 4 ``trade``: ``held`` by a pre-trade hook, awaiting a decision
11
+ 5 ``trade``: ``unknown``: it MAY have executed; never re-sent
12
+ 130 interrupted (Ctrl-C)
13
+ ==== ==========================================================
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import getpass as _getpass
19
+ import os
20
+ import sys
21
+ import time
22
+ from collections.abc import Callable, Mapping
23
+ from dataclasses import dataclass, field
24
+ from typing import Any, TextIO
25
+ from urllib.parse import urlsplit
26
+
27
+ import httpx
28
+ from tickwire import ConfigError, Tickwire, TickwireError
29
+ from tickwire.config import ENV_API_KEY, ENV_API_URL, ENV_SANDBOX_URL
30
+
31
+ from ._version import __version__
32
+ from .commands import COMMANDS
33
+ from .credentials import DEFAULT_PROFILE, SANDBOX_PROFILE, CredentialError, CredentialStore
34
+ from .errors import UsageError
35
+ from .output import Output
36
+
37
+ EXIT_OK, EXIT_ERROR, EXIT_USAGE = 0, 1, 2
38
+ ACTOR = "tickwire-cli"
39
+
40
+
41
+ LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
42
+
43
+
44
+ def check_api_url(url: str) -> None:
45
+ """https:// always; plain http:// only to this machine (a local stack), because the
46
+ API key travels in every request."""
47
+ parts = urlsplit(url)
48
+ host = (parts.hostname or "").lower()
49
+ if parts.scheme == "https" and host:
50
+ return
51
+ if parts.scheme == "http" and host in LOCAL_HOSTS:
52
+ return
53
+ raise UsageError(f"the API URL must be https://… (http:// is allowed only for localhost, 127.0.0.1 "
54
+ f"or [::1]); got {url!r}")
55
+
56
+
57
+ @dataclass
58
+ class Ctx:
59
+ args: argparse.Namespace
60
+ out: Output
61
+ store: CredentialStore
62
+ env: Mapping[str, str]
63
+ stdin: TextIO
64
+ transport: httpx.BaseTransport | None = None # API calls (tests inject one)
65
+ forward_transport: httpx.BaseTransport | None = None # listen --forward-to (tests inject one)
66
+ getpass: Callable[[str], str] = _getpass.getpass
67
+ sleep: Callable[[float], Any] = time.sleep
68
+ _client: Tickwire | None = field(default=None, repr=False)
69
+
70
+ # ---- which profile, URL and key
71
+ @property
72
+ def sandbox(self) -> bool:
73
+ return bool(getattr(self.args, "sandbox", False))
74
+
75
+ @property
76
+ def profile_name(self) -> str:
77
+ name = getattr(self.args, "profile", None) or self.env.get("TICKWIRE_PROFILE")
78
+ return name or (SANDBOX_PROFILE if self.sandbox else DEFAULT_PROFILE)
79
+
80
+ def api_url(self, *, sandbox: bool | None = None, required: bool = True) -> str:
81
+ sandbox = self.sandbox if sandbox is None else sandbox
82
+ url = getattr(self.args, "api_url", None) or self.env.get(ENV_SANDBOX_URL if sandbox else ENV_API_URL, "")
83
+ if not url:
84
+ p = self.store.profile(self.profile_name)
85
+ url = p.api_url if p else ""
86
+ url = (url or "").strip().rstrip("/")
87
+ if required and not url:
88
+ env = ENV_SANDBOX_URL if sandbox else ENV_API_URL
89
+ raise UsageError(f"no API URL: pass --api-url or set {env}")
90
+ if url:
91
+ check_api_url(url)
92
+ return url
93
+
94
+ def client(self) -> Tickwire:
95
+ if self._client is not None:
96
+ return self._client
97
+ name = self.profile_name
98
+ profile = self.store.profile(name)
99
+ if self.sandbox and profile is not None and not profile.sandbox:
100
+ raise UsageError(f"profile {name!r} is a live profile, but --sandbox was given")
101
+ key = self.env.get(ENV_API_KEY, "").strip()
102
+ if not key:
103
+ key = self.store.key(name) or ""
104
+ if not key:
105
+ hint = " --sandbox" if self.sandbox else ""
106
+ raise UsageError(f"not logged in (profile {name!r}): run `tickwire login{hint}` "
107
+ f"or set {ENV_API_KEY}")
108
+ sandbox = self.sandbox or bool(profile and profile.sandbox)
109
+ self._client = Tickwire(base_url=self.api_url(sandbox=sandbox), token=key, actor=ACTOR,
110
+ transport=self.transport)
111
+ return self._client
112
+
113
+ def close(self) -> None:
114
+ if self._client is not None:
115
+ self._client.close()
116
+
117
+
118
+ def _global_options(p: argparse.ArgumentParser, *, suppress: bool) -> None:
119
+ d = {"default": argparse.SUPPRESS} if suppress else {}
120
+ p.add_argument("--json", action="store_true", help="machine-readable JSON output", **d)
121
+ p.add_argument("--profile", help="credential profile (default: 'default', or 'sandbox' with --sandbox)", **d)
122
+ p.add_argument("--sandbox", action="store_true", help="use the sandbox (TICKWIRE_SANDBOX_URL)", **d)
123
+ p.add_argument("--api-url", help="API base URL (else TICKWIRE_API_URL / TICKWIRE_SANDBOX_URL "
124
+ "or the profile's)", **d)
125
+
126
+
127
+ def build_parser() -> argparse.ArgumentParser:
128
+ parser = argparse.ArgumentParser(prog="tickwire", description="The Tickwire MT4/MT5 cloud API from your terminal.")
129
+ parser.add_argument("--version", action="version", version=f"tickwire-cli {__version__}")
130
+ _global_options(parser, suppress=False)
131
+ common = argparse.ArgumentParser(add_help=False)
132
+ _global_options(common, suppress=True) # the same flags also work after the command
133
+ sub = parser.add_subparsers(dest="command", metavar="<command>")
134
+ sub.required = True
135
+ for module in COMMANDS:
136
+ module.register(sub, common)
137
+ return parser
138
+
139
+
140
+ def run(argv: list[str], *, env: Mapping[str, str] | None = None, stdin: TextIO | None = None,
141
+ stdout: TextIO | None = None, stderr: TextIO | None = None,
142
+ transport: httpx.BaseTransport | None = None, forward_transport: httpx.BaseTransport | None = None,
143
+ getpass: Callable[[str], str] | None = None, sleep: Callable[[float], Any] | None = None,
144
+ store: CredentialStore | None = None) -> int:
145
+ env = os.environ if env is None else env
146
+ parser = build_parser()
147
+ try:
148
+ args = parser.parse_args(argv)
149
+ except SystemExit as e: # --help, --version, bad usage
150
+ return int(e.code or 0)
151
+ out = Output(bool(getattr(args, "json", False)), stdout, stderr)
152
+ ctx = Ctx(args=args, out=out, store=store or CredentialStore(env=env), env=env,
153
+ stdin=stdin or sys.stdin, transport=transport, forward_transport=forward_transport,
154
+ getpass=getpass or _getpass.getpass, sleep=sleep or time.sleep)
155
+ try:
156
+ return int(args.func(ctx) or 0)
157
+ except UsageError as e:
158
+ out.error("usage", str(e))
159
+ return EXIT_USAGE
160
+ except (CredentialError, ConfigError) as e:
161
+ out.error("config", getattr(e, "message", None) or str(e))
162
+ return EXIT_USAGE
163
+ except TickwireError as e:
164
+ extra = {"status": e.status} if e.status is not None else {}
165
+ rid = e.body.get("requestId") if isinstance(e.body, dict) else None
166
+ if rid:
167
+ extra["requestId"] = rid
168
+ out.error(e.code or type(e).__name__, e.message, **extra)
169
+ return EXIT_ERROR
170
+ except KeyboardInterrupt:
171
+ out.note("interrupted")
172
+ return 130
173
+ finally:
174
+ ctx.close()
@@ -0,0 +1,11 @@
1
+ """The ``tickwire`` commands. Each module has ``register(subparsers, common)``,
2
+ which adds its parser(s) with ``parents=[common]`` (the global flags) and sets
3
+ ``func(ctx) -> exit code``.
4
+
5
+ To add a command, add a module here and list it in :data:`COMMANDS`.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ from . import accounts, login, logs, sandbox, trade, trigger, webhooks_listen
10
+
11
+ COMMANDS = [login, sandbox, accounts, trade, webhooks_listen, trigger, logs]
@@ -0,0 +1,51 @@
1
+ """``tickwire accounts list`` and ``tickwire accounts get <id> [--health]``."""
2
+ from __future__ import annotations
3
+
4
+ from ..output import table
5
+
6
+
7
+ def register(sub, common) -> None:
8
+ p = sub.add_parser("accounts", parents=[common], help="your trading accounts")
9
+ ss = p.add_subparsers(dest="accounts_command", metavar="<subcommand>")
10
+ ss.required = True
11
+ ls = ss.add_parser("list", parents=[common], help="list accounts")
12
+ ls.set_defaults(func=list_accounts)
13
+ g = ss.add_parser("get", parents=[common], help="one account")
14
+ g.add_argument("account_id")
15
+ g.add_argument("--health", action="store_true", help="also read the account's truthful health")
16
+ g.set_defaults(func=get_account)
17
+
18
+
19
+ def _row(a: dict) -> list:
20
+ return [a.get("id"), a.get("platform"), a.get("login"), a.get("server"), a.get("status"),
21
+ "yes" if a.get("sandbox") else ""]
22
+
23
+
24
+ HEADERS = ["ID", "PLATFORM", "LOGIN", "SERVER", "STATUS", "SANDBOX"]
25
+
26
+
27
+ def list_accounts(ctx) -> int:
28
+ accounts = ctx.client().list_accounts() or []
29
+ ctx.out.result(accounts, lambda: table([_row(a) for a in accounts], HEADERS) if accounts
30
+ else "No accounts.")
31
+ return 0
32
+
33
+
34
+ def get_account(ctx) -> int:
35
+ tw = ctx.client()
36
+ account = tw.get_account(ctx.args.account_id)
37
+ if ctx.args.health:
38
+ account = {**account, "health": tw.account(ctx.args.account_id).health()}
39
+
40
+ def human() -> str:
41
+ lines = [table([_row(account)], HEADERS)]
42
+ if account.get("error"):
43
+ lines.append(f"error: {account['error']}")
44
+ h = account.get("health")
45
+ if isinstance(h, dict):
46
+ reasons = ", ".join(h.get("reasons") or []) or "none"
47
+ lines.append(f"health: {h.get('status')} (reasons: {reasons}; checked {h.get('checked_at')})")
48
+ return "\n".join(lines)
49
+
50
+ ctx.out.result(account, human)
51
+ return 0
@@ -0,0 +1,81 @@
1
+ """``tickwire login`` / ``tickwire logout``: store or remove an API key.
2
+
3
+ The key is never a command-line argument (it would land in shell history and
4
+ the process list) and is never printed: it is read with a hidden prompt, or
5
+ from standard input (``--key-stdin``, or any non-terminal stdin), then checked
6
+ against the API and stored in the OS keychain or a ``0600`` file.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ from tickwire import Tickwire
11
+
12
+ from ..credentials import SANDBOX_PROFILE
13
+ from ..errors import UsageError
14
+
15
+ SANDBOX_PREFIX = "twsk_"
16
+
17
+
18
+ def register(sub, common) -> None:
19
+ p = sub.add_parser("login", parents=[common], help="store an API key (hidden prompt or stdin)",
20
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
21
+ p.add_argument("--key-stdin", action="store_true", help="read the key from standard input")
22
+ p.add_argument("--no-keyring", action="store_true", help="store in the 0600 file even if a keychain exists")
23
+ p.add_argument("--no-verify", action="store_true", help="store without checking the key against the API")
24
+ p.set_defaults(func=login)
25
+
26
+ q = sub.add_parser("logout", parents=[common], help="forget the stored key of a profile")
27
+ q.set_defaults(func=logout)
28
+
29
+
30
+ def _read_key(ctx) -> str:
31
+ stdin = ctx.stdin
32
+ if getattr(ctx.args, "key_stdin", False) or not _isatty(stdin):
33
+ key = stdin.readline()
34
+ else:
35
+ key = ctx.getpass("Tickwire API key (input hidden): ")
36
+ key = (key or "").strip()
37
+ if not key:
38
+ raise UsageError("no key given")
39
+ if any(c.isspace() for c in key) or not key.isprintable():
40
+ raise UsageError("that does not look like an API key (it contains spaces or control characters)")
41
+ return key
42
+
43
+
44
+ def _isatty(stream) -> bool:
45
+ try:
46
+ return bool(stream.isatty())
47
+ except (AttributeError, ValueError):
48
+ return False
49
+
50
+
51
+ def login(ctx) -> int:
52
+ name = ctx.profile_name
53
+ existing = ctx.store.profile(name)
54
+ sandbox = ctx.sandbox or (name == SANDBOX_PROFILE) or bool(existing and existing.sandbox)
55
+ url = ctx.api_url(sandbox=sandbox)
56
+ key = _read_key(ctx)
57
+ if sandbox and not key.startswith(SANDBOX_PREFIX):
58
+ raise UsageError(f"--sandbox needs a sandbox key ({SANDBOX_PREFIX}…); this looks like a live key")
59
+ if not sandbox and key.startswith(SANDBOX_PREFIX):
60
+ raise UsageError("this is a sandbox key: run `tickwire login --sandbox`")
61
+ verified = False
62
+ if not ctx.args.no_verify:
63
+ with Tickwire(base_url=url, token=key, actor="tickwire-cli", transport=ctx.transport) as tw:
64
+ tw.list_accounts() # 401 raises: nothing is stored
65
+ verified = True
66
+ profile = ctx.store.save(name, key, api_url=url, sandbox=sandbox, use_keyring=not ctx.args.no_keyring)
67
+ where = ("the OS keychain" if profile.storage == "keyring"
68
+ else f"{ctx.store.dir / 'credentials.json'} (mode 600)")
69
+ data = {**profile.public(), "verified": verified}
70
+ ctx.out.result(data, f"Logged in: profile {name!r}, {'sandbox' if sandbox else 'live'} API at {url}.\n"
71
+ f"Key {profile.key_hint} stored in {where}"
72
+ + ("" if verified else " (not verified: --no-verify)") + ".")
73
+ return 0
74
+
75
+
76
+ def logout(ctx) -> int:
77
+ name = ctx.profile_name
78
+ removed = ctx.store.delete(name)
79
+ ctx.out.result({"profile": name, "removed": removed},
80
+ f"Removed the key of profile {name!r}." if removed else f"No profile {name!r}.")
81
+ return 0
@@ -0,0 +1,272 @@
1
+ """``tickwire logs tail``: your request log (``GET /v1/request-logs``) in the terminal.
2
+
3
+ Prints the most recent calls your organisation's keys made, oldest first, one
4
+ line per request (``--json``: one JSON object per line). ``--follow`` keeps
5
+ polling and prints new calls as the gateway records them; Ctrl-C stops it.
6
+
7
+ How it works (``docs/public/cli.md`` has the full story):
8
+
9
+ * The list is newest first and paginated with an opaque cursor
10
+ (``nextCursor``/``hasMore``). The CLI never decodes the cursor; it passes it
11
+ back unchanged, with the same filters, as the API requires.
12
+ * ``--follow`` polls the first page every ``--interval`` seconds and walks
13
+ back until it reaches a call it already printed, so a call that is recorded
14
+ late is still shown once. If more than ``MAX_POLL_ROWS`` calls arrived
15
+ between two polls, it prints the newest and says how many pages it skipped.
16
+ * ``--bodies`` fetches ``GET /v1/request-logs/{id}`` for failed calls
17
+ (status >= 400; only those keep excerpts) and prints the redacted
18
+ ``requestBody``/``responseBody`` exactly as the API returned them. Nothing is
19
+ printed when the API returns none. A credential that may not see bodies
20
+ (``excerptsHidden: true`` or ``403``) gets metadata only, with one note.
21
+ * ``429``: the CLI waits for ``Retry-After`` (or backs off exponentially when
22
+ there is none) and tries again: forever with ``--follow``, a few times
23
+ otherwise. Timeouts and 502/503/504 are handled the same way.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import re
28
+ from collections import OrderedDict
29
+ from datetime import datetime, timedelta, timezone
30
+ from urllib.parse import quote
31
+
32
+ from tickwire import Backoff, TickwireError, TransportError
33
+ from tickwire.errors import Forbidden, NotFound, RateLimited
34
+
35
+ from ..errors import UsageError
36
+ from ..output import clean
37
+
38
+ PAGE_MAX = 200 # the API's largest page
39
+ POLL_PAGE = 100 # page size while following
40
+ MAX_POLL_ROWS = 2000 # new calls walked per poll before we say we skipped some
41
+ MAX_LIMIT = 1000
42
+ SEEN_MAX = 10_000 # ids remembered to avoid printing a call twice
43
+ RETRY_STATUS = frozenset({408, 429, 502, 503, 504})
44
+ ONE_SHOT_RETRIES = 3
45
+ BACKOFF_BASE_S, BACKOFF_CAP_S = 1.0, 60.0
46
+ _REL = re.compile(r"^(\d+)\s*([smhd])$")
47
+ _UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days"}
48
+
49
+
50
+ def register(sub, common) -> None:
51
+ p = sub.add_parser("logs", parents=[common], help="your request log",
52
+ description="Read your organisation's request log (GET /v1/request-logs).")
53
+ lsub = p.add_subparsers(dest="logs_command", metavar="<subcommand>")
54
+ lsub.required = True
55
+ t = lsub.add_parser("tail", parents=[common], help="print recent API calls; --follow for new ones",
56
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
57
+ t.add_argument("-f", "--follow", action="store_true", help="keep polling and print new calls (Ctrl-C stops)")
58
+ t.add_argument("-n", "--limit", type=int, default=20,
59
+ help=f"how many recent calls to print first (default 20, at most {MAX_LIMIT}; "
60
+ f"0 with --follow prints only new ones)")
61
+ t.add_argument("--since", help="only calls at or after this time: ISO 8601, or relative (30s, 15m, 2h, 7d)")
62
+ t.add_argument("--until", help="only calls before this time (ISO 8601 or relative); not with --follow")
63
+ t.add_argument("--status", help="404, 4xx, 5xx, errors (>= 400) or aborted")
64
+ t.add_argument("--method", help="GET, POST, …")
65
+ t.add_argument("--route", "--path", dest="route", help="part of the path or of its template")
66
+ t.add_argument("--error-code", help="e.g. validation_error")
67
+ t.add_argument("--account", help="trading account id")
68
+ t.add_argument("--key-id", help="API key id (never the key itself)")
69
+ t.add_argument("--request-id", help="an X-Request-ID")
70
+ t.add_argument("--bodies", action="store_true",
71
+ help="also print the redacted request/response excerpts of failed calls "
72
+ "(full-access key with the writer role only)")
73
+ t.add_argument("--interval", type=float, default=2.0, help="seconds between polls with --follow (default 2)")
74
+ t.set_defaults(func=tail)
75
+
76
+
77
+ # --------------------------------------------------------------------------- helpers
78
+ def _now() -> datetime:
79
+ return datetime.now(timezone.utc)
80
+
81
+
82
+ def parse_time(value: str | None, flag: str) -> str | None:
83
+ """``--since``/``--until``: ISO 8601 (kept as given, UTC when no zone) or ``<n>[smhd]`` ago."""
84
+ if value is None or not value.strip():
85
+ return None
86
+ v = value.strip()
87
+ m = _REL.match(v.lower())
88
+ if m:
89
+ dt = _now() - timedelta(**{_UNITS[m.group(2)]: int(m.group(1))})
90
+ else:
91
+ try:
92
+ dt = datetime.fromisoformat(v.replace("Z", "+00:00").replace("z", "+00:00"))
93
+ except ValueError:
94
+ raise UsageError(f"{flag} must be an ISO 8601 time (2026-09-28T10:00:00Z) or relative "
95
+ f"(30s, 15m, 2h, 7d); got {value!r}") from None
96
+ if dt.tzinfo is None:
97
+ dt = dt.replace(tzinfo=timezone.utc)
98
+ return dt.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
99
+
100
+
101
+ def _latency(ms) -> str:
102
+ if ms is None:
103
+ return "-"
104
+ return f"{ms} ms" if ms < 10_000 else f"{ms / 1000:.1f} s"
105
+
106
+
107
+ def human_line(row: dict) -> str:
108
+ parts = [str(row.get("createdAt") or "-"), f"{row.get('method') or '-':<6}", str(row.get("status") or "-"),
109
+ f"{_latency(row.get('latencyMs')):>8}", str(row.get("path") or "-")]
110
+ if row.get("errorCode"):
111
+ parts.append(str(row["errorCode"]))
112
+ if row.get("outcome") == "aborted":
113
+ parts.append("[aborted]")
114
+ if row.get("kind") == "websocket":
115
+ parts.append("[websocket]")
116
+ if row.get("accountId"):
117
+ parts.append(f"account={row['accountId']}")
118
+ parts.append(str(row.get("requestId") or row.get("id") or ""))
119
+ return " ".join(p for p in parts if p)
120
+
121
+
122
+ class _Tail:
123
+ def __init__(self, ctx) -> None:
124
+ self.ctx = ctx
125
+ a = ctx.args
126
+ self.a = a
127
+ self.tw = ctx.client()
128
+ # The CLI owns retries here: it honours Retry-After in full (the SDK caps its wait) and,
129
+ # with --follow, keeps going. One attempt per SDK call.
130
+ self.tw.opts.backoff = Backoff(max_attempts=1)
131
+ self.filters = {"status": a.status, "method": a.method, "route": a.route, "errorCode": a.error_code,
132
+ "accountId": a.account, "keyId": a.key_id, "requestId": a.request_id,
133
+ "since": parse_time(a.since, "--since"), "until": parse_time(a.until, "--until")}
134
+ self.seen: OrderedDict[str, None] = OrderedDict()
135
+ self.bodies = bool(a.bodies)
136
+ self.shown = 0
137
+
138
+ # ---- one API call, with the retry policy
139
+ def call(self, path: str, params: dict | None = None):
140
+ failures = 0
141
+ while True:
142
+ try:
143
+ return self.tw.request("GET", path, control=True, params=params)
144
+ except TickwireError as e:
145
+ retryable = isinstance(e, (RateLimited, TransportError)) or e.status in RETRY_STATUS
146
+ if not retryable or (not self.a.follow and failures >= ONE_SHOT_RETRIES):
147
+ raise
148
+ failures += 1
149
+ backoff = min(BACKOFF_CAP_S, BACKOFF_BASE_S * 2 ** (failures - 1))
150
+ retry_after = getattr(e, "retry_after", None)
151
+ wait = max(float(retry_after), backoff) if retry_after is not None else backoff
152
+ what = "rate limited (429)" if isinstance(e, RateLimited) else (
153
+ f"HTTP {e.status}" if e.status else "no answer")
154
+ self.ctx.out.note(f"{what}: retrying in {wait:g} s"
155
+ + (" (Retry-After)" if retry_after is not None else ""))
156
+ self.ctx.sleep(wait)
157
+
158
+ def page(self, limit: int, cursor: str | None) -> dict:
159
+ page = self.call("/request-logs", {**self.filters, "limit": limit, "cursor": cursor})
160
+ if not isinstance(page, dict) or not isinstance(page.get("data"), list):
161
+ raise TickwireError("unexpected answer from GET /v1/request-logs (no data list)")
162
+ return page
163
+
164
+ # ---- the rows
165
+ def newest(self, n: int) -> list[dict]:
166
+ """The ``n`` newest calls, newest first."""
167
+ rows: list[dict] = []
168
+ cursor = None
169
+ while len(rows) < n:
170
+ page = self.page(min(PAGE_MAX, n - len(rows)), cursor)
171
+ rows += page["data"]
172
+ cursor = page.get("nextCursor")
173
+ if not (page.get("hasMore") and cursor):
174
+ break
175
+ return rows[:n]
176
+
177
+ def new_since_last_poll(self) -> list[dict]:
178
+ """Calls not printed yet, newest first. Walks back until a call already seen."""
179
+ rows: list[dict] = []
180
+ cursor = None
181
+ while True:
182
+ page = self.page(POLL_PAGE, cursor)
183
+ for row in page["data"]:
184
+ if row.get("id") in self.seen:
185
+ return rows
186
+ rows.append(row)
187
+ cursor = page.get("nextCursor")
188
+ if not (page.get("hasMore") and cursor):
189
+ return rows
190
+ if len(rows) >= MAX_POLL_ROWS:
191
+ self.ctx.out.note(f"warning: more than {MAX_POLL_ROWS} new calls since the last poll; "
192
+ f"showing the newest {len(rows)}, older ones in between were skipped "
193
+ f"(narrow the filters or use a shorter --interval)")
194
+ return rows
195
+
196
+ def remember(self, row: dict) -> None:
197
+ rid = row.get("id")
198
+ if rid is None:
199
+ return
200
+ self.seen[rid] = None
201
+ while len(self.seen) > SEEN_MAX:
202
+ self.seen.popitem(last=False)
203
+
204
+ # ---- --bodies
205
+ def detail(self, row: dict) -> dict:
206
+ """The row plus the excerpts the API returned for it (errors only), or the row alone."""
207
+ if not self.bodies or not isinstance(row.get("status"), int) or row["status"] < 400 or not row.get("id"):
208
+ return row
209
+ try:
210
+ d = self.call(f"/request-logs/{quote(str(row['id']), safe='')}")
211
+ except Forbidden as e:
212
+ self._no_bodies(clean(f"403 {e.code or 'forbidden'}"))
213
+ return row
214
+ except NotFound: # pruned between the list and the detail: metadata only
215
+ return row
216
+ if not isinstance(d, dict):
217
+ return row
218
+ if d.get("excerptsHidden"):
219
+ self._no_bodies("the API hides them from this credential")
220
+ return {**row, "excerptsHidden": True}
221
+ out = dict(row)
222
+ for k in ("requestBody", "responseBody"):
223
+ if d.get(k) is not None: # only what the API returned
224
+ out[k] = d[k]
225
+ return out
226
+
227
+ def _no_bodies(self, why: str) -> None:
228
+ self.bodies = False
229
+ self.ctx.out.note(f"note: request/response bodies are not shown ({why}). Only a full-access key "
230
+ f"with the writer role, not limited to some accounts or applications, may read "
231
+ f"them; printing metadata only.")
232
+
233
+ def emit(self, rows_newest_first: list[dict]) -> None:
234
+ for row in reversed(rows_newest_first):
235
+ if row.get("id") in self.seen:
236
+ continue
237
+ row = self.detail(row)
238
+ lines = [human_line(row)] # each line is made terminal-safe by Output.line
239
+ for k, label in (("requestBody", "request "), ("responseBody", "response")):
240
+ if row.get(k) is not None:
241
+ lines.append(f" {label}: {row[k]}")
242
+ self.ctx.out.line(row, lines)
243
+ self.remember(row)
244
+ self.shown += 1
245
+
246
+
247
+ def tail(ctx) -> int:
248
+ a = ctx.args
249
+ if a.limit < 0 or a.limit > MAX_LIMIT or (a.limit == 0 and not a.follow):
250
+ raise UsageError(f"--limit must be 1 to {MAX_LIMIT} (0 is allowed with --follow)")
251
+ if a.follow and a.until:
252
+ raise UsageError("--until cannot be combined with --follow")
253
+ if a.interval <= 0:
254
+ raise UsageError("--interval must be positive")
255
+ t = _Tail(ctx)
256
+ try:
257
+ if a.limit:
258
+ t.emit(t.newest(a.limit))
259
+ elif a.follow:
260
+ for row in t.newest(1): # start from the current head, print nothing old
261
+ t.remember(row)
262
+ if not a.follow:
263
+ if not t.shown:
264
+ ctx.out.note("no matching calls in the request log (kept 14 days)")
265
+ return 0
266
+ ctx.out.note("following the request log; Ctrl-C to stop")
267
+ while True:
268
+ ctx.sleep(a.interval)
269
+ t.emit(t.new_since_last_poll())
270
+ except KeyboardInterrupt:
271
+ ctx.out.note(f"stopped ({t.shown} call{'s' if t.shown != 1 else ''} shown)")
272
+ return 130