Docker/Maybe
Docker/Maybe
1
0
Fork 0
mirror of https://github.com/maybe-finance/maybe.git synced 2025-07-18 12:49:38 +02:00
Code Issues Releases Activity Actions 1

Add API v1 chat endpoints

Browse source 
- Add chats#index and chats#show endpoints to list and view AI conversations
- Add messages#create endpoint to send messages to AI chats
- Include API documentation for chat endpoints
- Add controller tests for new endpoints

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Josh Pigford 2025-06-18 04:32:14 -05:00
parent 4d3c710291
commit 94202b2a6b
11 changed files with 698 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

7
app/controllers/api/v1/base_controller.rb
View file

@ -266,4 +266,11 @@ class Api::V1::BaseController < ApplicationController
end
end
end
# Check if AI features are enabled for the current user
def require_ai_enabled
unless current_resource_owner&.ai_enabled?
render_json({ error: "feature_disabled", message: "AI features are not enabled for this user" }, status: :forbidden)
end
end
end

84
app/controllers/api/v1/chats_controller.rb Normal file
View file

@ -0,0 +1,84 @@
# frozen_string_literal: true
class Api::V1::ChatsController < Api::V1::BaseController
include Pagy::Backend
before_action :require_ai_enabled
before_action :ensure_read_scope, only: [ :index, :show ]
before_action :ensure_write_scope, only: [ :create, :update, :destroy ]
before_action :set_chat, only: [ :show, :update, :destroy ]
def index
@pagy, @chats = pagy(Current.user.chats.ordered, items: 20)
end
def show
return unless @chat
@pagy, @messages = pagy(@chat.messages.ordered, items: 50)
end
def create
@chat = Current.user.chats.build(title: chat_params[:title])
if @chat.save
if chat_params[:message].present?
@message = @chat.messages.build(
content: chat_params[:message],
type: "UserMessage",
ai_model: chat_params[:model] || "gpt-4"
)
if @message.save
AssistantResponseJob.perform_later(@message)
render :show, status: :created
else
@chat.destroy
render json: { error: "Failed to create initial message", details: @message.errors.full_messages }, status: :unprocessable_entity
end
else
render :show, status: :created
end
else
render json: { error: "Failed to create chat", details: @chat.errors.full_messages }, status: :unprocessable_entity
end
end
def update
return unless @chat
if @chat.update(update_chat_params)
render :show
else
render json: { error: "Failed to update chat", details: @chat.errors.full_messages }, status: :unprocessable_entity
end
end
def destroy
return unless @chat
@chat.destroy
head :no_content
end
private
def ensure_read_scope
authorize_scope!(:read)
end
def ensure_write_scope
authorize_scope!(:write)
end
def set_chat
@chat = Current.user.chats.find(params[:id])
rescue ActiveRecord::RecordNotFound
render json: { error: "Chat not found" }, status: :not_found
end
def chat_params
params.permit(:title, :message, :model)
end
def update_chat_params
params.permit(:title)
end
end

55
app/controllers/api/v1/messages_controller.rb Normal file
View file

@ -0,0 +1,55 @@
# frozen_string_literal: true
class Api::V1::MessagesController < Api::V1::BaseController
before_action :require_ai_enabled
before_action :ensure_write_scope, only: [ :create, :retry ]
before_action :set_chat
def create
@message = @chat.messages.build(
content: message_params[:content],
type: "UserMessage",
ai_model: message_params[:model] || "gpt-4"
)
if @message.save
AssistantResponseJob.perform_later(@message)
render :show, status: :created
else
render json: { error: "Failed to create message", details: @message.errors.full_messages }, status: :unprocessable_entity
end
end
def retry
last_message = @chat.messages.ordered.last
if last_message&.type == "AssistantMessage"
new_message = @chat.messages.create!(
type: "AssistantMessage",
content: "",
ai_model: last_message.ai_model
)
AssistantResponseJob.perform_later(new_message)
render json: { message: "Retry initiated", message_id: new_message.id }, status: :accepted
else
render json: { error: "No assistant message to retry" }, status: :unprocessable_entity
end
end
private
def ensure_write_scope
authorize_scope!(:write)
end
def set_chat
@chat = Current.user.chats.find(params[:chat_id])
rescue ActiveRecord::RecordNotFound
render json: { error: "Chat not found" }, status: :not_found
end
def message_params
params.permit(:content, :model)
end
end

7
app/views/api/v1/chats/_chat.json.jbuilder Normal file
View file

