@mohasinac/appkit 2.1.3 → 2.2.0

package/dist/constants/api-endpoints.js

@@ -0,0 +1,342 @@
+/**
+ * API Endpoints — @mohasinac/appkit
+ *
+ * Canonical endpoint constants used throughout appkit hooks and client utilities.
+ * Hooks consume these defaults; consumers override via endpoint options on each hook.
+ *
+ * Never hard-code `/api/...` strings in hook files — import from here.
+ */
+// ---------------------------------------------------------------------------
+// Logs
+// ---------------------------------------------------------------------------
+export const LOGS_ENDPOINTS = {
+    WRITE: "/api/logs/write",
+};
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+export const AUTH_ENDPOINTS = {
+    ME: "/api/auth/me",
+    LOGIN: "/api/auth/login",
+    REGISTER: "/api/auth/register",
+    LOGOUT: "/api/auth/logout",
+    GOOGLE_START: "/api/auth/google/start",
+    SESSION: "/api/auth/session",
+    SESSION_ACTIVITY: "/api/auth/session/activity",
+    SESSION_VALIDATE: "/api/auth/session/validate",
+    EVENT_INIT: "/api/auth/event/init",
+    RESEND_VERIFICATION: "/api/auth/resend-verification",
+};
+// ---------------------------------------------------------------------------
+// User / Account
+// ---------------------------------------------------------------------------
+export const ACCOUNT_ENDPOINTS = {
+    /** @param userId — Firestore user document id */
+    BY_ID: (userId) => `/api/account/${userId}`,
+    PROFILE: "/api/user/profile",
+    CHANGE_PASSWORD: "/api/user/change-password",
+    /** @param userId — for public profile pages */
+    PUBLIC_PROFILE: (userId) => `/api/profile/${userId}`,
+    /** @param userId — seller profile page */
+    SELLER_PROFILE: (sellerId) => `/api/profile/${sellerId}`,
+    /** @param userId — seller public reviews */
+    SELLER_REVIEWS: (sellerId) => `/api/profile/${sellerId}/reviews`,
+    ADDRESSES: "/api/user/addresses",
+    ADDRESS_BY_ID: (id) => `/api/user/addresses/${id}`,
+    ADDRESS_SET_DEFAULT: (id) => `/api/user/addresses/${id}/set-default`,
+    ORDERS: "/api/user/orders",
+    ORDER_BY_ID: (orderId) => `/api/user/orders/${orderId}`,
+    WISHLIST: "/api/user/wishlist",
+};
+// ---------------------------------------------------------------------------
+// Notifications
+// ---------------------------------------------------------------------------
+export const NOTIFICATIONS_ENDPOINTS = {
+    LIST: "/api/notifications",
+    READ_ALL: "/api/notifications/read-all",
+    BY_ID: (id) => `/api/notifications/${id}`,
+};
+// ---------------------------------------------------------------------------
+// Site Settings
+// ---------------------------------------------------------------------------
+export const SITE_SETTINGS_ENDPOINTS = {
+    GET: "/api/site-settings",
+};
+// ---------------------------------------------------------------------------
+// Admin
+// ---------------------------------------------------------------------------
+export const ADMIN_ENDPOINTS = {
+    STATS: "/api/admin/stats",
+    REALTIME_TOKEN: "/api/realtime/token",
+    PAYMENTS_SETTINGS: "/api/admin/payments/settings",
+    BLOG: "/api/admin/blog",
+    EVENTS: "/api/admin/events",
+    COUPONS: "/api/admin/coupons",
+};
+// ---------------------------------------------------------------------------
+// Chat
+// ---------------------------------------------------------------------------
+export const CHAT_ENDPOINTS = {
+    LIST: "/api/chat",
+    BY_ID: (chatId) => `/api/chat/${chatId}`,
+    MESSAGES: (chatId) => `/api/chat/${chatId}/messages`,
+};
+// ---------------------------------------------------------------------------
+// Auctions
+// ---------------------------------------------------------------------------
+export const AUCTION_ENDPOINTS = {
+    LIST: "/api/auctions",
+    BY_SLUG: (slug) => `/api/auctions/${slug}`,
+    BIDS: (slug) => `/api/auctions/${slug}/bids`,
+};
+// ---------------------------------------------------------------------------
+// Bids
+// ---------------------------------------------------------------------------
+export const BID_ENDPOINTS = {
+    LIST: "/api/bids",
+    BY_PRODUCT: (productId) => `/api/bids?productId=${productId}`,
+    REALTIME: (productId) => `/api/realtime/bids/${productId}`,
+};
+// ---------------------------------------------------------------------------
+// Cart
+// ---------------------------------------------------------------------------
+export const CART_ENDPOINTS = {
+    GET: "/api/cart",
+    BY_USER: (userId) => `/api/cart?userId=${userId}`,
+    MERGE: "/api/cart/merge",
+};
+// ---------------------------------------------------------------------------
+// Categories
+// ---------------------------------------------------------------------------
+export const CATEGORY_ENDPOINTS = {
+    LIST: "/api/categories",
+    FLAT: "/api/categories?flat=true",
+    BY_SLUG: (slug) => `/api/categories?slug=${slug}`,
+    BY_PARENT: (parentId) => `/api/categories?parentId=${parentId}`,
+    BRANDS: (pageSize = 100) => `/api/categories?isBrand=true&pageSize=${pageSize}`,
+    ROOT: (pageSize = 20) => `/api/categories?tier=0&pageSize=${pageSize}`,
+};
+// ---------------------------------------------------------------------------
+// Checkout
+// ---------------------------------------------------------------------------
+export const CHECKOUT_ENDPOINTS = {
+    PREFLIGHT: "/api/checkout/preflight",
+    PLACE_ORDER: "/api/checkout",
+};
+// ---------------------------------------------------------------------------
+// Payment
+// ---------------------------------------------------------------------------
+export const PAYMENT_ENDPOINTS = {
+    CREATE_ORDER: "/api/payment/create-order",
+    VERIFY: "/api/payment/verify",
+};
+// ---------------------------------------------------------------------------
+// Collections
+// ---------------------------------------------------------------------------
+export const COLLECTION_ENDPOINTS = {
+    LIST: "/api/collections",
+    BY_SLUG: (slug) => `/api/collections/${slug}`,
+};
+// ---------------------------------------------------------------------------
+// Consultation
+// ---------------------------------------------------------------------------
+export const CONSULTATION_ENDPOINTS = {
+    LIST: "/api/consultations",
+};
+// ---------------------------------------------------------------------------
+// Copilot
+// ---------------------------------------------------------------------------
+export const COPILOT_ENDPOINTS = {
+    CHAT: "/api/copilot/chat",
+};
+// ---------------------------------------------------------------------------
+// Corporate
+// ---------------------------------------------------------------------------
+export const CORPORATE_ENDPOINTS = {
+    INQUIRIES: "/api/corporate-inquiries",
+};
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+export const EVENT_ENDPOINTS = {
+    LIST: "/api/events",
+    BY_ID: (id) => `/api/events/${id}`,
+    ENTRIES: (id) => `/api/events/${id}/entries`,
+    LEADERBOARD: (id, limit) => `/api/events/${id}/leaderboard${limit !== undefined ? `?limit=${limit}` : ""}`,
+};
+// ---------------------------------------------------------------------------
+// FAQ
+// ---------------------------------------------------------------------------
+export const FAQ_ENDPOINTS = {
+    LIST: "/api/faqs",
+    BY_ID: (id) => `/api/faqs/${id}`,
+    VOTE: "/api/faqs/vote",
+};
+// ---------------------------------------------------------------------------
+// Homepage
+// ---------------------------------------------------------------------------
+export const HOMEPAGE_ENDPOINTS = {
+    GET: "/api/homepage",
+    SECTIONS: "/api/homepage-sections",
+    CAROUSEL: "/api/carousel",
+    NEWSLETTER_SUBSCRIBE: "/api/newsletter/subscribe",
+};
+// ---------------------------------------------------------------------------
+// Loyalty
+// ---------------------------------------------------------------------------
+export const LOYALTY_ENDPOINTS = {
+    BALANCE: (uid) => `/api/loyalty/balance?uid=${uid}`,
+};
+// ---------------------------------------------------------------------------
+// Media
+// ---------------------------------------------------------------------------
+export const MEDIA_ENDPOINTS = {
+    BASE: "/api/media",
+    UPLOAD: "/api/media/upload",
+    CROP: "/api/media/crop",
+    TRIM: "/api/media/trim",
+    DELETE: (url) => `/api/media?url=${encodeURIComponent(url)}`,
+};
+// ---------------------------------------------------------------------------
+// Orders
+// ---------------------------------------------------------------------------
+export const ORDER_ENDPOINTS = {
+    LIST: "/api/orders",
+    BY_ID: (id) => `/api/orders/${id}`,
+    TRACK: (trackingId) => `/api/orders/track/${trackingId}`,
+};
+// ---------------------------------------------------------------------------
+// Pre-orders
+// ---------------------------------------------------------------------------
+export const PREORDER_ENDPOINTS = {
+    LIST: "/api/preorders",
+    BY_SLUG: (slug) => `/api/preorders/${slug}`,
+};
+// ---------------------------------------------------------------------------
+// Products
+// ---------------------------------------------------------------------------
+export const PRODUCT_ENDPOINTS = {
+    LIST: "/api/products",
+    BY_SLUG: (slug) => `/api/products/${slug}`,
+    BY_ID: (id) => `/api/products/${id}`,
+};
+// ---------------------------------------------------------------------------
+// Promotions
+// ---------------------------------------------------------------------------
+export const PROMOTION_ENDPOINTS = {
+    LIST: "/api/promotions",
+    COUPON_BY_CODE: (code) => `/api/coupons/${code}`,
+    COUPON_VALIDATE: "/api/coupons/validate",
+};
+// ---------------------------------------------------------------------------
+// Reviews
+// ---------------------------------------------------------------------------
+export const REVIEW_ENDPOINTS = {
+    LIST: "/api/reviews",
+    FEATURED: "/api/reviews?featured=true",
+};
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+export const SEARCH_ENDPOINTS = {
+    QUERY: (q, extra) => `/api/search?q=${encodeURIComponent(q)}${extra ? `&${extra}` : ""}`,
+};
+// ---------------------------------------------------------------------------
+// Seller
+// ---------------------------------------------------------------------------
+export const SELLER_ENDPOINTS = {
+    BECOME: "/api/seller/become",
+    PAYOUTS: "/api/seller/payouts",
+    PAYOUT_SETTINGS: "/api/seller/payout-settings",
+    STORE: "/api/seller/store",
+    STORE_ADDRESSES: "/api/seller/store/addresses",
+    DASHBOARD: "/api/seller/dashboard",
+    ANALYTICS: (period) => `/api/seller/analytics${period ? `?period=${period}` : ""}`,
+};
+// ---------------------------------------------------------------------------
+// Blog
+// ---------------------------------------------------------------------------
+export const BLOG_ENDPOINTS = {
+    LIST: "/api/blog",
+    BY_SLUG: (slug) => `/api/blog/${slug}`,
+    FEATURED: (perPage) => `/api/blog?featured=true${perPage !== undefined ? `&perPage=${perPage}` : ""}`,
+    SORTED: (sort) => `/api/blog?sort=${sort}`,
+};
+// ---------------------------------------------------------------------------
+// Stores
+// ---------------------------------------------------------------------------
+export const STORE_ENDPOINTS = {
+    LIST: "/api/stores",
+    BY_SLUG: (slug) => `/api/stores/${slug}`,
+    PRODUCTS: (slug) => `/api/stores/${slug}/products`,
+    AUCTIONS: (slug) => `/api/stores/${slug}/auctions`,
+    REVIEWS: (slug) => `/api/stores/${slug}/reviews`,
+};
+// ---------------------------------------------------------------------------
+// Wishlist (seller-side)
+// ---------------------------------------------------------------------------
+export const WISHLIST_ENDPOINTS = {
+    LIST: "/api/user/wishlist",
+    BY_USER: (userId) => `/api/wishlist?userId=${userId}`,
+};
+// ---------------------------------------------------------------------------
+// Profile Stats
+// ---------------------------------------------------------------------------
+export const PROFILE_STATS_ENDPOINTS = {
+    ORDERS: "/api/user/orders",
+    ADDRESSES: "/api/user/addresses",
+    PRODUCTS: (sellerId) => `/api/products?filters=sellerId==${sellerId}`,
+    REVIEWS: (userId) => `/api/profile/${userId}/reviews`,
+};
+// ---------------------------------------------------------------------------
+// Before / After
+// ---------------------------------------------------------------------------
+export const BEFORE_AFTER_ENDPOINTS = {
+    LIST: "/api/before-after",
+};
+// ---------------------------------------------------------------------------
+// Demo / Seed
+// ---------------------------------------------------------------------------
+export const DEMO_ENDPOINTS = {
+    SEED: "/api/demo/seed",
+};
+// ---------------------------------------------------------------------------
+// Aggregate namespace export
+// ---------------------------------------------------------------------------
+export const API_ENDPOINTS = {
+    LOGS: LOGS_ENDPOINTS,
+    AUTH: AUTH_ENDPOINTS,
+    ACCOUNT: ACCOUNT_ENDPOINTS,
+    NOTIFICATIONS: NOTIFICATIONS_ENDPOINTS,
+    SITE_SETTINGS: SITE_SETTINGS_ENDPOINTS,
+    ADMIN: ADMIN_ENDPOINTS,
+    CHAT: CHAT_ENDPOINTS,
+    AUCTIONS: AUCTION_ENDPOINTS,
+    BIDS: BID_ENDPOINTS,
+    CART: CART_ENDPOINTS,
+    CATEGORIES: CATEGORY_ENDPOINTS,
+    BEFORE_AFTER: BEFORE_AFTER_ENDPOINTS,
+    CHECKOUT: CHECKOUT_ENDPOINTS,
+    PAYMENT: PAYMENT_ENDPOINTS,
+    COLLECTIONS: COLLECTION_ENDPOINTS,
+    CONSULTATION: CONSULTATION_ENDPOINTS,
+    COPILOT: COPILOT_ENDPOINTS,
+    CORPORATE: CORPORATE_ENDPOINTS,
+    EVENTS: EVENT_ENDPOINTS,
+    FAQS: FAQ_ENDPOINTS,
+    HOMEPAGE: HOMEPAGE_ENDPOINTS,
+    LOYALTY: LOYALTY_ENDPOINTS,
+    MEDIA: MEDIA_ENDPOINTS,
+    ORDERS: ORDER_ENDPOINTS,
+    PREORDERS: PREORDER_ENDPOINTS,
+    PRODUCTS: PRODUCT_ENDPOINTS,
+    PROMOTIONS: PROMOTION_ENDPOINTS,
+    REVIEWS: REVIEW_ENDPOINTS,
+    SEARCH: SEARCH_ENDPOINTS,
+    SELLER: SELLER_ENDPOINTS,
+    BLOG: BLOG_ENDPOINTS,
+    STORES: STORE_ENDPOINTS,
+    WISHLIST: WISHLIST_ENDPOINTS,
+    PROFILE_STATS: PROFILE_STATS_ENDPOINTS,
+    DEMO: DEMO_ENDPOINTS,
+};

