@withmata/blueprints 0.2.0

package/blueprints/features/auth-better-auth/files/client/auth-client.ts

@@ -0,0 +1,31 @@
+// =============================================================================
+// Better Auth Client Setup
+// =============================================================================
+// Creates the auth client for React/Next.js applications. This is the single
+// entry point for all client-side auth operations (sign in, sign up, session
+// management, organization operations).
+//
+// The baseURL logic handles two deployment modes:
+//   - Standalone server (e.g. Hono): In local dev, point directly to the API
+//     server. In production, proxy through the frontend (e.g. Vercel rewrites)
+//     so cookies stay on the same domain.
+//   - Next.js API routes: Always use relative URL.
+// =============================================================================
+
+import { organizationClient } from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
+import { env } from "../env"; // CONFIGURE: adjust path to your env file
+
+// CONFIGURE: Adjust baseURL logic for your deployment
+const isLocalDev = env.NEXT_PUBLIC_API_URL.includes("localhost");
+const BASE_URL = isLocalDev
+  ? `${env.NEXT_PUBLIC_API_URL}/api/auth`
+  : `${env.NEXT_PUBLIC_FRONTEND_URL}/api/auth`;
+
+const authClient = createAuthClient({
+  baseURL: BASE_URL,
+  // CONFIGURE: Remove organizationClient() if not using the organization plugin
+  plugins: [organizationClient()],
+});
+
+export { authClient };

package/blueprints/features/auth-better-auth/files/client/context/organization.ts

