@sylphx/sdk 0.3.0 → 0.3.2

package/dist/nextjs/index.d.ts

@@ -0,0 +1,2061 @@
+import { NextResponse, NextRequest } from 'next/server';
+
+/**
+ * Sylphx Unified Middleware — State of the Art
+ *
+ * ONE middleware function handles EVERYTHING:
+ * - Auth routes (mounted automatically, zero manual API routes)
+ * - Token refresh (automatic, every request)
+ * - Route protection
+ * - Cookie management
+ *
+ * This follows Auth0 v4 / Clerk / Supabase patterns where middleware
+ * handles all auth concerns. Apps don't need to create any /api/auth/* routes.
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts (or proxy.ts for Next.js 16)
+ * import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
+ *
+ * export default createSylphxMiddleware({
+ *   publicRoutes: ['/', '/about', '/pricing'],
+ * })
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next|.*\\..*).*)', '/'],
+ * }
+ * ```
+ *
+ * That's it. No /api/auth/* routes needed.
+ */
+
+interface SylphxMiddlewareConfig {
+    /**
+     * Routes that don't require authentication.
+     * Supports exact paths and wildcards.
+     *
+     * @example ['/', '/about', '/pricing', '/blog/*']
+     * @default ['/']
+     */
+    publicRoutes?: string[];
+    /**
+     * Routes that middleware should completely ignore.
+     * Use for webhooks, static assets, or third-party integrations.
+     *
+     * @default []
+     */
+    ignoredRoutes?: string[];
+    /**
+     * URL to redirect unauthenticated users.
+     * @default '/login'
+     */
+    signInUrl?: string;
+    /**
+     * URL to redirect after sign out.
+     * @default '/'
+     */
+    afterSignOutUrl?: string;
+    /**
+     * URL to redirect after successful sign in.
+     * @default '/dashboard'
+     */
+    afterSignInUrl?: string;
+    /**
+     * Auth routes prefix. Routes are mounted at:
+     * - {prefix}/callback — OAuth callback handler
+     * - {prefix}/signout — Sign out handler
+     *
+     * @default '/auth'
+     */
+    authPrefix?: string;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Secret key for authentication.
+     * Override to use a programmatic key instead of SYLPHX_SECRET_KEY env var.
+     *
+     * Use case: Platform Console uses dynamically generated keys.
+     *
+     * @default process.env.SYLPHX_SECRET_KEY
+     */
+    secretKey?: string;
+    /**
+     * Platform URL for API calls.
+     * Override for self-hosted or same-origin deployments.
+     *
+     * @default process.env.SYLPHX_PLATFORM_URL || 'https://sylphx.com'
+     */
+    platformUrl?: string;
+    /**
+     * Callback to add custom headers/logic to responses.
+     * Called for every non-auth-route request after SDK processing.
+     *
+     * Use case: Add security headers, tracking cookies, etc.
+     *
+     * @example
+     * ```typescript
+     * onResponse: (response, request) => {
+     *   response.headers.set('X-Custom-Header', 'value')
+     * }
+     * ```
+     */
+    onResponse?: (response: NextResponse, request: NextRequest) => void | Promise<void>;
+}
+/**
+ * Create Sylphx middleware — State of the Art
+ *
+ * ONE function handles everything:
+ * - Auth routes ({authPrefix}/callback, {authPrefix}/signout)
+ * - Token refresh (automatic, every request)
+ * - Route protection
+ * - Cookie management
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts (or proxy.ts for Next.js 16)
+ * import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
+ *
+ * export default createSylphxMiddleware({
+ *   publicRoutes: ['/', '/about', '/pricing'],
+ * })
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next|.*\\..*).*)', '/'],
+ * }
+ * ```
+ */
+declare function createSylphxMiddleware(userConfig?: SylphxMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Create recommended matcher config
+ */
+declare function createMatcher(): {
+    matcher: string[];
+};
+/**
+ * Get cookie namespace from secret key (for advanced use)
+ */
+declare function getNamespace(secretKey: string): string;
+
+interface components {
+	schemas: {
+		ErrorResponse: {
+			error: {
+				message: string
+				code: string
+			}
+		}
+		User: {
+			/** Format: uuid */
+			id: string
+			/** Format: email */
+			email: string
+			name: string | null
+			/** Format: uri */
+			image?: string | null
+			emailVerified: boolean
+		}
+		TokenResponse: {
+			accessToken: string
+			refreshToken: string
+			/** @description Token expiry in seconds */
+			expiresIn: number
+			user: components['schemas']['User']
+		}
+		/** @enum {string} */
+		OrgRole: 'super_admin' | 'admin' | 'billing' | 'analytics' | 'developer' | 'viewer'
+		Organization: {
+			/** Format: uuid */
+			id: string
+			name: string
+			slug: string
+			/** Format: uri */
+			logoUrl: string | null
+			/** Format: email */
+			email: string | null
+			/** Format: email */
+			billingEmail: string | null
+			/** Format: date-time */
+			createdAt: string
+		}
+		OrganizationMember: {
+			/** Format: uuid */
+			id: string
+			/** Format: uuid */
+			userId: string
+			/** Format: email */
+			email: string
+			name: string | null
+			/** Format: uri */
+			image: string | null
+			role: components['schemas']['OrgRole']
+			/** Format: date-time */
+			joinedAt: string
+		}
+		OrganizationInvitation: {
+			/** Format: uuid */
+			id: string
+			/** Format: email */
+			email: string
+			role: components['schemas']['OrgRole']
+			/** @enum {string} */
+			status: 'pending' | 'accepted' | 'expired' | 'revoked'
+			/** Format: uuid */
+			invitedById: string
+			invitedByName: string | null
+			/** Format: date-time */
+			expiresAt: string
+			/** Format: date-time */
+			createdAt: string
+		}
+		OrganizationMembership: {
+			role: components['schemas']['OrgRole']
+			/** Format: date-time */
+			joinedAt: string
+		}
+		CreateOrgRequest: {
+			name: string
+			slug?: string
+			/** Format: email */
+			email?: string
+		}
+		UpdateOrgRequest: {
+			name?: string
+			slug?: string
+			/** Format: uri */
+			logoUrl?: string | null
+			/** Format: email */
+			email?: string | null
+			/** Format: email */
+			billingEmail?: string | null
+		}
+		InviteMemberRequest: {
+			/** Format: email */
+			email: string
+			role: components['schemas']['OrgRole']
+		}
+		UpdateMemberRoleRequest: {
+			role: components['schemas']['OrgRole']
+		}
+		AcceptInvitationRequest: {
+			token: string
+		}
+		OrganizationsResponse: {
+			organizations: components['schemas']['Organization'][]
+		}
+		OrganizationResponse: {
+			organization: components['schemas']['Organization']
+			membership: components['schemas']['OrganizationMembership'] & unknown
+		}
+		CreateOrgResponse: {
+			organization: components['schemas']['Organization']
+		}
+		OrganizationMembersResponse: {
+			members: components['schemas']['OrganizationMember'][]
+		}
+		OrganizationInvitationsResponse: {
+			invitations: components['schemas']['OrganizationInvitation'][]
+		}
+		InviteMemberResponse: {
+			invitation: components['schemas']['OrganizationInvitation']
+		}
+		UpdateMemberRoleResponse: {
+			member: components['schemas']['OrganizationMember']
+		}
+		AcceptInvitationResponse: {
+			organization: components['schemas']['Organization']
+		}
+		LoginResponse:
+			| {
+					/** @enum {boolean} */
+					requiresTwoFactor: false
+					accessToken: string
+					refreshToken: string
+					expiresIn: number
+					user: components['schemas']['User']
+			  }
+			| {
+					/** @enum {boolean} */
+					requiresTwoFactor: true
+					/** Format: uuid */
+					userId: string
+					/** Format: email */
+					email: string
+			  }
+		LoginRequest: {
+			/** Format: email */
+			email: string
+			password: string
+		}
+		RegisterResponse: {
+			requiresVerification: boolean
+			message: string
+			user: {
+				/** Format: uuid */
+				id: string
+				/** Format: email */
+				email: string
+				name: string | null
+			}
+		}
+		RegisterRequest: {
+			name: string
+			/** Format: email */
+			email: string
+			password: string
+		}
+		TwoFactorVerifyRequest: {
+			/** Format: uuid */
+			userId: string
+			code: string
+		}
+		SuccessResponse: {
+			success: boolean
+			message?: string
+		}
+		ForgotPasswordRequest: {
+			/** Format: email */
+			email: string
+		}
+		ResetPasswordRequest: {
+			token: string
+			password: string
+		}
+		VerifyEmailRequest: {
+			token: string
+		}
+		LogoutRequest: {
+			refreshToken?: string
+		}
+		MeResponse: {
+			/** Format: uuid */
+			id: string
+			/** Format: email */
+			email: string
+			name: string | null
+			/** Format: uri */
+			image?: string | null
+			emailVerified: boolean
+			twoFactorEnabled: boolean
+		}
+		OAuthProvidersResponse: {
+			providers: string[]
+		}
+		UserProfile: {
+			/** Format: uuid */
+			id: string
+			/** Format: email */
+			email: string
+			name: string | null
+			/** Format: uri */
+			image?: string | null
+			emailVerified: boolean
+			/** Format: date-time */
+			createdAt: string
+		}
+		UpdateProfileRequest: {
+			name?: string
+			/** Format: uri */
+			image?: string | null
+		}
+		SecuritySettings: {
+			twoFactorEnabled: boolean
+			hasPassword: boolean
+			emailVerified: boolean
+		}
+		SessionsResponse: components['schemas']['Session'][]
+		Session: {
+			/** Format: uuid */
+			id: string
+			isCurrent: boolean
+			deviceName?: string | null
+			browser?: string | null
+			os?: string | null
+			deviceType?: string | null
+			ipAddress?: string | null
+			country?: string | null
+			city?: string | null
+			/** Format: date-time */
+			lastActiveAt: string
+			/** Format: date-time */
+			createdAt: string
+		}
+		LoginHistoryEntry: {
+			/** Format: uuid */
+			id: string
+			ipAddress?: string | null
+			userAgent?: string | null
+			country?: string | null
+			city?: string | null
+			device?: string | null
+			success: boolean
+			/** Format: date-time */
+			createdAt: string
+		}
+		ConnectedAccount: {
+			provider: string
+			/** Format: date-time */
+			connectedAt: string
+		}
+		PlansResponse: components['schemas']['Plan'][]
+		Plan: {
+			/** Format: uuid */
+			id: string
+			slug: string
+			name: string
+			description: string | null
+			features: string[]
+			priceMonthly: number | null
+			priceAnnual: number | null
+			priceLifetime: number | null
+		}
+		Subscription: {
+			/** Format: uuid */
+			id: string
+			/** Format: uuid */
+			userId: string
+			/** Format: uuid */
+			planId: string
+			planSlug: string
+			status: string
+			/** @enum {string} */
+			interval: 'monthly' | 'annual' | 'lifetime'
+			/** Format: date-time */
+			currentPeriodStart: string | null
+			/** Format: date-time */
+			currentPeriodEnd: string | null
+			cancelAtPeriodEnd: boolean
+			/** Format: date-time */
+			trialEnd: string | null
+		} | null
+		CheckoutResponse: {
+			/** Format: uri */
+			checkoutUrl: string | null
+			sessionId: string
+		}
+		CheckoutRequest: {
+			/** Format: uuid */
+			userId: string
+			planSlug: string
+			/** @enum {string} */
+			interval: 'monthly' | 'annual' | 'lifetime'
+			/** Format: uri */
+			successUrl: string
+			/** Format: uri */
+			cancelUrl: string
+		}
+		PortalResponse: {
+			/** Format: uri */
+			portalUrl: string
+		}
+		PortalRequest: {
+			/** Format: uuid */
+			userId: string
+			/** Format: uri */
+			returnUrl: string
+		}
+		BalanceResponse: {
+			balance: {
+				current: number
+				currentFormatted: string
+			}
+			status: {
+				level: string
+				isHealthy: boolean
+				isLow: boolean
+				alertThreshold: number
+			}
+			/** @enum {string} */
+			billingType: 'prepaid' | 'postpaid'
+			trustLevel: string
+			spendingCap: number | null
+			currentMonthSpend: number
+			spendingCapPercent: number | null
+			/** Format: date-time */
+			gracePeriodEndsAt: string | null
+			isAdminOrg: boolean
+		}
+		UsageResponse: {
+			period: {
+				type: string
+				/** Format: date-time */
+				start: string
+				/** Format: date-time */
+				end: string
+			}
+			metrics: {
+				aiCostMicrodollars: number
+				storageBytesUsed: number
+				storageEgressBytes: number
+				storageUploads: number
+				dbStorageBytes: number
+				dbComputeSeconds: number
+				emailSentCount: number
+				jobInvocationCount: number
+				cronActiveCount: number
+				notificationsSentCount: number
+				analyticsEventCount: number
+				webhookDeliveryCount: number
+				errorEventCount: number
+				authMau: number
+			} | null
+		}
+		BatchTrackResponse: {
+			success: boolean
+			/** @description Number of new events tracked */
+			count: number
+			/** @description Number of duplicate events filtered out */
+			deduplicated: number
+			/** @description Total events in the request */
+			total: number
+		}
+		BatchTrackRequest: {
+			events: components['schemas']['TrackEventItem'][]
+		}
+		TrackEventItem: {
+			event: string
+			properties?: {
+				[key: string]: unknown
+			}
+			/** Format: date-time */
+			timestamp?: string
+			destinations?: ('google_ads' | 'meta' | 'tiktok')[]
+			skipDestinations?: boolean
+			conversion?: components['schemas']['ConversionData']
+		}
+		ConversionData: {
+			clickId?: string
+			value?: number
+			currency?: string
+			orderId?: string
+			/** Format: email */
+			userEmail?: string
+			userPhone?: string
+			userFirstName?: string
+			userLastName?: string
+		}
+		AnalyticsQueryResponse: {
+			data: {
+				eventName: string
+				count: number
+			}[]
+			/** @description Total count across all events */
+			total: number
+		}
+		AnalyticsQueryRequest: {
+			/**
+			 * Format: date-time
+			 * @description Start of date range (ISO 8601)
+			 */
+			dateFrom?: string
+			/**
+			 * Format: date-time
+			 * @description End of date range (ISO 8601)
+			 */
+			dateTo?: string
+			/** @description Filter by specific event names */
+			events?: string[]
+			/**
+			 * @description Group by time interval
+			 * @enum {string}
+			 */
+			interval?: 'hour' | 'day' | 'week' | 'month'
+			/**
+			 * @description Limit results (default 100, max 1000)
+			 * @default 100
+			 */
+			limit: number
+		}
+		JobStatusResponse: {
+			available: boolean
+			provider: string
+		}
+		ScheduleJobResponse: {
+			/** Format: uuid */
+			jobId?: string
+			messageId?: string
+			/** Format: date-time */
+			scheduledFor?: string | null
+		}
+		ScheduleJobRequest: {
+			/** Format: uri */
+			callbackUrl: string
+			payload?: {
+				[key: string]: unknown
+			}
+			/**
+			 * @default POST
+			 * @enum {string}
+			 */
+			method: 'GET' | 'POST' | 'PUT' | 'DELETE'
+			headers?: {
+				[key: string]: string
+			}
+			delay?: number
+			/** Format: date-time */
+			scheduledFor?: string
+			/** @default 3 */
+			retries: number
+			name?: string
+			type?: string
+			/** @default 30 */
+			timeout: number
+		}
+		ListJobsResponse: {
+			jobs: components['schemas']['Job'][]
+			total: number
+			limit: number
+			offset: number
+		}
+		Job: {
+			/** Format: uuid */
+			id: string
+			name: string | null
+			type: string
+			/** @enum {string} */
+			status:
+				| 'pending'
+				| 'queued'
+				| 'running'
+				| 'completed'
+				| 'failed'
+				| 'scheduled'
+				| 'paused'
+				| 'cancelled'
+				| 'deleted'
+			callbackUrl: string
+			payload?: {
+				[key: string]: unknown
+			}
+			/** Format: date-time */
+			scheduledFor: string | null
+			/** Format: date-time */
+			startedAt: string | null
+			/** Format: date-time */
+			completedAt: string | null
+			/** Format: date-time */
+			failedAt: string | null
+			retries: number
+			maxRetries: number
+			lastError: string | null
+			cronExpression: string | null
+			/** Format: date-time */
+			createdAt: string
+		}
+		ScheduleCronResponse: {
+			/** Format: uuid */
+			jobId?: string
+			scheduleId: string
+			cron: string
+			paused: boolean
+		}
+		ScheduleCronRequest: {
+			/** Format: uri */
+			callbackUrl: string
+			cron: string
+			payload?: {
+				[key: string]: unknown
+			}
+			/**
+			 * @default POST
+			 * @enum {string}
+			 */
+			method: 'GET' | 'POST' | 'PUT' | 'DELETE'
+			headers?: {
+				[key: string]: string
+			}
+			/** @default 3 */
+			retries: number
+			name: string
+			type?: string
+			/** @default false */
+			paused: boolean
+		}
+		ReferralCodeResponse: {
+			/** @description 8-character referral code */
+			code: string
+			/** @enum {string} */
+			status: 'pending' | 'completed' | 'expired'
+		}
+		RegenerateCodeResponse: {
+			/** @description New 8-character referral code */
+			code: string
+			totalReferrals: number
+			completedReferrals: number
+			pendingReferrals: number
+		}
+		ReferralStatsResponse: {
+			/** @description Total referrals created */
+			totalReferrals: number
+			/** @description Successfully completed referrals */
+			completedReferrals: number
+			/** @description Pending referrals */
+			pendingReferrals: number
+		}
+		RedeemReferralResponse: {
+			success: boolean
+			/** @description Type of reward applied */
+			rewardType: string
+			/** @description Details of reward applied to referee */
+			referredReward?: {
+				[key: string]: unknown
+			}
+			/** @description Details of reward applied to referrer */
+			referrerReward?: {
+				[key: string]: unknown
+			}
+		}
+		RedeemReferralRequest: {
+			/** @description Referral code to redeem */
+			code: string
+			defaults?: components['schemas']['ReferralRewardDefaults']
+		}
+		/** @description Optional inline defaults for reward configuration */
+		ReferralRewardDefaults: {
+			referrerReward?: components['schemas']['ReferralRewardConfig']
+			refereeReward?: components['schemas']['ReferralRewardConfig'] & unknown
+			/** @description Whether both parties get rewarded (default: true) */
+			doubleReward?: boolean
+			/** @description Minimum days before rewards are granted (anti-fraud) */
+			minimumDaysBeforeReward?: number
+		}
+		/** @description Reward for the person who shared the code */
+		ReferralRewardConfig: {
+			/** @enum {string} */
+			type: 'points' | 'premium_trial' | 'discount' | 'credit'
+			/** @description Points to award (for type: points) */
+			points?: number
+			/** @description Trial days to grant (for type: premium_trial) */
+			days?: number
+			/** @description Discount percentage (for type: discount) */
+			discountPercent?: number
+			/** @description Credit amount in cents (for type: credit) */
+			creditCents?: number
+		}
+		LeaderboardResponse: {
+			/** @enum {string} */
+			period: 'all' | 'month' | 'week'
+			entries: components['schemas']['LeaderboardEntry'][]
+			/** @description Current user rank if authenticated */
+			currentUserRank: number | null
+		}
+		LeaderboardEntry: {
+			/** @description Position in the leaderboard */
+			rank: number
+			/**
+			 * Format: uuid
+			 * @description User ID (only revealed if current user)
+			 */
+			userId: string | null
+			/** @description Masked name for privacy */
+			displayName: string | null
+			/** Format: uri */
+			avatarUrl: string | null
+			completedReferrals: number
+			totalReferrals: number
+			isCurrentUser: boolean
+		}
+		PushPreferencesResponse: {
+			enabled: boolean
+			subscriptionCount: number
+		}
+		RegisterPushResponse: {
+			success: boolean
+			updated: boolean
+		}
+		RegisterPushRequest: {
+			subscription: {
+				/** Format: uri */
+				endpoint: string
+				keys: {
+					p256dh: string
+					auth: string
+				}
+			}
+		}
+		UnregisterPushRequest: {
+			/** Format: uri */
+			endpoint: string
+		}
+		MobileConfigResponse: {
+			ios: boolean
+			android: boolean
+			anyConfigured: boolean
+		}
+		MobilePreferencesResponse: {
+			enabled: boolean
+			devices: components['schemas']['MobileDevice'][]
+		}
+		MobileDevice: {
+			/** Format: uuid */
+			id: string
+			/** @enum {string} */
+			platform: 'ios' | 'android'
+			name: string | null
+			/** Format: date-time */
+			registeredAt: string
+			/** Format: date-time */
+			lastUsedAt: string | null
+		}
+		RegisterMobileDeviceResponse: {
+			success: boolean
+			updated: boolean
+			/** Format: uuid */
+			tokenId: string
+		}
+		RegisterMobileDeviceRequest: {
+			/** @enum {string} */
+			platform: 'ios' | 'android'
+			token: string
+			deviceId?: string
+			deviceName?: string
+			appVersion?: string
+			osVersion?: string
+		}
+		UnregisterMobileDeviceRequest: {
+			token: string
+		}
+		InAppMessagesResponse: components['schemas']['InAppMessage'][]
+		InAppMessage: {
+			/** Format: uuid */
+			id: string
+			/** @enum {string|null} */
+			type: 'info' | 'success' | 'warning' | 'error' | 'announcement' | 'system' | 'action' | null
+			/** @enum {string|null} */
+			priority: 'low' | 'normal' | 'high' | 'urgent' | null
+			title: string
+			body: string
+			icon: string | null
+			imageUrl: string | null
+			actionText: string | null
+			actionUrl: string | null
+			secondaryActionText: string | null
+			secondaryActionUrl: string | null
+			metadata: {
+				[key: string]: unknown
+			} | null
+			topic: string | null
+			isRead: boolean
+			isDismissed: boolean
+			/** Format: date-time */
+			readAt: string | null
+			/** Format: date-time */
+			createdAt: string
+		}
+		UnreadCountResponse: {
+			count: number
+		}
+		MarkAllReadResponse: {
+			success: boolean
+			markedCount: number
+		}
+		RecordClickRequest: {
+			/** @enum {string} */
+			action: 'primary' | 'secondary'
+		}
+		MessagePreferencesResponse: {
+			enabled: boolean
+			mutedTopics: string[]
+			highPriorityOnly: boolean
+		}
+		UpdateMessagePreferencesRequest: {
+			enabled?: boolean
+			mutedTopics?: string[]
+			highPriorityOnly?: boolean
+		}
+		StorageFile: {
+			/** Format: uuid */
+			id: string
+			filename: string
+			path: string
+			/** Format: uri */
+			url: string | null
+			mimeType: string
+			/** @description File size in bytes */
+			size: number
+			metadata: {
+				[key: string]: unknown
+			} | null
+			/** Format: date-time */
+			createdAt: string
+		}
+		UploadUrlResponse: {
+			/**
+			 * Format: uri
+			 * @description Endpoint URL for the upload
+			 */
+			uploadEndpoint: string
+			/** @description JSON payload to include in the upload request */
+			clientPayload: string
+			/** @description Maximum file size in bytes */
+			maxSize: number
+			/** @description List of allowed MIME types */
+			allowedContentTypes: string[]
+			/** @description Instructions for making the upload request */
+			instructions: {
+				method: string
+				headers: {
+					[key: string]: string
+				}
+				body: {
+					type: string
+					payload: {
+						pathname: string
+						clientPayload: string
+					}
+				}
+			}
+		}
+		UploadUrlRequest: {
+			/** @description Name of the file to upload */
+			filename: string
+			/** @description MIME type of the file */
+			contentType?: string
+			/** @description Optional folder path within app storage */
+			folder?: string
+			/** @description Custom metadata to attach to the file */
+			metadata?: {
+				[key: string]: unknown
+			}
+		}
+		CaptureExceptionResponse: {
+			/**
+			 * Format: uuid
+			 * @description Unique event ID
+			 */
+			eventId: string
+			/** @description Whether this is a new unique error or a duplicate */
+			isNewError: boolean
+		}
+		CaptureExceptionRequest: {
+			/** @description The exception to capture */
+			exception: {
+				values: components['schemas']['MonitoringExceptionValue'][]
+			}
+			level?: components['schemas']['MonitoringErrorLevel']
+			/** @description Tags for filtering */
+			tags?: {
+				[key: string]: string
+			}
+			/** @description Extra context data */
+			extra?: {
+				[key: string]: unknown
+			}
+			/** @description Breadcrumbs leading up to the error */
+			breadcrumbs?: components['schemas']['MonitoringBreadcrumb'][]
+			/** @description Current page/screen */
+			route?: string
+			/** @description User agent */
+			userAgent?: string
+			/** @description Custom fingerprint for grouping */
+			fingerprint?: string[]
+			/** @description Release version */
+			release?: string
+			/** @description Environment (dev/staging/prod) */
+			environment?: string
+		}
+		MonitoringExceptionValue: {
+			/** @description Exception type (e.g., "TypeError", "ReferenceError") */
+			type: string
+			/** @description Exception message */
+			value: string
+			stacktrace?: {
+				frames: {
+					filename?: string
+					function?: string
+					lineno?: number
+					colno?: number
+					in_app?: boolean
+				}[]
+			}
+		}
+		/**
+		 * @description Error level
+		 * @enum {string}
+		 */
+		MonitoringErrorLevel: 'fatal' | 'error' | 'warning' | 'info'
+		MonitoringBreadcrumb: {
+			type: string
+			category: string
+			message: string
+			timestamp: string
+		}
+		CaptureMessageResponse: {
+			/**
+			 * Format: uuid
+			 * @description Unique event ID
+			 */
+			eventId: string
+			/** @description Whether this is a new unique message or a duplicate */
+			isNewError: boolean
+		}
+		CaptureMessageRequest: {
+			/** @description Message to capture */
+			message: string
+			level?: components['schemas']['MonitoringErrorLevel'] & unknown
+			/** @description Tags for filtering */
+			tags?: {
+				[key: string]: string
+			}
+			/** @description Extra context data */
+			extra?: {
+				[key: string]: unknown
+			}
+			/** @description Current page/screen */
+			route?: string
+		}
+		AIUsageResponse: {
+			/** @enum {string} */
+			period: 'day' | 'week' | 'month'
+			/** @description Total number of AI requests */
+			requests: number
+			tokens: {
+				/** @description Total input tokens */
+				input: number
+				/** @description Total output tokens */
+				output: number
+				/** @description Total tokens (input + output) */
+				total: number
+			}
+			cost: {
+				/** @description Cost in microdollars (1/1,000,000 USD) */
+				microdollars: number
+				/** @description Human-readable cost string */
+				formatted: string
+			}
+			/** @description Usage breakdown by model */
+			byModel: {
+				[key: string]: {
+					requests: number
+					tokens: number
+					cost: number
+				}
+			}
+			/** @description Usage breakdown by request type (chat, embedding, vision) */
+			byType: {
+				[key: string]: {
+					requests: number
+					tokens: number
+				}
+			}
+		}
+		AIRateLimitResponse: {
+			/** @description Max requests per minute (null if unlimited) */
+			requestsPerMinute: number | null
+			/** @description Max requests per day (null if unlimited) */
+			requestsPerDay: number | null
+			/** @description Max tokens per minute (null if unlimited) */
+			tokensPerMinute: number | null
+			/** @description Max tokens per day (null if unlimited) */
+			tokensPerDay: number | null
+			/** @description Max cost per day in microdollars (null if unlimited) */
+			costPerDayMicrodollars: number | null
+			current: {
+				/** @description Requests made in the last minute */
+				requestsThisMinute: number
+				/** @description Requests made today */
+				requestsToday: number
+				/** @description Tokens used in the last minute */
+				tokensThisMinute: number
+				/** @description Tokens used today */
+				tokensToday: number
+				/** @description Cost today in microdollars */
+				costToday: number
+			}
+		}
+		AIModelsResponse: {
+			models: components['schemas']['AIModel'][]
+			/** @description Total number of matching models */
+			total: number
+			/** @description Whether more results are available */
+			hasMore: boolean
+		}
+		AIModel: {
+			/** @description Model ID (e.g., openai/gpt-4) */
+			id: string
+			/** @description Human-readable model name */
+			name: string
+			/** @description Model description */
+			description?: string | null
+			/** @description Model capabilities */
+			capabilities: ('chat' | 'vision' | 'tool' | 'embedding')[]
+			/** @description Maximum context window size */
+			contextWindow?: number
+			pricing?: {
+				/** @description Cost per input token in USD */
+				inputPerToken?: number
+				/** @description Cost per output token in USD */
+				outputPerToken?: number
+			}
+		}
+		ConsentTypesResponse: components['schemas']['ConsentType'][]
+		ConsentType: {
+			/** Format: uuid */
+			id: string
+			slug: string
+			/** @enum {string} */
+			category: 'necessary' | 'analytics' | 'marketing' | 'preferences' | 'functional'
+			name: string
+			description: string
+			required: boolean
+			defaultEnabled: boolean
+		}
+		UserConsentsResponse: components['schemas']['UserConsent'][]
+		UserConsent: {
+			slug: string
+			/** @enum {string} */
+			category: 'necessary' | 'analytics' | 'marketing' | 'preferences' | 'functional'
+			name: string
+			required: boolean
+			granted: boolean
+			/** Format: date-time */
+			grantedAt: string | null
+			version: number | null
+		}
+		SetConsentResponse: {
+			consents: {
+				slug: string
+				granted: boolean
+			}[]
+		}
+		SetConsentRequest: {
+			/**
+			 * Format: uuid
+			 * @description User ID (for logged-in users)
+			 */
+			userId?: string
+			/** @description Anonymous ID (for non-logged-in users) */
+			anonymousId?: string
+			/** @description Consents to set */
+			consents: {
+				/** @description Consent type slug */
+				slug: string
+				/** @description Whether consent is granted */
+				granted: boolean
+			}[]
+			/**
+			 * @description Source of consent
+			 * @default banner
+			 * @enum {string}
+			 */
+			source: 'banner' | 'settings' | 'api'
+			/** @description User agent string */
+			userAgent?: string
+		}
+		AcceptAllConsentRequest: {
+			/**
+			 * Format: uuid
+			 * @description User ID (for logged-in users)
+			 */
+			userId?: string
+			/** @description Anonymous ID (for non-logged-in users) */
+			anonymousId?: string
+			/**
+			 * @description Source of consent
+			 * @default banner
+			 * @enum {string}
+			 */
+			source: 'banner' | 'settings' | 'api'
+			/** @description User agent string */
+			userAgent?: string
+		}
+		DeclineOptionalConsentRequest: {
+			/**
+			 * Format: uuid
+			 * @description User ID (for logged-in users)
+			 */
+			userId?: string
+			/** @description Anonymous ID (for non-logged-in users) */
+			anonymousId?: string
+			/**
+			 * @description Source of consent
+			 * @default banner
+			 * @enum {string}
+			 */
+			source: 'banner' | 'settings' | 'api'
+			/** @description User agent string */
+			userAgent?: string
+		}
+		SendEmailResponse: {
+			success: boolean
+			/** @description Email ID from provider */
+			id?: string
+		}
+		SendEmailRequest: {
+			/**
+			 * Format: email
+			 * @description Recipient email address
+			 */
+			to: string
+			/** @description Email subject */
+			subject: string
+			/** @description Email HTML content */
+			html: string
+			/** @description Plain text fallback */
+			text?: string
+			/**
+			 * Format: email
+			 * @description Reply-to email address
+			 */
+			replyTo?: string
+		}
+		SendTemplatedEmailResponse: {
+			success: boolean
+			/** @description Template that was sent */
+			template: string
+		}
+		SendTemplatedEmailRequest: {
+			/**
+			 * @description Template type
+			 * @enum {string}
+			 */
+			template: 'welcome' | 'verification' | 'password_reset' | 'security_alert'
+			/**
+			 * Format: email
+			 * @description Recipient email address
+			 */
+			to: string
+			/** @description Template variables */
+			data?: {
+				[key: string]: unknown
+			}
+		}
+		SendToUserResponse: {
+			success: boolean
+			/** @description Email ID from provider */
+			id?: string
+		}
+		SendToUserRequest: {
+			/**
+			 * Format: uuid
+			 * @description User ID to send email to
+			 */
+			userId: string
+			/** @description Email subject */
+			subject: string
+			/** @description Email HTML content */
+			html: string
+			/** @description Plain text fallback */
+			text?: string
+		}
+		NewsletterSubscribeResponse: {
+			success: boolean
+			/** @description Human-readable result message */
+			message: string
+			/** @description Whether email verification is required */
+			requiresVerification: boolean
+			/** @description Whether email was already subscribed */
+			alreadySubscribed: boolean
+		}
+		NewsletterSubscribeRequest: {
+			/**
+			 * Format: email
+			 * @description Subscriber email address
+			 */
+			email: string
+			/**
+			 * @description Subscription source
+			 * @default website
+			 * @enum {string}
+			 */
+			source: 'website' | 'waitlist' | 'referral' | 'api' | 'import'
+			/** @description Subscriber name */
+			name?: string
+			/** @description Additional tracking metadata */
+			metadata?: {
+				referrer?: string
+				utmSource?: string
+				utmMedium?: string
+				utmCampaign?: string
+				referralCode?: string
+			} & {
+				[key: string]: unknown
+			}
+			/** @description Initial subscription preferences */
+			preferences?: {
+				newsletter?: boolean
+				product_updates?: boolean
+				promotions?: boolean
+				changelog?: boolean
+				security_alerts?: boolean
+			}
+		}
+		NewsletterVerifyResponse: {
+			success: boolean
+			/** @description Human-readable result message */
+			message: string
+			/**
+			 * Format: email
+			 * @description Verified email address
+			 */
+			email: string
+		}
+		NewsletterVerifyRequest: {
+			/** @description Verification token from email */
+			token: string
+		}
+		NewsletterUnsubscribeResponse: {
+			success: boolean
+			/** @description Human-readable result message */
+			message: string
+			/**
+			 * Format: email
+			 * @description Unsubscribed email address
+			 */
+			email: string
+		}
+		NewsletterUnsubscribeRequest: {
+			/**
+			 * Format: email
+			 * @description Email to unsubscribe
+			 */
+			email: string
+			/** @description Unsubscribe token from email */
+			token: string
+		}
+		NewsletterResendVerificationResponse: {
+			success: boolean
+			/** @description Human-readable result message */
+			message: string
+		}
+		NewsletterResendVerificationRequest: {
+			/**
+			 * Format: email
+			 * @description Email to resend verification to
+			 */
+			email: string
+		}
+		NewsletterUnsubscribeInfoResponse: {
+			/**
+			 * Format: email
+			 * @description Subscriber email
+			 */
+			email: string
+			/** @description Subscriber name */
+			name: string | null
+			/**
+			 * Format: date-time
+			 * @description When subscription was confirmed
+			 */
+			subscribedAt: string | null
+		}
+		NewsletterPreferences: {
+			/** @description Newsletter preference */
+			newsletter: boolean
+			/** @description Product updates preference */
+			product_updates: boolean
+			/** @description Promotions preference */
+			promotions: boolean
+			/** @description Changelog preference */
+			changelog: boolean
+			/** @description Security alerts preference */
+			security_alerts: boolean
+		}
+		NewsletterUpdatePreferencesResponse: {
+			success: boolean
+			preferences: components['schemas']['NewsletterPreferences'] & unknown
+		}
+		NewsletterUpdatePreferencesRequest: {
+			/**
+			 * Format: email
+			 * @description Subscriber email
+			 */
+			email: string
+			/** @description Preferences to update */
+			preferences: {
+				newsletter?: boolean
+				product_updates?: boolean
+				promotions?: boolean
+				changelog?: boolean
+				security_alerts?: boolean
+			}
+		}
+		WebhookConfigResponse: {
+			environments: components['schemas']['WebhookEnvironmentConfig'][]
+			supportedEvents: string[]
+		}
+		WebhookEnvironmentConfig: {
+			/** Format: uuid */
+			id: string
+			name: string
+			/** Format: uri */
+			webhookUrl: string | null
+			hasSecret: boolean
+			/** Format: date-time */
+			updatedAt: string | null
+		}
+		UpdateWebhookConfigResponse: {
+			success: boolean
+			/** Format: uri */
+			webhookUrl: string | null
+			secretGenerated: boolean
+			/** @description Only returned on initial setup or regeneration */
+			webhookSecret?: string
+		}
+		UpdateWebhookConfigRequest: {
+			/** Format: uuid */
+			environmentId: string
+			/** Format: uri */
+			webhookUrl: string | null
+			/** @default false */
+			regenerateSecret: boolean
+		}
+		ListWebhookDeliveriesResponse: {
+			deliveries: components['schemas']['WebhookDelivery'][]
+			total: number
+			limit: number
+			offset: number
+		}
+		WebhookDelivery: {
+			/** Format: uuid */
+			id: string
+			event: string
+			url: string
+			/** @enum {string} */
+			status: 'pending' | 'queued' | 'delivered' | 'failed'
+			retryCount: number
+			responseStatus: number | null
+			error: string | null
+			/** Format: date-time */
+			createdAt: string
+			/** Format: date-time */
+			queuedAt: string | null
+			/** Format: date-time */
+			deliveredAt: string | null
+			/** Format: date-time */
+			failedAt: string | null
+		}
+		ReplayDeliveryResponse: {
+			success: boolean
+			/** Format: uuid */
+			newDeliveryId?: string
+			messageId?: string
+		}
+		WebhookStatsResponse: {
+			/** @enum {string} */
+			period: 'day' | 'week' | 'month'
+			totals: {
+				total: number
+				delivered: number
+				failed: number
+				pending: number
+				/** @description Percentage formatted as string (e.g., "95.5%") */
+				deliveryRate: string
+			}
+			byEvent: {
+				event: string
+				count: number
+			}[]
+			byStatus: {
+				/** @enum {string} */
+				status: 'pending' | 'queued' | 'delivered' | 'failed'
+				count: number
+			}[]
+		}
+		TwoFactorSetupResponse: {
+			/** @description TOTP secret key */
+			secret: string
+			/** @description TOTP URI for QR code generation */
+			uri: string
+			/** @description Base64 encoded QR code image */
+			qrCode?: string
+		}
+		Security2FAVerifyResponse: {
+			success: boolean
+			/** @description One-time backup codes */
+			backupCodes: string[]
+		}
+		Security2FAVerifyRequest: {
+			/** @description 6-digit TOTP code */
+			code: string
+		}
+		Security2FADisableResponse: {
+			success: boolean
+		}
+		BackupCodesResponse: {
+			/** @description Remaining unused backup codes */
+			codes: string[]
+			/** @description Number of remaining codes */
+			count: number
+		}
+		BackupCodesRegenerateResponse: {
+			/** @description New backup codes */
+			codes: string[]
+		}
+		SetPasswordRequest: {
+			/** @description New password */
+			password: string
+		}
+		EmailChangeResponse: {
+			success: boolean
+			message: string
+			/**
+			 * Format: date-time
+			 * @description When the verification link expires
+			 */
+			expiresAt: string
+		}
+		EmailChangeRequest: {
+			/**
+			 * Format: email
+			 * @description New email address
+			 */
+			newEmail: string
+		}
+		EmailChangeConfirmResponse: {
+			success: boolean
+			/**
+			 * Format: email
+			 * @description The new email address
+			 */
+			newEmail: string
+		}
+		EmailChangeConfirmRequest: {
+			/** @description Verification token from email */
+			token: string
+		}
+		PasskeysListResponse: {
+			passkeys: components['schemas']['Passkey'][]
+		}
+		Passkey: {
+			/** Format: uuid */
+			id: string
+			name: string | null
+			/** Format: date-time */
+			createdAt: string
+			/** Format: date-time */
+			lastUsedAt: string | null
+		}
+		PasskeyRegistrationOptions: {
+			challenge: string
+			rp: {
+				name: string
+				id: string
+			}
+			user: {
+				id: string
+				name: string
+				displayName: string
+			}
+			pubKeyCredParams: {
+				/** @enum {string} */
+				type: 'public-key'
+				alg: number
+			}[]
+			timeout?: number
+			attestation?: string
+			excludeCredentials?: {
+				/** @enum {string} */
+				type: 'public-key'
+				id: string
+			}[]
+			authenticatorSelection?: {
+				authenticatorAttachment?: string
+				requireResidentKey?: boolean
+				residentKey?: string
+				userVerification?: string
+			}
+		} & {
+			[key: string]: unknown
+		}
+		PasskeyRegisterVerifyResponse: {
+			/** Format: uuid */
+			id: string
+			name: string | null
+			/** Format: date-time */
+			createdAt: string
+		}
+		PasskeyRegisterVerifyRequest: {
+			/** @description WebAuthn RegistrationResponseJSON */
+			credential?: unknown
+			/** @description Optional device name */
+			deviceName?: string
+		}
+		PasskeyRenameRequest: {
+			name: string
+		}
+		OAuthDisconnectResponse: {
+			success: boolean
+		}
+		OAuthDisconnectRequest: {
+			/** @description OAuth provider name (e.g., google, github) */
+			provider: string
+		}
+		SecurityScore: {
+			/** @description Overall security score */
+			score: number
+			/**
+			 * @description Security level
+			 * @enum {string}
+			 */
+			level: 'critical' | 'low' | 'medium' | 'high' | 'excellent'
+			/** @description Individual security factors */
+			factors: {
+				name: string
+				enabled: boolean
+				weight: number
+				description: string
+			}[]
+			/** @description Recommended security improvements */
+			recommendations: {
+				/** @enum {string} */
+				priority: 'high' | 'medium' | 'low'
+				title: string
+				description: string
+				action?: string
+			}[]
+		}
+		ChallengeVerifyResponse: {
+			verified: boolean
+			/** @enum {string} */
+			method: 'password' | 'email' | 'totp' | 'backup'
+			/**
+			 * @description Type of verification completed
+			 * @enum {string}
+			 */
+			type: 'identity' | 'mfa'
+		}
+		ChallengeVerifyRequest: {
+			/**
+			 * @description Verification method
+			 * @enum {string}
+			 */
+			method: 'password' | 'email' | 'totp' | 'backup'
+			/** @description Verification value (password, code, etc.) */
+			value: string
+		}
+	}
+	responses: never
+	parameters: never
+	requestBodies: never
+	headers: never
+	pathItems: never
+}
+
+/**
+ * Auth Functions
+ *
+ * Pure functions for authentication - no hidden state.
+ * Each function takes config as the first parameter.
+ *
+ * Uses REST API at /api/sdk/auth/* for all operations.
+ *
+ * Types are derived from the OpenAPI spec (generated/api.d.ts).
+ * Run `bun run generate:types:local` to regenerate after API changes.
+ */
+
+type TokenResponse = components['schemas']['TokenResponse'];
+
+/**
+ * Platform SDK Types
+ *
+ * Type definitions for the SDK. API types are generated from OpenAPI spec (ADR-007).
+ * SDK-specific types for React layer and internal use are defined here.
+ *
+ * ## Type Sources (ADR-007)
+ *
+ * | Source | Example | When to Use |
+ * |--------|---------|-------------|
+ * | `generated/api.d.ts` | `LoginRequest`, `Plan` | All API request/response types |
+ * | SDK modules | `SessionResult`, `FlagContext` | SDK-specific types |
+ * | `types.ts` | `AppConfig`, `AIMessage` | Shared/React layer types |
+ *
+ * ## Naming Conventions (Generated Types)
+ *
+ * | Suffix | Purpose | Example |
+ * |--------|---------|---------|
+ * | `Request` | API request payloads | `LoginRequest`, `CheckoutRequest` |
+ * | `Response` | API response payloads | `LoginResponse`, `TokenResponse` |
+ * | (none) | Domain objects | `Plan`, `Subscription`, `User` |
+ *
+ * ## Naming Conventions (SDK Types)
+ *
+ * | Suffix | Purpose | Example |
+ * |--------|---------|---------|
+ * | `Result` | SDK function return (non-API) | `SessionResult` |
+ * | `Options` | Optional function parameters | `FileUploadOptions`, `RevokeTokenOptions` |
+ * | `Config` | Runtime configuration | `SylphxConfig`, `AppConfig` |
+ *
+ * ## Sdk* Prefix (services-context.ts)
+ *
+ * Types prefixed with `Sdk` (e.g., `SdkUserProfile`) are SDK internal representations
+ * with Date objects instead of ISO strings. API types use strings, SDK transforms to Date.
+ */
+
+/**
+ * Base user type for SDK operations.
+ *
+ * Used in:
+ * - Token responses (login, refresh)
+ * - Cookie data for client hydration
+ * - Basic user state in React context
+ *
+ * For authenticated user with security fields (twoFactorEnabled),
+ * see AuthUser in services-context.ts.
+ */
+/**
+ * User type - compatible with generated User from API
+ *
+ * Note: `image` is optional to match generated type.
+ * Extra fields (role, createdAt) are SDK extensions for internal use.
+ */
+interface User {
+    id: string;
+    email: string;
+    name: string | null;
+    image?: string | null;
+    emailVerified: boolean;
+    role?: string;
+    createdAt?: string;
+}
+/**
+ * User cookie data (JS-readable for client hydration)
+ *
+ * Single Source of Truth for the user cookie shape.
+ * Used by both server-side (nextjs/cookies.ts) and client-side (react/storage-utils.ts).
+ *
+ * Note: This contains NO sensitive data.
+ * Tokens are stored separately in HttpOnly cookies.
+ */
+interface UserCookieData {
+    user: User;
+    /** Timestamp when session expires (for client-side expiry check) */
+    expiresAt: number;
+}
+
+/**
+ * Server-side Auth Helpers for Next.js
+ *
+ * Use in Server Components and API Routes.
+ *
+ * Architecture: Cookie-Centric Single Source of Truth
+ * ===================================================
+ *
+ * All auth state lives in cookies. The auth() function reads
+ * from HttpOnly cookies and refreshes if needed.
+ *
+ * Cookie Structure:
+ * - __sylphx_{namespace}_session  — HttpOnly JWT (5 min)
+ * - __sylphx_{namespace}_refresh  — HttpOnly refresh token (30 days)
+ * - __sylphx_{namespace}_user     — JS-readable user data (5 min)
+ */
+
+/**
+ * Configure the SDK for server-side usage
+ *
+ * NOTE: This is optional! The SDK auto-configures from environment variables:
+ * - SYLPHX_SECRET_KEY (required)
+ * - SYLPHX_PLATFORM_URL (optional, defaults to https://sylphx.com)
+ *
+ * Use this only if you need to override the default configuration.
+ *
+ * @example
+ * ```ts
+ * // Optional: Override default configuration
+ * import { configureServer } from '@sylphx/sdk/nextjs'
+ *
+ * configureServer({
+ *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ *   platformUrl: 'https://custom.sylphx.com',
+ * })
+ * ```
+ */
+declare function configureServer(config: {
+    secretKey: string;
+    platformUrl?: string;
+}): void;
+/**
+ * Auth state returned by auth()
+ */
+interface AuthResult {
+    userId: string | null;
+    user: User | null;
+    /** Session token (for internal use only - not exposed to client) */
+    sessionToken: string | null;
+}
+/**
+ * Get the current auth state (memoized per request)
+ *
+ * This is the primary way to check authentication in Server Components.
+ * It reads from HttpOnly cookies and refreshes if needed.
+ *
+ * @example
+ * ```ts
+ * // In a Server Component
+ * import { auth } from '@sylphx/platform-sdk/nextjs'
+ *
+ * export default async function Dashboard() {
+ *   const { userId, user } = await auth()
+ *
+ *   if (!userId) {
+ *     redirect('/login')
+ *   }
+ *
+ *   return <div>Hello, {user?.name}</div>
+ * }
+ * ```
+ */
+declare const auth: () => Promise<AuthResult>;
+/**
+ * Get the current user (null if not logged in)
+ *
+ * @example
+ * ```ts
+ * import { currentUser } from '@sylphx/platform-sdk/nextjs'
+ *
+ * export default async function Header() {
+ *   const user = await currentUser()
+ *   if (!user) return <SignIn />
+ *   return <span>Hello, {user.name}</span>
+ * }
+ * ```
+ */
+declare function currentUser(): Promise<User | null>;
+/**
+ * Get the current user ID (null if not logged in)
+ */
+declare function currentUserId(): Promise<string | null>;
+/**
+ * Handle OAuth callback - exchange code for tokens and set cookies
+ *
+ * NOTE: With createSylphxMiddleware(), this is handled automatically.
+ * You don't need to create manual /api/auth/* routes.
+ *
+ * This function is exported for advanced use cases where you need
+ * custom callback handling outside of the middleware flow.
+ *
+ * @example
+ * ```ts
+ * // Using middleware (recommended - zero manual routes)
+ * import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
+ * export default createSylphxMiddleware({ publicRoutes: ['/', '/about'] })
+ *
+ * // Middleware automatically handles /auth/callback
+ * ```
+ */
+declare function handleCallback(code: string): Promise<User>;
+/**
+ * Sign out - clear cookies and optionally revoke token
+ *
+ * NOTE: With createSylphxMiddleware(), signout is handled automatically
+ * at /auth/signout. No manual route needed.
+ *
+ * This function is exported for advanced use cases.
+ *
+ * @example
+ * ```ts
+ * // Using middleware (recommended)
+ * // Navigate users to /auth/signout - middleware handles everything
+ * <a href="/auth/signout">Sign Out</a>
+ * ```
+ */
+declare function signOut(): Promise<void>;
+/**
+ * Sync tokens to cookies (server action)
+ *
+ * NOTE: With createSylphxMiddleware(), OAuth callbacks are handled
+ * automatically at /auth/callback. This function is rarely needed.
+ *
+ * Use only for edge cases like custom OAuth providers not going
+ * through the standard flow.
+ */
+declare function syncAuthToCookies(tokens: TokenResponse): Promise<void>;
+/**
+ * Get authorization URL for OAuth redirect
+ */
+declare function getAuthorizationUrl(options?: {
+    redirectUri?: string;
+    mode?: 'login' | 'signup';
+    state?: string;
+    appId?: string;
+}): string;
+/**
+ * Get the current session token for API calls
+ *
+ * This is for apps that need to call third-party APIs with the session token.
+ * For same-origin API calls, cookies are sent automatically.
+ *
+ * @example
+ * ```ts
+ * // In an API route that needs to call external APIs
+ * import { getSessionToken } from '@sylphx/platform-sdk/nextjs'
+ *
+ * export async function GET() {
+ *   const token = await getSessionToken()
+ *   if (!token) {
+ *     return new Response('Unauthorized', { status: 401 })
+ *   }
+ *
+ *   // Call third-party API
+ *   const response = await fetch('https://api.example.com/data', {
+ *     headers: { Authorization: `Bearer ${token}` }
+ *   })
+ *   // ...
+ * }
+ * ```
+ */
+declare function getSessionToken(): Promise<string | null>;
+
+/**
+ * Token expiry buffer in milliseconds (30 seconds)
+ *
+ * Refresh tokens this many milliseconds BEFORE they expire
+ * to account for network latency and clock skew.
+ */
+declare const TOKEN_EXPIRY_BUFFER_MS = 30000;
+/** Session token lifetime in milliseconds (for React Query staleTime) */
+declare const SESSION_TOKEN_LIFETIME_MS: number;
+
+/**
+ * Cookie Management for Next.js — Single Source of Truth
+ *
+ * Architecture: Cookie-Centric Auth (Clerk Pattern)
+ * ================================================
+ *
+ * ALL auth state lives in cookies. Zero localStorage for auth.
+ *
+ * Cookie Structure:
+ * - __sylphx_{namespace}_session  — HttpOnly JWT, 5 min (access token)
+ * - __sylphx_{namespace}_refresh  — HttpOnly, 30 days (refresh token)
+ * - __sylphx_{namespace}_user     — JS-readable, 5 min (user data for client hydration)
+ *
+ * Benefits:
+ * 1. Single Source of Truth — no server/client state divergence
+ * 2. XSS-safe — tokens never accessible to JavaScript
+ * 3. Cross-tab sync — cookies shared across tabs automatically
+ * 4. SSR works — auth() in Server Components reads cookies directly
+ *
+ * Security:
+ * - Short token lifetime (5 min) like Clerk
+ * - Server-side refresh in middleware
+ * - SameSite=Lax for CSRF protection
+ */
+
+/**
+ * Get cookie names for a given namespace
+ *
+ * Namespace is derived from the secret key environment (dev/stg/prod).
+ * This prevents cookies from different environments colliding.
+ *
+ * @example
+ * getCookieNames('sylphx_prod')
+ * // Returns:
+ * // {
+ * //   SESSION: '__sylphx_prod_session',
+ * //   REFRESH: '__sylphx_prod_refresh',
+ * //   USER: '__sylphx_prod_user',
+ * // }
+ */
+declare function getCookieNames(namespace: string): {
+    /** HttpOnly JWT access token (5 min) */
+    SESSION: string;
+    /** HttpOnly refresh token (30 days) */
+    REFRESH: string;
+    /** JS-readable user data for client hydration (5 min) */
+    USER: string;
+};
+/**
+ * Session token lifetime (5 minutes like Clerk)
+ */
+declare const SESSION_TOKEN_LIFETIME: number;
+/**
+ * Refresh token lifetime (30 days)
+ */
+declare const REFRESH_TOKEN_LIFETIME: number;
+/**
+ * Cookie options for HttpOnly tokens (session, refresh)
+ *
+ * Security features:
+ * - httpOnly: true — Not accessible via JavaScript (XSS protection)
+ * - secure: true in production — Only sent over HTTPS
+ * - sameSite: 'lax' — CSRF protection while allowing navigation
+ */
+declare const SECURE_COOKIE_OPTIONS: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+};
+/**
+ * Cookie options for JS-readable user cookie
+ *
+ * This cookie contains only user info (no tokens) and enables:
+ * - Client-side hydration without loading states
+ * - Cross-tab sync via cookie visibility
+ */
+declare const USER_COOKIE_OPTIONS: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+};
+/**
+ * Auth cookies data returned by getAuthCookies
+ */
+interface AuthCookiesData {
+    /** Access token from SESSION cookie (HttpOnly) */
+    sessionToken: string | null;
+    /** Refresh token from REFRESH cookie (HttpOnly) */
+    refreshToken: string | null;
+    /** User data from USER cookie (JS-readable) */
+    user: User | null;
+    /** Expiry timestamp from USER cookie */
+    expiresAt: number | null;
+}
+/**
+ * Get auth cookies from the request
+ *
+ * Used by auth() to read current auth state.
+ */
+declare function getAuthCookies(namespace: string): Promise<AuthCookiesData>;
+/**
+ * Set auth cookies from token response
+ *
+ * Sets all three cookies:
+ * - SESSION: HttpOnly access token (5 min)
+ * - REFRESH: HttpOnly refresh token (30 days)
+ * - USER: JS-readable user data (5 min)
+ *
+ * @param namespace - Cookie namespace (e.g., 'sylphx_prod')
+ * @param response - Token response from auth endpoint
+ * @param options - Optional: custom expiresIn override
+ */
+declare function setAuthCookies(namespace: string, response: TokenResponse, options?: {
+    sessionLifetime?: number;
+}): Promise<void>;
+/**
+ * Clear all auth cookies
+ *
+ * Call on sign out to remove all auth state.
+ */
+declare function clearAuthCookies(namespace: string): Promise<void>;
+/**
+ * Check if session is expired
+ *
+ * Uses a 30 second buffer to account for network latency.
+ */
+declare function isSessionExpired(namespace: string): Promise<boolean>;
+/**
+ * Check if we have a refresh token (can potentially refresh)
+ */
+declare function hasRefreshToken(namespace: string): Promise<boolean>;
+
+/**
+ * Set auth cookies on a NextResponse (for middleware use)
+ *
+ * Unlike setAuthCookies() which uses next/headers, this works with NextResponse.
+ * Use this in middleware where you need to modify cookies on the response.
+ */
+declare function setAuthCookiesMiddleware(response: NextResponse, namespace: string, tokens: TokenResponse): void;
+/**
+ * Clear auth cookies on a NextResponse (for middleware use)
+ */
+declare function clearAuthCookiesMiddleware(response: NextResponse, namespace: string): void;
+/**
+ * Parse user cookie value (for client-side use)
+ */
+declare function parseUserCookie(value: string): UserCookieData | null;
+
+export { type AuthCookiesData, type AuthResult, REFRESH_TOKEN_LIFETIME, SECURE_COOKIE_OPTIONS, SESSION_TOKEN_LIFETIME, SESSION_TOKEN_LIFETIME_MS, type SylphxMiddlewareConfig, TOKEN_EXPIRY_BUFFER_MS, USER_COOKIE_OPTIONS, type UserCookieData, auth, clearAuthCookies, clearAuthCookiesMiddleware, configureServer, createMatcher, createSylphxMiddleware, currentUser, currentUserId, getAuthCookies, getAuthorizationUrl, getCookieNames, getNamespace, getSessionToken, handleCallback, hasRefreshToken, isSessionExpired, parseUserCookie, setAuthCookies, setAuthCookiesMiddleware, signOut, syncAuthToCookies };