@firstflow/react 0.0.1 → 0.0.101

package/README.md

@@ -1,315 +1,107 @@
-# @cdn/react-issue-reporter
-
-Firstflow platform React SDK. Issue reporting is one feature module; the root API is a platform instance with `agentId`, `apiUrl`, and feature modules (e.g. `firstflow.issue`).
-
-Three modes for issues: **inline** (form in a container), **modal** (form in a modal), and **programmatic** (submit without UI).
-
-## Installation
-
-```bash
-npm install @cdn/react-issue-reporter
-```
-
-Peer dependencies: `react` and `react-dom` (>= 18).
-
-## Quick start
-
-### 1. Create the platform instance
-
-```ts
-import { createFirstflow } from '@cdn/react-issue-reporter';
-
-const firstflow = createFirstflow({
-  agentId: 'your-agent-id',
-  apiUrl: 'https://api.example.com',
-});
-```
-
-The instance has read-only `agentId`, `apiUrl`, a platform **analytics** API (`firstflow.analytics.track()`, etc.), an **issue** module (`open`, `submit`, `getConfig`, `destroy`), and a **feedback** module for per-message ratings (`submit`, `getConfig`, `isEnabled`). Issue and message-feedback submissions are sent via the analytics layer (Jitsu event `issue_submitted` / `feedback_submitted`); no backend POST for those events.
-
-To load **issues**, **message feedback**, and **active experiences** (including saved `flow` graphs) from the backend (`GET {apiUrl}/agents/{agentId}/config`), use `useCreateFirstflow(agentId, apiUrl, { fetchConfig: true })`. Pass the returned `firstflow` and **`config`** to `FirstflowProvider` (`config={config}`). Children can call **`useFirstflowConfig()`** to read `config.experiences` (and issues/feedback fields) without a second request.
-
-Alternatively pass `feedbackConfig` into `createFirstflow({ ..., feedbackConfig })` if you are not using `fetchConfig` but still want the message feedback UI enabled.
-
-### 2. Use with React (inline or modal)
-
-Wrap your app with `FirstflowProvider` and pass the instance:
-
-```tsx
-import { FirstflowProvider, InlineIssueForm, useFirstflow } from '@cdn/react-issue-reporter';
-
-<FirstflowProvider firstflow={firstflow}>
-  <YourApp />
-  <InlineIssueForm />
-</FirstflowProvider>
-```
-
-- **Inline:** `<InlineIssueForm />` renders the form in place.
-- **Modal:** Call `firstflow.issue.open()` or `useIssueReporter().open()` to open the form in a modal (e.g. a “Report issue” button).
-
-### 3. Programmatic submit (no UI)
-
-```ts
-await firstflow.issue.submit({
-  name: 'Jane',
-  email: 'j@example.com',
-  subject: 'Bug',
-  description: '…',
-  messageId: 'msg_1',
-  conversationId: 'conv_1',
-});
-```
-
-Form fields are validated; context metadata (`messageId`, `conversationId`, etc.) is passed through without validation.
-
-#### Headless issue form: `useIssueForm()`
-
-Inside `IssueReporterProvider` / `FirstflowProvider`, build your own layout (Tailwind, etc.):
-
-```tsx
-import { useIssueForm } from '@cdn/react-issue-reporter';
-
-function CustomIssueForm() {
-  const { values, setValue, errors, submit, submitting, isEnabled, fields, promptText } = useIssueForm();
-  if (!isEnabled) return null;
-  return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        void submit();
-      }}
-    >
-      {promptText && <p>{promptText}</p>}
-      {fields.map((f) => (
-        <div key={f.id}>
-          <label>{f.label}</label>
-          <input value={values[f.id] ?? ''} onChange={(e) => setValue(f.id, e.target.value)} />
-          {errors[f.id] && <span>{errors[f.id]}</span>}
-        </div>
-      ))}
-      <button type="submit" disabled={submitting}>Send</button>
-    </form>
-  );
-}
-```
-
-`submit()` merges context from `open({ messageId, conversationId, … })` the same way as `FormEngine` / `InlineIssueForm`.
-
-### 4. Message feedback (per assistant message)
-
-Host must pass stable **`conversationId`** and **`messageId`** (the assistant message being rated). **`agent_id`** is added automatically on the Jitsu payload.
-
-Two integration styles (similar to Clerk’s ready components vs hooks):
-
-| Style | Use when |
-|-------|----------|
-| **`MessageFeedback`** | You want the built-in card / inline thumbs UI. |
-| **`useFeedback({ conversationId, messageId, messagePreview })`** | Headless per-message ratings (Tailwind, custom buttons). |
-| **`useFeedback()`** (no args) | Programmatic feedback only: `submit(payload)`, `getConfig()`, `isEnabled()` (e.g. custom slots). |
-
-#### Headless message ratings: `useFeedback({ ... })`
-
-Inside `FirstflowProvider`, pass `conversationId`, `messageId`, and `messagePreview`. Returns `rating`, `selectedTags`, `comment`, `setRating`, `toggleTag`, `setComment`, `submit`, `isEnabled`, `config`, `sideConfig`, plus `submitting`, `submitted`, `error`, `clearError`.
-
-```tsx
-import { useFeedback } from '@cdn/react-issue-reporter';
-
-function MyFeedbackRow({ conversationId, messageId, preview }: Props) {
-  const { rating, setRating, submit, isEnabled, submitting, sideConfig, selectedTags, toggleTag, comment, setComment } =
-    useFeedback({
-      conversationId,
-      messageId,
-      messagePreview: preview,
-      metadata: { surface: 'chat' },
-    });
-
-  if (!isEnabled) return null;
-
-  return (
-    <div className="flex flex-col gap-2">
-      <div className="flex gap-2">
-        <button
-          type="button"
-          className={rating === 'like' ? 'bg-green-600 text-white' : 'bg-gray-200'}
-          onClick={() => setRating('like')}
-        >
-          Helpful
-        </button>
-        <button
-          type="button"
-          className={rating === 'dislike' ? 'bg-red-500 text-white' : 'bg-gray-200'}
-          onClick={() => setRating('dislike')}
-        >
-          Not helpful
-        </button>
-      </div>
-      {rating && sideConfig && (
-        <>
-          <p className="text-xs font-semibold">{sideConfig.heading}</p>
-          <div className="flex flex-wrap gap-1">
-            {sideConfig.tags.map((tag) => (
-              <button key={tag} type="button" onClick={() => toggleTag(tag)} className={selectedTags.includes(tag) ? 'ring-2 ring-blue-500' : ''}>
-                {tag}
-              </button>
-            ))}
-          </div>
-          <textarea value={comment} onChange={(e) => setComment(e.target.value)} placeholder={sideConfig.placeholder} />
-          <button type="button" disabled={submitting} onClick={() => void submit()}>
-            {submitting ? 'Sending…' : 'Send'}
-          </button>
-        </>
-      )}
-    </div>
-  );
-}
-```
-
-#### Ready component: `MessageFeedback`
-
-Use **`MessageFeedback`** when `feedback_config.enabled` is true (from agent or from `createFirstflow({ feedbackConfig })`):
-
-```tsx
-// App root: one provider after firstflow is ready
-<FirstflowProvider firstflow={firstflow}>
-  <ChatMessage conversationId={cid} messageId={mid} text={assistantText} />
-</FirstflowProvider>
-
-function ChatMessage({ conversationId, messageId, text }) {
-  return (
-    <MessageFeedback
-      conversationId={conversationId}
-      messageId={messageId}
-      messagePreview={text}
-    />
-  );
-}
-```
-
-- **`variant="default"`** (default): preview box + thumbs + form.
-- **`variant="inline"`**: thumbs only in the first fragment node (place beside the message in a flex row); after the user picks like/dislike, the tag/comment form renders in a second fragment node — use a wrapping flex container with `flex-wrap: wrap` and give the form child `flex: 1 1 100%` so it spans the full width below.
-- **`inlineFormSurface="dark"`**: when using `variant="inline"`, styles the expanded form for dark chat backgrounds.
-
-Programmatic (no UI):
-
-```ts
-await firstflow.feedback.submit({
-  conversationId: 'conv_1',
-  messageId: 'msg_assistant_42',
-  rating: 'like', // or 'dislike'
-  comment: 'optional',
-  messagePreview: 'snippet for analytics',
-  metadata: { page: '/chat', locale: 'en' },
-});
-```
-
-**Jitsu event `feedback_submitted`** — properties (snake_case) include:
-
-| Property | Required | Notes |
-|----------|----------|--------|
-| `agent_id` | yes | Injected by SDK |
-| `session_id`, `device_type` | yes | Injected by SDK |
-| `anonymousId` | yes | On envelope (Segment-style) |
-| `conversation_id` | yes | From host |
-| `message_id` | yes | From host |
-| `rating` | yes | `like` \| `dislike` |
-| `comment` | no | Free text |
-| `message_preview` | no | Truncated (~2000 chars) |
-| `metadata` | no | Arbitrary JSON object (serializable keys/values; max ~32KB serialized) |
-| `submitted_at` | yes | ISO timestamp |
-
-**Analytics:** “Current” feedback per user per message is the **latest** row by timestamp for the same `message_id` and identity (`anonymousId` / `userId`), e.g. `ROW_NUMBER() OVER (PARTITION BY message_id, anonymous_id ORDER BY timestamp DESC) = 1` in your warehouse.
-
-### 5. Experience flow: Message nodes (`useExperienceMessageNode`)
-
-Headless hook for a **Message** step in an experience (config matches the dashboard message node: text, carousel, quick replies, CTAs, **`ctaUrl`** / **`ctaPrompt`**). It returns **`blocks`** in fixed order (`text` → `carousel` → `quick_replies` → `cta_primary` → `cta_dismiss`), **`blocksVersion`** (currently **4**; quick-reply options are `{ label, prompt? }` and `quick_reply` actions include optional **`promptText`**; v3 added primary CTA **`promptText`**; v2 added per-card carousel CTA fields), **`ui`** flags, and **`handlers`** for clicks. Integrate navigation in **`onAction`** (map `kind` / `label` / `promptText` / `url` / `index` / `cardId` / `actionId` to your graph — e.g. send **`promptText`** or **`label`** as the user message for button CTAs and quick replies, open **`url`** for link CTAs).
-
-| Topic | Behavior |
-|-------|----------|
-| **Shown** | `EXPERIENCE_SHOWN` on mount by default (`trackShownOnMount: true`). |
-| **Dedupe** | Module-scoped Set: same default key (`agentId` + `experienceId` + `nodeId` + `conversationId`) fires **once** per page load. Re-showing the same node in a new run needs a unique **`impressionKey`** (e.g. append `flowInstanceId`) or **`dedupeShown: false`**. |
-| **Virtualized lists** | `trackShownOnMount: false` and call **`reportShown()`** when the row is visible (e.g. IntersectionObserver). |
-| **Clicks** | `EXPERIENCE_CLICKED` with `action` from **`EXPERIENCE_MESSAGE_ANALYTICS_ACTION`** (`cta_primary`, `cta_dismiss`, `quick_reply`, `carousel_cta`). For `cta_primary`, props may include **`cta_url`** (link) and **`cta_prompt`** (button prompt text). For `quick_reply`, props include **`quick_reply_label`**, **`quick_reply_index`**, and optional **`quick_reply_prompt`**. For `carousel_cta`, props include **`card_id`**, **`carousel_action_id`** (`primary` / `secondary`), and when the card is in config: **`carousel_button_action`** (`prompt` / `link`), **`carousel_button_label`**, **`carousel_link_url`**, **`carousel_prompt`**. Use **`buildExperienceCarouselCtaAction(config, cardId, actionId)`** if you build clicks outside **`handlers.onCarouselCta`**. **`message_style`** normalizes legacy `inline` to `message`. |
-| **Errors** | `onAction` / `mapAnalytics` throws are logged; analytics still runs (`onAction` first, then track; if `mapAnalytics` throws, base props are tracked). |
-
-Optional **`mapAnalytics(eventName, props)`** transforms payloads before `track` (avoid renaming events unless intentional).
-
-**Next step (not in SDK yet):** a thin `<MessageNode />` wrapper around this hook for default markup.
-
-### 6. Imperative mount (optional DOM adapter)
-
-```ts
-import { createFirstflow, mount } from '@cdn/react-issue-reporter';
-
-const firstflow = createFirstflow({ agentId, apiUrl });
-const unmount = mount(firstflow, document.getElementById('issue-root'));
-// Later: firstflow.issue.open() opens the modal.
-// Teardown: unmount(); firstflow.issue.destroy();
-```
-
-## API
-
-### createFirstflow(options)
-
-Returns a **FirstflowInstance** (root platform context).
-
-- `options.agentId` (string)
-- `options.apiUrl` (string)
-- `options.jitsuHost?` (string) — Jitsu host for analytics; defaults to shared Firstflow Jitsu if omitted
-- `options.jitsuWriteKey?` (string) — Jitsu write key; defaults to shared key if omitted
-
-**FirstflowInstance:**
-
-- `agentId`, `apiUrl` (read-only)
-- `analytics` — platform analytics API (used by all feature modules):
-  - `track(eventName, properties?)` — send a track event to Jitsu (Segment-compatible)
-  - `identify(userId?, traits?)` — identify a user (optional)
-  - `page(name?, properties?)` — page view (optional)
-- `issue` — public issue module API:
-  - `open(options?)` — open the issue UI (modal or inline depending on integration)
-  - `submit(data)` — submit an issue (form values + optional context)
-  - `getConfig()` — read-only config (enabled, promptText, fields)
-  - `destroy()` — tear down handlers
-- `feedback` — message feedback (Jitsu `feedback_submitted`):
-  - `submit({ conversationId, messageId, rating, comment?, messagePreview?, metadata? })` — tag pills in the UI are not sent to Jitsu; put anything you need for analytics in `metadata`
-  - `getConfig()`, `isEnabled()`
-
-Naming: issue uses **open** + **submit**; feedback uses **submit** (and optional **MessageFeedback** UI).
-
-### React exports
-
-- **FirstflowProvider** — accepts `firstflow: FirstflowInstance`; provides the platform instance to the tree. Transitional: it delegates to the existing issue provider; the final architecture may use a single provider for multiple modules.
-- **useFirstflow()** — returns the platform instance from context.
-- **useCreateFirstflow(agentId, apiUrl, { fetchConfig? })** — returns `{ firstflow, loading, error }`. With `fetchConfig: true`, loads `issues_config` and `feedback_config` from the agent on `GET .../config` (supports `{ meta, data: { agent } }`).
-- **useFeedback()** — returns `firstflow.feedback` (must be inside `FirstflowProvider`).
-- **MessageFeedback** — props: `conversationId`, `messageId`, `messagePreview`, optional `metadata`; renders nothing when feedback is disabled.
-- **fetchSdkAgentConfig(apiUrl, agentId)** — low-level fetch of `{ issues_config, feedback_config }`.
-- **useIssueReporter()** — returns `{ reporter, open, reportIssue, submit, config, isModalOpen, closeModal }` for issue-specific state.
-- **InlineIssueForm** — renders the form inline (only when `config.enabled`).
-- **IssueModal** — modal wrapper (rendered by the provider).
-- **FormEngine** — headless-friendly form (config + onSubmit + optional onCancel).
-
-### mount(firstflow, target)
-
-DOM adapter only: renders `FirstflowProvider` + `InlineIssueForm` into `target` with React 18 `createRoot`. Returns an unmount function.
-
-## Issue types (platform-first exports)
-
-Issue-specific types are under the **Issue** namespace so the root package stays platform-first:
-
-- `Issue.FormValues`, `Issue.ContextMetadata`, `Issue.Payload`, `Issue.OpenOptions`
-- `Issue.NormalizedConfig`, `Issue.NormalizedFieldConfig`, `Issue.RawIssueFieldConfig`, `Issue.RawIssuesConfig`, `Issue.ValidationResult`
-
-Platform types at root: `FirstflowInstance`, `CreateFirstflowOptions`, `IssueModulePublic`, `AnalyticsModulePublic`. Event names: `ISSUE_SUBMITTED`, `FEEDBACK_SUBMITTED`, `SURVEY_COMPLETED`, etc. (see `analytics/events`).
-
-## Analytics and validation
-
-- **Analytics:** Issue submissions (and future modules) go through the platform analytics layer. Feature modules call `firstflow.analytics.track(eventName, properties)`; the analytics service sends Segment-compatible events to Jitsu. See [ANALYTICS.md](./ANALYTICS.md).
-- **Validation:** `validatePayload(data, fields)` applies to form field keys only; used by the issue module before calling `analytics.track("issue_submitted", payload)`.
-
-## Architecture
-
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for the platform instance, analytics layer, transitional provider design, and data flow.
-
-## License
-
-Private / Firstflow.
+# Firstflow React SDK
+
+Official React SDK for [Firstflow](https://firstflow.app) — in-chat surveys, onboarding flows, announcements, and analytics inside your agent product.
+
+## Installation
+
+```bash
+npm install @firstflow/react
+```
+
+**Requirements:** React 18+ and React DOM 18+ (peer dependencies).
+
+Styles for bundled UI ship with the package and are applied automatically in the browser; you do not need a separate CSS import for default integrations.
+
+## Getting started
+
+Wrap your app (or chat surface) with `FirstflowProvider`, pass your **agent ID** and **API key** from the Firstflow dashboard, then use hooks and components as needed.
+
+```tsx
+import {
+  FirstflowProvider,
+  FirstflowWidget,
+  useFirstflow,
+} from "@firstflow/react";
+
+export function App() {
+  return (
+    <FirstflowProvider
+      agentId={process.env.NEXT_PUBLIC_FIRSTFLOW_AGENT_ID!}
+      apiKey={process.env.NEXT_PUBLIC_FIRSTFLOW_API_KEY!}
+      fallback={<span>Loading…</span>}
+      onError={(err) => console.error(err)}
+    >
+      <ChatShell />
+    </FirstflowProvider>
+  );
+}
+
+function ChatShell() {
+  const firstflow = useFirstflow();
+  firstflow.analytics.track("custom_event", { source: "chat" });
+  return <FirstflowWidget />;
+}
+```
+
+### Provider
+
+- Loads agent configuration from the Firstflow API when `apiKey` is set.
+- Optional `initialSdkPayload` for SSR or bootstrap (same shape as the config API response).
+- Optional `user` (`UserContext`) for identity, traits, and audience targeting.
+- `autoFetchAudienceMembership` defaults to `true`; set `false` if you only use `setAudienceMembership` for segments.
+
+## Documentation
+
+- **[Product docs](https://firstflow.app)** — guides and dashboard.
+- In this repository: [ARCHITECTURE.md](./ARCHITECTURE.md) (runtime, provider, audience) and [ANALYTICS.md](./ANALYTICS.md) (events, identity, pipeline).
+
+## API overview
+
+| Area | Main exports |
+|------|----------------|
+| Setup | `FirstflowProvider`, `useFirstflow`, `useFirstflowSelector`, `createFirstflow`, `fetchSdkAgentConfig`, `FIRSTFLOW_PUBLIC_API_BASE_URL` |
+| Surveys | `useFirstflowSurvey`, `Survey` |
+| Experiences | `FirstflowWidget`, `ExperienceSlot`, message/announcement components and hooks (`useExperienceMessageNode`, `useExperienceAnnouncementNode`, eligibility helpers, …) |
+| Types | `FirstflowInstance`, `CreateFirstflowOptions`, `UserContext`, `SdkAgentConfigPayload`, … |
+
+Analytics event name constants (stable strings for pipelines): `SURVEY_COMPLETED`, `EXPERIENCE_SHOWN`, `EXPERIENCE_CLICKED`, `CHAT_MESSAGE_SENT`, `EXPERIENCE_ANALYTICS_TYPE`.
+
+### Advanced: imperative instance
+
+For tests, non-UI tooling, or custom wiring:
+
+```ts
+import { createFirstflow } from "@firstflow/react";
+
+const firstflow = createFirstflow({
+  agentId: "...",
+  apiKey: "...",
+  user: { id: "u1", traits: { plan: "pro" } },
+});
+
+await firstflow.refreshConfig();
+```
+
+Public TypeScript types on `FirstflowInstance` currently emphasize `analytics` and `survey`. Issue reporting and per-message feedback modules are implemented but not exported from the main entry; Firstflow-internal tooling may import `@firstflow/react/internal` until those APIs are published on the default export.
+
+### `FirstflowInstance` (public surface)
+
+| Member | Purpose |
+|--------|---------|
+| `agentId`, `apiUrl` | Agent identity; API base is defined by the SDK. |
+| `analytics` | `track`, `identify`, `page`. |
+| `survey` | Load and submit survey experiences. |
+| `getUser` / `setUser` | User context and traits. |
+| `setAudienceMembership` / `getAudienceMembership` | Segment membership (`true` only grants a segment). |
+| `getWidgetUi` | Brand hints from agent config. |
+| `refreshConfig`, `reset` | Reload remote config or reset runtime state. |
+
+## Best practices
+
+- Send product analytics through `firstflow.analytics.track` rather than parallel collectors inside Firstflow flows.
+- After a successful server fetch, audience membership is replaced (not merged); see ARCHITECTURE.md for details.
+- If your CSP blocks inline styles, plan a custom styling strategy; default embeds rely on injected styles from the bundle.
+
+## License
+
+See `package.json`. This package is `UNLICENSED` unless your agreement with Firstflow states otherwise.