stellar-drive 1.0.0

package/dist/kit/server.js

@@ -0,0 +1,297 @@
+/**
+ * @fileoverview Server-side API helpers for SvelteKit route handlers.
+ *
+ * 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-drive/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`
+ */
+// =============================================================================
+//  HELPERS — Vercel API Utilities
+// =============================================================================
+/**
+ * Low-level wrapper around the Vercel REST API.
+ *
+ * Handles authentication headers and JSON body serialization for all
+ * Vercel API calls. This is an internal helper — not exported.
+ *
+ * @param path   - The API path (appended to `https://api.vercel.com`).
+ * @param token  - The Vercel bearer token for authorization.
+ * @param method - HTTP method (defaults to `'GET'`).
+ * @param body   - Optional request body, serialized to JSON.
+ *
+ * @returns The raw `Response` from the Vercel API.
+ *
+ * @throws {TypeError} If the `fetch` call itself fails (e.g. network error).
+ */
+async function vercelApi(path, token, method = 'GET', body) {
+    return fetch(`https://api.vercel.com${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: body ? JSON.stringify(body) : undefined
+    });
+}
+/**
+ * Creates or updates a single environment variable on a Vercel project.
+ *
+ * Implements an upsert strategy:
+ *   1. Attempt to create via `POST /v10/projects/:id/env`.
+ *   2. If Vercel returns `ENV_ALREADY_EXISTS`, list all env vars to find
+ *      the existing entry's ID, then patch it with the new value.
+ *
+ * This two-step approach is necessary because Vercel's create endpoint
+ * does not support an "upsert" mode — it always fails if the key exists.
+ *
+ * @param projectId - The Vercel project ID.
+ * @param token     - The Vercel bearer token.
+ * @param key       - The environment variable name to set.
+ * @param value     - The environment variable value.
+ *
+ * @throws {Error} If the create fails for a reason other than already-exists,
+ *                 or if the list/patch fallback also fails.
+ */
+async function setEnvVar(projectId, token, key, value) {
+    const createRes = await vercelApi(`/v10/projects/${projectId}/env`, token, 'POST', {
+        key,
+        value,
+        target: ['production', 'preview', 'development'],
+        type: 'plain'
+    });
+    if (createRes.ok)
+        return;
+    const createData = await createRes.json();
+    const errorCode = createData.error?.code || '';
+    const errorMessage = createData.error?.message || '';
+    /* If the variable already exists, fall through to the update path.
+       Vercel may report this via error code or message text depending
+       on the API version, so we check both. */
+    if (errorCode === 'ENV_ALREADY_EXISTS' || errorMessage.includes('already exists')) {
+        /* List all env vars to find the existing entry's ID — Vercel requires
+           the entry ID for PATCH operations, not the key name. */
+        const listRes = await vercelApi(`/v9/projects/${projectId}/env`, token);
+        if (!listRes.ok) {
+            throw new Error(`Failed to list env vars: ${listRes.statusText}`);
+        }
+        const listData = await listRes.json();
+        const existing = listData.envs?.find((e) => e.key === key);
+        if (existing) {
+            const updateRes = await vercelApi(`/v9/projects/${projectId}/env/${existing.id}`, token, 'PATCH', { value });
+            if (!updateRes.ok) {
+                throw new Error(`Failed to update env var ${key}: ${updateRes.statusText}`);
+            }
+        }
+        else {
+            /* Edge case: Vercel says the var exists but it's not in the list.
+               This can happen with env var scoping issues. */
+            throw new Error(`Env var ${key} reported as existing but not found in list`);
+        }
+    }
+    else {
+        throw new Error(`Failed to create env var ${key}: ${createData.error?.message || createRes.statusText}`);
+    }
+}
+// =============================================================================
+//  PUBLIC API
+// =============================================================================
+/**
+ * Reads Supabase configuration from `process.env` at runtime.
+ *
+ * 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-drive/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 function getServerConfig() {
+    const supabaseUrl = process.env.PUBLIC_SUPABASE_URL || '';
+    const supabaseAnonKey = process.env.PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY || '';
+    if (supabaseUrl && supabaseAnonKey) {
+        return { configured: true, supabaseUrl, supabaseAnonKey };
+    }
+    return { configured: false };
+}
+/**
+ * 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 async function deployToVercel(config) {
+    try {
+        // -------------------------------------------------------------------------
+        //  Phase 1 — Upsert environment variables
+        // -------------------------------------------------------------------------
+        await setEnvVar(config.projectId, config.vercelToken, 'PUBLIC_SUPABASE_URL', config.supabaseUrl);
+        await setEnvVar(config.projectId, config.vercelToken, 'PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY', config.supabaseAnonKey);
+        // -------------------------------------------------------------------------
+        //  Phase 2 — Trigger production redeployment
+        // -------------------------------------------------------------------------
+        const deploymentId = process.env.VERCEL_DEPLOYMENT_ID || process.env.VERCEL_URL;
+        const gitRepo = process.env.VERCEL_GIT_REPO_SLUG;
+        const gitOwner = process.env.VERCEL_GIT_REPO_OWNER;
+        const gitRef = process.env.VERCEL_GIT_COMMIT_REF || 'main';
+        let deploymentUrl = '';
+        /* Strategy A — Git-based redeployment (preferred).
+           Uses the connected GitHub repo to trigger a fresh build from source.
+           Only available when Vercel has git integration metadata. */
+        if (gitRepo && gitOwner) {
+            const deployRes = await vercelApi(`/v13/deployments`, config.vercelToken, 'POST', {
+                name: config.projectId,
+                project: config.projectId,
+                target: 'production',
+                gitSource: {
+                    type: 'github',
+                    repoId: `${gitOwner}/${gitRepo}`,
+                    ref: gitRef
+                }
+            });
+            if (deployRes.ok) {
+                const deployData = await deployRes.json();
+                deploymentUrl = deployData.url || '';
+            }
+        }
+        /* Strategy B — Clone current deployment (fallback).
+           Reuses the most recent deployment's build output with the newly
+           updated env vars. Used when git metadata is unavailable (e.g.
+           manual deploys or Vercel CLI uploads). */
+        if (!deploymentUrl && deploymentId) {
+            const redeployRes = await vercelApi(`/v13/deployments`, config.vercelToken, 'POST', {
+                name: config.projectId,
+                project: config.projectId,
+                target: 'production',
+                deploymentId
+            });
+            if (redeployRes.ok) {
+                const redeployData = await redeployRes.json();
+                deploymentUrl = redeployData.url || '';
+            }
+        }
+        return { success: true, deploymentUrl };
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : 'Unknown error';
+        return { success: false, error: message };
+    }
+}
+/**
+ * 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-drive/kit/server';
+ * export const POST = createValidateHandler();
+ * ```
+ *
+ * @see {@link validateSupabaseCredentials} in `supabase/validate.ts`
+ */
+export function createValidateHandler() {
+    return async ({ request }) => {
+        /* Dynamic import keeps the Supabase client out of the module graph
+           until this handler is actually invoked — reduces cold start time
+           for routes that don't need validation. */
+        const { validateSupabaseCredentials } = await import('../supabase/validate.js');
+        try {
+            const { supabaseUrl, supabaseAnonKey } = await request.json();
+            if (!supabaseUrl || !supabaseAnonKey) {
+                return new Response(JSON.stringify({ valid: false, error: 'Supabase URL and Anon Key are required' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+            }
+            const result = await validateSupabaseCredentials(supabaseUrl, supabaseAnonKey);
+            return new Response(JSON.stringify(result), {
+                headers: { 'Content-Type': 'application/json' }
+            });
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : 'Unknown error';
+            return new Response(JSON.stringify({ valid: false, error: `Could not connect to Supabase: ${message}` }), { headers: { 'Content-Type': 'application/json' } });
+        }
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/kit/server.js.map

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

package/dist/kit/sw.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Service worker lifecycle helpers.
+ *
+ * This module extracts SW monitoring and update logic so components and pages
+ * can use clean APIs without duplicating browser-specific service worker code.
+ * It provides three main functions:
+ *
+ *   - `pollForNewServiceWorker` — active polling for a new SW after a
+ *     deployment, useful for "checking for updates..." UI flows
+ *   - `handleSwUpdate`         — triggers `SKIP_WAITING` on a waiting SW
+ *     and reloads the page when the new controller activates
+ *   - `monitorSwLifecycle`     — comprehensive passive monitoring that covers
+ *     six different detection strategies for maximum reliability across
+ *     browsers and platforms (including iOS PWA quirks)
+ *
+ * All functions include SSR guards (`typeof navigator === 'undefined'`) so
+ * they can be safely imported in universal (shared) SvelteKit code without
+ * causing server-side errors.
+ *
+ * @module kit/sw
+ *
+ * @example
+ * ```ts
+ * // In a Svelte component
+ * import { monitorSwLifecycle, handleSwUpdate } from 'stellar-drive/kit/sw';
+ *
+ * let showBanner = $state(false);
+ * const cleanup = monitorSwLifecycle({
+ *   onUpdateAvailable: () => { showBanner = true; }
+ * });
+ * // When user clicks "Update Now":
+ * await handleSwUpdate();
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API}
+ * @see {@link debug} in `debug.ts` for the logging utility used throughout
+ */
+/**
+ * Options for `pollForNewServiceWorker`.
+ *
+ * All fields are optional with sensible defaults for typical deployment
+ * detection scenarios.
+ */
+export interface PollOptions {
+    /**
+     * Polling interval in milliseconds.
+     * @default 5000
+     */
+    intervalMs?: number;
+    /**
+     * Maximum number of polling attempts before giving up.
+     * With the default interval of 5s and 60 attempts, polling runs for ~5 minutes.
+     * @default 60
+     */
+    maxAttempts?: number;
+    /**
+     * Callback invoked when a new service worker is detected in the
+     * `waiting` state. Called exactly once, then polling stops automatically.
+     */
+    onFound?: () => void;
+}
+/**
+ * Callbacks for `monitorSwLifecycle`.
+ *
+ * Provides hooks into the service worker lifecycle events that the
+ * monitoring system detects.
+ */
+export interface SwLifecycleCallbacks {
+    /**
+     * Called whenever an update-available condition is detected through
+     * any of the six monitoring strategies. May be called multiple times
+     * if different strategies detect the same update independently.
+     */
+    onUpdateAvailable: () => void;
+}
+/**
+ * Polls `registration.update()` until a new service worker is detected
+ * in the `waiting` state. Useful after triggering a deployment to detect
+ * when the new build is live and ready to activate.
+ *
+ * The polling loop calls `registration.update()` on each tick, which
+ * forces the browser to check the server for a new SW script. When a
+ * waiting worker is found, the `onFound` callback fires and polling
+ * stops automatically.
+ *
+ * @param options - Optional configuration for interval, max attempts,
+ *                  and the detection callback.
+ *
+ * @returns A cleanup function that stops polling when called. Useful
+ *          for cleanup in Svelte's `onDestroy` or `$effect` teardown.
+ *
+ * @example
+ * ```ts
+ * const stopPolling = pollForNewServiceWorker({
+ *   intervalMs: 3000,
+ *   maxAttempts: 100,
+ *   onFound: () => showUpdateBanner()
+ * });
+ *
+ * // Later, to stop polling early:
+ * stopPolling();
+ * ```
+ *
+ * @see {@link handleSwUpdate} for activating the waiting SW once found
+ */
+export declare function pollForNewServiceWorker(options?: PollOptions): () => void;
+/**
+ * Sends `SKIP_WAITING` to the waiting service worker, listens for the
+ * `controllerchange` event, then reloads the page to activate the new
+ * version.
+ *
+ * If no waiting worker is found (e.g. the update was already applied),
+ * falls back to a simple page reload. The `{ once: true }` listener
+ * option acts as a double-reload guard — the handler fires exactly once
+ * even if `controllerchange` is emitted multiple times during activation.
+ *
+ * @returns A promise that resolves just before the page reloads.
+ *          In practice, the caller won't observe the resolution since
+ *          `window.location.reload()` interrupts execution.
+ *
+ * @example
+ * ```ts
+ * // In an "Update Now" button handler
+ * async function onUpdateClick() {
+ *   await handleSwUpdate();
+ *   // Page will have reloaded by this point
+ * }
+ * ```
+ *
+ * @see {@link pollForNewServiceWorker} for detecting when an update is available
+ * @see {@link monitorSwLifecycle} for passive update detection
+ */
+export declare function handleSwUpdate(): Promise<void>;
+/**
+ * Comprehensive service worker monitoring covering all detection strategies
+ * for maximum reliability across browsers and platforms:
+ *
+ *   1. **Immediate check** — inspects the current registration for a
+ *      waiting worker right away
+ *   2. **Delayed retries at 1s/3s** — iOS PWA sometimes needs extra time
+ *      after app launch before the SW registration is fully populated
+ *   3. **`SW_INSTALLED` message listener** — listens for a custom message
+ *      from the SW itself, posted after the `install` event completes
+ *   4. **`updatefound` + `statechange` tracking** — monitors the standard
+ *      SW lifecycle events for newly installing workers
+ *   5. **`visibilitychange` re-check** — triggers an update check when the
+ *      app resumes from the background (critical for iOS PWA resume)
+ *   6. **2-minute polling interval** — periodic fallback for long-running
+ *      sessions where none of the event-based strategies would fire
+ *
+ * @param callbacks - Object containing the `onUpdateAvailable` callback,
+ *                    which fires whenever any strategy detects a waiting
+ *                    service worker.
+ *
+ * @returns A cleanup function that removes all event listeners, clears all
+ *          intervals and timeouts, and stops monitoring. Should be called
+ *          in Svelte's `onDestroy` or `$effect` teardown to prevent leaks.
+ *
+ * @example
+ * ```ts
+ * // In a Svelte component's $effect
+ * $effect(() => {
+ *   const cleanup = monitorSwLifecycle({
+ *     onUpdateAvailable: () => {
+ *       updateAvailable = true;
+ *     }
+ *   });
+ *   return cleanup;
+ * });
+ * ```
+ *
+ * @see {@link handleSwUpdate} for activating the detected update
+ * @see {@link SwLifecycleCallbacks} for the callback interface
+ */
+export declare function monitorSwLifecycle(callbacks: SwLifecycleCallbacks): () => void;
+//# sourceMappingURL=sw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sw.d.ts","sourceRoot":"","sources":["../../src/kit/sw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,IAAI,CAqCzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAuI9E"}