@xenterprises/nuxt-x-auth-better 0.3.2 → 0.4.0

package/README.md

@@ -257,6 +257,199 @@ This layer uses Better Auth's official Vue client (`better-auth/vue`) via `creat
 
 5. **Token access**: `getToken()` and `getAuthHeaders()` extract the access token from the Better Auth session for use with your own API calls.
 
+## Organizations & Teams
+
+The layer includes a full BetterAuth Organizations & Teams implementation. Enable it in `app.config.ts`:
+
+```ts
+xAuth: {
+  features: {
+    organization: true,
+    teams: true,
+  },
+  organization: {
+    enabled: true,
+    teams: true,
+  },
+}
+```
+
+### `useOrganization()` Composable
+
+```vue
+<script setup>
+const {
+  // State
+  organizations,
+  organizationsLoading,
+  activeOrganization,
+  activeLoading,
+  activeMember,
+  activeMemberRole,
+  members,
+  invitations,
+  teams,
+  isOrgAdmin,
+  isOrgOwner,
+  canCreateOrganization,
+
+  // Org CRUD
+  createOrganization,
+  updateOrganization,
+  deleteOrganization,
+  setActiveOrganization,
+  getFullOrganization,
+  checkSlug,
+
+  // Members
+  listMembers,
+  updateMemberRole,
+  removeMember,
+  leaveOrganization,
+
+  // Invitations
+  inviteMember,
+  cancelInvitation,
+  acceptInvitation,
+  rejectInvitation,
+  getInvitation,
+  listInvitations,
+  listUserInvitations,
+
+  // Teams
+  listTeams,
+  createTeam,
+  updateTeam,
+  deleteTeam,
+  setActiveTeam,
+  listTeamMembers,
+  addTeamMember,
+  removeTeamMember,
+  listUserTeams,
+
+  // Access control
+  hasPermission,
+  checkRolePermission,
+  getDefaultPermissions,
+} = useOrganization()
+</script>
+```
+
+#### Reactive State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `organizations` | `Ref<Organization[]>` | All orgs the user belongs to |
+| `organizationsLoading` | `Ref<boolean>` | Whether the org list is loading |
+| `activeOrganization` | `Ref<Organization \| null>` | Currently active organization |
+| `activeLoading` | `Ref<boolean>` | Whether the active org is loading |
+| `activeMember` | `Ref<OrganizationMember \| null>` | Current user's membership in active org |
+| `activeMemberRole` | `Ref<string \| null>` | Role of current user in active org |
+| `members` | `ComputedRef<OrganizationMember[]>` | Members of the active org |
+| `invitations` | `ComputedRef<OrganizationInvitation[]>` | Pending invitations for the active org |
+| `teams` | `ComputedRef<OrganizationTeam[]>` | Teams in the active org |
+| `isOrgAdmin` | `ComputedRef<boolean>` | User is owner or admin of active org |
+| `isOrgOwner` | `ComputedRef<boolean>` | User is owner of active org |
+| `canCreateOrganization` | `ComputedRef<boolean>` | User can create new organizations |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `createOrganization(name, slug?, logo?)` | Create a new organization |
+| `updateOrganization(data)` | Update organization details |
+| `deleteOrganization(organizationId?)` | Delete an organization |
+| `setActiveOrganization(organizationId?, organizationSlug?)` | Set the active organization |
+| `getFullOrganization(organizationId?, organizationSlug?)` | Fetch full org details |
+| `checkSlug(slug)` | Check if a slug is available |
+| `listMembers(organizationId?)` | List organization members |
+| `updateMemberRole(memberId, role, organizationId?)` | Update a member's role |
+| `removeMember(memberId, organizationId?)` | Remove a member |
+| `leaveOrganization()` | Leave the active organization |
+| `inviteMember(email, role, organizationId?)` | Invite a user by email |
+| `cancelInvitation(invitationId)` | Cancel a pending invitation |
+| `acceptInvitation(invitationId)` | Accept an invitation |
+| `rejectInvitation(invitationId)` | Reject an invitation |
+| `getInvitation(invitationId)` | Fetch invitation details |
+| `listInvitations(organizationId?)` | List org invitations |
+| `listUserInvitations()` | List current user's invitations |
+| `listTeams(organizationId?)` | List teams in an org |
+| `createTeam(name, organizationId?)` | Create a team |
+| `updateTeam(teamId, data, organizationId?)` | Update a team |
+| `deleteTeam(teamId, organizationId?)` | Delete a team |
+| `setActiveTeam(teamId)` | Set the active team |
+| `listTeamMembers(teamId)` | List members of a team |
+| `addTeamMember(teamId, memberId, organizationId?)` | Add a member to a team |
+| `removeTeamMember(teamId, memberId)` | Remove a member from a team |
+| `listUserTeams()` | List teams for current user |
+| `hasPermission(permissionCheck)` | Check if active member has a permission |
+| `checkRolePermission(role, permissions)` | Check permissions for a specific role |
+| `getDefaultPermissions(role)` | Get default permissions for a role |
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `XAuthOrganizationSwitcher` | List and switch between organizations |
+| `XAuthOrganizationCreate` | Create a new organization |
+| `XAuthOrganizationSettings` | Edit / delete organization |
+| `XAuthOrganizationMembers` | Manage organization members |
+| `XAuthOrganizationInvite` | Invite a new member |
+| `XAuthOrganizationInvitations` | List pending invitations |
+| `XAuthTeamList` | List teams in an organization |
+| `XAuthTeamCreate` | Create a team |
+| `XAuthTeamSettings` | Edit / delete team |
+| `XAuthTeamMembers` | Manage team members |
+
+### Pages (auto-registered)
+
+| Path | Description |
+|------|-------------|
+| `/org` | Organization list / switcher |
+| `/org/create` | Create a new organization |
+| `/org/:slug` | Organization dashboard |
+| `/org/:slug/settings` | Organization settings |
+| `/org/:slug/members` | Member list |
+| `/org/:slug/invite` | Invite member |
+| `/org/:slug/invitations` | Pending invitations |
+| `/org/:slug/teams` | Team list |
+| `/org/:slug/teams/create` | Create team |
+| `/org/:slug/teams/:teamId` | Team settings + members |
+| `/auth/handler/invitation?id=...` | Public invitation accept handler |
+
+### Middleware
+
+`organization.global.ts` runs on every navigation. For routes under `/org` (or any path configured in `organization.protectedRoutes`), it:
+
+1. Verifies organizations are enabled.
+2. Redirects unauthenticated users to the login page.
+3. Resolves the requested organization by slug and sets it active.
+4. Redirects non-members to the `notMember` redirect path.
+5. Enforces `requireOwner`, `requireAdmin`, and `requiredPermissions` rules on matched `OrganizationRoute` objects.
+
+### Server Setup & Custom Roles
+
+Add the `organization` plugin to your BetterAuth server config and enable teams on both server and client:
+
+```ts
+// server/auth.ts
+import { betterAuth } from 'better-auth'
+import { organization } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      allowUserToCreateOrganization: true,
+      teams: {
+        enabled: true,
+      },
+    }),
+  ],
+})
+```
+
+Custom access-control roles must be configured **on both server and client**. See `INTEGRATION.md` for details.
+
 ## Layer Architecture
 
 - **`nuxt.config.ts`**: Registers `@nuxt/ui` module, loads the auth CSS, and defines `runtimeConfig.public.x.auth` for base URL and auth path.

