project-standalo-sonic-cloud/.workflow/versions/v005/contracts/api_contract.yml

955 lines
22 KiB
YAML

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<string, unknown>
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<string, unknown>
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<string, unknown>
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<string, unknown>
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<string, unknown>
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: []