@superlogic/spree-pay 0.1.39 → 0.2.0

package/README.md

@@ -33,17 +33,33 @@ function Checkout() {
 }
 
 function CheckoutContent() {
-  const { process, selectedPaymentMethod, isProcessing } = useSpreePay(); // Access payment process function and processing state (must be inside provider)
+  const { process, selectedPaymentMethod, isProcessing, enabled } = useSpreePay();
   const [status, setStatus] = useState<'idle' | 'processing' | 'success' | 'error'>('idle');
 
   async function handleProcess() {
+    if (!enabled) {
+      console.log('Please select a payment method');
+      return;
+    }
+
     setStatus('processing');
     try {
       // Example: create order and process payment
       const order = await getOrderHash();
-      await process({ hash: order.hash });
+      const result = await process({
+        hash: order.hash,
+        capture: true, // Optional: auto-capture payment
+        metadata: { orderId: order.id }, // Optional: additional data
+      });
+
+      console.log('Payment result:', result);
+      // result.status: AUTHORIZED or CAPTURED
+      // result.paymentId: unique payment identifier
+      // result.paymentType: CREDIT_CARD, CRYPTO, CDC, etc.
+
       setStatus('success');
     } catch (err) {
+      console.error('Payment failed:', err);
       setStatus('error');
     }
   }
@@ -56,6 +72,8 @@ function CheckoutContent() {
         transactionFeePercentage={0.04}
         className="w-full max-w-[540px]"
         isProcessing={status === 'processing'}
+        disabledPoints={false}
+        topUpLink="/top-up"
       />
       {status === 'success' && <p>Payment successful! Thank you for your order.</p>}
       {status === 'error' && <p>Payment failed. Please try again.</p>}
@@ -68,7 +86,7 @@ export default function ThreeDSRedirectPage() {
   // take payment intent from search params as payment_intent
   const searchParams = exampleGetSearchParams();
 
-  // place that hook, it will take paymentIntent and close 3ds modal
+  // Pass the entire search params object to the hook
   useCapture3DS({ paymentIntent: searchParams['payment_intent'] });
 
   // Render null or any other UI/Loader
@@ -78,11 +96,140 @@ export default function ThreeDSRedirectPage() {
 
 ### SpreePay props
 
-- amount: number — USD amount to charge (e.g., 99 for $99). Used for display and fee calculation.
-- onProcess: () => Promise<void> — Called when the Checkout button is clicked. Implement your order flow here and call useSpreePay().process({ hash, ... }).
-- isProcessing: boolean — Optional, shows a loading state and disables interactions when true (useful while your onProcess runs).
-- transactionFeePercentage: number — Optional fee multiplier applied to the USD portion (e.g., 0.04 for 4%).
-- className: string — Optional wrapper class for layout/styling.
+```typescript
+type SpreePayProps = {
+  amount?: number; // USD amount to charge (e.g., 99 for $99). Used for display and fee calculation.
+  onProcess?: () => Promise<void>; // Called when the Checkout button is clicked. Implement your order flow here and call useSpreePay().process({ hash, ... }).
+  isProcessing?: boolean; // Shows a loading state and disables interactions when true (useful while your onProcess runs).
+  transactionFeePercentage?: number; // Fee multiplier applied to the USD portion (e.g., 0.04 for 4%).
+  disabledPoints?: boolean; // Disables points payment option if true.
+  topUpLink?: string; // Optional link to top-up page for points balance.
+  className?: string; // Optional wrapper class for layout/styling.
+};
+```
+
+## API Reference
+
+### SpreePayProvider Props
+
+```typescript
+type ENV = {
+  environment: 'dev' | 'stg' | 'prod'; // Environment for API endpoints and logging
+  tenantId: 'bookit' | 'moca' | 'qiibee' | 'umhp' | 'cdc'; // Tenant identifier
+  ssoPageURI: string; // Path to Keycloak SSO page (e.g., '/silent-check-sso.html')
+  redirect3dsURI: string; // Path to 3DS redirect handler (e.g., '/3ds')
+  accessToken?: string; // Optional: provide pre-authenticated token to skip Keycloak SSO
+  useWeb3Points?: boolean; // Optional: enable Web3-based points (default: true)
+};
+```
+
+### useSpreePay Hook
+
+```typescript
+const {
+  process, // Function to trigger payment processing
+  isProcessing, // Internal processing state (true while payment is being processed)
+  enabled, // true if a payment method is selected and ready
+  selectedPaymentMethod, // Currently selected payment method details
+} = useSpreePay();
+
+// process function signature:
+async function process(params: ProcessFnParams): Promise<PaymentMethodResult>;
+
+type ProcessFnParams = {
+  hash: string; // Order hash from your backend
+  capture?: boolean; // Optional: auto-capture payment (default: false)
+  metadata?: Record<string, unknown>; // Optional: additional metadata to pass through
+};
+
+type PaymentMethodResult = {
+  status: SlapiPaymentStatus; // Payment status (AUTHORIZED, CAPTURED, FAILED, etc.)
+  paymentId: string; // Unique payment identifier
+  txHash: string | null; // Transaction hash (for crypto payments)
+  txId: string | null; // Transaction ID
+  paymentType: PaymentType; // Type of payment used
+};
+```
+
+### Payment Types & Statuses
+
+```typescript
+enum PaymentType {
+  CREDIT_CARD = 'CREDIT_CARD',
+  CRYPTO = 'CRYPTO',
+  CDC = 'CDC', // Crypto.com Pay
+  CREDIT_CARD_SPLIT = 'SPLIT', // Split payment (card + points)
+  POINTS = 'POINTS',
+}
+
+enum SlapiPaymentStatus {
+  AUTHORIZED = 'AUTHORIZED', // Payment authorized (success)
+  CAPTURED = 'CAPTURED', // Payment captured (success)
+  FAILED = 'FAILED', // Payment failed
+  PENDING = 'PENDING', // Payment pending (backend only)
+  NOT_INITIALIZED = 'NOT_INITIALIZED', // Not yet started (backend only)
+  VOIDED = 'VOIDED', // Payment voided (backend only)
+  CAPTURE_FAILED = 'CAPTURE_FAILED', // Capture failed (backend only)
+}
+```
+
+### useCapture3DS Hook
+
+```typescript
+// Use in your 3DS redirect page to capture payment intent and close the modal
+useCapture3DS(searchParams: Record<string, string | null>);
+```
+
+### Logger API
+
+```typescript
+import { LogLevel, configureLogger, logger } from '@superlogic/spree-pay';
+
+// Configure logging behavior
+configureLogger({
+  environment: 'dev', // 'prod' = ERROR only, 'dev'/'stg' = all logs
+  minLevel: LogLevel.DEBUG, // Optional: override default log level
+});
+
+// Use the logger
+logger.debug('Debug message', { context: 'data' });
+logger.info('Info message');
+logger.warn('Warning message');
+logger.error('Error message', error);
+
+// Create child logger with prefix
+const componentLogger = logger.child('MyComponent');
+componentLogger.info('Component initialized');
+
+enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  NONE = 4,
+}
+```
+
+## Theme Customization
+
+The widget uses CSS variables for theming. You can override the default theme by wrapping the `<SpreePay>` component in a container with custom CSS variables:
+
+```tsx
+<div
+  style={
+    {
+      '--primary': '#your-color',
+      '--accent': '#your-accent',
+      '--s-default': '#your-surface-color',
+      // ... see packages/spree-pay/src/styles/globals.css for all 54 variables
+    } as React.CSSProperties
+  }
+>
+  <SpreePay {...props} />
+</div>
+```
+
+All available CSS variables are documented in `packages/spree-pay/src/styles/globals.css:21-81`.
 
 ## Keycloak SSO page example (/silent-check-sso.html)