authula 0.5.4 → 0.7.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-<img src="./project-logo.png" width="200" />
+  <img src="./project-logo.png" width="200" />
 </p>
 
 <p align="center">
@@ -14,15 +14,39 @@ This Node.js SDK provides seamless integration with an Authula server for both c
 
 ---
 
+## 🚨 Breaking Changes
+
+Starting with v0.6.x, the SDK transitions to an automated, schema-driven architecture powered by Orval. Code generation is now tied 1-to-1 with the Authula backend OpenAPI specification, ensuring absolute parity and enhanced reliability.
+
+This architectural shift introduces several breaking changes to the SDK footprint:
+
+1. Relocation of Core Methods
+
+   What changed: Core utility methods have been consolidated.
+
+   Impact: Any foundational system methods have moved directly into the Core Plugin namespace, as the underlying Authula engine now explicitly groups these operations under the core OpenAPI tag.
+
+2. Standardized Method Signatures via Orval
+
+   What changed: Every Authula plugin now exposes its feature set via auto-generated endpoints.
+
+   Impact: While plugins remain organized under their original top-level objects, individual method names, parameters, and payloads may have changed to match the strict schema specification.
+
+3. Unified Server & Client Support
+
+   The Benefit: Each plugin now natively exports decoupled, standalone methods optimized for server-side execution, alongside fully typed TanStack Query hooks dedicated to client-side web applications.
+
+   Why this matters: Moving forward, this SDK will perfectly mirror upstream backend updates with zero drift, drastically reducing runtime bugs and offering complete type safety across your entire stack.
+
 ## Features
 
 - **Framework Agnostic**: Works with Next.js/React, Vue.js and more
 - **Full TypeScript Support**: Complete TypeScript definitions with strict typing
-- **SSR Safe**: Supports proper cookie handling for SSR apps
 - **CSRF Protection**: Automatic CSRF token handling for mutating requests
 - **Multiple Auth Methods**: Email/password, OAuth2, JWT-based authentication
 - **Plugin Architecture**: Extensible plugin system for custom authentication flows
 - **Automatic Token Refresh**: Built-in bearer token refresh mechanism
+- **Built-in support for Zod and Tanstack Query**: provides types and zod schemas out of the box along with tanstack query code for all available methods.
 
 ## Installation
 
@@ -38,742 +62,91 @@ pnpm add authula
 
 ### Basic Setup
 
-```typescript
-import { createClient } from "authula";
-import { EmailPasswordPlugin } from "authula/plugins";
-
-// Create a client instance
-const authulaClient = createClient({
-  // Your Authula server URL
-  url: "http://localhost:8080/auth",
-  plugins: [new EmailPasswordPlugin()],
-});
-
-// Now you can use the client to perform authentication operations
-```
+`Client instance`:
 