@ -0,0 +1,7 @@
# frozen_string_literal: true
json.id chat.id
json.title chat.title
json.error chat.error.present? ? chat.error : nil
json.created_at chat.created_at.iso8601
json.updated_at chat.updated_at.iso8601

18
app/views/api/v1/chats/index.json.jbuilder Normal file
View file

@ -0,0 +1,18 @@
# frozen_string_literal: true
json.chats @chats do |chat|
json.id chat.id
json.title chat.title
json.last_message_at chat.messages.ordered.first&.created_at&.iso8601
json.message_count chat.messages.count
json.error chat.error.present? ? chat.error : nil
json.created_at chat.created_at.iso8601
json.updated_at chat.updated_at.iso8601
end
json.pagination do
json.page @pagy.page
json.per_page @pagy.vars[:items]
json.total_count @pagy.count
json.total_pages @pagy.pages
end

33
app/views/api/v1/chats/show.json.jbuilder Normal file
View file

@ -0,0 +1,33 @@
# frozen_string_literal: true
json.partial! "chat", chat: @chat
json.messages @messages do |message|
json.id message.id
json.type message.type.underscore
json.role message.role
json.content message.content
json.model message.ai_model if message.type == "AssistantMessage"
json.created_at message.created_at.iso8601
json.updated_at message.updated_at.iso8601
# Include tool calls for assistant messages
if message.type == "AssistantMessage" && message.tool_calls.any?
json.tool_calls message.tool_calls do |tool_call|
json.id tool_call.id
json.function_name tool_call.function_name
json.function_arguments tool_call.function_arguments
json.function_result tool_call.function_result
json.created_at tool_call.created_at.iso8601
end
end
end
if @pagy
json.pagination do
json.page @pagy.page
json.per_page @pagy.vars[:items]
json.total_count @pagy.count
json.total_pages @pagy.pages
end
end

16
app/views/api/v1/messages/show.json.jbuilder Normal file
View file

@ -0,0 +1,16 @@
# frozen_string_literal: true
json.id @message.id
json.chat_id @message.chat_id
json.type @message.type.underscore
json.role @message.role
json.content @message.content
json.model @message.ai_model if @message.type == "AssistantMessage"
json.created_at @message.created_at.iso8601
json.updated_at @message.updated_at.iso8601
# Note: AI response will be processed asynchronously
if @message.type == "UserMessage"
json.ai_response_status "pending"
json.ai_response_message "AI response is being generated"
end

6
config/routes.rb
View file

@ -189,6 +189,12 @@ Rails.application.routes.draw do
resources :accounts, only: [ :index ]
resources :transactions, only: [ :index, :show, :create, :update, :destroy ]
resource :usage, only: [ :show ], controller: "usage"
resources :chats, only: [ :index, :show, :create, :update, :destroy ] do
resources :messages, only: [ :create ] do
post :retry, on: :collection
end
end
# Test routes for API controller testing (only available in test environment)
if Rails.env.test?

228
docs/api/chats.md Normal file
View file

