@b3dotfun/sdk 0.0.70-alpha.0 → 0.0.70-alpha.1

package/dist/types/anyspend/utils/validation.d.ts

@@ -0,0 +1,67 @@
+export interface ValidationResult {
+    isValid: boolean;
+    error?: string;
+    cleaned?: string;
+}
+export interface StringValidationOptions {
+    required?: boolean;
+    defaultValue?: () => string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    patternErrorMessage?: string;
+    trim?: boolean;
+    toLowerCase?: boolean;
+    toUpperCase?: boolean;
+    customValidator?: (value: string) => {
+        valid: boolean;
+        error?: string;
+    };
+}
+/**
+ * Generic string validator with configurable rules
+ */
+export declare function validateString(value: string | undefined, options: StringValidationOptions): ValidationResult;
+/**
+ * Common validation patterns
+ */
+export declare const ValidationPatterns: {
+    readonly ALPHANUMERIC: RegExp;
+    readonly ALPHANUMERIC_WITH_DASH_UNDERSCORE: RegExp;
+    readonly ALPHANUMERIC_WITH_SAFE_CHARS: RegExp;
+    readonly SAFE_IDENTIFIER: RegExp;
+    readonly NO_CONTROL_CHARS: RegExp;
+    readonly URL_SAFE: RegExp;
+    readonly NUMERIC: RegExp;
+    readonly HEX: RegExp;
+};
+/**
+ * Pre-configured validators for common use cases
+ */
+export declare const Validators: {
+    /**
+     * Validates client reference IDs (alphanumeric + safe chars)
+     * Returns undefined if not provided
+     */
+    clientReferenceId: (value?: string) => ValidationResult;
+    /**
+     * Validates alphanumeric strings (letters and numbers only)
+     */
+    alphanumeric: (value?: string, required?: boolean) => ValidationResult;
+    /**
+     * Validates wallet addresses (hex format)
+     */
+    walletAddress: (value?: string, required?: boolean) => ValidationResult;
+    /**
+     * Validates order IDs (UUID format)
+     */
+    orderId: (value?: string) => ValidationResult;
+    /**
+     * Validates URL-safe strings
+     */
+    urlSafe: (value?: string, maxLength?: number) => ValidationResult;
+    /**
+     * Validates safe identifiers (no injection risks)
+     */
+    safeIdentifier: (value?: string, required?: boolean) => ValidationResult;
+};

package/dist/types/global-account/react/stores/useModalStore.d.ts

@@ -122,6 +122,8 @@ export interface AnySpendModalProps extends BaseModalProps {
     destinationTokenChainId?: number;
     /** Custom USD input values for quick amount buttons in fiat onramp */
     customUsdInputValues?: string[];
+    /** Client-provided reference ID for tracking orders */
+    clientReferenceId?: string;
 }
 /**
  * Props for the AnySpend NFT modal
@@ -136,6 +138,8 @@ export interface AnySpendNftProps extends BaseModalProps {
     recipientAddress?: string;
     /** Callback function called when the NFT is successfully transferred */
     onSuccess?: (txHash?: string) => void;