-### Using with Cookies (SSR Compatible)
-
-For server-side rendering or applications that need to handle cookies properly:
+Use with SPA (Vite etc.)
 
 ```typescript
-import { cookies } from "next/headers";
-
 import { createClient } from "authula";
-import { EmailPasswordPlugin, CSRFPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  cookies: cookies, // Provide cookie store for SSR
-  plugins: [
-    new EmailPasswordPlugin(),
-    new CSRFPlugin({
-      cookieName: "authula_csrf_token",
-      headerName: "X-AUTHULA-CSRF-TOKEN",
-    }),
-  ],
-});
-```
-
-## Core Client Methods
-
-The client provides built-in methods for essential authentication operations:
-
-### Get Current User
-
-Retrieve information about the currently authenticated user:
-
-```typescript
-const { user, session } = await authulaClient.getMe();
-
-console.log(user.email);
-console.log(session.id);
-```
-
-### Sign Out
-
-Sign out the current user or all sessions:
-
-```typescript
-// Sign out current session
-await authulaClient.signOut({});
-
-// Sign out all sessions
-await authulaClient.signOut({
-  signOutAll: true,
-});
-
-// Sign out a specific session
-await authulaClient.signOut({
-  sessionId: "session-id",
-});
-```
-
-### Get Plugin Instance
-
-Access a plugin instance programmatically:
-
-```typescript
-const emailPasswordPlugin = authulaClient.getPlugin("emailPassword");
-
-// Use the plugin
-if (emailPasswordPlugin) {
-  // Plugin methods are now available
-}
-```
-
-## Available Plugins
-
-### Access Control Plugin
-
-Provides role-based access control (RBAC) management for users, including roles, permissions, and their assignments.
-
-```typescript
-import { AccessControlPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new AccessControlPlugin()],
-});
-```
-
-#### Role Management
-
-```typescript
-// Create a new role
-const createdRole = await authulaClient.accessControl.createRole({
-  name: "Admin",
-  description: "Administrator role",
-  isSystem: false,
-});
-
-// Get all roles
-const allRoles = await authulaClient.accessControl.getAllRoles();
-
-// Look up a role by name
-const roleByName = await authulaClient.accessControl.getRoleByName("Admin");
-
-// Get a specific role
-const roleDetails = await authulaClient.accessControl.getRoleById("role-id");
-
-// Update a role
-const updatedRole = await authulaClient.accessControl.updateRole("role-id", {
-  name: "Updated name",
-  description: "Updated description",
-});
-
-// Delete a role
-const deleteRoleResult =
-  await authulaClient.accessControl.deleteRole("role-id");
-```
-
-#### Permission Management
-
-```typescript
-// Create a new permission
-const createdPermission = await authulaClient.accessControl.createPermission({
-  key: "users.create",
-  description: "Create new users",
-  isSystem: false,
-});
-
-// Get all permissions
-const allPermissions = await authulaClient.accessControl.getAllPermissions();
-
-// Get a specific permission
-const permission =
-  await authulaClient.accessControl.getPermissionById("permission-id");
-
-// Update a permission
-const updatedPermission = await authulaClient.accessControl.updatePermission(
-  "permission-id",
-  {
-    description: "Updated permission description",
-  },
-);
-
-// Delete a permission
-const deletePermissionResult =
-  await authulaClient.accessControl.deletePermission("permission-id");
-```
-
-#### Role-Permission Management
-
-```typescript
-// Add a permission to a role
-const addPermissionResult = await authulaClient.accessControl.addRolePermission(
-  "role-id",
-  {
-    permissionId: "permission-id",
-  },
-);
-
-// Get all permissions for a role
-const rolePermissions =
-  await authulaClient.accessControl.getRolePermissions("role-id");
-
-// Replace all permissions for a role
-const replaceRolePermissionsResult =
-  await authulaClient.accessControl.replaceRolePermissions("role-id", {
-    permissionIds: ["permission-id-1", "permission-id-2", "permission-id-3"],
-  });
-
-// Remove a permission from a role
-const removeRolePermissionResult =
-  await authulaClient.accessControl.removeRolePermission(
-    "role-id",
-    "permission-id",
-  );
-```
-
-#### User Role Management
-
-```typescript
-// Get all roles assigned to a user
-const userRoles = await authulaClient.accessControl.getUserRoles("user-id");
-
-// Assign a role to a user
-const assignUserRoleResult = await authulaClient.accessControl.assignUserRole(
-  "user-id",
-  {
-    roleId: "role-id",
-    expiresAt: new Date("2025-12-31"), // Optional: role expiration date
-  },
-);
-
-// Replace all roles for a user
-const replaceUserRolesResult =
-  await authulaClient.accessControl.replaceUserRoles("user-id", {
-    roleIds: ["role-id-1", "role-id-2"],
-  });
-
-// Remove a role from a user
-const removeUserRoleResult = await authulaClient.accessControl.removeUserRole(
-  "user-id",
-  "role-id",
-);
-```
-
-#### User Permission Management
-
-```typescript
-// Get all effective permissions for a user (from all assigned roles)
-const effectivePermissions =
-  await authulaClient.accessControl.getUserPermissions("user-id");
-
-// Check whether the user has all requested permissions
-const permissionCheck = await authulaClient.accessControl.checkUserPermissions(
-  "user-id",
-  {
-    permissionKeys: ["users.create", "users.update"],
-  },
-);
-```
-
----
-
-### Organizations Plugin
-
-Provides the ability to manage organizations, members, teams and invitations.
-
-```typescript
-import { OrganizationsPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new OrganizationsPlugin()],
-});
-
-// Organizations
-
-await authulaClient.organizations.createOrganization({
-  name: "Acme Inc.",
-  slug: "acme-inc",
-  logo: "https://example.com/logo.svg",
-  metadata: { key: "value" },
-});
-
-await authulaClient.organizations.getAllOrganizations();
-
-await authulaClient.organizations.getOrganizationById("organization-id");
-
-await authulaClient.organizations.updateOrganization("organization-id", {
-  name: "Updated name",
-});
-
-await authulaClient.organizations.deleteOrganization("organization-id");
-
-// Invitations
-
-await authulaClient.organizations.createOrganizationInvitation(
-  "organization-id",
-  {
-    email: "user@example.com",
-    role: "member",
-    redirectUrl: "https://example.com/invite",
-  },
-);
-
-await authulaClient.organizations.getAllOrganizationInvitations(
-  "organization-id",
-);
-
-await authulaClient.organizations.getOrganizationInvitation(
-  "organization-id",
-  "invitation-id",
-);
-
-await authulaClient.organizations.revokeOrganizationInvitation(
-  "organization-id",
-  "invitation-id",
-);
-
-await authulaClient.organizations.acceptOrganizationInvitation(
-  "organization-id",
-  "invitation-id",
-  {
-    redirectUrl: "https://example.com/accepted",
-  },
-);
-
-await authulaClient.organizations.rejectOrganizationInvitation(
-  "organization-id",
-  "invitation-id",
-);
-
-// Members
-
-await authulaClient.organizations.addOrganizationMember("organization-id", {
-  userId: "user-id",
-  role: "owner",
-});
-
-await authulaClient.organizations.getAllOrganizationMembers("organization-id");
-
-await authulaClient.organizations.getOrganizationMember(
-  "organization-id",
-  "member-id",
-);
-
-await authulaClient.organizations.updateOrganizationMember(
-  "organization-id",
-  "member-id",
-  {
-    role: "owner",
-  },
-);
-
-await authulaClient.organizations.deleteOrganizationMember(
-  "organization-id",
-  "member-id",
-);
-
-// Teams
+import { CorePlugin, EmailPasswordPlugin } from "authula/plugins";
 
-await authulaClient.organizations.createOrganizationTeam("organization-id", {
-  name: "Platform",
-  slug: "platform",
-  description: "Platform team",
-  metadata: { key: "value" },
-});
-
-await authulaClient.organizations.getAllOrganizationTeams("organization-id");
-
-await authulaClient.organizations.updateOrganizationTeam(
-  "organization-id",
-  "team-id",
-  {
-    name: "Platform",
-    slug: "platform",
-    description: "Updated team description",
-    metadata: { key: "value" },
-  },
-);
-await authulaClient.organizations.deleteOrganizationTeam(
-  "organization-id",
-  "team-id",
-);
-
-// Team Members
-
-await authulaClient.organizations.addOrganizationTeamMember(
-  "organization-id",
-  "team-id",
-  {
-    memberId: "member-id",
-  },
-);
-await authulaClient.organizations.getAllOrganizationTeamMembers(
-  "organization-id",
-  "team-id",
-);
-await authulaClient.organizations.getOrganizationTeamMember(
-  "organization-id",
-  "team-id",
-  "member-id",
-);
-await authulaClient.organizations.deleteOrganizationTeamMember(
-  "organization-id",
-  "team-id",
-  "member-id",
-);
-```
-
----
-
-### Admin Plugin
-
-Provides the ability to manage users, accounts, sessions, and impersonations.
-
-```typescript
-import { AdminPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new AdminPlugin()],
-});
-```
-
-#### User Management
-
-```typescript
-await authulaClient.admin.createUser({
-  name: "John Doe",
-  email: "user@example.com",
-  // other fields...
-});
-
-// Get all users with pagination
-const users = await authulaClient.admin.getAllUsers(100);
-
-// Get a specific user by ID
-const user = await authulaClient.admin.getUserById("user-id");
-
-// Update user information
-await authulaClient.admin.updateUser("user-id", { name: "Jane" });
-
-// Delete a user
-await authulaClient.admin.deleteUser("user-id");
-```
-
-#### Account Management
-
-```typescript
-// Create a new account for a user
-await authulaClient.admin.createAccount("user-id", {
-  /* account data */
-});
-
-// Get all accounts for a user
-await authulaClient.admin.getUserAccounts("user-id");
-
-// Get a specific account by ID
-await authulaClient.admin.getAccountById("account-id");
-
-// Update account information
-await authulaClient.admin.updateAccount("account-id", {
-  /* data */
-});
-
-// Delete an account
-await authulaClient.admin.deleteAccount("account-id");
-```
-
-#### User State Management
-
-```typescript
-// Get user state
-await authulaClient.admin.getUserState("user-id");
-
-// Create or update user state
-await authulaClient.admin.createUserState("user-id", {
-  /* state data */
-});
-
-// Update user state
-await authulaClient.admin.updateUserState("user-id", {
-  /* state data */
-});
-
-// Delete user state
-await authulaClient.admin.deleteUserState("user-id");
-
-// Get all banned user states
-await authulaClient.admin.getBannedUserStates();
-
-// Ban a user
-await authulaClient.admin.banUser("user-id", { reason: "reason..." });
-
-// Unban a user
-await authulaClient.admin.unbanUser("user-id");
-
-// Get all active sessions for a user
-await authulaClient.admin.getUserAdminSessions("user-id");
-```
-
-#### Session State Management
-
-```typescript
-// Get session state
-await authulaClient.admin.getSessionState("session-id");
-
-// Create or update session state
-await authulaClient.admin.createSessionState("session-id", {
-  /* data */
-});
-
-// Update session state
-await authulaClient.admin.updateSessionState("session-id", {
-  /* data */
+const authulaBrowserClient = createClient({
+  // Your Authula server URL
+  url: "http://localhost:8080/api/auth",
+  plugins: [new CorePlugin(), new EmailPasswordPlugin()],
 });
 
-// Delete session state
-await authulaClient.admin.deleteSessionState("session-id");
-
-// Get all revoked session states
-await authulaClient.admin.getRevokedSessionStates();
-
-// Revoke a session
-await authulaClient.admin.revokeSession("session-id", { reason: "reason..." });
-```
-
-#### Impersonations
+// Direct method call
+const response = await authulaBrowserClient.core.getMe();
 
