@heedkit/sdk-react-native 0.1.0

package/src/client.test.ts

@@ -0,0 +1,330 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { HeedKitClient, type InitResult } from "./client";
+
+// ---------------------------------------------------------------------------
+// fetch mocking helpers
+// ---------------------------------------------------------------------------
+
+type FetchCall = { url: string; init?: RequestInit };
+
+function mockFetch(handler: (call: FetchCall) => Response | Promise<Response>) {
+  const calls: FetchCall[] = [];
+  const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+    const call = { url, init };
+    calls.push(call);
+    return handler(call);
+  });
+  // @ts-expect-error — overriding global fetch for the test
+  globalThis.fetch = fetchMock;
+  return { calls, fetchMock };
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// The Rails /sdk/init response nests project config under `project`.
+const FULL_INIT_RESPONSE: InitResult = {
+  end_user_id: "eu-alice",
+  project: {
+    name: "Test",
+    theme: { primary: "#000000" },
+    enabled_kinds: ["feature_request", "bug_report", "improvement", "appreciation", "other"],
+    kind_visibility: {
+      feature_request: "public",
+      bug_report: "private",
+      improvement: "private",
+      appreciation: "private",
+      other: "private",
+    },
+    kind_interactions: {
+      feature_request: { upvote: true, downvote: false },
+      bug_report: { plus_one: true },
+      improvement: { upvote: true, downvote: false },
+      appreciation: { like: true },
+      other: { like: true },
+    },
+    is_public_roadmap: false,
+  },
+};
+
+let originalFetch: typeof fetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// init() — payload parsing + state hydration
+// ---------------------------------------------------------------------------
+
+describe("HeedKitClient.init", () => {
+  it("posts identity to /sdk/init with the project key header", async () => {
+    const { calls } = mockFetch(() => jsonResponse(FULL_INIT_RESPONSE));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+
+    await client.init({ externalId: "alice", email: "alice@x.com", platform: "tests" });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("http://api/sdk/init");
+    const init = calls[0].init!;
+    expect(init.method).toBe("POST");
+    // init.headers may be a Headers instance OR a plain object depending on the runtime.
+    const headers = new Headers(init.headers as HeadersInit);
+    expect(headers.get("X-Project-Key")).toBe("fh_test");
+    expect(headers.get("Content-Type")).toBe("application/json");
+    expect(JSON.parse(init.body as string)).toEqual({
+      external_id: "alice",
+      email: "alice@x.com",
+      name: undefined,
+      avatar_url: undefined,
+      platform: "tests",
+    });
+  });
+
+  it("defaults platform to 'web' when no user is provided", async () => {
+    const { calls } = mockFetch(() => jsonResponse(FULL_INIT_RESPONSE));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await client.init();
+    const body = JSON.parse(calls[0].init!.body as string);
+    expect(body.platform).toBe("web");
+  });
+
+  it("hydrates theme / enabledKinds / kindVisibility / kindInteractions / endUserId", async () => {
+    mockFetch(() => jsonResponse(FULL_INIT_RESPONSE));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+
+    await client.init({ externalId: "alice" });
+
+    expect(client.getEndUserId()).toBe("eu-alice");
+    expect(client.getProjectName()).toBe("Test");
+    expect(client.getTheme()).toEqual({ primary: "#000000" });
+    expect(client.getEnabledKinds()).toContain("feature_request");
+    expect(client.getKindVisibility().bug_report).toBe("private");
+    expect(client.getKindInteractions().feature_request).toEqual({
+      upvote: true,
+      downvote: false,
+    });
+  });
+
+  it("tolerates an old server response missing kind_visibility / kind_interactions", async () => {
+    const partial = {
+      project_id: "p",
+      project_name: "Old",
+      theme: {},
+      enabled_kinds: ["feature_request"],
+      end_user_id: "eu",
+    };
+    mockFetch(() => jsonResponse(partial));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+
+    await client.init({ externalId: "alice" });
+    // Falls back to empty maps rather than throwing.
+    expect(client.getKindVisibility()).toEqual({});
+    expect(client.getKindInteractions()).toEqual({});
+    expect(client.getInteractionsFor("feature_request")).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getInteractionsFor — canonical order + filtering
+// ---------------------------------------------------------------------------
+
+describe("getInteractionsFor", () => {
+  it("returns enabled interactions in canonical order", async () => {
+    mockFetch(() => jsonResponse(FULL_INIT_RESPONSE));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await client.init({ externalId: "alice" });
+
+    // Even though the JSON had `upvote: true, downvote: false`, the canonical
+    // order is [upvote, downvote, plus_one, like] — only enabled ones surface.
+    expect(client.getInteractionsFor("feature_request")).toEqual(["upvote"]);
+    expect(client.getInteractionsFor("bug_report")).toEqual(["plus_one"]);
+    expect(client.getInteractionsFor("appreciation")).toEqual(["like"]);
+  });
+
+  it("returns up+down together when both enabled", async () => {
+    mockFetch(() => jsonResponse({
+      ...FULL_INIT_RESPONSE,
+      project: {
+        ...FULL_INIT_RESPONSE.project,
+        kind_interactions: {
+          ...FULL_INIT_RESPONSE.project.kind_interactions,
+          feature_request: { upvote: true, downvote: true },
+        },
+      },
+    }));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await client.init({ externalId: "alice" });
+    expect(client.getInteractionsFor("feature_request")).toEqual(["upvote", "downvote"]);
+  });
+
+  it("returns empty array for a kind that has no interactions enabled", async () => {
+    mockFetch(() => jsonResponse({
+      ...FULL_INIT_RESPONSE,
+      project: {
+        ...FULL_INIT_RESPONSE.project,
+        kind_interactions: { ...FULL_INIT_RESPONSE.project.kind_interactions, appreciation: { like: false } },
+      },
+    }));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await client.init({ externalId: "alice" });
+    expect(client.getInteractionsFor("appreciation")).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// list / submit / vote — URL + payload shape
+// ---------------------------------------------------------------------------
+
+describe("list / submit / vote", () => {
+  async function newReady(handler: (call: FetchCall) => Response | Promise<Response>) {
+    const records = mockFetch(handler);
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await client.init({ externalId: "alice" });
+    records.calls.length = 0;
+    return { client, calls: records.calls };
+  }
+
+  it("list sends end_user_id and any provided filters", async () => {
+    const { client, calls } = await newReady((call) => {
+      if (call.url.includes("/sdk/features")) return jsonResponse({ features: [], next_cursor: null });
+      return jsonResponse(FULL_INIT_RESPONSE);
+    });
+
+    await client.list({ status: "planned", kind: "bug_report", sort: "new" });
+    expect(calls).toHaveLength(1);
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe("/sdk/features");
+    expect(url.searchParams.get("end_user_id")).toBe("eu-alice");
+    expect(url.searchParams.get("status")).toBe("planned");
+    expect(url.searchParams.get("kind")).toBe("bug_report");
+    expect(url.searchParams.get("sort")).toBe("new");
+  });
+
+  it("list unwraps { features } and maps `author` -> author_name", async () => {
+    const { client } = await newReady((call) => {
+      if (call.url.includes("/sdk/features"))
+        return jsonResponse({
+          features: [ { id: 7, title: "Dark mode", status: "planned", kind: "feature_request", visibility: "public", vote_count: 3, author: "Dana", created_at: "2026-01-01T00:00:00Z" } ],
+          next_cursor: null,
+        });
+      return jsonResponse(FULL_INIT_RESPONSE);
+    });
+    const features = await client.list();
+    expect(features).toHaveLength(1);
+    expect(features[0].id).toBe("7");
+    expect(features[0].author_name).toBe("Dana");
+    expect(features[0].voted).toBe(false);
+    expect(features[0].on_roadmap).toBe(false);
+  });
+
+  it("listComments unwraps { comments } and maps `author` -> author_name", async () => {
+    const { client } = await newReady((call) => {
+      if (call.url.includes("/comments"))
+        return jsonResponse({ comments: [ { id: 1, body: "yes please", author: "Sam", created_at: "2026-01-01T00:00:00Z" } ] });
+      return jsonResponse(FULL_INIT_RESPONSE);
+    });
+    const comments = await client.listComments("7");
+    expect(comments).toHaveLength(1);
+    expect(comments[0].author_name).toBe("Sam");
+    expect(comments[0].is_internal).toBe(false);
+  });
+
+  it("submit posts the correct body and defaults kind to feature_request", async () => {
+    const { client, calls } = await newReady((call) => {
+      if (call.url.endsWith("/sdk/features"))
+        return jsonResponse({
+          id: "f1",
+          title: "x",
+          description: "",
+          status: "open",
+          kind: "feature_request",
+          visibility: "public",
+          on_roadmap: false,
+          tag: null,
+          vote_count: 0,
+          voted: false,
+          platform: null,
+          author_name: null,
+          created_at: "2026-01-01T00:00:00Z",
+        });
+      return jsonResponse(FULL_INIT_RESPONSE);
+    });
+
+    await client.submit({ title: "Dark mode" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].init!.method).toBe("POST");
+    const body = JSON.parse(calls[0].init!.body as string);
+    expect(body).toEqual({
+      end_user_id: "eu-alice",
+      title: "Dark mode",
+      description: "",
+      tag: null,
+      kind: "feature_request",
+    });
+  });
+
+  it("vote posts to /sdk/features/{id}/vote", async () => {
+    const { client, calls } = await newReady((call) => {
+      if (call.url.endsWith("/vote"))
+        return jsonResponse({ voted: true, vote_count: 1 });
+      return jsonResponse(FULL_INIT_RESPONSE);
+    });
+    const out = await client.vote("feat-42");
+    expect(out).toEqual({ voted: true, vote_count: 1 });
+    expect(calls[0].url).toBe("http://api/sdk/features/feat-42/vote");
+  });
+
+  it("throws Error before init when calling list/submit/vote", async () => {
+    mockFetch(() => jsonResponse(FULL_INIT_RESPONSE));
+    const client = new HeedKitClient({ projectKey: "fh_test", apiUrl: "http://api" });
+    await expect(client.list()).rejects.toThrow(/not initialized/);
+    await expect(client.submit({ title: "x" })).rejects.toThrow(/not initialized/);
+    await expect(client.vote("x")).rejects.toThrow(/not initialized/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// HTTP error handling
+// ---------------------------------------------------------------------------
+
+describe("error handling", () => {
+  it("surfaces the Rails `error` code on a 4xx", async () => {
+    mockFetch(() =>
+      new Response(JSON.stringify({ error: "invalid_project_key" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+    const client = new HeedKitClient({ projectKey: "bad", apiUrl: "http://api" });
+    await expect(client.init()).rejects.toThrow(/invalid_project_key/);
+  });
+
+  it("tolerates a legacy `detail` error field on a 4xx", async () => {
+    mockFetch(() =>
+      new Response(JSON.stringify({ detail: "Invalid project key" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+    const client = new HeedKitClient({ projectKey: "bad", apiUrl: "http://api" });
+    await expect(client.init()).rejects.toThrow(/Invalid project key/);
+  });
+
+  it("falls back to HTTP <status> when the body isn't JSON", async () => {
+    mockFetch(() =>
+      new Response("Internal Server Error", { status: 500 })
+    );
+    const client = new HeedKitClient({ projectKey: "ok", apiUrl: "http://api" });
+    await expect(client.init()).rejects.toThrow(/HTTP 500/);
+  });
+});

package/src/client.ts

@@ -0,0 +1,301 @@
+export type Visibility = "public" | "private";
+
+export type Interaction = "upvote" | "downvote" | "plus_one" | "like";
+
+export type KindInteractions = Partial<Record<Interaction, boolean>>;
+
+export type ShowCounts = Partial<Record<FeatureKind, boolean>>;
+
+export type GroupMode = "tabs" | "list";
+
+export type Theme = {
+  primary?: string;
+  primaryDark?: string;
+  radius?: number;
+  /// `"system"` follows the OS color scheme at render time.
+  mode?: "light" | "dark" | "system";
+  font_family?: string;
+  font_size?: "sm" | "md" | "lg";
+  group_mode?: GroupMode;
+  show_counts?: ShowCounts;
+  // Older deployments may still send camelCase keys for these — kept for backcompat.
+  fontFamily?: string;
+};
+
+export type EndUser = {
+  externalId?: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  platform?: string;
+};
+
+export type FeatureKind =
+  | "feature_request"
+  | "bug_report"
+  | "improvement"
+  | "appreciation"
+  | "other";
+
+export type Feature = {
+  id: string;
+  title: string;
+  description: string;
+  status: "open" | "planned" | "in_progress" | "shipped" | "declined";
+  kind: FeatureKind;
+  /// Whether the item is visible beyond its author + the project team.
+  visibility: Visibility;
+  /// Whether the item appears on the project's roadmap (public if visibility=public).
+  on_roadmap: boolean;
+  tag: string | null;
+  vote_count: number;
+  voted: boolean;
+  platform: string | null;
+  author_name: string | null;
+  created_at: string;
+};
+
+export type Comment = {
+  id: string;
+  body: string;
+  author_name: string | null;
+  is_internal: boolean;
+  created_at: string;
+};
+
+export type HeedKitConfig = {
+  projectKey: string;
+  apiUrl?: string;
+  user?: EndUser;
+};
+
+/// Project configuration returned by /sdk/init (nested under `project`).
+export type ProjectConfig = {
+  name: string;
+  theme: Theme;
+  enabled_kinds: FeatureKind[];
+  /// Default visibility applied to new submissions of each kind.
+  kind_visibility: Record<FeatureKind, Visibility>;
+  /// Which interactions admin has enabled per kind. The widget should only render
+  /// the affordances listed here.
+  kind_interactions: Record<FeatureKind, KindInteractions>;
+  is_public_roadmap?: boolean;
+};
+
+export type InitResult = {
+  end_user_id: string;
+  project: ProjectConfig;
+};
+
+const DEFAULT_API = "https://api.heedkit.com";
+
+/**
+ * Optional storage shim for the device id. React Native doesn't ship with a
+ * synchronous KV store; pass `@react-native-async-storage/async-storage` (or
+ * any equivalent) once at app startup and the client will use it to persist
+ * the per-device id across launches.
+ *
+ *   import AsyncStorage from "@react-native-async-storage/async-storage";
+ *   import { setDeviceStorage } from "@heedkit/sdk-react-native";
+ *   setDeviceStorage(AsyncStorage);
+ *
+ * If you don't, an in-memory id is used — fine for a session but resets on
+ * cold launch.
+ */
+export interface DeviceStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+const DEVICE_ID_KEY = "heedkit.device_id";
+let _storage: DeviceStorage | null = null;
+let _memoryDeviceId: string | null = null;
+
+export function setDeviceStorage(s: DeviceStorage): void {
+  _storage = s;
+}
+
+async function getOrCreateDeviceId(): Promise<string> {
+  if (_storage) {
+    try {
+      const existing = await _storage.getItem(DEVICE_ID_KEY);
+      if (existing) return existing;
+      const next = _newId();
+      await _storage.setItem(DEVICE_ID_KEY, next);
+      return next;
+    } catch {
+      // Storage error — fall through to memory.
+    }
+  }
+  if (!_memoryDeviceId) _memoryDeviceId = _newId();
+  return _memoryDeviceId;
+}
+
+function _newId(): string {
+  // Avoid the crypto.randomUUID polyfill dance on RN — a 16-byte hex is plenty.
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  return "dev_" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/// Map a raw API feature onto the SDK shape (the backend compacts null fields and
+/// exposes the author display name as `author`).
+function normalizeFeature(f: any): Feature {
+  return {
+    id: String(f.id),
+    title: f.title,
+    description: f.description ?? "",
+    status: f.status,
+    kind: f.kind,
+    visibility: f.visibility,
+    on_roadmap: f.on_roadmap ?? false,
+    tag: f.tag ?? null,
+    vote_count: f.vote_count ?? 0,
+    voted: f.voted ?? false,
+    platform: f.platform ?? null,
+    author_name: f.author_name ?? f.author ?? null,
+    created_at: f.created_at,
+  };
+}
+
+function normalizeComment(c: any): Comment {
+  return {
+    id: String(c.id),
+    body: c.body,
+    author_name: c.author_name ?? c.author ?? null,
+    // The SDK endpoint only ever returns public comments.
+    is_internal: c.is_internal ?? false,
+    created_at: c.created_at,
+  };
+}
+
+export class HeedKitClient {
+  private apiUrl: string;
+  private projectKey: string;
+  private endUserId: string | null = null;
+  private theme: Theme = {};
+  private projectName = "";
+  private enabledKinds: FeatureKind[] = [];
+  private kindVisibility: Partial<Record<FeatureKind, Visibility>> = {};
+  private kindInteractions: Partial<Record<FeatureKind, KindInteractions>> = {};
+
+  constructor(config: HeedKitConfig) {
+    this.apiUrl = config.apiUrl || DEFAULT_API;
+    this.projectKey = config.projectKey;
+  }
+
+  async init(user: EndUser = {}): Promise<InitResult> {
+    const externalId = user.externalId ?? (await getOrCreateDeviceId());
+    const body = {
+      external_id: externalId,
+      email: user.email,
+      name: user.name,
+      avatar_url: user.avatarUrl,
+      platform: user.platform || "web",
+    };
+    const res = await this.request<InitResult>("/sdk/init", "POST", body);
+    this.endUserId = res.end_user_id;
+    // The Rails backend nests project config under `project`; tolerate a flat
+    // response from older deployments too.
+    const p: any = (res as any).project ?? res;
+    this.theme = p.theme || {};
+    this.projectName = p.name ?? p.project_name ?? "";
+    this.enabledKinds = p.enabled_kinds || [];
+    this.kindVisibility = p.kind_visibility || {};
+    this.kindInteractions = p.kind_interactions || {};
+    return res;
+  }
+
+  getTheme() { return this.theme; }
+  getEnabledKinds(): FeatureKind[] { return this.enabledKinds; }
+  getKindVisibility() { return this.kindVisibility; }
+  getKindInteractions() { return this.kindInteractions; }
+  getProjectName() { return this.projectName; }
+  getEndUserId() { return this.endUserId; }
+
+  /// Convenience: which interactions are enabled for a given kind, in stable order.
+  getInteractionsFor(kind: FeatureKind): Interaction[] {
+    const row = this.kindInteractions[kind] || {};
+    return (["upvote", "downvote", "plus_one", "like"] as Interaction[]).filter(
+      (i) => row[i]
+    );
+  }
+
+  async list(
+    opts: { status?: string; kind?: FeatureKind; sort?: "top" | "new" } = {}
+  ): Promise<Feature[]> {
+    this.ensureInit();
+    const params = new URLSearchParams({ end_user_id: this.endUserId! });
+    if (opts.status) params.set("status", opts.status);
+    if (opts.kind) params.set("kind", opts.kind);
+    if (opts.sort) params.set("sort", opts.sort);
+    // Rails returns { features, next_cursor }; tolerate a bare array too.
+    const res = await this.request<any>(`/sdk/features?${params}`, "GET");
+    const features = Array.isArray(res) ? res : (res.features ?? []);
+    return features.map((f: any) => normalizeFeature(f));
+  }
+
+  async submit(input: {
+    title: string;
+    description?: string;
+    tag?: string;
+    kind?: FeatureKind;
+  }): Promise<Feature> {
+    this.ensureInit();
+    const res = await this.request<any>("/sdk/features", "POST", {
+      end_user_id: this.endUserId,
+      title: input.title,
+      description: input.description || "",
+      tag: input.tag || null,
+      kind: input.kind || "feature_request",
+    });
+    return normalizeFeature(res);
+  }
+
+  async vote(featureId: string): Promise<{ voted: boolean; vote_count: number }> {
+    this.ensureInit();
+    return this.request(`/sdk/features/${featureId}/vote`, "POST", {
+      end_user_id: this.endUserId,
+    });
+  }
+
+  async listComments(featureId: string): Promise<Comment[]> {
+    // Rails returns { comments: [...] }; tolerate a bare array too.
+    const res = await this.request<any>(`/sdk/features/${featureId}/comments`, "GET");
+    const comments = Array.isArray(res) ? res : (res.comments ?? []);
+    return comments.map((c: any) => normalizeComment(c));
+  }
+
+  async comment(featureId: string, body: string): Promise<Comment> {
+    this.ensureInit();
+    const res = await this.request<any>(`/sdk/features/${featureId}/comments`, "POST", {
+      end_user_id: this.endUserId,
+      body,
+    });
+    return normalizeComment(res);
+  }
+
+  private ensureInit() {
+    if (!this.endUserId) throw new Error("HeedKit not initialized — call init() first");
+  }
+
+  private async request<T>(path: string, method: string, body?: unknown): Promise<T> {
+    const res = await fetch(`${this.apiUrl}${path}`, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-Key": this.projectKey,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      let detail = `HTTP ${res.status}`;
+      try {
+        const j = await res.json();
+        detail = j.error || j.detail || detail; // Rails uses `error`; legacy used `detail`.
+      } catch { /* non-JSON body */ }
+      throw new Error(detail);
+    }
+    return res.json() as Promise<T>;
+  }
+}