mkit-cli 0.3.1__py3-none-any.whl

mkit/cloud/fbproject.py

@@ -0,0 +1,180 @@
+"""Remote Config templates and Firebase app management (SHA fingerprints,
+google-services.json), with this app's Firebase service account.
+
+Remote Config is published whole: the template is read with its ETag and
+written back with If-Match, so a change someone made in the console between
+plan and apply is a conflict (exit 5), never silently overwritten.
+"""
+import json
+import re
+import time
+
+from ..errors import Conflict, MkitError, NotFound, UsageError
+from . import auth
+from .firebase import project_id
+
+RC = 'https://firebaseremoteconfig.googleapis.com/v1/projects/{p}/remoteConfig'
+MGMT = 'https://firebase.googleapis.com/v1beta1/projects/{p}'
+TEMPLATE_KEYS = ('conditions', 'parameters', 'parameterGroups')
+
+
+def _session(ctx, scopes):
+    import google.auth.transport.requests
+    return google.auth.transport.requests.AuthorizedSession(auth.credentials(ctx, auth.FIREBASE, scopes))
+
+
+def _check(r, what):
+    if r.status_code in (401, 403):
+        raise MkitError(f'{what} refused ({r.status_code}): {r.text[:200]}', code='PERMISSION_DENIED',
+                        hint='Give the Firebase service account the matching role (Remote Config Admin, '
+                             'Firebase Admin) in the Cloud console IAM page.')
+    if r.status_code == 409 or r.status_code == 412:
+        raise Conflict(f'{what}: the template changed since it was read; run plan again')
+    if r.status_code == 404:
+        raise NotFound(f'{what}: not found')
+    if r.status_code >= 400:
+        raise MkitError(f'{what} failed ({r.status_code}): {r.text[:300]}', code=f'HTTP_{r.status_code}')
+    return r
+
+
+# ------------------------------------------------------------------ Remote Config
+
+def template_path(ctx):
+    return ctx.project.path('firebase.remote_config', 'remoteconfig.template.json')
+
+
+def rc_get(ctx):
+    s = _session(ctx, [auth.SCOPE_REMOTE_CONFIG])
+    r = _check(s.get(RC.format(p=project_id(ctx)), headers={'Accept-Encoding': 'gzip'}, timeout=60),
+               'Remote Config')
+    return r.json(), r.headers.get('ETag')
+
+
+def local_template(ctx):
+    path = template_path(ctx)
+    if not path.is_file():
+        raise UsageError(f'{path} not found', hint='`mkit remoteconfig pull` writes it from Firebase.',
+                         code='NO_TEMPLATE')
+    data = json.loads(path.read_text(encoding='utf-8'))
+    return {k: data[k] for k in TEMPLATE_KEYS if k in data}
+
+
+def rc_diff(remote, local):
+    changes = []
+    rp, lp = remote.get('parameters', {}), local.get('parameters', {})
+    for key in sorted(set(rp) | set(lp)):
+        if key not in lp:
+            changes.append({'parameter': key, 'change': 'remove'})
+        elif key not in rp:
+            changes.append({'parameter': key, 'change': 'add'})
+        elif rp[key] != lp[key]:
+            changes.append({'parameter': key, 'change': 'update'})
+    for key in ('conditions', 'parameterGroups'):
+        if remote.get(key, [] if key == 'conditions' else {}) != local.get(key, [] if key == 'conditions' else {}):
+            changes.append({'parameter': f'({key})', 'change': 'update'})
+    return changes
+
+
+def rc_publish(ctx, template, etag, validate_only=False):
+    s = _session(ctx, [auth.SCOPE_REMOTE_CONFIG])
+    r = _check(s.put(RC.format(p=project_id(ctx)), params={'validate_only': 'true'} if validate_only else None,
+                     headers={'If-Match': etag, 'Content-Type': 'application/json; UTF-8'},
+                     data=json.dumps(template), timeout=60), 'Remote Config publish')
+    return r.json().get('version', {})
+
+
+def rc_versions(ctx, limit=10):
+    s = _session(ctx, [auth.SCOPE_REMOTE_CONFIG])
+    r = _check(s.get(RC.format(p=project_id(ctx)) + ':listVersions', params={'pageSize': limit}, timeout=60),
+               'Remote Config versions')
+    return r.json().get('versions', [])
+
+
+def rc_rollback(ctx, version):
+    s = _session(ctx, [auth.SCOPE_REMOTE_CONFIG])
+    r = _check(s.post(RC.format(p=project_id(ctx)) + ':rollback', json={'versionNumber': str(version)},
+                      timeout=60), 'Remote Config rollback')
+    return r.json().get('version', {})
+
+
+# ------------------------------------------------------------------ Firebase apps
+
+def android_apps(ctx):
+    s = _session(ctx, [auth.SCOPE_FIREBASE])
+    r = _check(s.get(MGMT.format(p=project_id(ctx)) + '/androidApps', params={'pageSize': 100},
+                     timeout=60), 'Firebase apps')
+    return s, r.json().get('apps', [])
+
+
+def android_app(ctx, package=None):
+    package = package or ctx.project.package
+    s, apps = android_apps(ctx)
+    app = next((a for a in apps if a.get('packageName') == package), None)
+    if not app:
+        raise NotFound(f'no Android app {package} in Firebase project {project_id(ctx)}',
+                       hint=f'It has: {", ".join(a.get("packageName", "?") for a in apps) or "none"}')
+    return s, app
+
+
+def ensure_android_app(ctx, package, display_name, wait=120):
+    """The project's Android app for `package`, registering it when missing.
+    Returns (app, created). Creation is a long-running operation; it is waited
+    for, so the config pulled right after already carries the new client."""
+    s, apps = android_apps(ctx)
+    app = next((a for a in apps if a.get('packageName') == package), None)
+    if app:
+        return app, False
+    op = _check(s.post(MGMT.format(p=project_id(ctx)) + '/androidApps',
+                       json={'packageName': package, 'displayName': display_name}, timeout=60),
+                f'Registering {package}').json()
+    deadline = time.monotonic() + wait
+    while not op.get('done'):
+        if time.monotonic() > deadline:
+            raise MkitError(f'Firebase is still registering {package}',
+                            hint='Run the same command again in a minute; it picks up where this left off.',
+                            code='FIREBASE_PENDING')
+        time.sleep(2)
+        op = _check(s.get(f'https://firebase.googleapis.com/v1beta1/{op["name"]}', timeout=60),
+                    f'Registering {package}').json()
+    if op.get('error'):
+        raise MkitError(f'Firebase could not register {package}: {op["error"].get("message", op["error"])}',
+                        code='FIREBASE_CREATE_FAILED')
+    return op.get('response', {}), True
+
+
+def parse_fingerprints(keytool_text):
+    """SHA-1 and SHA-256 of a certificate, from `keytool -list -v` output."""
+    found = {}
+    for label, key in (('SHA1', 'SHA_1'), ('SHA256', 'SHA_256')):
+        m = re.search(rf'{label}:\s*([0-9A-Fa-f:]+)', keytool_text)
+        if m:
+            found[key] = m.group(1)
+    return found
+
+
+def sha_list(ctx):
+    s, app = android_app(ctx)
+    r = _check(s.get(f'https://firebase.googleapis.com/v1beta1/{app["name"]}/sha', timeout=60), 'SHA list')
+    return app, r.json().get('certificates', [])
+
+
+def sha_add(ctx, sha, package=None):
+    clean = sha.replace(':', '').lower()
+    cert_type = {40: 'SHA_1', 64: 'SHA_256'}.get(len(clean))
+    if not cert_type:
+        raise UsageError('a SHA-1 has 40 hex digits and a SHA-256 has 64 (colons are fine)')
+    s, app = android_app(ctx, package)
+    r = s.post(f'https://firebase.googleapis.com/v1beta1/{app["name"]}/sha',
+               json={'shaHash': clean, 'certType': cert_type}, timeout=60)
+    if r.status_code == 409:
+        return {'shaHash': clean, 'certType': cert_type, 'changed': False}
+    _check(r, 'SHA add')
+    return {'shaHash': clean, 'certType': cert_type, 'changed': True}
+
+
+def config_file(ctx):
+    import base64
+    s, app = android_app(ctx)
+    r = _check(s.get(f'https://firebase.googleapis.com/v1beta1/{app["name"]}/config', timeout=60),
+               'google-services.json')
+    return base64.b64decode(r.json()['configFileContents']).decode('utf-8')