-```typescript
-// Get all active impersonations
-await authulaClient.admin.getAllImpersonations();
-
-// Get a specific impersonation by ID
-await authulaClient.admin.getImpersonationById("impersonation-id");
-
-// Start impersonating a user
-await authulaClient.admin.startImpersonation({ user_id: "user-id" /* data */ });
-
-// Stop impersonation
-await authulaClient.admin.stopImpersonation("impersonation-id");
+// Tanstack Query
+const { data, error, isLoading, isError } =
+  await authulaBrowserClient.core.useGetMe();
 ```
 
----
-
-### Email Password Plugin
+`Server instance`:
 
-Handles traditional email/password authentication flows.
+Use with SSR frameworks e.g. Next.js/Tanstack Start etc.
 
 ```typescript
-import { EmailPasswordPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new EmailPasswordPlugin()],
-});
-
-// Sign up
-await authulaClient.emailPassword.signUp({
-  name: "John Doe",
-  email: "john@example.com",
-  password: "securePassword123",
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
-
-// Sign in
-const response = await authulaClient.emailPassword.signIn({
-  email: "john@example.com",
-  password: "securePassword123",
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
+import { cookies } from "next/headers";
 
-// Send email verification
-await authulaClient.emailPassword.sendEmailVerification({
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
+import { createClient } from "authula";
+import { CorePlugin, EmailPasswordPlugin } from "authula/plugins";
 
-// Request password reset
-await authulaClient.emailPassword.requestPasswordReset({
-  email: "john@example.com",
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
+const authulaServerClient = createClient({
+  // Your Authula server URL
+  url: "http://localhost:8080/api/auth",
+  plugins: [new CorePlugin(), new EmailPasswordPlugin()],
+  // For frameworks other than Next.js, you may need to implement this cookies object manually by implementing the interface.
+  cookies: cookies,
 });
 
-// Change password
-await authulaClient.emailPassword.changePassword({
-  token: "reset-token",
-  password: "newSecurePassword123",
-});
+// Now you can use the client...
 
-// Request email change
-await authulaClient.emailPassword.requestEmailChange({
-  email: "john.doe@example.com",
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
+const response = await authulaServerClient.core.getMe();
 ```
 
