@shipnoted/react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @shipnoted/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.
+Headless React hooks for [Shipnoted](https://shipnoted.com): a changelog, a feedback board, a subscribe form and release reactions in your own components. You write the markup; this holds the data and the logic.
+
+```sh
+npm i @shipnoted/react
+```
+
+```tsx
+import { ShipnotedProvider, useChangelog, useFeedback } from "@shipnoted/react"
+
+function Page() {
+  const { releases, hasMore, loadMore, unread, markSeen } = useChangelog({ limit: 10 })
+  const { items, vote, hasVoted, submit } = useFeedback({ status: "open", sort: "top" })
+  // render however you like
+}
+
+<ShipnotedProvider project="your-slug"><Page /></ShipnotedProvider>
+```
+
+- **No API key.** It uses the open API the widget uses: public reads, and visitors voting, posting and subscribing, all rate limited.
+- **Optimistic votes** that are put back if the server refuses them.
+- **Server rendering:** fetch the first page on the server and pass it as `initialData`: no loading state on first paint.
+- **Signed-in customers:** pass `userToken` (a short JWT your backend signs) and votes count as that verified customer, with plan and revenue.
+- **Framework-free core:** `@shipnoted/react/core` exports the same logic as plain stores (`getSnapshot`, `subscribe`) for Vue, Svelte and scripts.
+
+Hooks: `useChangelog`, `useFeedback`, `useSubscribe`, `useReactions`, `useProjectConfig`. Full guide: https://shipnoted.com/docs/react
+
+Prefer ready-made UI? The shadcn components (`npx shadcn@latest add https://shipnoted.com/r/whats-new.json`) are built on the same API.
+
+MIT licensed.

package/dist/core/changelog.d.ts

@@ -0,0 +1,25 @@
+import type { PublicClient, Release } from "./client.js";
+export type ChangelogState = {
+    releases: Release[];
+    loading: boolean;
+    loadingMore: boolean;
+    error: string | null;
+    hasMore: boolean;
+    seen: number;
+};
+export type ChangelogOptions = {
+    limit?: number;
+    lang?: string;
+    initialData?: Release[];
+};
+/** The changelog as plain state and actions. Pages of `limit` releases; "unread" is releases newer than the last one this browser marked as seen. */
+export declare function createChangelog(client: PublicClient, opts?: ChangelogOptions): {
+    refresh: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    markSeen: () => void;
+    unread: (s?: ChangelogState) => number;
+    getSnapshot: () => ChangelogState;
+    subscribe: (fn: () => void) => () => void;
+    set: (patch: Partial<ChangelogState> | ((s: ChangelogState) => Partial<ChangelogState>)) => void;
+};
+export type Changelog = ReturnType<typeof createChangelog>;

package/dist/core/changelog.js

@@ -0,0 +1,56 @@
+import { createStore } from "./store.js";
+/** The changelog as plain state and actions. Pages of `limit` releases; "unread" is releases newer than the last one this browser marked as seen. */
+export function createChangelog(client, opts = {}) {
+    const limit = Math.min(30, Math.max(1, opts.limit ?? 10));
+    const seenKey = `shipnoted:${client.project}:seen`;
+    const readSeen = () => {
+        try {
+            return Number(client.storage?.getItem(seenKey) ?? 0) || 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const store = createStore({ releases: opts.initialData ?? [], loading: !opts.initialData, loadingMore: false, error: null, hasMore: (opts.initialData?.length ?? 0) >= limit, seen: 0 });
+    let run = 0;
+    async function refresh() {
+        const my = ++run;
+        store.set({ loading: true, error: null, seen: readSeen() });
+        try {
+            const d = await client.releases({ limit, lang: opts.lang });
+            if (my === run)
+                store.set({ releases: d.releases, hasMore: d.releases.length >= limit, loading: false });
+        }
+        catch (e) {
+            if (my === run)
+                store.set({ loading: false, error: e instanceof Error ? e.message : "Could not load the changelog." });
+        }
+    }
+    async function loadMore() {
+        const s = store.getSnapshot();
+        const last = s.releases[s.releases.length - 1];
+        if (!last || !s.hasMore || s.loadingMore)
+            return;
+        store.set({ loadingMore: true });
+        try {
+            const d = await client.releases({ limit, lang: opts.lang, before: last.publishedAt });
+            const have = new Set(store.getSnapshot().releases.map((r) => r.id));
+            store.set((c) => ({ releases: [...c.releases, ...d.releases.filter((r) => !have.has(r.id))], hasMore: d.releases.length >= limit, loadingMore: false }));
+        }
+        catch (e) {
+            store.set({ loadingMore: false, error: e instanceof Error ? e.message : "Could not load more." });
+        }
+    }
+    function markSeen() {
+        const newest = store.getSnapshot().releases[0]?.publishedAt;
+        if (!newest)
+            return;
+        try {
+            client.storage?.setItem(seenKey, String(newest));
+        }
+        catch { }
+        store.set({ seen: newest });
+    }
+    const unread = (s = store.getSnapshot()) => s.releases.filter((r) => r.publishedAt > s.seen).length;
+    return { ...store, refresh, loadMore, markSeen, unread };
+}

package/dist/core/client.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The public API of one project: the same endpoints the widget uses. Nothing here needs an API key. With a `userToken` (a short JWT your own backend signs
+ * for the signed-in person) votes and ideas count as that verified customer; a token that has gone bad is dropped and the call is retried anonymously.
+ */
+export type Release = {
+    id: string;
+    slug: string;
+    title: string;
+    version: string;
+    tags: string[];
+    publishedAt: number;
+    summary: string;
+    body: string;
+    url: string;
+    lang: string;
+    asked: string[];
+    announce: boolean;
+    targeted: boolean;
+};
+export type RequestStatus = "open" | "planned" | "progress" | "shipped" | "declined";
+export type FeedbackItem = {
+    id: string;
+    title: string;
+    body: string;
+    status: RequestStatus | string;
+    category: string;
+    votes: number;
+    comments: number;
+    createdAt: number;
+    author: string;
+    verified?: boolean;
+};
+export type SimilarItem = {
+    id: string;
+    title: string;
+    votes: number;
+    status: string;
+};
+export type ProjectConfig = {
+    name: string;
+    slug: string;
+    accent: string;
+    onAccent: string;
+    dark: boolean;
+    vars: Record<string, string>;
+    feedback: boolean;
+    roadmap: boolean;
+    badge: boolean;
+};
+export type ClientOptions = {
+    project: string;
+    /** Where Shipnoted lives. Default https://shipnoted.com, or your custom domain's origin. */
+    baseUrl?: string;
+    userToken?: string | (() => string | undefined);
+    fetch?: typeof fetch;
+    /** Where the anonymous voter id and "seen" marks are kept. Default: localStorage when there is one. */
+    storage?: Pick<Storage, "getItem" | "setItem"> | null;
+};
+export declare class ShipnotedApiError extends Error {
+    status: number;
+    code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+export declare function createPublicClient(opts: ClientOptions): {
+    project: string;
+    voterId: () => string;
+    storage: Pick<Storage, "getItem" | "setItem"> | null;
+    config: () => Promise<{
+        ok: true;
+    } & ProjectConfig>;
+    releases: (o?: {
+        limit?: number;
+        before?: number;
+        lang?: string;
+    }) => Promise<{
+        ok: true;
+        releases: Release[];
+    }>;
+    feedback: () => Promise<{
+        ok: true;
+        items: FeedbackItem[];
+    }>;
+    voted: () => Promise<{
+        ok: true;
+        ids: string[];
+        identified: boolean;
+    }>;
+    similar: (text: string) => Promise<{
+        ok: true;
+        items: SimilarItem[];
+    }>;
+    vote: (id: string) => Promise<{
+        ok: true;
+        voted: boolean;
+        votes: number;
+    }>;
+    submit: (input: {
+        title: string;
+        body?: string;
+        email?: string;
+        name?: string;
+        category?: string;
+    }) => Promise<{
+        ok: true;
+        feedback: FeedbackItem;
+    }>;
+    subscribe: (email: string, categories?: string[]) => Promise<{
+        ok: true;
+        already?: boolean;
+    }>;
+    reactions: (ids: string[]) => Promise<{
+        ok: true;
+        counts: Record<string, Record<string, number>>;
+        mine: Record<string, string[]>;
+    }>;
+    react: (release: string, emoji: string) => Promise<{
+        ok: true;
+        on: boolean;
+        counts: Record<string, number>;
+    }>;
+};
+export type PublicClient = ReturnType<typeof createPublicClient>;

package/dist/core/client.js

@@ -0,0 +1,76 @@
+export class ShipnotedApiError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.name = "ShipnotedApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+const VOTER = /^[A-Za-z0-9_-]{12,64}$/;
+const fresh = () => {
+    const c = globalThis.crypto;
+    return (c?.randomUUID ? c.randomUUID() + c.randomUUID() : Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2) + Date.now().toString(36)).replace(/-/g, "").slice(0, 32);
+};
+export function createPublicClient(opts) {
+    const base = `${(opts.baseUrl ?? "https://shipnoted.com").replace(/\/$/, "")}/api/public/${encodeURIComponent(opts.project)}`;
+    const f = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const storage = opts.storage === undefined ? (typeof localStorage === "undefined" ? null : localStorage) : opts.storage;
+    let memoryVoter = "";
+    let tokenDropped = false;
+    const token = () => {
+        if (tokenDropped)
+            return "";
+        return (typeof opts.userToken === "function" ? opts.userToken() : opts.userToken) ?? "";
+    };
+    /** This browser's anonymous id: made once and kept, so a visitor is one voter across visits. */
+    function voterId() {
+        if (!storage)
+            return (memoryVoter || (memoryVoter = fresh()));
+        try {
+            let v = storage.getItem("sn_voter") ?? "";
+            if (!VOTER.test(v)) {
+                v = fresh();
+                storage.setItem("sn_voter", v);
+            }
+            return v;
+        }
+        catch {
+            return (memoryVoter || (memoryVoter = fresh()));
+        }
+    }
+    async function request(method, path, body, withToken = true) {
+        const t = withToken ? token() : "";
+        const url = `${base}${path}${method === "GET" && t ? `${path.includes("?") ? "&" : "?"}token=${encodeURIComponent(t)}` : ""}`;
+        const res = await f(url, { method, headers: body ? { "content-type": "application/json" } : undefined, body: body ? JSON.stringify(t ? { ...body, token: t } : body) : undefined });
+        const data = (await res.json().catch(() => ({})));
+        if (res.status === 401 && data.code === "bad_token" && t) {
+            tokenDropped = true;
+            return request(method, path, body, false);
+        }
+        if (!res.ok || data.ok === false)
+            throw new ShipnotedApiError(data.error ?? "Something went wrong.", res.status, data.code);
+        return data;
+    }
+    const q = (o) => {
+        const p = new URLSearchParams();
+        for (const [k, v] of Object.entries(o))
+            if (v !== undefined && v !== "")
+                p.set(k, String(v));
+        return p.size ? `?${p}` : "";
+    };
+    return {
+        project: opts.project,
+        voterId,
+        storage,
+        config: () => request("GET", "/config"),
+        releases: (o = {}) => request("GET", `/releases${q(o)}`),
+        feedback: () => request("GET", "/feedback-list"),
+        voted: () => request("GET", `/votes${q({ voter: voterId() })}`),
+        similar: (text) => request("GET", `/similar${q({ q: text.slice(0, 200) })}`),
+        vote: (id) => request("POST", "/vote", { id, voter: voterId() }),
+        submit: (input) => request("POST", "/feedback", { ...input, voter: voterId() }),
+        subscribe: (email, categories = []) => request("POST", "/subscribe", { email, categories }),
+        reactions: (ids) => request("GET", `/react${q({ ids: ids.join(","), voter: voterId() })}`),
+        react: (release, emoji) => request("POST", "/react", { release, emoji, voter: voterId() }),
+    };
+}

package/dist/core/feedback.d.ts

@@ -0,0 +1,34 @@
+import type { FeedbackItem, PublicClient, SimilarItem } from "./client.js";
+export type FeedbackState = {
+    items: FeedbackItem[];
+    voted: string[];
+    loading: boolean;
+    submitting: boolean;
+    error: string | null;
+};
+export type FeedbackFilter = {
+    sort?: "top" | "new";
+    status?: string;
+    q?: string;
+};
+/** The board as plain state and actions. Votes show at once and are put back if the server says no. */
+export declare function createFeedback(client: PublicClient, opts?: {
+    initialData?: FeedbackItem[];
+}): {
+    refresh: () => Promise<void>;
+    vote: (id: string) => Promise<boolean>;
+    submit: (input: {
+        title: string;
+        body?: string;
+        email?: string;
+        name?: string;
+        category?: string;
+    }) => Promise<FeedbackItem | null>;
+    similar: (text: string) => Promise<SimilarItem[]>;
+    getSnapshot: () => FeedbackState;
+    subscribe: (fn: () => void) => () => void;
+    set: (patch: Partial<FeedbackState> | ((s: FeedbackState) => Partial<FeedbackState>)) => void;
+};
+export type Feedback = ReturnType<typeof createFeedback>;
+/** Filter and order the loaded items. Search matches words in the title and body, case-insensitively. */
+export declare function visibleItems(items: FeedbackItem[], f?: FeedbackFilter): FeedbackItem[];

package/dist/core/feedback.js

@@ -0,0 +1,52 @@
+import { createStore } from "./store.js";
+/** The board as plain state and actions. Votes show at once and are put back if the server says no. */
+export function createFeedback(client, opts = {}) {
+    const store = createStore({ items: opts.initialData ?? [], voted: [], loading: !opts.initialData, submitting: false, error: null });
+    async function refresh() {
+        store.set({ loading: true, error: null });
+        try {
+            const [list, voted] = await Promise.all([client.feedback(), client.voted().catch(() => ({ ids: [] }))]);
+            store.set({ items: list.items, voted: voted.ids, loading: false });
+        }
+        catch (e) {
+            store.set({ loading: false, error: e instanceof Error ? e.message : "Could not load the board." });
+        }
+    }
+    /** Toggle your vote. Resolves to whether it is now on. */
+    async function vote(id) {
+        const was = store.getSnapshot().voted.includes(id);
+        const apply = (on, delta) => store.set((s) => ({ voted: on ? [...new Set([...s.voted, id])] : s.voted.filter((x) => x !== id), items: s.items.map((i) => (i.id === id ? { ...i, votes: Math.max(0, i.votes + delta) } : i)) }));
+        apply(!was, was ? -1 : 1);
+        try {
+            const r = await client.vote(id);
+            store.set((s) => ({ voted: r.voted ? [...new Set([...s.voted, id])] : s.voted.filter((x) => x !== id), items: s.items.map((i) => (i.id === id ? { ...i, votes: r.votes } : i)) }));
+            return r.voted;
+        }
+        catch (e) {
+            apply(was, was ? 1 : -1);
+            store.set({ error: e instanceof Error ? e.message : "Could not record that vote." });
+            return was;
+        }
+    }
+    async function submit(input) {
+        store.set({ submitting: true, error: null });
+        try {
+            const r = await client.submit(input);
+            store.set((s) => ({ items: [r.feedback, ...s.items], voted: [...new Set([...s.voted, r.feedback.id])], submitting: false }));
+            return r.feedback;
+        }
+        catch (e) {
+            store.set({ submitting: false, error: e instanceof Error ? e.message : "Could not post that." });
+            return null;
+        }
+    }
+    /** Requests that already say this, to show while someone types an idea. */
+    const similar = async (text) => (text.trim().length < 6 ? [] : (await client.similar(text).catch(() => ({ items: [] }))).items);
+    return { ...store, refresh, vote, submit, similar };
+}
+/** Filter and order the loaded items. Search matches words in the title and body, case-insensitively. */
+export function visibleItems(items, f = {}) {
+    const words = (f.q ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+    const list = items.filter((i) => (!f.status || f.status === "all" || i.status === f.status) && words.every((w) => `${i.title} ${i.body}`.toLowerCase().includes(w)));
+    return list.sort(f.sort === "new" ? (a, b) => b.createdAt - a.createdAt : (a, b) => b.votes - a.votes || b.createdAt - a.createdAt);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client.js";
+export * from "./store.js";
+export * from "./changelog.js";
+export * from "./feedback.js";

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export * from "./client.js";
+export * from "./store.js";
+export * from "./changelog.js";
+export * from "./feedback.js";

package/dist/core/store.d.ts

@@ -0,0 +1,7 @@
+/** A tiny observable value: the shape `useSyncExternalStore` wants, and just as usable from Vue, Svelte or plain scripts. */
+export type Store<S> = {
+    getSnapshot: () => S;
+    subscribe: (fn: () => void) => () => void;
+    set: (patch: Partial<S> | ((s: S) => Partial<S>)) => void;
+};
+export declare function createStore<S extends object>(initial: S): Store<S>;

package/dist/core/store.js

@@ -0,0 +1,17 @@
+export function createStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    return {
+        getSnapshot: () => state,
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+        set(patch) {
+            const next = typeof patch === "function" ? patch(state) : patch;
+            state = { ...state, ...next };
+            for (const l of [...listeners])
+                l();
+        },
+    };
+}

package/dist/hooks.d.ts

@@ -0,0 +1,62 @@
+import { type ChangelogOptions, type ClientOptions, type FeedbackFilter, type FeedbackItem, type ProjectConfig, type Release } from "./core/index.js";
+type Common = Partial<Pick<ClientOptions, "project" | "baseUrl" | "userToken">>;
+/**
+ * The changelog, headless. You render it; this holds the data.
+ *
+ *   const { releases, loading, hasMore, loadMore, unread, markSeen } = useChangelog({ limit: 10 })
+ *
+ * `initialData` lets a server component fetch the first page, so there is no loading state on first paint.
+ */
+export declare function useChangelog(opts?: ChangelogOptions & Common): {
+    unread: number;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+    markSeen: () => void;
+    releases: Release[];
+    loading: boolean;
+    loadingMore: boolean;
+    error: string | null;
+    hasMore: boolean;
+    seen: number;
+};
+/**
+ * The feedback board, headless: the list, which ones you voted for, voting and posting. Votes are optimistic.
+ *
+ *   const { items, voted, vote, submit, similar } = useFeedback({ sort: "top", status: "open" })
+ */
+export declare function useFeedback(opts?: FeedbackFilter & Common & {
+    initialData?: FeedbackItem[];
+}): {
+    items: FeedbackItem[];
+    vote: (id: string) => Promise<boolean>;
+    submit: (input: {
+        title: string;
+        body?: string;
+        email?: string;
+        name?: string;
+        category?: string;
+    }) => Promise<FeedbackItem | null>;
+    similar: (text: string) => Promise<import("./index.js").SimilarItem[]>;
+    refresh: () => Promise<void>;
+    hasVoted: (id: string) => boolean;
+    voted: string[];
+    loading: boolean;
+    submitting: boolean;
+    error: string | null;
+};
+/** An email box: `subscribe(email, ["fixed"])` starts the double opt-in; nobody is emailed until they confirm. */
+export declare function useSubscribe(opts?: Common): {
+    subscribe: (email: string, categories?: string[]) => Promise<boolean>;
+    status: "error" | "idle" | "busy" | "sent" | "already";
+    error: string | null;
+    busy: boolean;
+};
+/** Reactions under a release: counts, which ones are yours, and toggling. */
+export declare function useReactions(release: Pick<Release, "id">, opts?: Common): {
+    counts: Record<string, number>;
+    mine: string[];
+    toggle: (emoji: string) => Promise<void>;
+};
+/** The project's look (accent, theme variables) and switches, to style your own UI to match. */
+export declare function useProjectConfig(opts?: Common): ProjectConfig | null;
+export {};

package/dist/hooks.js

@@ -0,0 +1,90 @@
+"use client";
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { createChangelog, createFeedback, visibleItems } from "./core/index.js";
+import { useClient } from "./provider.js";
+/**
+ * The changelog, headless. You render it; this holds the data.
+ *
+ *   const { releases, loading, hasMore, loadMore, unread, markSeen } = useChangelog({ limit: 10 })
+ *
+ * `initialData` lets a server component fetch the first page, so there is no loading state on first paint.
+ */
+export function useChangelog(opts = {}) {
+    const client = useClient(opts);
+    const { limit, lang, initialData } = opts;
+    const log = useMemo(() => createChangelog(client, { limit, lang, initialData }), [client, limit, lang, initialData]);
+    const state = useSyncExternalStore(log.subscribe, log.getSnapshot, log.getSnapshot);
+    useEffect(() => {
+        if (!initialData)
+            void log.refresh();
+        else
+            log.set({ seen: Number(client.storage?.getItem(`shipnoted:${client.project}:seen`) ?? 0) || 0 });
+    }, [log, initialData, client]);
+    return { ...state, unread: log.unread(state), loadMore: log.loadMore, refresh: log.refresh, markSeen: log.markSeen };
+}
+/**
+ * The feedback board, headless: the list, which ones you voted for, voting and posting. Votes are optimistic.
+ *
+ *   const { items, voted, vote, submit, similar } = useFeedback({ sort: "top", status: "open" })
+ */
+export function useFeedback(opts = {}) {
+    const client = useClient(opts);
+    const { initialData, sort, status, q } = opts;
+    const board = useMemo(() => createFeedback(client, { initialData }), [client, initialData]);
+    const state = useSyncExternalStore(board.subscribe, board.getSnapshot, board.getSnapshot);
+    useEffect(() => { void board.refresh(); }, [board]);
+    const items = useMemo(() => visibleItems(state.items, { sort, status, q }), [state.items, sort, status, q]);
+    return { ...state, items, vote: board.vote, submit: board.submit, similar: board.similar, refresh: board.refresh, hasVoted: (id) => state.voted.includes(id) };
+}
+/** An email box: `subscribe(email, ["fixed"])` starts the double opt-in; nobody is emailed until they confirm. */
+export function useSubscribe(opts = {}) {
+    const client = useClient(opts);
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    const subscribe = useCallback(async (email, categories = []) => {
+        setStatus("busy");
+        setError(null);
+        try {
+            const r = await client.subscribe(email, categories);
+            setStatus(r.already ? "already" : "sent");
+            return true;
+        }
+        catch (e) {
+            setStatus("error");
+            setError(e instanceof Error ? e.message : "Could not subscribe.");
+            return false;
+        }
+    }, [client]);
+    return { subscribe, status, error, busy: status === "busy" };
+}
+/** Reactions under a release: counts, which ones are yours, and toggling. */
+export function useReactions(release, opts = {}) {
+    const client = useClient(opts);
+    const [counts, setCounts] = useState({});
+    const [mine, setMine] = useState([]);
+    useEffect(() => {
+        let live = true;
+        client.reactions([release.id]).then((d) => { if (live) {
+            setCounts(d.counts[release.id] ?? {});
+            setMine(d.mine[release.id] ?? []);
+        } }).catch(() => { });
+        return () => { live = false; };
+    }, [client, release.id]);
+    const toggle = useCallback(async (emoji) => {
+        const r = await client.react(release.id, emoji);
+        setCounts(r.counts);
+        setMine((m) => (r.on ? [...new Set([...m, emoji])] : m.filter((x) => x !== emoji)));
+    }, [client, release.id]);
+    return { counts, mine, toggle };
+}
+/** The project's look (accent, theme variables) and switches, to style your own UI to match. */
+export function useProjectConfig(opts = {}) {
+    const client = useClient(opts);
+    const [config, setConfig] = useState(null);
+    useEffect(() => {
+        let live = true;
+        client.config().then((c) => live && setConfig(c)).catch(() => { });
+        return () => { live = false; };
+    }, [client]);
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ShipnotedProvider, useClient } from "./provider.js";
+export { useChangelog, useFeedback, useSubscribe, useReactions, useProjectConfig } from "./hooks.js";
+export { createPublicClient, createChangelog, createFeedback, createStore, visibleItems, ShipnotedApiError } from "./core/index.js";
+export type { Release, FeedbackItem, SimilarItem, RequestStatus, ProjectConfig, ClientOptions, PublicClient, ChangelogState, ChangelogOptions, FeedbackState, FeedbackFilter } from "./core/index.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ShipnotedProvider, useClient } from "./provider.js";
+export { useChangelog, useFeedback, useSubscribe, useReactions, useProjectConfig } from "./hooks.js";
+export { createPublicClient, createChangelog, createFeedback, createStore, visibleItems, ShipnotedApiError } from "./core/index.js";

package/dist/provider.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+import { type ClientOptions, type PublicClient } from "./core/index.js";
+/** Tell every hook below which project (and, optionally, which signed-in customer) it is for. Hooks also work without it if you pass `project` to each. */
+export declare function ShipnotedProvider({ children, ...options }: ClientOptions & {
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function useClient(options?: Partial<ClientOptions>): PublicClient;

package/dist/provider.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { createPublicClient } from "./core/index.js";
+const Ctx = createContext(null);
+/** Tell every hook below which project (and, optionally, which signed-in customer) it is for. Hooks also work without it if you pass `project` to each. */
+export function ShipnotedProvider({ children, ...options }) {
+    const { project, baseUrl, fetch: f, storage } = options;
+    const userToken = options.userToken;
+    // The client is rebuilt only when the project, address or token function changes, not on every render.
+    const client = useMemo(() => createPublicClient({ project, baseUrl, userToken, fetch: f, storage }), [project, baseUrl, userToken, f, storage]);
+    return _jsx(Ctx.Provider, { value: client, children: children });
+}
+export function useClient(options) {
+    const ctx = useContext(Ctx);
+    const own = options?.project;
+    const baseUrl = options?.baseUrl;
+    const userToken = options?.userToken;
+    const client = useMemo(() => (own ? createPublicClient({ ...options, project: own, baseUrl, userToken }) : null), [own, baseUrl, userToken]); // eslint-disable-line react-hooks/exhaustive-deps
+    const found = client ?? ctx;
+    if (!found)
+        throw new Error("Wrap your app in <ShipnotedProvider project=\"your-slug\"> or pass { project } to the hook.");
+    return found;
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@shipnoted/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Headless React hooks for Shipnoted: a changelog, a feedback board and a subscribe form in your own components. Framework-free core included.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./core": { "types": "./dist/core/index.d.ts", "default": "./dist/core/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "rm -rf dist && tsc -p tsconfig.json" },
+  "peerDependencies": { "react": ">=18" },
+  "devDependencies": { "typescript": "^5", "@types/react": "^19" },
+  "keywords": ["changelog", "feedback", "roadmap", "react", "hooks", "headless", "shipnoted"],
+  "repository": { "type": "git", "url": "git+https://github.com/vamsiy78/shipnoted.git", "directory": "react" },
+  "homepage": "https://shipnoted.com/docs/react"
+}