npm package: @genation/sdk
Description: OAuth 2.1 SDK for Genation authentication
Latest version: 0.2.12

# Genation SDK

OAuth 2.1 SDK for Genation authentication. Built with TypeScript, supports
browser and Node.js environments.

## Installation

```bash
npm install @genation/sdk
```

## Quick Start

```typescript
import { createClient } from "@genation/sdk";

const client = createClient({
    // Your Genation client ID and secret
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    // Your app redirect URI
    redirectUri: "http://localhost:3000/callback",
});

// Listen to auth state changes
client.onAuthStateChange((event, session) => {
    if (event === "SIGNED_IN") {
        console.log("Welcome!", session?.user);
    } else if (event === "SIGNED_OUT") {
        console.log("Goodbye!");
    }
});

// Start login
window.location.href = await client.signIn();

// Handle callback (on /callback page)
const params = new URLSearchParams(window.location.search);
await client.handleCallback(params.get("code")!, params.get("state")!);
```

## API Reference

### `createClient(config)`

Create a new Genation client instance.

```typescript
const client = createClient({
  clientId: string;       // Required
  clientSecret: string;   // Required
  redirectUri: string;    // Required
});
```

### `client.onAuthStateChange(callback)`

Listen to authentication state changes.

**Events:**

| Event             | Description                              |
| ----------------- | ---------------------------------------- |
| `INITIAL_SESSION` | First load, session may or may not exist |
| `SIGNED_IN`       | User successfully signed in              |
| `SIGNED_OUT`      | User signed out or session expired       |
| `TOKEN_REFRESHED` | Access token was automatically refreshed |

```typescript
const { subscription } = client.onAuthStateChange((event, session) => {
    console.log(event, session);
});

// Cleanup
subscription.unsubscribe();
```

### `client.signIn()`

Start OAuth login flow. Returns authorization URL.

```typescript
const url = await client.signIn();
window.location.href = url;
```

### `client.handleCallback(url)`

Exchange authorization code for tokens.

```typescript
const url = window.location.href;
await client.handleCallback(url);
```

### `client.getSession()`

Get current session with auto-refresh.

```typescript
const session = await client.getSession();
if (session) {
    console.log(session.accessToken);
    console.log(session.user);
}
```

### `client.signOut()`

Sign out the current user and clear local session tokens.

```typescript
await client.signOut();
// Triggers "SIGNED_OUT" event
```

### `client.verifyToken(token)`

Verify a JWT token signature using the public JWKS endpoint.

```typescript
try {
    const payload = await client.verifyToken(accessToken);
    console.log("Token is valid:", payload);
} catch (error) {
    console.error("Token verification failed:", error);
}
```

### Standalone Token Verification

You can also verify tokens without a client instance:

```typescript
import { verifyToken } from "@genation/sdk";

// Uses default Genation Auth URL
const payload = await verifyToken(token);
```

## Session Object

```typescript
interface Session {
    accessToken: string;
    refreshToken?: string;
    expiresIn: number;
    expiresAt: number;
    user: User | null;
}

interface User {
    sub: string; // user id
    name?: string;
    email?: string;
    ...
}
```

### `client.getLicenses()`

```typescript
const licenses = await client.getLicenses({ expiresAfter: new Date() });
```

## License Object

```typescript
interface License {
    id: string;
    expiresAt: string;
    appPlanId: string;
    durationDays: number;
    planTermId: string | null;
    purchaserId: string;
    redeemedBy: string;
    purchasedAt: string;
    redeemedAt: string;
    purchaserNote: string;
    status: string;
    plan: LicensePlan;
}
```

## Security

- ✅ OAuth 2.1 with PKCE (S256)
- ✅ State parameter for CSRF protection
- ✅ Automatic token refresh
- ✅ Matches Supabase implementation

## License

MIT