@feedclip/sdk 0.1.0

package/README.md

@@ -0,0 +1,676 @@
+# FeedClip AI
+
+Customer Feedback Infrastructure for SaaS.
+
+FeedClip is an embeddable feedback SDK for React, Vue, and Angular that captures
+customer video, voice, screenshots, page context, and product metadata. Your
+backend can turn that submission into a transcript, structured AI analysis, and
+an engineering issue.
+
+```text
+Capture SDK -> Ingestion API -> Transcription -> AI analysis -> Issue tracker
+```
+
+## Current MVP
+
+The repository currently includes:
+
+- camera and microphone recording with browser `MediaRecorder`;
+- pause, resume, stop, preview, reset, and optional trimming;
+- customer feedback type and written description;
+- optional screenshot attachment;
+- automatic URL, browser, locale, viewport, timezone, and referrer capture;
+- custom SaaS context such as user, account, plan, release, and feature flags;
+- an AI-ready `FeedbackSubmission` contract;
+- a multipart HTTP transport for feedback ingestion;
+- an IndexedDB transport for local development and offline capture;
+- rendering of returned AI analysis and generated issue details;
+- legacy file-only upload support;
+- Supabase and S3 uploader helpers;
+- localization for 10 languages;
+- React implementation with Vue 3 and Angular 19 lifecycle adapters;
+- ESM, CommonJS, CSS, and TypeScript declaration builds;
+- 106 automated tests.
+
+The hosted ingestion service, production transcription worker, persistent
+dashboard, deduplication, and native issue-tracker connectors are the next
+platform layer. The SDK contracts required by that layer are already included.
+
+## Installation
+
+React:
+
+```bash
+npm install @feedclip/sdk react react-dom
+```
+
+Vue 3:
+
+```bash
+npm install @feedclip/sdk vue react react-dom
+```
+
+Angular 19:
+
+```bash
+npm install @feedclip/sdk @angular/core react react-dom
+```
+
+The Vue and Angular entrypoints are lifecycle adapters over the same tested
+React capture engine. They require React 19 and React DOM 19 as peer
+dependencies. Jotai is an internal dependency and is installed automatically.
+
+These are framework adapters, not independent native Vue and Angular
+implementations. This keeps capture behavior consistent, but means Vue and
+Angular applications include the React runtime.
+
+## React
+
+Use `onSubmit` for the complete customer-feedback flow:
+
+```tsx
+import FeedClip, {
+  createFeedbackEndpointTransport,
+} from "@feedclip/sdk";
+import "@feedclip/sdk/style.css";
+
+const submitFeedback = createFeedbackEndpointTransport({
+  endpoint: "/api/feedback",
+  headers: {
+    Authorization: `Bearer ${sessionToken}`,
+  },
+});
+
+export function CustomerFeedback() {
+  return (
+    <FeedClip
+      config={{
+        locale: "en-US",
+        maxDurationMilliSeconds: 60_000,
+        maxFileSize: 100_000_000,
+        defaultVideoFileExtension: "webm",
+        defaultVideoFileNameStyle: "ISO 8601",
+        onSubmit: submitFeedback,
+        getContext: () => ({
+          userId: currentUser.id,
+          accountId: currentAccount.id,
+          plan: currentAccount.plan,
+          appVersion: APP_VERSION,
+          featureFlags: activeFeatureFlags,
+        }),
+      }}
+    />
+  );
+}
+```
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import FeedClipVue from "@feedclip/sdk/vue";
+import { createFeedbackEndpointTransport } from "@feedclip/sdk";
+import "@feedclip/sdk/style.css";
+
+const config = {
+  locale: "en-US" as const,
+  maxDurationMilliSeconds: 60_000,
+  maxFileSize: 100_000_000,
+  defaultVideoFileExtension: "webm" as const,
+  defaultVideoFileNameStyle: "ISO 8601" as const,
+  onSubmit: createFeedbackEndpointTransport({
+    endpoint: "/api/feedback",
+  }),
+};
+</script>
+
+<template>
+  <FeedClipVue :config="config" />
+</template>
+```
+
+The adapter reacts to deep `config` changes and unmounts its internal capture
+root together with the Vue component.
+
+## Angular
+
+```ts
+import { Component } from "@angular/core";
+import { FeedClipAngularComponent } from "@feedclip/sdk/angular";
+import { createFeedbackEndpointTransport } from "@feedclip/sdk";
+import "@feedclip/sdk/style.css";
+
+@Component({
+  selector: "app-feedback",
+  standalone: true,
+  imports: [FeedClipAngularComponent],
+  template: `<feedclip-widget [config]="config" />`,
+})
+export class FeedbackComponent {
+  readonly config = {
+    locale: "en-US" as const,
+    maxDurationMilliSeconds: 60_000,
+    maxFileSize: 100_000_000,
+    defaultVideoFileExtension: "webm" as const,
+    defaultVideoFileNameStyle: "ISO 8601" as const,
+    onSubmit: createFeedbackEndpointTransport({
+      endpoint: "/api/feedback",
+    }),
+  };
+}
+```
+
+`FeedClipAngularComponent` is standalone, responds to `config` input changes,
+and releases the capture root in `ngOnDestroy`.
+
+Use either `onSubmit` or the legacy `onUpload` handler. When both are provided,
+`onSubmit` takes precedence.
+
+For local development without a backend, store real submissions in IndexedDB:
+
+```ts
+import { createIndexedDbFeedbackStore } from "@feedclip/sdk";
+
+const onSubmit = createIndexedDbFeedbackStore({
+  databaseName: "my-product-feedback",
+});
+
+await onSubmit.delete(feedbackId);
+await onSubmit.clear();
+```
+
+This stores the metadata, video, and screenshot in the browser and returns
+`{ status: "received" }`. It does not invent an AI result.
+
+## Feedback Flow
+
+```text
+Start recording
+      |
+      v
+Video + voice capture <-> Pause / resume
+      |
+      v
+Preview + description + feedback type + screenshot
+      |
+      v
+FeedbackSubmission
+      |
+      v
+Backend processing
+      |
+      +-> transcript
+      +-> AI summary and severity
+      +-> reproduction steps
+      +-> GitHub / Linear / Jira issue
+      |
+      v
+FeedbackReceipt rendered in the widget
+```
+
+## Submission Contract
+
+`onSubmit` receives the following object:
+
+```ts
+interface FeedbackSubmission {
+  id: string;
+  createdAt: string;
+  kind: "bug" | "idea" | "question" | "other";
+  description: string;
+  video: File;
+  screenshot?: File;
+  context: {
+    url: string;
+    title: string;
+    userAgent: string;
+    language: string;
+    viewport: {
+      width: number;
+      height: number;
+      devicePixelRatio: number;
+    };
+    timezone: string;
+    referrer?: string;
+  };
+  customContext?: Record<string, unknown>;
+}
+```
+
+`getContext` may be synchronous or asynchronous. Do not place passwords,
+access tokens, payment data, or other secrets in the returned object.
+
+FeedClip removes URL credentials, fragments, query strings, and referrers from
+browser context by default. Query strings can be enabled only when required:
+
+```ts
+browserContext: {
+  includeQueryString: true,
+  includeReferrer: false,
+}
+```
+
+Review query parameters before enabling this option because they commonly
+contain email addresses, reset tokens, OAuth codes, and other sensitive data.
+
+Link the widget to the integrating product's privacy notice:
+
+```ts
+privacyNotice: {
+  url: "/privacy",
+  label: "Privacy notice",
+}
+```
+
+The integrating product remains responsible for selecting and documenting its
+lawful basis, presenting any required notice before capture, and obtaining
+consent where consent is the selected basis. Browser camera or microphone
+permission is not a substitute for privacy consent.
+
+## Backend Transport
+
+`createFeedbackEndpointTransport` sends `multipart/form-data`:
+
+| Field | Content |
+|---|---|
+| `payload` | JSON metadata without binary files |
+| `video` | Recorded video and voice |
+| `screenshot` | Optional customer screenshot |
+
+```ts
+import { createFeedbackEndpointTransport } from "@feedclip/sdk";
+
+const onSubmit = createFeedbackEndpointTransport({
+  endpoint: "https://feedback.example.com/v1/submissions",
+  credentials: "include",
+  headers: {
+    "X-Project-Key": projectKey,
+  },
+});
+```
+
+The endpoint must return a JSON `FeedbackReceipt`:
+
+```ts
+interface FeedbackReceipt {
+  feedbackId: string;
+  status: "received" | "processing" | "completed";
+  analysis?: {
+    title: string;
+    summary: string;
+    category: "bug" | "idea" | "question" | "other";
+    priority: "low" | "medium" | "high" | "critical";
+    sentiment: "negative" | "neutral" | "positive";
+    reproductionSteps: string[];
+    expectedBehavior?: string;
+    actualBehavior?: string;
+    labels: string[];
+    transcript?: string;
+  };
+  issue?: {
+    provider: "github" | "linear" | "jira" | "custom";
+    id: string;
+    title: string;
+    url?: string;
+  };
+}
+```
+
+When `analysis` or `issue` is present, FeedClip renders it below the capture
+controls.
+
+## AI Processing
+
+A production backend should:
+
+1. authenticate the project and validate the submission;
+2. store video and screenshot in private object storage;
+3. enqueue asynchronous processing;
+4. transcribe the audio track;
+5. generate schema-validated analysis;
+6. deduplicate similar feedback;
+7. create or update an issue;
+8. persist the result and notify the originating SaaS.
+
+FeedClip exports `buildFeedbackAnalysisPrompt` for the analysis step.
+
+Example with AI SDK 6:
+
+```ts
+import { generateText, Output } from "ai";
+import { z } from "zod";
+import { buildFeedbackAnalysisPrompt } from "@feedclip/sdk";
+
+const analysisSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  category: z.enum(["bug", "idea", "question", "other"]),
+  priority: z.enum(["low", "medium", "high", "critical"]),
+  sentiment: z.enum(["negative", "neutral", "positive"]),
+  reproductionSteps: z.array(z.string()),
+  expectedBehavior: z.string().optional(),
+  actualBehavior: z.string().optional(),
+  labels: z.array(z.string()),
+  transcript: z.string().optional(),
+});
+
+const { output: analysis } = await generateText({
+  model: "openai/gpt-5.4",
+  output: Output.object({ schema: analysisSchema }),
+  prompt: buildFeedbackAnalysisPrompt(payload, transcript),
+});
+```
+
+Keep provider credentials and AI processing on the server. Never expose model
+or issue-tracker API keys in the capture SDK.
+
+### Included API project
+
+This repository includes a standalone Node.js API in [`apps/api`](./apps/api).
+It implements the SDK multipart contract, project-key authentication, private
+development storage, OpenAI transcription, schema-validated AI analysis, and
+submission status polling.
+
+```bash
+cd apps/api
+cp .env.example .env
+npm install
+npm run dev
+```
+
+See [`apps/api/README.md`](./apps/api/README.md) for configuration and
+production deployment notes.
+
+See [`COMPLIANCE.md`](./COMPLIANCE.md) for the data inventory, controller and
+processor responsibilities, deletion and retention controls, and deployment
+checklist.
+
+## Legacy File Upload
+
+Existing integrations can continue to receive only the recorded file:
+
+```tsx
+<FeedClip
+  config={{
+    locale: "en-US",
+    maxDurationMilliSeconds: 60_000,
+    maxFileSize: 100_000_000,
+    defaultVideoFileExtension: "webm",
+    defaultVideoFileNameStyle: "UnixTimestamp",
+    onUpload: async (file) => {
+      const formData = new FormData();
+      formData.append("video", file);
+      await fetch("/api/upload", {
+        method: "POST",
+        body: formData,
+      });
+    },
+  }}
+/>
+```
+
+## Configuration
+
+| Property | Type | Required | Description |
+|---|---|---:|---|
+| `locale` | Supported locale | Yes | Widget language |
+| `maxDurationMilliSeconds` | `number` | Yes | Recording time limit |
+| `maxFileSize` | `number` | Yes | Maximum submitted video size in bytes |
+| `defaultVideoFileExtension` | `"webm" \| "mp4" \| "avi" \| "mov" \| "mkv"` | Yes | Preferred file extension |
+| `defaultVideoFileNameStyle` | `"UnixTimestamp" \| "ISO 8601" \| "Custom"` | Yes | Generated filename strategy |
+| `onSubmit` | `(submission, onProgress?) => Promise<FeedbackReceipt \| void>` | One handler | Complete feedback pipeline |
+| `onUpload` | `(file, onProgress?) => Promise<void>` | One handler | Legacy file-only upload |
+| `getContext` | `() => object \| Promise<object>` | No | Application-specific metadata |
+| `browserContext` | `{ includeQueryString?, includeReferrer? }` | No | Opt in to additional browser context |
+| `privacyNotice` | `{ url, label }` | No | Link to the integrating product's privacy notice |
+| `license` | `FeedClipLicenseConfig` | No | Signed license token and verification parameters |
+| `onLicenseError` | `(reason: string) => void` | No | Receives license verification failures |
+
+Runtime validation currently expects consumers to provide one submission
+handler. Omitting both handlers causes submission to fail with an error alert.
+
+## Free and Paid Products
+
+The current `@feedclip/sdk` package is MIT-licensed. Its source code,
+including commercial use, is free under the terms of [LICENSE](./LICENSE).
+
+| Capability | Free | Paid |
+|---|:---:|:---:|
+| Video and voice capture | Yes | Yes |
+| Description, feedback type, screenshot | Yes | Yes |
+| Browser and custom product context | Yes | Yes |
+| Self-hosted `onSubmit` and HTTP transport | Yes | Yes |
+| Local IndexedDB storage | Yes | Yes |
+| Pause and preview | Yes | Yes |
+| Trimming, thumbnails, upload progress | No | Yes |
+| Supabase/S3 uploader helpers | No | Yes |
+| Screen recording, console and network capture | Roadmap | Roadmap |
+| Privacy redaction and resumable uploads | Roadmap | Roadmap |
+| Custom branding and UI themes | Roadmap | Roadmap |
+| Managed storage and hosted transcription | Roadmap | Roadmap |
+| Native issue generation | Roadmap | Roadmap |
+| Dashboard, search, deduplication, webhooks | Roadmap | Roadmap |
+| SSO, RBAC, audit logs, data residency, SLA | Roadmap | Roadmap |
+
+The repository includes a self-hosted transcription and structured-analysis
+reference API. It is not a hosted service included with the Paid license.
+
+The Paid version uses a compact ECDSA P-256 signed license token. The private key stays
+on the FeedClip licensing server; the SDK receives only the token and public
+verification key.
+
+```ts
+const { token } = await fetch("/api/feedclip/license", {
+  credentials: "include",
+}).then((response) => response.json());
+
+<FeedClip
+  config={{
+    // ...
+    license: {
+      token,
+      publicKey: FEEDCLIP_PUBLIC_KEY,
+      issuer: "https://feedclip.dev",
+      audience: "@feedclip/sdk",
+      projectId: "project_123",
+    },
+    onLicenseError: (reason) => {
+      console.error("FeedClip license rejected:", reason);
+    },
+  }}
+/>;
+```
+
+The SDK verifies:
+
+- token format and `ES256` algorithm;
+- ECDSA signature;
+- issuer and audience;
+- project binding;
+- issue and expiry timestamps;
+- plan and optional feature overrides.
+
+Invalid, expired, or mismatched tokens fall back to the Free plan.
+
+### Issuing licenses
+
+Generate an ECDSA key pair:
+
+```bash
+npm run license:keys
+```
+
+Store the generated private JWK in a server-side secret manager. The public JWK
+may be embedded in the client application.
+
+Issue a project-bound license:
+
+```bash
+export FEEDCLIP_PRIVATE_KEY_JWK='{"kty":"EC",...}'
+
+npm run license:issue -- \
+  --project project_123 \
+  --plan paid \
+  --issuer https://feedclip.dev \
+  --audience @feedclip/sdk \
+  --days 365
+```
+
+Optional feature overrides are signed into the token for development and
+future product rollout:
+
+```bash
+npm run license:issue -- \
+  --project project_123 \
+  --plan paid \
+  --features '{"screenRecording":true}'
+```
+
+An override does not provide an implementation that is not present in the
+installed SDK.
+
+License verification protects the official SDK feature path from accidental or
+unauthorized activation. Because the Free SDK source is MIT-licensed, it is not
+DRM. Paid backend APIs, quotas, storage, AI processing, and connectors must
+always enforce the same plan server-side.
+
+## Upload Helpers
+
+Supabase and S3 helpers perform real browser uploads.
+
+### Supabase Storage
+
+```ts
+import { createSupabaseUploader } from "@feedclip/sdk";
+
+const license = await verifyFeedClipLicense({
+  token,
+  publicKey: FEEDCLIP_PUBLIC_KEY,
+  issuer: "https://feedclip.dev",
+  audience: "@feedclip/sdk",
+  projectId: "project_123",
+});
+
+const onUpload = createSupabaseUploader({
+  url: "https://project.supabase.co",
+  apiKey: supabaseAnonKey,
+  bucket: "feedback",
+  folder: "recordings",
+  license,
+});
+```
+
+### S3 Pre-signed URL
+
+```ts
+import { createS3Uploader } from "@feedclip/sdk";
+
+const onUpload = createS3Uploader({
+  presignedUrl,
+  license,
+});
+```
+
+Do not embed privileged Supabase service keys or AWS credentials in browser
+code. Use restricted public credentials or server-generated pre-signed URLs.
+
+## Localization
+
+Supported locale tags:
+
+| Tag | Language |
+|---|---|
+| `en-US` | English |
+| `ru-RU` | Russian |
+| `es-ES` | Spanish |
+| `fr-FR` | French |
+| `de-DE` | German |
+| `it-IT` | Italian |
+| `pt-PT` | Portuguese |
+| `zh-CN` | Simplified Chinese |
+| `ja-JP` | Japanese |
+| `ko-KR` | Korean |
+
+The original recording controls are translated for every listed locale.
+The new feedback description fields currently use English fallback outside
+`en-US` and `ru-RU`.
+
+## Public Exports
+
+```ts
+import FeedClip, {
+  buildFeedbackAnalysisPrompt,
+  collectBrowserContext,
+  createFeedbackEndpointTransport,
+  createFeedbackId,
+  createIndexedDbFeedbackStore,
+  getPlanEntitlements,
+  isFeatureAllowed,
+  createS3Uploader,
+  createSupabaseUploader,
+  verifyFeedClipLicense,
+} from "@feedclip/sdk";
+
+import type {
+  BrowserContext,
+  Configuration,
+  FeedbackAnalysis,
+  FeedbackKind,
+  FeedbackPriority,
+  FeedbackReceipt,
+  FeedbackSubmission,
+  FeedClipEntitlements,
+  FeedClipFeature,
+  FeedClipLicenseClaims,
+  FeedClipLicenseConfig,
+  FeedClipLicenseGrant,
+  FeedClipPlan,
+  GeneratedIssue,
+} from "@feedclip/sdk";
+
+import FeedClipVue from "@feedclip/sdk/vue";
+import { FeedClipAngularComponent } from "@feedclip/sdk/angular";
+```
+
+## Development
+
+```bash
+yarn install
+yarn dev
+yarn lint
+yarn test
+yarn build
+```
+
+The production build outputs:
+
+```text
+dist/feedclip.js
+dist/feedclip.cjs
+dist/vue.js
+dist/vue.cjs
+dist/angular.js
+dist/angular.cjs
+dist/feedclip.css
+dist/types/
+```
+
+## Roadmap
+
+- hosted multi-tenant ingestion API;
+- secure direct uploads and resumable large-file support;
+- production transcription pipeline;
+- native GitHub, Linear, and Jira connectors;
+- semantic deduplication and feedback clustering;
+- dashboard, search, status tracking, and release linkage;
+- console and network error capture with privacy controls;
+- configurable retention, redaction, consent, and data residency;
+- webhooks and processing-status polling.
+
+## Licensing
+
+The current `@feedclip/sdk` repository and npm package are licensed under
+MIT, including commercial use.
+
+The Paid FeedClip distribution and hosted services use commercial terms. See
+[COMMERCIAL-LICENSE.md](./COMMERCIAL-LICENSE.md).