diff --git a/CHANGELOG.md b/CHANGELOG.md index dd75106..a141b94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## Unreleased + +- `apple_reply_review` is now two-step: the default call validates and returns a preview without sending; it sends only with the `confirm_token` from that preview, a hash of the exact text, attachments and submission, so nothing can change between preview and send, and a token sends only once (#12). Suggested by u/QuanTradin on r/mcp. +- Tools marked "External action" now carry MCP tool annotations (`destructiveHint`, `openWorldHint`) so clients can gate them. + ## 0.2.0 - Toolsets: `SHIPSTORES_TOOLSETS` (or `[server] toolsets` in `config.toml`) exposes only the tool groups you need: `apple`, `play` and/or `eas`. Core diagnostics stay on, and the default is still all 60 tools. Thanks @berkay-byte for the first community contribution (#11). diff --git a/README.md b/README.md index 615cf4c..8c4bdbb 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ uvx --from shipstores python -m shipstores.browser login # opens a window; sig **Apple: listing & app setup** — `apple_update_listing`, `apple_upload_screenshots`, `apple_set_app_info` (subtitle, URLs, categories, copyright, content rights), `apple_set_age_rating`, `apple_set_free_price`, `apple_set_availability`, `apple_set_app_privacy`, `apple_review_details`, `apple_set_review_details` -**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264) +**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264; returns a preview and a `confirm_token` first; only sends when called again with that token) **Apple: subscriptions** — `apple_create_subscription_group`, `apple_create_subscription`, `apple_list_price_points`, `apple_set_subscription_price`, `apple_set_subscription_availability`, `apple_create_intro_offer`, `apple_list_subscriptions`, `apple_upload_subscription_screenshot` @@ -115,7 +115,7 @@ uvx --from shipstores python -m shipstores.browser login # opens a window; sig **Expo / EAS** — `eas_build_list`, `eas_build_start`, `eas_build_status`, `eas_build_download`, `eas_submit` -Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first. +Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first. They also carry MCP tool annotations (`destructiveHint`), so clients that support them can ask for approval on their own. `apple_reply_review` goes further: the reply reaches a person at Apple, so the server only sends it on a second call carrying the `confirm_token` from the preview — a hash of the exact text, attachments and submission, usable once. ## Workflows diff --git a/src/shipstores/apple_review.py b/src/shipstores/apple_review.py index 8138e58..2711c2c 100644 --- a/src/shipstores/apple_review.py +++ b/src/shipstores/apple_review.py @@ -29,6 +29,15 @@ ASC = "https://appstoreconnect.apple.com" +# Printed by the harness script right after the Reply button is clicked. Without it +# in the output, the failure happened before anything could reach Apple. +CLICKED = "__SP__clicked" + + +class ReplyNotSent(browser.BrowserError): + """The reply failed before the Reply button was clicked: nothing reached Apple.""" + + # Console UI labels, matched literally against the page text (pt-BR and en-US) REPLY_OPEN = ("Responda à equipe de revisão de apps", "Reply to App Review") REPLY_SEND = ("Responder", "Reply") @@ -91,7 +100,11 @@ def prepare_attachment(path: Path) -> Path: def reply(app_id: str, submission_id: str, text: str, attachments: list[Path]) -> str: - """Reply to App Review through the console box and verify the message landed in the thread.""" + """Reply to App Review through the console box and verify the message landed in the thread. + + Raises ReplyNotSent only when the failure provably happened before the click. + Any other error means the message may have reached Apple. + """ script = f""" import time, json TEXT = {json.dumps(text)} @@ -135,6 +148,7 @@ def reply(app_id: str, submission_id: str, text: str, attachments: list[Path]) - sent = js("(()=>{{const b=[...document.querySelectorAll('[role=dialog] button')].filter(b=>%s.includes(b.innerText.trim())).pop(); if(!b) return 'no button'; if(b.disabled) return 'disabled'; b.click(); return 'sent'}})()" % json.dumps(SEND)) if sent != 'sent': raise SystemExit('ERROR: not sent (' + sent + ')') +print({CLICKED!r}, flush=True) for _ in range(15): time.sleep(2) if js(COUNT) > before: break @@ -142,8 +156,20 @@ def reply(app_id: str, submission_id: str, text: str, attachments: list[Path]) - raise SystemExit('ERROR: the message did not appear in the thread after sending') print('__SP__ok') """ - out = browser.run_harness(script, timeout=600) + try: + out = browser.run_harness(script, timeout=600) + except subprocess.TimeoutExpired as exc: + partial = exc.stdout.decode(errors="replace") if isinstance(exc.stdout, bytes) else (exc.stdout or "") + if partial and CLICKED not in partial: + raise ReplyNotSent("Timed out before clicking Reply; nothing was sent.") from exc + raise browser.BrowserError("Timed out after clicking Reply; the message may have been sent.") from exc + except browser.BrowserError as exc: + # Only a failed script run carries its output; anything else may come after the click. + if str(exc).startswith(("browser-harness failed", "browser-harness not found")) and CLICKED not in str(exc): + erro = next((l for l in str(exc).splitlines() if l.startswith("ERROR")), str(exc)[-500:]) + raise ReplyNotSent(erro) from exc + raise if "__SP__ok" not in out: erro = next((l for l in out.splitlines() if l.startswith("ERROR")), out[-500:]) - raise browser.BrowserError(erro) + raise (browser.BrowserError if CLICKED in out else ReplyNotSent)(erro) return "sent" diff --git a/src/shipstores/server.py b/src/shipstores/server.py index 8a6b1cc..369f172 100644 --- a/src/shipstores/server.py +++ b/src/shipstores/server.py @@ -2,6 +2,7 @@ from __future__ import annotations +import hashlib import tempfile from collections.abc import Callable from pathlib import Path @@ -9,6 +10,7 @@ import httpx from fastmcp import FastMCP +from mcp.types import ToolAnnotations from . import apple, apple_console, apple_review, browser, data_safety, eas, play, play_console, signing from .config import ( @@ -51,6 +53,11 @@ _CORE_TOOLS = {"store_doctor", "store_audit_identity", "store_browser_session"} +# Tools whose docstring says "External action" change something in a store (or +# reach a person at Apple/Google). Clients that read MCP annotations can gate +# them without relying on the description text. +_EXTERNAL_ACTION = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True) + def _register_tool(function: Callable[..., Any]) -> Any: name = function.__name__ @@ -60,7 +67,8 @@ def _register_tool(function: Callable[..., Any]) -> Any: toolset = name.partition("_")[0] if toolset not in TOOLSETS - {"core"}: raise ValueError(f"Tool {name!r} does not belong to a known toolset.") - return mcp.tool(tags={toolset})(function) + external = "External action" in (function.__doc__ or "") + return mcp.tool(tags={toolset}, annotations=_EXTERNAL_ACTION if external else None)(function) # ---------------------------------------------------------------- diagnostics @@ -697,12 +705,40 @@ def apple_review_messages(app_id: str) -> dict[str, Any]: return {"app_id": app_id, "messages": messages, "total": len(messages)} +# Preview tokens already used to send a reply, so a repeated confirm cannot send twice. +_SENT_REPLY_TOKENS: set[str] = set() + + +def _reply_token(app_id: str, sub_id: str, text: str, files: list[Path]) -> str: + """Hash of everything that would be sent: the submission, the exact text and each attachment's bytes.""" + digest = hashlib.sha256() + for part in (app_id, sub_id, text): + digest.update(part.encode()) + digest.update(b"\0") + for path in files: + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1 << 20), b""): + digest.update(chunk) + digest.update(b"\0") + return digest.hexdigest()[:16] + + @_register_tool def apple_reply_review( - app_id: str, text: str, attachments: list[str] | None = None + app_id: str, text: str, attachments: list[str] | None = None, confirm_token: str = "" ) -> dict[str, Any]: """Reply to App Review on a rejected submission, with attachments. External action. + Two steps, because the reply goes to a person at Apple and cannot be edited + or taken back: + 1. Call without confirm_token. Nothing is sent: it validates the text and + attachments, converts videos, finds the rejected submission and returns a + preview plus a `confirm_token` (a hash of exactly what would be sent). + 2. Show the preview to the user. Only after an explicit yes, call again with + the same arguments and that confirm_token. If the text, an attachment or + the submission changed since the preview, the token no longer matches and + nothing is sent. A token can only send once. + For a "Guideline 2.1 - Information Needed" request: send the answers in `text` (up to 4000 characters) and the video recorded on the iPhone in `attachments`. HEVC video is converted to H.264 at 1920px before upload. Copy @@ -710,16 +746,55 @@ def apple_reply_review( Apple asks. Replying is not enough: the version stays Rejected until you resubmit it ("Update Review" on the version page, then resubmit). """ + if not text.strip(): + raise ValueError("The reply is empty.") if len(text) > 4000: raise ValueError(f"The reply has {len(text)} characters; the console limit is 4000.") - files = [] + originals = [] for item in attachments or []: path = Path(item).expanduser() if not path.exists(): raise FileNotFoundError(f"Attachment not found: {path}") - files.append(apple_review.prepare_attachment(path)) + originals.append(path) sub_id = _active_submission(app_id, ("UNRESOLVED_ISSUES",)) - apple_review.reply(app_id, sub_id, text, files) + token = _reply_token(app_id, sub_id, text, originals) + if not confirm_token: + files = [apple_review.prepare_attachment(path) for path in originals] + return { + "sent": False, + "preview": { + "review_submission_id": sub_id, + "text": text, + "characters": len(text), + "attachments": [str(f) for f in files], + }, + "confirm_token": token, + "next_step": ( + "Nothing was sent. Show this preview to the user; only after an explicit yes, " + "call apple_reply_review again with the same arguments and this confirm_token." + ), + } + if confirm_token in _SENT_REPLY_TOKENS: + raise ValueError("This reply was already sent with this confirm_token; nothing was sent again.") + if confirm_token != token: + raise ValueError( + "confirm_token does not match: the text, an attachment or the submission changed since " + "the preview. Nothing was sent. Call again without confirm_token for a new preview." + ) + files = [apple_review.prepare_attachment(path) for path in originals] + _SENT_REPLY_TOKENS.add(token) + try: + apple_review.reply(app_id, sub_id, text, files) + except apple_review.ReplyNotSent: + # Nothing reached Apple, so the same token may retry. + _SENT_REPLY_TOKENS.discard(token) + raise + except Exception as exc: + # Unknown outcome: keep the token burned so a retry cannot double-post. + raise RuntimeError( + f"{exc}\nThe reply may have reached Apple. Check with apple_review_messages " + "before sending anything again." + ) from exc return { "review_submission_id": sub_id, "sent": True, diff --git a/tests/test_reply_review.py b/tests/test_reply_review.py new file mode 100644 index 0000000..19c1c28 --- /dev/null +++ b/tests/test_reply_review.py @@ -0,0 +1,145 @@ +import asyncio +import subprocess +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + +from shipstores import server + + +class ReplyReviewConfirmTests(unittest.TestCase): + def setUp(self) -> None: + server._SENT_REPLY_TOKENS.clear() + self.submission = patch.object(server, "_active_submission", return_value="sub-1") + self.reply = patch.object(server.apple_review, "reply") + self.submission.start() + self.reply_mock = self.reply.start() + + def tearDown(self) -> None: + self.reply.stop() + self.submission.stop() + + def test_default_returns_preview_and_token_without_sending(self) -> None: + result = server.apple_reply_review("123", "Here is the demo video.") + self.reply_mock.assert_not_called() + self.assertFalse(result["sent"]) + self.assertEqual(result["preview"]["text"], "Here is the demo video.") + self.assertTrue(result["confirm_token"]) + + def test_confirm_with_matching_token_sends(self) -> None: + token = server.apple_reply_review("123", "Here is the demo video.")["confirm_token"] + result = server.apple_reply_review("123", "Here is the demo video.", confirm_token=token) + self.reply_mock.assert_called_once_with("123", "sub-1", "Here is the demo video.", []) + self.assertTrue(result["sent"]) + + def test_changed_text_after_preview_is_rejected(self) -> None: + token = server.apple_reply_review("123", "Here is the demo video.")["confirm_token"] + with self.assertRaises(ValueError): + server.apple_reply_review("123", "Something else entirely.", confirm_token=token) + self.reply_mock.assert_not_called() + + def test_changed_attachment_after_preview_is_rejected(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + note = Path(tmp) / "notes.pdf" + note.write_bytes(b"%PDF v1") + token = server.apple_reply_review("123", "See attached.", [str(note)])["confirm_token"] + note.write_bytes(b"%PDF v2") + with self.assertRaises(ValueError): + server.apple_reply_review("123", "See attached.", [str(note)], confirm_token=token) + self.reply_mock.assert_not_called() + + def test_changed_submission_after_preview_is_rejected(self) -> None: + token = server.apple_reply_review("123", "Hi")["confirm_token"] + with patch.object(server, "_active_submission", return_value="sub-2"): + with self.assertRaises(ValueError): + server.apple_reply_review("123", "Hi", confirm_token=token) + self.reply_mock.assert_not_called() + + def test_two_confirms_in_a_row_send_once(self) -> None: + token = server.apple_reply_review("123", "Hi")["confirm_token"] + server.apple_reply_review("123", "Hi", confirm_token=token) + with self.assertRaises(ValueError): + server.apple_reply_review("123", "Hi", confirm_token=token) + self.reply_mock.assert_called_once() + + def test_failure_before_send_allows_retry(self) -> None: + token = server.apple_reply_review("123", "Hi")["confirm_token"] + self.reply_mock.side_effect = [server.apple_review.ReplyNotSent("ERROR: the reply box did not open"), "sent"] + with self.assertRaises(server.apple_review.ReplyNotSent): + server.apple_reply_review("123", "Hi", confirm_token=token) + server.apple_reply_review("123", "Hi", confirm_token=token) + self.assertEqual(self.reply_mock.call_count, 2) + + def test_failure_after_send_keeps_token_burned(self) -> None: + token = server.apple_reply_review("123", "Hi")["confirm_token"] + self.reply_mock.side_effect = server.browser.BrowserError("ERROR: the message did not appear in the thread") + with self.assertRaises(RuntimeError): + server.apple_reply_review("123", "Hi", confirm_token=token) + with self.assertRaises(ValueError): + server.apple_reply_review("123", "Hi", confirm_token=token) + self.assertEqual(self.reply_mock.call_count, 1) + + def test_validation_runs_before_preview(self) -> None: + with self.assertRaises(ValueError): + server.apple_reply_review("123", "x" * 4001) + with self.assertRaises(ValueError): + server.apple_reply_review("123", " ") + with self.assertRaises(FileNotFoundError): + server.apple_reply_review("123", "See attached.", ["/nonexistent/video.mov"]) + self.reply_mock.assert_not_called() + + +class ReplyOutcomeTests(unittest.TestCase): + """apple_review.reply says "not sent" only when the click provably did not happen.""" + + def _reply(self, **harness): + with patch.object(server.apple_review.browser, "run_harness", **harness): + return server.apple_review.reply("123", "sub-1", "Hi", []) + + def test_script_error_before_click_is_not_sent(self) -> None: + error = server.browser.BrowserError("browser-harness failed (exit 1):\nERROR: the reply box did not open") + with self.assertRaises(server.apple_review.ReplyNotSent): + self._reply(side_effect=error) + + def test_script_error_after_click_may_be_sent(self) -> None: + error = server.browser.BrowserError( + "browser-harness failed (exit 1):\n__SP__clicked\nERROR: the message did not appear in the thread" + ) + with self.assertRaises(server.browser.BrowserError) as ctx: + self._reply(side_effect=error) + self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent) + + def test_timeout_after_click_may_be_sent(self) -> None: + timeout = subprocess.TimeoutExpired("browser-harness", 600, output="__SP__clicked\n") + with self.assertRaises(server.browser.BrowserError) as ctx: + self._reply(side_effect=timeout) + self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent) + + def test_timeout_without_output_may_be_sent(self) -> None: + with self.assertRaises(server.browser.BrowserError) as ctx: + self._reply(side_effect=subprocess.TimeoutExpired("browser-harness", 600)) + self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent) + + def test_other_errors_may_be_sent(self) -> None: + with self.assertRaises(server.browser.BrowserError) as ctx: + self._reply(side_effect=server.browser.BrowserError("Logged out of the Apple console")) + self.assertNotIsInstance(ctx.exception, server.apple_review.ReplyNotSent) + + +class ToolAnnotationTests(unittest.TestCase): + def test_external_action_tools_are_annotated(self) -> None: + tools = {t.name: t for t in asyncio.run(server.mcp.list_tools())} + for name in ("apple_reply_review", "apple_submit_for_review", "play_promote_release", "eas_submit"): + annotations = tools[name].annotations + self.assertIsNotNone(annotations, name) + self.assertTrue(annotations.destructiveHint, name) + self.assertFalse(annotations.readOnlyHint, name) + + def test_read_tools_are_not_flagged_destructive(self) -> None: + tools = {t.name: t for t in asyncio.run(server.mcp.list_tools())} + self.assertIsNone(tools["apple_review_messages"].annotations) + + +if __name__ == "__main__": + unittest.main()