Class FeedbackClient

Primary API client for interacting with CupThread backend services.

Remarks

The FeedbackClient manages network transport, serialization, user authentication tokens, error mapping, and platform targeting across all CupThread API surfaces.

Example

import { FeedbackClient } from '@cupthread/react-native';

const client = new FeedbackClient({
  baseUrl: 'https://api.cupthread.com',
  appKey: 'app_live_sample123',
  defaultPlatform: 'ios',
});

// Submit feedback draft
const result = await client.submit({
  title: 'Crash on launch in offline mode',
  description: 'App freezes on splash screen when cellular data is disabled.',
});
console.log(`Feedback submitted: ${result.submissionId}`);

Constructors

constructor

new FeedbackClient(config: FeedbackClientConfig): FeedbackClient
Creates a new FeedbackClient instance.
Parameters
- config: FeedbackClientConfig
  Initialization options including baseUrl and appKey.
Returns FeedbackClient
Example
```
const client = new FeedbackClient({
  baseUrl: 'https://api.cupthread.com',
  appKey: 'app_prod_998877',
});
```
- Defined in src/client/FeedbackClient.ts:384

Properties

`Readonly`config

config: FeedbackClientConfig

Resolved client configuration.

Methods

fetchAppConfig

fetchAppConfig(options?: RequestOptions | AbortSignal): Promise<PublicAppConfig>
Retrieves public application settings, features, and styling configuration.

As of the September 2026 API sync, the public config endpoints answer private applications (allowPublic = false) with HTTP 404 {"error": "App not found"} identically to unknown app keys, rather than returning a 200 body with allowPublic: false.
Parameters
- Optionaloptions: RequestOptions | AbortSignal
  Optional request options or an AbortSignal.
Returns Promise<PublicAppConfig>
Application metadata and visual theme configuration.
Throws
UnexpectedStatusException If the app key is invalid, private/unpublished (HTTP 404), or the server returns an unexpected status code.
Example
```
const config = await client.fetchAppConfig();
console.log(`Loaded settings for ${config.name}, theme: ${config.sdk.theme}`);
```
- Defined in src/client/FeedbackClient.ts:598

fetchChangelog

fetchChangelog(
options?: RequestOptions | AbortSignal,
): Promise<ChangelogEntry[]>
Retrieves published changelog entries and release notes sorted by publication date descending.
Parameters
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<ChangelogEntry[]>
Chronological list of release notes.
Example
```
const entries = await client.fetchChangelog();
console.log(`Latest release: ${entries[0]?.title}`);
```
- Defined in src/client/FeedbackClient.ts:881

fetchColumns

fetchColumns(options?: RequestOptions | AbortSignal): Promise<BoardColumn[]>
Retrieves all Kanban roadmap columns configured for the application, sorted by position.
Parameters
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<BoardColumn[]>
List of active roadmap columns in display order.
Example
```
const columns = await client.fetchColumns();
columns.forEach(c => console.log(`${c.name} (position: ${c.position})`));
```
- Defined in src/client/FeedbackClient.ts:618

fetchComments

fetchComments(
featureRequestId: string,
options?: RequestOptions | AbortSignal,
): Promise<FeatureRequestComment[]>
Retrieves all discussion comments for a feature request.
Parameters
- featureRequestId: string
  ID of the feature request.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<FeatureRequestComment[]>
List of discussion comments.
Example
```
const comments = await client.fetchComments('fr_123');
console.log(`Loaded ${comments.length} comments.`);
```
- Defined in src/client/FeedbackClient.ts:816

fetchFeatureRequests

fetchFeatureRequests(
    options: {
        limit?: number;
        offset?: number;
        query?: string;
        signal?: AbortSignal;
        timeoutMs?: number;
        tokenTransport?: "query" | "header" | "both";
        userToken: string;
        versionId?: string;
    },
): Promise<ListFeatureRequestsResult>
Fetches paginated feature requests with optional milestone filtering and keyword search.

