@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/admin/config.js

@@ -0,0 +1,224 @@
+/**
+ * @rovela-ai/sdk/admin/config
+ *
+ * NextAuth configuration for STORE ADMIN authentication.
+ *
+ * Completely separate from customer auth:
+ *   - Mounts at its OWN NextAuth endpoint: `/api/admin-auth/[...nextauth]`
+ *   - Writes its OWN session cookie: `__Secure-rovela.admin.session-token`
+ *   - Uses only the `admin-credentials` provider
+ *
+ * Because the cookie name differs from customer auth, both sessions can
+ * coexist in the same browser — a merchant can be signed into `/admin` as
+ * an admin AND signed into `/account` as a customer simultaneously. This
+ * is the foundation of the "linked customer" feature.
+ *
+ * `sameSite: 'none'` + `secure: true` is required for the Rovela preview
+ * iframe (rovela.ai embeds the sandbox storefront cross-origin).
+ */
+import CredentialsProvider from 'next-auth/providers/credentials';
+import { authenticateAdmin, findAdminForSession } from './server/admin-service';
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default admin session duration: 24 hours.
+ *
+ * Matches the customer default because merchants expect parity between
+ * the two sessions. With `rememberMe=true` this extends to 30 days.
+ */
+const DEFAULT_SESSION_MAX_AGE = 24 * 60 * 60;
+/**
+ * Remember-me session duration: 30 days.
+ */
+const REMEMBER_ME_MAX_AGE = 30 * 24 * 60 * 60;
+// =============================================================================
+// Auth Configuration
+// =============================================================================
+/**
+ * Create NextAuth options for STORE ADMIN authentication.
+ *
+ * @example
+ * ```typescript
+ * // app/api/admin-auth/[...nextauth]/route.ts
+ * import NextAuth from 'next-auth'
+ * import { createAdminAuthOptions } from '@rovela-ai/sdk/admin'
+ *
+ * const handler = NextAuth(createAdminAuthOptions())
+ * export { handler as GET, handler as POST }
+ * ```
+ */
+export function createAdminAuthOptions(options = {}) {
+    const { sessionMaxAge = DEFAULT_SESSION_MAX_AGE, rememberMeMaxAge = REMEMBER_ME_MAX_AGE, signInPage = '/admin/login', errorPage = '/admin/login', dashboardPage = '/admin', } = options;
+    return {
+        providers: [
+            CredentialsProvider({
+                // CRITICAL: Different ID from customer auth ('credentials')
+                id: 'admin-credentials',
+                name: 'Admin Credentials',
+                credentials: {
+                    email: { label: 'Email', type: 'email' },
+                    password: { label: 'Password', type: 'password' },
+                    rememberMe: { label: 'Remember Me', type: 'checkbox' },
+                },
+                async authorize(credentials) {
+                    if (!credentials?.email || !credentials?.password) {
+                        return null;
+                    }
+                    const result = await authenticateAdmin(credentials.email, credentials.password);
+                    if (!result.success) {
+                        throw new Error(result.error, { cause: result.code });
+                    }
+                    // `sessionVersion` is embedded in the JWT so `requireAdmin` can
+                    // detect forced logouts after password changes (Phase 4 session
+                    // versioning). See admin-session.ts.
+                    const sessionVersion = result.admin.sessionVersion ?? 0;
+                    return {
+                        id: result.admin.id,
+                        email: result.admin.email,
+                        name: result.admin.name,
+                        role: result.admin.role,
+                        sessionVersion,
+                        rememberMe: credentials.rememberMe === 'true',
+                    };
+                },
+            }),
+        ],
+        // Cookie + JWT lifetime ceiling is the longest possible session (30 days)
+        // so "keep me signed in" cookies outlast shorter per-session expiries.
+        // Per-session expiration is enforced by `token.exp` in the JWT callback.
+        session: {
+            strategy: 'jwt',
+            maxAge: rememberMeMaxAge,
+        },
+        jwt: {
+            maxAge: rememberMeMaxAge,
+        },
+        pages: {
+            signIn: signInPage,
+            error: errorPage,
+        },
+        // =========================================================================
+        // Cookie Configuration
+        // =========================================================================
+        // Admin-specific cookie names so the admin session lives in a completely
+        // separate cookie jar from the customer session. Both can coexist in the
+        // same browser; neither can be mistaken for the other.
+        //
+        // `sameSite: 'none'` + `secure: true` is required for cross-origin iframe
+        // contexts (the rovela.ai preview embeds the sandbox storefront, and the
+        // admin login page posts credentials via postMessage through that frame).
+        cookies: {
+            sessionToken: {
+                name: `__Secure-rovela.admin.session-token`,
+                options: {
+                    httpOnly: true,
+                    sameSite: 'none',
+                    path: '/',
+                    secure: true,
+                },
+            },
+            callbackUrl: {
+                name: `__Secure-rovela.admin.callback-url`,
+                options: {
+                    sameSite: 'none',
+                    path: '/',
+                    secure: true,
+                },
+            },
+            csrfToken: {
+                name: `__Host-rovela.admin.csrf-token`,
+                options: {
+                    httpOnly: true,
+                    sameSite: 'none',
+                    path: '/',
+                    secure: true,
+                },
+            },
+        },
+        callbacks: {
+            async jwt({ token, user, trigger, session }) {
+                const adminToken = token;
+                const now = Math.floor(Date.now() / 1000);
+                // Initial sign in
+                if (user) {
+                    const adminUser = user;
+                    adminToken.id = user.id;
+                    adminToken.email = user.email ?? undefined;
+                    adminToken.name = user.name ?? undefined;
+                    adminToken.role = adminUser.role;
+                    adminToken.sessionVersion = adminUser.sessionVersion ?? 0;
+                    // Persist rememberMe + originalIat so silent refreshes can
+                    // recompute the same absolute exp without sliding the session.
+                    const rememberMe = Boolean(adminUser.rememberMe);
+                    adminToken.rememberMe = rememberMe;
+                    adminToken.originalIat = now;
+                    const effectiveMaxAge = rememberMe ? rememberMeMaxAge : sessionMaxAge;
+                    adminToken.exp = now + effectiveMaxAge;
+                }
+                else if (adminToken.originalIat) {
+                    // Silent refresh — re-apply absolute exp from originalIat.
+                    const rememberMe = Boolean(adminToken.rememberMe);
+                    const effectiveMaxAge = rememberMe ? rememberMeMaxAge : sessionMaxAge;
+                    adminToken.exp = adminToken.originalIat + effectiveMaxAge;
+                }
+                // Update trigger (client calling useSession().update())
+                if (trigger === 'update' && session) {
+                    if (session.name !== undefined) {
+                        adminToken.name = session.name;
+                    }
+                }
+                return token;
+            },
+            async session({ session, token }) {
+                if (token) {
+                    const adminToken = token;
+                    const user = session.user;
+                    user.id = adminToken.id;
+                    user.email = adminToken.email;
+                    user.name = adminToken.name;
+                    user.role = adminToken.role;
+                    user.sessionVersion = adminToken.sessionVersion ?? 0;
+                }
+                return session;
+            },
+            async redirect({ url, baseUrl }) {
+                if (url.startsWith('/')) {
+                    return `${baseUrl}${url}`;
+                }
+                if (url.startsWith(baseUrl)) {
+                    return url;
+                }
+                return `${baseUrl}${dashboardPage}`;
+            },
+        },
+        events: {
+            async signIn({ user }) {
+                console.log(`[Admin Auth] Admin signed in: ${user.email}`);
+            },
+            async signOut({ token }) {
+                console.log(`[Admin Auth] Admin signed out: ${token?.email}`);
+            },
+        },
+        debug: process.env.NODE_ENV === 'development',
+    };
+}
+/**
+ * Get admin session data from the current session.
+ * Refreshes data from database for accuracy.
+ *
+ * @param adminId - Admin UUID from session
+ * @returns Admin session data or null
+ *
+ * @example
+ * ```typescript
+ * const session = await getServerSession(createAdminAuthOptions())
+ * if (session?.user?.id) {
+ *   const admin = await getAdminSession(session.user.id)
+ * }
+ * ```
+ */
+export async function getAdminSession(adminId) {
+    return findAdminForSession(adminId);
+}
+//# sourceMappingURL=config.js.map

