reflet-sdk 0.1.5 → 0.2.0

package/README.md

@@ -113,9 +113,73 @@ function FeedbackPage() {
 }
 ```
 
-### 4. Server-Side User Signing (Recommended for Production)
+### 4. Floating Feedback Widget
 
-For production apps, sign user tokens on your server to prevent client-side spoofing.
+One component adds a floating button to your app. Opening it screenshots the
+current viewport, lets the user draw on that screenshot, and lets them point at
+an element so the report carries the React component behind it.
+
+```bash
+npx reflet-cli init
+```
+
+Or mount it yourself, once, as the last child of your app shell:
+
+```tsx
+import { RefletFeedback } from 'reflet-sdk/feedback';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <RefletFeedback publicKey={process.env.NEXT_PUBLIC_REFLET_PUBLIC_KEY} />
+      </body>
+    </html>
+  );
+}
+```
+
+The entry ships its own `"use client"` directive, so a Next.js layout can stay a
+Server Component. With Vite, read the key from
+`import.meta.env.VITE_REFLET_PUBLIC_KEY` and render the widget next to `<App />`.
+
+Every report carries the URL, page title, browser, OS, device, viewport, locale
+and timezone, plus the last 30 console errors and warnings. Pointing at an
+element adds a selector that resolves back to it, the React component stack, and
+the source file and line when the build exposes them (development and preview
+builds do; production builds strip React's debug data).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `publicKey` | `string` | — | Your `fb_pub_…` key. Optional inside `RefletProvider`. |
+| `user` | `RefletUser` | — | Who is reporting. Hides the email field. |
+| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Which corner the button sits in. |
+| `enabled` | `boolean` | `true` | Render the widget. Gate it to staff or beta users. |
+| `dismissForDays` | `number` | — | Let a reporter hide the launcher in this browser for this many days. |
+| `captureOnOpen` | `boolean` | `true` | Screenshot as soon as the panel opens. |
+| `captureConsole` | `boolean` | `true` | Record console errors and warnings. |
+| `hotkey` | `string \| null` | `null` | Shortcut toggling the panel, e.g. `"mod+shift+f"`. |
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | Colour scheme. |
+| `primaryColor` | `string` | — | Any CSS color for the button and accents. |
+| `offset` | `number` | `20` | Pixels between the button and the viewport edge. |
+| `metadata` | `Record<string, string>` | — | Extra fields merged into every report. |
+| `categories` | `("bug" \| "idea" \| "question")[]` | all three | Category chips to show. |
+| `labels` | `Partial<FeedbackWidgetLabels>` | — | Override any string for i18n. |
+| `onSubmit` | `(result: { feedbackId: string }) => void` | — | Fires after a successful send. |
+
+The panel renders in a shadow root, so your CSS cannot reach it and its CSS
+cannot reach your app. Screenshots are rendered from the DOM rather than through
+`getDisplayMedia`, so users are never asked for a screen-share permission —
+the trade-off is that cross-origin images without CORS headers, iframes and
+canvas content may come out blank.
+
+### 5. Server-Side User Signing (required for voting and commenting)
+
+`user` is a client-asserted identity: the browser can claim to be anyone, so
+the API accepts it only to attribute a report or a survey answer. Voting,
+commenting and subscribing require a token signed on your server with
+`signUser` — anything else is rejected with a 401.
 
 **On your server** (works with any backend: Express, Fastify, Hono, serverless functions, etc.):
 
@@ -277,11 +341,11 @@ const reflet = new Reflet(config: RefletConfig);
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `publicKey` | `string` | Yes | Your organization's public API key (`fb_pub_...`) |
-| `user` | `RefletUser` | No | User information for client-side identification |
-| `userToken` | `string` | No | Signed JWT from your server (use instead of `user` for production) |
+| `user` | `RefletUser` | No | Client-asserted identity — attributes reports only, never grants voting or commenting |
+| `userToken` | `string` | No | Signed JWT from your server (`signUser`), required for voting, commenting and subscribing |
 | `baseUrl` | `string` | No | Custom API endpoint (defaults to Reflet production API) |
 
-> **Note:** Provide either `user` OR `userToken`, not both. If neither is provided, the user can only read feedback (no voting, commenting, or creating).
+> **Note:** Provide either `user` OR `userToken`, not both. With neither, the user can only read feedback and submit anonymous reports. With `user` alone, reports are attributed but voting, commenting and subscribing stay unavailable.
 
 #### Methods
 
@@ -403,7 +467,7 @@ try {
 
 | Error | Cause | Solution |
 |-------|-------|----------|
-| `RefletAuthError` | No user/token provided | Pass `user` or `userToken` to the client |
+| `RefletAuthError` | No signed token provided | Pass a `userToken` from `signUser`; `user` alone cannot vote or comment |
 | `RefletAuthError` | Invalid or expired token | Generate a new token on your server |
 | `RefletNotFoundError` | Invalid feedback ID | Check the ID exists |
 | `RefletError` (403) | Organization is private | Use a secret key or make organization public |
@@ -522,7 +586,7 @@ function App() {
 
 **Cause:** Trying to vote, comment, or create feedback without user identification.
 
-**Solution:** Provide `user` or `userToken` when initializing the client:
+**Solution:** Provide a server-signed `userToken` when initializing the client:
 
 ```typescript
 const reflet = new Reflet({

package/dist/client-BYuSKJw5.js

@@ -0,0 +1,270 @@
+//#region src/types.ts
+var RefletError = class extends Error {
+	status;
+	code;
+	constructor(message, status, code) {
+		super(message);
+		this.name = "RefletError";
+		this.status = status;
+		this.code = code;
+	}
+};
+var RefletAuthError = class extends RefletError {
+	constructor(message) {
+		super(message, 401, "AUTH_ERROR");
+		this.name = "RefletAuthError";
+	}
+};
+var RefletValidationError = class extends RefletError {
+	constructor(message) {
+		super(message, 400, "VALIDATION_ERROR");
+		this.name = "RefletValidationError";
+	}
+};
+var RefletNotFoundError = class extends RefletError {
+	constructor(message) {
+		super(message, 404, "NOT_FOUND");
+		this.name = "RefletNotFoundError";
+	}
+};
+//#endregion
+//#region src/client.ts
+const DEFAULT_API_URL = "https://harmless-clam-802.convex.site";
+/** btoa is Latin1-only — a name like "José" would throw. */
+function base64Utf8(value) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(value)) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+/**
+* Reflet SDK Client
+*
+* @example
+* ```ts
+* import { Reflet } from 'reflet-sdk';
+*
+* const reflet = new Reflet({
+*   publicKey: 'fb_pub_xxx',
+*   user: { id: 'user_123', email: 'user@example.com', name: 'John' }
+* });
+*
+* // List feedback
+* const { items } = await reflet.list({ status: 'open' });
+*
+* // Vote on feedback
+* await reflet.vote('feedback_id');
+*
+* // Submit new feedback
+* await reflet.create({ title: 'Great idea', description: 'Details...' });
+* ```
+*/
+var Reflet = class {
+	publicKey;
+	baseUrl;
+	userToken;
+	user;
+	constructor(config) {
+		this.publicKey = config.publicKey;
+		this.baseUrl = config.baseUrl ?? DEFAULT_API_URL;
+		this.userToken = config.userToken;
+		this.user = config.user;
+		if (!this.publicKey) throw new Error("Reflet: publicKey is required");
+	}
+	/**
+	* Update the user identification
+	*/
+	setUser(user) {
+		this.user = user;
+		this.userToken = void 0;
+	}
+	/**
+	* Set the user token directly (for server-signed tokens)
+	*/
+	setUserToken(token) {
+		this.userToken = token;
+		this.user = void 0;
+	}
+	/**
+	* Get the organization configuration
+	*/
+	async getConfig() {
+		return await this.request("GET", "/api/v1/feedback");
+	}
+	/**
+	* List feedback items with optional filtering
+	*/
+	async list(params) {
+		const searchParams = new URLSearchParams();
+		if (params?.statusId) searchParams.set("statusId", params.statusId);
+		if (params?.status) searchParams.set("status", params.status);
+		if (params?.search) searchParams.set("search", params.search);
+		if (params?.sortBy) searchParams.set("sortBy", params.sortBy);
+		if (params?.limit) searchParams.set("limit", String(params.limit));
+		if (params?.offset) searchParams.set("offset", String(params.offset));
+		const query = searchParams.toString();
+		const url = `/api/v1/feedback/list${query ? `?${query}` : ""}`;
+		return await this.request("GET", url);
+	}
+	/**
+	* Get a single feedback item by ID
+	*/
+	async get(feedbackId) {
+		const result = await this.request("GET", `/api/v1/feedback/item?id=${encodeURIComponent(feedbackId)}`);
+		if (!result) throw new RefletNotFoundError("Feedback not found");
+		return result;
+	}
+	/**
+	* Create new feedback
+	* Works anonymously or with user identification
+	*/
+	async create(params) {
+		return await this.request("POST", "/api/v1/feedback/create", params);
+	}
+	/**
+	* Ask the API for a one-shot storage URL to upload a screenshot to.
+	*/
+	async getScreenshotUploadUrl() {
+		return await this.request("POST", "/api/v1/feedback/screenshot/upload-url");
+	}
+	/**
+	* Attach an already uploaded screenshot to a feedback item.
+	*/
+	async saveScreenshot(params) {
+		return await this.request("POST", "/api/v1/feedback/screenshot/save", params);
+	}
+	/**
+	* Toggle vote on feedback
+	* Requires user identification
+	*/
+	async vote(feedbackId, type = "upvote") {
+		return await this.request("POST", "/api/v1/feedback/vote", {
+			feedbackId,
+			voteType: type
+		});
+	}
+	/**
+	* Get comments for a feedback item
+	*/
+	async getComments(feedbackId, sortBy = "oldest") {
+		return await this.request("GET", `/api/v1/feedback/comments?feedbackId=${encodeURIComponent(feedbackId)}&sortBy=${sortBy}`);
+	}
+	/**
+	* Add a comment to feedback
+	* Requires user identification
+	*/
+	async comment(params) {
+		return await this.request("POST", "/api/v1/feedback/comment", params);
+	}
+	/**
+	* Subscribe to feedback updates
+	* Requires user identification
+	*/
+	async subscribe(feedbackId) {
+		return await this.request("POST", "/api/v1/feedback/subscribe", { feedbackId });
+	}
+	/**
+	* Unsubscribe from feedback updates
+	* Requires user identification
+	*/
+	async unsubscribe(feedbackId) {
+		return await this.request("POST", "/api/v1/feedback/unsubscribe", { feedbackId });
+	}
+	/**
+	* Get roadmap data
+	*/
+	async getRoadmap() {
+		return await this.request("GET", "/api/v1/feedback/roadmap");
+	}
+	/**
+	* Get changelog entries
+	*/
+	async getChangelog(limit) {
+		const url = limit ? `/api/v1/feedback/changelog?limit=${limit}` : "/api/v1/feedback/changelog";
+		return await this.request("GET", url);
+	}
+	/**
+	* Build request headers with authentication
+	*/
+	buildHeaders() {
+		const headers = {
+			Authorization: `Bearer ${this.publicKey}`,
+			"Content-Type": "application/json"
+		};
+		const token = this.userToken ?? this.generateUserToken();
+		if (token) headers["X-User-Token"] = token;
+		return headers;
+	}
+	/**
+	* Parse JSON response text safely.
+	* Returns `unknown` — callers must narrow before use.
+	*/
+	parseJsonSafely(text, status) {
+		try {
+			return JSON.parse(text);
+		} catch (parseError) {
+			throw new RefletError(`Invalid response: ${parseError instanceof Error ? parseError.message : "Failed to parse JSON"}`, status);
+		}
+	}
+	/**
+	* Type guard for API error responses
+	*/
+	isErrorResponse(data) {
+		return typeof data === "object" && data !== null && "error" in data && typeof data.error === "string";
+	}
+	/**
+	* Throw appropriate error based on status code
+	*/
+	throwHttpError(message, status) {
+		if (status === 401) throw new RefletAuthError(message);
+		if (status === 404) throw new RefletNotFoundError(message);
+		throw new RefletError(message, status);
+	}
+	/**
+	* Make an authenticated API request
+	*/
+	async request(method, path, body) {
+		let response;
+		try {
+			response = await fetch(`${this.baseUrl}${path}`, {
+				body: body ? JSON.stringify(body) : void 0,
+				headers: this.buildHeaders(),
+				method
+			});
+		} catch (networkError) {
+			throw new RefletError(`Network error: ${networkError instanceof Error ? networkError.message : "Failed to connect"}`, 0);
+		}
+		const text = await response.text();
+		if (!text) {
+			if (!response.ok) this.throwHttpError(`Request failed with status ${response.status}`, response.status);
+			return {};
+		}
+		const data = this.parseJsonSafely(text, response.status);
+		if (!response.ok) {
+			const errorMessage = this.isErrorResponse(data) ? data.error : `Request failed with status ${response.status}`;
+			this.throwHttpError(errorMessage, response.status);
+		}
+		return data;
+	}
+	/**
+	* Unsigned identity from the `user` option. The API attributes reports with
+	* it but refuses voting, commenting and subscribing — those need `signUser`.
+	*/
+	generateUserToken() {
+		if (!this.user) return;
+		const payload = {
+			email: this.user.email,
+			exp: Math.floor(Date.now() / 1e3) + 86400,
+			iat: Math.floor(Date.now() / 1e3),
+			id: this.user.id,
+			name: this.user.name
+		};
+		return `${base64Utf8(JSON.stringify({
+			alg: "none",
+			typ: "JWT"
+		}))}.${base64Utf8(JSON.stringify(payload))}.`;
+	}
+};
+//#endregion
+export { RefletValidationError as a, RefletNotFoundError as i, RefletAuthError as n, RefletError as r, Reflet as t };
+
+//# sourceMappingURL=client-BYuSKJw5.js.map

package/dist/client-BYuSKJw5.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-BYuSKJw5.js","names":[],"sources":["../src/types.ts","../src/client.ts"],"sourcesContent":["/**\n * Reflet SDK Types\n */\n\n// ============================================\n// Configuration\n// ============================================\n\nexport interface RefletConfig {\n  /** API base URL (optional, defaults to Reflet production API) */\n  baseUrl?: string;\n  /** Your organization's public API key (fb_pub_xxx) */\n  publicKey: string;\n  /** User identification for SSO */\n  user?: RefletUser;\n  /** Pre-signed user token (alternative to user object) */\n  userToken?: string;\n}\n\nexport interface RefletUser {\n  /** URL to user's avatar image */\n  avatar?: string;\n  /** User's email address */\n  email?: string;\n  /** Unique identifier for the user in your system */\n  id: string;\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n  /** User's display name */\n  name?: string;\n}\n\n// ============================================\n// API Responses\n// ============================================\n\nexport interface OrganizationConfig {\n  description?: string;\n  id: string;\n  isPublic: boolean;\n  logo?: string;\n  name: string;\n  primaryColor?: string;\n  settings?: OrganizationSettings;\n  slug: string;\n  statuses: OrganizationStatus[];\n}\n\nexport interface OrganizationSettings {\n  allowAnonymousVoting?: boolean;\n  defaultStatus?: FeedbackStatus;\n  requireApproval?: boolean;\n}\n\nexport interface OrganizationStatus {\n  color: string;\n  icon?: string;\n  id: string;\n  name: string;\n  order: number;\n}\n\nexport type FeedbackStatus =\n  | \"open\"\n  | \"under_review\"\n  | \"planned\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"closed\";\n\n// ============================================\n// Feedback\n// ============================================\n\nexport interface FeedbackItem {\n  author: FeedbackAuthor | null;\n  commentCount: number;\n  completedAt?: number;\n  createdAt: number;\n  description: string;\n  hasVoted: boolean;\n  id: string;\n  isPinned: boolean;\n  organizationStatus: {\n    id: string;\n    name: string;\n    color: string;\n  } | null;\n  status: FeedbackStatus;\n  tags: FeedbackTag[];\n  title: string;\n  updatedAt: number;\n  voteCount: number;\n}\n\nexport interface FeedbackDetail extends FeedbackItem {\n  isSubscribed: boolean;\n}\n\nexport interface FeedbackTag {\n  color: string;\n  id: string;\n  name: string;\n}\n\nexport interface FeedbackAuthor {\n  avatar?: string;\n  email?: string;\n  isExternal: boolean;\n  name?: string;\n}\n\nexport interface FeedbackListResponse {\n  hasMore: boolean;\n  items: FeedbackItem[];\n  total: number;\n}\n\nexport interface FeedbackListParams {\n  /** Number of items to return (max 100) */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Search in title and description */\n  search?: string;\n  /** Sort order */\n  sortBy?: \"votes\" | \"newest\" | \"oldest\" | \"comments\";\n  /** Filter by status name */\n  status?: FeedbackStatus;\n  /** Filter by custom status ID */\n  statusId?: string;\n}\n\nexport interface ElementRect {\n  height: number;\n  width: number;\n  x: number;\n  y: number;\n}\n\nexport interface ElementSelection {\n  /** React component names owning the element, innermost first. */\n  componentStack: string[];\n  /** Truncated outerHTML of the selected element. */\n  html: string;\n  /** Short human-readable description, e.g. `button \"Sign in\"`. */\n  label: string;\n  rect: ElementRect;\n  selector: string;\n  /** `src/components/login-form.tsx:46:19` when the React build exposes it. */\n  sourceLocation?: string;\n}\n\nexport interface ConsoleEvent {\n  level: \"error\" | \"warn\";\n  message: string;\n  timestamp: number;\n}\n\nexport interface PageContext {\n  browser?: string;\n  device?: string;\n  language?: string;\n  os?: string;\n  pageTitle?: string;\n  referrer?: string;\n  screen?: { height: number; width: number };\n  timezone?: string;\n  url?: string;\n  userAgent?: string;\n  viewport?: { devicePixelRatio: number; height: number; width: number };\n}\n\n/** Everything the widget knows about where and how the feedback was written. */\nexport interface FeedbackContext extends PageContext {\n  consoleEvents?: ConsoleEvent[];\n  metadata?: Record<string, string>;\n  sdkVersion?: string;\n  selection?: ElementSelection;\n}\n\nexport interface CreateFeedbackParams {\n  context?: FeedbackContext;\n  description: string;\n  title: string;\n}\n\nexport interface ScreenshotAnnotation {\n  color?: string;\n  endX?: number;\n  endY?: number;\n  height?: number;\n  points?: Array<{ x: number; y: number }>;\n  text?: string;\n  type: \"arrow\" | \"blur\" | \"highlight\" | \"pen\" | \"rectangle\" | \"text\";\n  width?: number;\n  x: number;\n  y: number;\n}\n\nexport interface SaveScreenshotParams {\n  annotatedStorageId?: string;\n  annotations?: ScreenshotAnnotation[];\n  feedbackId: string;\n  filename?: string;\n  height?: number;\n  mimeType?: string;\n  pageUrl?: string;\n  size?: number;\n  storageId: string;\n  width?: number;\n}\n\nexport interface CreateFeedbackResponse {\n  feedbackId: string;\n  isApproved: boolean;\n}\n\nexport interface VoteResponse {\n  voteCount: number;\n  voted: boolean;\n}\n\n// ============================================\n// Comments\n// ============================================\n\nexport interface Comment {\n  author: FeedbackAuthor | null;\n  body: string;\n  createdAt: number;\n  id: string;\n  isOfficial: boolean;\n  replies: CommentReply[];\n  updatedAt: number;\n}\n\nexport interface CommentReply {\n  author: FeedbackAuthor | null;\n  body: string;\n  createdAt: number;\n  id: string;\n  isOfficial: boolean;\n  updatedAt: number;\n}\n\nexport interface AddCommentParams {\n  body: string;\n  feedbackId: string;\n  parentId?: string;\n}\n\nexport interface AddCommentResponse {\n  commentId: string;\n}\n\n// ============================================\n// Subscriptions\n// ============================================\n\nexport interface SubscribeResponse {\n  alreadySubscribed?: boolean;\n  subscribed: boolean;\n}\n\nexport interface UnsubscribeResponse {\n  unsubscribed: boolean;\n  wasNotSubscribed?: boolean;\n}\n\n// ============================================\n// Roadmap\n// ============================================\n\nexport interface Roadmap {\n  lanes: RoadmapLane[];\n}\n\nexport interface RoadmapLane {\n  color: string;\n  id: string;\n  items: RoadmapItem[];\n  name: string;\n}\n\nexport interface RoadmapItem {\n  id: string;\n  status: FeedbackStatus;\n  title: string;\n  voteCount: number;\n}\n\n// ============================================\n// Changelog\n// ============================================\n\nexport interface ChangelogEntry {\n  description?: string;\n  feedback: { id: string; title: string }[];\n  id: string;\n  publishedAt?: number;\n  title: string;\n  version?: string;\n}\n\n// ============================================\n// Errors\n// ============================================\n\nexport class RefletError extends Error {\n  readonly status: number;\n  readonly code?: string;\n\n  constructor(message: string, status: number, code?: string) {\n    super(message);\n    this.name = \"RefletError\";\n    this.status = status;\n    this.code = code;\n  }\n}\n\nexport class RefletAuthError extends RefletError {\n  constructor(message: string) {\n    super(message, 401, \"AUTH_ERROR\");\n    this.name = \"RefletAuthError\";\n  }\n}\n\nexport class RefletValidationError extends RefletError {\n  constructor(message: string) {\n    super(message, 400, \"VALIDATION_ERROR\");\n    this.name = \"RefletValidationError\";\n  }\n}\n\nexport class RefletNotFoundError extends RefletError {\n  constructor(message: string) {\n    super(message, 404, \"NOT_FOUND\");\n    this.name = \"RefletNotFoundError\";\n  }\n}\n","import {\n  type AddCommentParams,\n  type AddCommentResponse,\n  type ChangelogEntry,\n  type Comment,\n  type CreateFeedbackParams,\n  type CreateFeedbackResponse,\n  type FeedbackDetail,\n  type FeedbackListParams,\n  type FeedbackListResponse,\n  type OrganizationConfig,\n  RefletAuthError,\n  type RefletConfig,\n  RefletError,\n  RefletNotFoundError,\n  type RefletUser,\n  type Roadmap,\n  type SaveScreenshotParams,\n  type SubscribeResponse,\n  type UnsubscribeResponse,\n  type VoteResponse,\n} from \"./types\";\n\n// Default to Reflet production API (HTTP routes use .convex.site)\nconst DEFAULT_API_URL = \"https://harmless-clam-802.convex.site\";\n\n/** btoa is Latin1-only — a name like \"José\" would throw. */\nfunction base64Utf8(value: string): string {\n  let binary = \"\";\n  for (const byte of new TextEncoder().encode(value)) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary);\n}\n\n/**\n * Reflet SDK Client\n *\n * @example\n * ```ts\n * import { Reflet } from 'reflet-sdk';\n *\n * const reflet = new Reflet({\n *   publicKey: 'fb_pub_xxx',\n *   user: { id: 'user_123', email: 'user@example.com', name: 'John' }\n * });\n *\n * // List feedback\n * const { items } = await reflet.list({ status: 'open' });\n *\n * // Vote on feedback\n * await reflet.vote('feedback_id');\n *\n * // Submit new feedback\n * await reflet.create({ title: 'Great idea', description: 'Details...' });\n * ```\n */\nexport class Reflet {\n  private readonly publicKey: string;\n  private readonly baseUrl: string;\n  private userToken: string | undefined;\n  private user: RefletUser | undefined;\n\n  constructor(config: RefletConfig) {\n    this.publicKey = config.publicKey;\n    this.baseUrl = config.baseUrl ?? DEFAULT_API_URL;\n    this.userToken = config.userToken;\n    this.user = config.user;\n\n    if (!this.publicKey) {\n      throw new Error(\"Reflet: publicKey is required\");\n    }\n  }\n\n  /**\n   * Update the user identification\n   */\n  setUser(user: RefletUser | undefined): void {\n    this.user = user;\n    this.userToken = undefined;\n  }\n\n  /**\n   * Set the user token directly (for server-signed tokens)\n   */\n  setUserToken(token: string | undefined): void {\n    this.userToken = token;\n    this.user = undefined;\n  }\n\n  /**\n   * Get the organization configuration\n   */\n  async getConfig(): Promise<OrganizationConfig> {\n    return await this.request<OrganizationConfig>(\"GET\", \"/api/v1/feedback\");\n  }\n\n  /**\n   * List feedback items with optional filtering\n   */\n  async list(params?: FeedbackListParams): Promise<FeedbackListResponse> {\n    const searchParams = new URLSearchParams();\n\n    if (params?.statusId) {\n      searchParams.set(\"statusId\", params.statusId);\n    }\n    if (params?.status) {\n      searchParams.set(\"status\", params.status);\n    }\n    if (params?.search) {\n      searchParams.set(\"search\", params.search);\n    }\n    if (params?.sortBy) {\n      searchParams.set(\"sortBy\", params.sortBy);\n    }\n    if (params?.limit) {\n      searchParams.set(\"limit\", String(params.limit));\n    }\n    if (params?.offset) {\n      searchParams.set(\"offset\", String(params.offset));\n    }\n\n    const query = searchParams.toString();\n    const url = `/api/v1/feedback/list${query ? `?${query}` : \"\"}`;\n\n    return await this.request<FeedbackListResponse>(\"GET\", url);\n  }\n\n  /**\n   * Get a single feedback item by ID\n   */\n  async get(feedbackId: string): Promise<FeedbackDetail> {\n    const result = await this.request<FeedbackDetail | null>(\n      \"GET\",\n      `/api/v1/feedback/item?id=${encodeURIComponent(feedbackId)}`\n    );\n\n    if (!result) {\n      throw new RefletNotFoundError(\"Feedback not found\");\n    }\n\n    return result;\n  }\n\n  /**\n   * Create new feedback\n   * Works anonymously or with user identification\n   */\n  async create(params: CreateFeedbackParams): Promise<CreateFeedbackResponse> {\n    return await this.request<CreateFeedbackResponse>(\n      \"POST\",\n      \"/api/v1/feedback/create\",\n      params\n    );\n  }\n\n  /**\n   * Ask the API for a one-shot storage URL to upload a screenshot to.\n   */\n  async getScreenshotUploadUrl(): Promise<{ uploadUrl: string }> {\n    return await this.request<{ uploadUrl: string }>(\n      \"POST\",\n      \"/api/v1/feedback/screenshot/upload-url\"\n    );\n  }\n\n  /**\n   * Attach an already uploaded screenshot to a feedback item.\n   */\n  async saveScreenshot(\n    params: SaveScreenshotParams\n  ): Promise<{ screenshotId: string }> {\n    return await this.request<{ screenshotId: string }>(\n      \"POST\",\n      \"/api/v1/feedback/screenshot/save\",\n      params\n    );\n  }\n\n  /**\n   * Toggle vote on feedback\n   * Requires user identification\n   */\n  async vote(\n    feedbackId: string,\n    type: \"upvote\" | \"downvote\" = \"upvote\"\n  ): Promise<VoteResponse> {\n    return await this.request<VoteResponse>(\"POST\", \"/api/v1/feedback/vote\", {\n      feedbackId,\n      voteType: type,\n    });\n  }\n\n  /**\n   * Get comments for a feedback item\n   */\n  async getComments(\n    feedbackId: string,\n    sortBy: \"newest\" | \"oldest\" = \"oldest\"\n  ): Promise<Comment[]> {\n    return await this.request<Comment[]>(\n      \"GET\",\n      `/api/v1/feedback/comments?feedbackId=${encodeURIComponent(feedbackId)}&sortBy=${sortBy}`\n    );\n  }\n\n  /**\n   * Add a comment to feedback\n   * Requires user identification\n   */\n  async comment(params: AddCommentParams): Promise<AddCommentResponse> {\n    return await this.request<AddCommentResponse>(\n      \"POST\",\n      \"/api/v1/feedback/comment\",\n      params\n    );\n  }\n\n  /**\n   * Subscribe to feedback updates\n   * Requires user identification\n   */\n  async subscribe(feedbackId: string): Promise<SubscribeResponse> {\n    return await this.request<SubscribeResponse>(\n      \"POST\",\n      \"/api/v1/feedback/subscribe\",\n      {\n        feedbackId,\n      }\n    );\n  }\n\n  /**\n   * Unsubscribe from feedback updates\n   * Requires user identification\n   */\n  async unsubscribe(feedbackId: string): Promise<UnsubscribeResponse> {\n    return await this.request<UnsubscribeResponse>(\n      \"POST\",\n      \"/api/v1/feedback/unsubscribe\",\n      {\n        feedbackId,\n      }\n    );\n  }\n\n  /**\n   * Get roadmap data\n   */\n  async getRoadmap(): Promise<Roadmap> {\n    return await this.request<Roadmap>(\"GET\", \"/api/v1/feedback/roadmap\");\n  }\n\n  /**\n   * Get changelog entries\n   */\n  async getChangelog(limit?: number): Promise<ChangelogEntry[]> {\n    const url = limit\n      ? `/api/v1/feedback/changelog?limit=${limit}`\n      : \"/api/v1/feedback/changelog\";\n\n    return await this.request<ChangelogEntry[]>(\"GET\", url);\n  }\n\n  /**\n   * Build request headers with authentication\n   */\n  private buildHeaders(): Record<string, string> {\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${this.publicKey}`,\n      \"Content-Type\": \"application/json\",\n    };\n\n    const token = this.userToken ?? this.generateUserToken();\n    if (token) {\n      headers[\"X-User-Token\"] = token;\n    }\n\n    return headers;\n  }\n\n  /**\n   * Parse JSON response text safely.\n   * Returns `unknown` — callers must narrow before use.\n   */\n  private parseJsonSafely(text: string, status: number): unknown {\n    try {\n      return JSON.parse(text);\n    } catch (parseError) {\n      throw new RefletError(\n        `Invalid response: ${parseError instanceof Error ? parseError.message : \"Failed to parse JSON\"}`,\n        status\n      );\n    }\n  }\n\n  /**\n   * Type guard for API error responses\n   */\n  private isErrorResponse(data: unknown): data is { error: string } {\n    return (\n      typeof data === \"object\" &&\n      data !== null &&\n      \"error\" in data &&\n      typeof (data as Record<string, unknown>).error === \"string\"\n    );\n  }\n\n  /**\n   * Throw appropriate error based on status code\n   */\n  private throwHttpError(message: string, status: number): never {\n    if (status === 401) {\n      throw new RefletAuthError(message);\n    }\n    if (status === 404) {\n      throw new RefletNotFoundError(message);\n    }\n    throw new RefletError(message, status);\n  }\n\n  /**\n   * Make an authenticated API request\n   */\n  private async request<T>(\n    method: string,\n    path: string,\n    body?: unknown\n  ): Promise<T> {\n    let response: Response;\n    try {\n      response = await fetch(`${this.baseUrl}${path}`, {\n        body: body ? JSON.stringify(body) : undefined,\n        headers: this.buildHeaders(),\n        method,\n      });\n    } catch (networkError) {\n      const message =\n        networkError instanceof Error\n          ? networkError.message\n          : \"Failed to connect\";\n      throw new RefletError(`Network error: ${message}`, 0);\n    }\n\n    const text = await response.text();\n\n    // Handle empty response\n    if (!text) {\n      if (!response.ok) {\n        this.throwHttpError(\n          `Request failed with status ${response.status}`,\n          response.status\n        );\n      }\n      // Successful empty body (e.g. 204 No Content) — return empty object\n      // narrowed through unknown for type-safe assertion\n      const emptyResponse: unknown = {};\n      return emptyResponse as T;\n    }\n\n    const data = this.parseJsonSafely(text, response.status);\n\n    if (!response.ok) {\n      const errorMessage = this.isErrorResponse(data)\n        ? data.error\n        : `Request failed with status ${response.status}`;\n      this.throwHttpError(errorMessage, response.status);\n    }\n\n    // Standard unknown → T assertion for runtime-parsed JSON\n    return data as T;\n  }\n\n  /**\n   * Unsigned identity from the `user` option. The API attributes reports with\n   * it but refuses voting, commenting and subscribing — those need `signUser`.\n   */\n  private generateUserToken(): string | undefined {\n    if (!this.user) {\n      return;\n    }\n\n    const payload = {\n      email: this.user.email,\n      exp: Math.floor(Date.now() / 1000) + 86_400, // 24 hours\n      iat: Math.floor(Date.now() / 1000),\n      id: this.user.id,\n      name: this.user.name,\n    };\n\n    const header = base64Utf8(JSON.stringify({ alg: \"none\", typ: \"JWT\" }));\n    const payloadB64 = base64Utf8(JSON.stringify(payload));\n\n    // Empty signature — the server treats this identity as unverified\n    return `${header}.${payloadB64}.`;\n  }\n}\n"],"mappings":"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"}

package/dist/client-Bi-GlSii.d.ts

@@ -0,0 +1,129 @@
+import { A as SubscribeResponse, E as Roadmap, M as VoteResponse, _ as OrganizationConfig, d as FeedbackDetail, i as Comment, j as UnsubscribeResponse, k as SaveScreenshotParams, m as FeedbackListResponse, n as AddCommentResponse, o as CreateFeedbackParams, p as FeedbackListParams, r as ChangelogEntry, s as CreateFeedbackResponse, t as AddCommentParams, w as RefletUser, x as RefletConfig } from "./types-xyOadyfX.js";
+//#region src/client.d.ts
+/**
+ * Reflet SDK Client
+ *
+ * @example
+ * ```ts
+ * import { Reflet } from 'reflet-sdk';
+ *
+ * const reflet = new Reflet({
+ *   publicKey: 'fb_pub_xxx',
+ *   user: { id: 'user_123', email: 'user@example.com', name: 'John' }
+ * });
+ *
+ * // List feedback
+ * const { items } = await reflet.list({ status: 'open' });
+ *
+ * // Vote on feedback
+ * await reflet.vote('feedback_id');
+ *
+ * // Submit new feedback
+ * await reflet.create({ title: 'Great idea', description: 'Details...' });
+ * ```
+ */
+declare class Reflet {
+  private readonly publicKey;
+  private readonly baseUrl;
+  private userToken;
+  private user;
+  constructor(config: RefletConfig);
+  /**
+   * Update the user identification
+   */
+  setUser(user: RefletUser | undefined): void;
+  /**
+   * Set the user token directly (for server-signed tokens)
+   */
+  setUserToken(token: string | undefined): void;
+  /**
+   * Get the organization configuration
+   */
+  getConfig(): Promise<OrganizationConfig>;
+  /**
+   * List feedback items with optional filtering
+   */
+  list(params?: FeedbackListParams): Promise<FeedbackListResponse>;
+  /**
+   * Get a single feedback item by ID
+   */
+  get(feedbackId: string): Promise<FeedbackDetail>;
+  /**
+   * Create new feedback
+   * Works anonymously or with user identification
+   */
+  create(params: CreateFeedbackParams): Promise<CreateFeedbackResponse>;
+  /**
+   * Ask the API for a one-shot storage URL to upload a screenshot to.
+   */
+  getScreenshotUploadUrl(): Promise<{
+    uploadUrl: string;
+  }>;
+  /**
+   * Attach an already uploaded screenshot to a feedback item.
+   */
+  saveScreenshot(params: SaveScreenshotParams): Promise<{
+    screenshotId: string;
+  }>;
+  /**
+   * Toggle vote on feedback
+   * Requires user identification
+   */
+  vote(feedbackId: string, type?: "upvote" | "downvote"): Promise<VoteResponse>;
+  /**
+   * Get comments for a feedback item
+   */
+  getComments(feedbackId: string, sortBy?: "newest" | "oldest"): Promise<Comment[]>;
+  /**
+   * Add a comment to feedback
+   * Requires user identification
+   */
+  comment(params: AddCommentParams): Promise<AddCommentResponse>;
+  /**
+   * Subscribe to feedback updates
+   * Requires user identification
+   */
+  subscribe(feedbackId: string): Promise<SubscribeResponse>;
+  /**
+   * Unsubscribe from feedback updates
+   * Requires user identification
+   */
+  unsubscribe(feedbackId: string): Promise<UnsubscribeResponse>;
+  /**
+   * Get roadmap data
+   */
+  getRoadmap(): Promise<Roadmap>;
+  /**
+   * Get changelog entries
+   */
+  getChangelog(limit?: number): Promise<ChangelogEntry[]>;
+  /**
+   * Build request headers with authentication
+   */
+  private buildHeaders;
+  /**
+   * Parse JSON response text safely.
+   * Returns `unknown` — callers must narrow before use.
+   */
+  private parseJsonSafely;
+  /**
+   * Type guard for API error responses
+   */
+  private isErrorResponse;
+  /**
+   * Throw appropriate error based on status code
+   */
+  private throwHttpError;
+  /**
+   * Make an authenticated API request
+   */
+  private request;
+  /**
+   * Unsigned identity from the `user` option. The API attributes reports with
+   * it but refuses voting, commenting and subscribing — those need `signUser`.
+   */
+  private generateUserToken;
+}
+//#endregion
+export { Reflet as t };
+//# sourceMappingURL=client-Bi-GlSii.d.ts.map

package/dist/client-Bi-GlSii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-Bi-GlSii.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;cAyDa;mBACM;mBACA;UACT;UACA;EAER,YAAY,QAAQ;;;;EAcpB,QAAQ,MAAM;;;;EAQd,aAAa;;;;EAQP,aAAa,QAAQ;;;;EAOrB,KAAK,SAAS,qBAAqB,QAAQ;;;;EA+B3C,IAAI,qBAAqB,QAAQ;;;;;EAiBjC,OAAO,QAAQ,uBAAuB,QAAQ;;;;EAW9C,0BAA0B;IAAU;;;;;EAUpC,eACJ,QAAQ,uBACP;IAAU;;;;;;EAYP,KACJ,oBACA,+BACC,QAAQ;;;;EAUL,YACJ,oBACA,+BACC,QAAQ;;;;;EAWL,QAAQ,QAAQ,mBAAmB,QAAQ;;;;;EAY3C,UAAU,qBAAqB,QAAQ;;;;;EAcvC,YAAY,qBAAqB,QAAQ;;;;EAazC,cAAc,QAAQ;;;;EAOtB,aAAa,iBAAiB,QAAQ;;;;UAWpC;;;;;UAkBA;;;;UAcA;;;;UAYA;;;;UAaM;;;;;UAqDN"}