By default, the caller's identity token is sent via the X-User-Token HTTP header rather than as a URL query parameter to prevent credential leakage into server access logs, reverse proxies, CDNs, and browser history (CWE-598).
Parameters
- options: {
      limit?: number;
      offset?: number;
      query?: string;
      signal?: AbortSignal;
      timeoutMs?: number;
      tokenTransport?: "query" | "header" | "both";
      userToken: string;
      versionId?: string;
  }
  Query parameters including userToken, limit, offset, versionId, and query.
  - Optionallimit?: number
    
    Maximum number of items to return per page (default: 50).
  - Optionaloffset?: number
    
    Page offset index (default: 0).
  - Optionalquery?: string
    
    Optional search query string.
  - Optionalsignal?: AbortSignal
    
    Optional abort signal to cancel the request.
  - OptionaltimeoutMs?: number
    
    Optional timeout in milliseconds for this request.
  - OptionaltokenTransport?: "query" | "header" | "both"
    
    Optional token transport override for this call ('header' | 'both' | 'query'). Defaults to the client configuration's tokenTransport (or 'header').
  - userToken: string
    
    Unique user token to evaluate hasVoted and isOwnRequest states.
  - OptionalversionId?: string
    
    Optional version ID filter.
Returns Promise<ListFeatureRequestsResult>
Paginated list of feature request items.
Example
```
const result = await client.fetchFeatureRequests({
  userToken: 'usr_token_abc',
  query: 'widgets',
  limit: 20,
});
console.log(`Found ${result.total} matching requests.`);
```
- Defined in src/client/FeedbackClient.ts:669

fetchUserProfile

fetchUserProfile(
userId: string,
options?: RequestOptions | AbortSignal,
): Promise<PublicUserProfileResult>
Retrieves the public developer profile, authored applications, and recent comment history.
Parameters
- userId: string
  Target user or developer identifier.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<PublicUserProfileResult>
Public profile details.
Example
```
const profile = await client.fetchUserProfile('usr_42');
console.log(`Developer: ${profile.profile.displayName}`);
```
- Defined in src/client/FeedbackClient.ts:1052

fetchVersions

fetchVersions(options?: RequestOptions | AbortSignal): Promise<AppVersion[]>
Retrieves all release version milestones for the application, sorted by position.
Parameters
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<AppVersion[]>
Array of version milestones.
Example
```
const versions = await client.fetchVersions();
const shipped = versions.filter(v => v.released);
```
- Defined in src/client/FeedbackClient.ts:639

postComment

postComment(
    featureRequestId: string,
    draft: CommentDraft,
    userToken: string,
    options?: RequestOptions | AbortSignal,
): Promise<FeatureRequestComment>
Posts a new discussion comment or reply on a feature request.
Parameters
- featureRequestId: string
  ID of the target feature request.
- draft: CommentDraft
  Comment message content, author info, and optional reply pointers.
- userToken: string
  User token of the commenter.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<FeatureRequestComment>
The created comment record.
Example
```
const comment = await client.postComment('fr_123', {
  body: 'We are targeting release in version 2.2!',
  authorName: 'Alex',
}, userToken);
```
- Defined in src/client/FeedbackClient.ts:845

prepareChangelogOverlay

prepareChangelogOverlay(
    options?: PrepareChangelogOverlayOptions,
): Promise<
    | {
        appearance: SdkAppearance;
        entries: ChangelogEntry[];
        latestKey: string;
    }
    | null,
>
Evaluates app configuration and fetches entries for the What's-New modal sheet.
Parameters
- Optionaloptions: PrepareChangelogOverlayOptions
  Optional filtering settings including onlyIfUnseen.
Returns Promise<
    | {
        appearance: SdkAppearance;
        entries: ChangelogEntry[];
        latestKey: string;
    }
    | null,
>
Overlay payload or null if changelog feature is disabled, empty, or already seen.
Example
```
const overlayData = await client.prepareChangelogOverlay({ onlyIfUnseen: true });
if (overlayData) {
  console.log(`Ready to show ${overlayData.entries.length} release highlights.`);
}
```
- Defined in src/client/FeedbackClient.ts:907

submit

submit(
    draft: FeedbackDraft,
    userToken?: string,
    options?: RequestOptions | AbortSignal,
): Promise<FeedbackSubmissionResult>
Submits a user feedback draft, bug report, or feature inquiry.

