RD LuckyCode Package

A production-ready npm package providing lightweight, framework-agnostic web components for vouchers, redeemable codes, and promotional campaigns. this package offers customizable, accessible components that work seamlessly with React, Vue, Angular, or vanilla JavaScript.

✨ Features

• 4 Ready-to-Use Components: Check codes, redeem vouchers, view customer history, and success popups
• Framework Agnostic: Works with React, Vue, Angular, or plain HTML
• Internationalization: Built-in support for English and Arabic (RTL)
• Customizable: Brand colors, logos, sizes, and text
• Lightweight: Minimal bundle size impact
• Responsive: Mobile-friendly and adaptive layouts
• ES & UMD Modules: Compatible with modern bundlers and legacy setups
• API Integration: Configurable API endpoints for your backend

📦 Installation

Install the package from npm:

npm install rd-luckycode-package

Or using yarn:

yarn add rd-luckycode-package

Or using pnpm:

pnpm add rd-luckycode-package

Prerequisites

• Node.js (v16 or higher)
• npm, yarn, or pnpm

🚀 Usage

Framework Integration

React/Next.js

import { useEffect } from 'react';
import 'rd-luckycode-package';
import { setApiConfig } from 'rd-luckycode-package';

// Configure API globally when app loads
useEffect(() => {
  setApiConfig({
    baseUrl: 'https://api.yourdomain.com'
  });
}, []);

function App() {
  return (
    <div>
      <check-code />
      <redeem-code />
    </div>
  );
}

// Or use per-component configuration:
function AppWithComponentConfig() {
  return (
    <div>
      <check-code api-base-url="https://api.yourdomain.com" />
      <redeem-code api-base-url="https://api.yourdomain.com" />
    </div>
  );
}

Vue 3

<template>
  <div>
    <check-code></check-code>
    <redeem-code></redeem-code>
  </div>
</template>

<script setup>
import 'rd-luckycode-package';
import { setApiConfig } from 'rd-luckycode-package';
import { onMounted } from 'vue';

// Configure API globally when component mounts
onMounted(() => {
  setApiConfig({
    baseUrl: 'https://api.yourdomain.com'
  });
});
</script>

Or use per-component configuration:

<template>
  <div>
    <check-code api-base-url="https://api.yourdomain.com"></check-code>
    <redeem-code api-base-url="https://api.yourdomain.com"></redeem-code>
  </div>
</template>

<script setup>
import 'rd-luckycode-package';
</script>

Angular

Option 1: Angular with NgModule (Traditional - Angular 2-18)

// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Required for web components
  bootstrap: [AppComponent]
})
export class AppModule { }

// app.component.ts
import { Component, OnInit } from '@angular/core';
import 'rd-luckycode-package';
import { setApiConfig } from 'rd-luckycode-package';

@Component({
  selector: 'app-root',
  template: `
    <div>
      <check-code></check-code>
      <redeem-code></redeem-code>
    </div>
  `
})
export class AppComponent implements OnInit {
  ngOnInit() {
    // Configure API globally for all components
    setApiConfig({
      baseUrl: 'https://api.yourdomain.com'
    });
  }
}

Or use per-component configuration:

// app.component.ts
import { Component } from '@angular/core';
import 'rd-luckycode-package';

@Component({
  selector: 'app-root',
  template: `
    <div>
      <check-code api-base-url="https://api.yourdomain.com"></check-code>
      <redeem-code api-base-url="https://api.yourdomain.com"></redeem-code>
    </div>
  `
})
export class AppComponent { }

Option 2: Angular Standalone Components (Modern - Angular 14+)

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';

bootstrapApplication(AppComponent).catch(err => console.error(err));

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { CommonModule } from '@angular/common';
import 'rd-luckycode-package';
import { setApiConfig } from 'rd-luckycode-package';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <div>
      <check-code></check-code>
      <redeem-code></redeem-code>
    </div>
  `
})
export class App {
  constructor() {
    // Configure API before components are created
    setApiConfig({
      baseUrl: 'https://api.yourdomain.com'
    });
  }
}

Option 3: Standalone with Component-level Config

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { CommonModule } from '@angular/common';
import 'rd-luckycode-package';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <div>
      <check-code api-base-url="https://api.yourdomain.com"></check-code>
      <redeem-code api-base-url="https://api.yourdomain.com"></redeem-code>
    </div>
  `
})
export class AppComponent { }

📚 Available Components

<check-code>

Validates voucher/code without redeeming it. This component allows users to verify if a code is valid, active, and available for use without actually redeeming it.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | title | string | "Check Code Status" | The title displayed at the top of the component | | language | "en" | "ar" | "en" | Language for the component (English or Arabic). Supports RTL for Arabic | | primary-color | string | "#111827" | Primary color used for styling buttons, headings, and interactive elements | | logo | string | Default LuckyCode logo | URL or path to custom logo image. Displayed at the top of the card | | width | string | "600px" | Maximum width of the card. Accepts any CSS width value (px, %, rem, vw, etc.) | | api-base-url | string | Global config or /api | API base URL for this component. Overrides global configuration |

Example - Basic Usage

<!-- Using default settings -->
<check-code></check-code>

Example - Fully Customized

<check-code
  title="Verify Your Code"
  language="en"
  primary-color="#3b82f6"
  logo="https://example.com/logo.png"
  width="800px">
</check-code>

Example - Arabic Version

<check-code
  title="تحقق من الكود"
  language="ar"
  primary-color="#8b5cf6"
  width="500px">
</check-code>

<redeem-code>

