@one-payments/adapters-web

Web platform adapters for One Payments SDK. Provides browser-based implementations for HTTP, Storage, Crypto, and Timer operations.

Features

- 🌐 Browser APIs - Built on native Web APIs (Fetch, LocalStorage, Web Crypto, setTimeout)
- 🔒 Secure - Uses Web Crypto API for HMAC generation
- 💾 Persistent Storage - LocalStorage for session management
- ⚡ Lightweight - No external dependencies
- 🎯 TypeScript - Full type safety
- 🧩 Framework Agnostic - Works with React, Vue, Angular, and vanilla JS

Installation

``bash
npm install @one-payments/adapters-web


or

yarn add @one-payments/adapters-web

or

pnpm add @one-payments/adapters-web
`

Usage

$3

`typescript
import { createWebAdapters } from '@one-payments/adapters-web';

// Create adapters instance
const adapters = createWebAdapters();

// Use with any One Payments component
// React example:
config={config}
adapters={adapters}
amount={5000}
currency="USD"
orderId="order-123"
/>
`

$3

`tsx
import { createWebAdapters } from '@one-payments/adapters-web';
import { OnePayment } from '@one-payments/react';

function CheckoutPage() {
const adapters = createWebAdapters();

return (
config={config}
adapters={adapters}
{...paymentProps}
/>
);
}
`

$3

`vue



`

$3

`typescript
import { Component } from '@angular/core';
import { createWebAdapters } from '@one-payments/adapters-web';
import { OnePaymentComponent } from '@one-payments/angular';

@Component({
selector: 'app-checkout',
standalone: true,
imports: [OnePaymentComponent],
template:
[config]="config"
[adapters]="adapters"
/>

})
export class CheckoutComponent {
adapters = createWebAdapters();
}
`

$3

`html











`

Server-Side Rendering (SSR)

Important: This package uses browser-only APIs and cannot be used during server-side rendering. Initialize adapters on the client-side only.

$3

For Next.js (and other SSR frameworks), dynamically import and initialize adapters in useEffect:

`tsx
'use client';

import { useState, useEffect } from 'react';
import dynamic from 'next/dynamic';
import type { Adapters } from '@one-payments/core';

// Dynamic import of payment component
const OnePayment = dynamic(
() => import('@one-payments/react').then((mod) => mod.OnePayment),
{ ssr: false }
);

export default function CheckoutPage() {
const [adapters, setAdapters] = useState(null);

// Initialize adapters on client-side only
useEffect(() => {
import('@one-payments/adapters-web').then(({ createWebAdapters }) => {
setAdapters(createWebAdapters());
});
}, []);

if (!adapters) {
return

;
}

return (
config={config}
adapters={adapters}
{...props}
/>
);
}
`

Why this is needed:
- Web APIs like window, localStorage, crypto.subtle don't exist in Node.js
- SSR renders on the server first, causing "ReferenceError: window is not defined"
- Dynamic import with ssr: false ensures code only runs in the browser

See the Next.js Integration Guide for complete instructions.

$3

`vue



`

Adapter Implementations

$3

Uses the native fetch API for HTTP requests:

`typescript
interface HttpAdapter {
fetch(url: string, options?: RequestInit): Promise;
}

// Implementation
const httpAdapter = {
fetch: (url, options) => window.fetch(url, options)
};
`

$3

Uses localStorage for persistent client-side storage:

`typescript
interface StorageAdapter {
getItem(key: string): Promise;
setItem(key: string, value: string): Promise;
removeItem(key: string): Promise;
}

// Implementation
const storageAdapter = {
getItem: (key) => Promise.resolve(localStorage.getItem(key)),
setItem: (key, value) => Promise.resolve(localStorage.setItem(key, value)),
removeItem: (key) => Promise.resolve(localStorage.removeItem(key))
};
`

Storage Keys Used:
- one-payments-session-* - Payment session data
- one-payments-config-* - Cached configuration

$3

Uses Web Crypto API for secure cryptographic operations:

`typescript
interface CryptoAdapter {
generateHMAC(message: string, secret: string): Promise;
randomUUID(): string;
}

// Implementation uses crypto.subtle for HMAC-SHA256
const cryptoAdapter = {
generateHMAC: async (message, secret) => {
const encoder = new TextEncoder();
const keyData = encoder.encode(secret);
const messageData = encoder.encode(message);

const key = await crypto.subtle.importKey(
'raw',
keyData,
{ name: 'HMAC', hash: 'SHA-256' },
false,
['sign']
);

const signature = await crypto.subtle.sign('HMAC', key, messageData);
return Array.from(new Uint8Array(signature))
.map(b => b.toString(16).padStart(2, '0'))
.join('');
},
randomUUID: () => crypto.randomUUID()
};
`

$3

Uses native JavaScript timer functions:

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

// Implementation
const timerAdapter = {
setTimeout: (callback, delay) => window.setTimeout(callback, delay),
clearTimeout: (id) => window.clearTimeout(id)
};
`

