@fastbackr/react 0.0.0-stage → 0.0.3

package/LICENSE

@@ -0,0 +1,46 @@
+Fastbackr SDK License
+
+Copyright (c) 2026 OpsCom, Corp. All rights reserved.
+
+This license covers the "@fastbackr/react" npm package and its source code (the
+"Software"). The Software is not open source. By installing or using it you
+accept these terms.
+
+1. Grant. OpsCom, Corp. grants you a free, non-exclusive, non-transferable,
+   non-sublicensable license to install and use the Software, solely to connect
+   your websites and applications to the Fastbackr service.
+
+2. Redistribution. You may redistribute the Software only unmodified and only
+   as part of your own website or application. Bundling, minifying,
+   transpiling or tree-shaking the Software with your build tools, as part of
+   building your own website or application, is not a modification under
+   this license.
+
+3. Restrictions. Except as section 2 allows, you may not:
+   a. modify, adapt or translate the Software, or create derivative works of
+      it;
+   b. distribute, publish or make available any modified version of the
+      Software;
+   c. use the Software with any service other than the Fastbackr service;
+   d. sell, rent, lease or sublicense the Software on its own;
+   e. remove or alter this license or any copyright notice;
+   f. reverse engineer, decompile or disassemble the Software, except to the
+      extent applicable law expressly permits it despite this restriction.
+
+4. Ownership. The Software is licensed, not sold. OpsCom, Corp. keeps all
+   rights, title and interest in the Software not expressly granted here.
+
+5. Termination. This license ends automatically if you breach any of its
+   terms. On termination you must stop using the Software and remove it from
+   your websites and applications.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR
+   A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+7. Limitation of liability. IN NO EVENT SHALL OPSCOM, CORP. 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
+   OF OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Governing law. This license is governed by the laws of the United States.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# @fastbackr/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let reviewers click any element of your React app, or drag a box around any area, and leave a
+comment on it. Comments show as numbered badges on the element or area, with replies, Done / Reopen
+and a site-wide drawer.
+
+- **One provider.** Wrap your app in `<FastbackrProvider>`. The UI is drawn inside a Shadow root with its own
+  stylesheet, so your CSS and ours never touch, whatever your app styles with.
+- **Quiet until clicked.** A page view shows a small `+` button in the bottom-right corner, adds
+  two listeners and makes no requests. The first click on `+` loads the UI as a separate chunk.
+- **Your app vouches for identity.** Your server trades its API key for a short-lived reviewer token.
+  The key never reaches a browser.
+
+## Install
+
+```sh
+npm install @fastbackr/react @fastbackr/core
+```
+
+React 19 is a peer dependency. `@fastbackr/react` is the browser side; your server imports
+`@fastbackr/core`:
+
+| Import                   | Runs in     | What it is                                              |
+| ------------------------ | ----------- | ------------------------------------------------------- |
+| `@fastbackr/react`       | Browser     | `<FastbackrProvider>`, `useFastbackr()`                 |
+| `@fastbackr/core/server` | Your server | `createTokenHandler`, `createReviewerToken`, the errors |
+
+## Setup
+
+You need a Fastbackr project and its API key (v1: created in the Fastbackr dashboard), with your site's
+origins on the project's allowed list (`http://localhost:*` style patterns are fine).
+
+### 1. Keep the API key on the server
+
+```sh
+# .env (server only)
+FASTBACKR_API_KEY=fb_...
+# Optional, for a self-hosted or local API. Defaults to https://api.fastbackr.com
+FASTBACKR_URL=http://localhost:3300
+```
+
+**`FASTBACKR_API_KEY` must never reach a browser.** Do not prefix it with `NEXT_PUBLIC_`, `VITE_` or
+anything else that inlines it into client code, do not return it from a route, and do not log it.
+Anyone holding it can mint tokens for any name on your project.
+
+### 2. Add the token route
+
+The SDK asks this route on your own origin for a short-lived reviewer token, so your session cookie
+stays first-party. `createTokenHandler` reads the key from `FASTBACKR_API_KEY`, decides who the
+reviewer is and answers the SDK. Next.js App Router:
+
+```ts
+// app/api/fastbackr/route.ts
+import { createTokenHandler } from '@fastbackr/core/server';
+import { auth } from '@/lib/auth'; // your own auth
+
+export const POST = createTokenHandler({
+  // Optional: who is signed in. Leave it out and everyone comments as a guest.
+  getUser: async () => {
+    const session = await auth();
+    return session && { id: session.user.id, name: session.user.name, email: session.user.email };
+  },
+});
+```
+
+The handler takes a web `Request` and returns a `Response`, so it is the route as-is in React
+Router, Hono, SvelteKit, Bun, Deno and Workers too. `getUser` gets the request. When it names
+nobody, a visitor who typed a name gets a guest token (id `guest:<random id>`, `verified: false`),
+so a guest can never claim a signed-in user's id; anyone else gets 401 and the SDK asks for a name.
+
+### 3. Wrap your app
+
+```tsx
+// app/layout.tsx
+import { FastbackrProvider } from '@fastbackr/react';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <FastbackrProvider>{children}</FastbackrProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+The provider is a client component that Server Components can render. Only one SDK runs per page,
+so React Strict Mode and a second provider are fine.
+
+### 4. Allow the API in your Content-Security-Policy
+
+If your site sends a CSP, add the API to `connect-src`:
+
+```text
+Content-Security-Policy: connect-src 'self' https://api.fastbackr.com
+```
+
+When the policy blocks the API, the SDK logs one console error naming the directive to add.
+
+## Using it
+
+- Click `+` (or press `c` once the bar is open). The cursor becomes a crosshair: click an element, or
+  drag a box around an area, then write in the box that opens below it. On touch screens, tap an
+  element.
+- The bar stays for the rest of the tab's session. Its chevron (Minimize) goes back to the `+`
+  button. Its ✕ (Close) removes the `+` button too, in this browser; press `f` three times
+  (outside a text field) to bring it back. `useFastbackr().show()` does the same from code.
+- `Feedback` opens the drawer with every thread on the site, filtered by status and page.
+- A box is stored as a fraction of the element it sits on, so it follows that element at other
+  screen widths. When the element's shape changes a lot (columns stacked on a phone), the whole
+  element is outlined and the thread names the width the comment was left at.
+
+## Options
+
+`<FastbackrProvider>` props:
+
+| Prop             | Type                                 | Default                     |
+| ---------------- | ------------------------------------ | --------------------------- |
+| `tokenUrl`       | `string`                             | `/api/fastbackr`            |
+| `getToken`       | `(guest?) => Promise<Token \| null>` | asks `tokenUrl`             |
+| `endpoint`       | `string`                             | `https://api.fastbackr.com` |
+| `signIn`         | `() => void \| Promise<void>`        | none: no "Sign in" button   |
+| `queryKeys`      | `readonly string[]`                  | `[]`                        |
+| `hashRoutes`     | `boolean`                            | `false`                     |
+| `getPageContext` | `() => { key, path, title }`         | built from the URL          |
+
+- `getToken` replaces the request to `tokenUrl`, for a token route of your own. With no arguments
+  it asks "who is signed in?". With `guest` (`{ id, name }`) a guest typed their name; `guest.id` is
+  random, generated once and kept in `localStorage`. Resolve `{ token, expiresAt, user }`, or `null`
+  for "not signed in". A rejection's message is shown.
+- The SDK refreshes the token a minute before it expires and after any 401.
+- `useFastbackr()`, inside the provider, returns `show()` and `hide()` for your own buttons. `show()`
+  brings back a closed `+` button and sends a rainbow ring around it (or around the open bar) for 2s.
+  `hide()` is the same as Close.
+- `hashRoutes: true` makes `#records/12` a distinct page. Credential-looking query keys (`token`,
+  `secret` and similar) never enter a page key, even when listed.
+
+## Guests
+
+Without a signed-in session the bar asks for a name, or "Anonymously" (the name `Anonymous`), and,
+when you passed `signIn`, shows a "Sign in" button. A guest's name carries a "guest" tag in threads and the drawer list; in the bar, a guest clicks their
+name to change it.
+
+What a guest may do is a per-project setting on the server:
+
+| Guest access | Effect                                                              |
+| ------------ | ------------------------------------------------------------------- |
+| `off`        | `/v1/tokens` refuses `verified: false` (403 `guest_access_off`)     |
+| `write-only` | A guest sees, replies to and resolves only the threads they created |
+| `read-write` | A guest is treated like a signed-in reviewer                        |
+
+Use `write-only` when guests are outsiders (customers, prospects) who must not read your team's
+comments.
+
+## Screenshots
+
+Turn on Screenshots in the project's settings in the dashboard (off by default) and each new thread
+gets an image of the reviewer's viewport, taken on Save, with the commented element outlined. It
+shows above the first message. The reviewer can uncheck "Take screenshot" in the comment box to skip
+it for that comment. Fastbackr's own UI is left out, and `data-fastbackr-private`
+elements and form fields (text inputs, textareas, selects, editable regions) become black boxes.
+Everything else on screen is captured, customer data included: mark private areas with
+`data-fastbackr-private`. The panel shows the image from a `blob:` URL, so a CSP needs
+`img-src blob:`.
+
+## Marking up your page (optional)
+
+Comments find their element again from its tag, label, text and position. Ids that look generated
+(`:r1:`, `radix-12`, hashed names) are ignored. Explicit ids are sturdier:
+
+| Attribute                        | Effect                                                        |
+| -------------------------------- | ------------------------------------------------------------- |
+| `data-fastbackr-id="hero-cta"`   | Stable identity; a comment attaches to exactly this element   |
+| `data-fastbackr-component="Nav"` | Labels comments left on this element                          |
+| `data-fastbackr-private`         | Never in a comment's excerpt; a black box in screenshots      |
+
+Form field values are never captured, and screenshots black the fields out.
+
+## A token route in another language
+
+`createTokenHandler` is the easy path. Any server can answer the SDK instead (Express, Rails,
+Django, Go): `POST /api/fastbackr` on your origin receives `{}` ("who is signed in?") or
+`{ "guest": { "id", "name" } }`. Answer:
+
+- 200 with the body of `POST https://api.fastbackr.com/v1/tokens`, which you call with
+  `Authorization: Bearer <FASTBACKR_API_KEY>` and `{ "user": { "id", "name", "email"?, "verified" } }`.
+  Vouch for a guest as `{ "id": "guest:<guest.id>", "name": <guest.name>, "verified": false }`.
+- 401 when nobody may comment yet: the SDK shows its name form.
+- 403 `{ "error": { "code": "guest_access_off", ... } }` passed on from the API.
+
+In Node, `createReviewerToken({ apiKey, user })` makes that API call for you.
+
+## Errors on the server
+
+`createTokenHandler` answers errors itself (500 when `FASTBACKR_API_KEY` is missing, 502 when the
+API cannot be reached) and logs the reason. `createReviewerToken` throws `FastbackrError` with
+`status` and `code`:
+
+- `status: 0`, `invalid_request`: bad input; nothing was sent.
+- `status: 0`, `network_error`: the API could not be reached.
+- otherwise the API's own status and code, for example `401 unauthorized` (bad or revoked key),
+  `403 guest_access_off`.
+
+Error messages never include the API key.
+
+## How it is built
+
+`@fastbackr/core` holds the logic: tokens, the API client, finding an element again, select mode.
+This package draws the UI with the components and theme of Fastbackr's design system (shadcn on
+Base UI, Tailwind CSS v4). The build compiles that stylesheet and the SDK injects it into its
+Shadow root; your page never loads it. Browsers ignore `@property` inside a Shadow root, so the build
+turns on Tailwind's fallback values for its `--tw-*` variables instead. The UI uses the system font.
+
+## License
+
+Free to install and use with the Fastbackr service. Modifying it is not allowed. See `LICENSE`.