FastComments Java SDK

Надайте вашому кодовому агенту контекст FastComments, який йому потрібен — віджети, конфігурація, Secure SSO, REST API та SDK:

npx skills add fastcomments/skills

Працює з Claude Code, Codex, Cursor, Copilot, Gemini та будь‑яким іншим агентом, який підтримує skills CLI.

Maven

Додайте репозиторій Repsy до POM-файлу вашого проєкту:

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

Потім додайте потрібні залежності:

<dependencies>
    <!-- API Client -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- Core Library (includes SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- PubSub Library (for live events) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>3.1.1</version>
    </dependency>
</dependencies>

Gradle

Додайте репозиторій Repsy до файлу build.gradle:

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // API Client
    implementation "com.fastcomments:client:3.1.1"
    
    // Core Library (includes SSO)
    implementation "com.fastcomments:core:3.1.1"
    
    // PubSub Library (for live events)
    implementation "com.fastcomments:pubsub:3.1.1"
}

Вміст бібліотеки

Ця бібліотека містить три модулі: згенерований API-клієнт, основну Java-бібліотеку з написаними вручну утилітами для спрощення роботи з API, а також модуль pubsub — бібліотеку для підписки на стрічки змін.

• Документація бібліотеки API-клієнта
• Документація основної бібліотеки, включно з прикладами SSO
• Документація бібліотеки PubSub

Публічні та захищені API

В API-клієнті є три класи: DefaultApi, PublicApi та ModerationApi. DefaultApi містить методи, які потребують ваш API-ключ, а PublicApi — методи, які можна викликати безпосередньо з браузера/мобільного пристрою тощо без автентифікації.

ModerationApi надає розширений набір швидких API для модерації в реальному часі. Кожен метод ModerationApi приймає параметр sso і може автентифікуватися через SSO або cookie сесії FastComments.com.

Використання автентифікованих API (DefaultApi)

Важливо: Ви повинні встановити свій API ключ у ApiClient перед виконанням автентифікованих запитів. Якщо ви цього не зробите, запити завершаться помилкою 401.

import com.fastcomments.invoker.ApiClient;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.api.DefaultApi;
import com.fastcomments.model.*;

public class Example {
    public static void main(String[] args) {
        // Створіть та налаштуйте клієнт API
        ApiClient apiClient = new ApiClient();

        // ОБОВ'ЯЗКОВО: Встановіть свій API-ключ (отримуйте його в панелі керування FastComments)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // Створіть екземпляр API з налаштованим клієнтом
        DefaultApi api = new DefaultApi(apiClient);

        // Тепер ви можете виконувати автентифіковані виклики API
        try {
            // Приклад: Додати SSO-користувача
            CreateAPISSOUserData userData = new CreateAPISSOUserData();
            userData.setId("user-123");
            userData.setEmail("user@example.com");
            userData.setDisplayName("John Doe");

            AddSSOUserAPIResponse response = api.addSSOUser("YOUR_TENANT_ID", userData)
                .execute();
            System.out.println("User created: " + response);

        } catch (ApiException e) {
            System.err.println("Error: " + e.getResponseBody());
            // Типові помилки:
            // - 401: API-ключ відсутній або недійсний
            // - 400: Помилка валідації запиту
        }
    }
}

Використання публічних API (PublicApi)

Публічні кінцеві точки не потребують автентифікації:

import com.fastcomments.api.PublicApi;
import com.fastcomments.invoker.ApiException;

PublicApi publicApi = new PublicApi();

try {
    var response = publicApi.getCommentsPublic("YOUR_TENANT_ID", "page-url-id")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Використання модераційних API (ModerationApi)

Клас ModerationApi керує панеллю модератора. Кожен метод приймає параметр sso, який ідентифікує модератора, автентифікованого через SSO, від імені якого виконується запит:

import com.fastcomments.api.ModerationApi;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.model.*;

ModerationApi moderationApi = new ModerationApi();

try {
    // Перелік коментарів, що очікують модерації
    ModerationAPIGetCommentsResponse response = moderationApi.getApiComments()
        .sso("YOUR_SSO_TOKEN")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Типові проблеми

1. 401 "missing-api-key" помилка: Переконайтеся, що ви викликаєте apiClient.setApiKey("YOUR_KEY") перед створенням екземпляра DefaultApi.
2. Неправильний клас API: Використовуйте DefaultApi для серверних автентифікованих запитів, PublicApi для клієнтських/публічних запитів.
3. Null API key: SDK мовчки пропустить автентифікацію, якщо API-ключ дорівнює null, що призведе до помилок 401.

Ідентифікатори трансляцій

Ви побачите, що в деяких викликах API потрібно передавати broadcastId. Коли ви отримуєте події, ви отримаєте назад цей ідентифікатор, щоб знати, що слід ігнорувати подію, якщо ви плануєте оптимістично застосовувати зміни на клієнті (що, ймовірно, варто зробити, оскільки це забезпечує найкращий досвід). Передайте тут UUID. Ідентифікатор має бути достатньо унікальним, щоб не зустрічатися двічі в одній сесії браузера.