@heedkit/sdk-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeedKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @heedkit/sdk-react
+
+React SDK for [HeedKit](https://heedkit.com). Drop-in feature requests, voting,
+and comments — themed from your console.
+
+- **Drop-in widget** — `<FeedbackButton/>` renders a floating launcher + panel.
+- **Headless** — `useHeedKit()` gives you the client; build your own UI.
+- **Themed remotely** — colors, radius, light/dark, tabs-vs-list, and per-kind
+  interactions are configured in the HeedKit console and applied at runtime.
+
+## Install
+
+```bash
+npm i @heedkit/sdk-react react react-dom
+```
+
+`react` and `react-dom` (both `>=17`) are **peer dependencies** — install them
+alongside the SDK (most React apps already have them).
+
+## Get your project key
+
+1. Sign in to the HeedKit console at <https://heedkit.com>.
+2. Open your project and copy its **project key** (looks like `fh_xxx`).
+
+The key is sent client-side as the `X-Project-Key` header on every request, so
+it's safe to embed in your front-end bundle.
+
+## Mount the widget
+
+```tsx
+import { HeedKitProvider, FeedbackButton } from "@heedkit/sdk-react";
+
+export default function App() {
+  return (
+    <HeedKitProvider
+      projectKey="fh_xxx"
+      user={{ externalId: "user-123", email: "alice@example.com", name: "Alice" }}
+    >
+      <YourApp />
+      <FeedbackButton label="Feedback" />
+    </HeedKitProvider>
+  );
+}
+```
+
+`FeedbackButton` mounts the floating launcher and panel — the same UI as the bare
+JS SDK (it delegates to it). When an admin changes theme, tabs vs list, per-kind
+interactions, or `show_counts` in the console, the widget picks it up on the next
+mount.
+
+## Imperative open / close
+
+`FeedbackButton` is **self-contained**: it runs its own `init` and does **not**
+read config from `<HeedKitProvider>`, so pass `projectKey` on every instance.
+Forward a ref to drive it imperatively:
+
+```tsx
+import React from "react";
+import { FeedbackButton, type Widget } from "@heedkit/sdk-react";
+
+function CustomTrigger() {
+  const ref = React.useRef<Widget>(null);
+
+  return (
+    <>
+      <FeedbackButton ref={ref} projectKey="fh_xxx" hideLauncher />
+      <button onClick={() => ref.current?.open()}>Open feedback</button>
+      <button onClick={() => ref.current?.close()}>Close</button>
+    </>
+  );
+}
+```
+
+The ref resolves to a `Widget` exposing `open()`, `close()`, `destroy()`, and the
+underlying `client`. If `init` fails (bad key / network), it's logged via
+`console.warn` and `open()` becomes a no-op rather than throwing.
+
+## Headless (no built-in UI)
+
+`useHeedKit()` returns the ready client so you can build your own roadmap. It
+must be called inside `<HeedKitProvider>` (it throws otherwise).
+
+```tsx
+import { useHeedKit, type Feature } from "@heedkit/sdk-react";
+
+function MyRoadmap() {
+  const { client, ready, theme } = useHeedKit();
+  const [features, setFeatures] = React.useState<Feature[]>([]);
+
+  React.useEffect(() => {
+    if (ready) client.list({ sort: "top" }).then(setFeatures);
+  }, [client, ready]);
+
+  if (!ready) return null;
+
+  // Data:   client.list / submit / vote / listComments / comment
+  // Config: client.getEnabledKinds() / getInteractionsFor(kind) /
+  //         getKindInteractions() / getKindVisibility() / getProjectName() /
+  //         getTheme() / getEndUserId()
+  return <ul>{features.map((f) => <li key={f.id}>{f.title}</li>)}</ul>;
+}
+```
+
+## SSR / Next.js (App Router)
+
+`HeedKitProvider`, `FeedbackButton`, and `useHeedKit` use React hooks and Context,
+so they must run in a **Client Component**. Add `"use client"` at the top of any
+file that renders them (or wrap them in one):
+
+```tsx
+"use client";
+import { HeedKitProvider, FeedbackButton } from "@heedkit/sdk-react";
+```
+
+They're safe under server rendering and streaming: the widget DOM work and
+`client.init()` run inside `useEffect` (browser only), and the device-id helper
+returns `null` on the server — importing the package or its types in a server
+file won't crash. The only requirement is the Client Component boundary.
+
+## Theming
+
+Theme is configured in the HeedKit console (not via props) and delivered on
+`init`. Themeable: primary color, corner radius, light / dark / `system` mode,
+font family & size, `tabs` vs `list` grouping, and per-kind `show_counts`. Read
+the resolved theme in headless UIs via `useHeedKit().theme` (or
+`client.getTheme()`).
+
+## API reference
+
+### `<HeedKitProvider>`
+
+| Prop         | Type        | Required | Notes                                   |
+| ------------ | ----------- | -------- | --------------------------------------- |
+| `projectKey` | `string`    | yes      | Your `fh_…` key.                        |
+| `apiUrl`     | `string`    | no       | Override the API base URL.              |
+| `user`       | `EndUser`   | no       | `{ externalId?, email?, name?, avatarUrl?, platform? }`. Omit `externalId` to use a persisted per-browser device id. |
+
+### `useHeedKit()`
+
+Returns `{ client: HeedKitClient, ready: boolean, theme: Theme }`. Throws if used
+outside `<HeedKitProvider>`.
+
+### `<FeedbackButton>`
+
+Accepts the same config as the provider (`projectKey`, `apiUrl`, `user`) plus:
+
+| Prop           | Type      | Default      | Notes                              |
+| -------------- | --------- | ------------ | ---------------------------------- |
+| `label`        | `string`  | `"Feedback"` | Floating launcher label.           |
+| `hideLauncher` | `boolean` | `false`      | Hide the launcher; drive via ref.  |
+
+Forwards a ref to a `Widget` (`open()`, `close()`, `destroy()`, `client`).
+
+### `HeedKitClient`
+
+| Method                            | Returns                                  |
+| --------------------------------- | ---------------------------------------- |
+| `list(opts?)`                     | `Promise<Feature[]>` — `opts: { status?, kind?, sort?: "top" \| "new" }` |
+| `submit(input)`                   | `Promise<Feature>` — `input: { title, description?, tag?, kind? }` |
+| `vote(featureId)`                 | `Promise<{ voted: boolean; vote_count: number }>` (toggles) |
+| `listComments(featureId)`         | `Promise<Comment[]>`                     |
+| `comment(featureId, body)`        | `Promise<Comment>`                       |
+| `getTheme()`                      | `Theme`                                  |
+| `getEnabledKinds()`               | `FeatureKind[]`                          |
+| `getInteractionsFor(kind)`        | `Interaction[]`                          |
+| `getKindInteractions()`           | per-kind interaction map                 |
+| `getKindVisibility()`             | per-kind default visibility              |
+| `getProjectName()`                | `string`                                 |
+| `getEndUserId()`                  | `string \| null`                         |
+
+Methods other than `init`/getters throw if called before `init()` resolves; the
+provider and widget call `init()` for you.
+
+## Example
+
+A complete Vite + React app lives in [`Example/`](./Example) — build the SDK
+once (`npm run build`), then `cd Example && npm install && npm run dev`.
+
+## License
+
+MIT © HeedKit