Allows users to redeem codes and vouchers. This component handles the full redemption process.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | title | string | "Redeem Your LuckyCode" | The title displayed at the top of the component | | language | "en" | "ar" | "en" | Language for the component (English or Arabic). Supports RTL for Arabic | | primary-color | string | "#111827" | Primary color used for styling buttons, headings, and interactive elements | | logo | string | Default LuckyCode logo | URL or path to custom logo image. Displayed at the top of the card | | width | string | "600px" | Maximum width of the card. Accepts any CSS width value (px, %, rem, vw, etc.) | | api-base-url | string | Global config or /api | API base URL for this component. Overrides global configuration |

Example - Basic Usage

<!-- Using default settings -->
<redeem-code></redeem-code>

Example - Fully Customized

<redeem-code
  title="Claim Your Reward"
  language="en"
  primary-color="#10b981"
  logo="https://yourstore.com/logo.png"
  width="700px">
</redeem-code>

Example - Arabic Version

<redeem-code
  title="استبدل الكود الخاص بك"
  language="ar"
  primary-color="#f59e0b"
  width="550px">
</redeem-code>

<customer-logs>

Displays customer redemption history and logs.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | customer-ref | string | "" | Customer reference ID to fetch codes for (required) | | title | string | "My LuckyCodes" | The title displayed at the top of the component | | language | "en" | "ar" | "en" | Language for the component (English or Arabic) | | primary-color | string | "#111827" | Primary color used for styling (buttons, headings) | | page-size | number | 20 | Number of items to display per page | | api-base-url | string | Global config or /api | API base URL for this component. Overrides global configuration |

Example - Basic Usage

<!-- Using default settings with required customer-ref -->
<customer-logs customer-ref="CUST123"></customer-logs>

Example - Fully Customized

<customer-logs
  customer-ref="CUST123"
  title="My Rewards History"
  language="en"
  primary-color="#3b82f6"
  page-size="10">
</customer-logs>

Example - Arabic Version

<customer-logs
  customer-ref="CUST123"
  title="أكوادي المحظوظة"
  language="ar"
  primary-color="#8b5cf6"
  page-size="15">
</customer-logs>

Example - React/Next.js with Dynamic Customer Ref

import { useEffect } from 'react';
import 'rd-luckycode-package';

function CustomerCodesPage({ customerId }) {
  return (
    <div>
      <customer-logs
        customer-ref={customerId}
        title="My Lucky Codes"
        primary-color="#10b981"
        page-size="20">
      </customer-logs>
    </div>
  );
}

Example - Vue 3 with Dynamic Customer Ref

<template>
  <div>
    <customer-logs
      :customer-ref="customerId"
      title="My Codes"
      primary-color="#f59e0b"
      :page-size="25">
    </customer-logs>
  </div>
</template>

<script setup>
import 'rd-luckycode-package';
import { ref } from 'vue';

const customerId = ref('CUST123');
</script>

<success-popup>

A popup component that displays after successful operations (like payment completion). It includes a trigger button that calls an API and shows a success modal when the operation completes. The modal allows users to either reveal their code immediately or view it later.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | button-text | string | "Payment Completion" | Text displayed on the trigger button | | primary-color | string | "#111827" | Primary color for modal styling (icon, headings, primary button) | | button-color | string | "#111827" | Color of the trigger button | | language | "en" | "ar" | "en" | Language for the component (English or Arabic). Supports RTL for Arabic | | title | string | "Congratulations!" | Optional custom title for the success modal. Falls back to language-specific default | | description | string | "Your transaction was successful..." | Optional custom description text for the modal. Falls back to language-specific default | | onNavigate | Function | undefined | Optional callback function that executes when "Reveal Code Now" button is clicked. If not provided, fires reveal-code event instead | | api-base-url | string | Global config or /api | API base URL for this component. Overrides global configuration |

Events

| Event | Description | Detail | |-------|-------------|--------| | reveal-code | Fired when user clicks "Reveal Code Now" button | { bubbles: true, composed: true } | | close | Fired when the modal is closed | N/A | | trigger-failed | Fired when the API call fails | { response } | | trigger-error | Fired when an error occurs during the API call | { error } |

Example - Basic Usage

<success-popup></success-popup>

Example - Customized

<success-popup
  button-text="Complete Payment"
  primary-color="#059669"
  button-color="#10b981"
  language="en">
</success-popup>

Example - Arabic Version

<success-popup
  button-text="إكمال الدفع"
  primary-color="#8b5cf6"
  button-color="#a78bfa"
  language="ar">
</success-popup>

Example - React/Next.js with onNavigate

import { useRouter } from 'next/router';
import { useEffect, useRef } from 'react';

function CheckoutPage() {
  const router = useRouter();
  const popupRef = useRef(null);

  useEffect(() => {
    if (popupRef.current) {
      popupRef.current.onNavigate = () => {
        router.push('/customer-codes');
      };
    }
  }, [router]);

  return (
    <success-popup
      ref={popupRef}
      button-text="Complete Purchase"
      primary-color="#10b981"
    />
  );
}

Example - Vue 3 with onNavigate

<template>
  <success-popup
    ref="popupRef"
    button-text="Complete Order"
    primary-color="#3b82f6"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';

const router = useRouter();
const popupRef = ref(null);

onMounted(() => {
  if (popupRef.value) {
    popupRef.value.onNavigate = () => {
      router.push('/my-lucky-codes');
    };
  }
});
</script>

Getting Help

If you encounter issues not listed here:

1. Review the component documentation above
2. Ensure you're using the latest version: npm update rd-luckycode-package
3. Check the browser console for error messages
4. Verify your framework and bundler configurations

📄 License

MIT

👤 Author

Redeemly