Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
API v1: external references and upload metadata (mailr spec G8)
Murtaza Nasirb00aabb6268c
diff --git a/docs/admin-guide/webhooks.md b/docs/admin-guide/webhooks.mdindex 7c8cccc3..92fe698a 100644--- a/docs/admin-guide/webhooks.md+++ b/docs/admin-guide/webhooks.md@@ -38,6 +38,7 @@ app, through API v1 or by a speaker rename or merge. `fields_changed` uses these| `transcript` | the transcript text or its speaker names || `speakers` | which name each diarization label shows || `tags` | a tag was added, removed or reordered |+| `external_refs` | the webhook owner's external references || `events` | extracted calendar events changed || `is_inbox`, `is_highlighted`, `is_archived` | the owner's flags || `audio` | the audio was removed |@@ -80,7 +81,8 @@ Every delivery is a `POST` with a JSON body shaped like:- `timestamp` and `occurred_at` are the time the event happened (UTC, microseconds). They donot change on retries: the body is stored once and every attempt sends the same bytes.- `data` of every `recording.*` event carries `updated_at`, the recording's last change as- in the API (absent for `recording.deleted`).+ in the API, and `external_refs`, the webhook owner's references (both absent for+ `recording.deleted`).- The body is `json.dumps(envelope, separators=(',', ':'), ensure_ascii=False)` in UTF-8.Verify the signature over the raw bytes you received, never over re-serialised JSON.diff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.mdindex 11759f1c..10e64ebc 100644--- a/docs/user-guide/api-reference.md+++ b/docs/user-guide/api-reference.md@@ -270,41 +270,61 @@ Upload a recording as multipart form-data and immediately queue transcription.| Field | Type | Required | Description ||-------|------|----------|-------------|-| `file` | file | yes | Audio file to upload |-| `notes` | string | no | Optional notes |-| `file_last_modified` | string | no | Client file lastModified (ms epoch) |+| `file` | file | yes | Audio or video file |+| `title` | string | no | Title. Without it, the title comes from your title settings once the transcript exists. |+| `participants` | string | no | Comma-separated names, at most 500 characters |+| `meeting_date` | string | no | ISO 8601. Takes precedence over every other date source. |+| `file_last_modified` | string | no | The file's last-modified time in milliseconds since the epoch. Used when `meeting_date` is absent and no date is read from the file name. |+| `notes` | string | no | Notes |+| `folder_id` | integer | no | Folder (your own or a group folder you belong to) |+| `tag_ids[0]`, `tag_ids[1]`, ... | integer | no | Tags, in order (your own or group tags you belong to) |+| `tag_id` | integer | no | Single tag (legacy) |+| `external_refs` | string | no | JSON array of [external references](#external-references) without `id` |+| `idempotency_key` | string | no | 1 to 100 characters; see below |+| `strict` | boolean | no | `true`: a tag or folder you cannot use is an error (`400`). Default `false`: it is dropped and reported in `ignored`. || `language` | string | no | Language hint (ISO 639-1) |-| `min_speakers` | integer | no | Min speaker count |-| `max_speakers` | integer | no | Max speaker count |-| `tag_ids[0]`, `tag_ids[1]`, ... | integer | no | Tag IDs (multi) |-| `tag_id` | integer | no | Single tag ID (legacy) |+| `min_speakers`, `max_speakers` | integer | no | Speaker count limits |+| `hotwords`, `initial_prompt` | string | no | Transcription hints |+| `transcription_model` | string | no | One of the models the administrator allows |+| `prompt_variables` | string | no | JSON object of `{{name}}` values for the summary prompt || `keep_audio_only` | boolean | no | If `true`, the server discards the video stream and stores only the extracted audio. Lets you upload videos larger than `max_file_size_mb`, up to `max_audio_only_video_size_mb`, as long as the extracted audio fits the regular limit. When `VIDEO_RETENTION` is off at the server, this is implicit for video uploads. |+The meeting date is chosen in this order: `meeting_date`, a date in the file name (when you turned that on in your settings), `file_last_modified`, the date stored in the file, the upload time.++**Idempotent uploads.** Send an `idempotency_key` (for example a message id and attachment number) when a client may retry. A repeat with the same key by the same user within 24 hours returns the recording the first call created, with `200` and `"idempotent_replay": true`; the file is not stored again and no second transcription is queued. Keys are per user.+**Response:**```json// 202 Accepted{"id": 123,- "title": "Recording - meeting.mp3",+ "title": "Weekly sync","status": "PENDING","created_at": "2024-01-15T10:00:00Z","meeting_date": "2024-01-15T09:00:00Z",+ "participants": "Dana, Omar","file_size": 15728640,"original_filename": "meeting.mp3","mime_type": "audio/mpeg",- "notes": "Quick test upload"+ "notes": "Quick test upload",+ "external_refs": [{"id": 77, "system": "mailr", "kind": "event", "ref": "[email protected]", "url": null, "label": null, "created_at": "2024-01-15T10:00:00.000000Z"}],+ "ignored": {"tag_ids": [], "folder_id": null}}```+`ignored` lists the tags and folder the upload dropped because you cannot use them.+**Example:**```bashcurl -X POST \- -H "X-API-Token: YOUR_TOKEN" \+ -H "Authorization: Bearer YOUR_TOKEN" \-F "file=@/path/to/audio.mp3" \- -F "notes=Quick test upload" \- -F "language=en" \+ -F "title=Weekly sync" \+ -F "participants=Dana, Omar" \+ -F 'external_refs=[{"system":"mailr","kind":"event","ref":"[email protected]"}]' \+ -F "idempotency_key=msg-4411:part-2" \https://speakr.example.com/api/v1/recordings/upload```@@ -388,6 +408,7 @@ GET /api/v1/recordings| `date_to` | string | - | Filter to date (ISO format); a date alone includes that whole day || `date_field` | string | `created_at` | What `date_from` and `date_to` filter: `created_at` or `meeting_date` || `updated_since` | string | - | Only recordings changed after this time (ISO 8601). Deletions are not listed; use the [changes feed](#changes-feed) for those. |+| `external_system`, `external_ref`, `external_kind` | string | - | Only recordings that carry this [external reference](#external-references) of yours (`external_kind` optional) || `tag_id` | integer | - | Filter by tag ID || `q` | string | - | Search query (title, participants) || `inbox` | boolean | - | Filter by inbox status |@@ -443,6 +464,56 @@ GET /api/v1/recordings`updated_at` is the time of the last change a client can see: title, participants, notes, summary, transcript, status, dates, folder, flags, tags, events or sharing. It is present on every recording in API v1 and starts at `created_at`.+### External References++A reference links a recording to an item in another system, such as a calendar event or a conversation in a mail client. References are private: you see only the ones you added, and a user a recording is shared with sees only their own. Every recording in the API carries your references in `external_refs`.++```json+{+ "id": 77,+ "system": "mailr",+ "kind": "event",+ "ref": "[email protected]@2026-10-06T15:00:00Z",+ "url": "https://mail.example.com/calendar/event/5f1c",+ "label": "Weekly sync (6 Oct)",+ "created_at": "2026-10-06T16:02:11.000000Z"+}+```++`system` and `kind`: 1 to 40 characters of `a-z`, `0-9`, `_`, `.`, `-`. `ref`: 1 to 500 printable characters. `url`: optional, `http://` or `https://`, at most 1000 characters. `label`: optional, at most 200 characters. At most 50 references per user per recording (`409 conflict`).++```http+GET /api/v1/recordings/{id}/external-refs+```++**Scope:** `read`++```http+POST /api/v1/recordings/{id}/external-refs+```++**Scope:** `write`++Adds one reference: `201` with the new reference, or `200` with the existing one when you already added the same `system`, `kind` and `ref`.++```http+PUT /api/v1/recordings/{id}/external-refs?system=mailr+```++**Scope:** `write`++Replaces your references of that system with `{"external_refs": [...]}` and returns the new list. References of other systems stay.++```http+DELETE /api/v1/recordings/{id}/external-refs/{ref_id}+```++**Scope:** `write`++`204`. The writes need edit access to the recording, and a reference change counts as a recording change (`updated_at`, `fields_changed: ["external_refs"]`).++To find recordings by reference, filter the list: `GET /api/v1/recordings?external_system=mailr&external_ref=<ref>`, optionally with `&external_kind=event`.+### Changes Feed```httpdiff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex ca0fa9a2..b8ddf6dc 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -915,6 +915,8 @@ CAPABILITY_FEATURES = {'changes_feed': True,'etags': True,'webhook_signature_v2': True,+ 'external_refs': True,+ 'upload_idempotency': True,}# search: {'keyword': True, 'semantic': <Inquire on>} is filled in get_capabilities.@@ -1007,8 +1009,15 @@ def _updated_at_z(recording):return iso_z(effective_updated_at(recording))-def _recording_list_item(r):- """One recording as GET /recordings lists it; the changes feed uses the same shape."""+def _recording_list_item(r, refs=None):+ """One recording as GET /recordings lists it; the changes feed uses the same shape.++ refs: this caller's external references of the recording, when the caller+ loaded them for a whole page (refs_map); otherwise read here.+ """+ if refs is None:+ from src.services.external_refs import refs_for+ refs = [x.to_dict() for x in refs_for(r.id, current_user.id)]from src.services.recording_changes import effective_updated_at, iso_zreturn {'id': r.id,@@ -1037,6 +1046,7 @@ def _recording_list_item(r):'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in r.tags],'keep_audio_only': r.keep_audio_only,'updated_at': iso_z(effective_updated_at(r)),+ 'external_refs': refs,}@@ -1134,6 +1144,22 @@ def list_recordings():except ValueError:pass+ # External references (mailr spec G8): only the caller's own.+ external_system = request.args.get('external_system')+ external_ref = request.args.get('external_ref')+ if external_system or external_ref:+ if not (external_system and external_ref):+ return jsonify({'error': 'external_system and external_ref go together',+ 'code': 'invalid_parameter'}), 400+ from src.models import RecordingExternalRef+ ref_query = db.session.query(RecordingExternalRef.recording_id).filter(+ RecordingExternalRef.user_id == current_user.id,+ RecordingExternalRef.system == external_system,+ RecordingExternalRef.ref == external_ref)+ if request.args.get('external_kind'):+ ref_query = ref_query.filter(RecordingExternalRef.kind == request.args['external_kind'])+ query = query.filter(Recording.id.in_(ref_query))+changed_column = db.func.coalesce(Recording.updated_at, Recording.created_at)if updated_since:try:@@ -1205,7 +1231,9 @@ def list_recordings():pagination = query.paginate(page=page, per_page=per_page, error_out=False)# Build response- recordings = [_recording_list_item(r) for r in pagination.items]+ from src.services.external_refs import refs_map+ page_refs = refs_map([r.id for r in pagination.items], current_user.id)+ recordings = [_recording_list_item(r, page_refs.get(r.id, [])) for r in pagination.items]return jsonify({'recordings': recordings,@@ -1325,6 +1353,82 @@ def search_recordings_v1():'results': results, 'page': page if not use_semantic else 1, 'has_more': has_more})+def _ref_recording(recording_id, require_edit):+ recording = db.session.get(Recording, recording_id)+ if not recording:+ return None, (jsonify({'error': 'Recording not found', 'code': 'not_found'}), 404)+ if not has_recording_access(recording, current_user, require_edit=require_edit):+ return None, (jsonify({'error': 'Permission denied'}), 403)+ return recording, None+++@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['GET'])+@require_scope('read')+@login_required+def list_external_refs(recording_id):+ """Your external references on a recording (mailr spec G8)."""+ from src.services.external_refs import refs_for+ recording, err = _ref_recording(recording_id, require_edit=False)+ if err:+ return err+ return jsonify({'external_refs': [r.to_dict() for r in refs_for(recording.id, current_user.id)]})+++@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['POST'])+@require_scope('write')+@login_required+def add_external_ref(recording_id):+ """Add one reference; an existing (system, kind, ref) answers 200 with it."""+ from src.services import external_refs as xr+ recording, err = _ref_recording(recording_id, require_edit=True)+ if err:+ return err+ try:+ row, created = xr.add(recording, current_user.id, xr.validate(request.get_json(silent=True)))+ except xr.RefError as e:+ return jsonify({'error': str(e), 'code': e.code}), e.status+ db.session.commit()+ return jsonify(row.to_dict()), 201 if created else 200+++@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['PUT'])+@require_scope('write')+@login_required+def replace_external_refs(recording_id):+ """Replace your references of one system (?system=) with the given list."""+ from src.services import external_refs as xr+ recording, err = _ref_recording(recording_id, require_edit=True)+ if err:+ return err+ system = request.args.get('system', '')+ body = request.get_json(silent=True) or {}+ try:+ if not xr._SLUG.match(system):+ raise xr.RefError('?system= is required')+ xr.replace_system(recording, current_user.id, system, xr.validate_list(body.get('external_refs')))+ except xr.RefError as e:+ db.session.rollback()+ return jsonify({'error': str(e), 'code': e.code}), e.status+ db.session.commit()+ return jsonify({'external_refs': [r.to_dict() for r in xr.refs_for(recording.id, current_user.id)]})+++@api_v1_bp.route('/recordings/<int:recording_id>/external-refs/<int:ref_id>', methods=['DELETE'])+@require_scope('write')+@login_required+def delete_external_ref(recording_id, ref_id):+ from src.models import RecordingExternalRef+ recording, err = _ref_recording(recording_id, require_edit=True)+ if err:+ return err+ row = db.session.get(RecordingExternalRef, ref_id)+ if row is None or row.recording_id != recording.id or row.user_id != current_user.id:+ return jsonify({'error': 'Reference not found', 'code': 'not_found'}), 404+ db.session.delete(row)+ db.session.commit()+ return '', 204++@api_v1_bp.route('/recordings/changes', methods=['GET'])@require_scope('read')@login_required@@ -1355,10 +1459,12 @@ def list_recording_changes():return jsonify({'error': 'The cursor is too old; start again without a cursor','code': 'cursor_expired'}), 410items, next_cursor, has_more = read_changes(current_user.id, cursor=cursor, limit=limit)+ from src.services.external_refs import refs_map+ page_refs = refs_map([obj.id for kind, obj in items if kind == 'upsert'], current_user.id)changes = []for kind, obj in items:if kind == 'upsert':- changes.append({'type': 'upsert', 'recording': _recording_list_item(obj)})+ changes.append({'type': 'upsert', 'recording': _recording_list_item(obj, page_refs.get(obj.id, []))})else:changes.append({'type': 'delete', 'id': obj.recording_id,'deleted_at': iso_z(obj.deleted_at), 'reason': obj.reason})@@ -1418,6 +1524,8 @@ def get_recording(recording_id):'duplicate_info': recording.get_duplicate_info(),'keep_audio_only': recording.keep_audio_only,'updated_at': iso_z(effective_updated_at(recording)),+ 'external_refs': [x.to_dict() for x in __import__('src.services.external_refs', fromlist=['refs_for'])+ .refs_for(recording.id, current_user.id)],}# Include large text fields based on params@@ -3368,5 +3476,81 @@ def upload_recording():- folder_id (optional)- tag_ids[0], tag_ids[1], ... (optional)- tag_id (optional, legacy)+ - participants (optional, comma-separated, at most 500 characters)+ - external_refs (optional, JSON array of references)+ - idempotency_key (optional, 1 to 100 characters)+ - strict (optional, true: a tag or folder you cannot use is an error)"""- return _upload_file_ui()+ from src.api.recordings import ingest_uploaded_recording+ from src.models import Folder, GroupMembership, Tag+ from src.services import external_refs as xr+ form = request.form++ participants = form.get('participants')+ if participants is not None and len(participants) > 500:+ return jsonify({'error': 'participants must be at most 500 characters', 'code': 'invalid_parameter'}), 400+ clean_refs = []+ if form.get('external_refs'):+ try:+ clean_refs = xr.validate_list(json.loads(form['external_refs']))+ except ValueError as e:+ code = getattr(e, 'code', 'invalid_parameter')+ status = getattr(e, 'status', 400)+ return jsonify({'error': str(e) if isinstance(e, xr.RefError) else 'external_refs must be JSON',+ 'code': code}), status+ key = (form.get('idempotency_key') or '').strip() or None+ if key is not None and len(key) > 100:+ return jsonify({'error': 'idempotency_key must be 1 to 100 characters', 'code': 'invalid_parameter'}), 400+ if key:+ earlier = (Recording.query+ .filter(Recording.user_id == current_user.id, Recording.upload_idempotency_key == key,+ Recording.created_at >= datetime.utcnow() - timedelta(hours=24))+ .order_by(Recording.id.desc()).first())+ if earlier is not None:+ data = earlier.to_dict(viewer_user=current_user)+ data['external_refs'] = [r.to_dict() for r in xr.refs_for(earlier.id, current_user.id)]+ data['idempotent_replay'] = True+ return jsonify(data), 200++ # Report tags and folders the upload cannot use (the pipeline drops them).+ def _usable(item):+ return item is not None and (item.user_id == current_user.id or (+ item.group_id and GroupMembership.query.filter_by(group_id=item.group_id,+ user_id=current_user.id).first()))+ asked_tags = [form.get(f'tag_ids[{i}]') for i in range(100) if form.get(f'tag_ids[{i}]')] \+ or ([form.get('tag_id')] if form.get('tag_id') else [])+ ignored_tags = []+ for raw in asked_tags:+ tag = db.session.get(Tag, int(raw)) if str(raw).isdigit() else None+ if not _usable(tag):+ ignored_tags.append(int(raw) if str(raw).isdigit() else raw)+ ignored_folder = None+ if form.get('folder_id'):+ raw = form.get('folder_id')+ folder = db.session.get(Folder, int(raw)) if str(raw).isdigit() else None+ if not _usable(folder):+ ignored_folder = int(raw) if str(raw).isdigit() else raw+ if (form.get('strict') or '').lower() == 'true' and (ignored_tags or ignored_folder is not None):+ return jsonify({'error': 'A tag or folder in the upload is not one you can use',+ 'code': 'invalid_parameter',+ 'ignored': {'tag_ids': ignored_tags, 'folder_id': ignored_folder}}), 400++ def _prepare(recording):+ if participants is not None:+ recording.participants = participants.strip() or None+ if key:+ recording.upload_idempotency_key = key+ db.session.flush()+ for clean in clean_refs:+ xr.add(recording, current_user.id, clean)++ response = ingest_uploaded_recording(owner=current_user, uploaded_file=request.files.get('file'),+ form=form, prepare=_prepare)+ body, status = (response if isinstance(response, tuple) else (response, response.status_code))+ if status in (200, 201, 202):+ data = body.get_json() or {}+ if data.get('id'):+ data['external_refs'] = [r.to_dict() for r in xr.refs_for(data['id'], current_user.id)]+ data['ignored'] = {'tag_ids': ignored_tags, 'folder_id': ignored_folder}+ return jsonify(data), status+ return responsediff --git a/src/api/recordings.py b/src/api/recordings.pyindex 966a16a0..22735e39 100644--- a/src/api/recordings.py+++ b/src/api/recordings.py@@ -2150,8 +2150,14 @@ def ingest_uploaded_recording(processing_source='upload',success_status=202,reuse_duplicate=False,+ prepare=None,):- """Run an uploaded file through Speakr's standard ingestion pipeline."""+ """Run an uploaded file through Speakr's standard ingestion pipeline.++ prepare(recording), when given, runs before the recording is first+ committed, so fields it sets (API v1 participants, references, the+ idempotency key) arrive with the recording itself.+ """try:if uploaded_file is None:return jsonify({'error': 'No file provided'}), 400@@ -2767,6 +2773,9 @@ def ingest_uploaded_recording()db.session.add(new_association)+ if prepare is not None:+ prepare(recording)+db.session.commit()if selected_tags:diff --git a/src/init_db.py b/src/init_db.pyindex 15c0ef92..b05f5195 100644--- a/src/init_db.py+++ b/src/init_db.py@@ -258,6 +258,10 @@ def _run_migrations(app, engine):run_once(engine, '0002_backfill_recording_updated_at', _backfill_recording_updated_at,logger=app.logger)+ # Idempotent API uploads (mailr spec G8).+ if add_column_if_not_exists(engine, 'recording', 'upload_idempotency_key', 'VARCHAR(100)'):+ app.logger.info("Added upload_idempotency_key column to recording table")+ create_index_if_not_exists(engine, 'ix_recording_user_idem', 'recording', 'user_id, upload_idempotency_key')if add_column_if_not_exists(engine, 'recording', 'processing_time_seconds', 'INTEGER'):app.logger.info("Added processing_time_seconds column to recording table")if add_column_if_not_exists(engine, 'recording', 'transcription_duration_seconds', 'INTEGER'):diff --git a/src/models/__init__.py b/src/models/__init__.pyindex f50713d4..7639c62b 100644--- a/src/models/__init__.py+++ b/src/models/__init__.py@@ -19,6 +19,7 @@ from .voice import VoiceEmbeddingSpace, SpeakerVoiceSamplefrom .api_token import APITokenfrom .speaker_snippet import SpeakerSnippetfrom .recording import Recording, RecordingTombstone, TranscriptChunk+from .external_ref import RecordingExternalReffrom .sharing import Share, InternalShare, SharedRecordingStatefrom .organization import Group, GroupMembership, Tag, RecordingTag, Folderfrom .events import Event@@ -61,7 +62,7 @@ __all__ = ['SpeakerSnippet',# Recording models'Recording',- 'TranscriptChunk', 'RecordingTombstone',+ 'TranscriptChunk', 'RecordingTombstone', 'RecordingExternalRef',# Sharing models'Share','InternalShare',diff --git a/src/models/external_ref.py b/src/models/external_ref.pynew file mode 100644index 00000000..c8708b4f--- /dev/null+++ b/src/models/external_ref.py@@ -0,0 +1,43 @@+"""External references: a link from a recording to an item in another system+(mailr spec G8), for example a mailr calendar event or conversation.++References are private per user: each user sees and writes only their own,+on recordings they can read.+"""++from datetime import datetime++from src.database import db+++class RecordingExternalRef(db.Model):+ __tablename__ = 'recording_external_ref'++ id = db.Column(db.Integer, primary_key=True)+ recording_id = db.Column(db.Integer, db.ForeignKey('recording.id', ondelete='CASCADE'),+ nullable=False, index=True)+ user_id = db.Column(db.Integer, db.ForeignKey('user.id', ondelete='CASCADE'), nullable=False)+ system = db.Column(db.String(40), nullable=False)+ kind = db.Column(db.String(40), nullable=False)+ ref = db.Column(db.String(500), nullable=False)+ url = db.Column(db.String(1000), nullable=True)+ label = db.Column(db.String(200), nullable=True)+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)++ __table_args__ = (+ db.UniqueConstraint('recording_id', 'user_id', 'system', 'kind', 'ref', name='uq_recording_external_ref'),+ db.Index('ix_external_ref_user_system_ref', 'user_id', 'system', 'ref'),+ )++ def to_dict(self):+ z = lambda v: v.strftime('%Y-%m-%dT%H:%M:%S.%fZ') if v else None+ return {+ 'id': self.id,+ 'system': self.system,+ 'kind': self.kind,+ 'ref': self.ref,+ 'url': self.url,+ 'label': self.label,+ 'created_at': z(self.created_at),+ }diff --git a/src/models/recording.py b/src/models/recording.pyindex 4cf212f6..48eeeb97 100644--- a/src/models/recording.py+++ b/src/models/recording.py@@ -51,6 +51,9 @@ class Recording(db.Model):# Last change a client can see (mailr spec G2); set by the before_flush# listener in src/services/recording_changes.py, never by hand.updated_at = db.Column(db.DateTime, nullable=True, index=True)+ # API upload retries (mailr spec G8): a repeat with the same key by the same+ # user within 24 hours returns this recording.+ upload_idempotency_key = db.Column(db.String(100), nullable=True)processing_time_seconds = db.Column(db.Integer, nullable=True)transcription_duration_seconds = db.Column(db.Integer, nullable=True) # Time taken for transcription# Cached audio duration in seconds, populated at transcriptiondiff --git a/src/services/external_refs.py b/src/services/external_refs.pynew file mode 100644index 00000000..fb68936c--- /dev/null+++ b/src/services/external_refs.py@@ -0,0 +1,99 @@+"""Validation and storage of external references (mailr spec G8)."""++import re++from src.database import db++MAX_PER_RECORDING = 50+_SLUG = re.compile(r'^[a-z0-9_.-]{1,40}$')+++class RefError(ValueError):+ def __init__(self, message, code='invalid_parameter', status=400):+ super().__init__(message)+ self.code = code+ self.status = status+++def validate(raw):+ """A clean ref dict from client input, or RefError."""+ if not isinstance(raw, dict):+ raise RefError('Each external reference must be an object')+ system = raw.get('system')+ kind = raw.get('kind')+ ref = raw.get('ref')+ url = raw.get('url')+ label = raw.get('label')+ if not isinstance(system, str) or not _SLUG.match(system):+ raise RefError('system must be 1 to 40 characters of a-z, 0-9, _ . -')+ if not isinstance(kind, str) or not _SLUG.match(kind):+ raise RefError('kind must be 1 to 40 characters of a-z, 0-9, _ . -')+ if not isinstance(ref, str) or not 1 <= len(ref) <= 500 or not ref.isprintable():+ raise RefError('ref must be 1 to 500 printable characters')+ if url is not None:+ if not isinstance(url, str) or len(url) > 1000 or not re.match(r'^https?://\S+$', url, re.I):+ raise RefError('url must be an http:// or https:// address of at most 1000 characters')+ if label is not None and (not isinstance(label, str) or len(label) > 200):+ raise RefError('label must be at most 200 characters')+ return {'system': system, 'kind': kind, 'ref': ref, 'url': url or None, 'label': label or None}+++def validate_list(raw_list):+ if not isinstance(raw_list, list):+ raise RefError('external_refs must be a list')+ if len(raw_list) > MAX_PER_RECORDING:+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)+ return [validate(r) for r in raw_list]+++def refs_for(recording_id, user_id):+ from src.models import RecordingExternalRef+ return (RecordingExternalRef.query.filter_by(recording_id=recording_id, user_id=user_id)+ .order_by(RecordingExternalRef.id).all())+++def refs_map(recording_ids, user_id):+ """{recording id: [ref dict]} for one page of recordings, in one query."""+ from src.models import RecordingExternalRef+ result = {rid: [] for rid in recording_ids}+ if not recording_ids:+ return result+ for ref in (RecordingExternalRef.query+ .filter(RecordingExternalRef.recording_id.in_(list(recording_ids)),+ RecordingExternalRef.user_id == user_id)+ .order_by(RecordingExternalRef.id)):+ result.setdefault(ref.recording_id, []).append(ref.to_dict())+ return result+++def add(recording, user_id, clean):+ """(ref, created). An existing (system, kind, ref) is returned unchanged."""+ from src.models import RecordingExternalRef+ existing = RecordingExternalRef.query.filter_by(+ recording_id=recording.id, user_id=user_id, system=clean['system'], kind=clean['kind'],+ ref=clean['ref']).first()+ if existing is not None:+ return existing, False+ if RecordingExternalRef.query.filter_by(recording_id=recording.id, user_id=user_id).count() >= MAX_PER_RECORDING:+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)+ row = RecordingExternalRef(recording_id=recording.id, user_id=user_id, **clean)+ db.session.add(row)+ return row, True+++def replace_system(recording, user_id, system, cleans):+ """Replace this user's refs of one system on the recording."""+ from src.models import RecordingExternalRef+ if any(c['system'] != system for c in cleans):+ raise RefError('Every reference must have the system given in ?system=')+ others = RecordingExternalRef.query.filter(+ RecordingExternalRef.recording_id == recording.id, RecordingExternalRef.user_id == user_id,+ RecordingExternalRef.system != system).count()+ unique = {(c['kind'], c['ref']): c for c in cleans}+ if others + len(unique) > MAX_PER_RECORDING:+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)+ for row in RecordingExternalRef.query.filter_by(recording_id=recording.id, user_id=user_id, system=system):+ db.session.delete(row)+ db.session.flush()+ for c in unique.values():+ db.session.add(RecordingExternalRef(recording_id=recording.id, user_id=user_id, **c))diff --git a/src/services/webhook_dispatch.py b/src/services/webhook_dispatch.pyindex cc90cd7c..7f632bfa 100644--- a/src/services/webhook_dispatch.py+++ b/src/services/webhook_dispatch.py@@ -407,7 +407,7 @@ def emit_webhook_event(user_id: int, event_type: str, data: dict, *, app=None) -return _do_enqueue()-def _with_updated_at(session, event_type, data):+def _with_updated_at(session, event_type, data, user_id=None):"""data of a recording.* event carries the recording's updated_at (spec W4)."""data = dict(data or {})if event_type.startswith('recording.') and 'updated_at' not in data and data.get('recording_id'):@@ -415,6 +415,11 @@ def _with_updated_at(session, event_type, data):rec = session.get(Recording, data['recording_id'])if rec is not None:data['updated_at'] = rec.updated_at_z()+ if event_type.startswith('recording.') and event_type != 'recording.deleted' and data.get('recording_id') \+ and 'external_refs' not in data:+ from src.models import RecordingExternalRef+ data['external_refs'] = [r.to_dict() for r in session.query(RecordingExternalRef).filter_by(+ recording_id=data['recording_id'], user_id=user_id).order_by(RecordingExternalRef.id)]return data@@ -447,7 +452,7 @@ def enqueue_event(session, user_id, event_type, data):matched = [w for w in subscriptions if event_type in w.event_list]if not matched:return 0- data = _with_updated_at(session, event_type, data)+ data = _with_updated_at(session, event_type, data, user_id)event_id = str(uuid.uuid4())first_attempt_at = datetime.utcnow()created = 0diff --git a/tests/test_api_v1_external_refs.py b/tests/test_api_v1_external_refs.pynew file mode 100644index 00000000..9a8a8fd4--- /dev/null+++ b/tests/test_api_v1_external_refs.py@@ -0,0 +1,272 @@+"""External references and the new upload fields (mailr spec G8).++A reference links a recording to an item in another system and belongs to+one user: the owner and a share recipient each see only their own. The API+upload takes participants, references, an idempotency key and strict mode.++SHARED-DB: users, tokens, tags, folders, shares, webhooks, recordings and+stored media are removed afterwards.+"""++import io+import json+import os+import secrets+import sys+from contextlib import contextmanager+from datetime import datetime, timedelta+from unittest.mock import MagicMock, patch++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import (APIToken, Folder, InternalShare, Recording, RecordingExternalRef, RecordingTag, Tag,+ User, Webhook, WebhookDelivery)+from src.utils.token_auth import hash_token++EVENT = {"system": "mailr", "kind": "event", "ref": "[email protected]@2026-10-06T15:00:00Z",+ "url": "https://mail.example.com/calendar/event/5f1c", "label": "Weekly sync (6 Oct)"}+++def world():+ with app.app_context():+ s = secrets.token_hex(4)+ owner = User(username=f"xr_{s}", email=f"xr_{s}@local.test", password="x")+ guest = User(username=f"xrg_{s}", email=f"xrg_{s}@local.test", password="x")+ db.session.add_all([owner, guest])+ db.session.commit()+ rec = Recording(user_id=owner.id, title="Sync", status="COMPLETED", original_filename="s.wav")+ mine = Tag(name=f"mine-{s}", user_id=owner.id)+ theirs = Tag(name=f"theirs-{s}", user_id=guest.id)+ folder = Folder(name=f"f-{s}", user_id=owner.id)+ db.session.add_all([rec, mine, theirs, folder])+ db.session.commit()+ db.session.add(InternalShare(recording_id=rec.id, owner_id=owner.id, shared_with_user_id=guest.id, can_edit=True))+ tokens = {}+ for who in (owner, guest):+ p = f"tok-{secrets.token_urlsafe(16)}"+ db.session.add(APIToken(user_id=who.id, token_hash=hash_token(p), name="xr"))+ tokens[who.id] = p+ db.session.commit()+ ids = dict(owner=owner.id, guest=guest.id, rec=rec.id, mine=mine.id, theirs=theirs.id, folder=folder.id,+ tokens=tokens)+ with patch("src.app.ENABLE_INTERNAL_SHARING", True):+ yield ids+ with app.app_context():+ db.session.rollback()+ users = [ids["owner"], ids["guest"]]+ recs = [r.id for r in Recording.query.filter(Recording.user_id.in_(users))]+ from src.services.storage import get_storage_service+ for r in Recording.query.filter(Recording.id.in_(recs)):+ if r.audio_path:+ try:+ get_storage_service().delete(r.audio_path, missing_ok=True)+ except Exception:+ pass+ RecordingExternalRef.query.filter(RecordingExternalRef.user_id.in_(users)).delete(synchronize_session=False)+ RecordingTag.query.filter(RecordingTag.recording_id.in_(recs)).delete(synchronize_session=False)+ InternalShare.query.filter(InternalShare.recording_id.in_(recs)).delete(synchronize_session=False)+ hooks = [w.id for w in Webhook.query.filter(Webhook.user_id.in_(users))]+ WebhookDelivery.query.filter(WebhookDelivery.webhook_id.in_(hooks)).delete(synchronize_session=False)+ Webhook.query.filter(Webhook.id.in_(hooks)).delete(synchronize_session=False)+ from src.models import ProcessingJob+ ProcessingJob.query.filter(ProcessingJob.recording_id.in_(recs)).delete(synchronize_session=False)+ Recording.query.filter(Recording.id.in_(recs)).delete(synchronize_session=False)+ Tag.query.filter(Tag.user_id.in_(users)).delete(synchronize_session=False)+ Folder.query.filter(Folder.user_id.in_(users)).delete(synchronize_session=False)+ APIToken.query.filter(APIToken.user_id.in_(users)).delete(synchronize_session=False)+ User.query.filter(User.id.in_(users)).delete(synchronize_session=False)+ db.session.commit()+++def _h(world, who="owner"):+ return {"Authorization": f"Bearer {world['tokens'][world[who]]}"}+++def _url(world, suffix=""):+ return f"/api/v1/recordings/{world['rec']}/external-refs{suffix}"+++# ------------------------------------------------------------ refs++def test_create_is_idempotent_and_listed(world):+ with app.test_client() as c:+ first = c.post(_url(world), json=EVENT, headers=_h(world))+ again = c.post(_url(world), json=EVENT, headers=_h(world))+ listed = c.get(_url(world), headers=_h(world)).get_json()["external_refs"]+ detail = c.get(f"/api/v1/recordings/{world['rec']}", headers=_h(world)).get_json()+ assert first.status_code == 201 and again.status_code == 200+ assert again.get_json()["id"] == first.get_json()["id"]+ assert [r["ref"] for r in listed] == [EVENT["ref"]] and listed[0]["created_at"].endswith("Z")+ assert [r["id"] for r in detail["external_refs"]] == [first.get_json()["id"]]+++def test_replace_by_system_and_delete(world):+ with app.test_client() as c:+ c.post(_url(world), json=dict(EVENT, system="other"), headers=_h(world))+ c.post(_url(world), json=EVENT, headers=_h(world))+ replaced = c.put(_url(world, "?system=mailr"), headers=_h(world), json={"external_refs": [+ {"system": "mailr", "kind": "conversation", "ref": "conv-1"},+ {"system": "mailr", "kind": "conversation", "ref": "conv-1"}]})+ refs = replaced.get_json()["external_refs"]+ assert replaced.status_code == 200+ assert sorted((r["system"], r["ref"]) for r in refs) == [("mailr", "conv-1"), ("other", EVENT["ref"])]+ mixed = c.put(_url(world, "?system=mailr"), headers=_h(world),+ json={"external_refs": [dict(EVENT, system="other")]})+ assert mixed.status_code == 400+ conv = next(r for r in refs if r["ref"] == "conv-1")+ assert c.delete(_url(world, f"/{conv['id']}"), headers=_h(world)).status_code == 204+ assert c.delete(_url(world, f"/{conv['id']}"), headers=_h(world)).status_code == 404+++def test_list_filter_by_ref(world):+ with app.test_client() as c:+ c.post(_url(world), json=EVENT, headers=_h(world))+ found = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}",+ headers=_h(world)).get_json()["recordings"]+ kind = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}&external_kind=conversation",+ headers=_h(world)).get_json()["recordings"]+ lone = c.get("/api/v1/recordings?external_system=mailr", headers=_h(world))+ assert [r["id"] for r in found] == [world["rec"]] and found[0]["external_refs"][0]["ref"] == EVENT["ref"]+ assert kind == [] and lone.status_code == 400+++def test_refs_are_private_per_user(world):+ with app.test_client() as c:+ assert c.post(_url(world), json=EVENT, headers=_h(world)).status_code == 201+ assert c.get(_url(world), headers=_h(world, "guest")).get_json()["external_refs"] == []+ mine = c.post(_url(world), json=dict(EVENT, ref="guest-own"), headers=_h(world, "guest")).get_json()+ assert [r["ref"] for r in c.get(_url(world), headers=_h(world)).get_json()["external_refs"]] == [EVENT["ref"]]+ owner_ref = c.get(_url(world), headers=_h(world)).get_json()["external_refs"][0]["id"]+ assert c.delete(_url(world, f"/{owner_ref}"), headers=_h(world, "guest")).status_code == 404+ assert mine["ref"] == "guest-own"+++def test_the_limit_is_fifty(world):+ with app.app_context():+ for i in range(50):+ db.session.add(RecordingExternalRef(recording_id=world["rec"], user_id=world["owner"],+ system="mailr", kind="k", ref=f"r{i}"))+ db.session.commit()+ with app.test_client() as c:+ resp = c.post(_url(world), json=EVENT, headers=_h(world))+ assert resp.status_code == 409 and resp.get_json()["code"] == "conflict"++[email protected]("bad", [+ dict(EVENT, url="javascript:alert(1)"), dict(EVENT, url="ftp://x"), dict(EVENT, system="Mailr"),+ dict(EVENT, kind=""), dict(EVENT, ref=""), dict(EVENT, ref="x" * 501), dict(EVENT, label="x" * 201),+])+def test_validation(world, bad):+ with app.test_client() as c:+ resp = c.post(_url(world), json=bad, headers=_h(world))+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"+++def test_a_ref_change_moves_updated_at_and_fires_a_webhook(world):+ with app.app_context():+ r = db.session.get(Recording, world["rec"])+ r.updated_at = datetime(2020, 1, 1)+ hook = Webhook(user_id=world["owner"], name="m", url="https://example.com/h", secret="s" * 40,+ events=json.dumps(["recording.updated"]))+ db.session.add(hook)+ db.session.commit()+ hook_id = hook.id+ with app.test_client() as c:+ c.post(_url(world), json=EVENT, headers=_h(world))+ with app.app_context():+ assert db.session.get(Recording, world["rec"]).updated_at > datetime(2025, 1, 1)+ payloads = [json.loads(d.payload)["data"] for d in WebhookDelivery.query.filter_by(webhook_id=hook_id)]+ assert [p["fields_changed"] for p in payloads] == [["external_refs"]]+ assert [x["ref"] for x in payloads[0]["external_refs"]] == [EVENT["ref"]]+++# ------------------------------------------------------------ upload++@contextmanager+def _no_media_tools():+ def _convert(filepath, **kwargs):+ r = MagicMock()+ r.output_path = filepath+ r.was_converted = r.was_compressed = False+ r.original_codec = r.final_codec = "opus"+ r.size_reduction_percent = 0.0+ return r+ with patch("src.api.recordings.convert_if_needed", side_effect=_convert), \+ patch("src.api.recordings.get_codec_info",+ return_value={"has_video": False, "audio_codec": "opus", "video_codec": None, "duration": 5.0}), \+ patch("src.api.recordings.get_duration", return_value=5.0), \+ patch("src.api.recordings.get_creation_date", return_value=None), \+ patch("src.services.job_queue.job_queue.enqueue", return_value=1) as enqueue:+ yield enqueue+++def _upload(world, who="owner", payload=b"audio", **fields):+ data = {"file": (io.BytesIO(payload + secrets.token_bytes(8)), "memo.webm")}+ data.update(fields)+ with app.test_client() as c:+ return c.post("/api/v1/recordings/upload", data=data, headers=_h(world, who),+ content_type="multipart/form-data")+++def test_an_upload_with_every_field(world):+ with _no_media_tools():+ resp = _upload(world, title="Weekly sync", participants="Dana, Omar", meeting_date="2026-10-06T15:00:00Z",+ folder_id=str(world["folder"]), **{"tag_ids[0]": str(world["mine"])},+ external_refs=json.dumps([EVENT]), idempotency_key="msg-1:part-2")+ body = resp.get_json()+ assert resp.status_code == 202, body+ assert body["ignored"] == {"tag_ids": [], "folder_id": None}+ assert [r["ref"] for r in body["external_refs"]] == [EVENT["ref"]]+ with app.test_client() as c:+ listed = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}",+ headers=_h(world)).get_json()["recordings"]+ item = next(r for r in listed if r["id"] == body["id"])+ assert (item["title"], item["participants"], item["folder_id"]) == ("Weekly sync", "Dana, Omar", world["folder"])+ assert item["meeting_date"].startswith("2026-10-06T15:00:00") and [t["id"] for t in item["tags"]] == [world["mine"]]+++def test_a_repeat_with_the_same_key_creates_nothing(world):+ with _no_media_tools() as enqueue:+ first = _upload(world, idempotency_key="msg-9")+ second = _upload(world, idempotency_key="msg-9")+ assert enqueue.call_count == 1+ assert second.status_code == 200 and second.get_json()["idempotent_replay"] is True+ assert second.get_json()["id"] == first.get_json()["id"]+ with app.app_context():+ assert Recording.query.filter_by(user_id=world["owner"], upload_idempotency_key="msg-9").count() == 1+ with _no_media_tools():+ other_user = _upload(world, who="guest", idempotency_key="msg-9")+ assert other_user.get_json()["id"] != first.get_json()["id"]+++def test_an_old_key_does_not_replay(world):+ with _no_media_tools():+ first = _upload(world, idempotency_key="msg-old")+ with app.app_context():+ r = db.session.get(Recording, first.get_json()["id"])+ r.created_at = datetime.utcnow() - timedelta(hours=25)+ db.session.commit()+ with _no_media_tools():+ second = _upload(world, idempotency_key="msg-old")+ assert second.status_code == 202 and second.get_json()["id"] != first.get_json()["id"]+++def test_strict_and_lenient_tags(world):+ with _no_media_tools():+ strict = _upload(world, strict="true", **{"tag_ids[0]": str(world["theirs"])})+ lenient = _upload(world, **{"tag_ids[0]": str(world["theirs"]), "tag_ids[1]": str(world["mine"])})+ assert strict.status_code == 400 and strict.get_json()["ignored"]["tag_ids"] == [world["theirs"]]+ assert lenient.status_code == 202 and lenient.get_json()["ignored"]["tag_ids"] == [world["theirs"]]++[email protected]("fields", [{"participants": "x" * 501}, {"external_refs": "not json"},+ {"external_refs": json.dumps([dict(EVENT, url="javascript:x")])},+ {"idempotency_key": "k" * 101}])+def test_bad_upload_fields(world, fields):+ with _no_media_tools():+ resp = _upload(world, **fields)+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"diff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.pyindex 95c23467..5e39cb47 100644--- a/tests/test_api_v1_scope_coverage.py+++ b/tests/test_api_v1_scope_coverage.py@@ -13,11 +13,11 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))from src.app import appEXPECTED = {- "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "search_recordings_v1", "get_recording",+ "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "search_recordings_v1", "list_external_refs", "get_recording","get_transcript", "get_summary", "get_notes", "get_recording_status", "list_tags", "list_folders","get_folder", "get_transcription_info", "list_speakers", "get_recording_speakers","get_recording_events", "download_events_ics", "download_audio"},- "write": {"update_recording", "replace_notes", "replace_summary", "create_tag", "update_tag",+ "write": {"add_external_ref", "replace_external_refs", "delete_external_ref", "update_recording", "replace_notes", "replace_summary", "create_tag", "update_tag","add_tags_to_recording", "remove_tag_from_recording", "create_folder", "update_folder","create_speaker", "update_speaker", "assign_speakers", "batch_update_recordings"},"account": {"update_auto_summarization"},diff --git a/tests/test_upgrade_mailr_api.py b/tests/test_upgrade_mailr_api.pyindex 409c10dc..57bc3a07 100644--- a/tests/test_upgrade_mailr_api.py+++ b/tests/test_upgrade_mailr_api.py@@ -137,3 +137,17 @@ def test_webhook_rotation_grace_columns(tmp_path, fixture):con.close()assert row == ("s" * 40, None, None)+[email protected]("fixture", FIXTURES, ids=[f[:-4] for f in FIXTURES])+def test_upload_idempotency_and_external_refs(tmp_path, fixture):+ """G8: the idempotency column and index, and the reference table."""+ db_path, con = _load(tmp_path, fixture)+ con.close()+ _upgrade(db_path)+ _upgrade(db_path)+ con = sqlite3.connect(db_path)+ assert "upload_idempotency_key" in _columns(con, "recording")+ assert "ix_recording_user_idem" in {r[1] for r in con.execute("PRAGMA index_list('recording')")}+ assert {"recording_id", "user_id", "system", "kind", "ref", "url", "label"} <= _columns(con, "recording_external_ref")+ con.close()+