@prabhask5/stellar-engine 1.1.7 → 1.1.8

package/dist/kit/loads.d.ts

@@ -1,46 +1,147 @@
 /**
  * @fileoverview SvelteKit load function helpers.
  *
- * Extracts orchestration logic from layout/page load functions so
- * scaffolded routes can be thin wrappers around these helpers.
+ * This module extracts orchestration logic from layout and page load functions
+ * so that scaffolded routes can be thin wrappers around these helpers. Each
+ * exported function encapsulates a specific load concern:
+ *
+ *   - `resolveRootLayout`      — full app initialization sequence (config,
+ *                                 auth, sync engine startup)
+ *   - `resolveProtectedLayout` — auth guard for protected route groups
+ *   - `resolveSetupAccess`     — access control for the `/setup` wizard
+ *
+ * By centralizing this logic in the engine, consuming apps avoid duplicating
+ * the initialization ordering and redirect logic across their route tree.
+ *
+ * @module kit/loads
+ *
+ * @example
+ * ```ts
+ * // In +layout.ts (root)
+ * import { resolveRootLayout } from 'stellar-engine/kit/loads';
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link initConfig} for runtime configuration bootstrap
+ * @see {@link resolveAuthState} for auth mode determination
+ * @see {@link startSyncEngine} for offline-first sync initialization
  */
 import type { AuthStateResult } from '../auth/resolveAuthState.js';
-/** Data returned by `resolveRootLayout`. */
+/**
+ * Data returned by `resolveRootLayout`.
+ *
+ * Extends the base auth state with an optional `singleUserSetUp` flag
+ * indicating whether the app has completed initial configuration.
+ */
 export interface RootLayoutData extends AuthStateResult {
+    /**
+     * Indicates whether the single-user setup wizard has been completed.
+     * When `false` and no config exists, the app should redirect to `/setup`.
+     */
     singleUserSetUp?: boolean;
 }
-/** Data returned by `resolveProtectedLayout`. */
+/**
+ * Data returned by `resolveProtectedLayout`.
+ *
+ * A narrowed subset of auth state fields needed by protected route groups
+ * to render authenticated content.
+ */
 export interface ProtectedLayoutData {
+    /** The Supabase session, or `null` if using offline/no auth. */
     session: AuthStateResult['session'];
+    /** The active authentication mode discriminator. */
     authMode: AuthStateResult['authMode'];
+    /** The offline profile credentials, if in offline mode. */
     offlineProfile: AuthStateResult['offlineProfile'];
 }
