@sylphx/sdk 0.0.1

package/dist/nextjs/index.d.cts

@@ -0,0 +1,2089 @@
+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>;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+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 };