package/dist/constants/cache-invalidation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cache Invalidation Paths — @mohasinac/appkit
+ *
+ * Canonical mapping from Firestore collection names to the API path prefixes
+ * they populate. Used by the cache revalidation endpoint and any consumer that
+ * needs to invalidate specific API cache entries after writes.
+ *
+ * Consumers can import `COLLECTION_CACHE_PATHS` directly and pass it to the
+ * cache revalidation route, or extend it with additional entries.
+ */
+/**
+ * Maps seed-script / Firestore collection names → the API path prefixes that
+ * serve data from those collections. The cache revalidation endpoint uses this
+ * to evict stale `CacheManager` entries after a write.
+ *
+ * Extend via `{ ...COLLECTION_CACHE_PATHS, myCollection: ["/api/my-collection"] }`.
+ */
+export declare const COLLECTION_CACHE_PATHS: Readonly<Record<string, string[]>>;

package/dist/constants/cache-invalidation.js

@@ -0,0 +1,33 @@
+/**
+ * Cache Invalidation Paths — @mohasinac/appkit
+ *
+ * Canonical mapping from Firestore collection names to the API path prefixes
+ * they populate. Used by the cache revalidation endpoint and any consumer that
+ * needs to invalidate specific API cache entries after writes.
+ *
+ * Consumers can import `COLLECTION_CACHE_PATHS` directly and pass it to the
+ * cache revalidation route, or extend it with additional entries.
+ */
+import { ADMIN_ENDPOINTS, BLOG_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, ORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, } from "./api-endpoints";
+/**
+ * Maps seed-script / Firestore collection names → the API path prefixes that
+ * serve data from those collections. The cache revalidation endpoint uses this
+ * to evict stale `CacheManager` entries after a write.
+ *
+ * Extend via `{ ...COLLECTION_CACHE_PATHS, myCollection: ["/api/my-collection"] }`.
+ */
+export const COLLECTION_CACHE_PATHS = {
+    categories: [CATEGORY_ENDPOINTS.LIST],
+    products: [PRODUCT_ENDPOINTS.LIST],
+    carouselSlides: [HOMEPAGE_ENDPOINTS.CAROUSEL],
+    homepageSections: [HOMEPAGE_ENDPOINTS.SECTIONS],
+    siteSettings: [SITE_SETTINGS_ENDPOINTS.GET],
+    faqs: [FAQ_ENDPOINTS.LIST],
+    reviews: [REVIEW_ENDPOINTS.LIST],
+    blogPosts: [ADMIN_ENDPOINTS.BLOG, BLOG_ENDPOINTS.LIST],
+    events: [ADMIN_ENDPOINTS.EVENTS, EVENT_ENDPOINTS.LIST],
+    coupons: [ADMIN_ENDPOINTS.COUPONS],
+    cart: [CART_ENDPOINTS.GET],
+    orders: [ORDER_ENDPOINTS.LIST],
+    promotions: [PROMOTION_ENDPOINTS.LIST],
+};

