workos 0.9.0 → 0.10.1

package/skills/workos-authkit-tanstack-start/SKILL.md

@@ -1,314 +0,0 @@
----
-name: workos-authkit-tanstack-start
-description: Integrate WorkOS AuthKit with TanStack Start applications. Full-stack TypeScript with server functions. Use when project uses TanStack Start, @tanstack/start, or vinxi.
----
-
-# WorkOS AuthKit for TanStack Start
-
-## Decision Tree
-
-```
-1. Fetch README (BLOCKING)
-   ├── Extract package name from install command
-   └── README is source of truth for ALL code patterns
-
-2. Detect directory structure
-   ├── src/ (TanStack Start v1.132+, default)
-   └── app/ (legacy vinxi-based projects)
-
-3. Follow README install/setup exactly
-   └── Do not invent commands or patterns
-```
-
-## Fetch SDK Documentation (BLOCKING)
-
-**STOP - Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/authkit-tanstack-start/main/README.md`
-
-From README, extract:
-
-1. Package name: `@workos/authkit-tanstack-react-start`
-2. Use that exact name for all imports
-
-**README overrides this skill if conflict.**
-
-## Pre-Flight Checklist
-
-- [ ] README fetched and package name extracted
-- [ ] `@tanstack/start` or `@tanstack/react-start` in package.json
-- [ ] Identify directory structure: `src/` (modern) or `app/` (legacy)
-- [ ] Environment variables set (see below)
-
-## Directory Structure Detection
-
-**Modern TanStack Start (v1.132+)** uses `src/`:
-
-```
-src/
-├── start.ts              # Middleware config (CRITICAL)
-├── router.tsx            # Router setup
-├── routes/
-│   ├── __root.tsx        # Root layout
-│   ├── api.auth.callback.tsx  # OAuth callback (flat route)
-│   └── ...
-```
-
-**Legacy (vinxi-based)** uses `app/`:
-
-```
-app/
-├── start.ts or router.tsx
-├── routes/
-│   └── api/auth/callback.tsx  # OAuth callback (nested route)
-```
-
-**Detection:**
-
-```bash
-ls src/routes 2>/dev/null && echo "Modern (src/)" || echo "Legacy (app/)"
-```
-
-## Environment Variables
-
-| Variable                 | Format       | Required |
-| ------------------------ | ------------ | -------- |
-| `WORKOS_API_KEY`         | `sk_...`     | Yes      |
-| `WORKOS_CLIENT_ID`       | `client_...` | Yes      |
-| `WORKOS_REDIRECT_URI`    | Full URL     | Yes      |
-| `WORKOS_COOKIE_PASSWORD` | 32+ chars    | Yes      |
-
-Generate password if missing: `openssl rand -base64 32`
-
-Default redirect URI: `http://localhost:3000/api/auth/callback`
-
-## Middleware Configuration (CRITICAL)
-
-**authkitMiddleware MUST be configured or auth will fail silently.**
-
-**WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.**
-
-### If `start.ts` already exists
-
-Read the existing file first. Add `authkitMiddleware` to the existing `requestMiddleware` array (or create the array if missing). Preserve the existing export style. Do not rewrite the file from scratch.
-
-### If `start.ts` does not exist
-
-Create `src/start.ts` (or `app/start.ts` for legacy) using `createStart`:
-
-```typescript
-import { createStart } from '@tanstack/react-start';
-import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';
-
-export const startInstance = createStart(() => ({
-  requestMiddleware: [authkitMiddleware()],
-}));
-```
-
-**Two things matter here:**
-
-1. **Named export `startInstance`** — the build plugin generates `import type { startInstance }` from this file. A `default` export will cause a build error.
-2. **`createStart` takes a function** returning the options object, not the options directly. `createStart({ ... })` will fail.
-
-**WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.**
-
-## Callback Route (CRITICAL)
-
-Path must match `WORKOS_REDIRECT_URI`. For `/api/auth/callback`:
-
-**Modern (flat routes):** `src/routes/api.auth.callback.tsx`
-**Legacy (nested routes):** `app/routes/api/auth/callback.tsx`
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router';
-import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';
-
-export const Route = createFileRoute('/api/auth/callback')({
-  server: {
-    handlers: {
-      GET: handleCallbackRoute(),
-    },
-  },
-});
-```
-
-**Key points:**
-
-- Use `handleCallbackRoute()` - do not write custom OAuth logic
-- Route path string must match the URI path exactly
-- This is a server-only route (no component needed)
-
-## Protected Routes
-
-Use `getAuth()` in route loaders to check authentication:
-
-```typescript
-import { createFileRoute, redirect } from '@tanstack/react-router';
-import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';
-
-export const Route = createFileRoute('/dashboard')({
-  loader: async () => {
-    const { user } = await getAuth();
-    if (!user) {
-      const signInUrl = await getSignInUrl();
-      throw redirect({ href: signInUrl });
-    }
-    return { user };
-  },
-  component: Dashboard,
-});
-```
-
-## Sign Out Route
-
-```typescript
-import { createFileRoute, redirect } from '@tanstack/react-router';
-import { signOut } from '@workos/authkit-tanstack-react-start';
-
-export const Route = createFileRoute('/signout')({
-  loader: async () => {
-    await signOut();
-    throw redirect({ href: '/' });
-  },
-});
-```
-
-## Client-Side Hooks (Optional)
-
-Only needed if you want reactive auth state in components.
-
-**1. Add AuthKitProvider to root:**
-
-```typescript
-// src/routes/__root.tsx
-import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';
-
-function RootComponent() {
-  return (
-    <AuthKitProvider>
-      <Outlet />
-    </AuthKitProvider>
-  );
-}
-```
-
-**2. Use hooks in components:**
-
-```typescript
-import { useAuth } from '@workos/authkit-tanstack-react-start/client';
-
-function Profile() {
-  const { user, isLoading } = useAuth();
-  // ...
-}
-```
-
-**Note:** Server-side `getAuth()` is preferred for most use cases.
-
-## Finalize (REQUIRED before declaring success)
-
-After creating/editing all files, run these steps in order. Skipping them is the most common cause of build failures.
-
-### 1. Regenerate the route tree
-
-Adding new route files (callback, signout, etc.) makes the existing `routeTree.gen.ts` stale. The build will fail with type errors about missing routes until it is regenerated.
-
-```bash
-pnpm build 2>/dev/null || npx tsr generate
-```
-
-The build itself triggers route tree regeneration. If it fails for other reasons, use `tsr generate` directly.
-
-### 2. Ensure Vite type declarations exist
-
-TanStack Start projects import CSS with `import styles from './styles.css?url'`. Without Vite's type declarations, TypeScript will error on these imports. Check if `src/vite-env.d.ts` (or `app/vite-env.d.ts`) exists — if not, create it now (before attempting the build):
-
-```typescript
-/// <reference types="vite/client" />
-```
-
-### 3. Verify the build
-
-```bash
-pnpm build
-```
-
-Do not skip this step. If the build fails, fix the errors before finishing. Common causes:
-
-- Stale route tree → re-run step 1
-- Missing Vite types → re-run step 2
-- Wrong import paths → check package name is `@workos/authkit-tanstack-react-start`
-
-## Verification Checklist (ALL MUST PASS)
-
-Run these commands to confirm integration. **Do not mark complete until all pass:**
-
-```bash
-# 1. Check authkitMiddleware is configured
-grep -r "authkitMiddleware" src/ app/ 2>/dev/null || echo "FAIL: Middleware not configured"
-
-# 2. Check callback route exists
-find src/routes app/routes -name "*callback*" 2>/dev/null
-
-# 3. Check environment variables
-grep -c "WORKOS_" .env 2>/dev/null || echo "FAIL: No env vars found"
-
-# 4. Build succeeds
-pnpm build
-```
-
-**If check #1 fails:** authkitMiddleware must be in src/start.ts (or app/start.ts for legacy) requestMiddleware array. Auth will fail silently without it.
-
-## Error Recovery
-
-### "AuthKit middleware is not configured"
-
-**Cause:** `authkitMiddleware()` not in start.ts
-**Fix:** Create/update `src/start.ts` with middleware config
-**Verify:** `grep -r "authkitMiddleware" src/`
-
-### "Module not found" for SDK
-
-**Cause:** Wrong package name or not installed
-**Fix:** `pnpm add @workos/authkit-tanstack-react-start`
-**Verify:** `ls node_modules/@workos/authkit-tanstack-react-start`
-
-### Callback 404
-
-**Cause:** Route file path doesn't match WORKOS_REDIRECT_URI
-**Fix:**
-
-- URI `/api/auth/callback` → file `src/routes/api.auth.callback.tsx` (flat) or `app/routes/api/auth/callback.tsx` (nested)
-- Route path string in `createFileRoute()` must match exactly
-
-### getAuth returns undefined user
-
-**Cause:** Middleware not configured or not running
-**Fix:** Ensure `authkitMiddleware()` is in start.ts requestMiddleware array
-
-### "Cookie password too short"
-
-**Cause:** WORKOS_COOKIE_PASSWORD < 32 chars
-**Fix:** `openssl rand -base64 32`, update .env
-
-### Build fails with route type errors
-
-**Cause:** Route tree not regenerated after adding routes
-**Fix:** `pnpm dev` to regenerate `routeTree.gen.ts`
-
-## SDK Exports Reference
-
-**Server (main export):**
-
-- `authkitMiddleware()` - Request middleware
-- `handleCallbackRoute()` - OAuth callback handler
-- `getAuth()` - Get current session
-- `signOut()` - Sign out user
-- `getSignInUrl()` / `getSignUpUrl()` - Auth URLs
-- `switchToOrganization()` - Change org context
-
-**Client (`/client` subpath):**
-
-- `AuthKitProvider` - Context provider
-- `useAuth()` - Auth state hook
-- `useAccessToken()` - Token management

package/skills/workos-authkit-vanilla-js/SKILL.md

@@ -1,92 +0,0 @@
----
-name: workos-authkit-vanilla-js
-description: Integrate WorkOS AuthKit with vanilla JavaScript applications. No framework required, browser-only. Use when project is plain HTML/JS, doesn't use React/Vue/etc, or mentions vanilla JavaScript authentication.
----
-
-# WorkOS AuthKit for Vanilla JavaScript
-
-## Decision Tree
-
-### Step 1: Fetch README (BLOCKING)
-
-WebFetch: `https://raw.githubusercontent.com/workos/authkit-js/main/README.md`
-
-**README is source of truth.** If this skill conflicts, follow README.
-
-### Step 2: Detect Project Type
-
-```
-Has package.json with build tool (Vite, webpack, Parcel)?
-  YES -> Bundled project (npm install)
-  NO  -> CDN/Static project (script tag)
-```
-
-### Step 3: Follow README Installation
-
-- **Bundled**: Use package manager install from README
-- **CDN**: Use unpkg script tag from README
-
-### Step 4: Implement Per README
-
-Follow README examples for:
-
-- Client initialization
-- Sign in/out handlers
-- User state management
-
-## Critical API Quirk
-
-`createClient()` is **async** - returns a Promise, not a client directly.
-
-```javascript
-// CORRECT
-const authkit = await createClient(clientId);
-```
-
-## Verification Checklist (ALL MUST PASS)
-
-Run these commands to confirm integration. **Do not mark complete until all pass:**
-
-```bash
-# 1. Check SDK is available (bundled or CDN)
-grep -r "createClient\|WorkOS" src/ *.html 2>/dev/null || echo "FAIL: SDK not found"
-
-# 2. Check createClient uses await
-grep -rn "await createClient" src/ *.js *.html 2>/dev/null || echo "FAIL: createClient must be awaited"
-
-# 3. Check sign-in is on user gesture (click handler)
-grep -rn "signIn\|sign_in" src/ *.js *.html 2>/dev/null
-
-# 4. Build succeeds (bundled projects only)
-pnpm build 2>/dev/null || echo "CDN project — verify manually in browser"
-```
-
-**If check #2 fails:** createClient() is async and must be awaited. Using it without await returns a Promise, not a client.
-
-## Environment Variables
-
-**Bundled projects only:**
-
-- Vite: `VITE_WORKOS_CLIENT_ID`
-- Webpack: `REACT_APP_WORKOS_CLIENT_ID` or custom
-- No `WORKOS_API_KEY` needed (client-side SDK)
-
-## Error Recovery
-
-| Error                            | Cause               | Fix                                                    |
-| -------------------------------- | ------------------- | ------------------------------------------------------ |
-| `WorkOS is not defined`          | CDN not loaded      | Add script to `<head>` before your code                |
-| `createClient is not a function` | Wrong import        | npm: check import path; CDN: use `WorkOS.createClient` |
-| `clientId is required`           | Undefined env var   | Check env prefix matches build tool                    |
-| CORS errors                      | `file://` protocol  | Use local dev server (`npx serve`)                     |
-| Popup blocked                    | Not user gesture    | Call `signIn()` only from click handler                |
-| Auth state lost                  | Token not persisted | Check localStorage in dev tools                        |
-
-## Task Flow
-
-1. **preflight**: Fetch README, detect project type, verify env vars
-2. **install**: Add SDK per project type
-3. **callback**: SDK handles internally (no server route needed)
-4. **provider**: Initialize client with `await createClient()`
-5. **ui**: Add auth buttons and state display
-6. **verify**: Build (if bundled), check console

