mkit-cli 0.3.1__py3-none-any.whl

mkit/aso.py

@@ -0,0 +1,359 @@
+"""Search rank and keyword winnability, read from Play's public web pages.
+
+There is no official API for search rank. This fetches the same search page
+a visitor sees (play.google.com/store/search, per market) and finds the app's
+position; it is a measurement, not a guarantee, and results vary by device and
+account. Keep request volume modest.
+
+Keywords file ([aso] keywords in mkit.toml), TOML:
+
+    [[market]]
+    lang = "en"          # label only
+    hl = "en_US"         # Play UI language
+    gl = "US"            # country
+    keywords = ["shopping list", "grocery list"]
+
+A JSON list of {"kw", "hl", "gl", "lang"} is accepted too. Each run is saved
+as results-YYYYMMDD.json beside the keywords file (or [aso] results_dir), and
+compared with the previous run.
+"""
+import json
+import math
+import re
+import threading
+import time
+import tomllib
+import urllib.parse
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from datetime import date, timedelta
+
+from . import output
+from .errors import UsageError
+
+UA = ('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 '
+      '(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36')
+_DETAILS = re.compile(r'/store/apps/details\?id=([A-Za-z0-9_.]+)')
+_NUM = {'K': 1e3, 'M': 1e6, 'B': 1e9}
+
+
+def load_keywords(project):
+    path = project.path('aso.keywords')
+    if not path or not path.is_file():
+        raise UsageError(f'keywords file not found ({path or "set keywords under [aso]"})', code='NO_KEYWORDS')
+    if path.suffix == '.json':
+        items = json.loads(path.read_text(encoding='utf-8'))
+        return [(k['kw'], k['hl'], k['gl'], k.get('lang', k['hl'])) for k in items], path
+    with open(path, 'rb') as f:
+        data = tomllib.load(f)
+    items = []
+    for m in data.get('market', []):
+        for kw in m.get('keywords', []):
+            items.append((kw, m['hl'], m['gl'], m.get('lang', m['hl'])))
+    return items, path
+
+
+def load_markets(project):
+    """The keywords file's markets, for `aso research`: each with its seeds
+    (the words autocomplete is asked about; the tracked keywords when none are
+    given) and its topic (a found phrase must hold one of these words)."""
+    path = project.path('aso.keywords')
+    if not path or not path.is_file() or path.suffix != '.toml':
+        raise UsageError(f'keywords file not found or not TOML ({path or "set keywords under [aso]"})',
+                         code='NO_KEYWORDS')
+    with open(path, 'rb') as f:
+        data = tomllib.load(f)
+    markets = []
+    for m in data.get('market', []):
+        seeds = m.get('seeds') or m.get('keywords', [])
+        topic = m.get('topic') or sorted({w for s in seeds for w in s.lower().split() if len(w) > 2})
+        markets.append({'lang': m.get('lang', m['hl']), 'hl': m['hl'], 'gl': m['gl'],
+                        'seeds': list(seeds), 'topic': [t.lower() for t in topic],
+                        'keywords': list(m.get('keywords', []))})
+    return markets, path
+
+
+def results_dir(project, keywords_path):
+    return project.path('aso.results_dir') or keywords_path.parent
+
+
+def _fetch(url, lang='en-US'):
+    for attempt in range(3):
+        try:
+            req = urllib.request.Request(url, headers={'User-Agent': UA, 'Accept-Language': lang + ',en;q=0.5'})
+            return urllib.request.urlopen(req, timeout=45).read().decode('utf-8', 'ignore')
+        except Exception:
+            if attempt == 2:
+                return None
+            time.sleep(2 + attempt * 3)
+
+
+def _search(word, hl, gl):
+    url = f'https://play.google.com/store/search?q={urllib.parse.quote(word)}&c=apps&hl={hl}&gl={gl}'
+    html = _fetch(url, hl.replace('_', '-'))
+    if html is None:
+        return None
+    seen = []
+    for i in _DETAILS.findall(html):
+        if i not in seen:
+            seen.append(i)
+    return seen
+
+
+def rank(package, items, workers=6):
+    out = output.out
+    done = [0]
+    lock = threading.Lock()
+
+    def one(item):
+        word, hl, gl, lang = item
+        found = _search(word, hl, gl)
+        with lock:
+            done[0] += 1
+            out.upload(done[0] / len(items) * 100)
+        if found is None:
+            return {'kw': word, 'lang': lang, 'gl': gl, 'pos': None, 'total': 0, 'error': 'fetch failed'}
+        return {'kw': word, 'lang': lang, 'gl': gl, 'pos': found.index(package) + 1 if package in found else None,
+                'total': len(found)}
+
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        return list(ex.map(one, items))
+
+
+def _to_int(s):
+    s = s.replace('+', '').replace(',', '').replace('.', '').strip()
+    if s and s[-1] in _NUM:
+        return int(float(s[:-1]) * _NUM[s[-1]])
+    try:
+        return int(s)
+    except ValueError:
+        return 0
+
+
+def score(package, items, workers=6):
+    """For each keyword, how beatable page one is: the install count of the
+    weakest of the top five apps. Under ~10k installs, a new app can get in."""
+    cache, lock = {}, threading.Lock()
+
+    def downloads(pkg):
+        with lock:
+            if pkg in cache:
+                return cache[pkg]
+        html = _fetch(f'https://play.google.com/store/apps/details?id={pkg}&hl=en_US&gl=US') or ''
+        m = re.search(r'<div class="ClM7O">([0-9.,]+[KMB]?\+?)</div><div class="g1rdde">Downloads', html)
+        t = re.search(r'<h1[^>]*><span[^>]*>(.*?)</span>', html)
+        info = {'installs': _to_int(m.group(1)) if m else 0, 'label': m.group(1) if m else '?',
+                'title': re.sub('<[^>]+>', '', t.group(1)) if t else pkg}
+        with lock:
+            cache[pkg] = info
+        return info
+
+    def one(item):
+        word, hl, gl, lang = item
+        found = _search(word, hl, gl) or []
+        top = [dict(downloads(p), package=p) for p in found[:5]]
+        counts = [t['installs'] for t in top]
+        return {'kw': word, 'lang': lang, 'gl': gl,
+                'pos': found.index(package) + 1 if package in found else None,
+                'weakest': min(counts) if counts else 0, 'strongest': max(counts) if counts else 0,
+                'top5': [{'title': t['title'][:40], 'installs': t['label']} for t in top]}
+
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        results = list(ex.map(one, items))
+    return sorted(results, key=lambda r: r['weakest'])
+
+
+# ------------------------------------------------------------------ research
+
+_pace_lock = threading.Lock()
+_last_request = [0.0]
+PACE = 0.35   # seconds between requests: research makes thousands
+
+
+def _paced(fn, *a):
+    with _pace_lock:
+        wait = PACE - (time.time() - _last_request[0])
+        if wait > 0:
+            time.sleep(wait)
+        _last_request[0] = time.time()
+    return fn(*a)
+
+
+def _post(url, body, lang):
+    for attempt in range(3):
+        try:
+            req = urllib.request.Request(url, data=body, headers={
+                'User-Agent': UA, 'Accept-Language': lang + ',en;q=0.5',
+                'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'})
+            return urllib.request.urlopen(req, timeout=45).read().decode('utf-8', 'ignore')
+        except Exception:
+            if attempt == 2:
+                return None
+            time.sleep(2 + attempt * 3)
+
+
+def suggest(term, hl, gl):
+    """Play's own search autocomplete for `term`: the phrases people type,
+    most typed first. The same call the Play website makes as you type."""
+    inner = json.dumps([[None, [term], [10], [2], 4]])
+    body = urllib.parse.urlencode({'f.req': json.dumps([[['IJ4APc', inner, None, 'generic']]])}).encode()
+    raw = _paced(_post, f'https://play.google.com/_/PlayStoreUi/data/batchexecute?rpcids=IJ4APc'
+                        f'&hl={hl}&gl={gl}&authuser&soc-app=121&soc-platform=1&soc-device=1',
+                 body, hl.replace('_', '-'))
+    try:
+        data = json.loads(raw[raw.index('['):])
+        payload = json.loads(data[0][2])
+        return [s[0].lower() for s in payload[0][0]] if payload and payload[0] else []
+    except (TypeError, ValueError, IndexError):
+        return []
+
+
+def demand(phrase, hl, gl, suggest_fn=None):
+    """How much people type `phrase`: 1.0 when autocomplete offers it after
+    two letters, falling towards 0 the more letters it takes, 0 when never
+    offered. Returns (demand, letters needed or None)."""
+    suggest_fn = suggest_fn or suggest
+    n = len(phrase)
+    for k in list(range(2, n, 2)) + [n]:
+        if phrase in suggest_fn(phrase[:k], hl, gl):
+            return round(1 - (k - 2) / max(n - 1, 1), 2), k
+    return 0.0, None
+
+
+def opportunity(demand_value, median_installs, in_title):
+    """Demand a new app can reach: discounted by how big page one is (median
+    of the top five's installs, on a log scale) and by how many of those five
+    carry the phrase in their title. 0 to 100."""
+    ease = 1 / math.log10(median_installs + 10)
+    return round(demand_value * ease * (1 - 0.12 * in_title) * 100, 1)
+
+
+def research(package, markets, workers=3, *, suggest_fn=None, search_fn=None, details_fn=None,
+             progress=None):
+    """Finds phrases through each market's seeds and scores every one.
+
+    A seed is asked about alone and with each letter after it ("grocery list
+    a", "grocery list b", ...), which is how autocomplete gives up its long
+    tail. Phrases of one word, or without a topic word, are dropped. The
+    tracked keywords are always scored, found or not."""
+    suggest_fn, search_fn = suggest_fn or suggest, search_fn or (lambda w, hl, gl: _paced(_search, w, hl, gl))
+    cache, lock = {}, threading.Lock()
+
+    def details(pkg):
+        with lock:
+            if pkg in cache:
+                return cache[pkg]
+        info = details_fn(pkg) if details_fn else _details(pkg)
+        with lock:
+            cache[pkg] = info
+        return info
+
+    results = []
+    for m in markets:
+        hl, gl = m['hl'], m['gl']
+        found = set(k.lower() for k in m['keywords'])
+        for seed in m['seeds']:
+            tails = [seed] + ([f'{seed} {c}' for c in 'abcdefghijklmnopqrstuvwxyz'] if seed.isascii() else [])
+            for q in tails:
+                for s in suggest_fn(q, hl, gl):
+                    if len(s.split()) >= 2 and any(t in s for t in m['topic']):
+                        found.add(s)
+        phrases = sorted(found)
+        done = [0]
+
+        def one(phrase, m=m, phrases=phrases, done=done):
+            d, letters = demand(phrase, m['hl'], m['gl'], suggest_fn)
+            apps = search_fn(phrase, m['hl'], m['gl']) or []
+            top = [dict(details(p), package=p) for p in apps[:5]]
+            words = [w for w in phrase.split() if len(w) > 2]
+            in_title = sum(1 for t in top if all(w in t['title'].lower() for w in words))
+            counts = sorted(t['installs'] for t in top) or [0]
+            with lock:
+                done[0] += 1
+                if progress:
+                    progress(done[0], len(phrases), f'{m["gl"]} {phrase}')
+            return {'kw': phrase, 'lang': m['lang'], 'gl': m['gl'], 'demand': d, 'letters': letters,
+                    'median_top5': counts[len(counts) // 2], 'weakest_top5': counts[0],
+                    'in_title': in_title, 'pos': apps.index(package) + 1 if package in apps else None,
+                    'tracked': phrase in {k.lower() for k in m['keywords']},
+                    'score': opportunity(d, counts[len(counts) // 2], in_title),
+                    'top5': [{'title': t['title'][:40], 'installs': t['label']} for t in top]}
+
+        with ThreadPoolExecutor(max_workers=workers) as ex:
+            results += sorted(ex.map(one, phrases), key=lambda r: -r['score'])
+    return results
+
+
+def _details(pkg):
+    html = _paced(_fetch, f'https://play.google.com/store/apps/details?id={pkg}&hl=en_US&gl=US') or ''
+    m = re.search(r'<div class="ClM7O">([0-9.,]+[KMB]?\+?)</div><div class="g1rdde">Downloads', html)
+    t = re.search(r'<h1[^>]*><span[^>]*>(.*?)</span>', html)
+    return {'installs': _to_int(m.group(1)) if m else 0, 'label': m.group(1) if m else '?',
+            'title': re.sub('<[^>]+>', '', t.group(1)) if t else pkg}
+
+
+# ------------------------------------------------------------------ impact
+
+def impact(daily, since, days, before_ranks, after_ranks):
+    """What a listing change did: store visitors and acquisitions per day in
+    the `days` before `since` against the `days` from it, and the keywords
+    gained and lost between the rank scans either side.
+
+    daily: {date 'YYYY-MM-DD': (visitors, acquisitions)}; a day with no row
+    counts as zero. *_ranks: {(kw, gl): position or None}."""
+    start = date.fromisoformat(since)
+    last = max((date.fromisoformat(d) for d in daily), default=start)
+
+    def window(first, count):
+        dates = [first + timedelta(days=i) for i in range(count)]
+        dates = [d for d in dates if d <= last]
+        v = sum(daily.get(d.isoformat(), (0, 0))[0] for d in dates)
+        a = sum(daily.get(d.isoformat(), (0, 0))[1] for d in dates)
+        n = len(dates)
+        return {'days': n, 'visitors': v, 'acquisitions': a,
+                'visitors_per_day': round(v / n, 1) if n else None,
+                'conversion': round(a / v * 100, 1) if v else None}
+
+    before = window(start - timedelta(days=days), days)
+    after = window(start, days)
+    keys = set(before_ranks) & set(after_ranks)
+    gained = sorted((k for k in keys if after_ranks[k] and not before_ranks[k]), key=lambda k: after_ranks[k])
+    lost = sorted(k for k in keys if before_ranks[k] and not after_ranks[k])
+    moved = sorted(((k, before_ranks[k], after_ranks[k]) for k in keys
+                    if before_ranks[k] and after_ranks[k] and before_ranks[k] != after_ranks[k]),
+                   key=lambda x: x[2] - x[1])
+    return {'since': since, 'before': before, 'after': after,
+            'ranked_before': sum(1 for k in keys if before_ranks[k]),
+            'ranked_after': sum(1 for k in keys if after_ranks[k]),
+            'gained': [{'kw': k[0], 'gl': k[1], 'pos': after_ranks[k]} for k in gained],
+            'lost': [{'kw': k[0], 'gl': k[1], 'was': before_ranks[k]} for k in lost],
+            'moved': [{'kw': k[0], 'gl': k[1], 'from': a, 'to': b} for k, a, b in moved]}
+
+
+def scan_around(folder, prefix, since):
+    """The last rank scan before `since` and the latest one from it on."""
+    scans = sorted(folder.glob(f'{prefix}-*.json'))
+    tag = since.replace('-', '')
+    before = [p for p in scans if p.stem.split('-')[-1] < tag]
+    after = [p for p in scans if p.stem.split('-')[-1] >= tag]
+
+    def ranks(p):
+        return {(r['kw'], r['gl']): r.get('pos') for r in json.loads(p.read_text(encoding='utf-8'))}
+
+    return (before[-1] if before else None, ranks(before[-1]) if before else {},
+            after[-1] if after else None, ranks(after[-1]) if after else {})
+
+
+def save(folder, prefix, results):
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / f'{prefix}-{date.today():%Y%m%d}.json'
+    path.write_text(json.dumps(results, ensure_ascii=False, indent=1), encoding='utf-8')
+    return path
+
+
+def previous(folder, prefix, current):
+    older = sorted(p for p in folder.glob(f'{prefix}-*.json') if p != current)
+    if not older:
+        return None, {}
+    data = json.loads(older[-1].read_text(encoding='utf-8'))
+    return older[-1], {(r['kw'], r['gl']): r.get('pos') for r in data}

mkit/cli.py

@@ -0,0 +1,176 @@
+"""Entry point: parse, load the project, run one command, report, exit.
+
+Global flags work before or after the command name:
+
+    --json / --human     force the output mode (default: human at a terminal,
+                         JSON anywhere else)
+    --project PATH       the app folder, instead of searching up from here
+    --yes --confirm PKG  approve a publish-class command without a prompt
+    --dry-run            do everything except the change itself
+    --strict             a skipped pipeline step is a failure, not a warning
+    --no-color
+"""
+import argparse
+import sys
+import traceback
+from dataclasses import dataclass, field
+
+from . import __version__, config, output
+from .errors import FAILED, INTERRUPTED, MkitError, UsageError
+from .registry import GROUPS, REGISTRY
+from .secrets import Secrets
+
+
+@dataclass
+class Context:
+    out: object
+    project: object = None
+    secrets: Secrets = None
+    command: str = ''
+    yes: bool = False
+    confirm: str | None = None
+    dry_run: bool = False
+    strict: bool = False
+    exit_code: int = 0
+    extra: dict = field(default_factory=dict)
+
+    def require(self, feature):
+        """For a command asked for directly: the feature must be switched on."""
+        if not self.project.has(feature):
+            raise UsageError(f'[{feature}] is not in {self.project.root / config.PROJECT_FILE}',
+                             hint=f'Add a [{feature}] table to switch it on for this app. '
+                                  '`mkit doctor` lists every feature.',
+                             code='FEATURE_OFF')
+
+
+def _global_flags(parser, suppress):
+    default = argparse.SUPPRESS if suppress else None
+    flag_default = argparse.SUPPRESS if suppress else False
+    g = parser.add_argument_group('global options')
+    g.add_argument('--json', dest='output_mode', action='store_const', const='json',
+                   default=default, help='JSON result on stdout, JSONL events on stderr')
+    g.add_argument('--human', dest='output_mode', action='store_const', const='human',
+                   default=default, help='human output even when not at a terminal')
+    g.add_argument('--project', default=default, metavar='PATH',
+                   help='app folder holding mkit.toml (default: search up from here)')
+    g.add_argument('--yes', action='store_true', default=flag_default,
+                   help='approve a publish without a prompt (needs --confirm)')
+    g.add_argument('--confirm', default=default, metavar='PACKAGE',
+                   help='the package id being changed, required with --yes')
+    g.add_argument('--dry-run', action='store_true', default=flag_default,
+                   help='do everything except the change itself')
+    g.add_argument('--strict', action='store_true', default=flag_default,
+                   help='treat a skipped pipeline step as a failure')
+    g.add_argument('--no-color', action='store_true', default=flag_default)
+
+
+def _add_args(parser, cmd):
+    for a in cmd.args:
+        if a.kind == 'positional':
+            kwargs = {'help': a.help, 'type': a.type}
+            if a.nargs:
+                kwargs['nargs'] = a.nargs
+            if a.choices:
+                kwargs['choices'] = a.choices
+            if a.default is not None:
+                kwargs['default'] = a.default
+            parser.add_argument(a.name, **kwargs)
+            continue
+        flags = [] if a.short and not a.long else [f'--{a.name.replace("_", "-")}']
+        if a.short:
+            flags.insert(0, f'-{a.short}')
+        if a.kind == 'flag':
+            parser.add_argument(*flags, dest=a.name, help=a.help,
+                                action='count' if a.repeat else 'store_true',
+                                default=0 if a.repeat else False)
+        else:
+            kwargs = {'dest': a.name, 'help': a.help, 'type': a.type, 'default': a.default}
+            if a.choices:
+                kwargs['choices'] = a.choices
+            if a.nargs:
+                kwargs['nargs'] = a.nargs
+            parser.add_argument(*flags, **kwargs)
+
+
+def build_parser():
+    from . import commands  # noqa: F401  (registers every command)
+
+    parser = argparse.ArgumentParser(
+        prog='mkit', description='Android release, Play Console and Firebase operations.',
+        epilog='`mkit commands` lists everything; `mkit <command> -h` explains one.')
+    parser.add_argument('--version', action='version', version=f'mkit {__version__}')
+    _global_flags(parser, suppress=False)
+    sub = parser.add_subparsers(dest='_cmd', metavar='<command>')
+
+    group_parsers = {}
+    for name in sorted(REGISTRY):
+        cmd = REGISTRY[name]
+        parts = name.split(' ')
+        target = sub
+        if len(parts) == 2:
+            head = parts[0]
+            if head not in group_parsers:
+                gp = sub.add_parser(head, help=GROUPS.get(head, ''))
+                group_parsers[head] = gp.add_subparsers(dest='_sub', metavar='<action>')
+            target = group_parsers[head]
+        p = target.add_parser(parts[-1], help=cmd.summary, description=cmd.summary,
+                              epilog='examples:\n  ' + '\n  '.join(cmd.examples) if cmd.examples else None,
+                              formatter_class=argparse.RawDescriptionHelpFormatter)
+        _global_flags(p, suppress=True)
+        _add_args(p, cmd)
+        p.set_defaults(_command=name)
+    return parser
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    out = output.configure(mode=args.output_mode, color=not args.no_color)
+    name = getattr(args, '_command', None)
+    if name is None:
+        if getattr(args, '_cmd', None):
+            # A group given without an action, e.g. `mkit listing`.
+            parser.parse_args([args._cmd, '-h'])
+        parser.print_help()
+        return 2
+
+    cmd = REGISTRY[name]
+    ctx = Context(out=out, command=name, yes=args.yes, confirm=args.confirm,
+                  dry_run=args.dry_run, strict=args.strict)
+    try:
+        if cmd.needs_project or args.project:
+            ctx.project = config.load(project=args.project)
+        else:
+            try:
+                ctx.project = config.load()
+            except MkitError:
+                ctx.project = None
+        ctx.secrets = Secrets(ctx.project.root if ctx.project else None)
+        for feature in cmd.needs:
+            ctx.require(feature)
+        data = cmd.handler(ctx, args)
+        out.result(name, data if data is not None else {}, ctx.exit_code)
+        return ctx.exit_code
+    except MkitError as e:
+        out.failure(name, e, e.exit_code)
+        return e.exit_code
+    except KeyboardInterrupt:
+        err = MkitError('interrupted', code='INTERRUPTED')
+        out.failure(name, err, INTERRUPTED)
+        return INTERRUPTED
+    except Exception as e:  # a bug in mkit, not an operational outcome
+        err = MkitError(f'internal error: {type(e).__name__}: {e}', code='INTERNAL',
+                        hint='This is a bug in mkit. The traceback is on stderr.')
+        traceback.print_exc(file=sys.stderr)
+        out.failure(name, err, FAILED)
+        return FAILED
+
+
+def run():
+    sys.exit(main())
+
+
+if __name__ == '__main__':
+    run()

mkit/cloud/__init__.py

@@ -0,0 +1 @@
+"""Google APIs: Play (Android Publisher, Reporting, reports bucket) and Firebase."""

mkit/cloud/auth.py

@@ -0,0 +1,130 @@
+"""Service-account clients, retries, and Google errors turned into MkitErrors.
+
+Two credentials, from secrets.py:
+
+    PLAY_SERVICE_ACCOUNT      Android Publisher, Play Developer Reporting, and
+                              the Play reports bucket. One per developer
+                              account, so it normally lives in ~/.mkit/.env.
+    FIREBASE_SERVICE_ACCOUNT  This app's Firebase / Cloud project: Firestore,
+                              rules, Remote Config, Firebase Management.
+"""
+import json
+import socket
+import ssl
+import time
+
+from .. import output
+from ..errors import Conflict, CredentialMissing, MkitError, NotFound
+
+PLAY = 'PLAY_SERVICE_ACCOUNT'
+FIREBASE = 'FIREBASE_SERVICE_ACCOUNT'
+
+SCOPE_PUBLISHER = 'https://www.googleapis.com/auth/androidpublisher'
+SCOPE_REPORTING = 'https://www.googleapis.com/auth/playdeveloperreporting'
+SCOPE_STORAGE_READ = 'https://www.googleapis.com/auth/devstorage.read_only'
+SCOPE_CLOUD = 'https://www.googleapis.com/auth/cloud-platform'
+SCOPE_FIREBASE = 'https://www.googleapis.com/auth/firebase'
+SCOPE_DATASTORE = 'https://www.googleapis.com/auth/datastore'
+SCOPE_REMOTE_CONFIG = 'https://www.googleapis.com/auth/firebase.remoteconfig'
+
+# A bundle is large and uploads from a home connection; httplib2's default
+# socket timeout kills a release on one slow chunk.
+UPLOAD_TIMEOUT = 600
+
+TRANSIENT = (TimeoutError, socket.timeout, ssl.SSLError, ConnectionError)
+
+
+def credentials(ctx, secret, scopes):
+    from google.oauth2 import service_account
+    info = ctx.secrets.json(secret)
+    return service_account.Credentials.from_service_account_info(info, scopes=list(scopes))
+
+
+def service_account_project(ctx, secret=FIREBASE):
+    project = ctx.secrets.json(secret).get('project_id')
+    if not project:
+        raise CredentialMissing(f'{secret} names no project_id', code='BAD_CREDENTIAL')
+    return project
+
+
+def token(ctx, secret, scopes):
+    import google.auth.transport.requests
+    creds = credentials(ctx, secret, scopes)
+    creds.refresh(google.auth.transport.requests.Request())
+    return creds.token
+
+
+def build(ctx, api, version, secret, scopes, timeout=120):
+    """A discovery client. static_discovery=False reads the live discovery
+    document, so methods Google added after this library was released (the
+    monetization and changesInReviewBehavior additions, for example) exist."""
+    import google_auth_httplib2
+    import httplib2
+    from googleapiclient.discovery import build as _build
+
+    creds = credentials(ctx, secret, scopes)
+    transport = httplib2.Http(timeout=timeout)
+    # A resumable upload's "308 Resume Incomplete" is progress, not a redirect.
+    transport.redirect_codes = set(range(300, 400)) - {308}
+    http = google_auth_httplib2.AuthorizedHttp(creds, http=transport)
+    return _build(api, version, http=http, cache_discovery=False, static_discovery=False)
+
+
+def play(ctx, timeout=None):
+    upload_timeout = int(ctx.project.get('play.upload_timeout', UPLOAD_TIMEOUT))
+    return build(ctx, 'androidpublisher', 'v3', PLAY, [SCOPE_PUBLISHER],
+                 timeout=timeout or upload_timeout)
+
+
+def status_of(error):
+    return getattr(getattr(error, 'resp', None), 'status', 0) or 0
+
+
+def api_message(error):
+    """The sentence out of a Google API error, not googleapiclient's repr of
+    the whole request. Play's rejections are one actionable line."""
+    try:
+        return json.loads(error.content.decode('utf-8', 'ignore'))['error']['message']
+    except Exception:
+        return str(error)
+
+
+def translate(error, what='Google API'):
+    """An HttpError as the MkitError a caller can branch on."""
+    from googleapiclient.errors import HttpError
+    if not isinstance(error, HttpError):
+        return error
+    status, message = status_of(error), api_message(error)
+    if status in (401, 403):
+        return CredentialMissing(
+            f'{what} refused the service account ({status}): {message}',
+            hint='In Play Console > Users and permissions (or the Cloud/Firebase IAM page), give '
+                 "the service account's email access to this app, then retry.",
+            code='PERMISSION_DENIED')
+    if status == 404:
+        return NotFound(f'{what}: {message}', code='NOT_FOUND')
+    if status == 409 or 'expired' in message.lower() or 'in review' in message.lower():
+        return Conflict(f'{what}: {message}', retryable=True)
+    return MkitError(f'{what} rejected the request ({status}): {message}',
+                     code=f'HTTP_{status}', retryable=status >= 500)
+
+
+def retry(call, what, tries=5):
+    """Run one API call, retrying 5xx and dropped connections with backoff.
+    Anything below 500 is Google telling us something real and is raised at
+    once. `call` is a zero-arg function returning an executable request."""
+    from googleapiclient.errors import HttpError
+    for attempt in range(tries):
+        try:
+            return call().execute()
+        except HttpError as error:
+            if status_of(error) < 500 or attempt == tries - 1:
+                raise
+            reason = f'HTTP {status_of(error)}'
+        except TRANSIENT as error:
+            if attempt == tries - 1:
+                raise
+            reason = type(error).__name__
+        wait = 2 ** attempt
+        output.out.warn(f'{what}: {reason}, retrying in {wait}s ({attempt + 1}/{tries - 1})')
+        time.sleep(wait)