package/dist/constants/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @mohasinac/appkit/constants
+ *
+ * Canonical application constants: API endpoint paths, cache invalidation maps,
+ * and endpoint resolution helpers.
+ *
+ * Import via sub-path:
+ *   import { API_ENDPOINTS } from "@mohasinac/appkit/constants";
+ *   import { COLLECTION_CACHE_PATHS } from "@mohasinac/appkit/constants";
+ *   import { resolveEndpoint } from "@mohasinac/appkit/constants";
+ */
+export { API_ENDPOINTS, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, CHAT_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, DEMO_ENDPOINTS, } from "./api-endpoints";
+export { COLLECTION_CACHE_PATHS } from "./cache-invalidation";
+export { resolveEndpoint, resolveEndpointFn } from "./api-endpoint-resolver";

package/dist/constants/index.js

@@ -0,0 +1,14 @@
+/**
+ * @mohasinac/appkit/constants
+ *
+ * Canonical application constants: API endpoint paths, cache invalidation maps,
+ * and endpoint resolution helpers.
+ *
+ * Import via sub-path:
+ *   import { API_ENDPOINTS } from "@mohasinac/appkit/constants";
+ *   import { COLLECTION_CACHE_PATHS } from "@mohasinac/appkit/constants";
+ *   import { resolveEndpoint } from "@mohasinac/appkit/constants";
+ */
+export { API_ENDPOINTS, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, CHAT_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, DEMO_ENDPOINTS, } from "./api-endpoints";
+export { COLLECTION_CACHE_PATHS } from "./cache-invalidation";
+export { resolveEndpoint, resolveEndpointFn } from "./api-endpoint-resolver";