Note: Platform allowlist enforcement against PublicAppConfig.allowedPlatforms happens at the composer layer (such as FeedbackComposer) via resolveAllowedPlatform. Direct client calls forward the draft's platform or client defaultPlatform directly to the intake endpoint.
Parameters
- draft: FeedbackDraft
  The feedback payload including title, description, and optional attachments.
- OptionaluserToken: string
  Optional persistent anonymous or authenticated user token.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<FeedbackSubmissionResult>
A promise resolving to the submission result metadata.
Throws
QuotaExceededException If the workspace has reached its monthly submission quota (402).

Throws
InactiveSubscriptionException If the workspace subscription is inactive or canceled (402).

Throws
PaymentRequiredException If the intake endpoint responds with HTTP 402 Payment Required.

Throws
UnexpectedStatusException If the server returns a non-2xx status code.

Throws
TurnstileRequiredException If the intake endpoint demands Cloudflare Turnstile verification and no valid turnstileToken was supplied.

Throws
InvalidResponseException If a network failure occurs or JSON parsing fails.
Example
```
const result = await client.submit({
  title: 'Dark mode contrast issue',
  description: 'Secondary text on settings screen is hard to read in dark mode.',
  reporterEmail: 'user@example.com',
});
```
- Defined in src/client/FeedbackClient.ts:468

submitFeatureRequest

submitFeatureRequest(
    draft: FeatureRequestDraft,
    userToken: string,
    options?: RequestOptions | AbortSignal,
): Promise<FeatureRequestSubmissionResult>
Proposes a new public feature request.
Parameters
- draft: FeatureRequestDraft
  Feature request proposal details (title, description, requesterName).
- userToken: string
  Current user identifier token.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<FeatureRequestSubmissionResult>
Submission confirmation and moderation pending status.
Throws
QuotaExceededException If the workspace has reached its monthly submission quota (402).

Throws
InactiveSubscriptionException If the workspace subscription is inactive or canceled (402).

Throws
PaymentRequiredException If the intake endpoint responds with HTTP 402 Payment Required.

Throws
TurnstileRequiredException If the intake endpoint demands Cloudflare Turnstile verification and no valid turnstileToken was supplied.
Example
```
const result = await client.submitFeatureRequest({
  title: 'Apple Watch Complications support',
  description: 'Provide circular and rectangular lock screen complications.',
}, userToken);
```
- Defined in src/client/FeedbackClient.ts:750

subscribeToChangelog

subscribeToChangelog(
    email: string,
    userToken: string,
    options?: RequestOptions | AbortSignal,
): Promise<ChangelogSubscriptionResult>
Subscribes an email address to future changelog and release note announcements.
Parameters
- email: string
  Target email address to subscribe.
- userToken: string
  Current user token.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<ChangelogSubscriptionResult>
Subscription status confirmation.
Example
```
const sub = await client.subscribeToChangelog('user@example.com', userToken);
if (sub.subscribed) {
  console.log('Successfully subscribed to release notes.');
}
```
- Defined in src/client/FeedbackClient.ts:957

toggleVote

toggleVote(
    featureRequestId: string,
    userToken: string,
    options?: RequestOptions | AbortSignal,
): Promise<VoteResult>
Toggles an upvote on a specified feature request for the given user token.
Parameters
- featureRequestId: string
  ID of the target feature request.
- userToken: string
  User token performing the vote.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<VoteResult>
Updated vote status and total vote count.
Example
```
const vote = await client.toggleVote('fr_123', userToken);
console.log(`Voted: ${vote.voted}, New count: ${vote.voteCount}`);
```
- Defined in src/client/FeedbackClient.ts:786

unsubscribeFromChangelog

unsubscribeFromChangelog(
email: string,
options?: RequestOptions | AbortSignal,
): Promise<ChangelogUnsubscribeResult>
Unsubscribes an email address from changelog notification emails.
Parameters
- email: string
  Email address to remove.
- Optionaloptions: RequestOptions | AbortSignal
Returns Promise<ChangelogUnsubscribeResult>
Confirmation result.
Example
```
await client.unsubscribeFromChangelog('user@example.com');
```
- Defined in src/client/FeedbackClient.ts:984

