mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/outlets/sheets.py

@@ -0,0 +1,169 @@
+"""A Google Sheets destination: each result is a row in "Mobster results",
+a sheet Mobster makes in your Google Drive."""
+
+import json
+import re
+from urllib.parse import quote, urlencode
+
+from . import connect, net
+from .kinds import Kind, again, careful, connection, flat
+from .webhook import USER_AGENT, Outcome
+
+SHEETS = "https://sheets.googleapis.com/v4/spreadsheets"
+DRIVE = "https://www.googleapis.com/drive/v3/files"
+TITLE = "Mobster results"
+LABEL = "Google Sheets"
+SHEET_ID = re.compile(r"[A-Za-z0-9_-]{20,200}")
+CELL_MAX = 50_000       # Google's limit for one cell's text
+
+
+def headers(token, body=False):
+    out = {"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT}
+    if body:
+        out["Content-Type"] = "application/json"
+    return out
+
+
+def refusal(status):
+    """Google's refusal as a sentence: what happened, then what to do."""
+    if status == 401:
+        return f"{LABEL} signed Mobster out. " + again(LABEL)
+    if status in (403, 404):
+        return (f"Mobster can't open {TITLE} any more: it was deleted, or Google took back Mobster's access. "
+                f"Connect {LABEL} again to make a new one.")
+    return f"Google answered {status}."
+
+
+def find_or_make(call, token):
+    """{"id", "title"}: the "Mobster results" sheet Mobster made before, else a new one. NetError, or ValueError."""
+    query = f"name = '{TITLE}' and mimeType = 'application/vnd.google-apps.spreadsheet' and trashed = false"
+    reply = call("GET", f"{DRIVE}?" + urlencode({"q": query, "fields": "files(id,name)", "orderBy": "createdTime",
+                                                  "pageSize": "1", "spaces": "drive"}), None, headers(token))
+    answer = reply.json_object()
+    if reply.status != 200 or answer is None:
+        raise ValueError(refusal(reply.status))
+    files = [item for item in answer.get("files") or () if isinstance(item, dict)
+             and isinstance(item.get("id"), str) and SHEET_ID.fullmatch(item["id"])]
+    if files:
+        return {"id": files[0]["id"], "title": TITLE}
+    sheet = {"properties": {"title": TITLE},
+             "sheets": [{"properties": {"title": "Results", "gridProperties": {"frozenRowCount": 1}}}]}
+    reply = call("POST", SHEETS, json.dumps(sheet).encode(), headers(token, body=True))
+    answer = reply.json_object()
+    made = (answer or {}).get("spreadsheetId")
+    if reply.status != 200 or not isinstance(made, str) or not SHEET_ID.fullmatch(made):
+        raise ValueError(f"Google didn't make the sheet ({reply.status}). Connect again.")
+    return {"id": made, "title": TITLE}
+
+
+def value(item):
+    """A cell: numbers and true/false as they are, anything else as text Google keeps as written (RAW)."""
+    if item is None:
+        return ""
+    if isinstance(item, bool) or (isinstance(item, (int, float)) and item == item and abs(item) != float("inf")):
+        return item
+    text = item if isinstance(item, str) else json.dumps(item, ensure_ascii=False)
+    return text[:CELL_MAX]
+
+
+class Stop(Exception):
+    """One try ends here, with ``outcome``."""
+
+    def __init__(self, outcome):
+        super().__init__(outcome.message)
+        self.outcome = outcome
+
+
+class Sheets(Kind):
+    id, label = "sheets", LABEL
+    example = "Sales sheet"
+    fields = ("connect",)
+    replay_safe = False
+    provider = "google-sheets"
+
+    def connected(self, call, tokens):
+        sheet = find_or_make(call, tokens["access_token"])
+        oauth = {key: item for key, item in tokens.items() if key != "kept"}
+        return {"credentials": {"oauth": oauth, "sheet": sheet}, "account": sheet["title"], "targets": None}
+
+    def setup(self, body, current=None):
+        if current is not None and "connect" not in body:
+            return {}
+        found = connection(body, self)["credentials"]
+        return {"hint": f"{LABEL} › {found['sheet']['title']}", "has_secret": True,
+                "config": {"spreadsheet": found["sheet"]["id"], "title": found["sheet"]["title"]},
+                "vault": {"url": None, "secret": None, "oauth": found["oauth"]}, "last_test": None}
+
+    @staticmethod
+    def _sheet(ctx):
+        sheet = ctx.destination["config"].get("spreadsheet")
+        if not sheet:
+            # A sheet saved before 15 Oct 2026 took rows through an Apps Script web app.
+            raise Stop(Outcome(False, False, None, "Mobster now adds rows itself, with no script. " + again(LABEL),
+                               unsent=True))
+        return f"{SHEETS}/{quote(sheet, safe='')}"
+
+    @staticmethod
+    def _call(ctx, method, url, data, token):
+        """One request that adds nothing (a read, or the header, written the same each time it's tried), with a token
+        that works: a 401 renews it once."""
+        for refresh in (False, True):
+            if refresh:
+                token = connect.access(ctx, LABEL, refresh=True)
+            try:
+                reply = ctx.call(method, url, data, headers(token, body=data is not None))
+            except net.NetError as error:
+                # Nothing this sends can add a row, so another try is safe even when this one may have arrived.
+                raise Stop(Outcome(False, error.retry, None, error.message, unsent=True)) from None
+            if reply.status == 401 and not refresh:
+                continue
+            if reply.status == 200:
+                return reply, token
+            raise Stop(Outcome(False, reply.status == 429 or reply.status >= 500, reply.status,
+                               refusal(reply.status), unsent=True))
+        raise Stop(Outcome(False, False, 401, refusal(401), unsent=True))
+
+    def _header(self, ctx, base, token):
+        reply, token = self._call(ctx, "GET", f"{base}/values/1:1?majorDimension=ROWS", None, token)
+        rows = (reply.json_object() or {}).get("values") or [[]]
+        return [str(name) for name in rows[0]], token
+
+    def send(self, ctx, body):
+        try:
+            base = self._sheet(ctx)
+            token = connect.access(ctx, LABEL)
+            header, token = self._header(ctx, base, token)
+            row = flat(body)
+            known = {name.casefold() for name in header}
+            missing = [name for name in row if name.casefold() not in known]
+            if missing:
+                header += missing
+                data = json.dumps({"values": [header]}, ensure_ascii=False).encode()
+                _reply, token = self._call(ctx, "PUT", f"{base}/values/A1?valueInputOption=RAW", data, token)
+        except (Stop, connect.NoToken) as error:
+            return error.outcome
+        by_name = {name.casefold(): item for name, item in row.items()}
+        data = json.dumps({"values": [[value(by_name.get(name.casefold())) for name in header]]},
+                          ensure_ascii=False).encode()
+        # RAW input, so text from a screen is never read as a formula.
+        url = f"{base}/values/A1:append?valueInputOption=RAW&insertDataOption=INSERT_ROWS"
+        reply, failed = careful(lambda: ctx.call("POST", url, data, headers(token, body=True)), TITLE)
+        if failed:
+            return failed
+        if reply.status == 200:
+            return Outcome(True, False, 200)
+        if reply.status == 429:
+            return Outcome(False, True, 429, "Google asked Mobster to wait.", unsent=True)
+        if reply.status >= 500:
+            return Outcome(False, False, reply.status, f"Google answered {reply.status}. Check {TITLE}, then resend "
+                                                       "if the row is missing.")
+        return Outcome(False, False, reply.status, refusal(reply.status), unsent=True)
+
+    def test(self, ctx):
+        """Reads the header: the sign-in and the sheet work. No row is added."""
+        try:
+            self._header(ctx, self._sheet(ctx), connect.access(ctx, LABEL))
+        except (Stop, connect.NoToken) as error:
+            return Outcome(False, False, error.outcome.status, error.outcome.message)
+        title = ctx.destination["config"].get("title") or TITLE
+        return Outcome(True, False, 200, f"Connected to {title}. Each result adds a row.")

mobile_agent/outlets/slack.py

@@ -0,0 +1,177 @@
+"""A Slack destination: each result is a message in one channel you picked, posted as you."""
+
+import json
+import re
+from urllib.parse import urlencode
+
+from ..api_errors import APIError
+from . import webhook
+from .kinds import Kind, again, careful, connection, target
+from .webhook import USER_AGENT, Outcome
+
+API = "https://slack.com/api"
+LABEL = "Slack"
+CHANNEL = re.compile(r"[CG][A-Z0-9]{2,30}")
+PAGES = 5                     # users.conversations pages of 200 read at Connect
+SAFE_LINK = re.compile(r"https://[A-Za-z0-9._~:/?#\[\]@!$'()*+,;=%&-]{1,500}")
+SECTION = 3000                # Block Kit's limit for a section's text
+STATUS = {"run.started": "Started", "needs_you": "Needs you in Mobster", "test": "Test"}
+RENEW = ("invalid_auth", "token_expired", "not_authed")
+SIGNED_OUT = ("token_revoked", "account_inactive", "user_removed_from_team", "team_disabled")
+NOT_HERE = {"channel_not_found": "the channel is gone", "is_archived": "the channel was archived",
+            "not_in_channel": "you're no longer in the channel", "restricted_action": "a workspace admin turned "
+            "posting there off", "cant_post": "you can't post in that channel"}
+TEST = "Mobster: this is a test. Results from your tasks will arrive here."
+
+
+def headers(token, body=False):
+    out = {"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT}
+    if body:
+        out["Content-Type"] = "application/json; charset=utf-8"
+    return out
+
+
+def refusal(error):
+    """Slack's ``error`` as a sentence: what happened, then what to do."""
+    if error in RENEW or error in SIGNED_OUT:
+        return "Slack signed Mobster out. Sign in to Slack again under Use in tasks in Settings › Connectors."
+    if error == "missing_scope":
+        return ("Your Slack sign-in can't do this: it needs chat:write, channels:read and groups:read. Sign in to "
+                "Slack again under Use in tasks.")
+    if error in NOT_HERE:
+        return f"Slack refused: {NOT_HERE[error]}. Pick another channel: " + again(LABEL)
+    return f"Slack refused ({str(error)[:60]})."
+
+
+def read(call, method, token, query=None):
+    """One Web API read: Slack's answer when ``ok``. NetError, or ValueError with Slack's refusal."""
+    reply = call("GET", f"{API}/{method}" + (f"?{urlencode(query)}" if query else ""), None, headers(token))
+    answer = reply.json_object()
+    if reply.status != 200 or answer is None:
+        raise ValueError(f"Slack answered {reply.status}. Try again.")
+    if answer.get("ok") is not True:
+        raise ValueError(refusal(answer.get("error")))
+    return answer
+
+
+def channels(call, token):
+    """The channels you're in, by name: [{"id", "name"}]."""
+    found, cursor = [], None
+    for _ in range(PAGES):
+        query = {"types": "public_channel,private_channel", "exclude_archived": "true", "limit": "200"}
+        if cursor:
+            query["cursor"] = cursor
+        answer = read(call, "users.conversations", token, query)
+        for item in answer.get("channels") or ():
+            if isinstance(item, dict) and isinstance(item.get("id"), str) and CHANNEL.fullmatch(item["id"]) \
+                    and isinstance(item.get("name"), str):
+                found.append({"id": item["id"], "name": "#" + item["name"][:80]})
+        cursor = (answer.get("response_metadata") or {}).get("next_cursor")
+        if not cursor:
+            break
+    return sorted(found, key=lambda item: item["name"])
+
+
+class Slack(Kind):
+    id, label = "slack", LABEL
+    example = "Team channel"
+    fields = ("connect", "target")
+    replay_safe = False
+    keychain = False
+
+    def connected(self, call, tokens):
+        token = tokens["access_token"]
+        team = read(call, "auth.test", token).get("team")
+        return {"credentials": {"connector": tokens["connector"]},
+                "account": team[:100] if isinstance(team, str) and team.strip() else None,
+                "targets": channels(call, token)}
+
+    def setup(self, body, current=None):
+        if current is not None and not ({"connect", "target"} & set(body)):
+            return {}
+        found = connection(body, self)
+        channel = target(found, body.get("target"), "a channel")
+        config = {"connector": found["credentials"]["connector"], "channel": channel["id"],
+                  "channelName": channel["name"]}
+        if found.get("account"):
+            config["workspace"] = found["account"]
+        return {"hint": f"Slack › {channel['name']}", "config": config, "last_test": None}
+
+    @staticmethod
+    def suite_message(body):
+        """A suite's message (testkit/notify.py): the title bold, one section of its lines, and a context line."""
+        report = body["report"]
+        title = webhook.slack_text(" ".join(str(report["title"]).split()))[:SECTION]
+        link = report.get("link")
+        safe = isinstance(link, str) and SAFE_LINK.fullmatch(link)
+        lines = [f"<{link.replace('&', '&amp;')}|Report>" if safe and line == f"Report: {link}"
+                 else webhook.slack_text(" ".join(str(line).split())) for line in report["lines"]]
+        text = "\n".join(lines)
+        budget = SECTION - len(title) - 3  # bold title and newline share this section
+        text = text if len(text) <= budget else text[:budget - 1] + "…"
+        return {"text": title, "unfurl_links": False, "unfurl_media": False, "link_names": False,
+                "blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": f"*{title}*\n{text}"}},
+                           {"type": "context", "elements": [{"type": "mrkdwn", "text": "Checks run by Mobster"}]}]}
+
+    @staticmethod
+    def message(body):
+        """Block Kit: the line as one section, and how the task ended as a quiet context line. &, < and > are escaped:
+        text from a screen can't mention @channel or a person, or make a link."""
+        text = webhook.slack_text(" ".join(str(body.get("text") or "Mobster").split()))
+        text = text if len(text) <= SECTION else text[:SECTION - 1] + "…"
+        kind = body.get("type")
+        if kind == "tests.finished":
+            return Slack.suite_message(body)
+        status = STATUS.get(kind) or ("Done" if body.get("status") in webhook.DONE else "Couldn't finish")
+        flow = (body.get("workflow") or {}).get("name")
+        context = webhook.slack_text(f"{status} in Mobster" + (f", from {flow}" if flow else ""))
+        return {"text": text, "unfurl_links": False, "unfurl_media": False, "link_names": False,
+                "blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": text}},
+                           {"type": "context", "elements": [{"type": "mrkdwn", "text": context}]}]}
+
+    def _post(self, ctx, message):
+        config = ctx.destination["config"]
+        if not config.get("channel") or not config.get("connector"):
+            # A Slack destination saved before 15 Oct 2026 posted through an incoming webhook.
+            return Outcome(False, False, None, "Mobster now posts as you, in a channel you pick. " + again(LABEL),
+                           unsent=True)
+        connectors = ctx.connectors()
+        if connectors is None:
+            return Outcome(False, True, None, "Mobster's connectors aren't running. Restart Mobster, then resend.",
+                           unsent=True)
+        from ..connectors import client as mcp
+        data = json.dumps({**message, "channel": config["channel"]}, ensure_ascii=False).encode()
+        for renew in (False, True):
+            try:
+                token = connectors.bearer(config["connector"], refresh=renew)
+            except APIError:
+                return Outcome(False, False, None, "Slack was disconnected from Mobster. Connect Slack under Use in "
+                               "tasks, then connect this destination again.", unsent=True)
+            except mcp.AuthNeeded:
+                return Outcome(False, False, None, refusal("token_revoked"), unsent=True)
+            except mcp.NotSent as error:
+                return Outcome(False, True, None, error.message, unsent=True)
+            reply, failed = careful(lambda: ctx.call("POST", f"{API}/chat.postMessage", data,
+                                                     headers(token, body=True)), "the channel")
+            if failed:
+                return failed
+            if reply.status == 429:
+                return Outcome(False, True, 429, "Slack asked Mobster to wait.", unsent=True)
+            if reply.status >= 500:
+                return Outcome(False, False, reply.status, f"Slack answered {reply.status}. Check the channel, then "
+                                                           "resend if the message is missing.")
+            answer = reply.json_object() or {}
+            if reply.status == 200 and answer.get("ok") is True:
+                return Outcome(True, False, 200)
+            error = answer.get("error")
+            if error in RENEW and not renew:
+                continue
+            # Slack answered ok: false, so it posted nothing.
+            return Outcome(False, error == "ratelimited", reply.status, refusal(error), unsent=True)
+        return Outcome(False, False, 401, refusal("invalid_auth"), unsent=True)
+
+    def send(self, ctx, body):
+        return self._post(ctx, self.message(body))
+
+    def test(self, ctx):
+        return self._post(ctx, self.message({"type": "test", "text": TEST}))

