@neosianexus/super-tebex 2.0.1 → 3.0.2

package/dist/index.d.ts

@@ -1,126 +1,731 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { Basket, Category, InBasket, Package, PackageType, TebexHeadless } from 'tebex_headless';
+import { QueryClient } from '@tanstack/react-query';
+import { ReactNode } from 'react';
+import { Basket, BasketPackage, Category, Code, GiftCardCode, Package, PackageType, TebexHeadless, Webstore } from 'tebex_headless';
 
-export interface GetShopUrlsResult {
-	completeUrl: string;
-	cancelUrl: string;
-}
-export declare const useCreateBasket: (username: string | null) => (() => Promise<Basket | null>);
-export declare let shopUrls: GetShopUrlsResult | null;
-export declare const initShopUrls: (baseUrl: string, paths?: {
-	complete?: string;
-	cancel?: string;
-}) => void;
-export declare let tebex: TebexHeadless | null;
-export declare const initTebex: (publicKey: string) => void;
-export declare const getTebex: () => TebexHeadless;
-export interface UseBasketResult {
-	basket: Basket | null;
-	loading: boolean;
-	error: Error | null;
-	addPackageToBasket: (packageId: Package["id"], quantity?: InBasket["quantity"], type?: PackageType, variableData?: Record<string, string>) => Promise<void>;
-	removePackageFromBasket: (packageId: Package["id"]) => Promise<void>;
-	updateManualBasket: (basket: Basket | null) => void;
-	refetch: () => Promise<void>;
-}
-export declare const useBasket: (username: string | null) => UseBasketResult;
-export interface CreateBasketProps {
-	username: string;
-	completeUrl: string;
-	cancelUrl: string;
-	custom?: Record<string, any>;
-	completeAutoRedirect?: boolean;
-	ipAddress?: string;
-}
-export interface ShopBasketStore {
-	basketIdent: string | null;
-	setBasketIdent: (basketIdent: string) => void;
-	clearBasketIdent: () => void;
-}
-export interface GetCategories {
-	includePackages?: boolean;
-	basketIdent?: string;
-	ipAddress?: string;
-}
-export interface UseCategoriesResult {
-	categories: Category[] | null;
-	loading: boolean;
-	error: Error | null;
-	getByName: (name: string) => Category | undefined;
-	refetch: () => Promise<void>;
-}
-export declare const useCategories: (options: GetCategories) => UseCategoriesResult;
-export declare const basketService: {
-	createBasket: ({ username, completeUrl, cancelUrl, custom, completeAutoRedirect, ipAddress, }: CreateBasketProps) => Promise<Basket>;
-	getBasket: (basketIdent: Basket["ident"]) => Promise<Basket>;
-	addPackageToBasket: (basketIdent: Basket["ident"], packageId: Package["id"], quantity?: InBasket["quantity"], type?: PackageType, variableData?: Record<string, string>) => Promise<Basket>;
-	removePackageFromBasket: (basketIdent: Basket["ident"], packageId: Package["id"], currentQuantity: InBasket["quantity"]) => Promise<Basket>;
-};
-export declare const categoriesService: {
-	getCategories: ({ includePackages, basketIdent, ipAddress, }: GetCategories) => Promise<Category[]>;
-};
-export declare const useShopBasketStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<ShopBasketStore>, "subscribe"> & {
+/**
+ * Enumeration of all possible Tebex error codes.
+ * Consumers can use these codes to provide localized error messages.
+ */
+export declare enum TebexErrorCode {
+	PROVIDER_NOT_FOUND = "PROVIDER_NOT_FOUND",
+	INVALID_CONFIG = "INVALID_CONFIG",
+	NOT_AUTHENTICATED = "NOT_AUTHENTICATED",
+	INVALID_USERNAME = "INVALID_USERNAME",
+	BASKET_NOT_FOUND = "BASKET_NOT_FOUND",
+	BASKET_CREATION_FAILED = "BASKET_CREATION_FAILED",
+	BASKET_EXPIRED = "BASKET_EXPIRED",
+	BASKET_EMPTY = "BASKET_EMPTY",
+	PACKAGE_NOT_FOUND = "PACKAGE_NOT_FOUND",
+	PACKAGE_OUT_OF_STOCK = "PACKAGE_OUT_OF_STOCK",
+	PACKAGE_ALREADY_OWNED = "PACKAGE_ALREADY_OWNED",
+	INVALID_QUANTITY = "INVALID_QUANTITY",
+	CATEGORY_NOT_FOUND = "CATEGORY_NOT_FOUND",
+	COUPON_INVALID = "COUPON_INVALID",
+	COUPON_EXPIRED = "COUPON_EXPIRED",
+	COUPON_ALREADY_USED = "COUPON_ALREADY_USED",
+	GIFTCARD_INVALID = "GIFTCARD_INVALID",
+	GIFTCARD_INSUFFICIENT_BALANCE = "GIFTCARD_INSUFFICIENT_BALANCE",
+	CREATOR_CODE_INVALID = "CREATOR_CODE_INVALID",
+	CHECKOUT_FAILED = "CHECKOUT_FAILED",
+	CHECKOUT_CANCELLED = "CHECKOUT_CANCELLED",
+	TEBEX_JS_NOT_LOADED = "TEBEX_JS_NOT_LOADED",
+	NETWORK_ERROR = "NETWORK_ERROR",
+	TIMEOUT = "TIMEOUT",
+	RATE_LIMITED = "RATE_LIMITED",
+	UNKNOWN = "UNKNOWN"
+}
+/**
+ * Custom error class for Tebex SDK errors.
+ * Provides structured error handling with error codes.
+ */
+export declare class TebexError extends Error {
+	readonly code: TebexErrorCode;
+	readonly cause?: unknown;
+	constructor(code: TebexErrorCode, message?: string, cause?: unknown);
+	/**
+	 * Converts an unknown error to a TebexError.
+	 * If the error is already a TebexError, it returns it as-is.
+	 */
+	static fromUnknown(error: unknown): TebexError;
+	/**
+	 * Returns a JSON representation of the error.
+	 */
+	toJSON(): {
+		name: string;
+		code: TebexErrorCode;
+		message: string;
+	};
+}
+/**
+ * URL configuration for checkout redirects.
+ */
+export interface TebexUrls {
+	/** URL to redirect after successful payment. Default: /shop/complete */
+	readonly complete?: string | undefined;
+	/** URL to redirect after cancelled payment. Default: /shop/cancel */
+	readonly cancel?: string | undefined;
+}
+/**
+ * Main configuration for TebexProvider.
+ */
+export interface TebexConfig {
+	/** Your Tebex public/webstore key */
+	readonly publicKey: string;
+	/** Base URL of your site (e.g., https://mysite.com) */
+	readonly baseUrl: string;
+	/** Optional URL paths for checkout redirects */
+	readonly urls?: TebexUrls | undefined;
+	/** Global error handler callback */
+	readonly onError?: ((error: TebexError) => void) | undefined;
+	/** Enable React Query DevTools. Default: true in development */
+	readonly devtools?: boolean | undefined;
+}
+/**
+ * Internal resolved configuration with default values applied.
+ */
+export interface ResolvedTebexConfig {
+	readonly publicKey: string;
+	readonly baseUrl: string;
+	readonly completeUrl: string;
+	readonly cancelUrl: string;
+	readonly onError?: ((error: TebexError) => void) | undefined;
+	readonly devtools: boolean;
+}
+/**
+ * Context value provided by TebexProvider.
+ */
+export interface TebexContextValue {
+	readonly config: ResolvedTebexConfig;
+	readonly queryClient: QueryClient;
+}
+/**
+ * Props for TebexProvider component.
+ */
+export interface TebexProviderProps {
+	readonly children: ReactNode;
+	readonly config: TebexConfig;
+	/** Optional custom QueryClient. If not provided, a default one will be created. */
+	readonly queryClient?: QueryClient | undefined;
+}
+/**
+ * TebexProvider - Main provider component for the Tebex SDK.
+ *
+ * This provider must wrap your application to use any Tebex hooks.
+ * It initializes the Tebex client, sets up React Query, and provides
+ * the configuration context.
+ *
+ * @example
+ * ```tsx
+ * <TebexProvider
+ *   config={{
+ *     publicKey: process.env.NEXT_PUBLIC_TEBEX_KEY!,
+ *     baseUrl: 'https://mysite.com',
+ *     onError: (error) => toast.error(t(`errors.${error.code}`)),
+ *   }}
+ * >
+ *   {children}
+ * </TebexProvider>
+ * ```
+ */
+export declare function TebexProvider({ children, config, queryClient: externalQueryClient, }: TebexProviderProps): ReactNode;
+/**
+ * Hook to access the Tebex context.
+ * Must be used within a TebexProvider.
+ *
+ * @throws TebexError if used outside of TebexProvider
+ */
+export declare function useTebexContext(): TebexContextValue;
+/**
+ * Hook to access just the Tebex configuration.
+ * Useful when you don't need the QueryClient.
+ */
+export declare function useTebexConfig(): ResolvedTebexConfig;
+/**
+ * Base return type for all query hooks.
+ */
+export interface BaseQueryReturn<T> {
+	readonly data: T | null;
+	readonly isLoading: boolean;
+	readonly isFetching: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+	readonly refetch: () => Promise<unknown>;
+}
+/**
+ * Base return type for mutation operations.
+ */
+export interface BaseMutationReturn {
+	readonly isPending: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+}
+export interface UseCategoriesOptions {
+	readonly includePackages?: boolean | undefined;
+	readonly enabled?: boolean | undefined;
+}
+export interface UseCategoriesReturn extends BaseQueryReturn<Category[]> {
+	readonly categories: Category[] | null;
+	readonly getByName: (name: string) => Category | undefined;
+	readonly getById: (id: number) => Category | undefined;
+}
+export interface UseCategoryOptions {
+	readonly id: number;
+	readonly enabled?: boolean | undefined;
+}
+export interface UseCategoryReturn extends BaseQueryReturn<Category> {
+	readonly category: Category | null;
+}
+export interface UsePackagesOptions {
+	readonly categoryId?: number | undefined;
+	readonly enabled?: boolean | undefined;
+}
+export interface UsePackagesReturn extends BaseQueryReturn<Package[]> {
+	readonly packages: Package[] | null;
+	readonly getById: (id: number) => Package | undefined;
+	readonly getByName: (name: string) => Package | undefined;
+}
+export interface UsePackageOptions {
+	readonly id: number;
+	readonly enabled?: boolean | undefined;
+}
+export interface UsePackageReturn extends BaseQueryReturn<Package> {
+	readonly package: Package | null;
+}
+export interface AddPackageParams {
+	readonly packageId: number;
+	readonly quantity?: number | undefined;
+	readonly type?: PackageType | undefined;
+	readonly variableData?: Record<string, string> | undefined;
+}
+export interface UpdateQuantityParams {
+	readonly packageId: number;
+	readonly quantity: number;
+}
+export interface UseBasketReturn extends BaseQueryReturn<Basket> {
+	readonly basket: Basket | null;
+	readonly basketIdent: string | null;
+	readonly packages: BasketPackage[];
+	readonly isAddingPackage: boolean;
+	readonly isRemovingPackage: boolean;
+	readonly isUpdatingQuantity: boolean;
+	readonly addPackage: (params: AddPackageParams) => Promise<void>;
+	readonly removePackage: (packageId: number) => Promise<void>;
+	readonly updateQuantity: (params: UpdateQuantityParams) => Promise<void>;
+	readonly clearBasket: () => void;
+	readonly itemCount: number;
+	readonly total: number;
+	readonly isEmpty: boolean;
+}
+export interface UseCheckoutOptions {
+	readonly onSuccess?: (() => void) | undefined;
+	readonly onError?: ((error: TebexError) => void) | undefined;
+	readonly onClose?: (() => void) | undefined;
+}
+export interface UseCheckoutReturn {
+	readonly launch: () => Promise<void>;
+	readonly isLaunching: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+	readonly canCheckout: boolean;
+	readonly checkoutUrl: string | null;
+}
+export interface UseCouponsReturn {
+	readonly coupons: Code[];
+	readonly apply: (couponCode: string) => Promise<void>;
+	readonly remove: (couponCode: string) => Promise<void>;
+	readonly isApplying: boolean;
+	readonly isRemoving: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+}
+export interface UseGiftCardsReturn {
+	readonly giftCards: GiftCardCode[];
+	readonly apply: (cardNumber: string) => Promise<void>;
+	readonly remove: (cardNumber: string) => Promise<void>;
+	readonly isApplying: boolean;
+	readonly isRemoving: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+}
+export interface UseCreatorCodesReturn {
+	readonly creatorCode: string | null;
+	readonly apply: (code: string) => Promise<void>;
+	readonly remove: () => Promise<void>;
+	readonly isApplying: boolean;
+	readonly isRemoving: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+}
+export interface WebstoreData {
+	readonly id: number;
+	readonly name: string;
+	readonly description: string;
+	readonly currency: string;
+	readonly domain: string;
+	readonly logo: string | null;
+}
+export interface UseWebstoreReturn extends BaseQueryReturn<WebstoreData> {
+	readonly webstore: WebstoreData | null;
+	readonly name: string | null;
+	readonly currency: string | null;
+	readonly domain: string | null;
+}
+export interface UseUserReturn {
+	readonly username: string | null;
+	readonly setUsername: (username: string) => void;
+	readonly clearUsername: () => void;
+	readonly isAuthenticated: boolean;
+}
+export interface GiftPackageParams {
+	readonly packageId: number;
+	readonly targetUsername: string;
+	readonly quantity?: number | undefined;
+}
+export interface UseGiftPackageReturn {
+	readonly gift: (params: GiftPackageParams) => Promise<void>;
+	readonly isGifting: boolean;
+	readonly error: TebexError | null;
+	readonly errorCode: TebexErrorCode | null;
+}
+/**
+ * Hook to manage the shopping basket with optimistic updates.
+ *
+ * @returns Basket data, actions, and computed values
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   basket,
+ *   packages,
+ *   addPackage,
+ *   removePackage,
+ *   itemCount,
+ *   total,
+ *   isAddingPackage,
+ * } = useBasket();
+ *
+ * const handleAddToCart = async (packageId: number) => {
+ *   await addPackage({ packageId, quantity: 1 });
+ * };
+ * ```
+ */
+export declare function useBasket(): UseBasketReturn;
+/**
+ * Hook to fetch all categories from the Tebex store.
+ *
+ * @param options - Configuration options
+ * @returns Categories data and helper methods
+ *
+ * @example
+ * ```tsx
+ * const { categories, isLoading, getByName } = useCategories();
+ *
+ * if (isLoading) return <Spinner />;
+ *
+ * const vipCategory = getByName('VIP');
+ * ```
+ */
+export declare function useCategories(options?: UseCategoriesOptions): UseCategoriesReturn;
+/**
+ * Hook to fetch a single category by ID.
+ *
+ * @param options - Configuration options including the category ID
+ * @returns Category data
+ *
+ * @example
+ * ```tsx
+ * const { category, isLoading } = useCategory({ id: 123 });
+ *
+ * if (isLoading) return <Spinner />;
+ * if (!category) return <NotFound />;
+ *
+ * return <CategoryDisplay category={category} />;
+ * ```
+ */
+export declare function useCategory(options: UseCategoryOptions): UseCategoryReturn;
+/**
+ * Hook to launch the Tebex checkout modal.
+ *
+ * @param options - Checkout callbacks
+ * @returns Checkout state and launch function
+ *
+ * @example
+ * ```tsx
+ * const { launch, canCheckout, isLaunching } = useCheckout({
+ *   onSuccess: () => router.push('/thank-you'),
+ *   onError: (error) => toast.error(error.message),
+ * });
+ *
+ * return (
+ *   <button onClick={launch} disabled={!canCheckout || isLaunching}>
+ *     Checkout
+ *   </button>
+ * );
+ * ```
+ */
+export declare function useCheckout(options?: UseCheckoutOptions): UseCheckoutReturn;
+/**
+ * Hook to manage coupons on the basket.
+ *
+ * @returns Coupon state and actions
+ *
+ * @example
+ * ```tsx
+ * const { coupons, apply, remove, isApplying } = useCoupons();
+ *
+ * const handleApply = async (code: string) => {
+ *   try {
+ *     await apply(code);
+ *     toast.success('Coupon applied!');
+ *   } catch (error) {
+ *     toast.error('Invalid coupon');
+ *   }
+ * };
+ * ```
+ */
+export declare function useCoupons(): UseCouponsReturn;
+/**
+ * Hook to manage creator codes on the basket.
+ *
+ * @returns Creator code state and actions
+ *
+ * @example
+ * ```tsx
+ * const { creatorCode, apply, remove, isApplying } = useCreatorCodes();
+ *
+ * const handleApply = async (code: string) => {
+ *   try {
+ *     await apply(code);
+ *     toast.success('Creator code applied!');
+ *   } catch (error) {
+ *     toast.error('Invalid creator code');
+ *   }
+ * };
+ * ```
+ */
+export declare function useCreatorCodes(): UseCreatorCodesReturn;
+/**
+ * Hook to manage gift cards on the basket.
+ *
+ * @returns Gift card state and actions
+ *
+ * @example
+ * ```tsx
+ * const { giftCards, apply, remove, isApplying } = useGiftCards();
+ *
+ * const handleApply = async (cardNumber: string) => {
+ *   try {
+ *     await apply(cardNumber);
+ *     toast.success('Gift card applied!');
+ *   } catch (error) {
+ *     toast.error('Invalid gift card');
+ *   }
+ * };
+ * ```
+ */
+export declare function useGiftCards(): UseGiftCardsReturn;
+/**
+ * Hook to gift a package to another player.
+ *
+ * @returns Gift package state and action
+ *
+ * @example
+ * ```tsx
+ * const { gift, isGifting, error } = useGiftPackage();
+ *
+ * const handleGift = async () => {
+ *   await gift({
+ *     packageId: 123,
+ *     targetUsername: 'FriendName',
+ *     quantity: 1,
+ *   });
+ * };
+ * ```
+ */
+export declare function useGiftPackage(): UseGiftPackageReturn;
+/**
+ * Hook to fetch a single package by ID.
+ *
+ * @param options - Configuration options including the package ID
+ * @returns Package data
+ *
+ * @example
+ * ```tsx
+ * const { package: pkg, isLoading } = usePackage({ id: 123 });
+ *
+ * if (isLoading) return <Spinner />;
+ * if (!pkg) return <NotFound />;
+ *
+ * return <PackageDisplay package={pkg} />;
+ * ```
+ */
+export declare function usePackage(options: UsePackageOptions): UsePackageReturn;
+/**
+ * Hook to fetch all packages from the Tebex store.
+ * Optionally filter by category.
+ *
+ * @param options - Configuration options
+ * @returns Packages data and helper methods
+ *
+ * @example
+ * ```tsx
+ * const { packages, isLoading, getById } = usePackages();
+ *
+ * // Or filter by category
+ * const { packages } = usePackages({ categoryId: 123 });
+ * ```
+ */
+export declare function usePackages(options?: UsePackagesOptions): UsePackagesReturn;
+/**
+ * Hook to manage the current user (Minecraft username).
+ * Username is persisted in localStorage.
+ *
+ * @returns User state and actions
+ *
+ * @example
+ * ```tsx
+ * const { username, setUsername, isAuthenticated } = useUser();
+ *
+ * if (!isAuthenticated) {
+ *   return <UsernameForm onSubmit={setUsername} />;
+ * }
+ *
+ * return <p>Welcome, {username}!</p>;
+ * ```
+ */
+export declare function useUser(): UseUserReturn;
+/**
+ * Hook to fetch webstore information.
+ *
+ * @returns Webstore data including name, currency, and domain
+ *
+ * @example
+ * ```tsx
+ * const { webstore, currency, isLoading } = useWebstore();
+ *
+ * if (isLoading) return <Spinner />;
+ *
+ * return (
+ *   <div>
+ *     <h1>{webstore?.name}</h1>
+ *     <p>Currency: {currency}</p>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useWebstore(): UseWebstoreReturn;
+/**
+ * Basket store state interface.
+ */
+export interface BasketStoreState {
+	readonly basketIdent: string | null;
+}
+/**
+ * Basket store actions interface.
+ */
+export interface BasketStoreActions {
+	readonly setBasketIdent: (ident: string) => void;
+	readonly clearBasketIdent: () => void;
+}
+/**
+ * Complete basket store type.
+ */
+export type BasketStore = BasketStoreState & BasketStoreActions;
+/**
+ * Zustand store for basket ident persistence.
+ * Uses localStorage to persist the basket ident across sessions.
+ */
+export declare const useBasketStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<BasketStore>, "subscribe"> & {
 	subscribe: {
-		(listener: (selectedState: ShopBasketStore, previousSelectedState: ShopBasketStore) => void): () => void;
-		<U>(selector: (state: ShopBasketStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
-			equalityFn?: ((a: U, b: U) => boolean) | undefined;
-			fireImmediately?: boolean | undefined;
+		(listener: (selectedState: BasketStore, previousSelectedState: BasketStore) => void): () => void;
+		<U>(selector: (state: BasketStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+			equalityFn?: (a: U, b: U) => boolean;
+			fireImmediately?: boolean;
 		} | undefined): () => void;
 	};
 }, "persist"> & {
 	persist: {
-		setOptions: (options: Partial<import("zustand/middleware").PersistOptions<ShopBasketStore, ShopBasketStore>>) => void;
+		setOptions: (options: Partial<import("zustand/middleware").PersistOptions<BasketStore, BasketStore>>) => void;
 		clearStorage: () => void;
 		rehydrate: () => void | Promise<void>;
 		hasHydrated: () => boolean;
-		onHydrate: (fn: (state: ShopBasketStore) => void) => () => void;
-		onFinishHydration: (fn: (state: ShopBasketStore) => void) => () => void;
-		getOptions: () => Partial<import("zustand/middleware").PersistOptions<ShopBasketStore, ShopBasketStore>>;
+		onHydrate: (fn: (state: BasketStore) => void) => () => void;
+		onFinishHydration: (fn: (state: BasketStore) => void) => () => void;
+		getOptions: () => Partial<import("zustand/middleware").PersistOptions<BasketStore, BasketStore>>;
 	};
 }>;
-export interface ShopUiStore {
-	isGlobalLoading: boolean;
-	setIsGlobalLoading: (isGlobalLoading: boolean) => void;
-	isCreatingBasket: boolean;
-	setIsCreatingBasket: (isCreatingBasket: boolean) => void;
+/**
+ * User store state interface.
+ */
+export interface UserStoreState {
+	readonly username: string | null;
 }
-export declare const useShopUiStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<ShopUiStore>, "subscribe"> & {
-	subscribe: {
-		(listener: (selectedState: ShopUiStore, previousSelectedState: ShopUiStore) => void): () => void;
-		<U>(selector: (state: ShopUiStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
-			equalityFn?: ((a: U, b: U) => boolean) | undefined;
-			fireImmediately?: boolean | undefined;
-		} | undefined): () => void;
-	};
-}>;
-export interface ShopUserStore {
-	username: string;
-	setUsername: (username: string) => void;
-	clearUsername: () => void;
+/**
+ * User store actions interface.
+ */
+export interface UserStoreActions {
+	readonly setUsername: (username: string) => void;
+	readonly clearUsername: () => void;
 }
-declare const shopUserStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<ShopUserStore>, "subscribe"> & {
+/**
+ * Complete user store type.
+ */
+export type UserStore = UserStoreState & UserStoreActions;
+/**
+ * Zustand store for user data persistence.
+ * Uses localStorage to persist the username (Minecraft username) across sessions.
+ */
+export declare const useUserStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<UserStore>, "subscribe"> & {
 	subscribe: {
-		(listener: (selectedState: ShopUserStore, previousSelectedState: ShopUserStore) => void): () => void;
-		<U>(selector: (state: ShopUserStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
-			equalityFn?: ((a: U, b: U) => boolean) | undefined;
-			fireImmediately?: boolean | undefined;
+		(listener: (selectedState: UserStore, previousSelectedState: UserStore) => void): () => void;
+		<U>(selector: (state: UserStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+			equalityFn?: (a: U, b: U) => boolean;
+			fireImmediately?: boolean;
 		} | undefined): () => void;
 	};
 }, "persist"> & {
 	persist: {
-		setOptions: (options: Partial<import("zustand/middleware").PersistOptions<ShopUserStore, ShopUserStore>>) => void;
+		setOptions: (options: Partial<import("zustand/middleware").PersistOptions<UserStore, UserStore>>) => void;
 		clearStorage: () => void;
 		rehydrate: () => void | Promise<void>;
 		hasHydrated: () => boolean;
-		onHydrate: (fn: (state: ShopUserStore) => void) => () => void;
-		onFinishHydration: (fn: (state: ShopUserStore) => void) => () => void;
-		getOptions: () => Partial<import("zustand/middleware").PersistOptions<ShopUserStore, ShopUserStore>>;
+		onHydrate: (fn: (state: UserStore) => void) => () => void;
+		onFinishHydration: (fn: (state: UserStore) => void) => () => void;
+		getOptions: () => Partial<import("zustand/middleware").PersistOptions<UserStore, UserStore>>;
 	};
 }>;
+/**
+ * Query keys factory for TanStack Query.
+ * Follows the recommended pattern for granular cache invalidation.
+ *
+ * @see https://tkdodo.eu/blog/effective-react-query-keys
+ */
+export declare const tebexKeys: {
+	/** Root key for all Tebex queries */
+	readonly all: readonly [
+		"tebex"
+	];
+	/** All category-related queries */
+	readonly categories: () => readonly [
+		"tebex",
+		"categories"
+	];
+	/** Categories list with include packages option */
+	readonly categoriesList: (includePackages: boolean) => readonly [
+		"tebex",
+		"categories",
+		"list",
+		{
+			readonly includePackages: boolean;
+		}
+	];
+	/** Single category by ID */
+	readonly category: (id: number) => readonly [
+		"tebex",
+		"categories",
+		"detail",
+		number
+	];
+	/** All package-related queries */
+	readonly packages: () => readonly [
+		"tebex",
+		"packages"
+	];
+	/** Packages list, optionally filtered by category */
+	readonly packagesList: (categoryId?: number) => readonly [
+		"tebex",
+		"packages",
+		"list",
+		{
+			readonly categoryId: number | undefined;
+		}
+	];
+	/** Single package by ID */
+	readonly package: (id: number) => readonly [
+		"tebex",
+		"packages",
+		"detail",
+		number
+	];
+	/** All basket-related queries */
+	readonly baskets: () => readonly [
+		"tebex",
+		"baskets"
+	];
+	/** Specific basket by ident */
+	readonly basket: (ident: string | null) => readonly [
+		"tebex",
+		"baskets",
+		string | null
+	];
+	/** Webstore info query */
+	readonly webstore: () => readonly [
+		"tebex",
+		"webstore"
+	];
+};
+/**
+ * Discriminated union for type-safe result handling.
+ * Use this for operations that can fail.
+ */
+export type Result<T, E = TebexError> = {
+	readonly success: true;
+	readonly data: T;
+} | {
+	readonly success: false;
+	readonly error: E;
+};
+/**
+ * Creates a successful result.
+ */
+export declare function ok<T>(data: T): Result<T, never>;
+/**
+ * Creates an error result.
+ */
+export declare function err<E>(error: E): Result<never, E>;
+/**
+ * Type guard to check if an error is a TebexError.
+ */
+export declare function isTebexError(error: unknown): error is TebexError;
+/**
+ * Type guard to check if a Result is successful.
+ */
+export declare function isSuccess<T, E>(result: Result<T, E>): result is {
+	readonly success: true;
+	readonly data: T;
+};
+/**
+ * Type guard to check if a Result is an error.
+ */
+export declare function isError<T, E>(result: Result<T, E>): result is {
+	readonly success: false;
+	readonly error: E;
+};
+/**
+ * Type guard to check if a value is defined (not null or undefined).
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Returns the initialized Tebex client.
+ * Throws if the client has not been initialized.
+ */
+export declare function getTebexClient(): TebexHeadless;
+/**
+ * Checks if the Tebex client is initialized.
+ */
+export declare function isTebexClientInitialized(): boolean;
 
 export {
-	shopUserStore as useShopUserStore,
+	Basket,
+	BasketPackage,
+	Category,
+	Code,
+	GiftCardCode,
+	Package,
+	PackageType,
+	Webstore,
 };
 
 export {};