package/app/app.config.ts

@@ -21,6 +21,25 @@ export default defineAppConfig({
       otp: false,
       forgotPassword: true,
       signup: true,
+      organization: false,
+      teams: false,
+    },
+
+    organization: {
+      enabled: false,
+      teams: true,
+      allowUserToCreateOrganization: true,
+      requireMemberEmailVerification: true,
+      defaultRole: 'member',
+      protectedRoutes: ['/org'],
+      redirects: {
+        create: '/org/create',
+        list: '/org',
+        settings: '/org/:slug/settings',
+        invitations: '/org/:slug/invitations',
+        notMember: '/org',
+        noPermission: '/org',
+      },
     },
 
     oauthProviders: [] as Array<{

package/app/components/XAuth/OrganizationCreate.vue

@@ -0,0 +1,65 @@
+<template>
+  <div class="w-full space-y-6">
+    <div class="text-center">
+      <h1 class="text-2xl font-semibold text-highlighted">Create organization</h1>
+      <p class="text-sm text-muted mt-1">Set up a new organization for your team.</p>
+    </div>
+
+    <UForm :schema="schema" :state="state" class="space-y-4" @submit="handleCreate">
+      <UFormField label="Name" name="name">
+        <UInput v-model="state.name" placeholder="Acme Inc." class="w-full" />
+      </UFormField>
+
+      <UFormField label="Slug" name="slug">
+        <UInput v-model="state.slug" placeholder="acme" class="w-full" />
+      </UFormField>
+
+      <UFormField label="Logo URL" name="logo">
+        <UInput v-model="state.logo" placeholder="https://example.com/logo.png" class="w-full" />
+      </UFormField>
+
+      <UButton
+        type="submit"
+        block
+        size="lg"
+        label="Create organization"
+        :loading="creating"
+      />
+    </UForm>
+  </div>
+</template>
+
+<script setup>
+import { z } from "zod"
+
+const router = useRouter()
+const { createOrganization, setActiveOrganization } = useOrganization()
+
+const creating = ref(false)
+
+const state = reactive({
+  name: '',
+  slug: '',
+  logo: '',
+})
+
+const schema = z.object({
+  name: z.string().min(1, 'Organization name is required'),
+  slug: z.string().min(1, 'Slug is required').regex(/^[a-z0-9-]+$/, 'Slug must be lowercase letters, numbers, and hyphens'),
+  logo: z.string().url().optional().or(z.literal('')),
+})
+
+async function handleCreate() {
+  creating.value = true
+  try {
+    const result = await createOrganization(state.name, state.slug || state.name.toLowerCase().replace(/\s+/g, '-'), state.logo || undefined)
+    if (result && !result.error) {
+      const slug = result?.slug || state.slug
+      await setActiveOrganization(result?.id)
+      router.push(`/org/${slug}`)
+    }
+  } finally {
+    creating.value = false
+  }
+}
+</script>

package/app/components/XAuth/OrganizationInvitations.vue

@@ -0,0 +1,48 @@
+<template>
+  <div class="w-full space-y-6">
+    <div class="flex items-center justify-between">
+      <h2 class="text-lg font-semibold text-highlighted">Invitations</h2>
+      <UButton
+        v-if="isOrgAdmin"
+        size="sm"
+        to="invite"
+        label="Invite"
+        icon="i-lucide-plus"
+      />
+    </div>
+
+    <div v-if="invitations.length === 0" class="text-center py-8 text-muted">
+      No pending invitations.
+    </div>
+
+    <div v-else class="divide-y divide-neutral-200 dark:divide-neutral-800">
+      <div
+        v-for="invitation in invitations"
+        :key="invitation.id"
+        class="flex items-center justify-between py-3"
+      >
+        <div>
+          <p class="text-sm font-medium text-highlighted">{{ invitation.email }}</p>
+          <p class="text-xs text-muted">
+            Role: {{ invitation.role }}
+            <span v-if="invitation.status">· {{ invitation.status }}</span>
+          </p>
+        </div>
+
+        <UButton
+          v-if="isOrgAdmin"
+          color="error"
+          variant="soft"
+          size="xs"
+          label="Cancel"
+          icon="i-lucide-x"
+          @click="cancelInvitation(invitation.id)"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const { invitations, isOrgAdmin, cancelInvitation } = useOrganization()
+</script>

package/app/components/XAuth/OrganizationInvite.vue

@@ -0,0 +1,73 @@
+<template>
+  <div class="w-full space-y-6">
+    <div class="text-center">
+      <h2 class="text-lg font-semibold text-highlighted">Invite member</h2>
+      <p class="text-sm text-muted mt-1">Invite a new member to this organization.</p>
+    </div>
+
+    <UForm :schema="schema" :state="state" class="space-y-4" @submit="handleInvite">
+      <UFormField label="Email" name="email">
+        <UInput v-model="state.email" type="email" placeholder="colleague@example.com" class="w-full" />
+      </UFormField>
+
+      <UFormField label="Role" name="role">
+        <USelect
+          v-model="state.role"
+          :items="roleOptions"
+          class="w-full"
+        />
+      </UFormField>
+
+      <UButton
+        type="submit"
+        block
+        size="lg"
+        label="Send invitation"
+        :loading="inviting"
+      />
+    </UForm>
+  </div>
+</template>
+
+<script setup>
+import { z } from "zod"
+
+const props = defineProps({
+  organization: {
+    type: Object,
+    required: true,
+  },
+})
+
+const router = useRouter()
+const { inviteMember } = useOrganization()
+
+const inviting = ref(false)
+
+const state = reactive({
+  email: '',
+  role: 'member',
+})
+
+const roleOptions = [
+  { label: 'Member', value: 'member' },
+  { label: 'Admin', value: 'admin' },
+]
+
+const schema = z.object({
+  email: z.string().email('Please enter a valid email address'),
+  role: z.enum(['member', 'admin']),
+})
+
+async function handleInvite() {
+  inviting.value = true
+  try {
+    const result = await inviteMember(state.email, state.role, props.organization.id)
+    if (result && !result.error) {
+      router.push(`/org/${props.organization.slug}/invitations`)
+    }
+  } finally {
+    inviting.value = false
+  }
+}
+</script>

package/app/components/XAuth/OrganizationMembers.vue

@@ -0,0 +1,103 @@
+<template>
+  <div class="w-full space-y-6">
+    <div class="flex items-center justify-between">
+      <h2 class="text-lg font-semibold text-highlighted">Members</h2>
+      <UButton
+        v-if="isOrgAdmin"
+        size="sm"
+        to="invite"
+        label="Invite"
+        icon="i-lucide-user-plus"
+      />
+    </div>
+
+    <div v-if="members.length === 0" class="text-center py-8 text-muted">
+      No members yet.
+    </div>
+
+    <div v-else class="divide-y divide-neutral-200 dark:divide-neutral-800">
+      <div
+        v-for="member in members"
+        :key="member.id"
+        class="flex items-center justify-between py-3"
+      >
+        <div class="flex items-center gap-3">
+          <div class="flex size-9 items-center justify-center rounded-full bg-primary/10 text-primary">
+            <UIcon name="i-lucide-user" class="size-4" />
+          </div>
+          <div>
+            <p class="text-sm font-medium text-highlighted">{{ member.name || member.email }}</p>
+            <p class="text-xs text-muted">{{ member.email }}</p>
+          </div>
+        </div>
+
+        <div class="flex items-center gap-2">
+          <UBadge
+            :label="member.role"
+            :color="roleColor(member.role)"
+            size="sm"
+            variant="soft"
+          />
+          <UDropdownMenu
+            v-if="isOrgAdmin && !isCurrentUser(member)"
+            :items="memberActions(member)"
+          >
+            <UButton
+              color="neutral"
+              variant="ghost"
+              size="xs"
+              icon="i-lucide-ellipsis-vertical"
+            />
+          </UDropdownMenu>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const props = defineProps({
+  organization: {
+    type: Object,
+    required: true,
+  },
+})
+
+const { user } = useXAuth()
+const { members, isOrgAdmin, isOrgOwner, updateMemberRole, removeMember } = useOrganization()
+
+const roleColor = (role) => {
+  const roles = role.split(',')
+  if (roles.includes('owner')) return 'primary'
+  if (roles.includes('admin')) return 'warning'
+  return 'neutral'
+}
+
+const isCurrentUser = (member) => member.userId === user.value?.id
+
+const memberActions = (member) => [
+  ...(isOrgOwner.value
+    ? [{
+        label: 'Make owner',
+        icon: 'i-lucide-crown',
+        onSelect: () => updateMemberRole(member.id, 'owner'),
+      }]
+    : []),
+  {
+    label: 'Make admin',
+    icon: 'i-lucide-shield',
+    onSelect: () => updateMemberRole(member.id, 'admin'),
+  },
+  {
+    label: 'Make member',
+    icon: 'i-lucide-user',
+    onSelect: () => updateMemberRole(member.id, 'member'),
+  },
+  {
+    label: 'Remove',
+    icon: 'i-lucide-trash',
+    color: 'error',
+    onSelect: () => removeMember(member.id, props.organization.id),
+  },
+]
+</script>

package/app/components/XAuth/OrganizationSettings.vue

@@ -0,0 +1,85 @@
+<template>
+  <div class="w-full space-y-6">
+    <div class="flex items-center justify-between">
+      <h2 class="text-lg font-semibold text-highlighted">Settings</h2>
+      <UButton
+        v-if="isOrgOwner"
+        color="error"
+        variant="soft"
+        size="sm"
+        label="Delete"
+        icon="i-lucide-trash"
+        @click="handleDelete"
+      />
+    </div>
+
+    <UForm :schema="schema" :state="state" class="space-y-4" @submit="handleUpdate">
+      <UFormField label="Name" name="name">
+        <UInput v-model="state.name" class="w-full" />
+      </UFormField>
+
+      <UFormField label="Slug" name="slug">
+        <UInput v-model="state.slug" class="w-full" />
+      </UFormField>
+
+      <UFormField label="Logo URL" name="logo">
+        <UInput v-model="state.logo" class="w-full" />
+      </UFormField>
+
+      <UButton
+        type="submit"
+        size="sm"
+        label="Save changes"
+        :loading="updating"
+      />
+    </UForm>
+  </div>
+</template>
+
+<script setup>
+import { z } from "zod"
+
+const props = defineProps({
+  organization: {
+    type: Object,
+    required: true,
+  },
+})
+
+const { updateOrganization, deleteOrganization, isOrgOwner } = useOrganization()
+
+const updating = ref(false)
+
+const state = reactive({
+  name: props.organization.name || '',
+  slug: props.organization.slug || '',
+  logo: props.organization.logo || '',
+})
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  slug: z.string().min(1, 'Slug is required').regex(/^[a-z0-9-]+$/, 'Slug must be lowercase letters, numbers, and hyphens'),
+  logo: z.string().url().optional().or(z.literal('')),
+})
+
+async function handleUpdate() {
+  updating.value = true
+  try {
+    await updateOrganization({
+      organizationId: props.organization.id,
+      name: state.name,
+      slug: state.slug,
+      logo: state.logo || undefined,
+    })
+  } finally {
+    updating.value = false
+  }
+}
+
+async function handleDelete() {
+  if (!confirm('Are you sure you want to delete this organization? This action cannot be undone.')) {
+    return
+  }
+  await deleteOrganization(props.organization.id)
+}
+</script>