mobile_agent/outlets/store.py

@@ -0,0 +1,194 @@
+"""Outlets' state in the run journal: schema ``outlets`` v2, in the same private SQLite file (0600)."""
+
+import json
+import sqlite3
+
+from ..journal import JournalError
+
+SCHEMA = "outlets"
+VERSION = 3
+MAX_DESTINATIONS = 50
+# Deliveries kept: the newest, for the runs History still has.
+MAX_DELIVERIES = 2000
+STATUSES = ("sending", "sent", "failed")
+EVENTS = ("run.finished", "run.started", "needs_you")
+LOG_MAX = 50                     # deliveries one destination's log shows
+
+
+def migrate(connection, from_version):
+    """journal.register_schema's migration: v0 -> v1 creates the tables; v1 -> v2 adds the kinds."""
+    if from_version < 1:
+        connection.execute("""CREATE TABLE IF NOT EXISTS outlet_destinations (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            hint TEXT NOT NULL,
+            has_secret INTEGER NOT NULL DEFAULT 0,
+            screenshot INTEGER NOT NULL DEFAULT 0,
+            last_test TEXT,
+            created_at REAL NOT NULL,
+            updated_at REAL NOT NULL)""")
+        connection.execute("""CREATE TABLE IF NOT EXISTS outlet_deliveries (
+            id TEXT PRIMARY KEY,
+            run_id TEXT NOT NULL,
+            destination_id TEXT NOT NULL,
+            destination_name TEXT NOT NULL,
+            status TEXT NOT NULL CHECK (status IN ('sending', 'sent', 'failed')),
+            attempts INTEGER NOT NULL DEFAULT 0,
+            http_status INTEGER,
+            error TEXT,
+            next_at REAL,
+            created_at REAL NOT NULL,
+            updated_at REAL NOT NULL)""")
+        connection.execute("CREATE INDEX IF NOT EXISTS outlet_deliveries_run ON outlet_deliveries(run_id)")
+    if from_version < 2:
+        columns = {row[1] for row in connection.execute("PRAGMA table_info(outlet_destinations)")}
+        if "kind" not in columns:
+            connection.execute("ALTER TABLE outlet_destinations ADD COLUMN kind TEXT NOT NULL DEFAULT 'webhook'")
+        if "config" not in columns:
+            connection.execute("ALTER TABLE outlet_destinations ADD COLUMN config TEXT")
+        if "inflight_at" not in {row[1] for row in connection.execute("PRAGMA table_info(outlet_deliveries)")}:
+            connection.execute("ALTER TABLE outlet_deliveries ADD COLUMN inflight_at REAL")
+    if from_version < 3:
+        columns = {row[1] for row in connection.execute("PRAGMA table_info(outlet_deliveries)")}
+        if "event" not in columns:
+            connection.execute("ALTER TABLE outlet_deliveries ADD COLUMN event TEXT NOT NULL DEFAULT 'run.finished'")
+        if "payload" not in columns:
+            connection.execute("ALTER TABLE outlet_deliveries ADD COLUMN payload TEXT")
+        connection.execute("CREATE INDEX IF NOT EXISTS outlet_deliveries_destination "
+                           "ON outlet_deliveries(destination_id, created_at)")
+
+
+DESTINATION_COLUMNS = ("id", "name", "hint", "has_secret", "screenshot", "last_test", "created_at", "updated_at",
+                       "kind", "config")
+DELIVERY_COLUMNS = ("id", "run_id", "destination_id", "destination_name", "status", "attempts", "http_status", "error",
+                    "next_at", "created_at", "updated_at", "inflight_at", "event", "payload")
+
+
+def _destination(row):
+    if row is None:
+        return None
+    value = dict(zip(DESTINATION_COLUMNS, row))
+    value["has_secret"], value["screenshot"] = bool(value["has_secret"]), bool(value["screenshot"])
+    for key in ("last_test", "config"):
+        try:
+            value[key] = json.loads(value[key]) if value[key] else None
+        except ValueError:
+            value[key] = None
+    value["kind"] = value["kind"] or "webhook"
+    value["config"] = value["config"] if isinstance(value["config"], dict) else {}
+    return value
+
+
+def _delivery(row):
+    if row is None:
+        return None
+    value = dict(zip(DELIVERY_COLUMNS, row))
+    value["event"] = value["event"] or "run.finished"
+    try:
+        value["payload"] = json.loads(value["payload"]) if value["payload"] else None
+    except ValueError:
+        value["payload"] = None
+    return value
+
+
+class OutletStore:
+    def __init__(self, journal):
+        self.journal = journal
+
+    def _read(self, sql, args=()):
+        with self.journal.lock:
+            if self.journal.connection is None:
+                raise JournalError("The run journal is closed")
+            try:
+                return self.journal.connection.execute(sql, args).fetchall()
+            except sqlite3.Error:
+                raise JournalError("Mobster could not read its saved destinations") from None
+
+    def destinations(self):
+        cols = ", ".join(DESTINATION_COLUMNS)
+        return [_destination(row) for row in self._read(f"SELECT {cols} FROM outlet_destinations "
+                                                        "ORDER BY created_at, rowid")]
+
+    def destination(self, destination_id):
+        cols = ", ".join(DESTINATION_COLUMNS)
+        rows = self._read(f"SELECT {cols} FROM outlet_destinations WHERE id=?", (destination_id,))
+        return _destination(rows[0]) if rows else None
+
+    def count(self):
+        return self._read("SELECT count(*) FROM outlet_destinations")[0][0]
+
+    def add_destination(self, row):
+        with self.journal.transaction() as connection:
+            connection.execute(f"INSERT INTO outlet_destinations({', '.join(DESTINATION_COLUMNS)}) "
+                               f"VALUES ({', '.join('?' * len(DESTINATION_COLUMNS))})",
+                               [row["id"], row["name"], row["hint"], int(bool(row["has_secret"])),
+                                int(bool(row["screenshot"])), None, row["created_at"], row["updated_at"],
+                                row.get("kind") or "webhook", json.dumps(row.get("config") or {})])
+        return self.destination(row["id"])
+
+    def update_destination(self, destination_id, **changes):
+        allowed = {"name", "hint", "has_secret", "screenshot", "last_test", "updated_at", "config"}
+        if set(changes) - allowed:
+            raise ValueError("Unknown destination field")
+        values = []
+        for key, value in changes.items():
+            if key in ("has_secret", "screenshot"):
+                value = int(bool(value))
+            elif key in ("last_test", "config"):
+                value = json.dumps(value) if value is not None else None
+            values.append(value)
+        if values:
+            with self.journal.transaction() as connection:
+                connection.execute(f"UPDATE outlet_destinations SET {', '.join(f'{k}=?' for k in changes)} WHERE id=?",
+                                   [*values, destination_id])
+        return self.destination(destination_id)
+
+    def delete_destination(self, destination_id):
+        with self.journal.transaction() as connection:
+            connection.execute("DELETE FROM outlet_destinations WHERE id=?", (destination_id,))
+
+    def add_delivery(self, row):
+        with self.journal.transaction() as connection:
+            connection.execute(f"INSERT INTO outlet_deliveries({', '.join(DELIVERY_COLUMNS)}) "
+                               f"VALUES ({', '.join('?' * len(DELIVERY_COLUMNS))})",
+                               [json.dumps(row["payload"], ensure_ascii=False) if column == "payload" and
+                                row.get("payload") is not None else
+                                (row.get(column) or "run.finished") if column == "event" else row.get(column)
+                                for column in DELIVERY_COLUMNS])
+            excess = connection.execute("SELECT count(*) FROM outlet_deliveries").fetchone()[0] - MAX_DELIVERIES
+            if excess > 0:
+                connection.execute("DELETE FROM outlet_deliveries WHERE rowid IN (SELECT rowid FROM outlet_deliveries "
+                                   "WHERE status != 'sending' ORDER BY created_at LIMIT ?)", (excess,))
+        return self.delivery(row["id"])
+
+    def delivery(self, delivery_id):
+        rows = self._read(f"SELECT {', '.join(DELIVERY_COLUMNS)} FROM outlet_deliveries WHERE id=?", (delivery_id,))
+        return _delivery(rows[0]) if rows else None
+
+    def deliveries_for(self, run_id):
+        return [_delivery(row) for row in self._read(
+            f"SELECT {', '.join(DELIVERY_COLUMNS)} FROM outlet_deliveries WHERE run_id=? ORDER BY created_at, rowid",
+            (run_id,))]
+
+    def deliveries_to(self, destination_id, limit=LOG_MAX):
+        """A destination's newest deliveries first: its delivery log."""
+        return [_delivery(row) for row in self._read(
+            f"SELECT {', '.join(DELIVERY_COLUMNS)} FROM outlet_deliveries WHERE destination_id=? "
+            "ORDER BY created_at DESC, rowid DESC LIMIT ?", (destination_id, max(1, min(int(limit), LOG_MAX))))]
+
+    def pending(self):
+        return [_delivery(row) for row in self._read(
+            f"SELECT {', '.join(DELIVERY_COLUMNS)} FROM outlet_deliveries WHERE status='sending' ORDER BY next_at")]
+
+    def update_delivery(self, delivery_id, **changes):
+        allowed = {"status", "attempts", "http_status", "error", "next_at", "updated_at", "inflight_at"}
+        if set(changes) - allowed:
+            raise ValueError("Unknown delivery field")
+        with self.journal.transaction() as connection:
+            connection.execute(f"UPDATE outlet_deliveries SET {', '.join(f'{k}=?' for k in changes)} WHERE id=?",
+                               [*changes.values(), delivery_id])
+        return self.delivery(delivery_id)
+
+    def forget_run(self, run_id):
+        with self.journal.transaction() as connection:
+            connection.execute("DELETE FROM outlet_deliveries WHERE run_id=?", (run_id,))

