@withaevum/react-hooks

React hooks and utilities for working with the Aevum API. This package provides reusable logic for fetching, managing, and manipulating offerings data, eliminating code duplication across applications.

Installation

npm install @withaevum/react-hooks
# or
yarn add @withaevum/react-hooks
# or
pnpm add @withaevum/react-hooks

Peer Dependencies

• react >= 18.0.0
• @withaevum/sdk >= 1.0.0

Usage

Utilities

Format Currency

import { formatCurrency } from '@withaevum/react-hooks';

const price = formatCurrency(15000); // "$150.00"
const free = formatCurrency(null); // "Free"

Format Duration

import { formatDuration } from '@withaevum/react-hooks';

const duration = formatDuration(60); // "60 min"
const allDay = formatDuration(null, true); // "All day"
const hours = formatDuration(120); // "2h"

Get First Session Date

import { getFirstSessionDate } from '@withaevum/react-hooks';

const firstSession = getFirstSessionDate(offering);
if (firstSession) {
  console.log('First session:', firstSession.toISOString());
}

Search, Sort, and Paginate

import { searchOfferings, sortOfferings, paginateOfferings } from '@withaevum/react-hooks';

// Search
const filtered = searchOfferings(offerings, 'therapy session');

// Sort
const sorted = sortOfferings(offerings, 'price_cents', true); // ascending

// Paginate
const paginated = paginateOfferings(offerings, 1, 20);
// Returns: { items: Offering[], total: number, totalPages: number, page: number, pageSize: number }

Hooks

useOfferings

Fetch offerings from the Aevum API.

import { useOfferings } from '@withaevum/react-hooks';
import { AevumClient } from '@withaevum/sdk';

const client = new AevumClient({ apiKey: 'your-api-key' });

function MyComponent() {
  const { offerings, loading, error, refetch } = useOfferings({
    client,
    eventId: 'optional-event-id',
    providerId: 'optional-provider-id',
    enabled: true, // optional, defaults to true
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {offerings.map(offering => (
        <div key={offering.id}>{offering.name}</div>
      ))}
    </div>
  );
}

useOfferingActions

Perform CRUD operations on offerings.

import { useOfferingActions } from '@withaevum/react-hooks';
import { AevumClient } from '@withaevum/sdk';

const client = new AevumClient({ apiKey: 'your-api-key' });

function MyComponent() {
  const { create, update, delete: deleteOffering, isMutating, error } = useOfferingActions(client);

  const handleCreate = async () => {
    try {
      const offering = await create({
        name: 'New Offering',
        price_cents: 15000,
        duration_minutes: 60,
      });
      console.log('Created:', offering);
    } catch (err) {
      console.error('Failed to create:', err);
    }
  };

  return (
    <button onClick={handleCreate} disabled={isMutating}>
      {isMutating ? 'Creating...' : 'Create Offering'}
    </button>
  );
}

useOfferingForm

Manage form state for creating/editing offerings.

import { useOfferingForm } from '@withaevum/react-hooks';

function OfferingForm({ initialData }) {
  const { formData, setField, reset, validate } = useOfferingForm(initialData);

  const handleSubmit = () => {
    const validation = validate();
    if (!validation.valid) {
      console.error('Validation errors:', validation.errors);
      return;
    }
    // Submit form...
  };

  return (
    <form>
      <input
        value={formData.name}
        onChange={(e) => setField('name', e.target.value)}
      />
      {/* Other fields... */}
    </form>
  );
}

useOfferingsTable

Complete table functionality hook - combines data fetching, filtering, sorting, pagination, and CRUD operations.

import { useOfferingsTable } from '@withaevum/react-hooks';
import { AevumClient } from '@withaevum/sdk';

const client = new AevumClient({ apiKey: 'your-api-key' });

function OfferingsTable() {
  const {
    // Data
    rows,
    totalCount,
    totalPages,
    
    // State
    loading,
    error,
    
    // Controls
    search,
    setSearch,
    sortKey,
    setSortKey,
    sortAsc,
    setSortAsc,
    page,
    setPage,
    
    // Utilities
    formatCurrency,
    formatDuration,
    getFirstSessionDate,
    
    // Actions
    refetch,
    create,
    update,
    delete: deleteOffering,
  } = useOfferingsTable({
    client,
    initialSearch: '',
    initialSort: { key: 'name', ascending: true },
    pageSize: 20,
  });

  return (
    <div>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search..."
      />
      <table>
        {rows.map(offering => (
          <tr key={offering.id}>
            <td>{offering.name}</td>
            <td>{formatCurrency(offering.price_cents)}</td>
            <td>{formatDuration(offering.duration_minutes, offering.is_all_day)}</td>
          </tr>
        ))}
      </table>
    </div>
  );
}

Migration Guide

From Duplicated Code

If you have duplicated utility functions or data fetching logic, migrate to this package:

Before:

// Your component
const formatCurrency = (cents) => {
  if (!cents) return 'Free';
  return new Intl.NumberFormat(undefined, {
    style: 'currency',
    currency: 'USD',
  }).format(cents / 100);
};

const getFirstSessionDate = (offering) => {
  // 50+ lines of calculation logic...
};

After:

import { formatCurrency, getFirstSessionDate } from '@withaevum/react-hooks';

// Use directly - no need to define them yourself
const price = formatCurrency(offering.price_cents);
const firstSession = getFirstSessionDate(offering);

From Custom Data Fetching

Before:

const [offerings, setOfferings] = useState([]);
const [loading, setLoading] = useState(true);

useEffect(() => {
  fetch('/api/offerings')
    .then(res => res.json())
    .then(data => {
      setOfferings(data);
      setLoading(false);
    });
}, []);

After:

import { useOfferings } from '@withaevum/react-hooks';

const { offerings, loading, error, refetch } = useOfferings({
  client: aevumClient,
});

API Reference

Utilities

• formatCurrency(cents: number | null, options?: FormatOptions): string
• formatDuration(minutes: number | null, isAllDay?: boolean): string
• getFirstSessionDate(offering: Offering): Date | null
• searchOfferings(offerings: Offering[], query: string): Offering[]
• sortOfferings(offerings: Offering[], key: SortKey, ascending: boolean): Offering[]
• paginateOfferings(offerings: Offering[], page: number, pageSize: number): PaginatedResult<Offering>

Hooks

• useOfferings(options: UseOfferingsOptions): UseOfferingsResult
• useOfferingActions(client: AevumClient): UseOfferingActionsResult
• useOfferingForm(initialData?: Offering): UseOfferingFormResult
• useOfferingsTable(options: UseOfferingsTableOptions): UseOfferingsTableResult

TypeScript Support

This package is written in TypeScript and includes full type definitions. All types are exported and can be imported:

import type {
  Offering,
  CreateOfferingParams,
  UpdateOfferingParams,
  SortKey,
  PaginatedResult,
  OfferingFormData,
} from '@withaevum/react-hooks';

License

ISC