package/dist/admin/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/admin/config.ts"],"names":[],"mappings":"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"}

package/dist/admin/hooks/fetchAdminApi.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @rovela/sdk/admin/hooks/fetchAdminApi
+ *
+ * The one-and-only way client code should hit `/api/admin/*` from inside
+ * the admin SDK. Returns a discriminated union so callers never have to
+ * juggle try/catch for expected 4xx responses.
+ *
+ * # Why this exists
+ *
+ * Before this helper, every admin hook and every inline-fetch component
+ * had its own copy of `try { fetch; if (!ok) throw } catch { console.error
+ * + setError }`. That pattern has two problems on Next.js 16 Turbopack:
+ *
+ *   1. `console.error` surfaces as the red "Console Error" dev overlay —
+ *      an expected 403 looks like a runtime crash.
+ *   2. The `throw new Error(data.error)` inside a try/catch re-catches
+ *      immediately and the useful server message ends up silently discarded
+ *      or replaced with a generic "Please try again." at the call site.
+ *
+ * This helper:
+ *
+ *   - Never throws for non-ok HTTP responses. Returns `{ok: false, error}`.
+ *   - Only `console.error`s in the outer network-exception branch, which is
+ *     where real crashes manifest. Expected 401/403/404/409 are silent.
+ *   - Translates curt server strings ('Forbidden', 'Unauthorized', empty) to
+ *     friendlier UI copy. Preserves specific server messages verbatim.
+ *
+ * # Usage
+ *
+ * ```ts
+ * const res = await fetchAdminApi<{ products: Product[] }>(
+ *   '/api/admin/products'
+ * )
+ * if (!res.ok) {
+ *   setError(res.error)
+ *   return
+ * }
+ * setProducts(res.data.products)
+ * ```
+ *
+ * For write operations the hook wraps this and returns `CrudResult<T>`:
+ *
+ * ```ts
+ * const deleteX = async (id: string): Promise<CrudResult<void>> => {
+ *   const res = await fetchAdminApi(`/api/admin/x/${id}`, { method: 'DELETE' })
+ *   if (!res.ok) {
+ *     setError(res.error)
+ *     return { success: false, error: res.error }
+ *   }
+ *   setError(null)
+ *   return { success: true }
+ * }
+ * ```
+ */
+export type AdminFetchResult<T> = {
+    ok: true;
+    data: T;
+    status: number;
+} | {
+    ok: false;
+    error: string;
+    status: number;
+};
+export declare function fetchAdminApi<T = unknown>(url: string, init?: RequestInit): Promise<AdminFetchResult<T>>;
+//# sourceMappingURL=fetchAdminApi.d.ts.map

