cupthread-android-sdk/dev.cupthread.feedback/FeedbackClient

FeedbackClient

Primary HTTP API client for interacting with the CupThread developer platform.

Provides asynchronous, coroutine-based access to:

Feedback drafting and binary attachment uploads (submit, uploadAttachment)
Public application configuration and styling (fetchAppConfig)
Roadmap kanban boards and milestones (fetchColumns, fetchVersions)
Feature request submissions, filtering, and voting (fetchFeatureRequests, submitFeatureRequest, toggleVote)
Threaded feature request comments and replies (fetchComments, postComment)
What's-New changelog streams and email subscriptions (fetchChangelog, subscribeToChangelog, unsubscribeFromChangelog)
User telemetry and customer segment attributes (updateUserAttributes)
Public user profiles (fetchUserProfile)

Thread Safety and Concurrency

Every public method is a suspend function that automatically dispatches network operations on Dispatchers.IO. FeedbackClient maintains no mutable state and is safe to use concurrently from multiple coroutines. You should create a single instance during application startup and share it across your dependency injection graph.

Error Handling

All API and network failures are wrapped in subclasses of FeedbackException, allowing predictable and uniform exception handling:

FeedbackException.AuthenticationRequired: Endpoint requires an authenticated or permitted user session (HTTP 401).
FeedbackException.UnexpectedStatus: Server returned an unexpected HTTP error code.
FeedbackException.InvalidResponse: Network transport failure or malformed JSON payload.
FeedbackException.UnreadableUploadResponse: Upload succeeded but server response descriptor was unreadable.

Example Initialization

val config = FeedbackClientConfig(
    baseUrl = "https://api.cupthread.com",
    appKey = "app_live_yourConsoleAppKey",
    defaultPlatform = FeedbackPlatform.ANDROID
)
val client = FeedbackClient(config)
val userToken = UserTokenStore.create(context).token

lifecycleScope.launch {
    try {
        val appConfig = client.fetchAppConfig()
        println("Loaded app: ${appConfig.name}")
    } catch (e: FeedbackException) {
        Log.e("CupThread", "Failed to load config", e)
    }
}

Parameters

config

Immutable client configuration (FeedbackClientConfig).

transport

Internal HTTP transport implementation; defaults to standard HttpURLConnection.

Constructors

FeedbackClient

constructor(config: FeedbackClientConfig)

Constructs a FeedbackClient with default HTTP URL connection transport.

Properties

config

val config: FeedbackClientConfig

Functions

fetchAppConfig

suspend fun fetchAppConfig(): PublicAppConfig

Fetches public app configuration from GET /api/v1/public/config/{appKey}.

fetchChangelog

suspend fun fetchChangelog(): List<ChangelogEntry>

Fetches published changelog entries and release notes from GET /api/v1/public/apps/{appKey}/changelog.

fetchColumns

suspend fun fetchColumns(): List<BoardColumn>

Fetches the roadmap kanban columns from GET /api/v1/public/columns/{appKey}.

fetchComments

suspend fun fetchComments(featureRequestId: String): List<FeatureRequestComment>

Fetches public comments on a feature request from GET /api/v1/feature-requests/{id}/comments.

fetchFeatureRequests

suspend fun fetchFeatureRequests(userToken: String, limit: Int = 50, offset: Int = 0, versionId: String? = null, query: String? = null): ListFeatureRequestsResult

Fetches a paginated list of public feature requests from GET /api/v1/feature-requests.

fetchUserProfile

suspend fun fetchUserProfile(userId: String): PublicUserProfileResult

Fetches a public user profile from GET /api/v1/users/{userId}/profile.

fetchVersions

suspend fun fetchVersions(): List<AppVersion>

Fetches milestone release versions from GET /api/v1/public/versions/{appKey}.

hasSeenChangelog

fun hasSeenChangelog(context: Context, versionOrId: String): Boolean

Checks whether the user has already viewed the changelog for versionOrId on this device.

markChangelogSeen

fun markChangelogSeen(context: Context, versionOrId: String)

Marks the changelog for versionOrId as seen on this device.

postComment

suspend fun postComment(featureRequestId: String, draft: CommentDraft, userToken: String): FeatureRequestComment

Posts a new comment or threaded @reply on a feature request via POST /api/v1/feature-requests/{id}/comments.

prepareChangelogOverlay

suspend fun prepareChangelogOverlay(context: Context? = null, onlyIfUnseen: Boolean = false): Pair<List<ChangelogEntry>, SdkAppearance>?

Prepares changelog entries and appearance styling for What's-New presentation overlays (dev.cupthread.feedback.ui.ChangelogOverlay and dev.cupthread.feedback.ui.presentLatestChangelog).

presentLatestChangelog

suspend fun FeedbackClient.presentLatestChangelog(activity: Activity, onlyIfUnseen: Boolean = false, autoMarkSeen: Boolean = true): Boolean

Convenience extension function that fetches console-configured What's-New copy and presents a modal bottom sheet dialog directly over an Android Activity.

submit

suspend fun submit(draft: FeedbackDraft, userToken: String? = null): FeedbackSubmissionResult

Submits a completed feedback draft to POST /api/v1/feedback.

submitFeatureRequest

suspend fun submitFeatureRequest(draft: FeatureRequestDraft, userToken: String): FeatureRequestSubmissionResult

Submits a new feature request proposal to POST /api/v1/feature-requests.

subscribeToChangelog

suspend fun subscribeToChangelog(email: String, userToken: String): ChangelogSubscriptionResult

Subscribes an email address to product update emails via POST /api/v1/public/apps/{appKey}/changelog/subscribe.

toggleVote

suspend fun toggleVote(featureRequestId: String, userToken: String): VoteResult

Toggles an upvote on a feature request via POST /api/v1/feature-requests/{id}/vote.

unsubscribeFromChangelog

suspend fun unsubscribeFromChangelog(email: String): ChangelogUnsubscribeResult

Unsubscribes an email address from product update emails via POST /api/v1/public/apps/{appKey}/changelog/unsubscribe.

updateUserAttributes

suspend fun updateUserAttributes(userToken: String, isPaying: Boolean? = null, plan: String? = null, mrr: Double? = null, currency: String? = null): UserAttributesUpdateResult

Reports self-declared user segmentation attributes and telemetry via PUT /api/v1/public/apps/{appKey}/user.

uploadAttachment

suspend fun uploadAttachment(data: ByteArray, filename: String, mimeType: String, preferredKind: FeedbackAttachment.Kind? = null): FeedbackAttachment

Uploads a binary file or screenshot attachment to storage and returns a descriptor ready to be attached to a FeedbackDraft.