fdbck-node 0.1.0

package/README.md

@@ -0,0 +1,315 @@
+# @fdbck/node
+
+Official Node.js SDK for [fdbck](https://fdbck.sh) (read feedback) - a simple API to programmatically collect and structure feedback from your users.
+
+Full TypeScript definitions included.
+
+```ts
+import { Fdbck } from '@fdbck/node';
+
+const fdbck = new Fdbck('sk_fdbck_...');
+
+const question = await fdbck.questions.create({
+  question: 'How was your first purchase?',
+  type: 'rating',
+  ratingConfig: { min: 1, max: 5 },
+  expiresIn: 172800,
+});
+
+const token = await fdbck.tokens.create(question.id, {
+  respondent: 'user_8f2a',
+});
+
+// Trigger the question in your app using the sdk
+// ...
+
+// Or send this URL to your user — they answer on fdbck's hosted page
+console.log(token.respondUrl);
+
+// Get a webhook for each response
+// ...
+
+// Later, read the results
+const results = await fdbck.questions.results(question.id);
+console.log(results.data); // [{ respondent: 'user_8f2a', value: 5, ... }]
+```
+
+## Install
+
+```sh
+npm install @fdbck/node
+```
+
+Requires Node.js 18 or later. Zero runtime dependencies.
+
+## Get your API key
+
+Sign up at [dashboard.fdbck.sh](https://dashboard.fdbck.sh) and grab your API key from the **API Keys** page. Keys start with `sk_fdbck_`.
+
+## Quick start
+
+The typical workflow is: **create a question**, **generate a token** for each respondent, **collect their answer**, and **read the results**.
+
+Respondents can answer via fdbck's hosted response page, or directly from your app using a UI SDK ([React](https://github.com/fdbck-sh), [Flutter](https://github.com/fdbck-sh)).
+
+### 1. Create a question
+
+```ts
+const question = await fdbck.questions.create({
+  question: 'How would you rate our onboarding?',
+  type: 'rating',
+  ratingConfig: {
+    min: 1,
+    max: 5,
+    minLabel: 'Terrible',
+    maxLabel: 'Loved it',
+  },
+  expiresIn: 86400, // 24 hours
+});
+```
+
+Four question types are available:
+
+| Type | Description | Required fields | Response `value` |
+|------|-------------|-----------------|------------------|
+| `yes_no` | Yes or no (options are generated automatically) | — | `true` or `false` |
+| `single_choice` | Pick one option | `options` | `"Option A"` |
+| `multiple_choice` | Pick one or more | `options` | `["Option A", "Option B"]` |
+| `rating` | Numeric scale | `ratingConfig` | `4` |
+
+### 2. Generate tokens
+
+Each respondent gets a unique, single-use token that authorizes them to answer once.
+
+```ts
+const token = await fdbck.tokens.create(question.id, {
+  respondent: 'user_42', // your internal user ID (optional)
+});
+
+// token.respondUrl → https://fdbck.sh/f/V1StGXR8_Z5jdHi6
+// token.expiresAt  → ISO timestamp (1 hour from creation)
+```
+
+Send `token.respondUrl` to your user however you like — email, in-app notification, SMS, etc. They open the link, answer on fdbck's hosted response page, and see a confirmation message. The page does not redirect — if you need to bring users back to your app, include a link in the question text or follow up after you receive the response.
+
+You can also embed the question directly in your app using `@fdbck/react` or `@fdbck/flutter` — pass the `token.token` value to the UI component and it handles submission for you.
+
+### 3. Read results
+
+Poll for responses at any time — they're available as soon as respondents answer.
+
+```ts
+const results = await fdbck.questions.results(question.id);
+
+for (const response of results.data) {
+  console.log(response.respondent, response.value);
+  // → 'user_42', 5
+}
+
+// Results are paginated — follow the cursor for more
+if (results.pagination.hasMore) {
+  const nextPage = await fdbck.questions.results(question.id, {
+    cursor: results.pagination.nextCursor,
+  });
+}
+```
+
+### 4. Or use webhooks
+
+Get notified in real time instead of polling.
+
+```ts
+const question = await fdbck.questions.create({
+  question: 'How was your experience?',
+  type: 'yes_no',
+  expiresIn: 86400,
+  webhookUrl: 'https://myapp.com/hooks/fdbck',
+  webhookTrigger: 'each_response', // or 'expiry', 'both'
+});
+```
+
+Verify incoming webhooks with the signing secret:
+
+```ts
+const isValid = fdbck.verifyWebhook(rawBody, signature, webhookSecret);
+// signature = X-FDBCK-Signature header
+// webhookSecret = question.webhookSecret from creation response
+```
+
+`verifyWebhook` is also available as a standalone import if you don't need a client instance:
+
+```ts
+import { verifyWebhook } from '@fdbck/node';
+```
+
+## API reference
+
+### `new Fdbck(apiKey, options?)`
+
+| Option | Type | Default |
+|--------|------|---------|
+| `baseUrl` | `string` | `https://api.fdbck.sh` |
+| `timeout` | `number` | `30000` (ms) |
+
+### Questions
+
+#### `fdbck.questions.create(options)` → `Question`
+
+Creates a new question.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `question` | `string` | Yes | The question text (max 500 chars) |
+| `type` | `QuestionType` | Yes | `yes_no`, `single_choice`, `multiple_choice`, or `rating` |
+| `options` | `string[]` | For choice types | 2–20 answer options |
+| `ratingConfig` | `RatingConfig` | For `rating` | `{ min, max, minLabel?, maxLabel? }` |
+| `expiresIn` or `expiresAt` | `number` or `string` | Yes (exactly one) | Seconds from now, or ISO 8601 timestamp |
+| `maxResponses` | `number` | No | Auto-complete after N responses |
+| `webhookUrl` | `string` | No | HTTPS URL to receive events |
+| `webhookTrigger` | `WebhookTrigger` | No | `each_response`, `expiry`, or `both` |
+| `metadata` | `Record<string, string>` | No | Arbitrary key-value pairs |
+| `themeColor` | `string` | No | Hex color for response page |
+| `themeMode` | `'light' \| 'dark'` | No | Response page theme |
+| `hideBranding` | `boolean` | No | Hide "Powered by fdbck" (paid plans) |
+
+#### `fdbck.questions.get(id)` → `Question`
+
+Returns a single question by ID.
+
+#### `fdbck.questions.list(options?)` → `PaginatedList<Question>`
+
+Returns a paginated list of questions.
+
+```ts
+const page = await fdbck.questions.list({ status: 'active', limit: 20 });
+
+console.log(page.data);                // Question[]
+console.log(page.pagination.hasMore);  // boolean
+console.log(page.pagination.nextCursor); // string | null
+
+// Fetch the next page
+if (page.pagination.nextCursor) {
+  const next = await fdbck.questions.list({
+    status: 'active',
+    cursor: page.pagination.nextCursor,
+  });
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `status` | `QuestionStatus` | Filter by `active`, `completed`, `expired`, or `cancelled` |
+| `limit` | `number` | Items per page |
+| `cursor` | `string` | Cursor from a previous page's `pagination.nextCursor` |
+
+#### `fdbck.questions.listAll(options?)` → `AsyncGenerator<Question>`
+
+Auto-paginates through all questions. Same options as `list` except `cursor`.
+
+Each page is fetched sequentially as you consume the iterator — there is no prefetching. If you have a large number of questions, be mindful of the number of API calls this produces.
+
+```ts
+for await (const question of fdbck.questions.listAll({ status: 'active' })) {
+  console.log(question.id, question.question);
+}
+```
+
+#### `fdbck.questions.results(id, options?)` → `PaginatedList<ResponseItem>`
+
+Returns individual responses to a question, paginated.
+
+```ts
+const page = await fdbck.questions.results(question.id, { limit: 50 });
+
+for (const response of page.data) {
+  console.log(response.respondent); // 'user_42' or null
+  console.log(response.value);      // answer value (type depends on question type)
+  console.log(response.createdAt);  // ISO timestamp
+}
+
+// Next page
+if (page.pagination.hasMore) {
+  const next = await fdbck.questions.results(question.id, {
+    cursor: page.pagination.nextCursor,
+  });
+}
+```
+
+Each `ResponseItem` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Response ID |
+| `questionId` | `string` | Parent question ID |
+| `value` | `unknown` | The answer — `true`/`false` for yes_no, `"Option A"` for single_choice, `["A", "B"]` for multiple_choice, `4` for rating |
+| `respondent` | `string \| null` | The respondent identifier you passed when creating the token |
+| `createdAt` | `string` | ISO timestamp |
+
+#### `fdbck.questions.cancel(id)` → `void`
+
+Cancels a question. It stops accepting responses immediately.
+
+#### `fdbck.questions.webhooks(id, options?)` → `PaginatedList<WebhookDelivery>`
+
+Returns webhook delivery logs for a question. Same pagination options as `results`.
+
+### Tokens
+
+#### `fdbck.tokens.create(questionId, options?)` → `TokenResult`
+
+Generates a single-use respondent token.
+
+```ts
+const token = await fdbck.tokens.create(question.id, {
+  respondent: 'user_42', // optional — your internal ID for this respondent
+});
+
+token.token;      // the raw token string
+token.respondUrl; // full URL to the hosted response page
+token.expiresAt;  // ISO timestamp (1 hour from creation)
+```
+
+### Account
+
+```ts
+const info = await fdbck.me();
+// info.organization → { id, name, plan }
+// info.usage → { responsesUsed, responsesLimit }
+```
+
+## Error handling
+
+```ts
+import { FdbckApiError, FdbckNetworkError } from '@fdbck/node';
+
+try {
+  await fdbck.questions.create({ ... });
+} catch (err) {
+  if (err instanceof FdbckApiError) {
+    console.error(err.status);  // 401, 422, etc.
+    console.error(err.code);    // 'unauthorized', 'validation_error', etc.
+    console.error(err.message); // Human-readable message
+    console.error(err.details); // { fields: [...] } for validation errors
+  }
+
+  if (err instanceof FdbckNetworkError) {
+    console.error(err.message); // 'fetch failed', timeout, etc.
+    console.error(err.cause);   // Original error
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- An API key from [dashboard.fdbck.sh](https://dashboard.fdbck.sh)
+
+## Links
+
+- [Documentation](https://docs.fdbck.sh)
+- [Dashboard](https://dashboard.fdbck.sh)
+- [GitHub](https://github.com/fdbck-sh)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,235 @@
+/** Question type */
+type QuestionType = 'yes_no' | 'single_choice' | 'multiple_choice' | 'rating';
+/** Question status */
+type QuestionStatus = 'collecting' | 'completed' | 'expired' | 'cancelled';
+/** Webhook trigger */
+type WebhookTrigger = 'expiry' | 'each_response' | 'both';
+/** Rating scale configuration */
+interface RatingConfig {
+    min: number;
+    max: number;
+    minLabel?: string;
+    maxLabel?: string;
+}
+/** Options for creating a question */
+interface CreateQuestionOptions {
+    question: string;
+    type: QuestionType;
+    options?: string[];
+    ratingConfig?: RatingConfig;
+    /** Seconds until expiry — mutually exclusive with `expiresAt` */
+    expiresIn?: number;
+    /** ISO date string — mutually exclusive with `expiresIn` */
+    expiresAt?: string;
+    maxResponses?: number;
+    webhookUrl?: string;
+    webhookTrigger?: WebhookTrigger;
+    metadata?: Record<string, string>;
+    themeColor?: string;
+    themeMode?: 'light' | 'dark';
+    hideBranding?: boolean;
+    welcomeMessage?: string;
+    thankYouMessage?: string;
+}
+/** A question resource */
+interface Question {
+    id: string;
+    question: string;
+    type: QuestionType;
+    options: string[] | null;
+    ratingConfig?: RatingConfig;
+    status: QuestionStatus;
+    expiresAt: string;
+    maxResponses: number | null;
+    webhookUrl?: string;
+    webhookTrigger?: WebhookTrigger;
+    webhookSecret?: string;
+    metadata: Record<string, string> | null;
+    themeColor: string;
+    themeMode: string;
+    hideBranding: boolean;
+    welcomeMessage: string | null;
+    thankYouMessage: string | null;
+    totalResponses?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Options for listing questions */
+interface ListQuestionsOptions {
+    cursor?: string;
+    limit?: number;
+    status?: QuestionStatus;
+    sort?: 'created_at' | 'updated_at';
+    order?: 'asc' | 'desc';
+    createdAfter?: string;
+    createdBefore?: string;
+}
+/** Paginated list envelope */
+interface PaginatedList<T> {
+    data: T[];
+    pagination: {
+        nextCursor: string | null;
+        hasMore: boolean;
+    };
+}
+/** A single response item */
+interface ResponseItem {
+    id: string;
+    questionId: string;
+    value: unknown;
+    respondent: string | null;
+    createdAt: string;
+}
+/** Options for listing responses */
+interface ListResponsesOptions {
+    cursor?: string;
+    limit?: number;
+}
+/** A webhook delivery log entry */
+interface WebhookDelivery {
+    id: string;
+    event: string;
+    success: boolean;
+    statusCode: number | null;
+    attempts: number;
+    error: string | null;
+    createdAt: string;
+    nextRetryAt: string | null;
+}
+/** Options for listing webhook deliveries */
+interface ListWebhooksOptions {
+    cursor?: string;
+    limit?: number;
+}
+/** Options for creating a token */
+interface CreateTokenOptions {
+    respondent?: string;
+    metadata?: Record<string, string>;
+}
+/** Token creation result */
+interface TokenResult {
+    token: string;
+    respondUrl: string;
+    expiresAt: string;
+}
+/** Account info from GET /v1/me */
+interface AccountInfo {
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+    } | null;
+    organization: {
+        id: string;
+        name: string;
+        slug: string;
+        plan: string;
+        role: string | null;
+        responsesUsed: number;
+        responsesLimit: number | null;
+        periodStartsAt: string;
+        periodEndsAt: string | null;
+        consecutiveOverageMonths: number;
+        hasBilling: boolean;
+    } | null;
+}
+/** Aggregated results with paginated individual responses */
+interface QuestionResultsResponse {
+    questionId: string;
+    type: string;
+    status: string;
+    totalResponses: number;
+    results: Record<string, unknown>;
+    data: ResponseItem[];
+    pagination: {
+        nextCursor: string | null;
+        hasMore: boolean;
+    };
+}
+/** SDK client options */
+interface FdbckOptions {
+    /** Base URL for the API (default: https://api.fdbck.sh) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+
+declare class QuestionsResource {
+    private readonly client;
+    constructor(client: Fdbck);
+    /** Create a new question. */
+    create(opts: CreateQuestionOptions): Promise<Question>;
+    /** Get a question by ID. */
+    get(id: string): Promise<Question>;
+    /** List questions with pagination. */
+    list(opts?: ListQuestionsOptions): Promise<PaginatedList<Question>>;
+    /** Auto-paginate through all questions. */
+    listAll(opts?: Omit<ListQuestionsOptions, 'cursor'>): AsyncGenerator<Question>;
+    /** Get responses for a question with aggregated results. */
+    results(id: string, opts?: ListResponsesOptions): Promise<QuestionResultsResponse>;
+    /** Cancel (delete) a question. */
+    cancel(id: string): Promise<Question>;
+    /** Get webhook delivery logs for a question. */
+    webhooks(id: string, opts?: ListWebhooksOptions): Promise<PaginatedList<WebhookDelivery>>;
+}
+
+declare class TokensResource {
+    private readonly client;
+    constructor(client: Fdbck);
+    /** Create a respondent token for a question. */
+    create(questionId: string, opts?: CreateTokenOptions): Promise<TokenResult>;
+}
+
+interface RequestOptions {
+    body?: Record<string, unknown>;
+    query?: Record<string, string>;
+}
+declare class Fdbck {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    readonly questions: QuestionsResource;
+    readonly tokens: TokensResource;
+    constructor(apiKey: string, options?: FdbckOptions);
+    /** Make an authenticated request to the fdbck API. */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Get current account info. */
+    me(): Promise<AccountInfo>;
+    /** Verify a webhook signature. */
+    verifyWebhook(rawBody: string, signature: string, secret: string): boolean;
+}
+
+/** Base error for all fdbck SDK errors */
+declare class FdbckError extends Error {
+    constructor(message: string);
+}
+/** Error returned by the fdbck API */
+declare class FdbckApiError extends FdbckError {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: {
+        fields: string[];
+    };
+    constructor(status: number, code: string, message: string, details?: {
+        fields: string[];
+    });
+}
+/** Network-level error (fetch failure, timeout, etc.) */
+declare class FdbckNetworkError extends FdbckError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * Verify an incoming webhook signature from fdbck.
+ *
+ * @param rawBody - The raw JSON string body of the webhook request
+ * @param signature - The value of the `X-FDBCK-Signature` header
+ * @param secret - The webhook secret from question creation
+ * @returns `true` if the signature is valid
+ */
+declare function verifyWebhook(rawBody: string, signature: string, secret: string): boolean;
+
+export { type AccountInfo, type CreateQuestionOptions, type CreateTokenOptions, Fdbck, FdbckApiError, FdbckError, FdbckNetworkError, type FdbckOptions, type ListQuestionsOptions, type ListResponsesOptions, type ListWebhooksOptions, type PaginatedList, type Question, type QuestionResultsResponse, type QuestionStatus, type QuestionType, type RatingConfig, type ResponseItem, type TokenResult, type WebhookDelivery, type WebhookTrigger, Fdbck as default, verifyWebhook };