package/dist/admin/hooks/fetchAdminApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchAdminApi.d.ts","sourceRoot":"","sources":["../../../src/admin/hooks/fetchAdminApi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAMH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAMhD,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7C,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAwC9B"}

package/dist/admin/hooks/fetchAdminApi.js

@@ -0,0 +1,96 @@
+/**
+ * @rovela/sdk/admin/hooks/fetchAdminApi
+ *
+ * The one-and-only way client code should hit `/api/admin/*` from inside
+ * the admin SDK. Returns a discriminated union so callers never have to
+ * juggle try/catch for expected 4xx responses.
+ *
+ * # Why this exists
+ *
+ * Before this helper, every admin hook and every inline-fetch component
+ * had its own copy of `try { fetch; if (!ok) throw } catch { console.error
+ * + setError }`. That pattern has two problems on Next.js 16 Turbopack:
+ *
+ *   1. `console.error` surfaces as the red "Console Error" dev overlay —
+ *      an expected 403 looks like a runtime crash.
+ *   2. The `throw new Error(data.error)` inside a try/catch re-catches
+ *      immediately and the useful server message ends up silently discarded
+ *      or replaced with a generic "Please try again." at the call site.
+ *
+ * This helper:
+ *
+ *   - Never throws for non-ok HTTP responses. Returns `{ok: false, error}`.
+ *   - Only `console.error`s in the outer network-exception branch, which is
+ *     where real crashes manifest. Expected 401/403/404/409 are silent.
+ *   - Translates curt server strings ('Forbidden', 'Unauthorized', empty) to
+ *     friendlier UI copy. Preserves specific server messages verbatim.
+ *
+ * # Usage
+ *
+ * ```ts
+ * const res = await fetchAdminApi<{ products: Product[] }>(
+ *   '/api/admin/products'
+ * )
+ * if (!res.ok) {
+ *   setError(res.error)
+ *   return
+ * }
+ * setProducts(res.data.products)
+ * ```
+ *
+ * For write operations the hook wraps this and returns `CrudResult<T>`:
+ *
+ * ```ts
+ * const deleteX = async (id: string): Promise<CrudResult<void>> => {
+ *   const res = await fetchAdminApi(`/api/admin/x/${id}`, { method: 'DELETE' })
+ *   if (!res.ok) {
+ *     setError(res.error)
+ *     return { success: false, error: res.error }
+ *   }
+ *   setError(null)
+ *   return { success: true }
+ * }
+ * ```
+ */
+// =============================================================================
+// Helper
+// =============================================================================
+export async function fetchAdminApi(url, init) {
+    let res;
+    try {
+        res = await fetch(url, init);
+    }
+    catch (err) {
+        // Genuine network / unexpected exception — log once here so the error
+        // still surfaces in dev tools, but return it as a normal result so the
+        // caller can render it in its own UI instead of crashing.
+        console.error(`[fetchAdminApi] ${init?.method ?? 'GET'} ${url}`, err);
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : 'Network error',
+            status: 0,
+        };
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        const raw = typeof body.error === 'string' ? body.error.trim() : '';
+        // Map curt server codes to friendlier UI copy. Specific server messages
+        // ('Cannot delete the last owner', 'Email already in use', etc.) pass
+        // through verbatim.
+        const isGenericAuth = raw === 'Forbidden' || raw === 'Unauthorized' || raw === '';
+        const error = isGenericAuth
+            ? res.status === 403
+                ? "You don't have permission to do this."
+                : res.status === 401
+                    ? 'Your session has expired. Please sign in again.'
+                    : res.status === 404
+                        ? 'Not found.'
+                        : `Request failed (${res.status}).`
+            : raw;
+        return { ok: false, error, status: res.status };
+    }
+    // Body might be empty (204 No Content) or malformed — fall back to undefined.
+    const data = (await res.json().catch(() => undefined));
+    return { ok: true, data, status: res.status };
+}
+//# sourceMappingURL=fetchAdminApi.js.map

