@cardql/core/README.md

CardQL core SDK for payment processing - cross-platform shared logic, auth and data access

# @cardql/core

CardQL core SDK for payment processing - cross-platform shared logic, authentication, and data access.

## Installation

```bash
npm install @cardql/core
# or
yarn add @cardql/core
# or
pnpm add @cardql/core
```

## Quick Start

```typescript
import { CardQL } from "@cardql/core";

// Initialize the SDK
const cardql = new CardQL({
  apiKey: "your-api-key",
  endpoint: "https://your-cardql-endpoint.com/graphql",
});

// Create a customer
const customer = await cardql.api.createCustomer({
  firstName: "John",
  lastName: "Doe",
  email: "john@example.com",
});

// Create a payment
const payment = await cardql.api.createPayment({
  amount: "10.00",
  currency: "USD",
  merchantID: "merchant_123",
  userID: "user_456",
  description: "Test payment",
});
```

## Configuration

### CardQLConfig Options

```typescript
interface CardQLConfig {
  apiKey: string; // Your CardQL API key
  endpoint: string; // GraphQL endpoint URL
  timeout?: number; // Request timeout in ms (default: 30000)
  retries?: number; // Number of retries (default: 3)
}
```

## API Reference

### Core Classes

#### CardQL

The main SDK class that provides access to all CardQL functionality.

```typescript
const cardql = new CardQL(config);

// Access the GraphQL client directly
cardql.client.request(query, variables);

// Use the high-level API
cardql.api.createPayment(input);
```

#### CardQLClient

Low-level GraphQL client for custom queries.

```typescript
// Make a raw GraphQL request
const result = await cardql.client.request(
  `
  query GetPayment($id: ID!) {
    payment(id: $id) {
      id
      amount
      status
    }
  }
`,
  { id: "payment_123" }
);

// Request with automatic retries
const result = await cardql.client.requestWithRetry(query, variables);
```

#### CardQLApi

High-level API for common operations.

```typescript
// Accounts
const accounts = await cardql.api.getAccounts();
const account = await cardql.api.getAccount("account_id");
const newAccount = await cardql.api.createAccount({ name: "My Account" });

// Customers
const customers = await cardql.api.getCustomers();
const customer = await cardql.api.createCustomer({
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com",
});

// Merchants
const merchants = await cardql.api.getMerchants();
const merchant = await cardql.api.createMerchant({
  name: "My Store",
  country: "US",
  currency: "USD",
});

// Payments
const payments = await cardql.api.getPayments();
const payment = await cardql.api.createPayment({
  amount: "25.99",
  currency: "USD",
  merchantID: "merchant_123",
  userID: "user_456",
});

// Ledgers
const ledgers = await cardql.api.getLedgers();
const ledger = await cardql.api.createLedger({
  amount: "100.00",
  currency: "USD",
  merchantID: "merchant_123",
  type: "credit",
});
```

## Types

The SDK provides comprehensive TypeScript types for all API entities:

```typescript
import type {
  Account,
  App,
  Customer,
  Merchant,
  Payment,
  Ledger,
  CreatePaymentInput,
  UpdatePaymentInput,
  CardQLError,
} from "@cardql/core";
```

## Error Handling

The SDK normalizes all errors into a consistent format:

```typescript
try {
  const payment = await cardql.api.createPayment(input);
} catch (error: CardQLError) {
  console.error("Error:", error.message);
  console.error("Code:", error.code);
  console.error("Details:", error.details);
}
```

## Authentication

Authentication is handled automatically using the API key provided in the configuration:

```typescript
const cardql = new CardQL({
  apiKey: "your-api-key",
  endpoint: "https://api.cardql.com/graphql",
});

// Update API key at runtime
cardql.setApiKey("new-api-key");
```

## Advanced Usage

### Custom Queries

You can execute custom GraphQL queries using the client directly:

```typescript
const customQuery = `
  query GetPaymentsByMerchant($merchantID: String!) {
    payments(where: { merchantID: $merchantID }) {
      id
      amount
      status
      createdAt
    }
  }
`;

const result = await cardql.client.request(customQuery, {
  merchantID: "merchant_123",
});
```

### Retry Configuration

Configure automatic retries for failed requests:

```typescript
const cardql = new CardQL({
  apiKey: "your-api-key",
  endpoint: "https://api.cardql.com/graphql",
  retries: 5, // Retry up to 5 times
  timeout: 60000, // 60 second timeout
});
```

## License

MIT

## Support

For support, please contact the CardQL team or visit our documentation.