@playcademy/better-auth 0.0.1-alpha.1 → 0.0.1

package/dist/client.d.ts

@@ -19,48 +19,122 @@
  * ```
  */
 import { playcademy as playcademyServerPlugin } from './server';
+/**
+ * Configuration options for the Playcademy Better Auth client plugin
+ *
+ * Configures how the client handles platform authentication and Safari
+ * Storage Access API integration.
+ */
 export interface PlaycademyClientOptions {
     /**
-     * Automatically show storage access prompt for Safari users
-     *
-     * When true (default), Safari users in iframes will see an automatic
-     * prompt to grant storage access (required for cookies in Safari).
-     *
-     * Set to false if you want to handle Safari storage access yourself.
+     * Safari browser configuration.
      *
-     * @default true
+     * Controls how the plugin handles Safari's Storage Access API requirements
+     * for cross-origin cookies in iframes.
      */
     safari?: {
+        /**
+         * Automatically show storage access prompt for Safari users.
+         *
+         * When `true` (default), Safari users running the game in an iframe
+         * (platform mode) will automatically see a prompt to grant cookie
+         * access. This is required for authentication to work in Safari iframes.
+         *
+         * Set to `false` if you want to handle Safari storage access manually
+         * or have a custom flow.
+         *
+         * **Why this is needed**: Safari blocks third-party cookies in iframes
+         * by default. The Storage Access API allows users to explicitly grant
+         * cookie access after a user interaction.
+         *
+         * @default true
+         * @example
+         * ```ts
+         * {
+         *   safari: {
+         *     autoPrompt: true // Show automatic prompt (recommended)
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * ```ts
+         * {
+         *   safari: {
+         *     autoPrompt: false // Handle Safari auth manually
+         *   }
+         * }
+         * ```
+         */
         autoPrompt?: boolean;
     };
 }
 /**
  * Playcademy client plugin for Better Auth
  *
- * Automatically handles:
- * - Platform vs standalone mode detection
- * - Token exchange for platform mode
- * - Safari Storage Access API (auto-prompt)
+ * Enables seamless authentication for Playcademy games that run both:
+ * - In the Playcademy platform (iframe with JWT token exchange)
+ * - As standalone games (standard Better Auth with cookies)
+ *
+ * **Key Features**:
+ * - Automatic platform vs standalone mode detection
+ * - JWT token exchange for platform authentication
+ * - Safari Storage Access API handling (automatic prompt)
+ * - Cookie-based auth with CHIPS support for Chrome/Edge
+ * - Zero configuration required
+ *
+ * **How it works**:
+ * 1. Platform mode: Exchanges platform JWT for Better Auth session
+ * 2. Standalone mode: Uses standard Better Auth providers (email/OAuth)
+ * 3. Safari: Automatically requests storage access for iframe cookies
+ *
+ * @param options - Configuration options (optional)
+ * @returns Better Auth client plugin
  *
  * @example
  * ```typescript
- * // Default: Auto-handles everything including Safari
+ * // Recommended: Use defaults (handles everything automatically)
+ * import { createAuthClient } from 'better-auth/react'
+ * import { playcademy } from '@playcademy/better-auth/client'
+ *
  * const auth = createAuthClient({
+ *   baseURL: 'http://localhost:8788',
  *   plugins: [playcademy()]
  * })
+ *
+ * // Access auth in your components
+ * export const { useSession } = auth
  * ```
  *
  * @example
  * ```typescript
- * // Custom: Disable auto Safari prompt
+ * // Custom: Disable Safari auto-prompt
  * const auth = createAuthClient({
+ *   baseURL: 'http://localhost:8788',
  *   plugins: [
  *     playcademy({
- *       safari: { autoPrompt: false }
+ *       safari: {
+ *         autoPrompt: false // Handle Safari manually
+ *       }
  *     })
  *   ]
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Use session in React component
+ * import { useSession } from './lib/auth'
+ *
+ * function App() {
+ *   const { data: session, isPending } = useSession()
+ *
+ *   if (isPending) return <div>Loading...</div>
+ *   if (!session) return <div>Not logged in</div>
+ *
+ *   return <div>Welcome, {session.user.name}!</div>
+ * }
+ * ```
  */
 export declare function playcademy(options?: PlaycademyClientOptions): {
     id: "playcademy-client";

package/dist/server.d.ts

@@ -1,30 +1,135 @@
 /**
- * Playcademy plugin for Better Auth
+ * Playcademy Platform Authentication Plugin (Server)
  *
- * This plugin provides:
- * - Platform user schema field (playcademyUserId)
- * - Token exchange endpoint (POST /api/auth/playcademy)
+ * Enables seamless authentication for Playcademy games that run both:
+ * - In the Playcademy platform (iframe with JWT token exchange)
+ * - As standalone games (standard Better Auth with cookies)
+ *
+ * **Key Features**:
+ * - Platform JWT token exchange endpoint (`POST /api/auth/playcademy`)
  * - Automatic account linking between platform and standalone modes
- * - Cross-site cookie support with CHIPS
+ * - Cross-site cookie support with CHIPS (Partitioned cookies)
+ * - Schema extension: adds `playcademyUserId` to user model
+ * - Safari Storage Access API compatibility
+ *
+ * **How it works**:
+ *
+ * 1. **Platform Mode (iframe)**:
+ *    - Game receives JWT token from Playcademy platform
+ *    - Client exchanges token via `/api/auth/playcademy` endpoint
+ *    - Server verifies token with platform API
+ *    - Creates or links Better Auth user by `playcademyUserId`
+ *    - Returns session cookie with CHIPS support
+ *
+ * 2. **Standalone Mode**:
+ *    - Users authenticate via Better Auth providers (email, OAuth, etc.)
+ *    - If they later access via platform, accounts are linked by `playcademyUserId`
+ *
+ * 3. **Account Linking**:
+ *    - Platform users get `playcademyUserId` set automatically
+ *    - If a user exists with that `playcademyUserId`, sessions merge
+ *    - Enables seamless switching between platform and standalone
+ *
+ * **Cookie Configuration**:
+ *
+ * For cross-origin iframe authentication to work, you MUST configure cookies:
+ *
+ * ```typescript
+ * advanced: {
+ *   defaultCookieAttributes: {
+ *     sameSite: 'none',    // Allow cross-site cookies
+ *     secure: true,        // HTTPS only (required for sameSite: none)
+ *     path: '/',           // Available across entire site
+ *     partitioned: true,   // CHIPS for Chrome/Edge
+ *   }
+ * }
+ * ```
+ *
+ * **Safari Compatibility**:
+ *
+ * Safari doesn't support CHIPS. The client plugin automatically handles
+ * Safari Storage Access API to request cookie permission from users.
+ *
+ * @returns Better Auth server plugin
  *
  * @example
  * ```typescript
+ * // Basic setup
  * import { betterAuth } from 'better-auth'
+ * import { drizzleAdapter } from 'better-auth/adapters/drizzle'
  * import { playcademy } from '@playcademy/better-auth/server'
+ * import { db } from './db'
  *
  * export const auth = betterAuth({
  *   database: drizzleAdapter(db, { provider: 'sqlite' }),
+ *
+ *   // Required: Platform integration
  *   plugins: [playcademy()],
+ *
+ *   // Required: Cross-site cookie support
  *   advanced: {
  *     defaultCookieAttributes: {
  *       sameSite: 'none',
  *       secure: true,
  *       path: '/',
  *       partitioned: true, // CHIPS for Chrome/Edge
- *     },
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With email/password and OAuth
+ * export const auth = betterAuth({
+ *   database: drizzleAdapter(db, { provider: 'sqlite' }),
+ *
+ *   // Platform auth (always included)
+ *   plugins: [playcademy()],
+ *
+ *   // Optional: Email/password for standalone
+ *   emailAndPassword: {
+ *     enabled: true
  *   },
+ *
+ *   // Optional: OAuth for standalone
+ *   socialProviders: {
+ *     github: {
+ *       clientId: process.env.GITHUB_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     }
+ *   },
+ *
+ *   advanced: {
+ *     defaultCookieAttributes: {
+ *       sameSite: 'none',
+ *       secure: true,
+ *       path: '/',
+ *       partitioned: true,
+ *     }
+ *   }
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in API route handler
+ * import { Context } from 'hono'
+ * import { auth } from './lib/auth'
+ *
+ * export async function GET(c: Context) {
+ *   const session = await auth.api.getSession({
+ *     headers: c.req.raw.headers
+ *   })
+ *
+ *   if (!session) {
+ *     return c.json({ error: 'Unauthorized' }, 401)
+ *   }
+ *
+ *   // session.user.playcademyUserId available if from platform
+ *   return c.json({ user: session.user })
+ * }
+ * ```
  */
 export declare const playcademy: () => {
     id: "playcademy";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/better-auth",
-    "version": "0.0.1-alpha.1",
+    "version": "0.0.1",
     "type": "module",
     "exports": {
         "./server": {
@@ -28,7 +28,7 @@
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.9.0",
-        "@playcademy/sdk": "0.1.13",
+        "@playcademy/sdk": "0.1.14",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
         "typescript": "^5.7.2"