updateUserAttributes

updateUserAttributes(
    options: {
        currency?: string;
        isPaying?: boolean;
        mrr?: number;
        plan?: string;
        signal?: AbortSignal;
        timeoutMs?: number;
        userToken: string;
    },
): Promise<UserAttributesUpdateResult>
Reports customer tier, subscription plan, or revenue metrics for a user token.
Parameters
- options: {
      currency?: string;
      isPaying?: boolean;
      mrr?: number;
      plan?: string;
      signal?: AbortSignal;
      timeoutMs?: number;
      userToken: string;
  }
  User attributes including subscription status, plan name, and MRR.
Returns Promise<UserAttributesUpdateResult>
Update confirmation.
Example
```
await client.updateUserAttributes({
  userToken: 'usr_token_abc',
  isPaying: true,
  plan: 'Pro Annual',
  mrr: 29.99,
  currency: 'USD',
});
```
- Defined in src/client/FeedbackClient.ts:1015

uploadAttachment

uploadAttachment(options: UploadAttachmentOptions): Promise<FeedbackAttachment>
Uploads a file, image, or log attachment to CupThread storage.
Parameters
- options: UploadAttachmentOptions
  Attachment file payload, filename, MIME type, and optional user token options.
Returns Promise<FeedbackAttachment>
The uploaded attachment descriptor ready to attach to FeedbackDraft.attachments.
Remarks
Direct callers of uploadAttachment should supply options.userToken (e.g. from useCupThreadUserToken) so uploads are properly attributed to the user's session and authenticated via the X-User-Token header.

Throws
AuthenticationRequiredException If the request is rejected as unauthenticated (401).

Throws
RequestTimeoutException If upload times out.

Throws
UnexpectedStatusException If upload endpoint responds with an error.

Throws
UnreadableUploadResponseException If response body is malformed.

Throws
InvalidResponseException If network transport fails.
Example
```
const attachment = await client.uploadAttachment({
  file: { uri: 'file:///path/to/screenshot.jpg' },
  filename: 'screenshot.jpg',
  mimeType: 'image/jpeg',
  userToken,
});
```
- Defined in src/client/FeedbackClient.ts:538

Class FeedbackClient

Remarks

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns FeedbackClient

Example

Properties

Readonlyconfig

Methods

fetchAppConfig

Parameters

Returns Promise<PublicAppConfig>

Throws

Example

fetchChangelog

Parameters

Returns Promise<ChangelogEntry[]>

Example

fetchColumns

Parameters

Returns Promise<BoardColumn[]>

Example

fetchComments

Parameters

Returns Promise<FeatureRequestComment[]>

Example

fetchFeatureRequests

Parameters

Optionallimit?: number

Optionaloffset?: number

Optionalquery?: string

Optionalsignal?: AbortSignal

OptionaltimeoutMs?: number

OptionaltokenTransport?: "query" | "header" | "both"

userToken: string

OptionalversionId?: string

Returns Promise<ListFeatureRequestsResult>

Example

fetchUserProfile

Parameters

Returns Promise<PublicUserProfileResult>

Example

fetchVersions

Parameters

Returns Promise<AppVersion[]>

Example

postComment

Parameters

Returns Promise<FeatureRequestComment>

Example

prepareChangelogOverlay

Parameters

Returns Promise< | { appearance: SdkAppearance; entries: ChangelogEntry[]; latestKey: string; } | null,>

Example

submit

Parameters

Returns Promise<FeedbackSubmissionResult>

Throws

Throws

Throws

Throws

Throws

Throws

Example

submitFeatureRequest

Parameters

Returns Promise<FeatureRequestSubmissionResult>

Throws

Throws

Throws

Throws

Example

subscribeToChangelog

Parameters

`Readonly`config

`Optional`limit?: number

`Optional`offset?: number

`Optional`query?: string

`Optional`signal?: AbortSignal

`Optional`timeoutMs?: number

`Optional`tokenTransport?: "query" | "header" | "both"

`Optional`versionId?: string

Returns Promise<
| {
appearance: SdkAppearance;
entries: ChangelogEntry[];
latestKey: string;
}
| null,
>