@tagadapay/plugin-sdk 1.0.29 → 2.0.1

package/README.md

@@ -6,16 +6,110 @@ A comprehensive SDK for building checkout plugins on the TagadaPay platform. Cre
 
 ### Core APIs
 
-- **[useCheckout](./README-useCheckout.md)** - Checkout state management and flow control
-- **[setCheckoutInfo](./README-setCheckoutInfo.md)** - Customer information and validation
-- **[useOffers](./README-useOffers.md)** - Dynamic pricing and promotional offers
-- **[Money utilities](./README-money.md)** - Currency formatting and calculations
-- **[URL utilities](./README-urlUtils.md)** - Navigation and routing helpers
+- **[useCheckout](./docs/README-useCheckout.md)** - Checkout state management and flow control
+- **[setCheckoutInfo](./docs/README-setCheckoutInfo.md)** - Customer information and validation
+- **[useOffers](./docs/README-useOffers.md)** - Dynamic pricing and promotional offers
+- **[Money utilities](./docs/README-money.md)** - Currency formatting and calculations
+- **[URL utilities](./docs/README-urlUtils.md)** - Navigation and routing helpers
+
+### Plugin Development
+
+- **[Plugin Configuration](./docs/PLUGIN_CONFIG.md)** - How to access store context, config, and branding
+- **[Google Autocomplete](./docs/README-google-autocomplete.md)** - Address autocomplete with Google Places API
+- **[ISO Data](./docs/README-iso-data.md)** - Country and region data with Google integration
 
 ### Examples
 
 - **[Vite Checkout Demo](../checkout-vite)** - Complete checkout implementation
 
+## 🏗️ Building a Plugin
+
+### Plugin Structure
+
+Every TagadaPay plugin follows this simple structure:
+
+```
+my-plugin/
+├── plugin.manifest.json    # Plugin metadata & routing
+├── .local.json            # Local dev config (auto-injected in production)
+├── config/                # Optional deployment configs
+│   ├── theme-green.json   # Config variant A
+│   └── theme-blue.json    # Config variant B
+├── src/
+│   └── App.tsx           # Your plugin code
+└── dist/                 # Built plugin files
+```
+
+### Configuration Flow
+
+```mermaid
+graph TD
+    A[🛠️ Local Development] --> B[.local.json]
+    A --> C[config/*.json]
+    B --> D[usePluginConfig()]
+    C --> D
+
+    E[🚀 Production] --> F[Platform Injection]
+    F --> G[HTTP Headers & Meta Tags]
+    G --> D
+
+    D --> H[Your Plugin Component]
+
+    style A fill:#e1f5fe
+    style E fill:#f3e5f5
+    style D fill:#fff3e0
+    style H fill:#e8f5e8
+```
+
+### Essential Files
+
+#### 1. **`plugin.manifest.json`** - Plugin Metadata
+
+```json
+{
+  "pluginId": "my-awesome-plugin",
+  "name": "My Awesome Plugin",
+  "version": "1.0.0",
+  "mode": "direct-mode",
+  "router": {
+    "basePath": "/",
+    "matcher": ".*",
+    "excluder": "/checkout"
+  }
+}
+```
+
+#### 2. **`.local.json`** - Local Development Context
+
+```json
+{
+  "storeId": "store_abc123",
+  "accountId": "acc_xyz789",
+  "basePath": "/"
+}
+```
+
+> ⚠️ **Auto-managed**: This file is only for local dev. In production, the platform injects this data automatically.
+
+#### 3. **`config/my-theme.json`** - Optional Deployment Config
+
+```json
+{
+  "configName": "green-theme",
+  "branding": {
+    "primaryColor": "#059669",
+    "companyName": "My Store",
+    "logoUrl": "https://example.com/logo.png"
+  },
+  "features": {
+    "enableChat": true,
+    "maxItems": 10
+  }
+}
+```
+
+> 📝 **Note**: Config can contain any keys you need - the SDK doesn't enforce a specific structure.
+
 ## 🚀 Quick Start
 
 ### Installation