package/dist/contracts/auth.d.ts

@@ -0,0 +1,58 @@
+export interface AuthPayload {
+    uid: string;
+    email: string | null;
+    /** Application-level role string, e.g. "admin" | "seller" | "user" */
+    role: string;
+    emailVerified: boolean;
+    /** Display name from the auth provider (Google "name" claim) */
+    name?: string | null;
+    /** Photo URL from the auth provider (Google "picture" claim) */
+    picture?: string | null;
+    /** Phone number from the auth provider */
+    phoneNumber?: string | null;
+    /** Any extra custom claims stored on the token */
+    claims?: Record<string, unknown>;
+}
+export interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+    role: string;
+    emailVerified: boolean;
+    disabled: boolean;
+    createdAt: string;
+}
+export interface CreateUserInput {
+    email: string;
+    password?: string;
+    displayName?: string;
+    photoURL?: string;
+    role?: string;
+    emailVerified?: boolean;
+}
+/**
+ * Server-side authentication operations.
+ * Implemented by @mohasinac/auth-firebase, @mohasinac/auth-nextauth, @mohasinac/auth-clerk.
+ */
+export interface IAuthProvider {
+    verifyToken(token: string): Promise<AuthPayload>;
+    createCustomToken(uid: string, claims?: Record<string, unknown>): Promise<string>;
+    getUser(uid: string): Promise<AuthUser | null>;
+    createUser(data: CreateUserInput): Promise<AuthUser>;
+    updateUser(uid: string, data: Partial<CreateUserInput>): Promise<AuthUser>;
+    deleteUser(uid: string): Promise<void>;
+    revokeTokens(uid: string): Promise<void>;
+}
+/**
+ * Session cookie management (HTTP-only, server-side).
+ * Implemented alongside IAuthProvider by the same auth package.
+ */
+export interface ISessionProvider {
+    /** Creates a session cookie value from a verified auth payload. */
+    createSession(payload: AuthPayload): Promise<string>;
+    /** Verifies a session cookie and returns the auth payload. */
+    verifySession(cookie: string): Promise<AuthPayload>;
+    /** Invalidates a session cookie. */
+    destroySession(cookie: string): Promise<void>;
+}

