Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.
Ruby agplai-assistantdockerdsgvogdprhotwireissue-trackerjira-alternativeknowledge-basellmmcp-servermeeting-notesopen-sourceproject-managementredmine-alternativeruby-on-railsself-hostedticketingtime-tracking
feat: read meetings over REST (R8)
Guido Boyke6b10145edf13
diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.ymlindex 2714fdd..c77a87d 100644--- a/.github/workflows/guards.yml+++ b/.github/workflows/guards.yml@@ -305,6 +305,7 @@ jobs:spec/requests/api/v1/comment_files_spec.rbspec/requests/api/v1/people_spec.rbspec/requests/api/v1/meetings_spec.rb+ spec/requests/api/v1/meetings_read_spec.rbspec/requests/api/people_parity_spec.rbspec/requests/api/v1/post_comment_format_spec.rbspec/requests/api/v1/ticket_changes_spec.rbdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3923f64..dfa012d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,6 +18,12 @@ starts (`db:prepare lalabase:data_backfills`). Without Docker, run## [Unreleased]+### Added++- The REST API reads meetings: `GET /api/v1/projects/:project_id/meetings` with search and+ pages, and `GET /api/v1/meetings/:id` with participants, summary, notes and transcript.+ API version 1.10.0.+### Changed- Synced documentation pages show their images from your instance. The sync copies themdiff --git a/CLAUDE.md b/CLAUDE.mdindex c0a9b4a..ac2805d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -907,6 +907,23 @@ reads no rows. The project gate is MCP's (token reach and `ProjectAccessService`malformed, beyond the reach, not openable (an archived project for a non-admin included) and foreign answer the same 404.Guards: `spec/requests/api/v1/knowledge_spec.rb`, `spec/services/knowledge/lookup_spec.rb`.+`GET /api/v1/projects/:project_id/meetings` and `GET /api/v1/meetings/:id` (REST R8, 2026-11-03,+API 1.10.0, capabilities `meetings.list`, `meetings.show`; no MCP tool) read a project's meetings+and one meeting. Fields are `Meetings::Serializer`'s two allowlists: a row has no text of the+meeting, the whole answer adds `participants` (names only), `generated_summary` (Markdown),+`notes`, `transcript` (uncut, a leading metadata block left off as on the web), `updated_at`,+`path`. No analyses, ticket suggestions or linked tickets: each has a visibility rule of its own.+The list runs `Meetings::ListQuery`, the web list's order (`occurred_at`, then the entry time,+then `id`, all newest first) and `Meeting.search_by_content`, on `policy_scope(project.meetings)`+and nowhere else, because the search matches inside transcripts. Paging and `q` by the strict+rule of knowledge, before the project (a 422 says nothing about it). The list's gate is+`Api::V1::ReadableProject`, shared with knowledge; a reader without the meetings area gets an+empty list. `Api::V1::ReadableMeeting` answers one 404 in status and body for missing, malformed,+out of reach, foreign and no area, and turns a policy refusal into that 404 as well: unlike a+ticket, a meeting never answers 403. An archived project is the web's: closed to a member (scope+alone would let them in, `show?` keeps them out), open to an account admin. Guard:+`spec/requests/api/v1/meetings_read_spec.rb`.+`GET /api/v1/organisations/:organisation_id/people` and `.../people/:id` (People S3b) readthe people directory through `People::Lookup`, the object the assistant's `find_people` /`get_person` and their MCP twins read as well: one rights question (the people right, 403diff --git a/app/controllers/api/v1/knowledge_controller.rb b/app/controllers/api/v1/knowledge_controller.rbindex b252fd5..dc2db12 100644--- a/app/controllers/api/v1/knowledge_controller.rb+++ b/app/controllers/api/v1/knowledge_controller.rb@@ -18,6 +18,8 @@ module Api# beyond the reach, one the owner cannot open and one of another organisation answer the# same 404. A reader who may open the project but read no knowledge gets an empty list.class KnowledgeController < BaseController+ include ReadableProject+rescue_from Knowledge::Lookup::InvalidOption, with: :invalid_input# GET /api/v1/projects/:project_id/knowledge?q=&type=&page=&per_page=@@ -41,16 +43,6 @@ module Api%i[q type page per_page].index_with { |key| params[key] }end- def readable_project(id)- project = ActsAsTenant.without_tenant { Project.find_by(id: id) } if id.present?- raise ActiveRecord::RecordNotFound unless project && current_token.accessible_project?(project)-- ActsAsTenant.with_tenant(project.organisation) do- raise ActiveRecord::RecordNotFound unless AccessCheck::ProjectAccessService.can_access_project?(current_user, project)- end- project- end-def invalid_input(exception)render_error(error: 'invalid_input', code: 'invalid_input', message: exception.message,status: :unprocessable_content)diff --git a/app/controllers/api/v1/meetings_controller.rb b/app/controllers/api/v1/meetings_controller.rbindex 5f8837e..f2c07b8 100644--- a/app/controllers/api/v1/meetings_controller.rb+++ b/app/controllers/api/v1/meetings_controller.rb@@ -7,9 +7,45 @@ module Api# Under the organisation, not the project: the project may be missing, the# meeting then lands in the inbox. The rule is Meetings::Intake, shared with# the MCP tool create_meeting; the write is Actors::SaveMeeting.+ #+ # GET /api/v1/projects/:project_id/meetings and GET /api/v1/meetings/:id (REST R8)+ # read through the web list's Meetings::ListQuery and Api::V1::ReadableMeeting; the+ # fields are Meetings::Serializer's.+ #+ # * Paging and `q` by Knowledge::Lookup's strict rule, one rule for REST lists of a+ # project: no whole number from 1 to the maximum (per_page at most 100) and a NUL in+ # `q` are a 422, an absent or empty value the default, checked before the project, so+ # the 422 does not depend on whether it exists.+ # * The search matches inside transcripts, so it runs on the policy scope and nowhere+ # else. A reader who may open the project but read no meetings gets an empty list.class MeetingsController < BaseController+ include ReadableMeeting+ include ReadableProject++ rescue_from Knowledge::Lookup::InvalidOption, with: :invalid_input+idempotent :create+ def index+ # Read raw, not through strong parameters: those would drop a list and let a+ # malformed request through as "no search".+ options = Knowledge::Lookup.options(%i[q page per_page].index_with { |key| params[key] }, strict: true)+ project = readable_project(params[:project_id])++ ActsAsTenant.with_tenant(project.organisation) do+ rows = Meetings::ListQuery.call(scope: policy_scope(project.meetings), search: options.query)+ total = rows.count(:all)+ render json: { data: page_of(rows, options, total).map { |meeting| Meetings::Serializer.summary(meeting) },+ meta: { page: options.page, per_page: options.per_page, total: total } }+ end+ end++ def show+ with_readable_meeting(params[:id]) do |meeting|+ render json: { data: Meetings::Serializer.full(meeting) }+ end+ end+def createorganisation = Organisation.find(params[:organisation_id])@@ -28,6 +64,19 @@ module Apiprivate+ # A page beyond the total reads no rows.+ def page_of(rows, options, total)+ offset = (options.page - 1) * options.per_page+ return [] if offset >= total++ rows.limit(options.per_page).offset(offset)+ end++ def invalid_input(exception)+ render_error(error: 'invalid_input', code: 'invalid_input', message: exception.message,+ status: :unprocessable_content)+ end+def answer(intake)result = intake.savereturn render json: { data: Meetings::Intake.summary(intake.meeting) }, status: :created if result.success?diff --git a/app/controllers/concerns/api/v1/readable_meeting.rb b/app/controllers/concerns/api/v1/readable_meeting.rbnew file mode 100644index 0000000..ce9c3f4--- /dev/null+++ b/app/controllers/concerns/api/v1/readable_meeting.rb@@ -0,0 +1,46 @@+# frozen_string_literal: true++module Api+ module V1+ # One read gate for a single meeting (REST R8). Missing, malformed, beyond the token's+ # reach, of another organisation, no read right in the meetings area: the same+ # RecordNotFound, so the same 404 in status and body.+ #+ # A policy refusal is a 404 as well, never the 403 ReadableTicket leaves to the base+ # controller: a transcript is what people said, and a 403 would say the meeting exists.+ #+ # The tenant is unknown at first, so discovery reads only organisation_id and project_id+ # without a tenant, and the row itself is read inside the tenant, through the policy+ # scope. Query counts differ for a missing and a hidden meeting: ids are random UUIDs,+ # and the contract is equal status and body, not equal timing.+ #+ # The project_id from discovery stays in the condition: a meeting that moves in between+ # is gone from the project whose reach was checked, and answers the 404.+ module ReadableMeeting+ extend ActiveSupport::Concern++ private++ def with_readable_meeting(id)+ raise ActiveRecord::RecordNotFound if id.blank?++ organisation_id, project_id = ActsAsTenant.without_tenant { Meeting.where(id: id).pick(:organisation_id, :project_id) }+ raise ActiveRecord::RecordNotFound unless organisation_id++ ActsAsTenant.with_tenant(Organisation.find(organisation_id)) do+ yield read_meeting(id, project_id)+ end+ end++ def read_meeting(id, project_id)+ raise ActiveRecord::RecordNotFound unless current_token.accessible_project?(Project.find_by(id: project_id))++ meeting = policy_scope(Meeting.where(id: id, project_id: project_id)).preload(:creator, :meeting_participants).take!+ authorize meeting, :show?+ meeting+ rescue Pundit::NotAuthorizedError+ raise ActiveRecord::RecordNotFound+ end+ end+ end+enddiff --git a/app/controllers/concerns/api/v1/readable_project.rb b/app/controllers/concerns/api/v1/readable_project.rbnew file mode 100644index 0000000..96200f0--- /dev/null+++ b/app/controllers/concerns/api/v1/readable_project.rb@@ -0,0 +1,27 @@+# frozen_string_literal: true++module Api+ module V1+ # The project gate of a list inside one project (knowledge, meetings), the one of MCP+ # (Mcp::ToolCall#authorized_project): the token's reach and the owner's access to the+ # project. A missing project, a malformed id, a project beyond the reach, one the owner+ # cannot open (an archived one for a non-admin) and one of another organisation raise+ # the same RecordNotFound, so they answer the same 404. What the reader sees inside the+ # project stays with the rows' policy scope.+ module ReadableProject+ extend ActiveSupport::Concern++ private++ def readable_project(id)+ project = ActsAsTenant.without_tenant { Project.find_by(id: id) } if id.present?+ raise ActiveRecord::RecordNotFound unless project && current_token.accessible_project?(project)++ ActsAsTenant.with_tenant(project.organisation) do+ raise ActiveRecord::RecordNotFound unless AccessCheck::ProjectAccessService.can_access_project?(current_user, project)+ end+ project+ end+ end+ end+enddiff --git a/app/services/api/v1/capabilities.rb b/app/services/api/v1/capabilities.rbindex a0d99bc..95e3d9b 100644--- a/app/services/api/v1/capabilities.rb+++ b/app/services/api/v1/capabilities.rb@@ -20,8 +20,9 @@ module Api# knowledge.search (R2); 1.7.0 adds tickets.changes (R3b); 1.8.0 adds a# comment's attachments (R7), a field and no capability: a client takes# its presence as the signal; 1.9.0 adds meetings.create and the field- # meeting_inbox on projects.list.- API_VERSION = '1.9.0'+ # meeting_inbox on projects.list; 1.10.0 adds meetings.list and meetings.show+ # (R8).+ API_VERSION = '1.10.0'# name => [verb, path as the router spells it]ENDPOINTS = {@@ -33,6 +34,8 @@ module Api'projects.list' => ['GET', '/api/v1/projects'],'projects.ticket_attribute_definitions' => ['GET', '/api/v1/projects/:id/ticket_attribute_definitions'],'knowledge.search' => ['GET', '/api/v1/projects/:project_id/knowledge'],+ 'meetings.list' => ['GET', '/api/v1/projects/:project_id/meetings'],+ 'meetings.show' => ['GET', '/api/v1/meetings/:id'],'tickets.list' => ['GET', '/api/v1/projects/:project_id/tickets'],'tickets.create' => ['POST', '/api/v1/projects/:project_id/tickets'],'tickets.by_number' => ['GET', '/api/v1/projects/:project_id/tickets/number/:number'],diff --git a/app/services/meetings/serializer.rb b/app/services/meetings/serializer.rbnew file mode 100644index 0000000..eb7d88c--- /dev/null+++ b/app/services/meetings/serializer.rb@@ -0,0 +1,46 @@+# frozen_string_literal: true++# What a program reads of a meeting (REST R8): a row of the list and the whole meeting.+#+# Both are allowlists, so a new column stays inside until somebody names it here: no+# create_embeddings, no *_flag, no *_error, no plain_text_version. Analyses, ticket+# suggestions and linked tickets have visibility rules of their own and are not part of+# this answer. A row carries no text of the meeting: the list selects only+# Meetings::ListQuery::LIST_COLUMNS, and a transcript is up to 1 MB per row.+#+# Formats: generated_summary is Markdown, the LLM answers in it; notes and transcript are+# text a person pasted, and the web renders them as Markdown too. Nothing is cut. All three+# are foreign text for whoever shows them. A leading metadata block is left off notes and+# transcript as on the web (Meeting.strip_frontmatter); the stored value stays.+#+# Entry point: summary, full+module Meetings+ module Serializer+ def self.summary(meeting)+ {+ id: meeting.id,+ project_id: meeting.project_id,+ title: meeting.title,+ occurred_at: meeting.occurred_at.iso8601,+ duration_minutes: meeting.duration_minutes,+ creator: { id: meeting.creator_id, name: meeting.creator&.display_name }+ }+ end++ # The caller preloads creator and meeting_participants. sort_by, not in_row_order: a+ # scope would ask the database again.+ def self.full(meeting)+ summary(meeting).merge(+ participants: meeting.meeting_participants.sort_by(&:created_at)+ .map { |participant| { display_name: participant.display_name } },+ generated_summary: meeting.generated_summary,+ notes: Meeting.strip_frontmatter(meeting.notes),+ transcript: Meeting.strip_frontmatter(meeting.transcript),+ updated_at: meeting.updated_at.iso8601,+ path: Rails.application.routes.url_helpers.organisation_project_meeting_path(+ meeting.organisation_id, meeting.project_id, meeting+ )+ )+ end+ end+enddiff --git a/config/routes.rb b/config/routes.rbindex e25bf38..d0cdcdf 100644--- a/config/routes.rb+++ b/config/routes.rb@@ -943,7 +943,11 @@ Rails.application.routes.draw doget :ticket_attribute_definitions, on: :member# REST R2: the project's notes and documents by title, read only.resources :knowledge, only: %i[index], controller: 'knowledge'+ # REST R8: the project's meetings, read only.+ resources :meetings, only: %i[index]end+ # REST R8: one meeting, read only, by its own id like a ticket.+ resources :meetings, only: %i[show]resources :tickets, only: %i[show update] domember doget :activitiesdiff --git a/spec/contracts/mcp_contract_recorder.rb b/spec/contracts/mcp_contract_recorder.rbindex bf6bee2..b3f3ba4 100644--- a/spec/contracts/mcp_contract_recorder.rb+++ b/spec/contracts/mcp_contract_recorder.rb@@ -111,6 +111,7 @@ module McpContractunread_notification: 71, read_notification: 72, archived_notification: 73,write_token: 81, read_token: 82, deactivated_token: 83, limited_token: 84, dora_token: 85,doris_person: 91, ben_person: 92,+ kickoff_meeting: 101, review_meeting: 102, hidden_meeting: 103, internal_meeting: 104, foreign_meeting: 105,missing: 999}.transform_values { |n| format('00000000-0000-4000-8000-%012d', n) }.freeze@@ -619,7 +620,10 @@ module McpContract'GET /api/v1/projects/:project_id/knowledge' => rest_knowledge_calls,# REST R3b, appended last: it changes the export and the login ticket# after every answer above, without advancing the clock.- 'POST /api/v1/tickets/:id/changes' => rest_ticket_change_calls+ 'POST /api/v1/tickets/:id/changes' => rest_ticket_change_calls,+ # REST R8, appended last: reads only, over meetings made right before them.+ 'GET /api/v1/projects/:project_id/meetings' => rest_meeting_list_calls,+ 'GET /api/v1/meetings/:id' => rest_meeting_show_calls}end@@ -662,6 +666,74 @@ module McpContract}end+ # The meetings the answers read. Made once, right before the first of them, without+ # `record`: no clock moves for anything recorded later. Anna reads the meetings of the+ # website and of the internal project (her limited token reaches only the website) and+ # none of the handbook, where she only reads notes.+ def meeting_world+ @meeting_world ||= begin+ people_world+ in_org do+ ProjectPermission.find_by!(user: @anna, project: @website).update!(meetings_access: :read_only)+ ProjectPermission.find_by!(user: @anna, project: @internal).update!(meetings_access: :read_only)+ kickoff = create(:meeting, id: id(:kickoff_meeting), project: @website, organisation: @organisation, creator: @anna,+ title: 'Kickoff Relaunch', occurred_at: START - 1.day, duration_minutes: 45,+ notes: 'Termin im März halten.', transcript: 'Anna: Wir starten im März.',+ generated_summary: '**Ergebnis:** Start im März.')+ create(:meeting_participant, meeting: kickoff, organisation: @organisation, user: @anna, display_name: 'Anna Albers')+ create(:meeting_participant, meeting: kickoff, organisation: @organisation, display_name: 'Erika Beispiel',+ created_at: Time.current + 1.second)+ create(:meeting, id: id(:review_meeting), project: @website, organisation: @organisation, creator: @ben,+ title: 'Kurze Abstimmung', occurred_at: START - 2.days)+ create(:meeting, id: id(:hidden_meeting), project: @handbook, organisation: @organisation, creator: @anna,+ title: 'Vertrauliches Gespräch', occurred_at: START - 3.days, transcript: 'Nicht für Notiz-Leser.')+ create(:meeting, id: id(:internal_meeting), project: @internal, organisation: @organisation, creator: @anna,+ title: 'Interne Runde', occurred_at: START - 4.days)+ end+ ActsAsTenant.with_tenant(@other_organisation) do+ create(:meeting, id: id(:foreign_meeting), project: @foreign_project, organisation: @other_organisation, creator: @ben,+ title: 'Fremdes Gespräch', occurred_at: START - 5.days)+ end+ true+ end+ end++ def rest_meeting_list_calls+ meeting_world+ # Spelled out, not a loop: each request from its own line (Prosopite).+ path = "/api/v1/projects/#{id(:website)}/meetings"+ {+ 'ok' => rest_get(:read, path),+ 'ok_search' => rest_get(:read, "#{path}?q=M%C3%A4rz"),+ 'ok_page' => rest_get(:read, "#{path}?page=2&per_page=1"),+ 'empty' => rest_get(:read, "#{path}?q=Gibt%20es%20nicht"),+ # The reader opens the project but reads no meetings there.+ 'empty_no_area' => rest_get(:read, "/api/v1/projects/#{id(:handbook)}/meetings"),+ 'invalid_input_per_page' => rest_get(:read, "#{path}?per_page=101"),+ 'invalid_input_page' => rest_get(:read, "#{path}?page=0"),+ 'not_found' => rest_get(:read, "/api/v1/projects/#{id(:foreign_project)}/meetings"),+ 'not_found_reach' => rest_get(:limited, "/api/v1/projects/#{id(:internal)}/meetings"),+ 'unauthorized' => rest_get(nil, path)+ }+ end++ def rest_meeting_show_calls+ meeting_world+ path = ->(meeting) { "/api/v1/meetings/#{id(meeting)}" }+ {+ 'ok' => rest_get(:read, path.call(:kickoff_meeting)),+ # No duration, no notes, no transcript, no summary, nobody named.+ 'ok_bare' => rest_get(:read, path.call(:review_meeting)),+ 'not_found' => rest_get(:read, path.call(:missing)),+ 'not_found_malformed' => rest_get(:read, '/api/v1/meetings/not-a-uuid'),+ # All of these answer exactly like the missing one.+ 'not_found_no_area' => rest_get(:read, path.call(:hidden_meeting)),+ 'not_found_reach' => rest_get(:limited, path.call(:internal_meeting)),+ 'not_found_foreign' => rest_get(:read, path.call(:foreign_meeting)),+ 'unauthorized' => rest_get(nil, path.call(:kickoff_meeting))+ }+ end+def rest_knowledge_calls# Spelled out, not a loop: each request from its own line (Prosopite).path = "/api/v1/projects/#{id(:website)}/knowledge"diff --git a/spec/fixtures/mcp_contract.json b/spec/fixtures/mcp_contract.jsonindex 6aa0dec..ccfa83d 100644--- a/spec/fixtures/mcp_contract.json+++ b/spec/fixtures/mcp_contract.json@@ -1,9 +1,9 @@{"header": {"regenerate": "RAILS_ENV=test bin/rails mcp:contract",- "core_commit": "9d5713e64258818e8a30252d744c23f2c2862643",- "core_dirty": false,- "contract_sha256": "3c2a9bb917338f78ae481cd9d2d5d294d2da4993e201186af2a7c6bedad82d1c"+ "core_commit": "49391c5b10ddbdfbbb3141520b8c6faece429b5f",+ "core_dirty": true,+ "contract_sha256": "5c6489e822b85cfec1fb37099088ac4ae3b4b524c1b3185d275a421ccde75ef3"},"contract": {"mcp": {@@ -4350,13 +4350,15 @@"all_projects": true}],- "api_version": "1.9.0",+ "api_version": "1.10.0","capabilities": ["error_codes","idempotency","knowledge.search","me.show","meetings.create",+ "meetings.list",+ "meetings.show","notifications.archive","notifications.list","notifications.mark_all_as_read",@@ -4417,13 +4419,15 @@"all_projects": true}],- "api_version": "1.9.0",+ "api_version": "1.10.0","capabilities": ["error_codes","idempotency","knowledge.search","me.show","meetings.create",+ "meetings.list",+ "meetings.show","notifications.archive","notifications.list","notifications.mark_all_as_read",@@ -7406,6 +7410,350 @@}}}+ },+ "GET /api/v1/projects/:project_id/meetings": {+ "ok": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings"+ },+ "response": {+ "status": 200,+ "body": {+ "data": [+ {+ "id": "00000000-0000-4000-8000-000000000101",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kickoff Relaunch",+ "occurred_at": "2026-01-04T09:00:00Z",+ "duration_minutes": 45,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000011",+ "name": "Anna Albers"+ }+ },+ {+ "id": "00000000-0000-4000-8000-000000000102",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kurze Abstimmung",+ "occurred_at": "2026-01-03T09:00:00Z",+ "duration_minutes": null,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000012",+ "name": "Ben Berger"+ }+ }+ ],+ "meta": {+ "page": 1,+ "per_page": 10,+ "total": 2+ }+ }+ }+ },+ "ok_search": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings?q=M%C3%A4rz"+ },+ "response": {+ "status": 200,+ "body": {+ "data": [+ {+ "id": "00000000-0000-4000-8000-000000000101",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kickoff Relaunch",+ "occurred_at": "2026-01-04T09:00:00Z",+ "duration_minutes": 45,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000011",+ "name": "Anna Albers"+ }+ }+ ],+ "meta": {+ "page": 1,+ "per_page": 10,+ "total": 1+ }+ }+ }+ },+ "ok_page": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings?page=2&per_page=1"+ },+ "response": {+ "status": 200,+ "body": {+ "data": [+ {+ "id": "00000000-0000-4000-8000-000000000102",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kurze Abstimmung",+ "occurred_at": "2026-01-03T09:00:00Z",+ "duration_minutes": null,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000012",+ "name": "Ben Berger"+ }+ }+ ],+ "meta": {+ "page": 2,+ "per_page": 1,+ "total": 2+ }+ }+ }+ },+ "empty": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings?q=Gibt%20es%20nicht"+ },+ "response": {+ "status": 200,+ "body": {+ "data": [],+ "meta": {+ "page": 1,+ "per_page": 10,+ "total": 0+ }+ }+ }+ },+ "empty_no_area": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000033/meetings"+ },+ "response": {+ "status": 200,+ "body": {+ "data": [],+ "meta": {+ "page": 1,+ "per_page": 10,+ "total": 0+ }+ }+ }+ },+ "invalid_input_per_page": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings?per_page=101"+ },+ "response": {+ "status": 422,+ "body": {+ "error": "invalid_input",+ "code": "invalid_input",+ "message": "per_page must be a whole number from 1 to 100"+ }+ }+ },+ "invalid_input_page": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings?page=0"+ },+ "response": {+ "status": 422,+ "body": {+ "error": "invalid_input",+ "code": "invalid_input",+ "message": "page must be a whole number from 1 to 100000"+ }+ }+ },+ "not_found": {+ "token": "read",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000034/meetings"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "not_found_reach": {+ "token": "limited",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000032/meetings"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "unauthorized": {+ "token": "invalid",+ "request": {+ "path": "/api/v1/projects/00000000-0000-4000-8000-000000000031/meetings"+ },+ "response": {+ "status": 401,+ "body": {+ "error": "unauthorized",+ "code": "unauthorized"+ }+ }+ }+ },+ "GET /api/v1/meetings/:id": {+ "ok": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000101"+ },+ "response": {+ "status": 200,+ "body": {+ "data": {+ "id": "00000000-0000-4000-8000-000000000101",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kickoff Relaunch",+ "occurred_at": "2026-01-04T09:00:00Z",+ "duration_minutes": 45,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000011",+ "name": "Anna Albers"+ },+ "participants": [+ {+ "display_name": "Anna Albers"+ },+ {+ "display_name": "Erika Beispiel"+ }+ ],+ "generated_summary": "**Ergebnis:** Start im März.",+ "notes": "Termin im März halten.",+ "transcript": "Anna: Wir starten im März.",+ "updated_at": "2026-01-05T09:36:00Z",+ "path": "/org/00000000-0000-4000-8000-000000000001/projects/00000000-0000-4000-8000-000000000031/meetings/00000000-0000-4000-8000-000000000101"+ }+ }+ }+ },+ "ok_bare": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000102"+ },+ "response": {+ "status": 200,+ "body": {+ "data": {+ "id": "00000000-0000-4000-8000-000000000102",+ "project_id": "00000000-0000-4000-8000-000000000031",+ "title": "Kurze Abstimmung",+ "occurred_at": "2026-01-03T09:00:00Z",+ "duration_minutes": null,+ "creator": {+ "id": "00000000-0000-4000-8000-000000000012",+ "name": "Ben Berger"+ },+ "participants": [],+ "generated_summary": "",+ "notes": null,+ "transcript": null,+ "updated_at": "2026-01-05T09:36:00Z",+ "path": "/org/00000000-0000-4000-8000-000000000001/projects/00000000-0000-4000-8000-000000000031/meetings/00000000-0000-4000-8000-000000000102"+ }+ }+ }+ },+ "not_found": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000999"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "not_found_malformed": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/not-a-uuid"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "not_found_no_area": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000103"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "not_found_reach": {+ "token": "limited",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000104"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "not_found_foreign": {+ "token": "read",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000105"+ },+ "response": {+ "status": 404,+ "body": {+ "error": "not_found",+ "code": "not_found"+ }+ }+ },+ "unauthorized": {+ "token": "invalid",+ "request": {+ "path": "/api/v1/meetings/00000000-0000-4000-8000-000000000101"+ },+ "response": {+ "status": 401,+ "body": {+ "error": "unauthorized",+ "code": "unauthorized"+ }+ }+ }}}}diff --git a/spec/requests/api/v1/capabilities_spec.rb b/spec/requests/api/v1/capabilities_spec.rbindex a150e88..68f6a85 100644--- a/spec/requests/api/v1/capabilities_spec.rb+++ b/spec/requests/api/v1/capabilities_spec.rb@@ -33,7 +33,7 @@ RSpec.describe 'API V1 capabilities', :ci_guard, type: :request doit 'names the API version and the capabilities beside the existing fields' dodata = me(token(read_only: false))- expect(data['api_version']).to eq('1.9.0')+ expect(data['api_version']).to eq('1.10.0')expect(data['capabilities']).to eq(Api::V1::Capabilities.names)expect(data.keys).to include('user', 'token', 'scoped_organisations')end@@ -48,7 +48,7 @@ RSpec.describe 'API V1 capabilities', :ci_guard, type: :request do'tickets.update', 'tickets.attachments', 'posts.create', 'time_sessions.create','notifications.list', 'notifications.mark_as_read', 'people.list', 'people.show', 'idempotency', 'error_codes','meetings.create', 'tickets.by_number', 'posts.show', 'tickets.paging', 'time_sessions.book', 'posts.plain', 'knowledge.search',- 'tickets.changes'+ 'tickets.changes', 'meetings.list', 'meetings.show')enddiff --git a/spec/requests/api/v1/meetings_read_spec.rb b/spec/requests/api/v1/meetings_read_spec.rbnew file mode 100644index 0000000..89d2250--- /dev/null+++ b/spec/requests/api/v1/meetings_read_spec.rb@@ -0,0 +1,432 @@+# frozen_string_literal: true++require 'rails_helper'++# REST R8: GET /api/v1/projects/:project_id/meetings and GET /api/v1/meetings/:id, a meeting+# for a program such as the terminal client.+#+# What: the rows of a project, newest first, searched by Meeting.search_by_content, and one+# meeting whole, with its transcript.+# Why: this is a new read of what people said, behind a token. No answer may tell a meeting+# that exists from one that does not, the search may never reach a meeting the reader+# cannot read (it matches inside transcripts), and nothing internal leaves the server.+RSpec.describe 'REST meetings', :ci_guard, type: :request do+ let(:organisation) { create(:organisation) }+ let(:role) { ActsAsTenant.with_tenant(organisation) { create(:role, organisation: organisation) } }+ let(:project) { new_project }+ let(:creator) { member(meetings: 'read_write', first_name: 'Clara', last_name: 'Creator') }+ let(:reader) { member }+ let(:not_found_body) { { error: 'not_found', code: 'not_found' }.to_json }++ def quietly(&) = Prosopite.pause { ActsAsTenant.with_tenant(organisation, &) }++ def new_project(owner = organisation)+ Prosopite.pause { ActsAsTenant.with_tenant(owner) { create(:project, organisation: owner) } }+ end++ def member(meetings: 'read_only', tickets: 'no_access', on: project, **names)+ quietly do+ user = create(:user, **names)+ create(:membership, user: user, organisation: organisation, role: role, active: true)+ create(:project_permission, user: user, project: on, meetings_access: meetings, tickets_access: tickets) if on+ user+ end+ end++ def account_admin+ quietly do+ create(:user).tap do |user|+ create(:membership, user: user, organisation: organisation, role: create(:admin_role, organisation: organisation),+ active: true)+ end+ end+ end++ def token_for(user, read_only: true, **reach)+ quietly do+ build(:personal_access_token, user: user, read_only: read_only, organisations: [organisation], **reach).tap do |pat|+ pat.token_hash = nil+ pat.token_prefix = nil+ pat.generate_token!+ pat.save!+ end+ end+ end++ def meeting(in_project: project, **attributes)+ Prosopite.pause do+ ActsAsTenant.with_tenant(in_project.organisation) do+ create(:meeting, { project: in_project, organisation: in_project.organisation, creator: creator,+ title: 'Sprint review', occurred_at: 1.day.ago }.merge(attributes))+ end+ end+ end++ def read(path, user: reader, pat: token_for(user))+ get path, headers: { 'Authorization' => "Bearer #{pat.token}" }+ response+ end++ def list(query = '', **options)+ read("/api/v1/projects/#{project.id}/meetings#{query}", **options)+ end++ def show(id, **options)+ read("/api/v1/meetings/#{id}", **options)+ end++ def ids = response.parsed_body['data'].pluck('id')++ describe 'GET /api/v1/projects/:project_id/meetings' do+ it 'lists the rows newest first, with the allowed fields and the page in meta' do+ older = meeting(title: 'Older', occurred_at: 3.days.ago, duration_minutes: 45)+ newer = meeting(title: 'Newer', occurred_at: 1.day.ago)++ expect(list).to have_http_status(:ok)+ expect(ids).to eq([newer.id, older.id])+ expect(response.parsed_body['meta']).to eq('page' => 1, 'per_page' => 10, 'total' => 2)+ expect(response.parsed_body['data'].first).to eq(+ 'id' => newer.id, 'project_id' => project.id, 'title' => 'Newer',+ 'occurred_at' => newer.occurred_at.iso8601, 'duration_minutes' => nil,+ 'creator' => { 'id' => creator.id, 'name' => 'Clara Creator' }+ )+ expect(response.parsed_body['data'].last['duration_minutes']).to eq(45)+ end++ it 'keeps the order over pages when date and entry time are equal, down to the id' do+ at = 2.days.ago.change(usec: 0)+ made = %w[1 3 2 5 4].map do |digit|+ meeting(id: "00000000-0000-4000-8000-00000000000#{digit}", occurred_at: at, created_at: at)+ end+ # Spelled out, not a loop: Prosopite reads one call site asked three times as an N+1.+ list('?page=1&per_page=2')+ first_page = ids+ list('?page=2&per_page=2')+ second_page = ids+ list('?page=3&per_page=2')++ expect(first_page + second_page + ids).to eq(made.map(&:id).sort.reverse)+ end++ it 'puts a later entry first among meetings of one date, as the web list does' do+ at = 2.days.ago.change(usec: 0)+ first_entered = meeting(id: '00000000-0000-4000-8000-000000000009', occurred_at: at, created_at: at - 1.hour)+ last_entered = meeting(id: '00000000-0000-4000-8000-000000000001', occurred_at: at, created_at: at)++ list+ expect(ids).to eq([last_entered.id, first_entered.id])+ end++ describe 'q' do+ it 'finds title, notes, transcript and summary, and counts only the hits' do+ hits = [meeting(title: 'Budget review'), meeting(notes: 'the budget was cut'),+ meeting(transcript: 'Anna: about the budget'), meeting(generated_summary: 'Budget agreed')]+ meeting(title: 'Something else')++ list('?q=budget')+ expect(ids).to match_array(hits.map(&:id))+ expect(response.parsed_body.dig('meta', 'total')).to eq(4)+ end++ it 'takes a blank q for no search' do+ found = meeting++ list('?q=%20')+ expect(ids).to eq([found.id])+ end++ it 'never finds a meeting of a project the reader cannot read, by its transcript or in the count' do+ elsewhere = new_project+ meeting(in_project: elsewhere, transcript: 'the secret word')+ meeting(transcript: 'the secret word')+ tickets_only = member(meetings: 'no_access', tickets: 'read_only')++ list('?q=secret', user: tickets_only)+ expect(ids).to be_empty+ expect(response.parsed_body.dig('meta', 'total')).to eq(0)+ end++ it 'matches a percent sign as text' do+ meeting(title: 'Plain')++ list('?q=%25')+ expect(ids).to be_empty+ end+ end++ describe 'paging, checked before the project' do+ ['per_page=0', 'per_page=101', 'per_page=-1', 'per_page=abc', 'per_page=1.5', 'page=0', 'page=abc',+ 'page=100001', 'page[]=1', 'per_page[]=1'].each do |query|+ it "refuses #{query} with 422, whether the project exists or not" do+ expect(list("?#{query}")).to have_http_status(:unprocessable_content)+ answer = response.body+ expect(response.parsed_body['code']).to eq('invalid_input')++ expect(read("/api/v1/projects/#{SecureRandom.uuid}/meetings?#{query}")).to have_http_status(:unprocessable_content)+ expect(response.body).to eq(answer)+ end+ end++ ['q=a%00b', 'q[]=a'].each do |query|+ it "refuses #{query} with 422" do+ expect(list("?#{query}")).to have_http_status(:unprocessable_content)+ expect(response.parsed_body['code']).to eq('invalid_input')+ end+ end++ it 'takes 100 rows, an empty value as the default, and answers a page beyond the end empty' do+ expect(list('?per_page=100&page=')).to have_http_status(:ok)+ expect(response.parsed_body['meta']).to include('per_page' => 100, 'page' => 1)++ meeting+ expect(list('?page=2')).to have_http_status(:ok)+ expect(ids).to be_empty+ expect(response.parsed_body['meta']).to include('page' => 2, 'total' => 1)+ end+ end++ describe 'the gate' do+ let!(:held) { meeting(transcript: 'the secret word') }++ it 'gives one 404 for a missing, malformed, foreign, unreached and unreadable project' do+ foreign = new_project(create(:organisation))+ unreached = new_project+ grant = quietly { create(:project_permission, user: reader, project: unreached, meetings_access: 'read_only') }+ stranger = member(on: nil)++ answers = [+ read("/api/v1/projects/#{SecureRandom.uuid}/meetings"),+ read('/api/v1/projects/not-a-uuid/meetings'),+ read("/api/v1/projects/#{foreign.id}/meetings"),+ read("/api/v1/projects/#{unreached.id}/meetings",+ pat: token_for(reader, project_scopes: { organisation => [project] })),+ list(user: stranger)+ ].map { |answer| [answer.status, answer.body] }++ expect(grant).to be_persisted+ expect(answers).to all(eq([404, not_found_body]))+ end++ it 'gives the same 404 for a token of a member who left' do+ pat = token_for(reader)+ quietly { Membership.find_by!(user: reader, organisation: organisation).update!(active: false) }++ expect(list(pat: pat)).to have_http_status(:not_found)+ expect(response.body).to eq(not_found_body)+ end++ it 'answers an empty list to a reader of the project without the meetings area' do+ tickets_only = member(meetings: 'no_access', tickets: 'read_only')++ expect(list(user: tickets_only)).to have_http_status(:ok)+ expect(response.parsed_body).to eq('data' => [], 'meta' => { 'page' => 1, 'per_page' => 10, 'total' => 0 })+ end++ it 'lets a read-only token read and a token with the project in reach' do+ expect(list(pat: token_for(reader, read_only: true))).to have_http_status(:ok)+ expect(ids).to eq([held.id])++ list(pat: token_for(reader, project_scopes: { organisation => [project] }))+ expect(ids).to eq([held.id])+ end++ it 'answers 401 without a token' do+ get "/api/v1/projects/#{project.id}/meetings"+ expect(response).to have_http_status(:unauthorized)+ end++ it 'treats an archived project as the web does: closed to a member, open to an account admin' do+ quietly { project.update!(archived_at: Time.current) }++ expect(list).to have_http_status(:not_found)+ expect(response.body).to eq(not_found_body)++ expect(list(user: account_admin)).to have_http_status(:ok)+ expect(ids).to eq([held.id])+ end+ end++ it 'reads no transcript for the rows and asks for creators once' do+ 3.times { meeting(transcript: 'long words', creator: member(meetings: 'read_write')) }+ pat = token_for(reader)+ queries = []+ counter = ->(*, payload) { queries << payload[:sql] unless payload[:name] == 'SCHEMA' }++ ActiveSupport::Notifications.subscribed(counter, 'sql.active_record') { list(pat: pat) }++ expect(ids.size).to eq(3)+ rows = queries.grep(/FROM "meetings"/).grep_v(/COUNT/i)+ expect(rows.size).to eq(1)+ expect(rows.first).not_to match(/transcript|"meetings"\.\*|plain_text_version/)+ expect(queries.grep(/FROM "users" WHERE "users"\."id" IN/).size).to be <= 2+ end++ it 'scales: more rows do not mean more queries' do+ pat = token_for(reader)+ count = lambda do+ queries = 0+ counter = ->(*, payload) { queries += 1 unless payload[:name] == 'SCHEMA' }+ ActiveSupport::Notifications.subscribed(counter, 'sql.active_record') { list(pat: pat) }+ queries+ end++ meeting(creator: member(meetings: 'read_write'))+ Prosopite.pause do+ count.call # the first request of a token also stamps its last_used_at+ one_row = count.call+ 4.times { meeting(creator: member(meetings: 'read_write')) }++ expect(count.call).to eq(one_row)+ end+ end+ end++ describe 'GET /api/v1/meetings/:id' do+ let(:held) do+ meeting(title: 'Kickoff', occurred_at: 2.days.ago, duration_minutes: 30, generated_summary: '**Head:** done',+ notes: 'Some notes', transcript: 'Anna: hello')+ end++ it 'answers the row, the participants by name, the texts whole, updated_at and the path' do+ quietly do+ create(:meeting_participant, meeting: held, organisation: organisation, display_name: 'Anna Albers',+ created_at: 2.minutes.ago)+ create(:meeting_participant, meeting: held, organisation: organisation, display_name: 'Ben Berger',+ user: creator, created_at: 1.minute.ago)+ end++ expect(show(held.id)).to have_http_status(:ok)+ expect(response.parsed_body['data']).to eq(+ 'id' => held.id, 'project_id' => project.id, 'title' => 'Kickoff',+ 'occurred_at' => held.occurred_at.iso8601, 'duration_minutes' => 30,+ 'creator' => { 'id' => creator.id, 'name' => 'Clara Creator' },+ 'participants' => [{ 'display_name' => 'Anna Albers' }, { 'display_name' => 'Ben Berger' }],+ 'generated_summary' => '**Head:** done', 'notes' => 'Some notes', 'transcript' => 'Anna: hello',+ 'updated_at' => held.reload.updated_at.iso8601,+ 'path' => "/org/#{organisation.id}/projects/#{project.id}/meetings/#{held.id}"+ )+ end++ it 'keeps the internal fields out, by listing what may leave' do+ quietly do+ held.update_columns(create_embeddings: true, embedding_creation_error: 'boom', embeddings_creation_flag: true,+ summary_creation_error: 'boom', summary_creation_flag: true,+ suggestions_creation_error: 'boom', suggestions_creation_flag: true,+ plain_text_version: 'plain')+ end++ show(held.id)+ expect(response.parsed_body['data'].keys).to contain_exactly(+ 'id', 'project_id', 'title', 'occurred_at', 'duration_minutes', 'creator', 'participants',+ 'generated_summary', 'notes', 'transcript', 'updated_at', 'path'+ )+ expect(response.body).not_to include('boom', 'embedding', '_flag', '_error', 'organisation_id', 'creator_id')+ end++ it 'does not cut a long transcript' do+ long = 'word ' * 150_000++ show(meeting(transcript: long).id)+ expect(response.parsed_body.dig('data', 'transcript')).to eq(long)+ end++ it 'leaves the metadata block off notes and transcript, as the web shows them' do+ block = "---\nid: 1\nparent: 2\n---\n"++ show(meeting(notes: "#{block}Notes", transcript: "#{block}Words").id)+ expect(response.parsed_body['data']).to include('notes' => 'Notes', 'transcript' => 'Words')+ end++ it 'answers null notes and transcript and an empty summary for a meeting without content' do+ show(meeting.id)+ expect(response.parsed_body['data']).to include('notes' => nil, 'transcript' => nil, 'generated_summary' => '')+ end++ it 'reads the participants in one query' do+ quietly do+ 3.times { |n| create(:meeting_participant, meeting: held, organisation: organisation, display_name: "P #{n}") }+ end+ queries = []+ counter = ->(*, payload) { queries << payload[:sql] }+ pat = token_for(reader)++ ActiveSupport::Notifications.subscribed(counter, 'sql.active_record') { show(held.id, pat: pat) }+ expect(queries.grep(/FROM "meeting_participants"/).size).to eq(1)+ end++ describe 'the gate: one 404 in status and body' do+ def expect_not_found(answer)+ expect(answer).to have_http_status(:not_found)+ expect(response.body).to eq(not_found_body)+ end++ it 'for a missing id' do+ expect_not_found(show(SecureRandom.uuid))+ end++ it 'for a malformed id' do+ expect_not_found(show('not-a-uuid'))+ expect_not_found(show('1'))+ expect_not_found(show('a%00b'))+ end++ it 'for a meeting outside the token reach, whatever the owner may read' do+ expect_not_found(show(held.id, pat: token_for(reader, project_scopes: { organisation => [new_project] })))+ end++ it 'for a meeting of another organisation' do+ foreign_org = create(:organisation)+ foreign = meeting(in_project: new_project(foreign_org))++ expect_not_found(show(foreign.id))+ end++ it 'for a reader of the project without the meetings area' do+ expect_not_found(show(held.id, user: member(meetings: 'no_access', tickets: 'read_only')))+ end++ it 'for a member without the project' do+ expect_not_found(show(held.id, user: member(on: nil)))+ end++ it 'for a token of a member who left' do+ pat = token_for(reader)+ quietly { Membership.find_by!(user: reader, organisation: organisation).update!(active: false) }++ expect_not_found(show(held.id, pat: pat))+ end++ it 'for a member of an archived project, whose grant the policy scope still names' do+ quietly { project.update!(archived_at: Time.current) }++ expect_not_found(show(held.id))+ end++ it 'when the policy alone refuses: never a 403, which would tell the meeting exists' do+ allow_any_instance_of(MeetingPolicy).to receive(:show?).and_return(false)++ expect_not_found(show(held.id))+ end+ end++ it 'answers 401 without a token' do+ get "/api/v1/meetings/#{held.id}"+ expect(response).to have_http_status(:unauthorized)+ end++ it 'lets a read-only token read, an account admin read an archived project' do+ expect(show(held.id, pat: token_for(reader, read_only: true))).to have_http_status(:ok)++ quietly { project.update!(archived_at: Time.current) }+ expect(show(held.id, user: account_admin)).to have_http_status(:ok)+ end++ it 'follows a meeting that moved: the reach of its project now, not of the old one' do+ target = new_project+ quietly { held.update!(project: target) }++ expect(show(held.id, pat: token_for(reader, project_scopes: { organisation => [project] })))+ .to have_http_status(:not_found)+ end+ end+end