@@ -24,27 +118,65 @@ A comprehensive SDK for building checkout plugins on the TagadaPay platform. Cre
 npm install @tagadapay/plugin-sdk
 ```
 
-### Basic Usage
+### Basic Plugin Setup
 
-```typescript
-import { useCheckout, setCheckoutInfo } from '@tagadapay/plugin-sdk';
+```tsx
+import React from 'react';
+import { 
+  TagadaProvider, 
+  usePluginConfig,
+  useGoogleAutocomplete,
+  useISOData 
+} from '@tagadapay/plugin-sdk/react';
+
+function MyPlugin() {
+  const { storeId, accountId, basePath, config, loading } = usePluginConfig();
 
-function CheckoutPage() {
-  const { customer, cart, payment } = useCheckout();
+  // Optional: Add address autocomplete
+  const { searchPlaces, predictions } = useGoogleAutocomplete({
+    apiKey: config?.googleMapsApiKey || 'YOUR_API_KEY'
+  });
 
-  const handleSubmit = async (data) => {
-    await setCheckoutInfo({
-      customer: data.customer,
-      payment: data.payment
-    });
-  };
+  // Optional: Add country/region data
+  const { countries } = useISOData('en');
+
+  if (loading) return <div>Loading...</div>;
 
   return (
-    <div>
-      {/* Your checkout UI */}
+    <div style={{ '--primary': config?.branding?.primaryColor }}>
+      <h1>Welcome to {config?.branding?.companyName}</h1>
+      <p>Store: {storeId}</p>
+      <p>Base Path: {basePath}</p>
+      <p>Available Countries: {Object.keys(countries).length}</p>
     </div>
   );
 }
+
+// Wrap your plugin with TagadaProvider
+function App() {
+  return (
+    <TagadaProvider>
+      <MyPlugin />
+    </TagadaProvider>
+  );
+}
+
+export default App;
+```
+
+### Development vs Production
+
+| Environment    | Store/Account ID | Deployment Config | How it Works       |
+| -------------- | ---------------- | ----------------- | ------------------ |
+| **Local Dev**  | `.local.json`    | `config/*.json`   | Files on disk      |
+| **Production** | HTTP Headers     | Meta Tags         | Platform injection |
+
+```tsx
+// ✅ ALWAYS use hooks - works in both environments
+const { storeId, accountId, basePath, config } = usePluginConfig();
+
+// ❌ NEVER access directly
+// const config = window.__PLUGIN_CONFIG__; // Doesn't exist!
 ```
 
 ## 🎯 Key Features

package/dist/data/iso3166.d.ts

@@ -0,0 +1,30 @@
+export interface Country {
+    code: string;
+    name: string;
+    iso3?: string;
+    numeric?: number;
+    uniqueKey?: string;
+}
+export interface State {
+    code: string;
+    name: string;
+    countryCode: string;
+    uniqueKey?: string;
+}
+export declare const getCountries: () => Country[];
+export declare const getAllStates: () => State[];
+export declare const getStatesForCountry: (countryCode: string) => State[];
+export declare const findCountryByName: (countryName: string) => Country | null;
+export declare const findRegionByCode: (regionCode: string) => State | null;
+export declare const isValidCountryCode: (countryCode: string) => boolean;
+export declare const isValidStateCode: (countryCode: string, stateCode: string) => boolean;
+export declare const getCountryWithRegions: (countryCode: string) => {
+    country: {
+        code: any;
+        name: any;
+        iso3: any;
+        numeric: any;
+        uniqueKey: string;
+    };
+    regions: State[];
+} | null;

package/dist/data/iso3166.js

