@dismissible/react-client 1.0.0-canary.4.a9fb4a5 → 1.0.0

package/README.md

@@ -1,37 +1,26 @@
-<p align="center">
-  <a href="https://dismissible.io" target="_blank"><img src="https://raw.githubusercontent.com/DismissibleIo/dismissible-api/main/docs/images/dismissible_logo.png" width="240" alt="Dismissible" /></a>
-</p>
-
-<p align="center">Never Show The Same Thing Twice!</p>
-<p align="center">
-    <a href="https://www.npmjs.com/package/@dismissible/react-client" target="_blank"><img src="https://img.shields.io/npm/v/@dismissible/react-client.svg" alt="NPM Version" /></a>
-    <a href="https://github.com/dismissibleio/dismissible-react-client/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/npm/l/@dismissible/react-client.svg" alt="Package License" /></a>
-    <a href="https://www.npmjs.com/package/@dismissible/react-client" target="_blank"><img src="https://img.shields.io/npm/dm/@dismissible/react-client.svg" alt="NPM Downloads" /></a>
-    <a href="https://github.com/dismissibleio/dismissible-react-client" target="_blank"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/dismissibleio/dismissible-react-client/publish.yml" /></a>
-    <a href="https://paypal.me/joshstuartx" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" /></a>
-</p>
-
-Dismissible manages the state of your UI elements across sessions, so your users see what matters, once! No more onboarding messages reappearing on every tab, no more notifications haunting users across devices. Dismissible syncs dismissal state everywhere, so every message is intentional, never repetitive.
-
 # @dismissible/react-client
 
-This is the React component library for creating dismissible UI elements with persistent state management.
+A React component library for creating dismissible UI elements with persistent state management.
 