package/dist/contracts/auth.js

@@ -0,0 +1,2 @@
+// ─── Auth Shared Types ────────────────────────────────────────────────────────
+export {};

package/dist/contracts/client-auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Client-side auth provider contract.
+ *
+ * Abstracts client-side authentication operations so hooks
+ * never import a specific auth SDK directly.
+ */
+export interface IClientAuthProvider {
+    /** Sign in with email + password */
+    signInWithEmailAndPassword(email: string, password: string): Promise<void>;
+    /** Apply an email verification action code */
+    applyActionCode(code: string): Promise<void>;
+    /** Send a password reset email */
+    sendPasswordResetEmail(email: string): Promise<void>;
+    /** Confirm a password reset with a code and new password */
+    confirmPasswordReset(code: string, newPassword: string): Promise<void>;
+    /** Re-authenticate with current password and change to new password */
+    reauthenticateAndChangePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /** Reload the current user's profile */
+    reloadCurrentUser(): Promise<void>;
+}
+export declare function registerClientAuthProvider(provider: IClientAuthProvider): void;
+export declare function getClientAuthProvider(): IClientAuthProvider;

package/dist/contracts/client-auth.js

@@ -0,0 +1,17 @@
+/**
+ * Client-side auth provider contract.
+ *
+ * Abstracts client-side authentication operations so hooks
+ * never import a specific auth SDK directly.
+ */
+// ─── Runtime registry ──────────────────────────────────────────────────────
+let _provider = null;
+export function registerClientAuthProvider(provider) {
+    _provider = provider;
+}
+export function getClientAuthProvider() {
+    if (!_provider) {
+        throw new Error("Client auth provider not registered. Call registerClientAuthProvider() before using auth hooks.");
+    }
+    return _provider;
+}