mobile_agent/outlets/vault.py

@@ -0,0 +1,80 @@
+"""Where a destination's address, secret and token live: one generic password per destination in the login Keychain,
+readable only by Mobster's own programs (keychain_acl.py), as remote/keychain.py keeps Mobster Remote's device key."""
+
+import base64
+import json
+import re
+
+from ..connectors import keystore
+
+SERVICE = "app.mobster.desktop.outlets"
+ENV = "MOBSTER_OUTLETS_KEYCHAIN"
+ACCOUNT = re.compile(r"destination:[0-9a-f]{12}")
+WORD = re.compile(r"[A-Za-z0-9_-]{1,8000}")
+VaultError = keystore.VaultError
+
+
+def account_for(destination_id):
+    account = f"destination:{destination_id}"
+    if not ACCOUNT.fullmatch(account):
+        raise ValueError("A destination's id is 12 hex characters")
+    return account
+
+
+EXTRA = {"token": str, "to": str, "oauth": dict}
+
+
+def encode(url, secret, extra=None):
+    item = {"url": url, "secret": secret or None}
+    for key, kind in EXTRA.items():
+        if isinstance((extra or {}).get(key), kind) and extra[key]:
+            item[key] = extra[key]
+    raw = json.dumps(item, separators=(",", ":")).encode()
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def decode(word):
+    """{"url", "secret", "token"?, "to"?, "oauth"?}: ``url`` and ``secret`` may be None (a Notion, Sheets or email
+    destination)."""
+    try:
+        raw = base64.urlsafe_b64decode(word + "=" * (-len(word) % 4))
+        value = json.loads(raw)
+    except (ValueError, TypeError):
+        raise VaultError("Mobster couldn't read a saved destination") from None
+    kinds = {"url": str, **EXTRA}
+    if not isinstance(value, dict) or not any(isinstance(value.get(key), kind) and value[key]
+                                              for key, kind in kinds.items()):
+        raise VaultError("Mobster couldn't read a saved destination")
+    out = {"url": None, "secret": None}
+    for key, kind in {"url": str, "secret": str, **EXTRA}.items():
+        found = value.get(key)
+        if isinstance(found, kind) and found:
+            out[key] = found
+    return out
+
+
+class Vault:
+    """``put(id, url, secret, extra)``, ``get(id) -> {"url", "secret", ...} | None`` and ``delete(id)`` over
+    a raw store."""
+
+    def put(self, destination_id, url, secret, extra=None):
+        self._set(account_for(destination_id), encode(url, secret, extra))
+
+    def get(self, destination_id):
+        word = self._get(account_for(destination_id))
+        return decode(word) if word else None
+
+    def delete(self, destination_id):
+        self._delete(account_for(destination_id))
+
+
+class FileVault(keystore.FileStore, Vault):
+    files = "destinations"
+
+
+class KeychainVault(keystore.KeychainStore, Vault):
+    service, noun, word = SERVICE, "destination", WORD
+
+
+def backend():
+    return keystore.backend(ENV, FileVault, KeychainVault)