@@ -0,0 +1,236 @@
+// =============================================================================
+// Organization Context
+// =============================================================================
+// Provides organization state and actions to the React component tree.
+// Split into TWO separate contexts for render performance:
+//   - OrganizationDataContext: reactive data (currentOrg, orgs list, role, etc.)
+//   - OrganizationActionsContext: stable action functions (switch, create, invite, etc.)
+//
+// Components that only call actions won't re-render when data changes.
+//
+// CONFIGURE: Remove this entire file if not using the organization plugin.
+// =============================================================================
+
+import { createContext, useCallback, useMemo, useRef, useState } from "react";
+import { authClient } from "../auth-client";
+import type {
+  Organization,
+  OrganizationWithRole,
+} from "../types/organization";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface OrganizationData {
+  currentOrganization: Organization | null;
+  organizations: OrganizationWithRole[];
+  currentRole: string | null;
+  isLoading: boolean;
+  needsOnboarding: boolean;
+}
+
+interface OrganizationActions {
+  switchOrganization: (organizationId: string) => Promise<void>;
+  createOrganization: (name: string, slug?: string) => Promise<Organization>;
+  inviteMember: (email: string, role: "admin" | "member") => Promise<void>;
+  removeMember: (memberId: string) => Promise<void>;
+  updateMemberRole: (
+    memberId: string,
+    role: "admin" | "member",
+  ) => Promise<void>;
+  leaveOrganization: () => Promise<void>;
+  refetch: () => void;
+}
+
+interface OrganizationContextValue
+  extends OrganizationData,
+    OrganizationActions {}
+
+// ============================================================================
+// Contexts
+// ============================================================================
+
+const OrganizationDataContext = createContext<OrganizationData | null>(null);
+const OrganizationActionsContext = createContext<OrganizationActions | null>(
+  null,
+);
+
+// ============================================================================
+// Hook — used by the Provider component
+// ============================================================================
+
+const useOrganizationContext = () => {
+  const { data: activeOrg, isPending: isActiveOrgLoading } =
+    authClient.useActiveOrganization();
+  const {
+    data: orgsData,
+    isPending: isOrgsLoading,
+    refetch,
+  } = authClient.useListOrganizations();
+  const { data: activeMember } = authClient.useActiveMember();
+
+  const [isSwitching, setIsSwitching] = useState(false);
+  const isLoading = isActiveOrgLoading || isOrgsLoading || isSwitching;
+
+  const currentOrgIdRef = useRef<string | null>(null);
+
+  const currentOrganization = useMemo(() => {
+    if (!activeOrg) {
+      currentOrgIdRef.current = null;
+      return null;
+    }
+    currentOrgIdRef.current = activeOrg.id;
+    return {
+      id: activeOrg.id,
+      name: activeOrg.name,
+      slug: activeOrg.slug,
+      logo: activeOrg.logo,
+      createdAt: activeOrg.createdAt,
+      metadata: activeOrg.metadata,
+    } as Organization;
+  }, [activeOrg]);
+
+  const organizations = useMemo(() => {
+    if (!orgsData) return [];
+    return orgsData.map((org) => ({
+      id: org.id,
+      name: org.name,
+      slug: org.slug,
+      logo: org.logo ?? null,
+      createdAt: org.createdAt,
+      metadata: org.metadata ?? null,
+      role: "member",
+    })) as OrganizationWithRole[];
+  }, [orgsData]);
+
+  const needsOnboarding = !isLoading && organizations.length === 0;
+
+  const currentRole = useMemo(() => {
+    return activeMember?.role ?? null;
+  }, [activeMember]);
+
+  const switchOrganization = useCallback(async (organizationId: string) => {
+    setIsSwitching(true);
+    try {
+      await authClient.organization.setActive({ organizationId });
+    } finally {
+      setIsSwitching(false);
+    }
+  }, []);
+
+  const createOrganization = useCallback(
+    async (name: string, slug?: string) => {
+      const result = await authClient.organization.create({
+        name,
+        slug: slug || name.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
+      });
+
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+
+      refetch();
+      return result.data as Organization;
+    },
+    [refetch],
+  );
+
+  const inviteMember = useCallback(
+    async (email: string, role: "admin" | "member") => {
+      const currentOrgId = currentOrgIdRef.current;
+      if (!currentOrgId) throw new Error("No active organization");
+
+      const result = await authClient.organization.inviteMember({
+        email,
+        role,
+        organizationId: currentOrgId,
+      });
+
+      if (result.error) throw new Error(result.error.message);
+    },
+    [],
+  );
+
+  const removeMember = useCallback(async (memberId: string) => {
+    const currentOrgId = currentOrgIdRef.current;
+    if (!currentOrgId) throw new Error("No active organization");
+
+    const result = await authClient.organization.removeMember({
+      memberIdOrEmail: memberId,
+      organizationId: currentOrgId,
+    });
+
+    if (result.error) throw new Error(result.error.message);
+  }, []);
+
+  const updateMemberRole = useCallback(
+    async (memberId: string, role: "admin" | "member") => {
+      const currentOrgId = currentOrgIdRef.current;
+      if (!currentOrgId) throw new Error("No active organization");
+
+      const result = await authClient.organization.updateMemberRole({
+        memberId,
+        role,
+        organizationId: currentOrgId,
+      });
+
+      if (result.error) throw new Error(result.error.message);
+    },
+    [],
+  );
+
+  const leaveOrganization = useCallback(async () => {
+    const currentOrgId = currentOrgIdRef.current;
+    if (!currentOrgId) throw new Error("No active organization");
+
+    const result = await authClient.organization.leave({
+      organizationId: currentOrgId,
+    });
+
+    if (result.error) throw new Error(result.error.message);
+    refetch();
+  }, [refetch]);
+
+  const dataValue = useMemo<OrganizationData>(
+    () => ({
+      currentOrganization,
+      organizations,
+      currentRole,
+      isLoading,
+      needsOnboarding,
+    }),
+    [currentOrganization, organizations, currentRole, isLoading, needsOnboarding],
+  );
+
+  const actionsValue = useMemo<OrganizationActions>(
+    () => ({
+      switchOrganization,
+      createOrganization,
+      inviteMember,
+      removeMember,
+      updateMemberRole,
+      leaveOrganization,
+      refetch,
+    }),
+    [
+      switchOrganization,
+      createOrganization,
+      inviteMember,
+      removeMember,
+      updateMemberRole,
+      leaveOrganization,
+      refetch,
+    ],
+  );
+
+  return { dataValue, actionsValue };
+};
+
+export {
+  OrganizationDataContext,
+  OrganizationActionsContext,
+  useOrganizationContext,
+};
+
+export type { OrganizationContextValue, OrganizationData, OrganizationActions };