package/skills/workos-dotnet/SKILL.md

@@ -1,163 +0,0 @@
----
-name: workos-dotnet
-description: Integrate WorkOS AuthKit with .NET (ASP.NET Core). Backend authentication with DI registration, auth endpoints, and appsettings configuration.
----
-
-# WorkOS AuthKit for .NET (ASP.NET Core)
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-dotnet/main/README.md`
-
-The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
-
-## Step 2: Pre-Flight Validation
-
-### Project Structure
-
-- Confirm a `*.csproj` file exists in the project root
-- Detect project style:
-  - **Minimal API** (modern): `Program.cs` with `WebApplication.CreateBuilder()` — .NET 6+
-  - **Startup pattern** (older): `Startup.cs` with `ConfigureServices()` / `Configure()` — .NET 5 and earlier
-
-This detection determines WHERE to register WorkOS services and middleware.
-
-### Environment Variables
-
-Check `appsettings.Development.json` for:
-
-- `WORKOS_API_KEY` — starts with `sk_`
-- `WORKOS_CLIENT_ID` — starts with `client_`
-
-## Step 3: Install SDK
-
-```bash
-dotnet add package WorkOS.net
-```
-
-**Verify:** Check the `*.csproj` file contains a `<PackageReference Include="WorkOS.net"` entry.
-
-If `dotnet` CLI is not available, stop and inform the user to install the .NET SDK.
-
-## Step 4: Configure WorkOS Client
-
-### Minimal API Pattern (Program.cs)
-
-Add WorkOS configuration to `Program.cs`:
-
-1. Read WorkOS settings from `IConfiguration`
-2. Register the WorkOS client in the DI container
-3. The WorkOS client needs API key for initialization
-
-```csharp
-// In Program.cs, after builder creation:
-var workosApiKey = builder.Configuration["WorkOS:ApiKey"];
-var workosClientId = builder.Configuration["WorkOS:ClientId"];
-```
-
-### Startup Pattern (Startup.cs)
-
-Add to `ConfigureServices()`:
-
-1. Read WorkOS settings from `IConfiguration`
-2. Register services
-
-Choose the pattern that matches the detected project structure.
-
-## Step 5: Create Authentication Endpoints
-
-Create auth endpoints following the WorkOS AuthKit pattern. Use minimal API `app.MapGet()` for minimal API projects, or a Controller for Startup-pattern projects.
-
-### Required Endpoints
-
-**GET /auth/login** — Redirect to WorkOS AuthKit:
-
-- Use the WorkOS SDK to generate an authorization URL
-- Include `clientId`, `redirectUri`, and `provider: "authkit"` parameters
-- Redirect the user to the authorization URL
-
-**GET /auth/callback** — Handle OAuth callback:
-
-- Extract `code` from query parameters
-- Exchange authorization code for user profile using the WorkOS SDK
-- Store user info in session or cookie
-- Redirect to home page
-
-**GET /auth/logout** — Clear session:
-
-- Clear the authentication session/cookie
-- Redirect to home page
-
-### Session Management
-
-Use ASP.NET Core's built-in session or cookie authentication:
-
-```csharp
-// Enable session middleware in Program.cs
-builder.Services.AddDistributedMemoryCache();
-builder.Services.AddSession();
-// ...
-app.UseSession();
-```
-
-## Step 6: Environment Setup
-
-Configure `appsettings.Development.json` with WorkOS credentials:
-
-```json
-{
-  "WorkOS": {
-    "ApiKey": "<WORKOS_API_KEY value>",
-    "ClientId": "<WORKOS_CLIENT_ID value>",
-    "RedirectUri": "http://localhost:5000/auth/callback"
-  }
-}
-```
-
-Use the actual credential values provided in the environment context.
-
-**Important:** Do NOT put secrets in `appsettings.json` (committed to git). Use `appsettings.Development.json` (gitignored) or `dotnet user-secrets`.
-
-## Step 7: Verification
-
-Run these checks — **do not mark complete until all pass:**
-
-```bash
-# 1. Check WorkOS.net is in csproj
-grep -i "WorkOS" *.csproj
-
-# 2. Check auth endpoints exist
-grep -r "auth/login\|auth/callback\|auth/logout" *.cs
-
-# 3. Build succeeds
-dotnet build
-```
-
-**If build fails:** Read the error output carefully. Common issues:
-
-- Missing `using` statements for WorkOS namespaces
-- Incorrect DI registration order
-- Missing session/cookie middleware registration
-
-## Error Recovery
-
-### "dotnet: command not found"
-
-- .NET SDK is not installed. Inform the user to install from https://dotnet.microsoft.com/download
-
-### NuGet restore failures
-
-- Check internet connectivity
-- Try `dotnet restore` explicitly before `dotnet build`
-
-### "No project file found"
-
-- Ensure you're in the correct directory with a `*.csproj` file
-
-### Build errors after integration
-
-- Check that all `using` statements are correct
-- Verify DI registration order (services before middleware)
-- Ensure `app.UseSession()` is called before mapping auth endpoints