-This component is used with the [Dismissible API Server](https://github.com/DismissibleIo/dismissible-api), which you can self-host with Docker or integrate into your NestJS application.
+**Free and open source** - use with the [Dismissible API Server](https://github.com/DismissibleIo/dismissible-api) that you can self-host with Docker or integrate into your NestJS application.
 
-**[dismissible.io](https://dismissible.io)** | **[Documentation](https://dismissible.io/docs)** | **[API Server](https://github.com/DismissibleIo/dismissible-api)**
+🌐 **[dismissible.io](https://dismissible.io)** | 📖 **[Documentation](https://dismissible.io/docs)** | 🐙 **[API Server](https://github.com/DismissibleIo/dismissible-api)**
+
+[![npm version](https://badge.fury.io/js/@dismissible%2Freact-client.svg)](https://badge.fury.io/js/@dismissible%2Freact-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **Easy to use** - Simple component API for dismissible content
-- **Persistent state** - Dismissal state is saved and restored across sessions when using the [Dismissible API Server](https://github.com/DismissibleIo/dismissible-api)
-- **Restore support** - Restore previously dismissed items programmatically
-- **JWT Authentication** - Built-in support for secure JWT-based authentication
-- **Customizable** - Custom loading, error, and dismiss button components
-- **Accessible** - Built with accessibility best practices
-- **Hook-based** - Includes `useDismissibleItem` hook for custom implementations
-- **Lightweight** - Minimal bundle size with tree-shaking support
-- **TypeScript** - Full TypeScript support with complete type definitions
+- 🎯 **Easy to use** - Simple component API for dismissible content
+- 💾 **Persistent state** - Dismissal state is saved and restored across sessions
+- 🔄 **Restore support** - Restore previously dismissed items programmatically
+- 🔐 **JWT Authentication** - Built-in support for secure JWT-based authentication
+- 🎨 **Customizable** - Custom loading, error, and dismiss button components
+- ♿ **Accessible** - Built with accessibility best practices
+- 🪝 **Hook-based** - Includes `useDismissibleItem` hook for custom implementations
+- 📦 **Lightweight** - Minimal bundle size with tree-shaking support
+- 🔧 **TypeScript** - Full TypeScript support with complete type definitions
+- 🐳 **Self-hosted** - Works with your own Dismissible API server
 
 ## Installation
 
@@ -51,7 +40,7 @@ npm install react react-dom
 
 ### 1. Set up the Dismissible API Server
 
-First, you need a [Dismissible API Server](https://github.com/DismissibleIo/dismissible-api). The easiest way is with Docker:
+First, you need a Dismissible API server running. The easiest way is with Docker:
 
 ```yaml
 # docker-compose.yml
@@ -63,29 +52,38 @@ services:
       - '3001:3001'
     environment:
       DISMISSIBLE_PORT: 3001
-```
+      DISMISSIBLE_POSTGRES_STORAGE_CONNECTION_STRING: postgresql://postgres:postgres@db:5432/dismissible
+    depends_on:
+      - db
 
-```bash
-docker-compose up -d
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: dismissible
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
 ```
 
-OR
-
 ```bash
-docker run -p 3001:3001 -e DISMISSIBLE_PORT=3001 dismissibleio/dismissible-api:latest
+docker-compose up -d
 ```
 
-See the [API Server documentation](https://github.com/DismissibleIo/dismissible-api) for more deployment options including NestJS integration, public Docker image and more.
+See the [API Server documentation](https://github.com/DismissibleIo/dismissible-api) for more deployment options including NestJS integration.
 
 ### 2. Configure the Provider
 
-Wrap your app with `DismissibleProvider`. The `userId` prop is **required** to track all your dismissals per user:
+Wrap your app with `DismissibleProvider`. The `userId` prop is **required** to track dismissals per user:
 
 ```tsx
 import { DismissibleProvider } from '@dismissible/react-client';
 
 function App() {
-  const userId = getCurrentUserId();
+  const userId = getCurrentUserId(); // Get from your auth system
   
   return (
     <DismissibleProvider userId={userId} baseUrl="http://localhost:3001">
@@ -96,7 +94,6 @@ function App() {
 ```
 
 ### 3. Use Dismissible Components
-Now wrap any component you want to be dismissible with the `<Dismissible>` component, and the `itemId`, along with the `userId`, will become the unique key that is tracked across sessions and devices.
 
 ```tsx
 import { Dismissible } from '@dismissible/react-client';
@@ -245,11 +242,11 @@ For custom implementations and advanced use cases.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `dismissedAt` | `string \| undefined` | ISO date string when item was dismissed, or undefined |
+| `dismissedOn` | `string \| null` | ISO date string when item was dismissed, or null |
 | `dismiss` | `() => Promise<void>` | Function to dismiss the item |
 | `restore` | `() => Promise<void>` | Function to restore a dismissed item |
 | `isLoading` | `boolean` | Loading state indicator |
-| `error` | `Error \| undefined` | Error state, if any |
+| `error` | `Error \| null` | Error state, if any |
 | `item` | `IDismissibleItem \| undefined` | The full dismissible item object |
 
 #### Example
@@ -258,7 +255,7 @@ For custom implementations and advanced use cases.
 import { useDismissibleItem } from '@dismissible/react-client';
 
 function CustomDismissible({ itemId, children }) {
-  const { dismissedAt, dismiss, restore, isLoading, error } = useDismissibleItem(itemId);
+  const { dismissedOn, dismiss, restore, isLoading, error } = useDismissibleItem(itemId);
 
   if (isLoading) {
     return <div>Loading...</div>;
@@ -268,7 +265,7 @@ function CustomDismissible({ itemId, children }) {
     return <div>Error: {error.message}</div>;
   }
 
-  if (dismissedAt) {
+  if (dismissedOn) {
     return (
       <div>
         <p>This item was dismissed.</p>
@@ -341,6 +338,7 @@ function App() {
 function Dashboard() {
   return (
     <div>
+      {/* Dismissible state is tracked per user */}
       <Dismissible itemId="user-welcome-banner">
         <div className="alert alert-info">
           <h4>Welcome back!</h4>
@@ -429,19 +427,19 @@ function Dashboard() {
     <div>
       <Dismissible itemId="feature-announcement">
         <div className="alert alert-success">
-          New feature: Dark mode is now available!
+          🎉 New feature: Dark mode is now available!
         </div>
       </Dismissible>
 
       <Dismissible itemId="maintenance-notice">
         <div className="alert alert-warning">
-          Scheduled maintenance: Sunday 2AM-4AM EST
+          ⚠️ Scheduled maintenance: Sunday 2AM-4AM EST
         </div>
       </Dismissible>
 
       <Dismissible itemId="survey-request">
         <div className="alert alert-info">
-          Help us improve! Take our 2-minute survey.
+          📝 Help us improve! Take our 2-minute survey.
         </div>
       </Dismissible>
     </div>
@@ -470,6 +468,74 @@ function RobustBanner() {
 }
 ```
 
+### Integration with Auth Providers
+
+```tsx
+import { DismissibleProvider } from '@dismissible/react-client';
+
+// With Firebase Auth
+function AppWithFirebase() {
+  const user = firebase.auth().currentUser;
+  
+  return (
+    <DismissibleProvider 
+      userId={user.uid}
+      jwt={async () => {
+        if (user) {
+          return await user.getIdToken();
+        }
+        throw new Error('User not authenticated');
+      }}
+      baseUrl="https://api.yourapp.com"
+    >
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+
+// With Auth0
+function AppWithAuth0() {
+  const { user, getAccessTokenSilently } = useAuth0();
+  
+  return (
+    <DismissibleProvider 
+      userId={user.sub}
+      jwt={async () => await getAccessTokenSilently()}
+      baseUrl="https://api.yourapp.com"
+    >
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+
+// With token refresh logic
+function AppWithTokenRefresh() {
+  const { user } = useAuth();
+  
+  return (
+    <DismissibleProvider 
+      userId={user.id}
+      jwt={async () => {
+        try {
+          const response = await fetch('/api/auth/refresh', {
+            method: 'POST',
+            credentials: 'include'
+          });
+          const { accessToken } = await response.json();
+          return accessToken;
+        } catch (error) {
+          console.error('Failed to refresh token:', error);
+          throw error;
+        }
+      }}
+      baseUrl="https://api.yourapp.com"
+    >
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+```
+
 ### Using the Hook for Complex Logic
 
 ```tsx
@@ -477,12 +543,12 @@ import { useDismissibleItem } from '@dismissible/react-client';
 import { useState, useEffect } from 'react';
 
 function SmartNotification({ itemId, message, type = 'info' }) {
-  const { dismissedAt, dismiss, isLoading } = useDismissibleItem(itemId);
+  const { dismissedOn, dismiss, isLoading } = useDismissibleItem(itemId);
   const [autoHide, setAutoHide] = useState(false);
 
   // Auto-hide after 10 seconds for info messages
   useEffect(() => {
-    if (type === 'info' && !dismissedAt) {
+    if (type === 'info' && !dismissedOn) {
       const timer = setTimeout(() => {
         setAutoHide(true);
         dismiss();
@@ -490,9 +556,9 @@ function SmartNotification({ itemId, message, type = 'info' }) {
       
       return () => clearTimeout(timer);
     }
-  }, [type, dismissedAt, dismiss]);
+  }, [type, dismissedOn, dismiss]);
 
-  if (dismissedAt || autoHide) {
+  if (dismissedOn || autoHide) {
     return null;
   }
 
@@ -519,12 +585,12 @@ Use the `restore` function to bring back previously dismissed content:
 import { useDismissibleItem } from '@dismissible/react-client';
 
 function RestorableBanner({ itemId }) {
-  const { dismissedAt, dismiss, restore, isLoading } = useDismissibleItem(itemId);
+  const { dismissedOn, dismiss, restore, isLoading } = useDismissibleItem(itemId);
 
-  if (dismissedAt) {
+  if (dismissedOn) {
     return (
       <div className="dismissed-placeholder">
-        <p>Banner was dismissed on {new Date(dismissedAt).toLocaleDateString()}</p>
+        <p>Banner was dismissed on {new Date(dismissedOn).toLocaleDateString()}</p>
         <button onClick={restore} disabled={isLoading}>
           {isLoading ? 'Restoring...' : 'Show Banner Again'}
         </button>
@@ -544,6 +610,51 @@ function RestorableBanner({ itemId }) {
 }
 ```
 
+### Admin Panel with Restore Capability
+
+```tsx
+import { useDismissibleItem } from '@dismissible/react-client';
+
+function AdminNotificationManager({ notificationId }) {
+  const { dismissedOn, dismiss, restore, item, isLoading, error } = 
+    useDismissibleItem(notificationId);
+
+  if (error) {
+    return <div className="error">Error: {error.message}</div>;
+  }
+
+  return (
+    <div className="admin-panel">
+      <h4>Notification: {notificationId}</h4>
+      <p>Status: {dismissedOn ? 'Dismissed' : 'Active'}</p>
+      {dismissedOn && (
+        <p>Dismissed at: {new Date(dismissedOn).toLocaleString()}</p>
+      )}
+      
+      <div className="actions">
+        {dismissedOn ? (
+          <button 
+            onClick={restore} 
+            disabled={isLoading}
+            className="btn-restore"
+          >
+            Restore
+          </button>
+        ) : (
+          <button 
+            onClick={dismiss} 
+            disabled={isLoading}
+            className="btn-dismiss"
+          >
+            Dismiss
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
 ## Styling
 
 The library includes minimal default styles. You can override them or provide your own:
@@ -567,6 +678,35 @@ The library includes minimal default styles. You can override them or provide yo
 }
 ```
 
+## TypeScript Support
+
+The library is written in TypeScript and exports all type definitions:
+
+```tsx
+import type {
+  DismissibleProps,
+  DismissibleProviderProps,
+  JwtToken,
+} from '@dismissible/react-client';
+
+// Custom provider wrapper
+const AuthenticatedDismissibleProvider: React.FC<{
+  children: React.ReactNode;
+}> = ({ children }) => {
+  const { user, getToken } = useAuth();
+  
+  return (
+    <DismissibleProvider 
+      userId={user.id} 
+      jwt={getToken}
+      baseUrl={process.env.DISMISSIBLE_API_URL}
+    >
+      {children}
+    </DismissibleProvider>
+  );
+};
+```
+
 ## Self-Hosting
 
 Dismissible is designed to be self-hosted. You have full control over your data.
@@ -593,9 +733,9 @@ See the [NestJS documentation](https://dismissible.io/docs/nestjs) for setup ins
 
 ## Support
 
-- [Documentation](https://dismissible.io/docs)
-- [GitHub - React Client](https://github.com/DismissibleIo/dismissible-react-client)
-- [GitHub - API Server](https://github.com/DismissibleIo/dismissible-api)
+- 📖 [Documentation](https://dismissible.io/docs)
+- 🐙 [GitHub - React Client](https://github.com/DismissibleIo/dismissible-react-client)
+- 🐙 [GitHub - API Server](https://github.com/DismissibleIo/dismissible-api)
 
 ## License
 

package/dist/config/api.config.d.ts

@@ -1,7 +1,21 @@
+/**
+ * API configuration settings
+ */
+/**
+ * Configuration interface for API settings
+ */
 export interface ApiConfig {
     /** Base URL for API requests */
     baseUrl: string;
 }
+/**
+ * Returns the API configuration based on the current environment
+ * @returns The API configuration object
+ */
 export declare const getConfig: () => ApiConfig;
+/**
+ * Gets the API base URL
+ * @returns The base URL for API requests
+ */
 export declare const getBaseUrl: () => string;
 export default getConfig;