TypeScript Support

The Easy React SDK is built with TypeScript and provides comprehensive type definitions for all APIs. This ensures type safety and great IDE autocomplete support.

Installation

TypeScript types are included automatically when you install the package:

npm install @easylabs/react
# or
pnpm add @easylabs/react
# or
yarn add @easylabs/react

No separate @types package needed!

Type-Safe Hooks

The useEasy hook returns fully typed methods:

import { useEasy } from "@easylabs/react";

function MyComponent() {
  const {
    getCustomers,
    getCustomer,
    createCustomer,
    updateCustomer,
    deleteCustomer,
    // ... all methods are fully typed
  } = useEasy();

  // TypeScript knows the exact shape of parameters and return types
}

Customer Types

interface Customer {
  id: string;
  first_name: string;
  last_name: string;
  email: string;
  phone?: string;
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

interface CreateCustomerParams {
  first_name: string;
  last_name: string;
  email: string;
  phone?: string;
  metadata?: Record<string, unknown>;
}

interface UpdateCustomerParams {
  first_name?: string;
  last_name?: string;
  email?: string;
  phone?: string;
  metadata?: Record<string, unknown>;
}

Usage

import { useEasy } from "@easylabs/react";
import type { Customer, CreateCustomerParams } from "@easylabs/react";

function CustomerForm() {
  const { createCustomer } = useEasy();

  const handleSubmit = async (data: CreateCustomerParams) => {
    const customer: Customer = await createCustomer(data);
    console.log("Created:", customer.id);
  };
}

Payment Instrument Types

type PaymentInstrumentType = "PAYMENT_CARD" | "BANK_ACCOUNT";

interface PaymentInstrument {
  id: string;
  identity_id: string;
  name: string;
  type: PaymentInstrumentType;
  details?: {
    card?: {
      last4: string;
      brand: string;
      exp_month: number;
      exp_year: number;
    };
    bank?: {
      last4: string;
      bank_name?: string;
      account_type: "CHECKING" | "SAVINGS";
    };
  };
  created_at: string;
  updated_at: string;
}

interface PaymentCardParams {
  type: "PAYMENT_CARD";
  address?: Address;
  cardElement?: RefObject<ICardElement>;
  cardNumberElement?: RefObject<ICardNumberElement>;
  cardExpirationDateElement?: RefObject<ICardExpirationDateElement>;
  cardVerificationCodeElement?: RefObject<ICardVerificationCodeElement>;
}

interface BankAccountParams {
  type: "BANK_ACCOUNT";
  accountType: "CHECKING" | "SAVINGS";
  routingElement?: RefObject<ITextElement>;
  accountElement?: RefObject<ITextElement>;
}

Usage

import { useEasy } from "@easylabs/react";
import type { PaymentInstrument, PaymentCardParams } from "@easylabs/react";
import { useRef } from "react";

function PaymentMethodManager() {
  const { addPaymentInstrument } = useEasy();
  const cardRef = useRef(null);

  const addCard = async () => {
    const params: PaymentCardParams = {
      type: "PAYMENT_CARD",
      cardElement: cardRef,
      address: {
        line1: "123 Main St",
        city: "Anytown",
        state: "CA",
        postal_code: "12345",
        country: "US",
      },
    };

    const instrument: PaymentInstrument = await addPaymentInstrument(
      "cust_123",
      params,
      "My Card",
    );
  };
}

Product & Pricing Types

interface Product {
  id: string;
  name: string;
  description?: string;
  active: boolean;
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

interface Price {
  id: string;
  product_id: string;
  active: boolean;
  currency: string;
  unit_amount: number;
  recurring?: {
    interval: "day" | "week" | "month" | "year";
    interval_count: number;
  };
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

interface CreateProductParams {
  name: string;
  description?: string;
  active?: boolean;
  metadata?: Record<string, unknown>;
}

interface CreatePriceParams {
  product_id: string;
  currency: string;
  unit_amount: number;
  recurring?: {
    interval: "day" | "week" | "month" | "year";
    interval_count?: number;
  };
  active?: boolean;
  metadata?: Record<string, unknown>;
}

Usage

import { useEasy } from "@easylabs/react";
import type {
  Product,
  Price,
  CreateProductParams,
  CreatePriceParams,
} from "@easylabs/react";

function ProductManager() {
  const { createProduct, createPrice } = useEasy();

  const setupProduct = async () => {
    const productParams: CreateProductParams = {
      name: "Premium Plan",
      description: "Access to all features",
      active: true,
    };

    const product: Product = await createProduct(productParams);

    const priceParams: CreatePriceParams = {
      product_id: product.id,
      currency: "usd",
      unit_amount: 2999, // $29.99
      recurring: {
        interval: "month",
        interval_count: 1,
      },
    };

    const price: Price = await createPrice(priceParams);
  };
}

Subscription Types

type SubscriptionStatus =
  | "active"
  | "canceled"
  | "incomplete"
  | "incomplete_expired"
  | "past_due"
  | "paused"
  | "trialing"
  | "unpaid";

interface Subscription {
  id: string;
  identity_id: string;
  status: SubscriptionStatus;
  items: SubscriptionItem[];
  current_period_start: string;
  current_period_end: string;
  cancel_at_period_end: boolean;
  canceled_at?: string;
  ended_at?: string;
  trial_start?: string;
  trial_end?: string;
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

interface SubscriptionItem {
  id: string;
  price_id: string;
  quantity: number;
}

interface CreateSubscriptionParams {
  identity_id: string;
  items: Array<{
    price_id: string;
    quantity?: number;
  }>;
  trial_period_days?: number;
  metadata?: Record<string, unknown>;
}

Usage

import { useEasy } from "@easylabs/react";
import type { Subscription, CreateSubscriptionParams } from "@easylabs/react";

function SubscriptionManager() {
  const { createSubscription } = useEasy();

  const subscribe = async (customerId: string, priceId: string) => {
    const params: CreateSubscriptionParams = {
      identity_id: customerId,
      items: [
        {
          price_id: priceId,
          quantity: 1,
        },
      ],
      trial_period_days: 14,
    };

    const subscription: Subscription = await createSubscription(params);
    console.log("Status:", subscription.status);
  };
}

Checkout Types

interface CheckoutParams {
  customer_creation: boolean;
  identity_id?: string;
  customer_details?: {
    first_name: string;
    last_name: string;
    email: string;
    phone?: string;
  };
  source: PaymentCardParams | BankAccountParams | string;
  line_items: LineItem[];
  metadata?: Record<string, unknown>;
}

interface LineItem {
  price_id: string;
  quantity: number;
}

interface CheckoutResult {
  checkout_id: string;
  status: "succeeded" | "failed" | "pending";
  customer: Customer;
  payment_instrument: PaymentInstrument;
  invoice?: Invoice;
}

Usage

import { useEasy, CardElement } from '@easylabs/react';
import type { CheckoutParams, CheckoutResult } from '@easylabs/react';
import { useRef } from 'react';

function CheckoutForm() {
  const { checkout } = useEasy();
  const cardRef = useRef(null);

  const handleCheckout = async () => {
    const params: CheckoutParams = {
      customer_creation: true,
      customer_details: {
        first_name: 'John',
        last_name: 'Doe',
        email: '[email protected]',
      },
      source: {
        type: 'PAYMENT_CARD',
        cardElement: cardRef,
      },
      line_items: [
        { price_id: 'price_123', quantity: 1 },
      ],
    };

    const result: CheckoutResult = await checkout(params);
    if (result.status === 'succeeded') {
      console.log('Payment successful!');
    }
  };

  return <CardElement ref={cardRef} />;
}

Generic Types

Address

interface Address {
  line1: string;
  line2?: string;
  city: string;
  state: string;
  postal_code: string;
  country: string;
}

Pagination

interface ListParams {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
}

interface ListResult<T> {
  data: T[];
  has_more: boolean;
  total_count: number;
}

Usage

import { useEasy } from "@easylabs/react";
import type { Customer, ListParams, ListResult } from "@easylabs/react";

function CustomerList() {
  const { getCustomers } = useEasy();

  const fetchCustomers = async () => {
    const params: ListParams = {
      limit: 50,
    };

    const result: ListResult<Customer> = await getCustomers(params);
    console.log(`Found ${result.total_count} customers`);
  };
}

Type Imports

You can import types in two ways:

Named Type Imports

import type { Customer, Product, Price } from "@easylabs/react";

Inline Type Imports

import { type Customer, useEasy } from "@easylabs/react";

Best Practices

1. Use Type Inference

// Good - Let TypeScript infer the type
const customer = await createCustomer({ ... });

// Also good - Explicit type for clarity
const customer: Customer = await createCustomer({ ... });

2. Define Form Types

interface PaymentFormData {
  firstName: string;
  lastName: string;
  email: string;
  address: Address;
}

function PaymentForm() {
  const [formData, setFormData] = useState<PaymentFormData>({
    firstName: "",
    lastName: "",
    email: "",
    address: {
      line1: "",
      city: "",
      state: "",
      postal_code: "",
      country: "US",
    },
  });
}

3. Type Guard Functions

function isPaymentCard(
  source: PaymentCardParams | BankAccountParams | string,
): source is PaymentCardParams {
  return typeof source === "object" && source.type === "PAYMENT_CARD";
}

function isBankAccount(
  source: PaymentCardParams | BankAccountParams | string,
): source is BankAccountParams {
  return typeof source === "object" && source.type === "BANK_ACCOUNT";
}

4. Error Handling with Types

import { useEasy } from '@easylabs/react';

function MyComponent() {
  const { createCustomer } = useEasy();

  const handleCreate = async () => {
    try {
      const customer = await createCustomer({ ... });
      // customer is typed as Customer
    } catch (error) {
      if (error instanceof Error) {
        console.error('Error:', error.message);
      }
    }
  };
}

IDE Support

The SDK provides excellent IDE support with:

• ✅ Autocomplete: IntelliSense for all methods and properties
• ✅ Type Checking: Catch errors before runtime
• ✅ Documentation: Hover over methods to see docs
• ✅ Refactoring: Safe rename and refactor operations

Next Steps

• Explore API Reference
• View Complete Examples
• Learn about Form Elements