package/dist/admin/hooks/fetchAdminApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchAdminApi.js","sourceRoot":"","sources":["../../../src/admin/hooks/fetchAdminApi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAUH,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAW,EACX,IAAkB;IAElB,IAAI,GAAa,CAAA;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,uEAAuE;QACvE,0DAA0D;QAC1D,OAAO,CAAC,KAAK,CAAC,mBAAmB,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;QACrE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;YAC3D,MAAM,EAAE,CAAC;SACV,CAAA;IACH,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAuB,CAAA;QACvE,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAEnE,wEAAwE;QACxE,sEAAsE;QACtE,oBAAoB;QACpB,MAAM,aAAa,GAAG,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,cAAc,IAAI,GAAG,KAAK,EAAE,CAAA;QACjF,MAAM,KAAK,GAAG,aAAa;YACzB,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG;gBAClB,CAAC,CAAC,uCAAuC;gBACzC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG;oBAClB,CAAC,CAAC,iDAAiD;oBACnD,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG;wBAClB,CAAC,CAAC,YAAY;wBACd,CAAC,CAAC,mBAAmB,GAAG,CAAC,MAAM,IAAI;YACzC,CAAC,CAAC,GAAG,CAAA;QAEP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAA;IACjD,CAAC;IAED,8EAA8E;IAC9E,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAM,CAAA;IAC3D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAA;AAC/C,CAAC"}