package/app/components/XAuth/OrganizationSwitcher.vue

@@ -0,0 +1,61 @@
+<template>
+  <div class="w-full space-y-4">
+    <div class="flex items-center justify-between">
+      <h2 class="text-lg font-semibold text-highlighted">Organizations</h2>
+      <UButton
+        v-if="canCreateOrganization"
+        size="sm"
+        to="/org/create"
+        label="New"
+        icon="i-lucide-plus"
+      />
+    </div>
+
+    <div v-if="organizationsLoading" class="flex items-center justify-center py-8">
+      <UIcon name="i-lucide-loader-2" class="size-6 animate-spin text-primary" />
+    </div>
+
+    <div v-else-if="organizations.length === 0" class="text-center py-8">
+      <div class="mx-auto mb-4 flex size-14 items-center justify-center rounded-full bg-primary/10 ring-1 ring-primary/20">
+        <UIcon name="i-lucide-building-2" class="size-7 text-primary" />
+      </div>
+      <h3 class="text-base font-semibold text-highlighted">No organizations yet</h3>
+      <p class="text-sm text-muted mt-1">Create an organization to get started.</p>
+      <UButton
+        v-if="canCreateOrganization"
+        class="mt-4"
+        size="sm"
+        to="/org/create"
+        label="Create organization"
+      />
+    </div>
+
+    <div v-else class="space-y-2">
+      <NuxtLink
+        v-for="org in organizations"
+        :key="org.id"
+        :to="`/org/${org.slug}`"
+        class="flex items-center gap-3 p-3 rounded-lg border border-neutral-200 dark:border-neutral-800 hover:bg-neutral-50 dark:hover:bg-neutral-900 transition-colors"
+        :class="{ 'bg-primary/5 border-primary/20 dark:border-primary/20': activeOrganization?.id === org.id }"
+      >
+        <div class="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary">
+          <img v-if="org.logo" :src="org.logo" alt="" class="size-10 rounded-lg object-cover" />
+          <UIcon v-else name="i-lucide-building-2" class="size-5" />
+        </div>
+        <div class="flex-1 min-w-0">
+          <p class="font-medium text-highlighted truncate">{{ org.name }}</p>
+          <p class="text-xs text-muted">@{{ org.slug }}</p>
+        </div>
+        <UIcon
+          v-if="activeOrganization?.id === org.id"
+          name="i-lucide-check"
+          class="size-5 text-primary"
+        />
+      </NuxtLink>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const { organizations, organizationsLoading, activeOrganization, canCreateOrganization } = useOrganization()
+</script>