mkit/cloud/firebase.py

@@ -0,0 +1,164 @@
+"""Firebase: the in-app update document, and Firestore rules/indexes deploy.
+
+The Firebase project is the one named under [firebase] project in mkit.toml, or
+else the one the service account belongs to. When both are set they must
+agree: a key for the wrong project is the mistake this catches before a rules
+deploy lands somewhere it should not.
+"""
+from urllib.parse import urlsplit
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+
+from .. import output, proc
+from ..errors import MkitError, UsageError
+from ..toolchain import tool
+from . import auth
+
+FIRESTORE = 'https://firestore.googleapis.com/v1'
+
+
+def project_id(ctx):
+    configured = ctx.project.get('firebase.project')
+    from_key = auth.service_account_project(ctx) if ctx.secrets.has(auth.FIREBASE) else None
+    if configured and from_key and configured != from_key:
+        raise UsageError(f'[firebase] project is {configured} but the service account belongs to {from_key}',
+                         hint='Use the key for this app\'s Firebase project, or fix mkit.toml.',
+                         code='PROJECT_MISMATCH')
+    project = configured or from_key
+    if not project:
+        raise UsageError('no Firebase project: set project under [firebase] or add the service account',
+                         code='NO_FIREBASE_PROJECT')
+    return project
+
+
+def _value(v):
+    if isinstance(v, bool):
+        return {'booleanValue': v}
+    if isinstance(v, int):
+        return {'integerValue': str(v)}
+    if isinstance(v, datetime):
+        return {'timestampValue': v.strftime('%Y-%m-%dT%H:%M:%SZ')}
+    return {'stringValue': str(v)}
+
+
+def _send(method, url, **kw):
+    """One request, with a transport failure turned into an MkitError.
+
+    Timeouts, refused connections and DNS failures arrive as requests'
+    own exceptions, which are not MkitErrors - so they used to travel all the
+    way out of a command as an "internal error" with a traceback, and past the
+    handlers that exist to degrade gracefully. A dropped connection is the most
+    ordinary failure there is and says nothing about a bug.
+    """
+    import requests
+    try:
+        return requests.request(method, url, **kw)
+    except requests.exceptions.RequestException as error:
+        raise MkitError(f'could not reach {urlsplit(url).netloc}: '
+                        f'{type(error).__name__.replace("Error", "").lower() or "failed"}',
+                        hint='Check the connection and run it again; nothing was written.',
+                        code='NETWORK', retryable=True) from None
+
+
+def patch_document(ctx, path, values):
+    """Write only the given fields of one document (updateMask), creating it if
+    needed. Fields not named are left exactly as they are."""
+    project = project_id(ctx)
+    token = auth.token(ctx, auth.FIREBASE, [auth.SCOPE_DATASTORE])
+    fields = {k: _value(v) for k, v in values.items()}
+    response = _send(
+        'PATCH', f'{FIRESTORE}/projects/{project}/databases/(default)/documents/{path}',
+        params=[('updateMask.fieldPaths', k) for k in fields],
+        json={'fields': fields}, headers={'Authorization': f'Bearer {token}'}, timeout=30)
+    if response.status_code in (401, 403):
+        raise MkitError(f'Firestore refused the write ({response.status_code})', code='PERMISSION_DENIED',
+                        hint='Give the service account the Cloud Datastore User role on the project.')
+    if response.status_code >= 400:
+        raise MkitError(f'Firestore write failed ({response.status_code}): {response.text[:300]}',
+                        code=f'HTTP_{response.status_code}')
+    return project
+
+
+def get_document(ctx, path):
+    project = project_id(ctx)
+    token = auth.token(ctx, auth.FIREBASE, [auth.SCOPE_DATASTORE])
+    response = _send('GET', f'{FIRESTORE}/projects/{project}/databases/(default)/documents/{path}',
+                     headers={'Authorization': f'Bearer {token}'}, timeout=30)
+    if response.status_code == 404:
+        return {}
+    if response.status_code >= 400:
+        raise MkitError(f'Firestore read failed ({response.status_code}): {response.text[:300]}',
+                        code=f'HTTP_{response.status_code}')
+    out = {}
+    for key, value in response.json().get('fields', {}).items():
+        (kind, raw), = value.items()
+        out[key] = int(raw) if kind == 'integerValue' else raw
+    return out
+
+
+def update_doc_path(ctx):
+    return ctx.project.get('firebase.update_doc', 'config/app')
+
+
+def publish_version(ctx, version_name, version_code):
+    """The document the app reads to decide whether to offer an update."""
+    path = update_doc_path(ctx)
+    project = patch_document(ctx, path, {'latestBuild': int(version_code),
+                                         'latestVersionName': version_name,
+                                         'updatedAt': datetime.now(timezone.utc)})
+    return f'{project}/{path}'
+
+
+def deploy_targets(ctx):
+    custom = ctx.project.get('firebase.deploy')
+    if custom:
+        return list(custom)
+    targets = []
+    if (ctx.project.root / 'firestore.rules').is_file():
+        targets.append('firestore:rules')
+    if (ctx.project.root / 'firestore.indexes.json').is_file():
+        targets.append('firestore:indexes')
+    return targets
+
+
+def deploy_rules(ctx):
+    """`firebase deploy --only firestore:rules,firestore:indexes` as the
+    project's service account, not whoever happens to be logged in to the CLI.
+
+    The key is written to a private temp file for the one command and deleted
+    straight after. Rules go out before a build on purpose: rules live ahead of
+    the app that needs them only widen what older clients may do, while an app
+    that reaches users before its rules gets PERMISSION_DENIED.
+    """
+    targets = deploy_targets(ctx)
+    if not targets:
+        raise UsageError('nothing to deploy: no firestore.rules or firestore.indexes.json',
+                         code='NO_RULES')
+    if not (ctx.project.root / 'firebase.json').is_file():
+        raise UsageError('firebase.json not found in the project root', code='NO_FIREBASE_JSON')
+    project = project_id(ctx)
+    info = ctx.secrets.json(auth.FIREBASE)
+    fd, key_path = tempfile.mkstemp(prefix='mkit-sa-', suffix='.json')
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(info, f)
+        env = dict(os.environ, GOOGLE_APPLICATION_CREDENTIALS=key_path)
+        env.pop('FIREBASE_TOKEN', None)
+        # "Deploy complete!" is the CLI's own word that the rules and indexes are live. It
+        # can still exit non-zero afterwards: on a success it posts a Google Analytics event
+        # with a 5s timeout (command.js -> withTimeout(5000, trackGA4)), and where that call
+        # cannot reach Google the timeout escapes as "An unexpected error has occurred". The
+        # deploy is done by then, and failing here would roll back a version bump over a
+        # telemetry ping.
+        proc.stream([tool('firebase'), 'deploy', '--only', ','.join(targets), '--project', project,
+                     '--non-interactive'], 'firebase deploy', proc.firebase_interesting,
+                    cwd=ctx.project.root, env=env, quiet=True,
+                    done_marker='Deploy complete!')
+    finally:
+        try:
+            os.remove(key_path)
+        except OSError:
+            output.out.warn(f'could not delete the temporary key file {key_path}; delete it by hand')
+    return project, targets

