@pliic/sdk

@pliic/sdk

Typed, dependency-free client for the Pliic Widget API (/widget/*).

Use it to build your own feedback UI — a custom suggestion board, a support center embedded in your product — on top of the same API the embedded widget uses. If the prebuilt widget already covers your needs, you don't need this package.

Install

npm install @pliic/sdk

Or load the hosted bundle with no build step (exposes the PliicSDK global):

<script src="https://pliic.com/sdk/v1.js"></script>
<script>
    const { Pliic } = window.PliicSDK;
</script>

Quickstart

import { Pliic } from '@pliic/sdk';

const client = new Pliic({
    appKey: 'pk_live_...',
    userToken: '<end-user JWT, minted server-side with the App sk_>',
    // baseUrl?: defaults to `${window.location.origin}/widget`
    // timeoutMs?: defaults to 10000
});

await client.init();
await client.ping();

• appKey (pk_live_... / pk_test_...) identifies the App and team — find it on the App's Install tab.
• userToken is an optional JWT minted on your server with the App secret key (sk_...). It identifies the end user and unlocks actions like voting. Without it, calls behave as anonymous.
• The browser sends the Origin header automatically; the calling domain must be in the App's allowed domains, just like the embedded widget.

Suggestions

await client.suggestions.list({ search: 'dark mode', status: 'planned' });
await client.suggestions.create({ title: 'Dark mode', description: '...' });
await client.suggestions.vote(123);
await client.suggestions.comments(123, { page: 1 });
await client.suggestions.addComment(123, { body: 'Great idea!' });
await client.suggestions.checkDuplicates({ title: 'Dark mode' });

Tickets

await client.tickets.list({ page: 1 });
await client.tickets.create({ subject: 'Checkout error', body: '...', type: 'bug' });
await client.tickets.get(456);
await client.tickets.reply(456, { body: 'More detail here...' });

Surveys

Read-only, consumer-side surface: fetch the survey currently eligible for the identified end user, submit answers, or dismiss it.

const survey = await client.surveys.active();
// null when there's no eligible survey for this user right now

if (survey) {
    await client.surveys.submit(survey.id, {
        answers: survey.questions.map((question) => ({
            question_id: question.id,
            value: '5',
        })),
    });

    // or, if the user closes it without answering:
    await client.surveys.dismiss(survey.id);
}

Error handling

Any non-2xx response throws PliicApiError with status, message, and the raw body:

import { Pliic, PliicApiError } from '@pliic/sdk';

try {
    await client.suggestions.create({ title: '' });
} catch (error) {
    if (error instanceof PliicApiError) {
        console.error(error.status, error.message, error.body);
    }
}

Requests that exceed the configured timeoutMs are rejected the same way.

Documentation

Full guide, authentication flow, and API reference: https://github.com/4nuunes/pliic/tree/main/packages/sdk

License

MIT Alessandro Nunes