This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). ## Getting Started Locally First, run the development server: ```bash npm run dev # or yarn dev # or pnpm dev # or bun dev ``` Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. ## Documentation # RoleplayChat API Documentation This document describes the RoleplayChat Flask-based API. --- ## Table of Contents 1. [Overview](#overview) 2. [Authentication](#authentication) 3. [Database Models](#database-models) 4. [Endpoints](#endpoints) * [Campaigns Collection](#campaigns-collection) * [Single Campaign](#single-campaign) * [Campaign Chats](#campaigns-chats) 5. [Error Handling](#error-handling) --- ## Overview The RoleplayChat backend allows clients to create, manage, and interact with role-playing game campaigns. It leverages Flask for HTTP routing, SQLAlchemy for database access, and Google GenAI for AI-generated content. --- ## Authentication All endpoints require an API key supplied via the \`Authorization\` header: \`\`\` Authorization: Bearer \`\`\` You can obtain or manage API keys at [https://roleplaychatwebsite.vercel.app/keys](https://roleplaychatwebsite.vercel.app/keys). The server verifies each key against the \`ApiKey\` table before processing requests. --- ## Database Models | Table | Fields | | -------- | ------------------------------------------------------------------------------------------------ | | ApiKey | \`id\` (UUID), \`key\` (string) | | Campaign | \`id\` (UUID), \`name\` (string), \`book\` (string), \`prompt\` (text), \`userId\` (string/null), | | | \`apiKeyId\` (UUID), \`createdAt\` (timestamp) | | Chat | \`id\` (serial), \`message\` (text), \`response\` (text), \`campaignId\` (UUID), \`createdAt\` (timestamp) | > **Note:** The `book` and `prompt` fields for campaigns are currently placeholders. Functionality related to these fields (such as customizing campaign prompts or associating campaigns with specific books) is not yet implemented and will be added in a future release. --- ## Endpoints ### Campaigns Collection #### GET \`/campaigns\` Retrieves all campaigns associated with your API key. Optional query parameter: * \`userId\` (string): filter campaigns by user identifier. **Responses**: * \`200 OK\` with JSON array of campaigns: \`\`\`json [ { "id": "uuid-1", "name": "Dragon Hunt" }, { "id": "uuid-2", "name": "Space Odyssey" } ] \`\`\` * \`204 No Content\` if none exist: \`\`\`json { "message": "You have no campaigns yet." } \`\`\` * \`401 Unauthorized\` if the API key is missing or invalid. * \`500 Internal Server Error\` on database failure. #### POST \`/campaigns\` Creates a new campaign. Request body (JSON): | Field | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------- | | \`name\` | string | yes | Campaign name | | \`book\` | string | yes | Source book or setting | | \`prompt\` | string | no | Initial prompt (defaults to server default) | | \`userId\` | string | no | Client user identifier | **Example**: \`\`\`bash curl -X POST https://api.example.com/campaigns \\ -H "Authorization: Bearer YOUR_KEY" \\ -H "Content-Type: application/json" \\ -d '{"name":"Quest","book":"Mythos","prompt":"Once upon a time...","userId":"user123"}' \`\`\` **Responses**: * \`201 Created\`: \`\`\`json { "status": "success", "message": "Campaign created successfully." } \`\`\` * \`400 Bad Request\` if required fields are missing. * \`500 Internal Server Error\` on database or AI errors. --- ### Single Campaign #### GET \`/campaigns/\` Fetch detailed information for a campaign by its UUID. **Response**: \`\`\`json { "book": "Mythos", "prompt": "Once upon a time...", "name": "Quest", "created_at": "2025-05-16T12:34:56" } \`\`\` **Status Codes**: * \`200 OK\` on success. * \`401 Unauthorized\` if the API key is invalid or access is denied. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- #### PUT \`/campaigns/\` Update the campaign’s name. Request body: \`\`\`json { "name": "New Campaign Name" } \`\`\` **Status Codes**: * \`200 OK\` on success. * \`400 Bad Request\` if \`name\` is missing. * \`401 Unauthorized\` if the API key is invalid or you are not the campaign owner. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- #### DELETE \`/campaigns/\` Delete a campaign and all associated chats. **Response**: \`\`\`json { "status": "success", "message": "Campaign deleted successfully." } \`\`\` **Status Codes**: * \`200 OK\` on success. * \`401 Unauthorized\` if the API key is invalid or you are not the campaign owner. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- ### Campaign Chats #### POST \`/campaigns//chats\` Send a user message to the AI; returns the AI response and stores both in the chat history. **Request body**: \`\`\`json { "input": "I open the treasure chest." } \`\`\` **Behavior**: 1. Retrieves the last 8 messages for context. 2. If there are more than 8 messages, older ones are summarized to maintain performance. 3. Calls the Google GenAI model \`gemini-2.0-flash\` with full context plus the new input. 4. Stores the user message and generated response. **Response**: \`\`\`json { "response": "Inside the chest, you find..." } \`\`\` **Status Codes**: * \`200 OK\` on success. * \`401 Unauthorized\` if the API key is invalid or you are not the campaign owner. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- #### GET \`/campaigns//chats\` Retrieve stored chat history for a campaign. **Query parameters**: * \`number\` (int): maximum number of chat entries to return, ordered oldest first. **Response**: \`\`\`json [ { "message": "Once upon a time...", "response": "Understood", "createdAt": "2025-05-16T12:00:00" }, { "message": "I open the treasure chest.", "response": "Inside you see...", "createdAt": "2025-05-16T12:01:00" } ] \`\`\` **Status Codes**: * \`200 OK\` on success. * \`204 No Content\` if no chats exist. * \`401 Unauthorized\` if the API key is invalid or you are not the campaign owner. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- #### DELETE \`/campaigns//chats\` Delete chat history for a campaign. **Query parameters**: * \`count\` (int): number of most recent messages to remove. If omitted, all messages are deleted and the chat resets to the default prompt. **Response**: \`\`\`json { "status": "success", "message": "Chats deleted and history reset successfully." } \`\`\` **Status Codes**: * \`200 OK\` on success. * \`401 Unauthorized\` if the API key is invalid or you are not the campaign owner. * \`404 Not Found\` if the campaign does not exist. * \`500 Internal Server Error\` on database failure. --- ## Error Handling All error responses are JSON objects with an \`error\` or \`message\` field and appropriate HTTP status codes. Example: \`\`\`json { "error": "Invalid API key." } \`\`\` --- *End of documentation.*