@fewchurs/react 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,41 @@
+Fewchurs SDK License
+
+Copyright (c) 2026 Fewchurs. All rights reserved.
+
+This software and its source code (the "SDK") are proprietary to Fewchurs.
+The source code is published for transparency only. It is not open source.
+
+1. Permitted use. You may install the SDK, unmodified, as an npm
+   dependency of your own applications, and deploy it as part of those
+   applications, including in the bundles they serve to browsers, solely to
+   connect them to the Fewchurs service under a valid Fewchurs account. You
+   may customise its look and text through the props, CSS variables, slots,
+   hooks and stylesheet overrides the SDK documents.
+
+2. Restrictions. Except as allowed in section 1, you may not:
+   a. copy, modify, translate or create derivative works of the SDK;
+   b. distribute, sublicense, sell, rent or lease the SDK on its own or as
+      part of a library, SDK, framework or developer tool;
+   c. use the SDK, or any part of it, to build or run a product or service
+      that competes with Fewchurs, or to connect to any service other than
+      Fewchurs;
+   d. remove or alter any copyright or license notice in the SDK.
+
+3. Ownership. Fewchurs keeps all rights, title and interest in the SDK. No
+   rights are granted except those stated in this license.
+
+4. Termination. This license ends automatically if you breach it, or when
+   your Fewchurs account ends. On termination you must stop deploying new
+   versions of your applications that include the SDK.
+
+5. No warranty. THE SDK 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.
+
+6. Limitation of liability. IN NO EVENT SHALL FEWCHURS 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 SDK OR THE USE
+   OF OR OTHER DEALINGS IN THE SDK.
+
+Your use of the Fewchurs service itself is governed separately by your
+agreement with Fewchurs (https://www.fewchurs.com).

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @fewchurs/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.
+A Fewchurs feature-request board for any React app — the client, the store, the hooks and the
+components. See the [repository README](../../README.md) for the full guide.
+
+```bash
+pnpm add @fewchurs/react
+```
+
+```tsx
+import { FewchursBoard, FewchursProvider } from "@fewchurs/react";
+import "@fewchurs/react/styles.css";
+
+<FewchursProvider apiKey={import.meta.env.VITE_FEWCHURS_KEY}>
+  <FewchursBoard />
+</FewchursProvider>;
+```
+
+`FewchursBoardDialog` renders the same board in a modal (`open`, `onClose`, plus every board
+prop), and `initialFeatureId` opens the board on one request with its comments expanded.
+
+In a Next.js app, use [`@fewchurs/next`](../next) instead: it renders the board on the server
+and keeps the API key out of the browser.
+
+`@fewchurs/react/core` is the server-safe half — the fetch client, the types, validation and
+error mapping, with no React and no `"use client"` boundary.

package/dist/core.d.mts

@@ -0,0 +1,213 @@
+type FewchursError = {
+    code: "invalid_key";
+    status: 401;
+    message: string;
+} | {
+    code: "validation_failed";
+    status: 400;
+    message: string;
+} | {
+    code: "rate_limited";
+    status: 429;
+    message: string;
+} | {
+    code: "not_found";
+    status: 404;
+    message: string;
+} | {
+    code: "limit_reached";
+    status: 402;
+    message: string;
+} | {
+    code: "server";
+    status: number;
+    message: string;
+} | {
+    code: "network";
+    message: string;
+};
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: FewchursError;
+};
+/** Safe to show a visitor: never leaks a server message that may name internals. */
+declare function userMessage(error: FewchursError): string;
+declare function networkError(message?: string): FewchursError;
+declare function validationError(message: string): FewchursError;
+declare function errorFromResponse(status: number, body: unknown): FewchursError;
+
+/** A status the server does not know about yet still renders, as `"unknown"`. */
+type FeatureStatus = "open" | "planned" | "in_progress" | "done" | "declined" | "unknown";
+type FeatureSort = "top" | "new";
+interface Feature {
+    id: string;
+    title: string;
+    description: string;
+    status: FeatureStatus;
+    upvoteCount: number;
+    commentCount: number;
+    followerCount: number;
+    hasVoted: boolean;
+    isFollowing: boolean;
+    isMine: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Comment {
+    id: string;
+    text: string;
+    authorName: string;
+    isDeveloper: boolean;
+    isMine: boolean;
+    createdAt: string;
+}
+interface FeaturePage {
+    features: Feature[];
+    nextCursor: string | null;
+}
+interface CommentPage {
+    comments: Comment[];
+    nextCursor: string | null;
+}
+interface FewchursConfig {
+    showBranding: boolean;
+    hideVoteCounts: boolean;
+    appName: string | null;
+}
+interface SubmitFeatureInput {
+    title: string;
+    description?: string;
+    email?: string;
+    isSubscriber?: boolean;
+}
+interface CreateCommentInput {
+    featureId: string;
+    text: string;
+    authorName?: string;
+}
+interface ListFeaturesParams {
+    sort?: FeatureSort;
+    limit?: number;
+    cursor?: string | null;
+    status?: FeatureStatus[];
+}
+interface ListCommentsParams {
+    limit?: number;
+    cursor?: string | null;
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface FewchursClientOptions {
+    /** Server-side, or in a SPA where the key is publishable. Omit when calling your own proxy. */
+    apiKey?: string;
+    /** `https://www.fewchurs.com/api/v1` by default, or a proxy path such as `/api/fewchurs`. */
+    baseUrl?: string;
+    deviceId?: string | null | (() => string | null);
+    /** Sent as `Accept-Language`, so server-side copy and emails match the visitor. */
+    language?: string;
+    fetch?: FetchLike;
+    retries?: number;
+    retryDelayMs?: number;
+}
+interface FewchursClient {
+    readonly baseUrl: string;
+    getDeviceId(): string | null;
+    getConfig(signal?: AbortSignal): Promise<Result<FewchursConfig>>;
+    listFeatures(params?: ListFeaturesParams, signal?: AbortSignal): Promise<Result<FeaturePage>>;
+    getFeature(featureId: string, signal?: AbortSignal): Promise<Result<Feature>>;
+    submitFeature(input: SubmitFeatureInput): Promise<Result<Feature>>;
+    vote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    unvote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    follow(featureId: string, email: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    unfollow(featureId: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    listComments(featureId: string, params?: ListCommentsParams, signal?: AbortSignal): Promise<Result<CommentPage>>;
+    createComment(input: CreateCommentInput): Promise<Result<Comment>>;
+}
+declare function createFewchursClient(options?: FewchursClientOptions): FewchursClient;
+
+declare const SDK_VERSION = "1.0.1";
+
+declare const SDK_HEADER = "react/1.0.1";
+declare const DEFAULT_BASE_URL = "https://www.fewchurs.com/api/v1";
+declare const DEFAULT_PAGE_SIZE = 20;
+/** Mirrors the server's zod schemas, so the UI can reject input before a round trip. */
+declare const LIMITS: {
+    readonly titleMin: 3;
+    readonly titleMax: 100;
+    readonly descriptionMax: 1000;
+    readonly commentMin: 1;
+    readonly commentMax: 1000;
+    readonly authorNameMax: 60;
+};
+/** What the Roadmap tab asks for, and what it keeps if the server ignores the filter. */
+declare const ROADMAP_STATUSES: FeatureStatus[];
+
+declare function createDeviceId(): string;
+
+interface ListQuery {
+    sort: FeatureSort;
+    status?: FeatureStatus[];
+}
+declare function listKey({ sort, status }: ListQuery): string;
+/**
+ * One feature, fetched by id, kept in `lists` beside the real lists. That way a deep-linked
+ * request goes through the same vote, comment and follow updates as a row in a list.
+ */
+declare function featureKey(featureId: string): string;
+
+type LoadStatus = "idle" | "loading" | "loadingMore" | "ready" | "error";
+interface ListState {
+    features: Feature[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface CommentsState {
+    comments: Comment[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface StoreState {
+    config: FewchursConfig | null;
+    lists: Record<string, ListState>;
+    comments: Record<string, CommentsState>;
+}
+type FewchursEventName = "boardOpened" | "featureSubmitted" | "voted" | "commented" | "followed" | "error";
+interface FewchursEvent {
+    name: FewchursEventName;
+    featureId?: string;
+    hasVoted?: boolean;
+    following?: boolean;
+    error?: FewchursError;
+}
+
+declare function normalizeStatus(value: unknown): FeatureStatus;
+declare function normalizeFeature(value: unknown, deviceId: string | null): Feature;
+declare function normalizeComment(value: unknown, deviceId: string | null): Comment;
+declare function normalizeFeaturePage(value: unknown, deviceId: string | null): FeaturePage;
+declare function normalizeCommentPage(value: unknown, deviceId: string | null): CommentPage;
+declare function normalizeConfig(value: unknown): FewchursConfig;
+declare function normalizeVote(value: unknown): {
+    upvoteCount: number;
+    hasVoted: boolean;
+};
+
+declare function validateFeatureInput(input: SubmitFeatureInput): FewchursError | null;
+declare function validateCommentInput(input: CreateCommentInput): FewchursError | null;
+declare function validateEmail(email: string): FewchursError | null;
+
+export { type Comment, type CommentPage, type CommentsState, type CreateCommentInput, DEFAULT_BASE_URL, DEFAULT_PAGE_SIZE, type Feature, type FeaturePage, type FeatureSort, type FeatureStatus, type FetchLike, type FewchursClient, type FewchursClientOptions, type FewchursConfig, type FewchursError, type FewchursEvent, type FewchursEventName, LIMITS, type ListCommentsParams, type ListFeaturesParams, type ListQuery, type ListState, type LoadStatus, ROADMAP_STATUSES, type Result, SDK_HEADER, SDK_VERSION, type StoreState, type SubmitFeatureInput, createDeviceId, createFewchursClient, errorFromResponse, featureKey, listKey, networkError, normalizeComment, normalizeCommentPage, normalizeConfig, normalizeFeature, normalizeFeaturePage, normalizeStatus, normalizeVote, userMessage, validateCommentInput, validateEmail, validateFeatureInput, validationError };

package/dist/core.d.ts

@@ -0,0 +1,213 @@
+type FewchursError = {
+    code: "invalid_key";
+    status: 401;
+    message: string;
+} | {
+    code: "validation_failed";
+    status: 400;
+    message: string;
+} | {
+    code: "rate_limited";
+    status: 429;
+    message: string;
+} | {
+    code: "not_found";
+    status: 404;
+    message: string;
+} | {
+    code: "limit_reached";
+    status: 402;
+    message: string;
+} | {
+    code: "server";
+    status: number;
+    message: string;
+} | {
+    code: "network";
+    message: string;
+};
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: FewchursError;
+};
+/** Safe to show a visitor: never leaks a server message that may name internals. */
+declare function userMessage(error: FewchursError): string;
+declare function networkError(message?: string): FewchursError;
+declare function validationError(message: string): FewchursError;
+declare function errorFromResponse(status: number, body: unknown): FewchursError;
+
+/** A status the server does not know about yet still renders, as `"unknown"`. */
+type FeatureStatus = "open" | "planned" | "in_progress" | "done" | "declined" | "unknown";
+type FeatureSort = "top" | "new";
+interface Feature {
+    id: string;
+    title: string;
+    description: string;
+    status: FeatureStatus;
+    upvoteCount: number;
+    commentCount: number;
+    followerCount: number;
+    hasVoted: boolean;
+    isFollowing: boolean;
+    isMine: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Comment {
+    id: string;
+    text: string;
+    authorName: string;
+    isDeveloper: boolean;
+    isMine: boolean;
+    createdAt: string;
+}
+interface FeaturePage {
+    features: Feature[];
+    nextCursor: string | null;
+}
+interface CommentPage {
+    comments: Comment[];
+    nextCursor: string | null;
+}
+interface FewchursConfig {
+    showBranding: boolean;
+    hideVoteCounts: boolean;
+    appName: string | null;
+}
+interface SubmitFeatureInput {
+    title: string;
+    description?: string;
+    email?: string;
+    isSubscriber?: boolean;
+}
+interface CreateCommentInput {
+    featureId: string;
+    text: string;
+    authorName?: string;
+}
+interface ListFeaturesParams {
+    sort?: FeatureSort;
+    limit?: number;
+    cursor?: string | null;
+    status?: FeatureStatus[];
+}
+interface ListCommentsParams {
+    limit?: number;
+    cursor?: string | null;
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface FewchursClientOptions {
+    /** Server-side, or in a SPA where the key is publishable. Omit when calling your own proxy. */
+    apiKey?: string;
+    /** `https://www.fewchurs.com/api/v1` by default, or a proxy path such as `/api/fewchurs`. */
+    baseUrl?: string;
+    deviceId?: string | null | (() => string | null);
+    /** Sent as `Accept-Language`, so server-side copy and emails match the visitor. */
+    language?: string;
+    fetch?: FetchLike;
+    retries?: number;
+    retryDelayMs?: number;
+}
+interface FewchursClient {
+    readonly baseUrl: string;
+    getDeviceId(): string | null;
+    getConfig(signal?: AbortSignal): Promise<Result<FewchursConfig>>;
+    listFeatures(params?: ListFeaturesParams, signal?: AbortSignal): Promise<Result<FeaturePage>>;
+    getFeature(featureId: string, signal?: AbortSignal): Promise<Result<Feature>>;
+    submitFeature(input: SubmitFeatureInput): Promise<Result<Feature>>;
+    vote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    unvote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    follow(featureId: string, email: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    unfollow(featureId: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    listComments(featureId: string, params?: ListCommentsParams, signal?: AbortSignal): Promise<Result<CommentPage>>;
+    createComment(input: CreateCommentInput): Promise<Result<Comment>>;
+}
+declare function createFewchursClient(options?: FewchursClientOptions): FewchursClient;
+
+declare const SDK_VERSION = "1.0.1";
+
+declare const SDK_HEADER = "react/1.0.1";
+declare const DEFAULT_BASE_URL = "https://www.fewchurs.com/api/v1";
+declare const DEFAULT_PAGE_SIZE = 20;
+/** Mirrors the server's zod schemas, so the UI can reject input before a round trip. */
+declare const LIMITS: {
+    readonly titleMin: 3;
+    readonly titleMax: 100;
+    readonly descriptionMax: 1000;
+    readonly commentMin: 1;
+    readonly commentMax: 1000;
+    readonly authorNameMax: 60;
+};
+/** What the Roadmap tab asks for, and what it keeps if the server ignores the filter. */
+declare const ROADMAP_STATUSES: FeatureStatus[];
+
+declare function createDeviceId(): string;
+
+interface ListQuery {
+    sort: FeatureSort;
+    status?: FeatureStatus[];
+}
+declare function listKey({ sort, status }: ListQuery): string;
+/**
+ * One feature, fetched by id, kept in `lists` beside the real lists. That way a deep-linked
+ * request goes through the same vote, comment and follow updates as a row in a list.
+ */
+declare function featureKey(featureId: string): string;
+
+type LoadStatus = "idle" | "loading" | "loadingMore" | "ready" | "error";
+interface ListState {
+    features: Feature[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface CommentsState {
+    comments: Comment[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface StoreState {
+    config: FewchursConfig | null;
+    lists: Record<string, ListState>;
+    comments: Record<string, CommentsState>;
+}
+type FewchursEventName = "boardOpened" | "featureSubmitted" | "voted" | "commented" | "followed" | "error";
+interface FewchursEvent {
+    name: FewchursEventName;
+    featureId?: string;
+    hasVoted?: boolean;
+    following?: boolean;
+    error?: FewchursError;
+}
+
+declare function normalizeStatus(value: unknown): FeatureStatus;
+declare function normalizeFeature(value: unknown, deviceId: string | null): Feature;
+declare function normalizeComment(value: unknown, deviceId: string | null): Comment;
+declare function normalizeFeaturePage(value: unknown, deviceId: string | null): FeaturePage;
+declare function normalizeCommentPage(value: unknown, deviceId: string | null): CommentPage;
+declare function normalizeConfig(value: unknown): FewchursConfig;
+declare function normalizeVote(value: unknown): {
+    upvoteCount: number;
+    hasVoted: boolean;
+};
+
+declare function validateFeatureInput(input: SubmitFeatureInput): FewchursError | null;
+declare function validateCommentInput(input: CreateCommentInput): FewchursError | null;
+declare function validateEmail(email: string): FewchursError | null;
+
+export { type Comment, type CommentPage, type CommentsState, type CreateCommentInput, DEFAULT_BASE_URL, DEFAULT_PAGE_SIZE, type Feature, type FeaturePage, type FeatureSort, type FeatureStatus, type FetchLike, type FewchursClient, type FewchursClientOptions, type FewchursConfig, type FewchursError, type FewchursEvent, type FewchursEventName, LIMITS, type ListCommentsParams, type ListFeaturesParams, type ListQuery, type ListState, type LoadStatus, ROADMAP_STATUSES, type Result, SDK_HEADER, SDK_VERSION, type StoreState, type SubmitFeatureInput, createDeviceId, createFewchursClient, errorFromResponse, featureKey, listKey, networkError, normalizeComment, normalizeCommentPage, normalizeConfig, normalizeFeature, normalizeFeaturePage, normalizeStatus, normalizeVote, userMessage, validateCommentInput, validateEmail, validateFeatureInput, validationError };