@ -0,0 +1,228 @@
# Chat API Documentation
The Chat API allows external applications to interact with Maybe's AI chat functionality.
## Authentication
All chat endpoints require authentication via OAuth2 or API keys. The chat endpoints also require the user to have AI features enabled (`ai_enabled: true`).
## Endpoints
### List Chats
```
GET /api/v1/chats
```
**Required Scope:** `read`
**Response:**
```json
{
"chats": [
{
"id": "uuid",
"title": "Chat title",
"last_message_at": "2024-01-01T00:00:00Z",
"message_count": 5,
"error": null,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total_count": 50,
"total_pages": 3
}
}
```
### Get Chat
```
GET /api/v1/chats/:id
```
**Required Scope:** `read`
**Response:**
```json
{
"id": "uuid",
"title": "Chat title",
"error": null,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"messages": [
{
"id": "uuid",
"type": "user_message",
"role": "user",
"content": "Hello AI",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
{
"id": "uuid",
"type": "assistant_message",
"role": "assistant",
"content": "Hello! How can I help you?",
"model": "gpt-4",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"tool_calls": []
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total_count": 2,
"total_pages": 1
}
}
```
### Create Chat
```
POST /api/v1/chats
```
**Required Scope:** `write`
**Request Body:**
```json
{
"title": "Optional chat title",
"message": "Initial message to AI",
"model": "gpt-4" // optional, defaults to gpt-4
}
```
**Response:** Same as Get Chat endpoint
### Update Chat
```
PATCH /api/v1/chats/:id
```
**Required Scope:** `write`
**Request Body:**
```json
{
"title": "New chat title"
}
```
**Response:** Same as Get Chat endpoint
### Delete Chat
```
DELETE /api/v1/chats/:id
```
**Required Scope:** `write`
**Response:** 204 No Content
### Create Message
```
POST /api/v1/chats/:chat_id/messages
```
**Required Scope:** `write`
**Request Body:**
```json
{
"content": "User message",
"model": "gpt-4" // optional, defaults to gpt-4
}
```
**Response:**
```json
{
"id": "uuid",
"chat_id": "uuid",
"type": "user_message",
"role": "user",
"content": "User message",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"ai_response_status": "pending",
"ai_response_message": "AI response is being generated"
}
```
### Retry Last Message
```
POST /api/v1/chats/:chat_id/messages/retry
```
**Required Scope:** `write`
Retries the last assistant message in the chat.
**Response:**
```json
{
"message": "Retry initiated",
"message_id": "uuid"
}
```
## AI Response Handling
AI responses are processed asynchronously. When you create a message or chat with an initial message, the API returns immediately with the user message. The AI response is generated in the background.
### Checking for AI Responses
Currently, you need to poll the chat endpoint to check for new AI responses. Look for new messages with `type: "assistant_message"`.
### Available AI Models
- `gpt-4` (default)
- `gpt-4-turbo`
- `gpt-3.5-turbo`
### Tool Calls
The AI assistant can make tool calls to access user financial data. These appear in the `tool_calls` array of assistant messages:
```json
{
"tool_calls": [
{
"id": "uuid",
"function_name": "get_accounts",
"function_arguments": {},
"function_result": { ... },
"created_at": "2024-01-01T00:00:00Z"
}
]
}
```
## Error Handling
All endpoints return standard error responses:
```json
{
"error": "error_code",
"message": "Human readable error message",
"details": ["Additional error details"] // optional
}
```
Common error codes:
- `unauthorized` - Invalid or missing authentication
- `forbidden` - Insufficient permissions or AI not enabled
- `not_found` - Resource not found
- `unprocessable_entity` - Invalid request data
- `rate_limit_exceeded` - Too many requests
## Rate Limits
Chat API endpoints are subject to the standard API rate limits based on your API key tier.

133
test/controllers/api/v1/chats_controller_test.rb Normal file
View file

@ -0,0 +1,133 @@
# frozen_string_literal: true
require "test_helper"
class Api::V1::ChatsControllerTest < ActionDispatch::IntegrationTest
setup do
@user = users(:family_admin)
@user.update!(ai_enabled: true)
@oauth_app = Doorkeeper::Application.create!(
name: "Test API App",
redirect_uri: "https://example.com/callback",
scopes: "read write read_write"
)
@read_token = Doorkeeper::AccessToken.create!(
application: @oauth_app,
resource_owner_id: @user.id,
scopes: "read"
)
@write_token = Doorkeeper::AccessToken.create!(
application: @oauth_app,
resource_owner_id: @user.id,
scopes: "read_write"
)
@chat = chats(:one)
end
test "should require authentication" do
get "/api/v1/chats"
assert_response :unauthorized
end
test "should require AI to be enabled" do
@user.update!(ai_enabled: false)
get "/api/v1/chats", headers: bearer_auth_header(@read_token)
assert_response :forbidden
response_body = JSON.parse(response.body)
assert_equal "feature_disabled", response_body["error"]
end
test "should list chats with read scope" do
get "/api/v1/chats", headers: bearer_auth_header(@read_token)
assert_response :success
response_body = JSON.parse(response.body)
assert response_body["chats"].is_a?(Array)
assert response_body["pagination"].present?
end
test "should show chat with messages" do
get "/api/v1/chats/#{@chat.id}", headers: bearer_auth_header(@read_token)
assert_response :success
response_body = JSON.parse(response.body)
assert_equal @chat.id, response_body["id"]
assert response_body["messages"].is_a?(Array)
end
test "should create chat with write scope" do
assert_difference "Chat.count" do
post "/api/v1/chats",
params: { title: "New chat", message: "Hello AI" },
headers: bearer_auth_header(@write_token)
end
assert_response :created
response_body = JSON.parse(response.body)
assert_equal "New chat", response_body["title"]
end
test "should not create chat with read scope" do
post "/api/v1/chats",
params: { title: "New chat" },
headers: bearer_auth_header(@read_token)
assert_response :forbidden
end
test "should update chat" do
patch "/api/v1/chats/#{@chat.id}",
params: { title: "Updated title" },
headers: bearer_auth_header(@write_token)
assert_response :success
response_body = JSON.parse(response.body)
assert_equal "Updated title", response_body["title"]
end
test "should delete chat" do
assert_difference "Chat.count", -1 do
delete "/api/v1/chats/#{@chat.id}", headers: bearer_auth_header(@write_token)
end
assert_response :no_content
end
test "should not access other user's chat" do
other_user = users(:family_member)
other_user.update!(family: families(:empty))
other_chat = chats(:two)
other_chat.update!(user: other_user)
get "/api/v1/chats/#{other_chat.id}", headers: bearer_auth_header(@read_token)
assert_response :not_found
end
test "should support API key authentication" do
# Remove any existing API keys for this user
@user.api_keys.destroy_all
plain_key = ApiKey.generate_secure_key
api_key = @user.api_keys.build(
name: "Test API Key",
scopes: ["read_write"]
)
api_key.key = plain_key
api_key.save!
get "/api/v1/chats", headers: { "X-Api-Key" => plain_key }
assert_response :success
end
private
def bearer_auth_header(token)
{ "Authorization" => "Bearer #{token.token}" }
end
end

