fix: http endpoint

Author: Jonovono

.changeset/legal-bobcats-mix.md

@@ -0,0 +1,5 @@
+---
+"hyperstar": minor
+---
+
+Http endpoint

examples/hn-uncensored/index.tsx

@@ -709,6 +709,33 @@ app.repeat("hnPoll", {
   },
 })
 
+// Cron webhook - allows external services (cron-job.org, Uptime Robot, etc.) to trigger polls
+// This enables Sprites hibernation while still collecting data periodically
+app.http("/cron", async (ctx) => {
+  const cronSecret = process.env.CRON_SECRET
+  const providedSecret = ctx.req.headers.get("x-cron-secret") ?? ctx.url.searchParams.get("secret")
+
+  // Authenticate if CRON_SECRET is set
+  if (cronSecret && providedSecret !== cronSecret) {
+    console.log(`${LOG_PREFIX} ⚠️  Cron webhook rejected - invalid secret`)
+    return new Response(JSON.stringify({ error: "Unauthorized" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+
+  console.log(`${LOG_PREFIX} 🔔 Cron webhook triggered`)
+  await runPoll(ctx, { source: "manual" })  // Respects poll interval
+
+  return new Response(JSON.stringify({
+    ok: true,
+    timestamp: new Date().toISOString(),
+    message: "Poll triggered successfully"
+  }), {
+    headers: { "Content-Type": "application/json" },
+  })
+})
+
 const server = app
   .app({
     store: {
@@ -1489,9 +1516,12 @@ console.log(`
 ║                    HN Uncensored Monitor                      ║
 ╠═══════════════════════════════════════════════════════════════╣
 ║  http://localhost:${server.port}                                    ║
+║  http://localhost:${server.port}/cron  (webhook for external cron)  ║
 ║                                                               ║
 ║  Polling: ${DEFAULT_POLL_MINUTES} minutes                     ║
 ║  Persist: ./data/hn-uncensored.json                           ║
+║                                                               ║
+║  Set CRON_SECRET env var to secure the webhook                ║
 ╚═══════════════════════════════════════════════════════════════╝
 `)
 

packages/hyperstar/src/server.ts

@@ -380,6 +380,35 @@ export interface CronHandle {
   readonly isPaused: boolean
 }
 
+/**
+ * HTTP route handler context.
+ * Provides access to store and update functions for custom HTTP endpoints.
+ */
+export interface HttpHandlerContext<S extends object> {
+  readonly req: Request
+  readonly url: URL
+  readonly getStore: () => S
+  readonly update: (fn: (s: S) => S) => void
+}
+
+/**
+ * HTTP route handler function.
+ * Returns a Response or void (void returns 200 OK with empty body).
+ */
+export type HttpHandler<S extends object> = (
+  ctx: HttpHandlerContext<S>
+) => Response | Promise<Response> | void | Promise<void>
+
+/**
+ * HTTP route configuration.
+ */
+export interface HttpConfig<S extends object> {
+  /** HTTP method(s) to match. Defaults to ["GET", "POST"] */
+  readonly method?: string | string[]
+  /** Route handler */
+  readonly handler: HttpHandler<S>
+}
+
 // ============================================================================
 // App Configuration (passed to .app())
 // ============================================================================
@@ -486,6 +515,26 @@ export interface HyperstarFactory<
     handler: (ctx: UserTriggerContext<S, U>, change: UserTriggerChange<T>) => void
   }): void
 
+  /**
+   * Define a custom HTTP endpoint.
+   * Useful for webhooks, cron triggers, health checks, APIs.
+   *
+   * @example
+   * ```tsx
+   * app.http("/cron", async (ctx) => {
+   *   await runPoll(ctx)
+   *   return new Response(JSON.stringify({ ok: true }))
+   * })
+   *
+   * // With specific method
+   * app.http("/api/data", { method: "GET", handler: (ctx) => {
+   *   return Response.json(ctx.getStore())
+   * }})
+   * ```
+   */
+  http(path: string, handler: HttpHandler<S>): void
+  http(path: string, config: HttpConfig<S>): void
+
   /**
    * Configure the app with store, view, and other options.
    * Returns a servable app.
@@ -560,6 +609,7 @@ export const createHyperstar = <
   const cronDefs: Array<{ id: string; config: CronConfig<S, U> }> = []
   const triggerDefs: Array<{ id: string; config: Omit<TriggerConfig<S, unknown>, "id"> }> = []
   const userTriggerDefs: Array<{ id: string; config: Omit<UserTriggerConfig<S, U, unknown>, "id"> }> = []
+  const httpDefs: Array<{ path: string; methods: string[]; handler: HttpHandler<S> }> = []
 
   // Create signal handles lazily via Proxy - handles are created on first access
   // Uses universal handles with all methods; TypeScript restricts visibility based on Signals type
@@ -629,6 +679,16 @@ export const createHyperstar = <
       userTriggerDefs.push({ id, config: config as UserTriggerConfig<S, U, unknown> })
     },
 
+    http(path: string, handlerOrConfig: HttpHandler<S> | HttpConfig<S>): void {
+      const isConfig = typeof handlerOrConfig === "object" && "handler" in handlerOrConfig
+      const handler = isConfig ? handlerOrConfig.handler : handlerOrConfig
+      const methodInput = isConfig ? handlerOrConfig.method : undefined
+      const methods = methodInput
+        ? (Array.isArray(methodInput) ? methodInput : [methodInput]).map(m => m.toUpperCase())
+        : ["GET", "POST"]
+      httpDefs.push({ path, methods, handler })
+    },
+
     app(config: HyperstarConfig<S, U, Signals>): HyperstarApp {
       // Signal defaults from config
       const signalDefaults: Record<string, unknown> = config.signals ?? {}
@@ -1035,6 +1095,34 @@ export const createHyperstar = <
           }
         }
 
+        // Check custom HTTP routes
+        for (const { path: routePath, methods, handler } of httpDefs) {
+          if (reqPath === routePath && methods.includes(req.method)) {
+            try {
+              const ctx: HttpHandlerContext<S> = {
+                req,
+                url,
+                getStore,
+                update: updateStore,
+              }
+              const result = await handler(ctx)
+              if (result instanceof Response) {
+                return result
+              }
+              // void return = 200 OK
+              return new Response(JSON.stringify({ ok: true }), {
+                headers: { "Content-Type": "application/json" },
+              })
+            } catch (error) {
+              console.error(`[hyperstar] HTTP handler error for ${routePath}:`, error)
+              return new Response(JSON.stringify({ error: String(error) }), {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+              })
+            }
+          }
+        }
+
         return new Response("Not Found", { status: 404 })
       }