Skip to main content

Client Initialization

The Easy Node.js SDK client is the main entry point for all server-side operations.

createClient​

Creates and initializes an Easy SDK client instance.

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY,
  __dev: process.env.NODE_ENV === "development",
});

Parameters​

  • options (object, required)
    • apiKey (string, required): Your Easy API secret key
    • __dev (boolean, optional): Enable development/sandbox mode

Returns​

Promise<EasyClient>;

Example: Production Configuration​

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

// Client is ready to use
const customers = await easy.getCustomers();

Example: Development Mode​

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_DEV_API_KEY!,
  __dev: true, // Uses sandbox environment
});

Example: Singleton Pattern​

For better performance, create a single client instance and reuse it:

// lib/easy-client.ts
import { createClient } from "@easylabs/node";

let easyClient: any = null;

export async function getEasyClient() {
  if (!easyClient) {
    easyClient = await createClient({
      apiKey: process.env.EASY_API_KEY!,
    });
  }
  return easyClient;
}

// Use in your routes
import { getEasyClient } from "./lib/easy-client";

const easy = await getEasyClient();
const customer = await easy.getCustomer("cust_123");

Example: Environment Variables​

# .env
EASY_API_KEY=easy_sk_production_key
EASY_DEV_API_KEY=easy_sk_sandbox_key
NODE_ENV=development
import { createClient } from "@easylabs/node";
import dotenv from "dotenv";

dotenv.config();

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
  __dev: process.env.NODE_ENV === "development",
});

Security Best Practices​

Never Expose Your API Key​

// ❌ BAD - Never hardcode API keys
const easy = await createClient({
  apiKey: "easy_sk_live_123456789...",
});

// ❌ BAD - Never expose in client-side code
// Never use @easylabs/node in the browser

// ✅ GOOD - Use environment variables
const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

Use Secrets Manager in Production​

import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from "@aws-sdk/client-secrets-manager";
import { createClient } from "@easylabs/node";

async function getApiKey() {
  const client = new SecretsManagerClient({ region: "us-east-1" });
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: "easy-api-key" }),
  );
  return JSON.parse(response.SecretString!).apiKey;
}

const apiKey = await getApiKey();
const easy = await createClient({ apiKey });

Type Definitions​

ClientOptions​

interface ClientOptions {
  apiKey: string;
  __dev?: boolean;
}

EasyClient​

The client instance provides all SDK methods:

interface EasyClient {
  // Customer Management
  createCustomer(data: CreateCustomer): Promise<ApiResponse<CustomerData>>;
  getCustomer(customerId: string): Promise<ApiResponse<CustomerData>>;
  getCustomers(params?: PaginationParams): Promise<ApiResponse<CustomerData[]>>;
  updateCustomer(
    customerId: string,
    data: UpdateCustomer,
  ): Promise<ApiResponse<CustomerData>>;

  // Payment Instruments
  createPaymentInstrument(
    data: CreatePaymentInstrument,
  ): Promise<ApiResponse<PaymentInstrumentData>>;
  updatePaymentInstrument(
    instrumentId: string,
    data: UpdatePaymentInstrument,
  ): Promise<ApiResponse<PaymentInstrumentData>>;
  getCustomerPaymentInstruments(
    customerId: string,
  ): Promise<ApiResponse<PaymentInstrumentData[]>>;

  // Transfers
  createTransfer(data: CreateTransfer): Promise<ApiResponse<TransferData>>;
  getTransfer(transferId: string): Promise<ApiResponse<TransferData>>;
  getTransfers(params?: PaginationParams): Promise<ApiResponse<TransferData[]>>;
  updateTransfer(
    transferId: string,
    tags: Record<string, unknown>,
  ): Promise<ApiResponse<TransferData>>;

  // Products & Pricing
  createProduct(data: CreateProduct): Promise<ApiResponse<ProductData>>;
  getProduct(productId: string): Promise<ApiResponse<ProductData>>;
  getProducts(params?: PaginationParams): Promise<ApiResponse<ProductData[]>>;
  updateProduct(
    productId: string,
    data: UpdateProduct,
  ): Promise<ApiResponse<ProductData>>;
  archiveProduct(productId: string): Promise<ApiResponse<void>>;

  createPrice(data: CreatePrice): Promise<ApiResponse<PriceData>>;
  getPrice(priceId: string): Promise<ApiResponse<PriceData>>;
  getPrices(params?: PaginationParams): Promise<ApiResponse<PriceData[]>>;
  updatePrice(
    priceId: string,
    data: UpdatePrice,
  ): Promise<ApiResponse<PriceData>>;
  archivePrice(priceId: string): Promise<ApiResponse<void>>;

  // Checkout
  checkout(data: CheckoutData): Promise<ApiResponse<OrderData>>;

  // And more...
}