package/dist/admin/hooks/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @rovela/sdk/admin/hooks
+ *
+ * Admin panel React hooks.
+ */
+export { useAdminAuth } from './useAdminAuth';
+export { useAdminSession } from './useAdminSession';
+export type { AdminSessionPayload, AdminSessionStatus, UseAdminSessionReturn, } from './useAdminSession';
+export { useAdminStats } from './useAdminStats';
+export { useAdminOrders } from './useAdminOrders';
+export { useAdminProducts } from './useAdminProducts';
+export { useAdminProductMetrics } from './useAdminProductMetrics';
+export { useSetupGuide } from './useSetupGuide';
+export type { SetupTaskId, SetupTier, SetupTask, SetupGuideData, ManualMarkKey, UseSetupGuideReturn, } from './useSetupGuide';
+export { useAdminCategories } from './useAdminCategories';
+export { useAdminCustomers } from './useAdminCustomers';
+export { useAdminUsers } from './useAdminUsers';
+export { useAdminPermissions } from './useAdminPermissions';
+export { useAdminMe } from './useAdminMe';
+export type { AdminMe, UseAdminMeReturn } from './useAdminMe';
+export { useLinkedCustomerStatus } from './useLinkedCustomerStatus';
+export type { LinkedCustomerStatus } from './useLinkedCustomerStatus';
+export type { CategoryTreeItem } from './useAdminCategories';
+//# sourceMappingURL=index.d.ts.map

package/dist/admin/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/admin/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,cAAc,EACd,aAAa,EACb,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AACnE,YAAY,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/admin/hooks/index.js

@@ -0,0 +1,19 @@
+/**
+ * @rovela/sdk/admin/hooks
+ *
+ * Admin panel React hooks.
+ */
+export { useAdminAuth } from './useAdminAuth';
+export { useAdminSession } from './useAdminSession';
+export { useAdminStats } from './useAdminStats';
+export { useAdminOrders } from './useAdminOrders';
+export { useAdminProducts } from './useAdminProducts';
+export { useAdminProductMetrics } from './useAdminProductMetrics';
+export { useSetupGuide } from './useSetupGuide';
+export { useAdminCategories } from './useAdminCategories';
+export { useAdminCustomers } from './useAdminCustomers';
+export { useAdminUsers } from './useAdminUsers';
+export { useAdminPermissions } from './useAdminPermissions';
+export { useAdminMe } from './useAdminMe';
+export { useLinkedCustomerStatus } from './useLinkedCustomerStatus';
+//# sourceMappingURL=index.js.map

package/dist/admin/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/admin/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAMnD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAS/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/admin/hooks/useAdminAuth.d.ts

@@ -0,0 +1,25 @@
+import type { UseAdminAuthReturn } from '../types';
+/**
+ * Admin authentication hook for auth state and actions.
+ *
+ * @example
+ * ```typescript
+ * function AdminDashboard() {
+ *   const { admin, isAuthenticated, isLoading, isOwner, signIn, signOut } =
+ *     useAdminAuth()
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (!isAuthenticated) return <AdminLoginForm />
+ *
+ *   return (
+ *     <div>
+ *       Welcome, {admin?.name}
+ *       {isOwner && <span>(Owner)</span>}
+ *       <button onClick={signOut}>Sign Out</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useAdminAuth(): UseAdminAuthReturn;
+//# sourceMappingURL=useAdminAuth.d.ts.map

package/dist/admin/hooks/useAdminAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAdminAuth.d.ts","sourceRoot":"","sources":["../../../src/admin/hooks/useAdminAuth.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAYjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAoJjD"}