mkit/cloud/insight.py

@@ -0,0 +1,286 @@
+"""How the app is doing: bulk reports, Android vitals, crash clusters, reviews.
+
+    stats     the Play Console bulk reports (Cloud Storage bucket, UTF-16 CSVs,
+              3-7 days behind). The service account needs "View app information
+              and download bulk reports"; the bucket is MKIT_PLAY_REPORTS_BUCKET.
+    vitals    Play Developer Reporting API crash and ANR rates.
+    crashes   Reporting API error issues: crash/ANR clusters with stack location.
+    reviews   Android Publisher reviews: only the last 7 days with text.
+"""
+import csv
+import io
+from collections import defaultdict
+from datetime import date, timedelta
+
+from ..errors import CredentialMissing, MkitError, UsageError
+from . import auth
+
+REPORTING = 'https://playdeveloperreporting.googleapis.com/v1beta1'
+
+
+# ------------------------------------------------------------------ bulk reports
+
+def _bucket(ctx):
+    bucket = ctx.project.get('play.reports_bucket') or ctx.secrets.value('MKIT_PLAY_REPORTS_BUCKET')
+    if not bucket:
+        raise UsageError('no reports bucket', code='NO_BUCKET',
+                         hint='Set MKIT_PLAY_REPORTS_BUCKET in ~/.mkit/.env (Play Console > Download '
+                              'reports > copy the Cloud Storage URI, the part after gs://).')
+    return bucket.removeprefix('gs://').strip('/')
+
+
+def _decode(raw):
+    for encoding in ('utf-16', 'utf-8-sig', 'utf-8'):
+        try:
+            text = raw.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+        if '\x00' not in text:
+            rows = list(csv.reader(io.StringIO(text)))
+            return (rows[0], rows[1:]) if rows else ([], [])
+    return [], []
+
+
+def _col(header, *names):
+    lowered = [h.strip().lower() for h in header]
+    for n in names:
+        if n.lower() in lowered:
+            return lowered.index(n.lower())
+    return None
+
+
+def _int(v):
+    try:
+        return int(float(v or 0))
+    except ValueError:
+        return 0
+
+
+def store_daily(ctx):
+    """Store listing visitors and acquisitions per day, all countries summed:
+    {'YYYY-MM-DD': (visitors, acquisitions)}. Days Play has no row for are
+    left out (no visitors that day, or under Play's reporting threshold)."""
+    from googleapiclient.errors import HttpError
+    bucket, package = _bucket(ctx), ctx.project.package
+    st = auth.build(ctx, 'storage', 'v1', auth.PLAY, [auth.SCOPE_STORAGE_READ])
+    prefix = f'stats/store_performance/store_performance_{package}_'
+    try:
+        names, token = [], None
+        while True:
+            res = st.objects().list(bucket=bucket, prefix=prefix, maxResults=1000, pageToken=token).execute()
+            names += [o['name'] for o in res.get('items', [])]
+            token = res.get('nextPageToken')
+            if not token:
+                break
+    except HttpError as e:
+        raise auth.translate(e, 'Play reports bucket') from None
+    daily = defaultdict(lambda: [0, 0])
+    for name in sorted(names):
+        if not name.endswith('_country.csv'):
+            continue
+        header, rows = _decode(st.objects().get_media(bucket=bucket, object=name).execute())
+        v, a = _col(header, 'Store listing visitors'), _col(header, 'Store listing acquisitions')
+        if None in (v, a):
+            continue
+        for r in rows:
+            if len(r) > max(v, a) and r[0]:
+                daily[r[0]][0] += _int(r[v])
+                daily[r[0]][1] += _int(r[a])
+    return {d: tuple(x) for d, x in sorted(daily.items())}
+
+
+def stats(ctx):
+    from googleapiclient.errors import HttpError
+    bucket, package = _bucket(ctx), ctx.project.package
+    st = auth.build(ctx, 'storage', 'v1', auth.PLAY, [auth.SCOPE_STORAGE_READ])
+
+    def listing(prefix):
+        names, token = [], None
+        while True:
+            res = st.objects().list(bucket=bucket, prefix=prefix, maxResults=1000, pageToken=token).execute()
+            names += [o['name'] for o in res.get('items', [])]
+            token = res.get('nextPageToken')
+            if not token:
+                return sorted(names)
+
+    def fetch(name):
+        return _decode(st.objects().get_media(bucket=bucket, object=name).execute())
+
+    try:
+        installs = listing(f'stats/installs/installs_{package}_')
+        store_perf = listing(f'stats/store_performance/store_performance_{package}_')
+        reviews = listing(f'reviews/reviews_{package}_')
+    except HttpError as e:
+        err = auth.translate(e, 'Play reports bucket')
+        if isinstance(err, CredentialMissing):
+            err.hint = ('In Play Console > Users and permissions, give the service account "View app '
+                        'information and download bulk reports" (account level).')
+        raise err from None
+
+    daily, by_country = [], defaultdict(int)
+    for name in installs:
+        header, rows = fetch(name)
+        if name.endswith('_overview.csv'):
+            i, u, a = (_col(header, 'Daily User Installs'), _col(header, 'Daily User Uninstalls'),
+                       _col(header, 'Active Device Installs'))
+            if None in (i, u, a):
+                continue
+            daily += [{'date': r[0], 'installs': _int(r[i]), 'uninstalls': _int(r[u]), 'active': _int(r[a])}
+                      for r in rows if len(r) > max(i, u, a)]
+        elif name.endswith('_country.csv'):
+            c, i = _col(header, 'Country', 'Country / region'), _col(header, 'Daily User Installs')
+            if None in (c, i):
+                continue
+            for r in rows:
+                if len(r) > max(c, i):
+                    by_country[r[c] or '??'] += _int(r[i])
+    daily.sort(key=lambda d: d['date'])
+
+    visitors = acquisitions = 0
+    for name in store_perf:
+        if not name.endswith('_country.csv'):
+            continue
+        header, rows = fetch(name)
+        v, a = _col(header, 'Store listing visitors'), _col(header, 'Store listing acquisitions')
+        if None in (v, a):
+            continue
+        for r in rows:
+            if len(r) > max(v, a):
+                visitors += _int(r[v])
+                acquisitions += _int(r[a])
+
+    stars = []
+    for name in reviews:
+        header, rows = fetch(name)
+        s = _col(header, 'Star Rating')
+        if s is not None:
+            stars += [_int(r[s]) for r in rows if len(r) > s and (r[s] or '').strip()]
+
+    active = [d['active'] for d in daily]
+    return {
+        'window': [daily[0]['date'], daily[-1]['date']] if daily else None,
+        'store': {'visitors': visitors, 'acquisitions': acquisitions,
+                  'conversion': round(acquisitions / visitors * 100, 1) if visitors else None},
+        'installs': {'installs': sum(d['installs'] for d in daily),
+                     'uninstalls': sum(d['uninstalls'] for d in daily),
+                     'active_peak': max(active, default=0), 'active_latest': active[-1] if active else 0},
+        'ratings': {'count': len(stars), 'average': round(sum(stars) / len(stars), 2) if stars else None},
+        'countries': dict(sorted(by_country.items(), key=lambda kv: -kv[1])),
+        'daily': daily,
+    }
+
+
+# ------------------------------------------------------------------ Reporting API
+
+def _session(ctx):
+    import google.auth.transport.requests
+    creds = auth.credentials(ctx, auth.PLAY, [auth.SCOPE_REPORTING])
+    return google.auth.transport.requests.AuthorizedSession(creds)
+
+
+def _call(session, method, url, **kw):
+    r = session.request(method, url, timeout=60, **kw)
+    if r.status_code in (401, 403):
+        raise CredentialMissing(f'Play Developer Reporting API refused the request ({r.status_code})',
+                                hint='Enable the "Google Play Developer Reporting API" in the service '
+                                     "account's Cloud project and give it \"View app information\" in Play Console.",
+                                code='PERMISSION_DENIED')
+    if r.status_code >= 400:
+        raise MkitError(f'Reporting API error {r.status_code}: {r.text[:300]}', code=f'HTTP_{r.status_code}')
+    return r.json()
+
+
+def _date(d):
+    return {'year': d.year, 'month': d.month, 'day': d.day}
+
+
+METRICS = {
+    'crash': ('crashRateMetricSet', ['crashRate', 'userPerceivedCrashRate', 'distinctUsers']),
+    'anr': ('anrRateMetricSet', ['anrRate', 'userPerceivedAnrRate', 'distinctUsers']),
+}
+
+
+def vitals(ctx, days=28):
+    """Crash and ANR rates over the last `days` days Play has data for, per
+    version code, plus the overall figure for the window."""
+    session = _session(ctx)
+    package = ctx.project.package
+    out = {}
+    for key, (metric_set, metrics) in METRICS.items():
+        name = f'apps/{package}/{metric_set}'
+        meta = _call(session, 'GET', f'{REPORTING}/{name}')
+        latest = next((f['latestEndTime'] for f in meta.get('freshnessInfo', {}).get('freshnesses', [])
+                       if f.get('aggregationPeriod') == 'DAILY'), None)
+        if not latest:
+            out[key] = {'rows': [], 'note': 'no data yet'}
+            continue
+        end = date(latest['year'], latest['month'], latest['day'])
+        start = end - timedelta(days=days)
+        tz = {'id': 'America/Los_Angeles'}
+        body = {'timelineSpec': {'aggregationPeriod': 'DAILY',
+                                 'startTime': dict(_date(start), timeZone=tz),
+                                 'endTime': dict(_date(end), timeZone=tz)},
+                'dimensions': ['versionCode'], 'metrics': metrics, 'pageSize': 1000}
+        rows = _call(session, 'POST', f'{REPORTING}/{name}:query', json=body).get('rows', [])
+        per_version = defaultdict(lambda: {'users': 0, 'weighted': defaultdict(float)})
+        for row in rows:
+            version = next((d.get('stringValue') or str(d.get('int64Value', '')) for d in row.get('dimensions', [])
+                            if d.get('dimension') == 'versionCode'), '?')
+            values = {m['metric']: float(m.get('decimalValue', {}).get('value', m.get('int64Value', 0)) or 0)
+                      for m in row.get('metrics', [])}
+            users = values.get('distinctUsers', 0)
+            entry = per_version[version]
+            entry['users'] += users
+            for m in metrics:
+                if m != 'distinctUsers':
+                    entry['weighted'][m] += values.get(m, 0) * users
+        table = []
+        for version, e in sorted(per_version.items(), key=lambda kv: kv[0]):
+            users = e['users'] or 1
+            table.append({'versionCode': version, 'users': int(e['users']),
+                          **{m: round(v / users * 100, 3) for m, v in e['weighted'].items()}})
+        out[key] = {'window': [str(start), str(end)], 'rows': table}
+    return out
+
+
+def crashes(ctx, limit=10):
+    session = _session(ctx)
+    data = _call(session, 'GET', f'{REPORTING}/apps/{ctx.project.package}/errorIssues:search',
+                 params={'pageSize': max(1, min(limit, 50))})
+    issues = []
+    for i in data.get('errorIssues', []):
+        issues.append({'type': i.get('type'), 'cause': i.get('cause'), 'location': i.get('location'),
+                       'reports': _int(i.get('errorReportCount')), 'users': _int(i.get('distinctUsers')),
+                       'firstVersion': (i.get('firstAppVersion') or {}).get('versionCode'),
+                       'lastVersion': (i.get('lastAppVersion') or {}).get('versionCode'),
+                       'link': i.get('issueUri')})
+    issues.sort(key=lambda i: -i['reports'])
+    return issues[:limit]
+
+
+# ------------------------------------------------------------------ reviews
+
+def reviews(ctx, limit=50, translate=None):
+    svc = auth.play(ctx, timeout=60)
+    kw = {'packageName': ctx.project.package, 'maxResults': min(limit, 100)}
+    if translate:
+        kw['translationLanguage'] = translate
+    data = auth.retry(lambda: svc.reviews().list(**kw), 'reviews')
+    out = []
+    for r in data.get('reviews', []):
+        user = next((c['userComment'] for c in r.get('comments', []) if 'userComment' in c), {})
+        reply = next((c['developerComment'] for c in r.get('comments', []) if 'developerComment' in c), None)
+        out.append({'id': r['reviewId'], 'author': r.get('authorName', ''), 'stars': user.get('starRating'),
+                    'text': user.get('text', '').strip(), 'language': user.get('reviewerLanguage'),
+                    'version': user.get('appVersionName'), 'device': (user.get('deviceMetadata') or {}).get('productName'),
+                    'date': (user.get('lastModified') or {}).get('seconds'),
+                    'replied': bool(reply), 'reply': (reply or {}).get('text')})
+    return out
+
+
+def reply(ctx, review_id, text):
+    if len(text) > 350:
+        raise UsageError(f'reply is {len(text)} characters; Play allows 350', code='REPLY_TOO_LONG')
+    svc = auth.play(ctx, timeout=60)
+    return auth.retry(lambda: svc.reviews().reply(packageName=ctx.project.package, reviewId=review_id,
+                                                  body={'replyText': text}), 'reply')