package/dist/contracts/client-payment-gateway.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Client-side payment gateway contract.
+ *
+ * Abstracts the browser-side interaction with a payment gateway SDK
+ * (script loading, modal/redirect, payment response) so checkout hooks
+ * never import a vendor-specific SDK directly.
+ *
+ * Implementations: Razorpay, Stripe, PayPal, etc.
+ */
+import type { PaymentGateway } from "../features/payments/schemas";
+/** Vendor-neutral payment response returned after the user completes payment. */
+export interface GatewayPaymentResponse {
+    /** Gateway-assigned order ID (e.g. Razorpay `order_xxx`, Stripe `pi_xxx`). */
+    gatewayOrderId: string;
+    /** Gateway-assigned payment ID. */
+    gatewayPaymentId: string;
+    /** Cryptographic signature for server-side verification (if gateway provides one). */
+    gatewaySignature?: string;
+}
+/** Options passed to the gateway when opening the payment modal/redirect. */
+export interface OpenGatewayOptions {
+    /** Gateway-assigned order/session ID. */
+    gatewayOrderId: string;
+    /** Public key / publishable key for the gateway SDK. */
+    publicKey: string;
+    /** Amount in the gateway's smallest currency unit (e.g. paise, cents). */
+    amount: number;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Display name shown in the payment modal. */
+    merchantName?: string;
+    /** Order description. */
+    description?: string;
+    /** Logo URL for the payment modal. */
+    logoUrl?: string;
+    /** Prefill customer details. */
+    prefill?: {
+        name?: string;
+        email?: string;
+        phone?: string;
+    };
+    /** Theme/branding overrides. */
+    theme?: {
+        color?: string;
+    };
+}
+export interface IClientPaymentGateway {
+    /** Which gateway this adapter handles. */
+    readonly gateway: PaymentGateway;
+    /**
+     * Load the gateway's client-side SDK script.
+     * Implementations should be idempotent (no-op if already loaded).
+     * @returns `true` when the SDK is ready to use.
+     */
+    loadScript(): Promise<boolean>;
+    /**
+     * Open the payment modal or redirect to the gateway's hosted page.
+     * Resolves with the payment response on success.
+     * Rejects if the user cancels or a gateway error occurs.
+     */
+    openPayment(options: OpenGatewayOptions): Promise<GatewayPaymentResponse>;
+}
+export declare function registerClientPaymentGateway(adapter: IClientPaymentGateway): void;
+export declare function getClientPaymentGateway(gateway: PaymentGateway): IClientPaymentGateway;
+export declare function getRegisteredPaymentGateways(): PaymentGateway[];