package/blueprints/features/auth-better-auth/files/client/hooks/use-create-organization.ts

@@ -0,0 +1,45 @@
+// =============================================================================
+// Create Organization Hook
+// =============================================================================
+// SWR mutation hook for creating a new organization and setting it as active.
+//
+// CONFIGURE: Remove if not using the organization plugin.
+// If using TanStack Query instead of SWR, adapt the mutation pattern.
+// =============================================================================
+
+import useSWRMutation from "swr/mutation";
+import { authClient } from "../auth-client";
+
+export function useCreateOrganization() {
+  const { trigger, isMutating, error, reset } = useSWRMutation(
+    "create-organization",
+    async (_, { arg }: { arg: { name: string } }) => {
+      const slug = arg.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+
+      const result = await authClient.organization.create({
+        name: arg.name,
+        slug,
+      });
+
+      if (result.error) {
+        throw new Error(result.error.message || "Failed to create organization");
+      }
+
+      // Set the new org as active
+      if (result.data?.id) {
+        await authClient.organization.setActive({
+          organizationId: result.data.id,
+        });
+      }
+
+      return result.data;
+    },
+  );
+
+  return {
+    createOrganization: trigger,
+    isCreating: isMutating,
+    error: error ? (error as Error).message : null,
+    reset,
+  };
+}

package/blueprints/features/auth-better-auth/files/client/hooks/use-has-permission.ts

@@ -0,0 +1,26 @@
+// =============================================================================
+// Role-Based Permission Hook
+// =============================================================================
+// Checks if the current user has the required role level.
+// Uses hierarchy: owner (3) > admin (2) > member (1)
+//
+// CONFIGURE: Adjust role hierarchy if your app uses different roles.
+// Remove if not using the organization plugin.
+// =============================================================================
+
+import { useOrganizationData } from "./use-organization";
+
+export function useHasPermission(
+  requiredRole: "owner" | "admin" | "member",
+): boolean {
+  const { currentRole } = useOrganizationData();
+
+  if (!currentRole) return false;
+
+  const roleHierarchy = { owner: 3, admin: 2, member: 1 };
+  const userLevel =
+    roleHierarchy[currentRole as keyof typeof roleHierarchy] ?? 0;
+  const requiredLevel = roleHierarchy[requiredRole];
+
+  return userLevel >= requiredLevel;
+}

package/blueprints/features/auth-better-auth/files/client/hooks/use-organization.ts

@@ -0,0 +1,64 @@
+// =============================================================================
+// Organization Hooks
+// =============================================================================
+// Three hooks for consuming organization context:
+//   - useOrganization()        — combined data + actions (backward compat)
+//   - useOrganizationData()    — data only (prevents re-renders from action changes)
+//   - useOrganizationActions() — actions only (prevents re-renders from data changes)
+//
+// CONFIGURE: Remove if not using the organization plugin.
+// =============================================================================
+
+import { useContext } from "react";
+import {
+  OrganizationDataContext,
+  OrganizationActionsContext,
+  type OrganizationContextValue,
+  type OrganizationData,
+  type OrganizationActions,
+} from "../context/organization";
+
+/**
+ * Combined hook — use when you need both data and actions.
+ * For better performance, prefer useOrganizationData() or useOrganizationActions().
+ */
+const useOrganization = (): OrganizationContextValue => {
+  const data = useContext(OrganizationDataContext);
+  const actions = useContext(OrganizationActionsContext);
+
+  if (!data || !actions) {
+    throw new Error(
+      "useOrganization must be used within an OrganizationProvider",
+    );
+  }
+
+  return { ...data, ...actions };
+};
+
+/**
+ * Data-only hook — prevents re-renders when action functions change.
+ */
+export const useOrganizationData = (): OrganizationData => {
+  const data = useContext(OrganizationDataContext);
+  if (!data) {
+    throw new Error(
+      "useOrganizationData must be used within an OrganizationProvider",
+    );
+  }
+  return data;
+};
+
+/**
+ * Actions-only hook — prevents re-renders when data changes.
+ */
+export const useOrganizationActions = (): OrganizationActions => {
+  const actions = useContext(OrganizationActionsContext);
+  if (!actions) {
+    throw new Error(
+      "useOrganizationActions must be used within an OrganizationProvider",
+    );
+  }
+  return actions;
+};
+
+export default useOrganization;