----
-
-### OAuth2 Plugin
+### Using with Cookies (SSR Compatible)
 
-Handles OAuth2 authentication with popular providers.
+For server-side rendering or applications that need to handle cookies properly:
 
 ```typescript
-import { OAuth2Plugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new OAuth2Plugin()],
-});
-
-// Redirect user to OAuth2 provider
-const response = await authulaClient.oauth2.signIn({
-  provider: "google", // or "github", "discord"
-  redirect_to: "http://localhost:3000/callback",
-});
-
-// Redirect user to the authUrl
-window.location.href = response.auth_url;
-```
-
----
-
-### CSRF Plugin
-
-Provides automatic CSRF protection for mutating requests.
+import { cookies } from "next/headers";
 
-```typescript
-import { CSRFPlugin } from "authula/plugins";
+import { createClient } from "authula";
+import { CorePlugin, EmailPasswordPlugin, CSRFPlugin } from "authula/plugins";
 
 const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  cookies: ..., // Provide cookie store for SSR if needed, else omit for SPA/Mobile apps
+  url: "http://localhost:8080/api/auth",
   plugins: [
+    new CorePlugin(),
+    new EmailPasswordPlugin(),
     new CSRFPlugin({
-      cookieName: "csrf_token",    // Name of the CSRF token cookie
-      headerName: "X-CSRF-TOKEN"   // Header name to send the token
-    })
-  ]
-});
-
-// CSRF tokens will be automatically added to mutating requests (POST, PUT, PATCH, DELETE)
-```
-
----
-
-### JWT Plugin
-
-Handles JWT token operations including refresh.
-
-```typescript
-import { JWTPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new JWTPlugin()],
-});
-
-// Refresh JWT tokens
-const tokens = await authulaClient.jwt.refreshToken({
-  refresh_token: "your-refresh-token",
-});
-
-// Get JWKS keys
-const jwksKeys = await authulaClient.jwt.getJWKSKeys();
-```
-
----
-
-### Bearer Plugin
-
-Provides automatic bearer token handling and refresh.
-
-```typescript
-import { BearerPlugin, JWTPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [
-    new JWTPlugin(),
-    new BearerPlugin({
-      headerName: "Authorization", // Can be omitted as default is Authorization
+      cookieName: "authula_csrf_token",
+      headerName: "X-AUTHULA-CSRF-TOKEN",
     }),
   ],
+  cookies,
 });
-
-// The Bearer plugin will automatically:
-// 1. Add Authorization: Bearer <token> header to requests
-// 2. Handle token refresh when receiving 401 responses
-// 3. Store tokens in localStorage (access_token and refresh_token)
 ```
 
