fdbck-node 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,393 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Fdbck: () => Fdbck,
+  FdbckApiError: () => FdbckApiError,
+  FdbckError: () => FdbckError,
+  FdbckNetworkError: () => FdbckNetworkError,
+  default: () => Fdbck,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FdbckError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FdbckError";
+  }
+};
+var FdbckApiError = class extends FdbckError {
+  status;
+  code;
+  details;
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "FdbckApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var FdbckNetworkError = class extends FdbckError {
+  constructor(message, options) {
+    super(message);
+    this.name = "FdbckNetworkError";
+    if (options?.cause) {
+      this.cause = options.cause;
+    }
+  }
+};
+
+// src/utils.ts
+function mapKeys(obj, fieldMap) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const mappedKey = fieldMap[key] ?? key;
+    result[mappedKey] = value;
+  }
+  return result;
+}
+var questionFieldsToApi = {
+  ratingConfig: "rating_config",
+  expiresAt: "expires_at",
+  maxResponses: "max_responses",
+  webhookUrl: "webhook_url",
+  webhookTrigger: "webhook_trigger",
+  themeColor: "theme_color",
+  themeMode: "theme_mode",
+  hideBranding: "hide_branding",
+  welcomeMessage: "welcome_message",
+  thankYouMessage: "thank_you_message"
+};
+var questionFieldsFromApi = {
+  expires_at: "expiresAt",
+  max_responses: "maxResponses",
+  webhook_url: "webhookUrl",
+  webhook_trigger: "webhookTrigger",
+  webhook_secret: "webhookSecret",
+  theme_color: "themeColor",
+  theme_mode: "themeMode",
+  hide_branding: "hideBranding",
+  welcome_message: "welcomeMessage",
+  thank_you_message: "thankYouMessage",
+  total_responses: "totalResponses",
+  created_at: "createdAt",
+  updated_at: "updatedAt"
+};
+var ratingConfigFieldsToApi = {
+  minLabel: "min_label",
+  maxLabel: "max_label"
+};
+var ratingConfigFieldsFromApi = {
+  min_label: "minLabel",
+  max_label: "maxLabel"
+};
+var responseFieldsFromApi = {
+  question_id: "questionId",
+  created_at: "createdAt"
+};
+var tokenFieldsFromApi = {
+  respond_url: "respondUrl",
+  expires_at: "expiresAt"
+};
+var webhookDeliveryFieldsFromApi = {
+  status_code: "statusCode",
+  next_retry_at: "nextRetryAt",
+  created_at: "createdAt"
+};
+var paginationFieldsFromApi = {
+  next_cursor: "nextCursor",
+  has_more: "hasMore"
+};
+var accountOrgFieldsFromApi = {
+  responses_used: "responsesUsed",
+  responses_limit: "responsesLimit",
+  period_starts_at: "periodStartsAt",
+  period_ends_at: "periodEndsAt",
+  consecutive_overage_months: "consecutiveOverageMonths",
+  has_billing: "hasBilling"
+};
+var accountUserFieldsFromApi = {
+  avatar_url: "avatarUrl"
+};
+var resultsFieldsFromApi = {
+  question_id: "questionId",
+  total_responses: "totalResponses"
+};
+function computeExpiresAt(seconds) {
+  return new Date(Date.now() + seconds * 1e3).toISOString();
+}
+
+// src/resources/questions.ts
+function mapQuestionFromApi(raw) {
+  const mapped = mapKeys(raw, questionFieldsFromApi);
+  if (mapped.ratingConfig && typeof mapped.ratingConfig === "object") {
+    mapped.ratingConfig = mapKeys(
+      mapped.ratingConfig,
+      ratingConfigFieldsFromApi
+    );
+  }
+  return mapped;
+}
+function mapResponseFromApi(raw) {
+  return mapKeys(raw, responseFieldsFromApi);
+}
+function mapWebhookDeliveryFromApi(raw) {
+  return mapKeys(raw, webhookDeliveryFieldsFromApi);
+}
+function mapPagination(raw) {
+  return mapKeys(raw, paginationFieldsFromApi);
+}
+var QuestionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a new question. */
+  async create(opts) {
+    const { expiresIn, ratingConfig, ...rest } = opts;
+    if (expiresIn !== void 0 && opts.expiresAt !== void 0) {
+      throw new Error("Provide either expiresIn or expiresAt, not both");
+    }
+    if (expiresIn === void 0 && opts.expiresAt === void 0) {
+      throw new Error("Either expiresIn or expiresAt is required");
+    }
+    const body = { ...rest };
+    if (expiresIn !== void 0) {
+      body.expiresAt = computeExpiresAt(expiresIn);
+    }
+    if (ratingConfig) {
+      body.ratingConfig = mapKeys(
+        ratingConfig,
+        ratingConfigFieldsToApi
+      );
+    }
+    const apiBody = mapKeys(body, questionFieldsToApi);
+    const raw = await this.client.request("POST", "/v1/questions", {
+      body: apiBody
+    });
+    return mapQuestionFromApi(raw);
+  }
+  /** Get a question by ID. */
+  async get(id) {
+    const raw = await this.client.request("GET", `/v1/questions/${id}`);
+    return mapQuestionFromApi(raw);
+  }
+  /** List questions with pagination. */
+  async list(opts) {
+    const query = {};
+    if (opts?.cursor) query.cursor = opts.cursor;
+    if (opts?.limit) query.limit = String(opts.limit);
+    if (opts?.status) query.status = opts.status;
+    if (opts?.sort) query.sort = opts.sort;
+    if (opts?.order) query.order = opts.order;
+    if (opts?.createdAfter) query.created_after = opts.createdAfter;
+    if (opts?.createdBefore) query.created_before = opts.createdBefore;
+    const raw = await this.client.request("GET", "/v1/questions", {
+      query
+    });
+    const data = raw.data.map(mapQuestionFromApi);
+    const pagination = mapPagination(raw.pagination);
+    return { data, pagination };
+  }
+  /** Auto-paginate through all questions. */
+  async *listAll(opts) {
+    let cursor;
+    do {
+      const page = await this.list({ ...opts, cursor });
+      for (const question of page.data) {
+        yield question;
+      }
+      cursor = page.pagination.nextCursor ?? void 0;
+    } while (cursor);
+  }
+  /** Get responses for a question with aggregated results. */
+  async results(id, opts) {
+    const query = {};
+    if (opts?.cursor) query.cursor = opts.cursor;
+    if (opts?.limit) query.limit = String(opts.limit);
+    const raw = await this.client.request(
+      "GET",
+      `/v1/questions/${id}/responses`,
+      { query }
+    );
+    const envelope = mapKeys(raw, resultsFieldsFromApi);
+    const data = raw.data.map(mapResponseFromApi);
+    const pagination = mapPagination(raw.pagination);
+    return {
+      questionId: envelope.questionId,
+      type: envelope.type,
+      status: envelope.status,
+      totalResponses: envelope.totalResponses,
+      results: envelope.results,
+      data,
+      pagination
+    };
+  }
+  /** Cancel (delete) a question. */
+  async cancel(id) {
+    const raw = await this.client.request("DELETE", `/v1/questions/${id}`);
+    return mapQuestionFromApi(raw);
+  }
+  /** Get webhook delivery logs for a question. */
+  async webhooks(id, opts) {
+    const query = {};
+    if (opts?.cursor) query.cursor = opts.cursor;
+    if (opts?.limit) query.limit = String(opts.limit);
+    const raw = await this.client.request(
+      "GET",
+      `/v1/questions/${id}/webhooks`,
+      { query }
+    );
+    const data = raw.data.map(mapWebhookDeliveryFromApi);
+    const pagination = mapPagination(raw.pagination);
+    return { data, pagination };
+  }
+};
+
+// src/resources/tokens.ts
+var TokensResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a respondent token for a question. */
+  async create(questionId, opts) {
+    const raw = await this.client.request(
+      "POST",
+      `/v1/questions/${questionId}/token`,
+      { body: opts ?? {} }
+    );
+    return mapKeys(raw, tokenFieldsFromApi);
+  }
+};
+
+// src/webhook.ts
+var import_node_crypto = require("crypto");
+function verifyWebhook(rawBody, signature, secret) {
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(rawBody).digest("hex");
+  if (expected.length !== signature.length) {
+    return false;
+  }
+  return (0, import_node_crypto.timingSafeEqual)(
+    Buffer.from(expected, "hex"),
+    Buffer.from(signature, "hex")
+  );
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.fdbck.sh";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "0.1.0";
+var Fdbck = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  questions;
+  tokens;
+  constructor(apiKey, options) {
+    if (!apiKey.startsWith("sk_fdbck_")) {
+      throw new Error('Invalid API key: must start with "sk_fdbck_"');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    this.questions = new QuestionsResource(this);
+    this.tokens = new TokensResource(this);
+  }
+  /** Make an authenticated request to the fdbck API. */
+  async request(method, path, options) {
+    const url = new URL(path, this.baseUrl);
+    if (options?.query) {
+      for (const [key, value] of Object.entries(options.query)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": `@fdbck/node/${SDK_VERSION}`
+    };
+    const fetchOptions = {
+      method,
+      headers
+    };
+    if (options?.body) {
+      headers["Content-Type"] = "application/json";
+      fetchOptions.body = JSON.stringify(options.body);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    fetchOptions.signal = controller.signal;
+    let response;
+    try {
+      response = await fetch(url.toString(), fetchOptions);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw new FdbckNetworkError(
+        error instanceof Error ? error.message : "Network request failed",
+        { cause: error }
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new FdbckApiError(response.status, "parse_error", "Failed to parse response body");
+    }
+    if (!response.ok) {
+      const err = data?.error;
+      throw new FdbckApiError(
+        response.status,
+        err?.code ?? "unknown_error",
+        err?.message ?? `Request failed with status ${response.status}`,
+        err?.details
+      );
+    }
+    return data;
+  }
+  /** Get current account info. */
+  async me() {
+    const raw = await this.request("GET", "/v1/me");
+    const rawUser = raw.user;
+    const rawOrg = raw.organization;
+    return {
+      user: rawUser ? mapKeys(rawUser, accountUserFieldsFromApi) : null,
+      organization: rawOrg ? mapKeys(rawOrg, accountOrgFieldsFromApi) : null
+    };
+  }
+  /** Verify a webhook signature. */
+  verifyWebhook(rawBody, signature, secret) {
+    return verifyWebhook(rawBody, signature, secret);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Fdbck,
+  FdbckApiError,
+  FdbckError,
+  FdbckNetworkError,
+  verifyWebhook
+});