package/blueprints/features/auth-better-auth/files/client/schema/auth.ts

@@ -0,0 +1,21 @@
+// =============================================================================
+// Shared Auth Validation Schemas
+// =============================================================================
+// Base Zod validators used across multiple auth forms (sign-in, sign-up, etc.)
+//
+// CONFIGURE: If using a different validation library, adapt these schemas.
+// =============================================================================
+
+import { z } from "zod";
+
+export const emailSchema = z
+  .string()
+  .min(1, "Please enter your email")
+  .email("Please enter a valid email address");
+
+export const passwordSchema = z
+  .string()
+  .min(1, "Please enter your password")
+  .min(8, "Password must be at least 8 characters");
+
+export const nameSchema = z.string().min(1, "Please enter your name").trim();

package/blueprints/features/auth-better-auth/files/client/schema/organization.ts

@@ -0,0 +1,51 @@
+// =============================================================================
+// Organization Form Schemas
+// =============================================================================
+// Zod schemas for organization-related forms: create, update, invite member.
+//
+// CONFIGURE: Remove if not using the organization plugin.
+// =============================================================================
+
+import { z } from "zod";
+
+export const createOrganizationSchema = z.object({
+  name: z
+    .string()
+    .min(1, "Please enter a workspace name")
+    .max(50, "Name must be 50 characters or less")
+    .trim(),
+});
+
+export type CreateOrganizationFormData = z.infer<
+  typeof createOrganizationSchema
+>;
+
+export const updateOrganizationSchema = z.object({
+  name: z
+    .string()
+    .min(1, "Please enter an organization name")
+    .max(50, "Name must be 50 characters or less")
+    .trim(),
+  slug: z
+    .string()
+    .min(1, "Please enter a slug")
+    .max(50, "Slug must be 50 characters or less")
+    .regex(
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+      "Slug must be lowercase letters, numbers, and hyphens",
+    )
+    .trim(),
+});
+
+export type UpdateOrganizationFormData = z.infer<
+  typeof updateOrganizationSchema
+>;
+
+export const inviteMemberSchema = z.object({
+  email: z.string().email("Please enter a valid email address"),
+  role: z.enum(["admin", "member"], {
+    message: "Please select a role",
+  }),
+});
+
+export type InviteMemberFormData = z.infer<typeof inviteMemberSchema>;

package/blueprints/features/auth-better-auth/files/client/types/organization.ts

@@ -0,0 +1,20 @@
+// =============================================================================
+// Organization Types
+// =============================================================================
+// CONFIGURE: Remove if not using the organization plugin.
+// =============================================================================
+
+type Organization = {
+  id: string;
+  name: string;
+  slug: string | null;
+  logo: string | null;
+  createdAt: Date;
+  metadata: string | null;
+};
+
+type OrganizationWithRole = Organization & {
+  role: string;
+};
+
+export type { Organization, OrganizationWithRole };

package/blueprints/features/auth-better-auth/files/db/auth-schema.ts