@@ -0,0 +1,102 @@
+// Import the ISO3166 library API functions
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - iso3166-2-db doesn't have TypeScript definitions
+import { getDataSet, reduce } from 'iso3166-2-db';
+// Get the full dataset with default English language
+const worldDatabase = reduce(getDataSet(), 'en');
+// Transform the ISO3166 data into our expected format
+export const getCountries = () => {
+    const countries = [];
+    Object.keys(worldDatabase).forEach((countryCode) => {
+        const countryData = worldDatabase[countryCode];
+        countries.push({
+            code: countryData.iso, // iso3166-1 alpha-2 code
+            name: countryData.name,
+            iso3: countryData.iso3, // iso3166-1 alpha-3 code
+            numeric: countryData.numeric,
+            uniqueKey: `country-${countryData.iso}`,
+        });
+    });
+    // Sort countries alphabetically by name
+    return countries.sort((a, b) => a.name.localeCompare(b.name));
+};
+// Get all states/regions for all countries
+export const getAllStates = () => {
+    const states = [];
+    Object.keys(worldDatabase).forEach((countryCode) => {
+        const countryData = worldDatabase[countryCode];
+        if (countryData.regions && Array.isArray(countryData.regions)) {
+            countryData.regions.forEach((region, index) => {
+                states.push({
+                    code: region.iso, // iso3166-2 code (the part after the dash)
+                    name: region.name,
+                    countryCode: countryData.iso,
+                    uniqueKey: `state-${countryData.iso}-${region.iso}-${index}`,
+                });
+            });
+        }
+    });
+    // Sort states alphabetically by name
+    return states.sort((a, b) => a.name.localeCompare(b.name));
+};
+// Get states for a specific country
+export const getStatesForCountry = (countryCode) => {
+    const countryData = worldDatabase[countryCode];
+    if (!countryData?.regions || !Array.isArray(countryData.regions)) {
+        return [];
+    }
+    return countryData.regions
+        .map((region, index) => ({
+        code: region.iso,
+        name: region.name,
+        countryCode: countryData.iso,
+        uniqueKey: `state-${countryData.iso}-${region.iso}-${index}`,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+};
+// Find country by name (fuzzy search)
+export const findCountryByName = (countryName) => {
+    const countries = getCountries();
+    const normalizedSearchName = countryName.toLowerCase().trim();
+    // Exact match first
+    const exactMatch = countries.find((country) => country.name.toLowerCase() === normalizedSearchName);
+    if (exactMatch)
+        return exactMatch;
+    // Partial match
+    const partialMatch = countries.find((country) => country.name.toLowerCase().includes(normalizedSearchName) ||
+        normalizedSearchName.includes(country.name.toLowerCase()));
+    return partialMatch ?? null;
+};
+// Find region by ISO code (e.g., "US-CA" for California)
+export const findRegionByCode = (regionCode) => {
+    const [countryCode, stateCode] = regionCode.split('-');
+    if (!countryCode || !stateCode)
+        return null;
+    const states = getStatesForCountry(countryCode);
+    return states.find((state) => state.code === stateCode) ?? null;
+};
+// Validate if a country code exists
+export const isValidCountryCode = (countryCode) => {
+    return Object.prototype.hasOwnProperty.call(worldDatabase, countryCode);
+};
+// Validate if a state code exists for a given country
+export const isValidStateCode = (countryCode, stateCode) => {
+    const states = getStatesForCountry(countryCode);
+    return states.some((state) => state.code === stateCode);
+};
+// Get country info including regions
+export const getCountryWithRegions = (countryCode) => {
+    const countryData = worldDatabase[countryCode];
+    if (!countryData)
+        return null;
+    return {
+        country: {
+            code: countryData.iso,
+            name: countryData.name,
+            iso3: countryData.iso3,
+            numeric: countryData.numeric,
+            uniqueKey: `country-${countryData.iso}`,
+        },
+        regions: getStatesForCountry(countryCode),
+    };
+};

package/dist/react/hooks/useAddressV2.d.ts

@@ -0,0 +1,53 @@
+import { type Country as ISO3166Country, type State as ISO3166State } from '../../data/iso3166';
+export type Country = ISO3166Country;
+export type State = ISO3166State;
+export interface AddressField {
+    value: string;
+    isValid: boolean;
+    error?: string;
+    touched?: boolean;
+}
+export interface AddressData {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    country: string;
+    address1: string;
+    address2: string;
+    city: string;
+    state: string;
+    postal: string;
+}
+export interface UseAddressV2Config {
+    autoValidate?: boolean;
+    enableGooglePlaces?: boolean;
+    googlePlacesApiKey?: string;
+    countryRestrictions?: string[];
+    onFieldsChange?: (data: AddressData) => void;
+    debounceConfig?: {
+        autoSaveDelay?: number;
+        enabled?: boolean;
+    };
+    initialValues?: Partial<AddressData>;
+}
+export interface UseAddressV2Return {
+    fields: Record<keyof AddressData, AddressField>;
+    setValue: (field: keyof AddressData, value: string) => void;
+    setValues: (values: Partial<AddressData>) => void;
+    getValue: (field: keyof AddressData) => string;
+    getValues: () => AddressData;
+    validateField: (field: keyof AddressData) => boolean;
+    validateAll: () => boolean;
+    isValid: boolean;
+    reset: () => void;
+    countries: Country[];
+    states: State[];
+    getStatesForCountry: (countryCode: string) => State[];
+    addressRef: React.RefObject<HTMLInputElement | null>;
+    addressInputValue: string;
+    setAddressInputValue: (value: string) => void;
+    handleFieldChange: (field: keyof AddressData) => (value: string) => void;
+    handleFieldBlur: (field: keyof AddressData) => () => void;
+}
+export declare const useAddressV2: (config?: UseAddressV2Config) => UseAddressV2Return;