@djangocfg/ext-payments 1.0.0

package/src/api/generated/ext_payments/storage.ts

@@ -0,0 +1,161 @@
+/**
+ * Storage adapters for cross-platform token storage.
+ *
+ * Supports:
+ * - LocalStorage (browser)
+ * - Cookies (SSR/browser)
+ * - Memory (Node.js/Electron/testing)
+ */
+
+import type { APILogger } from './logger';
+
+/**
+ * Storage adapter interface for cross-platform token storage.
+ */
+export interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/**
+ * LocalStorage adapter with safe try-catch for browser environments.
+ * Works in modern browsers with localStorage support.
+ * 
+ * Note: This adapter uses window.localStorage and should only be used in browser/client environments.
+ * For server-side usage, use MemoryStorageAdapter or CookieStorageAdapter instead.
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        const value = localStorage.getItem(key);
+        this.logger?.debug(`LocalStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+        return value;
+      }
+      this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+    } catch (error) {
+      this.logger?.error('LocalStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.setItem(key, value);
+        this.logger?.debug(`LocalStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.removeItem(key);
+        this.logger?.debug(`LocalStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * Cookie-based storage adapter for SSR and browser environments.
+ * Useful for Next.js, Nuxt.js, and other SSR frameworks.
+ */
+export class CookieStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof document === 'undefined') {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+        return null;
+      }
+      const value = `; ${document.cookie}`;
+      const parts = value.split(`; ${key}=`);
+      if (parts.length === 2) {
+        const result = parts.pop()?.split(';').shift() || null;
+        this.logger?.debug(`CookieStorage.getItem("${key}"): ${result ? 'found' : 'not found'}`);
+        return result;
+      }
+      this.logger?.debug(`CookieStorage.getItem("${key}"): not found`);
+    } catch (error) {
+      this.logger?.error('CookieStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=${value}; path=/; max-age=31536000`;
+        this.logger?.debug(`CookieStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+        this.logger?.debug(`CookieStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * In-memory storage adapter for Node.js, Electron, and testing environments.
+ * Data is stored in RAM and cleared when process exits.
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private storage: Map<string, string> = new Map();
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    const value = this.storage.get(key) || null;
+    this.logger?.debug(`MemoryStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+    return value;
+  }
+
+  setItem(key: string, value: string): void {
+    this.storage.set(key, value);
+    this.logger?.debug(`MemoryStorage.setItem("${key}"): success`);
+  }
+
+  removeItem(key: string): void {
+    this.storage.delete(key);
+    this.logger?.debug(`MemoryStorage.removeItem("${key}"): success`);
+  }
+}

package/src/api/generated/ext_payments/validation-events.ts

@@ -0,0 +1,133 @@
+/**
+ * Zod Validation Events - Browser CustomEvent integration
+ *
+ * Dispatches browser CustomEvents when Zod validation fails, allowing
+ * React/frontend apps to listen and handle validation errors globally.
+ *
+ * @example
+ * ```typescript
+ * // In your React app
+ * window.addEventListener('zod-validation-error', (event) => {
+ *   const { operation, path, method, error, response } = event.detail;
+ *   console.error(`Validation failed for ${method} ${path}`, error);
+ *   // Show toast notification, log to Sentry, etc.
+ * });
+ * ```
+ */
+
+import type { ZodError } from 'zod'
+
+/**
+ * Validation error event detail
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string
+  /** API endpoint path */
+  path: string
+  /** HTTP method */
+  method: string
+  /** Zod validation error */
+  error: ZodError
+  /** Raw response data that failed validation */
+  response: any
+  /** Timestamp of the error */
+  timestamp: Date
+}
+
+/**
+ * Custom event type for Zod validation errors
+ */
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>
+
+/**
+ * Dispatch a Zod validation error event.
+ *
+ * Only dispatches in browser environment (when window is defined).
+ * Safe to call in Node.js/SSR - will be a no-op.
+ *
+ * @param detail - Validation error details
+ */
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  // Check if running in browser
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>('zod-validation-error', {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    })
+
+    window.dispatchEvent(event)
+  } catch (error) {
+    // Silently fail - validation event dispatch should never crash the app
+    console.warn('Failed to dispatch validation error event:', error)
+  }
+}
+
+/**
+ * Add a global listener for Zod validation errors.
+ *
+ * @param callback - Function to call when validation error occurs
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onValidationError(({ operation, error }) => {
+ *   toast.error(`Validation failed in ${operation}`);
+ *   logToSentry(error);
+ * });
+ *
+ * // Later, remove listener
+ * cleanup();
+ * ```
+ */
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void
+): () => void {
+  if (typeof window === 'undefined') {
+    // Return no-op cleanup function for SSR
+    return () => {}
+  }
+
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) {
+      callback(event.detail)
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+
+  // Return cleanup function
+  return () => {
+    window.removeEventListener('zod-validation-error', handler)
+  }
+}
+
+/**
+ * Format Zod error for logging/display.
+ *
+ * @param error - Zod validation error
+ * @returns Formatted error message
+ */
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join('.') || 'root'
+    const parts = [`${index + 1}. ${path}: ${issue.message}`]
+
+    if ('expected' in issue && issue.expected) {
+      parts.push(`   Expected: ${issue.expected}`)
+    }
+
+    if ('received' in issue && issue.received) {
+      parts.push(`   Received: ${issue.received}`)
+    }
+
+    return parts.join('\n')
+  })
+
+  return issues.join('\n')
+}

