> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Support

> Add type definitions for the Mage SDK in your TypeScript project.

The Mage SDK is injected into the storefront at runtime via `window.MageSDK`. Since it isn't an npm package, TypeScript won't know about it by default. You can add full type support by creating a declaration file in your project.

## Setup

Create a file called `mage-sdk.d.ts` anywhere in your project (e.g. the root, or a `types/` folder):

```typescript mage-sdk.d.ts theme={null}
interface MageSDKResponse<T = unknown> {
  success: boolean;
  error?: string;
  data?: T;
}

interface MageVipTier {
  id: string;
  name: string;
  description: string | null;
  pointsRequired: number;
  pointsMultiplier: number;
  badgeImageUrl: string | null;
  badgeColor: string | null;
  rewards: Array<{
    id: string;
    name: string;
    discountType: string | null;
    discountAmount: number | null;
    pointsCost: number;
    isActive: boolean;
  }>;
}

interface MageCustomerDetails {
  id: string;
  shopifyCustomerId: string;
  email: string;
  firstName: string;
  lastName: string;
  points: number;
  lifetimePoints: number;
  redeemedPoints: number;
  isExcluded: boolean;
  dateOfBirth: string | null;
  referralCode: string | null;
  referralUrl: string | null;
  tier: MageVipTier | null;
  tierProgressValue: number;
  earningHistory: Array<{
    id: string;
    earningRuleId: string;
    status: string;
    points: number;
    createdAt: string;
    earningRule: { id: string; name: string };
  }>;
  referralEarnings: Array<{
    id: string;
    type: string;
    status: string;
    friendEmail: string;
    createdAt: string;
  }>;
  createdAt: string;
  updatedAt: string;
}

interface MageReward {
  id: string;
  name: string;
  description: string;
  pointsCost: number;
  category: string;
  discountType: string | null;
  tier: MageVipTier | null;
  minimumSpend?: string;
  productMetadata?: {
    productId?: string;
    productTitle?: string;
    productImage?: string | null;
    productHandle?: string | null;
  } | null;
}

interface MageCustomerReward {
  id: string;
  rewardName: string;
  rewardDescription?: string;
  points: number;
  discountCode: string;
  discountType?: string | null;
  status: string;
  createdAt: string;
  expiresAt: string | null;
}

interface MageEarningRule {
  id: string;
  name: string;
  description: string | null;
  action: string;
  category: string;
  isActive: boolean;
  pointsToGive: number;
  customerFacingLabel: string | null;
  callToActionUrl: string | null;
  customerEarningRule?: {
    id: string;
    earningRuleId: string;
    status: string;
    points: number;
    createdAt: string;
  } | null;
}

interface MageReferralStats {
  summary: {
    totalReferrals: number;
    pending: number;
    friendConverted: number;
    completed: number;
    expired: number;
    availableRewards: number;
  };
  referrals: Array<{
    id: string;
    friendEmail: string;
    status: string;
    createdAt: string;
  }>;
}

interface MageReferralLink {
  enabled: boolean;
  referralCode?: string;
  referralUrl?: string;
  stats?: {
    totalReferred: number;
    completedReferrals: number;
    pendingReferrals: number;
  };
  socialSharing?: {
    twitter: boolean;
    twitterMessage: string | null;
    facebook: boolean;
    email: boolean;
    whatsapp: boolean;
    whatsappMessage: string | null;
  };
  message?: string;
}

interface MageLoyaltySDK {
  // Customers
  getCustomerDetails(): Promise<MageSDKResponse<{ customer: MageCustomerDetails }>>;
  getCustomerVipTier(): Promise<MageSDKResponse<{ tier: MageVipTier | null; tierProgressValue: number }>>;
  updateCustomerDob(dob: string): Promise<boolean>;

  // Rewards
  getShopRewards(): Promise<MageSDKResponse<{ regularRewards: MageReward[]; tieredRewards: MageReward[] }>>;
  getCustomerRewards(): Promise<MageSDKResponse<{ customerRewards: MageCustomerReward[] }>>;
  redeemReward(rewardId: string): Promise<MageSDKResponse<{ discountCode: string; reward: { name: string; discountType: string } }>>;

  // VIP Tiers
  getShopVipTiers(): Promise<MageSDKResponse<{ tiers: MageVipTier[]; entryMethod: string; currencySymbol: string; pointsMultiplierMode: string | null }>>;

  // Earning Rules
  getEarningRules(): Promise<MageSDKResponse<{ earningRules: MageEarningRule[] }>>;

  // Referrals
  getCustomerReferralStats(): Promise<MageSDKResponse<MageReferralStats>>;
  getReferralLink(): Promise<MageSDKResponse<MageReferralLink>>;

  // Sidebar
  openSidebar(): void;
  closeSidebar(): void;
}

interface Window {
  MageSDK: MageLoyaltySDK;
}
```

Make sure the file is included in your `tsconfig.json` (it will be automatically if it's inside your project root or `include` paths).

## Usage

Once the declaration file is in place, you get full autocomplete and type checking:

```typescript theme={null}
// TypeScript now knows about window.MageSDK
const resp = await window.MageSDK.getCustomerDetails();

if (resp.success && resp.data) {
  const { customer } = resp.data;
  console.log(customer.points);    // number
  console.log(customer.tier?.name); // string | undefined
}
```