-/** Data returned by `resolveSetupAccess`. */
+/**
+ * Data returned by `resolveSetupAccess`.
+ *
+ * Tells the setup page whether this is a first-time configuration
+ * (public access) or a reconfiguration (admin-only).
+ */
 export interface SetupAccessData {
+    /**
+     * `true` when no configuration exists yet — the setup page should
+     * render the full first-time wizard without requiring authentication.
+     */
     isFirstSetup: boolean;
 }
 /**
- * Orchestrates the root layout load sequence:
- *  1. Calls the app's `initEngine` function (for database schema setup)
- *  2. Runs `initConfig()` — redirects to `/setup` if unconfigured
- *  3. Resolves auth state
- *  4. Starts sync engine if authenticated
- *
- * @param initEngineFn - The app's `initEngine()` call (executed before config init).
- *                       Should already have been called at module scope in the browser.
- * @param url          - The current page URL (for setup redirect check).
- * @returns Layout data with session, auth mode, offline profile, and setup status.
+ * Orchestrates the root layout load sequence, which is the critical
+ * initialization path that runs on every page load:
+ *
+ *   1. Calls the app's `initEngine` function (for database schema setup)
+ *   2. Runs `initConfig()` — loads runtime config from storage; if no
+ *      config exists and the user is not already on `/setup`, returns a
+ *      blank state so the layout can redirect to the setup wizard
+ *   3. Resolves auth state — determines whether the user is authenticated
+ *      via Supabase, offline credentials, or not at all
+ *   4. Starts the sync engine if the user is authenticated, enabling
+ *      offline-first data synchronization
+ *
+ * @param url          - The current page URL object. Only `pathname` is
+ *                       inspected, to detect whether the user is already
+ *                       on the `/setup` page.
+ * @param _initEngineFn - (Optional) The app's `initEngine()` call, executed
+ *                        before config init. Typically already called at
+ *                        module scope in the browser; this parameter exists
+ *                        for explicit invocation in SSR contexts.
+ *
+ * @returns Layout data containing session, auth mode, offline profile,
+ *          and setup status. The consuming layout uses these to hydrate
+ *          the auth store and conditionally render the app shell.
+ *
+ * @example
+ * ```ts
+ * // +layout.ts
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link RootLayoutData} for the return type shape
+ * @see {@link initConfig} for config bootstrapping details
+ * @see {@link resolveAuthState} for auth resolution logic
  */
 export declare function resolveRootLayout(url: {
     pathname: string;
 }, _initEngineFn?: () => void): Promise<RootLayoutData>;
 /**
- * Auth guard for protected routes. Resolves auth state and returns
- * redirect info if unauthenticated.
+ * Auth guard for protected routes. Resolves auth state and, if the user
+ * is unauthenticated, computes a redirect URL to the login page with a
+ * `redirect` query parameter so the user can be sent back after login.
+ *
+ * The caller is responsible for performing the actual redirect (typically
+ * via SvelteKit's `throw redirect(302, redirectUrl)`), since this helper
+ * is framework-agnostic in its return value.
+ *
+ * @param url - The current page URL object with `pathname` and `search`
+ *              properties, used to construct the post-login return URL.
  *
- * @param url - The current page URL (for building redirect parameter).
- * @returns Auth data, or `null` if a redirect to `/login` is needed.
- *          When null, caller should `throw redirect(302, loginUrl)`.
+ * @returns An object containing:
+ *   - `data` — the auth state payload for the layout
+ *   - `redirectUrl` — a login URL string if unauthenticated, or `null`
+ *     if the user is authenticated and should proceed normally.
+ *     When non-null, the caller should `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /(protected)/+layout.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveProtectedLayout } from 'stellar-engine/kit/loads';
+ *
+ * export async function load({ url }) {
+ *   const { data, redirectUrl } = await resolveProtectedLayout(url);
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
+ *
+ * @see {@link ProtectedLayoutData} for the return data shape
+ * @see {@link resolveAuthState} for the underlying auth resolution
  */
 export declare function resolveProtectedLayout(url: {
     pathname: string;
@@ -50,10 +151,36 @@ export declare function resolveProtectedLayout(url: {
     redirectUrl: string | null;
 }>;
 /**
- * Setup page guard: if unconfigured → public access; if configured → admin-only.
+ * Setup page guard implementing a two-tier access model:
+ *
+ *   - **Unconfigured app** (first-time setup): public access, no auth required.
+ *     Returns `{ isFirstSetup: true }`.
+ *   - **Configured app** (reconfiguration): only authenticated admin users
+ *     may access. Non-admins are redirected to `/`, unauthenticated users
+ *     to `/login`.
+ *
+ * @returns An object containing:
+ *   - `data` — setup access info (`{ isFirstSetup }`)
+ *   - `redirectUrl` — a redirect path if the user lacks access, or `null`
+ *     if access is granted. When non-null, the caller should
+ *     `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /setup/+page.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveSetupAccess } from 'stellar-engine/kit/loads';
+ *
+ * export async function load() {
+ *   const { data, redirectUrl } = await resolveSetupAccess();
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
  *
- * @returns `{ isFirstSetup }` with access info, or `null` with a redirectUrl
- *          if the user should be redirected away.
+ * @see {@link SetupAccessData} for the return data shape
+ * @see {@link getConfig} for checking whether config exists
+ * @see {@link isAdmin} for admin role verification
  */
 export declare function resolveSetupAccess(): Promise<{
     data: SetupAccessData;

package/dist/kit/loads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loads.d.ts","sourceRoot":"","sources":["../../src/kit/loads.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAMnE,4CAA4C;AAC5C,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IACpC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACtC,cAAc,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,OAAO,CAAC;CACvB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EACzB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,OAAO,CAAC,cAAc,CAAC,CAsBzB;AAMD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAarE;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAgBD"}
+{"version":3,"file":"loads.d.ts","sourceRoot":"","sources":["../../src/kit/loads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAMnE;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAEpC,oDAAoD;IACpD,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IAEtC,2DAA2D;IAC3D,cAAc,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EACzB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,OAAO,CAAC,cAAc,CAAC,CA4BzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAgBrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAsBD"}

package/dist/kit/loads.js

@@ -1,8 +1,32 @@
 /**
  * @fileoverview SvelteKit load function helpers.
  *
- * Extracts orchestration logic from layout/page load functions so
- * scaffolded routes can be thin wrappers around these helpers.
+ * This module extracts orchestration logic from layout and page load functions
+ * so that scaffolded routes can be thin wrappers around these helpers. Each
+ * exported function encapsulates a specific load concern:
+ *
+ *   - `resolveRootLayout`      — full app initialization sequence (config,
+ *                                 auth, sync engine startup)
+ *   - `resolveProtectedLayout` — auth guard for protected route groups
+ *   - `resolveSetupAccess`     — access control for the `/setup` wizard
+ *
+ * By centralizing this logic in the engine, consuming apps avoid duplicating
+ * the initialization ordering and redirect logic across their route tree.
+ *
+ * @module kit/loads
+ *
+ * @example
+ * ```ts
+ * // In +layout.ts (root)
+ * import { resolveRootLayout } from 'stellar-engine/kit/loads';
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link initConfig} for runtime configuration bootstrap
+ * @see {@link resolveAuthState} for auth mode determination
+ * @see {@link startSyncEngine} for offline-first sync initialization
  */
 import { initConfig, getConfig } from '../runtime/runtimeConfig.js';
 import { resolveAuthState } from '../auth/resolveAuthState.js';
@@ -13,30 +37,61 @@ import { isAdmin } from '../auth/admin.js';
 //  ROOT LAYOUT
 // =============================================================================
 /**
- * Orchestrates the root layout load sequence:
- *  1. Calls the app's `initEngine` function (for database schema setup)
- *  2. Runs `initConfig()` — redirects to `/setup` if unconfigured
- *  3. Resolves auth state
- *  4. Starts sync engine if authenticated
- *
- * @param initEngineFn - The app's `initEngine()` call (executed before config init).
- *                       Should already have been called at module scope in the browser.
- * @param url          - The current page URL (for setup redirect check).
- * @returns Layout data with session, auth mode, offline profile, and setup status.
+ * Orchestrates the root layout load sequence, which is the critical
+ * initialization path that runs on every page load:
+ *
+ *   1. Calls the app's `initEngine` function (for database schema setup)
+ *   2. Runs `initConfig()` — loads runtime config from storage; if no
+ *      config exists and the user is not already on `/setup`, returns a
+ *      blank state so the layout can redirect to the setup wizard
+ *   3. Resolves auth state — determines whether the user is authenticated
+ *      via Supabase, offline credentials, or not at all
+ *   4. Starts the sync engine if the user is authenticated, enabling
+ *      offline-first data synchronization
+ *
+ * @param url          - The current page URL object. Only `pathname` is
+ *                       inspected, to detect whether the user is already
+ *                       on the `/setup` page.
+ * @param _initEngineFn - (Optional) The app's `initEngine()` call, executed
+ *                        before config init. Typically already called at
+ *                        module scope in the browser; this parameter exists
+ *                        for explicit invocation in SSR contexts.
+ *
+ * @returns Layout data containing session, auth mode, offline profile,
+ *          and setup status. The consuming layout uses these to hydrate
+ *          the auth store and conditionally render the app shell.
+ *
+ * @example
+ * ```ts
+ * // +layout.ts
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link RootLayoutData} for the return type shape
+ * @see {@link initConfig} for config bootstrapping details
+ * @see {@link resolveAuthState} for auth resolution logic
  */
 export async function resolveRootLayout(url, _initEngineFn) {
     const config = await initConfig();
-    // No config yet → first-time user, redirect to setup wizard
+    /* No config yet — this is a first-time user. Return blank state so the
+       layout can detect `singleUserSetUp === false` and redirect to /setup.
+       We skip the redirect if already on /setup to avoid an infinite loop. */
     if (!config && url.pathname !== '/setup') {
         return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
     }
-    // Still on setup page with no config — return blank state
+    /* Still on setup page with no config — return blank state without
+       redirecting, allowing the setup wizard to render normally. */
     if (!config) {
         return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
     }
-    // Resolve auth — determines Supabase / offline / none
+    /* Resolve auth — determines Supabase / offline / none based on the
+       stored runtime config and available credentials. */
     const result = await resolveAuthState();
-    // Start sync engine only when the user is actually authenticated
+    /* Start sync engine only when the user is actually authenticated;
+       the engine requires auth context to connect to the remote database
+       or initialize the local-first storage layer. */
     if (result.authMode !== 'none') {
         await startSyncEngine();
     }
@@ -46,16 +101,45 @@ export async function resolveRootLayout(url, _initEngineFn) {
 //  PROTECTED LAYOUT
 // =============================================================================
 /**
- * Auth guard for protected routes. Resolves auth state and returns
- * redirect info if unauthenticated.
+ * Auth guard for protected routes. Resolves auth state and, if the user
+ * is unauthenticated, computes a redirect URL to the login page with a
+ * `redirect` query parameter so the user can be sent back after login.
  *
- * @param url - The current page URL (for building redirect parameter).
- * @returns Auth data, or `null` if a redirect to `/login` is needed.
- *          When null, caller should `throw redirect(302, loginUrl)`.
+ * The caller is responsible for performing the actual redirect (typically
+ * via SvelteKit's `throw redirect(302, redirectUrl)`), since this helper
+ * is framework-agnostic in its return value.
+ *
+ * @param url - The current page URL object with `pathname` and `search`
+ *              properties, used to construct the post-login return URL.
+ *
+ * @returns An object containing:
+ *   - `data` — the auth state payload for the layout
+ *   - `redirectUrl` — a login URL string if unauthenticated, or `null`
+ *     if the user is authenticated and should proceed normally.
+ *     When non-null, the caller should `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /(protected)/+layout.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveProtectedLayout } from 'stellar-engine/kit/loads';
+ *
+ * export async function load({ url }) {
+ *   const { data, redirectUrl } = await resolveProtectedLayout(url);
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
+ *
+ * @see {@link ProtectedLayoutData} for the return data shape
+ * @see {@link resolveAuthState} for the underlying auth resolution
  */
 export async function resolveProtectedLayout(url) {
     const result = await resolveAuthState();
     if (result.authMode === 'none') {
+        /* Build a return URL so the login page can redirect back after
+           successful authentication. Skip the redirect param if the user
+           is at the root — there's no meaningful "return to" destination. */
         const returnUrl = url.pathname + url.search;
         const loginUrl = returnUrl && returnUrl !== '/'
             ? `/login?redirect=${encodeURIComponent(returnUrl)}`
@@ -68,20 +152,52 @@ export async function resolveProtectedLayout(url) {
 //  SETUP ACCESS
 // =============================================================================
 /**
- * Setup page guard: if unconfigured → public access; if configured → admin-only.
+ * Setup page guard implementing a two-tier access model:
+ *
+ *   - **Unconfigured app** (first-time setup): public access, no auth required.
+ *     Returns `{ isFirstSetup: true }`.
+ *   - **Configured app** (reconfiguration): only authenticated admin users
+ *     may access. Non-admins are redirected to `/`, unauthenticated users
+ *     to `/login`.
+ *
+ * @returns An object containing:
+ *   - `data` — setup access info (`{ isFirstSetup }`)
+ *   - `redirectUrl` — a redirect path if the user lacks access, or `null`
+ *     if access is granted. When non-null, the caller should
+ *     `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /setup/+page.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveSetupAccess } from 'stellar-engine/kit/loads';
+ *
+ * export async function load() {
+ *   const { data, redirectUrl } = await resolveSetupAccess();
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
  *
- * @returns `{ isFirstSetup }` with access info, or `null` with a redirectUrl
- *          if the user should be redirected away.
+ * @see {@link SetupAccessData} for the return data shape
+ * @see {@link getConfig} for checking whether config exists
+ * @see {@link isAdmin} for admin role verification
  */
 export async function resolveSetupAccess() {
+    /* No config exists — this is the first-time setup, grant public access
+       so the wizard can run without requiring authentication. */
     if (!getConfig()) {
         return { data: { isFirstSetup: true }, redirectUrl: null };
     }
+    /* Config exists — this is a reconfiguration. Require a valid session. */
     const session = await getValidSession();
     if (!session?.user) {
+        /* No session — redirect to login so the user can authenticate first. */
         return { data: { isFirstSetup: false }, redirectUrl: '/login' };
     }
     if (!isAdmin(session.user)) {
+        /* Authenticated but not an admin — redirect to home. Only admins
+           should be able to change the app's configuration. */
         return { data: { isFirstSetup: false }, redirectUrl: '/' };
     }
     return { data: { isFirstSetup: false }, redirectUrl: null };

package/dist/kit/loads.js.map

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

package/dist/kit/server.d.ts

@@ -1,41 +1,173 @@
 /**
  * @fileoverview Server-side API helpers for SvelteKit route handlers.
  *
- * Extracts reusable backend logic so scaffolded API routes can be thin wrappers.
+ * This module extracts reusable backend logic so scaffolded API routes can be
+ * thin wrappers around these helpers. It provides three main capabilities:
+ *
+ *   - **Server config reading** — reads Supabase credentials from environment
+ *     variables at runtime (`getServerConfig`)
+ *   - **Vercel deployment** — upserts env vars and triggers production
+ *     redeployments via the Vercel REST API (`deployToVercel`)
+ *   - **Credential validation** — factory for a SvelteKit POST handler that
+ *     validates Supabase credentials (`createValidateHandler`)
+ *
+ * All Vercel API interactions use a create-or-update (upsert) strategy for
+ * environment variables, and support both git-based and clone-based
+ * redeployment strategies for maximum compatibility.
+ *
+ * @module kit/server
+ *
+ * @example
+ * ```ts
+ * // In /api/config/+server.ts
+ * import { getServerConfig } from 'stellar-engine/kit/server';
+ * export function GET() {
+ *   return new Response(JSON.stringify(getServerConfig()));
+ * }
+ * ```
+ *
+ * @see {@link https://vercel.com/docs/rest-api} for Vercel API reference
+ * @see {@link validateSupabaseCredentials} in `supabase/validate.ts`
+ */
+/**
+ * Configuration for deploying Supabase credentials to Vercel.
+ *
+ * Contains all the information needed to authenticate with Vercel,
+ * identify the target project, and set the Supabase connection values.
  */
-/** Configuration for deploying Supabase credentials to Vercel. */
 export interface DeployConfig {
+    /** Vercel personal access token or team token for API authentication. */
     vercelToken: string;
+    /** The Vercel project ID (found in project settings). */
     projectId: string;
+    /** The Supabase project URL (e.g. `https://abc.supabase.co`). */
     supabaseUrl: string;
+    /** The Supabase anonymous/public key for client-side access. */
     supabaseAnonKey: string;
 }
-/** Result of a Vercel deployment attempt. */
+/**
+ * Result of a Vercel deployment attempt.
+ *
+ * On success, includes the deployment URL. On failure, includes
+ * the error message from the Vercel API or internal exception.
+ */
 export interface DeployResult {
+    /** Whether the env var upsert and redeployment completed without errors. */
     success: boolean;
+    /**
+     * The Vercel deployment URL for the triggered build.
+     * Only present when `success` is `true` and Vercel returns a URL.
+     */
     deploymentUrl?: string;
+    /**
+     * Error message describing what went wrong.
+     * Only present when `success` is `false`.
+     */
     error?: string;
 }
-/** Server config status returned by `getServerConfig()`. */
+/**
+ * Server config status returned by `getServerConfig()`.
+ *
+ * Indicates whether the required Supabase environment variables are
+ * present in the server's runtime environment.
+ */
 export interface ServerConfig {
+    /** `true` when both `PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY` are set. */
     configured: boolean;
+    /** The Supabase project URL, if configured. */
     supabaseUrl?: string;
+    /** The Supabase anonymous key, if configured. */
     supabaseAnonKey?: string;
 }
 /**
  * Reads Supabase configuration from `process.env` at runtime.
- * Returns `{ configured: true, supabaseUrl, supabaseAnonKey }` when both
- * env vars exist, or `{ configured: false }` otherwise.
+ *
+ * Checks for the presence of both `PUBLIC_SUPABASE_URL` and
+ * `PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY` environment variables.
+ * Returns `{ configured: true }` with the values when both exist,
+ * or `{ configured: false }` otherwise.
+ *
+ * This is intended for use in SvelteKit server routes (e.g. `+server.ts`)
+ * to report configuration status to the client during the setup flow.
+ *
+ * @returns The server config status with optional Supabase credentials.
+ *
+ * @example
+ * ```ts
+ * // In /api/config/+server.ts
+ * import { getServerConfig } from 'stellar-engine/kit/server';
+ * export function GET() {
+ *   return new Response(JSON.stringify(getServerConfig()), {
+ *     headers: { 'Content-Type': 'application/json' }
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link ServerConfig} for the return type shape
  */
 export declare function getServerConfig(): ServerConfig;
 /**
- * Full Vercel deployment flow: upsert env vars, then trigger a production
- * redeployment via git-based or clone-based strategy.
+ * Full Vercel deployment flow: upserts Supabase environment variables,
+ * then triggers a production redeployment.
+ *
+ * The deployment uses a two-strategy approach:
+ *   - **Strategy A (preferred)**: Git-based redeployment using the repo
+ *     metadata from Vercel's environment (`VERCEL_GIT_REPO_SLUG`, etc.).
+ *     This triggers a fresh build from the source branch.
+ *   - **Strategy B (fallback)**: Clone-based redeployment using an existing
+ *     deployment ID (`VERCEL_DEPLOYMENT_ID` or `VERCEL_URL`). This
+ *     reuses the last build artifacts with updated env vars.
+ *
+ * Both strategies target the `production` environment.
+ *
+ * @param config - The deployment configuration containing Vercel auth
+ *                 credentials, project ID, and Supabase connection values.
+ *
+ * @returns A result object indicating success/failure with an optional
+ *          deployment URL or error message.
+ *
+ * @example
+ * ```ts
+ * const result = await deployToVercel({
+ *   vercelToken: 'tok_...',
+ *   projectId: 'prj_...',
+ *   supabaseUrl: 'https://abc.supabase.co',
+ *   supabaseAnonKey: 'eyJ...'
+ * });
+ * if (!result.success) console.error(result.error);
+ * ```
+ *
+ * @see {@link DeployConfig} for the input configuration shape
+ * @see {@link DeployResult} for the return type shape
+ * @see {@link setEnvVar} for the upsert strategy used for env vars
  */
 export declare function deployToVercel(config: DeployConfig): Promise<DeployResult>;
 /**
- * Factory returning a SvelteKit POST handler that validates Supabase credentials.
- * The handler parses the request body and delegates to `validateSupabaseCredentials`.
+ * Factory returning a SvelteKit POST handler that validates Supabase
+ * credentials by attempting to connect to the provided Supabase instance.
+ *
+ * The returned handler:
+ *   1. Parses the JSON request body for `supabaseUrl` and `supabaseAnonKey`
+ *   2. Validates that both fields are present (returns 400 if not)
+ *   3. Delegates to `validateSupabaseCredentials` for the actual check
+ *   4. Returns a JSON response with the validation result
+ *
+ * The `validateSupabaseCredentials` import is dynamic (`await import(...)`)
+ * to keep this module's dependency footprint minimal — the validation logic
+ * and its Supabase client dependency are only loaded when the endpoint is
+ * actually called.
+ *
+ * @returns An async handler function compatible with SvelteKit's
+ *          `RequestHandler` signature for POST endpoints.
+ *
+ * @example
+ * ```ts
+ * // In /api/validate-supabase/+server.ts
+ * import { createValidateHandler } from 'stellar-engine/kit/server';
+ * export const POST = createValidateHandler();
+ * ```
+ *
+ * @see {@link validateSupabaseCredentials} in `supabase/validate.ts`
  */
 export declare function createValidateHandler(): ({ request }: {
     request: Request;

package/dist/kit/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/kit/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA+ED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA+DhF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,KACrB,aAAa;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,KAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/kit/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA6BH;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,UAAU,EAAE,OAAO,CAAC;IAEpB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6GD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAwEhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,KACrB,aAAa;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,KAAG,OAAO,CAAC,QAAQ,CAAC,CA2BpE"}