nostr-comments 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# Nostr Comments
+
+A web comment component based on the Nostr network, implementing the [NIP-22](https://github.com/nostr-protocol/nips/blob/master/22.md) protocol (Web part), using the `I` tag to identify URLs.
+
+## Features
+
+- **NIP-22 Protocol**: Uses kind:1111 events, supports comments and replies
+- **Multiple Login Methods**:
+  - NIP-07 browser extensions (Alby, nos2x, etc.)
+  - NIP-46 Bunker remote signing
+  - Temporary account (locally generated key pair)
+- **Multilingual**: 20 languages built-in (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt, ru, ar, it, nl, pl, tr, vi, th, id, hi, uk), supports custom translations
+- **Profile Links**: Click avatar or username to view profile on [Jumble](https://jumble.social)
+- **Themes**: Light, dark, auto (follows system), easy customization with a few CSS variables
+- **Transparent Background**: No default background, blends into any host page
+- **Headless Mode**: Disable default styles for fully custom UI
+
+## Installation
+
+```bash
+npm install nostr-comments
+```
+
+## Quick Start
+
+### React/Preact Usage
+
+```tsx
+import { NostrComments } from "nostr-comments";
+import "nostr-comments/style.css";
+
+function App() {
+  return <NostrComments url="https://example.com/blog/my-post" locale="en" />;
+}
+```
+
+### CDN Usage
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/nostr-comments/dist/nostr-comments.css"
+/>
+<script src="https://cdn.jsdelivr.net/npm/nostr-comments/dist/nostr-comments.umd.js"></script>
+
+<div id="comments"></div>
+
+<script>
+  NostrComments.render("#comments", {
+    url: "https://example.com/blog/my-post",
+    locale: "en",
+  });
+</script>
+```
+
+## API
+
+### NostrComments Component Props
+
+| Prop                 | Type                                | Default            | Description                                          |
+| -------------------- | ----------------------------------- | ------------------ | ---------------------------------------------------- |
+| `url`                | `string`                            | **Required**       | Web page URL, used to identify comment scope         |
+| `authorPubkeys`      | `string[]`                          | -                  | List of article author public keys for notifications |
+| `relays`             | `string[]`                          | Default relay list | List of Nostr relay addresses                        |
+| `pageSize`           | `number`                            | `50`               | Number of comments per page                          |
+| `locale`             | `string`                            | Auto-detect        | Interface language (20 languages supported)          |
+| `translations`       | `Partial<Translations>`             | -                  | Custom translation text                              |
+| `theme`              | `'light' \| 'dark' \| 'auto'`       | `'auto'`           | Theme mode                                           |
+| `headless`           | `boolean`                           | `false`            | Enable Headless mode                                 |
+| `classNames`         | `object`                            | -                  | Custom CSS class names                               |
+| `enabledSigners`     | `('nip07' \| 'bunker' \| 'temp')[]` | All enabled        | Enabled login methods                                |
+| `onCommentPublished` | `(event: NostrEvent) => void`       | -                  | Callback when comment is published                   |
+| `onError`            | `(error: Error) => void`            | -                  | Error callback                                       |
+
+### classNames Object
+
+```ts
+{
+  root?: string       // Root container
+  list?: string       // Comment list
+  item?: string       // Comment item
+  editor?: string     // Editor
+  loginModal?: string // Login modal
+}
+```
+
+## Examples
+
+### Custom Relays
+
+```tsx
+<NostrComments
+  url="https://example.com/post/123"
+  relays={["wss://relay.damus.io", "wss://relay.nostr.band", "wss://nos.lol"]}
+/>
+```
+
+### Dark Theme
+
+```tsx
+<NostrComments url="https://example.com/post/123" theme="dark" />
+```
+
+### Custom Translations
+
+```tsx
+<NostrComments
+  url="https://example.com/post/123"
+  locale="en"
+  translations={{
+    comments: "Discussion",
+    writeComment: "Share your thoughts...",
+    publish: "Post",
+    noComments: "Start the conversation!",
+    keyCompatibility: "This key works with any Nostr app!",
+  }}
+/>
+```
+
+### Extension Login Only
+
+```tsx
+<NostrComments url="https://example.com/post/123" enabledSigners={["nip07"]} />
+```
+
+### Headless Mode
+
+```tsx
+<NostrComments
+  url="https://example.com/post/123"
+  headless={true}
+  classNames={{
+    root: "my-comments",
+    list: "my-comments-list",
+    editor: "my-editor",
+  }}
+/>
+```
+
+## CSS Variables
+
+The component uses CSS variables for theme customization. Only a few base colors need to be set — all secondary, hover, border, and muted colors are **automatically derived** via `color-mix()`.
+
+### Base Colors (override these to customize)
+
+```css
+.nostr-comments {
+  --nc-bg: #ffffff; /* Background for inputs, modals */
+  --nc-text: #1f2937; /* Primary text color */
+  --nc-primary: #2563eb; /* Accent/brand color */
+  --nc-error: #dc2626; /* Error states */
+  --nc-success: #16a34a; /* Success states */
+}
+```
+
+All other color variables (`--nc-bg-secondary`, `--nc-bg-hover`, `--nc-border`, `--nc-text-secondary`, `--nc-text-muted`, `--nc-primary-hover`, `--nc-primary-light`, `--nc-error-light`, `--nc-success-light`) are derived automatically from the base colors.
+
+### Custom Theme Example
+
+```css
+/* A custom purple theme — works for both light and dark */
+.nostr-comments {
+  --nc-bg: #1a1a2e;
+  --nc-text: #eaeaea;
+  --nc-primary: #e94560;
+}
+```
+
+For dark mode, override the base colors under `[data-theme="dark"]` or `[data-theme="auto"]` with `prefers-color-scheme: dark`. The derived colors will adjust automatically.
+
+### Other Variables
+
+```css
+.nostr-comments {
+  /* Spacing */
+  --nc-space-xs: 4px;
+  --nc-space-sm: 8px;
+  --nc-space-md: 12px;
+  --nc-space-lg: 16px;
+  --nc-space-xl: 24px;
+
+  /* Border Radius */
+  --nc-radius-sm: 8px;
+  --nc-radius-md: 12px;
+  --nc-radius-lg: 16px;
+  --nc-radius-xl: 24px;
+
+  /* Avatar Border Radius */
+  --nc-avatar-radius: 50%;
+}
+```
+
+## Advanced Usage
+
+### Using Standalone Hooks
+
+```tsx
+import { useComments, useSigner } from "nostr-comments";
+
+function CustomComments({ url }) {
+  const { comments, loading, addEvent } = useComments({ url });
+  const { signer, loginWithNip07 } = useSigner();
+
+  // Custom UI...
+}
+```
+
+### Using Service Functions
+
+```tsx
+import { publishComment, subscribeComments } from "nostr-comments";
+
+// Publish a comment
+const event = await publishComment(signer, relays, {
+  url: "https://example.com/post",
+  content: "Great post!",
+});
+
+// Subscribe to comments
+const unsubscribe = subscribeComments({
+  url: "https://example.com/post",
+  relays,
+  onEvent: (event) => console.log("New comment:", event),
+});
+```
+
+### Custom Signers
+
+```tsx
+import { Nip07Signer, TempSigner, BunkerSigner } from "nostr-comments";
+
+// NIP-07 extension
+const nip07 = new Nip07Signer();
+const pubkey = await nip07.getPublicKey();
+
+// Temporary account
+const temp = new TempSigner();
+const nsec = temp.getNsec(); // Export private key
+temp.downloadKeyFile(); // Download key file
+
+// Bunker
+const bunker = BunkerSigner.create("bunker://pubkey?relay=wss://...");
+await bunker.connect();
+```
+
+## NIP-22 Event Format
+
+### Top-level Comment
+
+```json
+{
+  "kind": 1111,
+  "content": "Nice article!",
+  "tags": [
+    ["I", "https://example.com/post/123"],
+    ["K", "web"],
+    ["i", "https://example.com/post/123"],
+    ["k", "web"]
+  ]
+}
+```
+
+### Reply Comment
+
+```json
+{
+  "kind": 1111,
+  "content": "I agree!",
+  "tags": [
+    ["I", "https://example.com/post/123"],
+    ["K", "web"],
+    ["e", "<parent_event_id>", "<relay_hint>", "<parent_pubkey>"],
+    ["k", "1111"],
+    ["p", "<parent_pubkey>"]
+  ]
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/NostrComments.d.ts

@@ -0,0 +1,2 @@
+import type { NostrCommentsProps } from "./types";
+export declare function NostrComments({ locale, translations, theme, headless, ...props }: NostrCommentsProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Avatar.d.ts

@@ -0,0 +1,7 @@
+interface AvatarProps {
+    pubkey: string;
+    size?: number;
+    className?: string;
+}
+export declare function Avatar({ pubkey, size, className }: AvatarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/CommentEditor.d.ts

@@ -0,0 +1,14 @@
+import type { NostrEvent } from "nostr-tools";
+interface CommentEditorProps {
+    url: string;
+    relays?: string[];
+    authorPubkeys?: string[];
+    parentEvent?: NostrEvent | null;
+    onClearParent?: () => void;
+    onPublished?: (event: NostrEvent) => void;
+    onLoginRequired: () => void;
+    onError?: (error: Error) => void;
+    className?: string;
+}
+export declare function CommentEditor({ url, relays, authorPubkeys, parentEvent, onClearParent, onPublished, onLoginRequired, onError, className, }: CommentEditorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/CommentItem.d.ts

@@ -0,0 +1,14 @@
+import type { NostrEvent } from "nostr-tools";
+import type { Comment } from "../types";
+interface CommentItemProps {
+    comment: Comment;
+    relays?: string[];
+    onReply: (event: NostrEvent) => void;
+    onLoginRequired: () => void;
+    currentPubkey?: string;
+    className?: string;
+    /** Whether this is a child comment (second level) */
+    isChild?: boolean;
+}
+export declare function CommentItem({ comment, relays, onReply, onLoginRequired, currentPubkey, className, isChild, }: CommentItemProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/CommentList.d.ts

@@ -0,0 +1,18 @@
+import type { NostrEvent } from "nostr-tools";
+import type { Comment } from "../types";
+interface CommentListProps {
+    comments: Comment[];
+    loading: boolean;
+    loadingMore: boolean;
+    hasMore: boolean;
+    error: string | null;
+    relays?: string[];
+    onReply: (event: NostrEvent) => void;
+    onLoginRequired: () => void;
+    onLoadMore: () => void;
+    onRetry: () => void;
+    currentPubkey?: string;
+    className?: string;
+}
+export declare function CommentList({ comments, loading, loadingMore, hasMore, error, relays, onReply, onLoginRequired, onLoadMore, onRetry, currentPubkey, className, }: CommentListProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/LoginModal/BunkerLogin.d.ts

@@ -0,0 +1,5 @@
+interface BunkerLoginProps {
+    onSuccess: () => void;
+}
+export declare function BunkerLogin({ onSuccess }: BunkerLoginProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/LoginModal/Nip07Login.d.ts

@@ -0,0 +1,5 @@
+interface Nip07LoginProps {
+    onSuccess: () => void;
+}
+export declare function Nip07Login({ onSuccess }: Nip07LoginProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/LoginModal/index.d.ts

@@ -0,0 +1,9 @@
+import type { SignerType } from '../../signers/types';
+interface LoginModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    enabledSigners?: SignerType[];
+    className?: string;
+}
+export declare function LoginModal({ isOpen, onClose, enabledSigners, className }: LoginModalProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/Username.d.ts

@@ -0,0 +1,6 @@
+interface UsernameProps {
+    pubkey: string;
+    className?: string;
+}
+export declare function Username({ pubkey, className }: UsernameProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export { Avatar } from "./Avatar";
+export { Username } from "./Username";
+export { CommentItem } from "./CommentItem";
+export { CommentList } from "./CommentList";
+export { CommentEditor } from "./CommentEditor";
+export { LoginModal } from "./LoginModal";

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { useSigner, isLoggedIn } from "./useSigner";
+export { useComments } from "./useComments";
+export type { UseCommentsOptions } from "./useComments";
+export { useProfile } from "./useProfile";

package/dist/hooks/useComments.d.ts

@@ -0,0 +1,20 @@
+import type { NostrEvent } from "nostr-tools";
+import type { Comment } from "../types";
+export interface UseCommentsOptions {
+    url: string;
+    authors?: string[];
+    relays?: string[];
+    pageSize?: number;
+}
+export declare function useComments(options: UseCommentsOptions): {
+    comments: Comment[];
+    commentCount: number;
+    events: NostrEvent[];
+    loading: boolean;
+    loadingMore: boolean;
+    error: string | null;
+    hasMore: boolean;
+    reload: () => Promise<() => void>;
+    loadMore: () => Promise<void>;
+    addEvent: (event: NostrEvent) => void;
+};

package/dist/hooks/useProfile.d.ts

@@ -0,0 +1,4 @@
+import { NostrUser } from "@nostr/gadgets/metadata";
+export declare function useProfile(pubkey: string): {
+    profile: NostrUser;
+};

package/dist/hooks/useSigner.d.ts

@@ -0,0 +1,18 @@
+import { TempSigner } from "../signers";
+import type { Signer, SignerInfo } from "../signers/types";
+export declare function isLoggedIn(): boolean;
+export declare function useSigner(): {
+    signer: Signer | null;
+    signerInfo: SignerInfo | null;
+    loading: boolean;
+    error: string | null;
+    isLoggedIn: boolean;
+    loginWithNip07: () => Promise<void>;
+    loginWithTemp: () => Promise<void>;
+    loginWithNsec: (nsec: string) => Promise<void>;
+    loginWithBunker: (bunkerUrl: string) => Promise<void>;
+    logout: () => void;
+    clearError: () => void;
+    getTempSigner: () => TempSigner | null;
+    isNip07Available: boolean;
+};

package/dist/i18n/index.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from "react";
+import type { Translations } from "../types";
+import { en } from "./locales/en";
+import { zhCN } from "./locales/zh-CN";
+import { zhTW } from "./locales/zh-TW";
+import { ja } from "./locales/ja";
+import { ko } from "./locales/ko";
+import { es } from "./locales/es";
+import { fr } from "./locales/fr";
+import { de } from "./locales/de";
+import { pt } from "./locales/pt";
+import { ru } from "./locales/ru";
+import { ar } from "./locales/ar";
+import { it } from "./locales/it";
+import { nl } from "./locales/nl";
+import { pl } from "./locales/pl";
+import { tr } from "./locales/tr";
+import { vi } from "./locales/vi";
+import { th } from "./locales/th";
+import { id } from "./locales/id";
+import { hi } from "./locales/hi";
+import { uk } from "./locales/uk";
+interface I18nContextValue {
+    locale: string;
+    translations: Translations;
+    t: (key: keyof Translations) => string;
+}
+interface I18nProviderProps {
+    locale?: string;
+    translations?: Partial<Translations>;
+    children: ReactNode;
+}
+export declare function I18nProvider({ locale, translations: customTranslations, children, }: I18nProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useI18n(): I18nContextValue;
+export { en, zhCN as zhCN, zhTW, ja, ko, es, fr, de, pt, ru, ar, it, nl, pl, tr, vi, th, id, hi, uk, };

package/dist/i18n/locales/ar.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const ar: Translations;

package/dist/i18n/locales/de.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const de: Translations;

package/dist/i18n/locales/en.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const en: Translations;

package/dist/i18n/locales/es.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const es: Translations;

package/dist/i18n/locales/fr.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const fr: Translations;

package/dist/i18n/locales/hi.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const hi: Translations;

package/dist/i18n/locales/id.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const id: Translations;

package/dist/i18n/locales/it.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const it: Translations;

package/dist/i18n/locales/ja.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const ja: Translations;

package/dist/i18n/locales/ko.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const ko: Translations;

package/dist/i18n/locales/nl.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const nl: Translations;

package/dist/i18n/locales/pl.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const pl: Translations;

package/dist/i18n/locales/pt.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const pt: Translations;

package/dist/i18n/locales/ru.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const ru: Translations;

package/dist/i18n/locales/th.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const th: Translations;

package/dist/i18n/locales/tr.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const tr: Translations;

package/dist/i18n/locales/uk.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const uk: Translations;

package/dist/i18n/locales/vi.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const vi: Translations;

package/dist/i18n/locales/zh-CN.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const zhCN: Translations;

package/dist/i18n/locales/zh-TW.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from "../../types";
+export declare const zhTW: Translations;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { NostrComments } from "./NostrComments";
+export type { NostrCommentsProps, Comment, Profile, Translations, } from "./types";
+export { Nip07Signer, TempSigner, BunkerSigner } from "./signers";
+export type { Signer, SignerType, SignerInfo } from "./signers";
+export { useSigner, useComments, useProfile, isLoggedIn } from "./hooks";
+export type { UseCommentsOptions } from "./hooks";
+export { Avatar, Username, CommentItem, CommentList, CommentEditor, LoginModal, } from "./components";
+export { getDefaultRelays, queryEvents, subscribeEvents, publishEvent, } from "./services/nostr";
+export { subscribeComments, fetchComments, publishComment, publishReply, buildCommentTree, } from "./services/comment";
+export { subscribeReactions, fetchReactions, publishReaction, countLikes, hasLiked, buildReactionEvent, } from "./services/reaction";
+export { buildWebComment, buildReplyComment, isReply, getParentId, getRootUrl, } from "./utils/nip22";
+export { getColorFromPubkey, generateAvatarSvg, getAvatarDataUrl, } from "./utils/avatar";
+export { I18nProvider, useI18n, en, zhCN } from "./i18n";
+import "./styles/base.css";