@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

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:

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:

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:

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:

environment: 'dev' as any

Types

Core Interfaces

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:

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

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:

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 wrapper
• @one-payments/vue - Vue 3 wrapper
• @one-payments/angular - Angular wrapper
• @one-payments/web-components - Vanilla JS

Mobile

• @one-payments/react-native - React Native

Platform Adapters

• @one-payments/adapters-web - Web platform
• @one-payments/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

'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 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)

// 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:

# .env
REACT_APP_ONE_PAYMENTS_API_KEY=pk_...
REACT_APP_ONE_PAYMENTS_SECRET_KEY=sk_...

Next.js:

# .env.local
NEXT_PUBLIC_ONE_PAYMENTS_API_KEY=pk_...
NEXT_PUBLIC_ONE_PAYMENTS_SECRET_KEY=sk_...

Vite:

# .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:

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

Related Packages

• @one-payments/react - React wrapper
• @one-payments/vue - Vue wrapper
• @one-payments/angular - Angular wrapper
• @one-payments/react-native - React Native
• @one-payments/adapters-web - Web adapters
• @one-payments/adapters-native - Native adapters

Requirements

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

License

MIT