npm package: @one-payments/core
Description: Headless payment SDK core - framework-agnostic business logic
Author: One Payments
Latest version: 1.7.5

# @one-payments/core

Core SDK types, interfaces, and business logic for One Payments. This package provides the foundation for all platform-specific implementations.

## Features

- 🔒 Secure payment configuration with validation
- 📝 Complete TypeScript definitions
- 🌐 Platform-agnostic interfaces
- 🔐 Built-in HMAC signature generation
- 🎯 Type-safe event payloads
- ⚙️ Environment configuration (dev, staging, prod)

## Installation

```bash
npm install @one-payments/core
# or
yarn add @one-payments/core
# or
pnpm add @one-payments/core
```

## Usage

### PaymentConfig Class

The `PaymentConfig` class provides validation and type safety for your SDK configuration:

```typescript
import { PaymentConfig } from '@one-payments/core';

// Recommended: Use PaymentConfig for automatic validation
const config = new PaymentConfig({
  apiKey: 'pk_...',
  secretKey: 'sk_...',
  environment: 'prod'
});

// Access validated config
console.log(config.apiKey);        // string
console.log(config.secretKey);     // string
console.log(config.environment);   // 'dev' | 'staging' | 'prod'
```

### Plain Config Object

You can also use a plain object if you prefer:

```typescript
import type { SDKConfig } from '@one-payments/core';

const config: SDKConfig = {
  apiKey: 'pk_...',
  secretKey: 'sk_...',
  environment: 'prod'
};
```

### Development Environment

For local development and testing, use the `'dev'` environment:

```typescript
const config = new PaymentConfig({
  apiKey: 'your-dev-api-key',
  secretKey: 'your-dev-secret-key',
  environment: 'dev'
});
```

> **Note for TypeScript users:** The TypeScript types currently show only `'prod'` and `'staging'`, but the runtime fully supports `'dev'`. Use type assertion if needed:
> ```typescript
> environment: 'dev' as any
> ```

## Types

### Core Interfaces

```typescript
interface SDKConfig {
  apiKey: string;
  secretKey: string;
  environment: 'dev' | 'staging' | 'prod';
}

interface PaymentSucceededPayload {
  paymentIntent: {
    id: string;
    amount: number;
    currency: string;
    status: 'succeeded';
  };
  metadata?: Record<string, unknown>;
}

interface PaymentFailedPayload {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}

interface StateChangedPayload {
  status: 'idle' | 'initializing' | 'ready' | 'processing' | 'requires_action' | 'succeeded' | 'failed';
  [key: string]: unknown;
}
```

### Adapters Interface

Platform adapters provide implementations for HTTP, Storage, Crypto, and Timer operations:

```typescript
interface Adapters {
  http: HttpAdapter;
  storage: StorageAdapter;
  crypto: CryptoAdapter;
  timer: TimerAdapter;
}

interface HttpAdapter {
  fetch(url: string, options?: RequestInit): Promise<Response>;
}

interface StorageAdapter {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

interface CryptoAdapter {
  generateHMAC(message: string, secret: string): Promise<string>;
  randomUUID(): string;
}

interface TimerAdapter {
  setTimeout(callback: () => void, delay: number): number;
  clearTimeout(id: number): void;
}
```

## Payment Method Types

```typescript
type PaymentMethodId =
  | 'card'
  | 'paynow'
  | 'apple_pay'
  | 'google_pay';

interface PaymentMethodConfig {
  id: PaymentMethodId;
  enabled: boolean;
  displayName?: string;
}
```

## Environment URLs

The SDK automatically selects the correct API endpoint based on the environment:

```typescript
const ENVIRONMENT_URLS = {
  dev: 'https://public.dev.one.ooo',
  staging: 'https://public.staging.one.ooo',
  prod: 'https://public.one.ooo'
};
```

## Framework Integration

This core package is used by all framework-specific wrappers:

### Web Frameworks
- [@one-payments/react](../react) - React wrapper
- [@one-payments/vue](../vue) - Vue 3 wrapper
- [@one-payments/angular](../angular) - Angular wrapper
- [@one-payments/web-components](../web-components) - Vanilla JS

### Mobile
- [@one-payments/react-native](../react-native) - React Native

### Platform Adapters
- [@one-payments/adapters-web](../adapters-web) - Web platform
- [@one-payments/adapters-native](../adapters-native) - React Native

## Server-Side Rendering (SSR)

This package is safe to import in SSR environments (Next.js, Nuxt, etc.) as it only contains types and pure functions. However, platform adapters should be initialized client-side only.

### Next.js Example

```typescript
'use client';

import { useState, useEffect } from 'react';
import { PaymentConfig } from '@one-payments/core';
import type { SDKConfig } from '@one-payments/core';

export default function CheckoutPage() {
  const [config, setConfig] = useState<SDKConfig | null>(null);

  useEffect(() => {
    // Initialize config on client-side
    setConfig(new PaymentConfig({
      apiKey: process.env.NEXT_PUBLIC_ONE_PAYMENTS_API_KEY!,
      secretKey: process.env.NEXT_PUBLIC_ONE_PAYMENTS_SECRET_KEY!,
      environment: 'prod'
    }));
  }, []);

  // ...
}
```

See the [Next.js Integration Guide](../../docs/integration-guides/nextjs.md) for complete instructions.

## Validation

The `PaymentConfig` class validates:

- ✅ Required fields (apiKey, secretKey, environment)
- ✅ Environment value is valid
- ✅ API keys are non-empty strings
- ⚠️ Warnings for common mistakes (mixing environments, test keys in production)

```typescript
// Throws error if invalid
const config = new PaymentConfig({
  apiKey: '',  // Error: apiKey is required
  secretKey: 'sk_...',
  environment: 'invalid'  // Error: environment must be dev/staging/prod
});
```

## Security Best Practices

### Environment Variables

Store API keys in environment variables, never commit them to version control:

**React / CRA:**
```bash
# .env
REACT_APP_ONE_PAYMENTS_API_KEY=pk_...
REACT_APP_ONE_PAYMENTS_SECRET_KEY=sk_...
```

**Next.js:**
```bash
# .env.local
NEXT_PUBLIC_ONE_PAYMENTS_API_KEY=pk_...
NEXT_PUBLIC_ONE_PAYMENTS_SECRET_KEY=sk_...
```

**Vite:**
```bash
# .env
VITE_ONE_PAYMENTS_API_KEY=pk_...
VITE_ONE_PAYMENTS_SECRET_KEY=sk_...
```

### .gitignore

Ensure your `.gitignore` includes:
```
.env
.env.local
.env.*.local
```

## TypeScript Configuration

Add these compiler options for optimal type checking:

```json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node"
  }
}
```

## Related Packages

- [@one-payments/react](../react) - React wrapper
- [@one-payments/vue](../vue) - Vue wrapper
- [@one-payments/angular](../angular) - Angular wrapper
- [@one-payments/react-native](../react-native) - React Native
- [@one-payments/adapters-web](../adapters-web) - Web adapters
- [@one-payments/adapters-native](../adapters-native) - Native adapters

## Requirements

- TypeScript >= 5.0.0 (for TypeScript projects)
- No runtime dependencies

## License

MIT