+    /** Client-provided reference ID for tracking orders */
+    clientReferenceId?: string;
 }
 /**
  * Props for the AnySpend tournament modal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b3dotfun/sdk",
-  "version": "0.0.70-alpha.0",
+  "version": "0.0.70-alpha.1",
   "source": "src/index.ts",
   "main": "./dist/cjs/index.js",
   "react-native": "./dist/cjs/index.native.js",

package/src/anyspend/index.ts

@@ -9,6 +9,7 @@ export * from "./utils/json";
 export * from "./utils/number";
 export * from "./utils/string";
 export * from "./utils/token";
+export * from "./utils/validation";
 
 // Constants
 export * from "./constants";

package/src/anyspend/react/components/AnySpend.tsx

@@ -8,6 +8,7 @@ import {
   useAnyspendQuote,
   useGeoOnrampOptions,
 } from "@b3dotfun/sdk/anyspend/react";
+import { Validators } from "@b3dotfun/sdk/anyspend/utils/validation";
 import {
   Button,
   ShinyButton,
@@ -87,6 +88,12 @@ export function AnySpend(props: {
   onTokenSelect?: (token: components["schemas"]["Token"], event: { preventDefault: () => void }) => void;
   onSuccess?: (txHash?: string) => void;
   customUsdInputValues?: string[];
+  /**
+   * Client-provided reference ID for tracking orders.
+   * Must be alphanumeric with optional hyphens, underscores, and dots (max 255 chars).
+   * Auto-generates UUID if not provided.
+   */
+  clientReferenceId?: string;
 }) {
   const fingerprintConfig = getFingerprintConfig();
 
@@ -108,6 +115,7 @@ function AnySpendInner({
   onTokenSelect,
   onSuccess,
   customUsdInputValues,
+  clientReferenceId: clientReferenceIdFromProps,
 }: {
   destinationTokenAddress?: string;
   destinationTokenChainId?: number;
@@ -119,10 +127,23 @@ function AnySpendInner({
   onTokenSelect?: (token: components["schemas"]["Token"], event: { preventDefault: () => void }) => void;
   onSuccess?: (txHash?: string) => void;
   customUsdInputValues?: string[];
+  clientReferenceId?: string;
 }) {
   const searchParams = useSearchParamsSSR();
   const router = useRouter();
 
+  // Validate and clean clientReferenceId
+  const validatedClientReferenceId = useMemo(() => {
+    const validation = Validators.clientReferenceId(clientReferenceIdFromProps);
+    if (!validation.isValid) {
+      console.error(
+        `[AnySpend] Invalid clientReferenceId: ${validation.error || "Validation failed"}. Will be set to undefined.`,
+      );
+      return undefined;
+    }
+    return validation.cleaned;
+  }, [clientReferenceIdFromProps]);
+
   // Determine if we're in "buy mode" based on whether destination token props are provided
   const isBuyMode = !!(destinationTokenAddress && destinationTokenChainId);
 
@@ -823,6 +844,7 @@ function AnySpendInner({
         srcAmount: srcAmountBigInt.toString(),
         expectedDstAmount: anyspendQuote?.data?.currencyOut?.amount || "0",
         creatorAddress: globalAddress,
+        clientReferenceId: validatedClientReferenceId,
       });
     } catch (err: any) {
       console.error(err);
@@ -891,6 +913,7 @@ function AnySpendInner({
         },
         expectedDstAmount: anyspendQuote?.data?.currencyOut?.amount?.toString() || "0",
         creatorAddress: globalAddress,
+        clientReferenceId: validatedClientReferenceId,
       });
     } catch (err: any) {
       console.error(err);

package/src/anyspend/react/components/AnySpendBondKit.tsx

@@ -38,7 +38,8 @@ export function AnySpendBondKit({
   imageUrl,
   b3Amount: initialB3Amount,
   onSuccess,
-}: AnySpendBondKitProps) {
+  clientReferenceId,
+}: AnySpendBondKitProps & { clientReferenceId?: string }) {
   const hasMounted = useHasMounted();
   const [showAmountPrompt, setShowAmountPrompt] = useState(!initialB3Amount);
   const [b3Amount, setB3Amount] = useState(initialB3Amount || "");
@@ -371,6 +372,7 @@ export function AnySpendBondKit({
       header={header}
       onSuccess={onSuccess}
       showRecipient={true}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendBuySpin.tsx

@@ -129,6 +129,7 @@ export function AnySpendBuySpin({
   recipientAddress,
   prefillQuantity,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -137,6 +138,7 @@ export function AnySpendBuySpin({
   recipientAddress: string;
   prefillQuantity?: string;
   onSuccess?: (txHash?: string) => void;
+  clientReferenceId?: string;
 }) {
   const hasMounted = useHasMounted();
   const { setB3ModalOpen } = useModalStore();
@@ -680,6 +682,7 @@ export function AnySpendBuySpin({
       header={header}
       onSuccess={txHash => onSuccess?.(txHash)}
       showRecipient={false}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendCustom.tsx

@@ -187,6 +187,7 @@ export function AnySpendCustom(props: {
   onSuccess?: (txHash?: string) => void;
   showRecipient?: boolean;
   onShowPointsDetail?: () => void;
+  clientReferenceId?: string;
 }) {
   const fingerprintConfig = getFingerprintConfig();
 
@@ -214,6 +215,7 @@ function AnySpendCustomInner({
   onSuccess,
   showRecipient = true,
   onShowPointsDetail,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -237,6 +239,7 @@ function AnySpendCustomInner({
   onSuccess?: (txHash?: string) => void;
   showRecipient?: boolean;
   onShowPointsDetail?: () => void;
+  clientReferenceId?: string;
 }) {
   const hasMounted = useHasMounted();
   const featureFlags = useFeatureFlags();
@@ -532,9 +535,13 @@ function AnySpendCustomInner({
                 : window.location.origin,
           },
           expectedDstAmount: anyspendQuote?.data?.currencyOut?.amount?.toString() || "0",
+          clientReferenceId: clientReferenceId,
         });
       } else {
-        void createRegularOrder(createOrderParams);
+        void createRegularOrder({
+          ...createOrderParams,
+          clientReferenceId: clientReferenceId,
+        });
       }
     } catch (err) {
       console.error(err);

package/src/anyspend/react/components/AnySpendCustomExactIn.tsx

@@ -57,6 +57,7 @@ export interface AnySpendCustomExactInProps {
     anyspendPrice: GetQuoteResponse | undefined;
     isLoadingAnyspendPrice: boolean;
   }) => React.JSX.Element;
+  clientReferenceId?: string;
 }
 
 export function AnySpendCustomExactIn(props: AnySpendCustomExactInProps) {
@@ -87,6 +88,7 @@ function AnySpendCustomExactInInner({
   orderType = "custom_exact_in",
   minDestinationAmount,
   header,
+  clientReferenceId,
 }: AnySpendCustomExactInProps) {
   const actionLabel = customExactInConfig?.action ?? "Custom Execution";
 
@@ -433,6 +435,7 @@ function AnySpendCustomExactInInner({
         expectedDstAmount: expectedDstAmountRaw,
         creatorAddress: globalAddress,
         payload,
+        clientReferenceId: clientReferenceId,
       });
     } catch (err: any) {
       console.error(err);
@@ -488,6 +491,7 @@ function AnySpendCustomExactInInner({
         expectedDstAmount: expectedDstAmountRaw,
         creatorAddress: globalAddress,
         payload,
+        clientReferenceId: clientReferenceId,
       });
     } catch (err: any) {
       console.error(err);

package/src/anyspend/react/components/AnySpendDepositUpside.tsx

@@ -33,6 +33,7 @@ export function AnySpendDepositUpside({
   depositContractAddress,
   token,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -42,6 +43,7 @@ export function AnySpendDepositUpside({
   depositContractAddress: string;
   token: components["schemas"]["Token"];
   onSuccess?: (amount: string) => void;
+  clientReferenceId?: string;
 }) {
   if (!recipientAddress) return null;
 
@@ -76,6 +78,7 @@ export function AnySpendDepositUpside({
       customExactInConfig={customExactInConfig}
       header={header}
       onSuccess={onSuccess}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendNFT.tsx

@@ -37,6 +37,7 @@ export function AnySpendNFT({
   nftContract,
   onSuccess,
   onShowPointsDetail,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -44,6 +45,7 @@ export function AnySpendNFT({
   nftContract: components["schemas"]["NftContract"];
   onSuccess?: (txHash?: string) => void;
   onShowPointsDetail?: () => void;
+  clientReferenceId?: string;
 }) {
   const [imageUrlWithFallback, setFallbackImageUrl] = useState<string | null>(nftContract.imageUrl);
   const [isLoadingFallback, setIsLoadingFallback] = useState(false);
@@ -167,6 +169,7 @@ export function AnySpendNFT({
       header={header}
       onSuccess={onSuccess}
       onShowPointsDetail={onShowPointsDetail}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendStakeB3.tsx

@@ -48,12 +48,14 @@ export function AnySpendStakeB3({
   recipientAddress,
   stakeAmount,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
   recipientAddress: string;
   stakeAmount?: string;
   onSuccess?: () => void;
+  clientReferenceId?: string;
 }) {
   const hasMounted = useHasMounted();
   const { setB3ModalOpen } = useModalStore();
@@ -506,6 +508,7 @@ export function AnySpendStakeB3({
       header={header}
       onSuccess={onSuccess}
       showRecipient={true}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendStakeB3ExactIn.tsx

@@ -53,6 +53,7 @@ export function AnySpendStakeB3ExactIn({
   recipientAddress,
   stakeAmount,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -61,6 +62,7 @@ export function AnySpendStakeB3ExactIn({
   recipientAddress: string;
   stakeAmount?: string;
   onSuccess?: (amount: string) => void;
+  clientReferenceId?: string;
 }) {
   const hasMounted = useHasMounted();
   const { setB3ModalOpen } = useModalStore();
@@ -517,6 +519,7 @@ export function AnySpendStakeB3ExactIn({
       customExactInConfig={customExactInConfig}
       header={header}
       onSuccess={onSuccess}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendStakeUpside.tsx

@@ -25,6 +25,7 @@ export function AnySpendStakeUpside({
   token,
   onSuccess,
   activeTab,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -34,6 +35,7 @@ export function AnySpendStakeUpside({
   token: components["schemas"]["Token"];
   onSuccess?: () => void;
   activeTab?: "crypto" | "fiat";
+  clientReferenceId?: string;
 }) {
   const header = () => (
     <>
@@ -80,6 +82,7 @@ export function AnySpendStakeUpside({
       onSuccess={onSuccess}
       showRecipient={true}
       activeTab={activeTab}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendStakeUpsideExactIn.tsx

@@ -25,6 +25,7 @@ export function AnySpendStakeUpsideExactIn({
   stakingContractAddress,
   token,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
@@ -34,6 +35,7 @@ export function AnySpendStakeUpsideExactIn({
   stakingContractAddress: string;
   token: components["schemas"]["Token"];
   onSuccess?: (amount: string) => void;
+  clientReferenceId?: string;
 }) {
   if (!recipientAddress) return null;
 
@@ -68,6 +70,7 @@ export function AnySpendStakeUpsideExactIn({
       customExactInConfig={customExactInConfig}
       header={header}
       onSuccess={onSuccess}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnySpendTournament.tsx

@@ -17,6 +17,7 @@ type AnySpendTournamentProps =
       tournamentEntryToken: components["schemas"]["Token"];
       tournamentEntryFee: string;
       onSuccess?: () => void;
+      clientReferenceId?: string;
     }
   | {
       mode?: "modal" | "page";
@@ -28,6 +29,7 @@ type AnySpendTournamentProps =
       tournamentFundToken: components["schemas"]["Token"];
       tournamentFundAmount: string;
       onSuccess?: () => void;
+      clientReferenceId?: string;
     };
 
 export function AnySpendTournament(props: AnySpendTournamentProps) {
@@ -104,6 +106,7 @@ export function AnySpendTournament(props: AnySpendTournamentProps) {
       header={header}
       onSuccess={onSuccess}
       showRecipient={action === "join"}
+      clientReferenceId={props.clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnyspendDepositHype.tsx

@@ -24,6 +24,7 @@ export interface AnySpendDepositHypeProps {
   onTokenSelect?: (token: components["schemas"]["Token"], event: { preventDefault: () => void }) => void;
   customUsdInputValues?: string[];
   preferEoa?: boolean;
+  clientReferenceId?: string;
 }
 
 export function AnySpendDepositHype({
@@ -38,6 +39,7 @@ export function AnySpendDepositHype({
   onTokenSelect,
   customUsdInputValues,
   preferEoa,
+  clientReferenceId,
 }: AnySpendDepositHypeProps) {
   if (!recipientAddress) return null;
 
@@ -79,6 +81,7 @@ export function AnySpendDepositHype({
       onTokenSelect={onTokenSelect}
       customUsdInputValues={customUsdInputValues}
       preferEoa={preferEoa}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/components/AnyspendSignatureMint.tsx

@@ -47,12 +47,14 @@ export function AnyspendSignatureMint({
   signatureData,
   imageUrl,
   onSuccess,
+  clientReferenceId,
 }: {
   loadOrder?: string;
   mode?: "modal" | "page";
   signatureData: GenerateSigMintResponse;
   imageUrl?: string;
   onSuccess?: (txHash?: string) => void;
+  clientReferenceId?: string;
 }) {
   // Get token data
   const {
@@ -149,6 +151,7 @@ export function AnyspendSignatureMint({
       header={header}
       onSuccess={onSuccess}
       showRecipient={true}
+      clientReferenceId={clientReferenceId}
     />
   );
 }

package/src/anyspend/react/hooks/useAnyspendCreateOnrampOrder.ts

@@ -55,6 +55,7 @@ export function useAnyspendCreateOnrampOrder({ onSuccess, onError }: UseAnyspend
         tournament,
         payload,
         partnerId,
+        clientReferenceId,
       } = params;
 
       try {
@@ -102,6 +103,7 @@ export function useAnyspendCreateOnrampOrder({ onSuccess, onError }: UseAnyspend
           }),
           creatorAddress: creatorAddress ? normalizeAddress(creatorAddress) : undefined,
           partnerId,
+          clientReferenceId,
           visitorData,
         });
       } catch (error: any) {

package/src/anyspend/react/hooks/useAnyspendCreateOrder.ts

@@ -20,6 +20,7 @@ export type CreateOrderParams = {
   creatorAddress?: string;
   payload?: any;
   partnerId?: string;
+  clientReferenceId?: string;
 };
 
 export type UseAnyspendCreateOrderProps = {
@@ -41,7 +42,17 @@ export function useAnyspendCreateOrder({ onSuccess, onError }: UseAnyspendCreate
   };
   const { mutate: createOrder, isPending } = useMutation({
     mutationFn: async (params: CreateOrderParams) => {
-      const { recipientAddress, orderType, srcChain, dstChain, srcToken, dstToken, srcAmount, creatorAddress } = params;
+      const {
+        recipientAddress,
+        orderType,
+        srcChain,
+        dstChain,
+        srcToken,
+        dstToken,
+        srcAmount,
+        creatorAddress,
+        clientReferenceId,
+      } = params;
 
       try {
         return await anyspendService.createOrder({
@@ -75,6 +86,7 @@ export function useAnyspendCreateOrder({ onSuccess, onError }: UseAnyspendCreate
             },
           }),
           creatorAddress: creatorAddress ? normalizeAddress(creatorAddress) : undefined,
+          clientReferenceId,
           visitorData,
         });
       } catch (error: any) {

package/src/anyspend/services/anyspend.ts

@@ -67,6 +67,7 @@ export const anyspendService = {
     metadata,
     creatorAddress,
     partnerId,
+    clientReferenceId,
     visitorData,
   }: {
     recipientAddress: string;
@@ -81,6 +82,7 @@ export const anyspendService = {
     metadata: Record<string, any>;
     creatorAddress?: string;
     partnerId?: string;
+    clientReferenceId?: string;
     visitorData?: VisitorData;
   }) => {
     const response = await fetch(`${ANYSPEND_MAINNET_BASE_URL}/orders`, {
@@ -103,6 +105,7 @@ export const anyspendService = {
         metadata,
         creatorAddress,
         partnerId,
+        ...(clientReferenceId && { clientReferenceId }),
       }),
     });
     const data: CreateOrderResponse = await response.json();