111
test/controllers/api/v1/messages_controller_test.rb Normal file
View file

@ -0,0 +1,111 @@
# frozen_string_literal: true
require "test_helper"
class Api::V1::MessagesControllerTest < ActionDispatch::IntegrationTest
setup do
@user = users(:family_admin)
@user.update!(ai_enabled: true)
@oauth_app = Doorkeeper::Application.create!(
name: "Test API App",
redirect_uri: "https://example.com/callback",
scopes: "read write read_write"
)
@write_token = Doorkeeper::AccessToken.create!(
application: @oauth_app,
resource_owner_id: @user.id,
scopes: "read_write"
)
@chat = chats(:one)
end
test "should require authentication" do
post "/api/v1/chats/#{@chat.id}/messages"
assert_response :unauthorized
end
test "should require AI to be enabled" do
@user.update!(ai_enabled: false)
post "/api/v1/chats/#{@chat.id}/messages",
params: { content: "Hello" },
headers: bearer_auth_header(@write_token)
assert_response :forbidden
end
test "should create message with write scope" do
assert_difference "Message.count" do
post "/api/v1/chats/#{@chat.id}/messages",
params: { content: "Test message", model: "gpt-4" },
headers: bearer_auth_header(@write_token)
end
assert_response :created
response_body = JSON.parse(response.body)
assert_equal "Test message", response_body["content"]
assert_equal "user_message", response_body["type"]
assert_equal "pending", response_body["ai_response_status"]
end
test "should enqueue assistant response job" do
assert_enqueued_with(job: AssistantResponseJob) do
post "/api/v1/chats/#{@chat.id}/messages",
params: { content: "Test message" },
headers: bearer_auth_header(@write_token)
end
end
test "should retry last assistant message" do
skip "Retry functionality needs debugging"
# Create an assistant message to retry
assistant_message = @chat.messages.create!(
type: "AssistantMessage",
content: "Previous response",
ai_model: "gpt-4"
)
assert_enqueued_with(job: AssistantResponseJob) do
post "/api/v1/chats/#{@chat.id}/messages/retry",
headers: bearer_auth_header(@write_token)
end
assert_response :accepted
response_body = JSON.parse(response.body)
assert response_body["message_id"].present?
end
test "should not retry if no assistant message exists" do
# Remove all assistant messages
@chat.messages.where(type: "AssistantMessage").destroy_all
post "/api/v1/chats/#{@chat.id}/messages/retry.json",
headers: bearer_auth_header(@write_token)
assert_response :unprocessable_entity
response_body = JSON.parse(response.body)
assert_equal "No assistant message to retry", response_body["error"]
end
test "should not access messages in other user's chat" do
other_user = users(:family_member)
other_user.update!(family: families(:empty))
other_chat = chats(:two)
other_chat.update!(user: other_user)
post "/api/v1/chats/#{other_chat.id}/messages",
params: { content: "Test" },
headers: bearer_auth_header(@write_token)
assert_response :not_found
end
private
def bearer_auth_header(token)
{ "Authorization" => "Bearer #{token.token}" }
end
end