@@ -0,0 +1,184 @@
+// =============================================================================
+// Auth Database Schema — REFERENCE FILE
+// =============================================================================
+// This schema is AUTO-GENERATED by the Better Auth CLI. Do NOT edit manually.
+// To regenerate after changing auth config:
+//   npx @better-auth/cli@latest generate --config ./src/auth/index.ts --output ./path/to/schema.ts --yes
+//
+// This file is included as a REFERENCE so you can see the table structure.
+// When scaffolding, generate your own schema from your auth config.
+//
+// Tables:
+//   Core:         user, session, account, verification
+//   Organization: organization, member, invitation (from organization plugin)
+// =============================================================================
+
+import { relations } from "drizzle-orm";
+import { boolean, index, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: boolean("email_verified").default(false).notNull(),
+  image: text("image"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => new Date())
+    .notNull(),
+  currentOrganizationId: text("current_organization_id"),
+});
+
+export const session = pgTable(
+  "session",
+  {
+    id: text("id").primaryKey(),
+    expiresAt: timestamp("expires_at").notNull(),
+    token: text("token").notNull().unique(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .$onUpdate(() => new Date())
+      .notNull(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    activeOrganizationId: text("active_organization_id"),
+  },
+  (table) => [index("session_userId_idx").on(table.userId)],
+);
+
+export const account = pgTable(
+  "account",
+  {
+    id: text("id").primaryKey(),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at"),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .$onUpdate(() => new Date())
+      .notNull(),
+  },
+  (table) => [index("account_userId_idx").on(table.userId)],
+);
+
+export const verification = pgTable(
+  "verification",
+  {
+    id: text("id").primaryKey(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .defaultNow()
+      .$onUpdate(() => new Date())
+      .notNull(),
+  },
+  (table) => [index("verification_identifier_idx").on(table.identifier)],
+);
+
+// Organization plugin tables (remove if not using organization plugin)
+
+export const organization = pgTable("organization", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull().unique(),
+  logo: text("logo"),
+  createdAt: timestamp("created_at").notNull(),
+  metadata: text("metadata"),
+});
+
+export const member = pgTable(
+  "member",
+  {
+    id: text("id").primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    role: text("role").default("member").notNull(),
+    createdAt: timestamp("created_at").notNull(),
+  },
+  (table) => [
+    index("member_organizationId_idx").on(table.organizationId),
+    index("member_userId_idx").on(table.userId),
+  ],
+);
+
+export const invitation = pgTable(
+  "invitation",
+  {
+    id: text("id").primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    email: text("email").notNull(),
+    role: text("role"),
+    status: text("status").default("pending").notNull(),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    inviterId: text("inviter_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+  },
+  (table) => [
+    index("invitation_organizationId_idx").on(table.organizationId),
+    index("invitation_email_idx").on(table.email),
+  ],
+);
+
+// Relations
+
+export const userRelations = relations(user, ({ many }) => ({
+  sessions: many(session),
+  accounts: many(account),
+  members: many(member),
+  invitations: many(invitation),
+}));
+
+export const sessionRelations = relations(session, ({ one }) => ({
+  user: one(user, { fields: [session.userId], references: [user.id] }),
+}));
+
+export const accountRelations = relations(account, ({ one }) => ({
+  user: one(user, { fields: [account.userId], references: [user.id] }),
+}));
+
+export const organizationRelations = relations(organization, ({ many }) => ({
+  members: many(member),
+  invitations: many(invitation),
+}));
+
+export const memberRelations = relations(member, ({ one }) => ({
+  organization: one(organization, {
+    fields: [member.organizationId],
+    references: [organization.id],
+  }),
+  user: one(user, { fields: [member.userId], references: [user.id] }),
+}));
+
+export const invitationRelations = relations(invitation, ({ one }) => ({
+  organization: one(organization, {
+    fields: [invitation.organizationId],
+    references: [organization.id],
+  }),
+  user: one(user, {
+    fields: [invitation.inviterId],
+    references: [user.id],
+  }),
+}));