tercul-backend/api/README.md

# Tercul API Documentation

This document provides comprehensive documentation for the Tercul GraphQL API. It is designed to give developers all the information they need to interact with the platform's data and services.

## Table of Contents

- [Introduction](#introduction)
- [Authentication](#authentication)
- [Queries](#queries)
  - [Work](#work)
  - [Translation](#translation)
  - [Author](#author)
  - [User](#user)
  - [Collection](#collection)
  - [Utility](#utility)
- [Mutations](#mutations)
  - [Authentication](#authentication-mutations)
  - [Work](#work-mutations)
  - [Translation](#translation-mutations)
  - [Like](#like-mutations)
  - [Comment](#comment-mutations)
- [Core Types](#core-types)

## Introduction

The Tercul API is a GraphQL-based service that exposes the full range of the platform's literary and social data. It allows for querying works, translations, authors, and user data, as well as performing actions such as creating content, liking, and commenting.

## Authentication

Most mutations and some queries require authentication. To authenticate, you must first use the `login` mutation to receive a JWT. This token must then be included in the `Authorization` header of subsequent requests as a Bearer token.

**Example Header:**
`Authorization: Bearer <your_jwt_token>`

---

## Queries

This section details all available queries.

### Work

#### `work(id: ID!): Work`
Retrieves a single work by its unique ID.
- **`id`**: The ID of the work to retrieve.

*Example:*
```graphql
query GetWork {
  work(id: "1") {
    id
    name
    language
    content
    stats {
      likes
      views
    }
  }
}
```

#### `works(...)`
Retrieves a list of works, with optional filters.
- **`limit`**: The maximum number of works to return.
- **`offset`**: The number of works to skip for pagination.
- **`language`**: Filter works by language code (e.g., "en").
- **`authorId`**: Filter works by author ID.
- **`categoryId`**: Filter works by category ID.
- **`tagId`**: Filter works by tag ID.
- **`search`**: A string to search for in work titles and content.

*Example:*
```graphql
query GetWorks {
  works(limit: 10, language: "en") {
    id
    name
  }
}
```

### Translation

#### `translation(id: ID!): Translation`
Retrieves a single translation by its unique ID.
- **`id`**: The ID of the translation.

#### `translations(...)`
Retrieves a list of translations for a given work.
- **`workId`**: The ID of the parent work.
- **`language`**: Filter translations by language code.
- **`limit`**: The maximum number of translations to return.
- **`offset`**: The number of translations to skip.

### Author

#### `author(id: ID!): Author`
Retrieves a single author by ID.

#### `authors(...)`
Retrieves a list of authors with optional filters.

### User

#### `user(id: ID!): User`
Retrieves a single user by ID.

#### `userByEmail(email: String!): User`
Retrieves a single user by email address.

#### `userByUsername(username: String!): User`
Retrieves a single user by username.

#### `me: User`
Retrieves the currently authenticated user.

### Collection

#### `collection(id: ID!): Collection`
Retrieves a single collection by ID.

#### `collections(...)`
Retrieves a list of collections, optionally filtered by user.

### Utility

#### `trendingWorks(...)`
Returns a list of works with the highest engagement.
- **`timePeriod`**: "daily", "weekly", or "monthly". Defaults to "daily".
- **`limit`**: The number of works to return. Defaults to 10.

---

## Mutations

This section details all available mutations for creating, updating, and deleting data.

### Authentication Mutations

#### `register(input: RegisterInput!): AuthPayload!`
Creates a new user account.

#### `login(input: LoginInput!): AuthPayload!`
Authenticates a user and returns a JWT.

#### `logout: Boolean!`
Logs out the currently authenticated user.

#### `refreshToken: AuthPayload!`
Issues a new JWT for an active session.

### Work Mutations

#### `createWork(input: WorkInput!): Work!`
Creates a new work.

#### `updateWork(id: ID!, input: WorkInput!): Work!`
Updates an existing work.

#### `deleteWork(id: ID!): Boolean!`
Deletes a work.

### Translation Mutations

#### `createTranslation(input: TranslationInput!): Translation!`
Creates a new translation for a work.

#### `updateTranslation(id: ID!, input: TranslationInput!): Translation!`
Updates an existing translation.

#### `deleteTranslation(id: ID!): Boolean!`
Deletes a translation.

### Like Mutations

#### `createLike(input: LikeInput!): Like!`
Adds a like to a work, translation, or comment. The input must contain exactly one of `workId`, `translationId`, or `commentId`.

*Example:*
```graphql
mutation LikeWork {
  createLike(input: { workId: "123" }) {
    id
    user {
      id
    }
  }
}
```

#### `deleteLike(id: ID!): Boolean!`
Removes a previously added like.

### Comment Mutations

#### `createComment(input: CommentInput!): Comment!`
Adds a comment to a work or translation.

#### `updateComment(id: ID!, input: CommentInput!): Comment!`
Updates an existing comment.

#### `deleteComment(id: ID!): Boolean!`
Deletes a comment.

---

## Core Types

- **`Work`**: Represents a literary work.
- **`Translation`**: Represents a translation of a `Work`.
- **`Author`**: Represents the creator of a `Work`.
- **`User`**: Represents a platform user.
- **`Comment`**: Represents a comment on a `Work` or `Translation`.
- **`Like`**: Represents a like on a `Work`, `Translation`, or `Comment`.
- **`Collection`**: Represents a user-curated collection of works.
- **`WorkStats` / `TranslationStats`**: Represents analytics data for content.