package/dist/contracts/client-payment-gateway.js

@@ -0,0 +1,25 @@
+/**
+ * Client-side payment gateway contract.
+ *
+ * Abstracts the browser-side interaction with a payment gateway SDK
+ * (script loading, modal/redirect, payment response) so checkout hooks
+ * never import a vendor-specific SDK directly.
+ *
+ * Implementations: Razorpay, Stripe, PayPal, etc.
+ */
+// ─── Runtime Registry ──────────────────────────────────────────────────────
+const _gateways = new Map();
+export function registerClientPaymentGateway(adapter) {
+    _gateways.set(adapter.gateway, adapter);
+}
+export function getClientPaymentGateway(gateway) {
+    const adapter = _gateways.get(gateway);
+    if (!adapter) {
+        throw new Error(`Client payment gateway "${gateway}" not registered. ` +
+            `Call registerClientPaymentGateway() with a ${gateway} adapter first.`);
+    }
+    return adapter;
+}
+export function getRegisteredPaymentGateways() {
+    return Array.from(_gateways.keys());
+}

package/dist/contracts/client-realtime.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Client-side realtime database provider contract.
+ *
+ * Abstracts RTDB operations so hooks never import a specific SDK.
+ * Register a concrete implementation (Firebase, Supabase, Ably, etc.)
+ * via `registerClientRealtimeProvider()`.
+ */
+/** Snapshot returned by a realtime subscription */
+export interface RealtimeSnapshot {
+    exists(): boolean;
+    val(): unknown;
+}
+/** Unsubscribe function returned by subscribe */
+export type Unsubscribe = () => void;
+export interface IClientRealtimeProvider {
+    /** Authenticate the realtime connection with a custom token */
+    signInWithToken(token: string): Promise<void>;
+    /** Sign out of the realtime connection */
+    signOut(): Promise<void>;
+    /** Subscribe to a path. Returns an unsubscribe function. */
+    subscribe(path: string, onData: (snapshot: RealtimeSnapshot) => void, onError?: (error: Error) => void): Unsubscribe;
+}
+export declare function registerClientRealtimeProvider(provider: IClientRealtimeProvider): void;
+export declare function getClientRealtimeProvider(): IClientRealtimeProvider;

package/dist/contracts/client-realtime.js

@@ -0,0 +1,18 @@
+/**
+ * Client-side realtime database provider contract.
+ *
+ * Abstracts RTDB operations so hooks never import a specific SDK.
+ * Register a concrete implementation (Firebase, Supabase, Ably, etc.)
+ * via `registerClientRealtimeProvider()`.
+ */
+// ─── Runtime registry ──────────────────────────────────────────────────────
+let _provider = null;
+export function registerClientRealtimeProvider(provider) {
+    _provider = provider;
+}
+export function getClientRealtimeProvider() {
+    if (!_provider) {
+        throw new Error("Client realtime provider not registered. Call registerClientRealtimeProvider() before using realtime hooks.");
+    }
+    return _provider;
+}