----
-
-### Magic Link Plugin
-
-Provides flows for passwordless authentication.
-
-```typescript
-import { MagicLinkPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new MagicLinkPlugin()],
-});
-
-// Send magic link via email
-await authulaClient.magicLink.signIn({
-  email: "john.doe@example.com",
-  name: "John Doe", // Optional name
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
-
-// Verify magic link token
-await authulaClient.magicLink.verify({
-  token: "magic-link-token",
-  callbackUrl: "http://localhost:3000/callback", // Optional callback URL
-});
-
-// Exchange token from verify endpoint for session
-await authulaClient.magicLink.exchange({
-  token: "magic-link-token",
-});
-```
-
----
-
-### TOTP Plugin
-
-Provides time-based one-time password (TOTP) two-factor authentication flows.
-
-```typescript
-import { TOTPPlugin } from "authula/plugins";
-
-const authulaClient = createClient({
-  url: "http://localhost:8080/auth",
-  plugins: [new TOTPPlugin()],
-});
-
-// Enable TOTP for the current user
-await authulaClient.totp.enable();
-
-// Disable TOTP for the current user
-await authulaClient.totp.disable();
-
-// Get the TOTP URI for QR code generation
-await authulaClient.totp.getUri();
-
-// Verify a TOTP code
-await authulaClient.totp.verify({
-  code: "123456",
-  trustDevice: true,
-});
-
-// Verify a backup code
-await authulaClient.totp.verifyBackupCode({
-  code: "AbcXyz",
-  trustDevice: true,
-});
-
-// Generate fresh backup codes
-await authulaClient.totp.generateBackupCodes();
-```
+## Available Plugins
 
----
+The following plugins are available in this SDK:
+
+- Core
+- Access Control
+- Admin
+- Organizations
+- API Key
+- Email Password
+- OAuth2
+- CSRF
+- JWT
+- Bearer
+- Magic Link
+- TOTP
 
 ## Advanced Configuration
 
@@ -786,6 +159,7 @@ const authulaClient = createClient({
   url: "http://localhost:8080/auth",
   fetchOptions: {
     abortTimeout: 30, // Timeout in seconds
+    headers: {}, // Custom headers
   },
   plugins: [
     // your plugins
@@ -800,7 +174,7 @@ Add custom before/after fetch hooks for advanced customization:
 ```typescript
 const authulaClient = createClient({
   url: "http://localhost:8080/auth",
-  plugins: [new EmailPasswordPlugin()],
+  plugins: [new CorePlugin()],
 });
 
 // Register a before fetch hook
@@ -822,40 +196,6 @@ authulaClient.registerAfterFetch(async (ctx, response) => {
 });
 ```
 
-## API Reference
-
-### Client Configuration
-
-```typescript
-{
-  // Base URL of your Authula server
-  url: string,
-  // Optional fetch configuration
-  fetchOptions?: {
-    // Request timeout in seconds
-    abortTimeout?: number
-  },
-  // Cookie provider for SSR compatibility
-  cookies?: () => CookieStore
-}
-```
-
-## Error Handling
-
-All methods return promises that can be caught for error handling:
-
-```typescript
-try {
-  const response = await authulaClient.emailPassword.signIn({
-    email: "user@example.com",
-    password: "password",
-  });
-  console.log("Signed in successfully", response);
-} catch (error) {
-  console.error("Sign in failed:", error);
-}
-```
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.