@tagadapay/plugin-sdk 2.8.7 → 2.8.8

package/dist/v2/core/resources/funnel.d.ts

@@ -33,13 +33,202 @@ export declare enum FunnelActionType {
 export type NextAction<T> = T & {
     [key: string]: any;
 };
-export interface DirectNavigationActionData {
+/**
+ * Base resource data type - all resources must have an id and optional metadata
+ */
+export interface FunnelResourceData {
+    id: string;
+    [key: string]: any;
+}
+/**
+ * Resource metadata for tracking, versioning, and relationships
+ */
+export interface ResourceMetadata {
+    /** Plugin that created this resource */
+    source?: string;
+    /** Schema version for this resource */
+    version?: string;
+    /** Timestamp when resource was created */
+    timestamp?: number;
+    /** Scope: how long should this resource persist */
+    scope?: 'global' | 'session' | 'step' | 'ephemeral';
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Related resource IDs (for relationships) */
+    relatedTo?: string[];
+    /** Custom metadata */
+    [key: string]: any;
+}
+/**
+ * Wrapped resource with metadata
+ */
+export interface ResourceWithMetadata<T extends FunnelResourceData = FunnelResourceData> {
+    data: T;
+    meta: ResourceMetadata;
+}
+/**
+ * Standard resource types for e-commerce (provides IntelliSense)
+ * These are SUGGESTIONS, not limitations - any key is allowed via index signature
+ */
+export interface StandardResourceKeys {
+    order?: FunnelResourceData;
+    customer?: FunnelResourceData;
+    payment?: FunnelResourceData;
+    checkout?: FunnelResourceData;
+    cart?: FunnelResourceData;
+    subscription?: FunnelResourceData;
+    product?: FunnelResourceData;
+    variant?: FunnelResourceData;
+    mainOrder?: FunnelResourceData;
+    upsellOrder?: FunnelResourceData;
+    downsellOrder?: FunnelResourceData;
+    orders?: FunnelResourceData[];
+    customers?: FunnelResourceData[];
+    payments?: FunnelResourceData[];
+}
+/**
+ * Flexible resource map supporting:
+ * 1. Single resources (order)
+ * 2. Collections (orders[])
+ * 3. Wrapped resources with metadata
+ * 4. Completely custom keys
+ *
+ * @example Simple usage (backward compatible)
+ * ```typescript
+ * resources: {
+ *   order: { id: '123', amount: 100 }
+ * }
+ * ```
+ *
+ * @example Multiple instances via collections
+ * ```typescript
+ * resources: {
+ *   order: { id: 'main' },  // Hot context
+ *   orders: [               // Full collection
+ *     { id: 'main', type: 'initial' },
+ *     { id: 'upsell1', type: 'addon' }
+ *   ]
+ * }
+ * ```
+ *
+ * @example With metadata (opt-in)
+ * ```typescript
+ * resources: {
+ *   order: {
+ *     data: { id: '123', amount: 100 },
+ *     meta: { source: 'checkout-plugin', version: '2.0' }
+ *   }
+ * }
+ * ```
+ *
+ * @example Typed resources (opt-in strict typing)
+ * ```typescript
+ * interface MyResources {
+ *   order: Order;  // Your typed Order interface
+ *   customer: Customer;
+ * }
+ *
+ * const result = await funnel.next<MyResources>({
+ *   type: 'payment_success',
+ *   data: {
+ *     resources: {
+ *       order: { id: '123', amount: 100 } // ✅ Type-checked!
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export type FunnelResourceMap<TCustom = {}> = StandardResourceKeys & {
+    /**
+     * Fully extensible - any key allowed
+     * Value can be:
+     * - Single resource: { id: '...' }
+     * - Collection: [{ id: '...' }, ...]
+     * - Wrapped: { data: {...}, meta: {...} }
+     */
+    [key: string]: FunnelResourceData | FunnelResourceData[] | ResourceWithMetadata | ResourceWithMetadata[] | undefined;
+} & TCustom;
+/**
+ * Typed resources structure for funnel actions
+ *
+ * 💡 RESOURCE PROTOCOL: Flexible & Scalable
+ *
+ * The system supports multiple patterns for maximum flexibility:
+ *
+ * 1. **Simple Pattern** (Default - Backward Compatible):
+ *    ```typescript
+ *    resources: { order: { id: '123' } }
+ *    ```
+ *
+ * 2. **Aliasing Pattern** (For Hot + Named Context):
+ *    ```typescript
+ *    resources: {
+ *      order: { id: '123' },      // Hot context (latest)
+ *      mainOrder: { id: '123' }   // Named (persistent)
+ *    }
+ *    ```
+ *
+ * 3. **Collection Pattern** (For Multiple Instances):
+ *    ```typescript
+ *    resources: {
+ *      orders: [
+ *        { id: 'main', label: 'Initial Order' },
+ *        { id: 'upsell1', label: 'Upsell #1' }
+ *      ]
+ *    }
+ *    ```
+ *
+ * 4. **Metadata Pattern** (For Versioning/Tracking):
+ *    ```typescript
+ *    resources: {
+ *      order: {
+ *        data: { id: '123', amount: 100 },
+ *        meta: { version: '2.0', source: 'checkout' }
+ *      }
+ *    }
+ *    ```
+ *
+ * 5. **Namespaced Pattern** (For Collision Prevention):
+ *    ```typescript
+ *    resources: {
+ *      'checkout:order': { id: '123' },
+ *      'subscription:order': { id: '456' }
+ *    }
+ *    ```
+ *
+ * 6. **Typed Pattern** (For Strict Type Safety):
+ *    ```typescript
+ *    interface StrictResources {
+ *      order: Order;  // Your interface
+ *      customer: Customer;
+ *    }
+ *    funnel.next<StrictResources>({ ... })
+ *    ```
+ *
+ * All patterns work together - choose what fits your use case!
+ */
+export interface FunnelActionResources<TCustom = {}> {
+    /**
+     * Resource map - infinitely extensible
+     * - Standard keys provide IntelliSense
+     * - Custom keys allowed via index signature
+     * - Supports single resources, collections, and metadata
+     * - Optional: pass generic for strict typing
+     */
+    resources?: FunnelResourceMap<TCustom>;
+    /**
+     * Legacy top-level data (backward compatible)
+     * Will be automatically migrated to resources by orchestrator
+     */
+    [key: string]: any;
+}
+export interface DirectNavigationActionData extends FunnelActionResources {
     targetStepId: string;
 }
-export interface BackNavigationActionData {
+export interface BackNavigationActionData extends FunnelActionResources {
     targetStepId: string;
 }
-export interface PaymentSuccessActionData {
+export interface PaymentSuccessActionData extends FunnelActionResources {
     payment: {
         id: string;
         status: string;
@@ -53,34 +242,30 @@ export interface PaymentSuccessActionData {
         currency: string;
         [key: string]: any;
     };
-    [key: string]: any;
 }
-export interface PaymentFailedActionData {
+export interface PaymentFailedActionData extends FunnelActionResources {
     payment: {
         id: string;
         status: string;
         error?: string;
         [key: string]: any;
     };
-    [key: string]: any;
 }
-export interface OfferAcceptedActionData {
+export interface OfferAcceptedActionData extends FunnelActionResources {
     offer: {
         accepted: boolean;
         offerId?: string;
         [key: string]: any;
     };
-    [key: string]: any;
 }
-export interface OfferDeclinedActionData {
+export interface OfferDeclinedActionData extends FunnelActionResources {
     offer: {
         declined: boolean;
         offerId?: string;
         [key: string]: any;
     };
-    [key: string]: any;
 }
-export interface CartUpdatedActionData {
+export interface CartUpdatedActionData extends FunnelActionResources {
     cart: {
         hasSpecificItem?: boolean;
         itemIds?: string[];
@@ -88,13 +273,11 @@ export interface CartUpdatedActionData {
         total?: number;
         [key: string]: any;
     };
-    [key: string]: any;
 }
-export interface FormSubmitActionData {
+export interface FormSubmitActionData extends FunnelActionResources {
     form?: {
         [key: string]: any;
     };
-    [key: string]: any;
 }
 /**
  * Base properties shared by all FunnelAction types
@@ -149,7 +332,10 @@ export type FunnelAction = BaseFunnelAction & (({
     data: NextAction<CartUpdatedActionData>;
 }) | ({
     type: FunnelActionType.CUSTOM;
-    data: NextAction<any>;
+    data: NextAction<FunnelActionResources>;
+}) | ({
+    type: string;
+    data?: NextAction<FunnelActionResources>;
 }));
 export interface FunnelNavigationAction {
     type: 'redirect' | 'replace' | 'push' | 'external' | 'none';
@@ -167,7 +353,33 @@ export interface FunnelNavigationResult {
         timestamp: string;
     };
 }
-export interface SimpleFunnelContext {
+/**
+ * Funnel context available to plugins
+ * Contains current state, resources, and metadata about the funnel session
+ *
+ * @example Basic usage
+ * ```typescript
+ * const context = await funnel.getContext();
+ * const orderId = context.resources?.order?.id;
+ * ```
+ *
+ * @example Typed usage (opt-in strict typing)
+ * ```typescript
+ * interface MyResources {
+ *   order: Order;
+ *   customer: Customer;
+ * }
+ * const context = await funnel.getContext<MyResources>();
+ * const total = context.resources?.order.amount; // ✅ Type-safe!
+ * ```
+ *
+ * @example Collection access
+ * ```typescript
+ * const allOrders = context.resources?.orders; // FunnelResourceData[]
+ * const mainOrder = allOrders?.find(o => o.id === 'main');
+ * ```
+ */
+export interface SimpleFunnelContext<TCustom = {}> {
     customerId: string;
     storeId: string;
     sessionId: string;
@@ -181,6 +393,17 @@ export interface SimpleFunnelContext {
     furthestStepId?: string;
     startedAt: number;
     lastActivityAt: number;
+    /**
+     * Typed resources map - infinitely extensible
+     * - Single resources, collections, or wrapped with metadata
+     * - Pass generic for strict typing: SimpleFunnelContext<MyResources>
+     * - Standard keys provide IntelliSense, custom keys always allowed
+     */
+    resources?: FunnelResourceMap<TCustom>;
+    /**
+     * Legacy/Custom metadata
+     * For backward compatibility and flexible unstructured data
+     */
     metadata?: Record<string, any>;
 }
 export interface FunnelInitializeRequest {

package/dist/v2/index.d.ts

@@ -23,9 +23,10 @@ export type { ToggleOrderBumpResponse, VipOffer, VipPreviewResponse } from './co
 export type { StoreConfig } from './core/resources/storeConfig';
 export { FunnelActionType } from './core/resources/funnel';
 export type { BackNavigationActionData, CartUpdatedActionData, DirectNavigationActionData, FormSubmitActionData, FunnelContextUpdateRequest, FunnelContextUpdateResponse, FunnelAction as FunnelEvent, FunnelInitializeRequest, FunnelInitializeResponse, FunnelNavigateRequest, FunnelNavigateResponse, FunnelNavigationAction, FunnelNavigationResult, NextAction, OfferAcceptedActionData, OfferDeclinedActionData, PaymentFailedActionData, PaymentSuccessActionData, SimpleFunnelContext } from './core/resources/funnel';
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCredits, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
 export type { TranslateFunction, TranslationText, UseTranslationOptions, UseTranslationResult } from './react/hooks/useTranslation';
 export type { ClubOffer, ClubOfferItem, ClubOfferLineItem, ClubOfferSummary, UseClubOffersOptions, UseClubOffersResult } from './react/hooks/useClubOffers';
+export type { UseCreditsOptions, UseCreditsResult } from './react/hooks/useCredits';
 export type { UseLoginOptions, UseLoginResult } from './react/hooks/useLogin';
 export type { CustomerAddress, CustomerInfos, CustomerOrderSummary, OrderWithRelations, Subscription, SubscriptionsResponse } from './core/resources/customer';
 export type { UseCustomerResult } from './react/hooks/useCustomer';

package/dist/v2/index.js

@@ -15,4 +15,4 @@ export * from './core/utils/products';
 export * from './core/pathRemapping';
 export { FunnelActionType } from './core/resources/funnel';
 // React exports (hooks and components only, types are exported above)
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCredits, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';

package/dist/v2/react/hooks/useFunnel.d.ts

@@ -46,6 +46,6 @@ export declare function useSimpleFunnel(funnelId: string, initialStepId?: string
     next: (event: FunnelAction) => Promise<any>;
     goToStep: (stepId: string) => Promise<any>;
     isLoading: boolean;
-    context: SimpleFunnelContext | null;
+    context: SimpleFunnelContext<{}> | null;
 };
 export type { FunnelAction as FunnelEvent, FunnelNavigationAction, FunnelNavigationResult, SimpleFunnelContext } from '../../core/resources/funnel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/plugin-sdk",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "description": "Modern React SDK for building Tagada Pay plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",