/**
 * @fileoverview Shared utilities for Firebase and Vercel functions
 * @description Common utilities that can be used by both Firebase and Vercel function implementations
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
import Stripe from 'stripe';
import { DoNotDevError } from '@donotdev/core/server';
import type { UserRole } from '@donotdev/core/server';
export { DoNotDevError };
/**
 * Get Firestore instance using @donotdev/firebase/server
 * Provider handles initialization and caching
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function getFirestore(): FirebaseFirestore.Firestore;
/**
 * Get Auth instance using @donotdev/firebase/server
 * Provider handles initialization and caching
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function getAuth(): import("firebase-admin/auth").Auth;
/**
 * Initialize Stripe explicitly (e.g. with a secret from defineSecret)
 * @param apiKey - Stripe secret key
 */
export declare function initStripe(apiKey: string): Stripe;
/**
 * Get Stripe instance with lazy initialization
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function getStripe(): Stripe;
/**
 * Lazy-initialized Stripe instance proxy
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare const stripe: Stripe;
/**
 * Assert that a user is authenticated from a Firebase callable auth context.
 *
 * @deprecated Import `assertAuthenticated` from `@donotdev/functions/shared/utils/internal/auth` instead.
 * This wrapper extracts uid from a Firebase callable auth context and delegates
 * to the canonical version.
 *
 * @param auth - Firebase callable request auth context (object with `.uid`)
 * @returns The authenticated user's uid
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function assertAuthenticated(auth: any): string;
/**
 * Get user role from Firebase auth context
 *
 * Determines the user's role for visibility filtering based on:
 * - auth.uid: If missing → 'guest'
 * - auth.token.isSuper: If true → 'super'
 * - auth.token.isAdmin: If true → 'admin'
 * - Otherwise → 'user' (authenticated)
 *
 * @param auth - Firebase auth context from callable function
 * @returns UserRole for visibility filtering
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function getUserRole(auth: any): UserRole;
/**
 * Validates that required Stripe environment variables are set
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function validateStripeEnvironment(): void;
/**
 * Creates a standardized success response
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function createSuccessResponse<T>(data: T): {
    success: true;
    data: T;
};
/**
 * Creates a standardized error response
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function createErrorResponse(error: unknown): {
    success: false;
    error: {
        code: string;
        message: string;
        details?: any;
    };
};
/**
 * Updates user subscription in Firebase.
 *
 * **Architecture decision — throwing stubs for billing functions:**
 * These subscription functions (`updateUserSubscription`, `getUserSubscription`,
 * `cancelUserSubscription`, `handleSubscriptionCancellation`) are intentional
 * placeholder implementations. They exist so the framework compiles and
 * type-checks out of the box, but throw at runtime to surface missing
 * integration early. Consumer apps replace them with their billing provider
 * integration (Stripe, Paddle, LemonSqueezy, etc.) via the documented
 * `shared/billing/helpers/` modules.
 *
 * C10: This was a silent no-op stub. It now throws to surface the missing
 * implementation at startup rather than silently dropping webhook events.
 * Use `updateUserSubscription` from `shared/billing/helpers/updateUserSubscription.ts`
 * (which requires an authProvider) instead.
 *
 * @deprecated Import `updateUserSubscription` from `@donotdev/functions/shared/billing/helpers/updateUserSubscription`.
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function updateUserSubscription(_firebaseUid: string, _subscription: any): Promise<void>;
/**
 * Gets user subscription from Firebase.
 *
 * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
 *
 * @deprecated Import from `@donotdev/functions/shared/billing/helpers` or implement directly using Firebase Admin SDK / Stripe API.
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function getUserSubscription(_firebaseUid: string): Promise<any>;
/**
 * Cancels user subscription.
 *
 * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
 *
 * @deprecated Import `cancelUserSubscription` from `@donotdev/functions/shared/billing/helpers/subscriptionManagement`.
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function cancelUserSubscription(_firebaseUid: string, _subscription: any): Promise<void>;
/**
 * Handles subscription cancellation.
 *
 * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
 *
 * @deprecated Handle via Stripe webhook events. Use `processWebhook` from `@donotdev/functions/shared/billing/webhookHandler`.
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function handleSubscriptionCancellation(_firebaseUid: string, _subscription: any): Promise<void>;
/**
 * Asserts that a user has admin privileges
 * Uses role hierarchy: super > admin > user > guest
 *
 * @deprecated Import `assertAdmin` from `@donotdev/functions/shared/utils/internal/auth` instead.
 * This is a thin wrapper that delegates to the canonical provider-agnostic version.
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function assertAdmin(uid: string): Promise<string>;
/**
 * Validates document data
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function validateDocument(data: any, schema?: any): void;
/**
 * Validates a Firestore collection name from client-supplied schema.
 *
 * W22: Vercel CRUD handlers accept `schema` (including collection name) from
 * the client. This is a known design limitation. As a defense-in-depth measure,
 * reject collection names that could be used for path traversal or access to
 * internal collections.
 *
 * @param name - Collection name to validate
 * @throws Error if the name is unsafe
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function validateCollectionName(name: string): void;
/**
 * Verifies Firebase auth token
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function verifyFirebaseAuthToken(token: string): Promise<string>;
/**
 * Finds references to a document
 *
 * @version 0.1.0
 * @since 0.0.1
 * @author AMBROISE PARK Consulting
 */
export declare function findReferences(collection: string, docId: string, referenceMetadata?: {
    incoming?: Array<{
        sourceCollection: string;
        sourceField: string;
    }>;
}): Promise<Array<{
    collection: string;
    field: string;
    count: number;
}>>;