Browser Support

$3

- Fetch API - All modern browsers (IE11 needs polyfill)
- LocalStorage - All browsers supporting Web Storage API
- Web Crypto API - Chrome 37+, Firefox 34+, Safari 11+, Edge 12+
- crypto.randomUUID() - Chrome 92+, Firefox 95+, Safari 15.4+

$3

For older browsers, you may need polyfills:

`html





`

Browser Compatibility

| Browser | Minimum Version | Notes |
|---------|----------------|-------|
| Chrome | 92+ | Full support |
| Firefox | 95+ | Full support |
| Safari | 15.4+ | Full support |
| Edge | 92+ | Full support |
| Mobile Safari | iOS 15.4+ | Full support |
| Chrome Mobile | 92+ | Full support |

Security Considerations

$3

- Uses Web Crypto API's crypto.subtle for secure HMAC-SHA256
- Secret keys never leave the browser
- HMAC signatures used for API request authentication

$3

- Uses localStorage which is origin-isolated
- Data is accessible only to your domain
- No sensitive card data is stored (PCI compliance)
- Session tokens expire after use

$3

If your site uses CSP, ensure these directives:

`http
Content-Security-Policy:
script-src 'self' 'unsafe-eval';
connect-src 'self' https://*.one.ooo;
frame-src https://*.one.ooo;
`

Comparison with Other Adapters

$3

| Feature | adapters-web | adapters-crypto-js |
|---------|--------------|-------------------|
| Environment | Modern browsers | Legacy browsers, WebView |
| Crypto | Web Crypto API | CryptoJS library |
| Bundle Size | ~2KB | ~50KB |
| Performance | Native (faster) | JavaScript (slower) |
| Use Case | Standard web apps | React Native WebView, IE11 |

Use @one-payments/adapters-crypto-js when:
- Supporting IE11 or older browsers
- Using React Native WebView (no Web Crypto API)
- Server-side rendering with crypto operations

Use @one-payments/adapters-web when:
- Building modern web applications
- Supporting Chrome, Firefox, Safari, Edge (latest versions)
- Performance is a priority

$3

| Feature | adapters-web | adapters-native |
|---------|--------------|-----------------|
| Platform | Web browsers | React Native |
| Storage | localStorage | AsyncStorage |
| HTTP | fetch | React Native fetch |
| Use Case | Web apps | Native mobile apps |

Troubleshooting

$3

Cause: Trying to import adapters during SSR

Solution: Initialize in useEffect (React) or onMounted (Vue):

`tsx
// ❌ Don't do this
const adapters = createWebAdapters();

// ✅ Do this
const [adapters, setAdapters] = useState(null);
useEffect(() => {
import('@one-payments/adapters-web').then(({ createWebAdapters }) => {
setAdapters(createWebAdapters());
});
}, []);
`

$3

Cause: Page not served over HTTPS (Web Crypto requires secure context)

Solution:
- Use HTTPS in production
- For localhost, modern browsers allow HTTP
- For testing, use chrome://flags/#unsafely-treat-insecure-origin-as-secure

$3

Cause: Browser privacy mode or storage disabled

Solution: Check if storage is available:

`typescript
try {
const adapters = createWebAdapters();
} catch (error) {
console.error('Storage not available:', error);
// Show message to user to disable privacy mode
}
`

Testing

Mock adapters in tests:

`typescript
// test-utils.ts
export const mockAdapters = {
http: {
fetch: jest.fn()
},
storage: {
getItem: jest.fn(),
setItem: jest.fn(),
removeItem: jest.fn()
},
crypto: {
generateHMAC: jest.fn().mockResolvedValue('mock-hmac'),
randomUUID: jest.fn().mockReturnValue('mock-uuid')
},
timer: {
setTimeout: jest.fn(),
clearTimeout: jest.fn()
}
};

// Your test
it('should process payment', () => {
render();
// ...
});
``

Related Packages

- @one-payments/core - Core types and interfaces
- @one-payments/react - React wrapper
- @one-payments/vue - Vue wrapper
- @one-payments/angular - Angular wrapper
- @one-payments/adapters-crypto-js - CryptoJS-based adapter
- @one-payments/adapters-native - React Native adapter

Requirements

- Modern browser with ES2020 support
- HTTPS (for Web Crypto API)
- LocalStorage enabled

Bundle Size

- Minified: ~2KB
- Gzipped: ~1KB

License

MIT