npm package: @onlyfansapi/auth
Description: Framework agnostic library to embed OnlyFans Authentication in your app using OnlyFansAPI.com/auth
Author: OnlyFansAPI.com
Latest version: 2.0.2

# @onlyfansapi/auth

A framework-agnostic library to embed OnlyFans Authentication in your app using OnlyFansAPI.com/auth.

## Features

- 🚀 **Framework Agnostic** - Works with React, Vue, Angular, vanilla JS, or any framework
- 🎨 **Beautiful Modal UI** - Modern, responsive modal with smooth animations
- 🔒 **Secure Communication** - PostMessage-based communication with origin validation
- ⌨️ **Keyboard Support** - ESC key to close modal
- 📱 **Mobile Friendly** - Responsive design that works on all devices
- 🎯 **TypeScript Support** - Full type definitions included
- 📦 **Modern Bundling** - Built with tsup for optimal bundle size and compatibility

## Installation

```bash
npm install @onlyfansapi/auth
# or
yarn add @onlyfansapi/auth
# or
pnpm add @onlyfansapi/auth
# or
bun install @onlyfansapi/auth
```

## Quick Start

```typescript
import { startOnlyFansAuthentication } from "@onlyfansapi/auth";

// Start authentication
startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
  onSuccess: (data) => {
    console.log("Authentication successful:", data);
    // data.accountId - The authenticated account ID
    // data.username - The authenticated username
    // data.response - Full response from the API
  },
  onError: (error) => {
    console.error("Authentication failed:", error);
    // error.message - Error message
    // error.code - Error code (if available)
    // error.details - Additional error details (if available)
  },
});
```

## API Reference

### `startOnlyFansAuthentication(clientSessionToken, options)`

Opens a modal with an iframe containing the OnlyFans authentication flow.

**Parameters:**

- `clientSessionToken` (string): Your client session token - Get your Client Session Token from https://docs.onlyfansapi.com/api-reference/client-sessions/create-client-session
- `options` (object):
  - `onSuccess(data: AuthSuccessData)` (function): Callback when authentication succeeds
  - `onError(error: AuthFailureError)` (function): Callback when authentication fails

**Example:**

```typescript
startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
  onSuccess: (data) => {
    // Handle successful authentication
    const { accountId, username } = data;
    console.log(`Welcome ${username}!`);
  },
  onError: (error) => {
    // Handle authentication error
    console.error("Auth failed:", error.message);
  },
});
```

### `closeOnlyFansAuthentication()`

Programmatically closes the authentication modal.

**Example:**

```typescript
import { closeOnlyFansAuthentication } from "@onlyfansapi/auth";

// Close the modal
closeOnlyFansAuthentication();
```

## Data Types

### `AuthSuccessData`

```typescript
interface AuthSuccessData {
  accountId: string; // The authenticated account ID
  username: string; // The authenticated username
  onlyfansData: {
    id: number | string; // OnlyFans user ID
    username: string; // OnlyFans username
    email: string; // OnlyFans email
    avatar_url: string | null; // OnlyFans avatar URL
    name: string; // OnlyFans display name
  };
}
```

### `AuthFailureError`

```typescript
interface AuthFailureError {
  message: string; // Error message, eg. "Wrong email or password"
}
```

## Framework Examples

### React

```tsx
import React from "react";
import { startOnlyFansAuthentication } from "@onlyfansapi/auth";

function AuthButton() {
  const handleAuth = () => {
    startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
      onSuccess: (data) => {
        console.log("Success:", data);
      },
      onError: (error) => {
        console.error("Error:", error);
      },
    });
  };

  return <button onClick={handleAuth}>Authenticate with OnlyFans</button>;
}
```

### Vue

```vue
<template>
  <button @click="handleAuth">Authenticate with OnlyFans</button>
</template>

<script setup>
import { startOnlyFansAuthentication } from "@onlyfansapi/auth";

const handleAuth = () => {
  startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
    onSuccess: (data) => {
      console.log("Success:", data);
    },
    onError: (error) => {
      console.error("Error:", error);
    },
  });
};
</script>
```

### Vanilla JavaScript

```html
<button onclick="authenticate()">Authenticate with OnlyFans</button>

<script>
  import { startOnlyFansAuthentication } from "@onlyfansapi/auth";

  function authenticate() {
    startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
      onSuccess: (data) => {
        console.log("Success:", data);
      },
      onError: (error) => {
        console.error("Error:", error);
      },
    });
  }
</script>
```

## Modal Features

The authentication modal includes:

- **Responsive Design**: Adapts to different screen sizes
- **Smooth Animations**: Fade-in/fade-out with scale transitions
- **Close Button**: Clickable × button in the top-right corner
- **Keyboard Support**: Press ESC to close
- **Body Scroll Lock**: Prevents background scrolling when modal is open
- **High Z-Index**: Ensures modal appears above other content
- **Origin Validation**: Secure postMessage communication

## Security

- All communication with the iframe is validated by origin
- Only messages from the configured OnlyFansAPI.com domain are accepted
- Client session tokens are passed securely via URL parameters

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT