api_contract: workflow_version: v005 design_document_revision: 1 generated_at: '2025-12-20T22:10:36.422275' validated_at: null status: draft types: - id: type_RefreshToken name: RefreshToken definition: type: object properties: - name: id type: string required: true description: Unique identifier - name: token type: string required: true description: Refresh token value - name: userId type: string required: true description: User who owns this token - name: expiresAt type: Date required: true description: Token expiration time - name: createdAt type: Date required: true description: When token was created - name: isRevoked type: boolean required: false description: Whether token has been revoked used_by: models: - model_refresh_token responses: [] requests: [] - id: type_Session name: Session definition: type: object properties: - name: id type: string required: true description: Unique session identifier - name: userId type: string required: true description: User who owns this session - name: token type: string required: true description: Session token - name: deviceInfo type: Record required: false description: Device information (browser, OS) - name: ipAddress type: string required: false description: Client IP address - name: userAgent type: string required: false description: Browser user agent - name: lastActivity type: Date required: false description: Last activity timestamp - name: createdAt type: Date required: true description: When session was created used_by: models: - model_session responses: [] requests: [] - id: type_PlayHistory name: PlayHistory definition: type: object properties: - name: id type: string required: true description: Unique identifier - name: userId type: string required: true description: User who played the song - name: songId type: string required: true description: Song that was played - name: playedAt type: Date required: true description: When playback started - name: playedDuration type: number required: false description: Seconds actually played - name: completed type: boolean required: false description: Did user listen to completion - name: source type: string required: false description: Where playback was initiated used_by: models: - model_play_history responses: [] requests: [] - id: type_Queue name: Queue definition: type: object properties: - name: id type: string required: true description: Unique queue identifier - name: userId type: string required: true description: User who owns this queue - name: songIds type: Record required: true description: Array of song IDs in order - name: currentIndex type: number required: false description: Current playing index - name: isShuffled type: boolean required: false description: Whether queue is shuffled - name: repeatMode type: string required: false description: 'Repeat mode: none, one, all' - name: createdAt type: Date required: true description: When queue was created - name: updatedAt type: Date required: true description: Last update time used_by: models: - model_queue responses: [] requests: [] - id: type_UploadSession name: UploadSession definition: type: object properties: - name: id type: string required: true description: Unique upload session ID - name: userId type: string required: true description: User uploading the file - name: fileName type: string required: true description: Original file name - name: fileSize type: number required: true description: Total file size in bytes - name: mimeType type: string required: true description: File MIME type - name: chunkSize type: number required: true description: Size of each chunk - name: totalChunks type: number required: true description: Total number of chunks - name: uploadedChunks type: Record required: false description: Array of uploaded chunk numbers - name: status type: string required: false description: Upload status - name: fileId type: string required: false description: Associated file ID when complete - name: metadata type: Record required: false description: Additional file metadata - name: createdAt type: Date required: true description: When upload started - name: expiresAt type: Date required: true description: When upload session expires used_by: models: - model_upload_session responses: [] requests: [] - id: type_SearchIndex name: SearchIndex definition: type: object properties: - name: id type: string required: true description: Unique index entry ID - name: entityType type: string required: true description: Type of entity (song, album, artist) - name: entityId type: string required: true description: ID of the indexed entity - name: title type: string required: true description: Entity title for search - name: content type: string required: false description: Full text content - name: metadata type: Record required: false description: Additional searchable metadata - name: createdAt type: Date required: true description: When indexed - name: updatedAt type: Date required: true description: Last update used_by: models: - model_search_index responses: [] requests: [] endpoints: - id: api_auth_refresh method: POST path: /api/auth/refresh path_params: [] query_params: [] request_body: type_id: type_AuthRefreshRequest content_type: application/json response: success: status: 200 type_id: type_AuthRefreshResponse is_array: false errors: - status: 401 type_id: type_ApiError description: Invalid or expired refresh token auth: required: false roles: [] version: 1.0.0 - id: api_auth_logout method: POST path: /api/auth/logout path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_auth_sessions method: GET path: /api/auth/sessions path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_auth_revoke_session method: DELETE path: /api/auth/sessions/:id path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_auth_verify_email method: POST path: /api/auth/verify-email path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_auth_confirm_email method: POST path: /api/auth/confirm-email path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_play method: POST path: /api/player/play path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_pause method: POST path: /api/player/pause path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_next method: POST path: /api/player/next path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_previous method: POST path: /api/player/previous path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_queue method: GET path: /api/player/queue path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_queue_add method: POST path: /api/player/queue path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_queue_clear method: DELETE path: /api/player/queue path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_player_history method: GET path: /api/player/history path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_upload_init method: POST path: /api/upload/init path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_upload_chunk method: POST path: /api/upload/chunk/:uploadId/:chunkIndex path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_upload_complete method: POST path: /api/upload/complete/:uploadId path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_upload_presigned method: GET path: /api/upload/presigned-url path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_search method: GET path: /api/search path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_search_suggestions method: GET path: /api/search/suggestions path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 - id: api_search_index method: POST path: /api/search/index path_params: [] query_params: [] request_body: null response: success: status: 200 type_id: null is_array: false errors: [] auth: required: false roles: [] version: 1.0.0 frontend_calls: - id: call_page_settings_security_api_auth_sessions source: entity_id: page_settings_security file_path: app/settings/security/page.tsx endpoint_id: api_auth_sessions purpose: Load active sessions trigger: onLoad request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Update state error_action: Show error - id: call_component_audio_player_api_player_play source: entity_id: component_audio_player file_path: app/components/AudioPlayer.tsx endpoint_id: api_player_play purpose: Call api_player_play trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_audio_player_api_player_pause source: entity_id: component_audio_player file_path: app/components/AudioPlayer.tsx endpoint_id: api_player_pause purpose: Call api_player_pause trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_audio_player_api_player_next source: entity_id: component_audio_player file_path: app/components/AudioPlayer.tsx endpoint_id: api_player_next purpose: Call api_player_next trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_audio_player_api_player_previous source: entity_id: component_audio_player file_path: app/components/AudioPlayer.tsx endpoint_id: api_player_previous purpose: Call api_player_previous trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_audio_player_api_player_queue source: entity_id: component_audio_player file_path: app/components/AudioPlayer.tsx endpoint_id: api_player_queue purpose: Call api_player_queue trigger: onDemand request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_upload_manager_api_upload_init source: entity_id: component_upload_manager file_path: app/components/UploadManager.tsx endpoint_id: api_upload_init purpose: Call api_upload_init trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_upload_manager_api_upload_chunk source: entity_id: component_upload_manager file_path: app/components/UploadManager.tsx endpoint_id: api_upload_chunk purpose: Call api_upload_chunk trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_upload_manager_api_upload_complete source: entity_id: component_upload_manager file_path: app/components/UploadManager.tsx endpoint_id: api_upload_complete purpose: Call api_upload_complete trigger: onSubmit request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_search_bar_api_search_suggestions source: entity_id: component_search_bar file_path: app/components/SearchBar.tsx endpoint_id: api_search_suggestions purpose: Call api_search_suggestions trigger: onDemand request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error - id: call_component_search_results_api_search source: entity_id: component_search_results file_path: app/components/SearchResults.tsx endpoint_id: api_search purpose: Call api_search trigger: onDemand request_mapping: from_props: [] from_state: [] from_form: [] response_handling: success_action: Handle response error_action: Show error backend_routes: - id: route_post_auth_refresh endpoint_id: api_auth_refresh file_path: app/api/auth/refresh/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_auth_logout endpoint_id: api_auth_logout file_path: app/api/auth/logout/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_auth_sessions endpoint_id: api_auth_sessions file_path: app/api/auth/sessions/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_delete_auth_sessions_:id endpoint_id: api_auth_revoke_session file_path: app/api/auth/sessions/[id]/route.ts export_name: DELETE uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_auth_verify-email endpoint_id: api_auth_verify_email file_path: app/api/auth/verify-email/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_auth_confirm-email endpoint_id: api_auth_confirm_email file_path: app/api/auth/confirm-email/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_player_play endpoint_id: api_player_play file_path: app/api/player/play/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_player_pause endpoint_id: api_player_pause file_path: app/api/player/pause/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_player_next endpoint_id: api_player_next file_path: app/api/player/next/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_player_previous endpoint_id: api_player_previous file_path: app/api/player/previous/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_player_queue endpoint_id: api_player_queue file_path: app/api/player/queue/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_player_queue endpoint_id: api_player_queue_add file_path: app/api/player/queue/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_delete_player_queue endpoint_id: api_player_queue_clear file_path: app/api/player/queue/route.ts export_name: DELETE uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_player_history endpoint_id: api_player_history file_path: app/api/player/history/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_upload_init endpoint_id: api_upload_init file_path: app/api/upload/init/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_upload_chunk_:uploadId_:chunkIndex endpoint_id: api_upload_chunk file_path: app/api/upload/chunk/[uploadId]/[chunkIndex]/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_upload_complete_:uploadId endpoint_id: api_upload_complete file_path: app/api/upload/complete/[uploadId]/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_upload_presigned-url endpoint_id: api_upload_presigned file_path: app/api/upload/presigned-url/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_search endpoint_id: api_search file_path: app/api/search/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_get_search_suggestions endpoint_id: api_search_suggestions file_path: app/api/search/suggestions/route.ts export_name: GET uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: [] - id: route_post_search_index endpoint_id: api_search_index file_path: app/api/search/index/route.ts export_name: POST uses_models: [] uses_services: [] must_validate: [] must_authenticate: false must_authorize: []