package/src/api/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Payments Extension API
+ *
+ * Pre-configured API instance with shared authentication
+ */
+import { API } from './generated/ext_payments';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+export const apiPayments = createExtensionAPI(API);

package/src/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Payments extension configuration
+ */
+
+import type { ExtensionMetadata } from '@djangocfg/ext-base';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'payments',
+  version: '1.0.0',
+  author: 'DjangoCFG',
+  displayName: 'Payments',
+  description: 'Payment processing and subscription management',
+  icon: '💳',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['payments', 'subscriptions', 'billing', 'checkout', 'stripe'],
+  dependencies: [],
+  minVersion: '2.0.0',
+} as const;

package/src/contexts/BalancesContext.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { apiPayments } from '../api';
+import { usePaymentsBalanceRetrieve } from '../api/generated/ext_payments/_utils/hooks';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface BalancesContextValue {
+  // Balance data - single endpoint returns balance info
+  balance: any | undefined;
+  isLoadingBalance: boolean;
+  balanceError: Error | undefined;
+  refreshBalance: () => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const BalancesContext = createContext<BalancesContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function BalancesProvider({ children }: { children: ReactNode }) {
+  // Get balance from /cfg/payments/balance/
+  const {
+    data: balance,
+    error: balanceError,
+    isLoading: isLoadingBalance,
+    mutate: mutateBalance,
+  } = usePaymentsBalanceRetrieve(apiPayments);
+
+  const refreshBalance = async () => {
+    await mutateBalance();
+  };
+
+  const value: BalancesContextValue = {
+    balance,
+    isLoadingBalance,
+    balanceError,
+    refreshBalance,
+  };
+
+  return <BalancesContext.Provider value={value}>{children}</BalancesContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useBalancesContext(): BalancesContextValue {
+  const context = useContext(BalancesContext);
+  if (!context) {
+    throw new Error('useBalancesContext must be used within BalancesProvider');
+  }
+  return context;
+}

package/src/contexts/CurrenciesContext.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { apiPayments } from '../api';
+import { usePaymentsCurrenciesList } from '../api/generated/ext_payments/_utils/hooks';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CurrenciesContextValue {
+  // Currencies data - returns raw response with currencies array
+  currencies: any | undefined;
+  isLoadingCurrencies: boolean;
+  currenciesError: Error | undefined;
+  refreshCurrencies: () => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const CurrenciesContext = createContext<CurrenciesContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function CurrenciesProvider({ children }: { children: ReactNode }) {
+  // Get currencies list from /cfg/payments/currencies/
+  const {
+    data: currencies,
+    error: currenciesError,
+    isLoading: isLoadingCurrencies,
+    mutate: mutateCurrencies,
+  } = usePaymentsCurrenciesList(apiPayments);
+
+  const refreshCurrencies = async () => {
+    await mutateCurrencies();
+  };
+
+  const value: CurrenciesContextValue = {
+    currencies,
+    isLoadingCurrencies,
+    currenciesError,
+    refreshCurrencies,
+  };
+
+  return <CurrenciesContext.Provider value={value}>{children}</CurrenciesContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useCurrenciesContext(): CurrenciesContextValue {
+  const context = useContext(CurrenciesContext);
+  if (!context) {
+    throw new Error('useCurrenciesContext must be used within CurrenciesProvider');
+  }
+  return context;
+}
+

package/src/contexts/OverviewContext.tsx

@@ -0,0 +1,173 @@
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { SWRConfig } from 'swr';
+import { apiPayments } from '../api';
+import {
+  usePaymentsBalanceRetrieve,
+  usePaymentsPaymentsList,
+  usePaymentsTransactionsList,
+  useCreatePaymentsPaymentsCreateCreate,
+} from '../api/generated/ext_payments/_utils/hooks';
+import type {
+  PaginatedPaymentListList,
+  PaymentList,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface OverviewContextValue {
+  // Balance data
+  balance: any | undefined;
+  isLoadingBalance: boolean;
+  balanceError: Error | undefined;
+  refreshBalance: () => Promise<void>;
+
+  // Payments data
+  payments: PaginatedPaymentListList | undefined;
+  isLoadingPayments: boolean;
+  paymentsError: Error | undefined;
+  refreshPayments: () => Promise<void>;
+
+  // Transactions data
+  transactions: any | undefined;
+  isLoadingTransactions: boolean;
+  transactionsError: Error | undefined;
+  refreshTransactions: () => Promise<void>;
+
+  // Payment operations
+  createPayment: () => Promise<PaymentList>;
+
+  // Loading states
+  isLoadingOverview: boolean;
+  overviewError: Error | undefined;
+
+  // Operations
+  refreshOverview: () => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const OverviewContext = createContext<OverviewContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function OverviewProvider({ children }: { children: ReactNode }) {
+  // SWR config for overview data - disable auto-revalidation
+  const swrConfig = {
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
+    revalidateIfStale: false,
+  };
+
+  // Balance
+  const {
+    data: balance,
+    error: balanceError,
+    isLoading: isLoadingBalance,
+    mutate: mutateBalance,
+  } = usePaymentsBalanceRetrieve(apiPayments);
+
+  // Payments list
+  const {
+    data: payments,
+    error: paymentsError,
+    isLoading: isLoadingPayments,
+    mutate: mutatePayments,
+  } = usePaymentsPaymentsList({}, apiPayments);
+
+  // Transactions
+  const {
+    data: transactions,
+    error: transactionsError,
+    isLoading: isLoadingTransactions,
+    mutate: mutateTransactions,
+  } = usePaymentsTransactionsList({}, apiPayments);
+
+  // Payment mutations
+  const createPaymentMutation = useCreatePaymentsPaymentsCreateCreate();
+
+  const isLoadingOverview = isLoadingBalance || isLoadingPayments || isLoadingTransactions;
+  const overviewError = balanceError || paymentsError || transactionsError;
+
+  const refreshBalance = async () => {
+    await mutateBalance();
+  };
+
+  const refreshPayments = async () => {
+    await mutatePayments();
+  };
+
+  const refreshTransactions = async () => {
+    await mutateTransactions();
+  };
+
+  const refreshOverview = async () => {
+    await Promise.all([
+      mutateBalance(),
+      mutatePayments(),
+      mutateTransactions(),
+    ]);
+  };
+
+  // Create payment
+  const createPayment = async (): Promise<PaymentList> => {
+    const result = await createPaymentMutation(apiPayments);
+    // Refresh overview data to show new payment
+    await refreshOverview();
+    return result as PaymentList;
+  };
+
+  const value: OverviewContextValue = {
+    balance,
+    isLoadingBalance,
+    balanceError,
+    refreshBalance,
+    payments,
+    isLoadingPayments,
+    paymentsError,
+    refreshPayments,
+    transactions,
+    isLoadingTransactions,
+    transactionsError,
+    refreshTransactions,
+    createPayment,
+    isLoadingOverview,
+    overviewError,
+    refreshOverview,
+  };
+
+  return (
+    <SWRConfig value={swrConfig}>
+      <OverviewContext.Provider value={value}>{children}</OverviewContext.Provider>
+    </SWRConfig>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useOverviewContext(): OverviewContextValue {
+  const context = useContext(OverviewContext);
+  if (!context) {
+    throw new Error('useOverviewContext must be used within OverviewProvider');
+  }
+  return context;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Re-export types
+// ─────────────────────────────────────────────────────────────────────────
+
+export type {
+  PaginatedPaymentListList,
+  PaymentList,
+};
+