@gencow/core 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
-export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx } from "./reactive";
-export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler } from "./reactive";
+export { query, mutation, httpAction, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
 export type { Storage } from "./storage";
 export { createScheduler, getSchedulerInfo } from "./scheduler";
 export type { Scheduler } from "./scheduler";

package/dist/index.js

@@ -4,7 +4,7 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
-export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export { query, mutation, httpAction, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
 export { createScheduler, getSchedulerInfo } from "./scheduler";
 export { v, parseArgs, GencowValidationError } from "./v";
 export { withRetry } from "./retry";

package/dist/reactive.d.ts

@@ -49,6 +49,38 @@ export interface GencowCtx {
 }
 type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
 type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+/**
+ * httpAction 핸들러의 Request/Response 타입.
+ * Hono의 Context를 직접 받아 full HTTP 제어 가능.
+ */
+export type HttpActionHandler = (ctx: GencowCtx, req: HttpActionRequest) => Promise<HttpActionResponse>;
+export interface HttpActionRequest {
+    /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** URL path (e.g. /api/cli/auth-start) */
+    path: string;
+    /** Route params (e.g. { id: "abc" } for /api/apps/:id) */
+    params: Record<string, string>;
+    /** Query string params */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Parse JSON body */
+    json: <T = unknown>() => Promise<T>;
+    /** Parse form data */
+    formData: () => Promise<FormData>;
+    /** Raw body as ArrayBuffer */
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    /** Raw body as text */
+    text: () => Promise<string>;
+}
+export interface HttpActionResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
 export interface QueryDef<TSchema = any, TReturn = any> {
     key: string;
     handler: QueryHandler<InferArgs<TSchema>, TReturn>;
@@ -67,6 +99,17 @@ export interface MutationDef<TSchema = any, TReturn = any> {
     _args?: InferArgs<TSchema>;
     _return?: TReturn;
 }
+/** httpAction 정의. 커스텀 HTTP 엔드포인트를 선언적으로 등록. */
+export interface HttpActionDef {
+    /** HTTP method */
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** URL path (Hono 패턴 — /api/cli/:code 형태 지원) */
+    path: string;
+    /** true = 인증 없이 접근 가능, false(기본) = auth 필수 */
+    isPublic: boolean;
+    /** 핸들러 */
+    handler: HttpActionHandler;
+}
 declare global {
     var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
     var __gencow_mutationRegistry: (MutationDef<any, any> & {
@@ -74,6 +117,7 @@ declare global {
     })[];
     var __gencow_subscribers: Map<string, Set<WSContext>>;
     var __gencow_connectedClients: Set<WSContext>;
+    var __gencow_httpActionRegistry: HttpActionDef[];
 }
 export declare function query<TSchema = any, TReturn = any>(key: string, handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | {
     args?: TSchema;
@@ -87,6 +131,38 @@ export declare function mutation<TSchema = any, TReturn = any>(invalidatesOrDef:
     invalidates: string[];
     handler: MutationHandler<InferArgs<TSchema>, TReturn>;
 }, handler?: MutationHandler<InferArgs<TSchema>, TReturn>, name?: string): MutationDef<TSchema, TReturn>;
+/**
+ * 커스텀 HTTP 엔드포인트를 선언적으로 등록합니다.
+ * query/mutation은 RPC 패턴이지만, httpAction은 RESTful HTTP 라우트를 직접 정의합니다.
+ *
+ * 사용 사례:
+ *   - CLI Device Auth (POST /api/cli/auth-start)
+ *   - 파일 업로드 (POST /api/apps/:id/deploy)
+ *   - Webhook 수신
+ *   - 외부 서비스 콜백
+ *
+ * @example
+ * ```typescript
+ * import { httpAction } from "@gencow/core";
+ *
+ * export const authStart = httpAction({
+ *     method: "POST",
+ *     path: "/api/cli/auth-start",
+ *     public: true,
+ *     handler: async (ctx, req) => {
+ *         const code = crypto.randomUUID().slice(0, 8);
+ *         return { body: { code, url: `https://gencow.com/cli-auth?code=${code}` } };
+ *     },
+ * });
+ * ```
+ */
+export declare function httpAction(def: {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    public?: boolean;
+    handler: HttpActionHandler;
+}): HttpActionDef;
+export declare function getRegisteredHttpActions(): HttpActionDef[];
 export declare function subscribe(queryKey: string, ws: WSContext): void;
 export declare function unsubscribe(ws: WSContext): void;
 /** Register a raw WS connection without any query subscription (e.g. admin dashboard) */

package/dist/reactive.js

@@ -6,8 +6,11 @@ if (!globalThis.__gencow_subscribers)
     globalThis.__gencow_subscribers = new Map();
 if (!globalThis.__gencow_connectedClients)
     globalThis.__gencow_connectedClients = new Set();
+if (!globalThis.__gencow_httpActionRegistry)
+    globalThis.__gencow_httpActionRegistry = [];
 const queryRegistry = globalThis.__gencow_queryRegistry;
 const mutationRegistry = globalThis.__gencow_mutationRegistry;
+const httpActionRegistry = globalThis.__gencow_httpActionRegistry;
 const subscribers = globalThis.__gencow_subscribers;
 /**
  * Every WebSocket client that ever establishes a connection is tracked here.
@@ -63,6 +66,45 @@ export function mutation(invalidatesOrDef, handler, name) {
     mutationRegistry.push(def);
     return def;
 }
+// ─── httpAction (커스텀 HTTP 엔드포인트) ────────────────
+/**
+ * 커스텀 HTTP 엔드포인트를 선언적으로 등록합니다.
+ * query/mutation은 RPC 패턴이지만, httpAction은 RESTful HTTP 라우트를 직접 정의합니다.
+ *
+ * 사용 사례:
+ *   - CLI Device Auth (POST /api/cli/auth-start)
+ *   - 파일 업로드 (POST /api/apps/:id/deploy)
+ *   - Webhook 수신
+ *   - 외부 서비스 콜백
+ *
+ * @example
+ * ```typescript
+ * import { httpAction } from "@gencow/core";
+ *
+ * export const authStart = httpAction({
+ *     method: "POST",
+ *     path: "/api/cli/auth-start",
+ *     public: true,
+ *     handler: async (ctx, req) => {
+ *         const code = crypto.randomUUID().slice(0, 8);
+ *         return { body: { code, url: `https://gencow.com/cli-auth?code=${code}` } };
+ *     },
+ * });
+ * ```
+ */
+export function httpAction(def) {
+    const actionDef = {
+        method: def.method,
+        path: def.path,
+        isPublic: def.public === true,
+        handler: def.handler,
+    };
+    httpActionRegistry.push(actionDef);
+    return actionDef;
+}
+export function getRegisteredHttpActions() {
+    return [...httpActionRegistry];
+}
 // ─── WebSocket subscription management ──────────────────
 export function subscribe(queryKey, ws) {
     connectedClients.add(ws);

package/package.json

@@ -1,39 +1,38 @@
 {
-    "name": "@gencow/core",
-    "version": "0.1.1",
-    "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
-    "type": "module",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        },
-        "./server": {
-            "import": "./dist/server.js",
-            "types": "./dist/server.d.ts"
-        }
+  "name": "@gencow/core",
+  "version": "0.1.3",
+  "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
-    "files": [
-        "dist/",
-        "src/"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "typecheck": "tsc --noEmit",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "@electric-sql/pglite": "^0.3.15",
-        "drizzle-orm": "^0.45.1",
-        "hono": "^4.12.0",
-        "node-cron": "^4.2.1"
-    },
-    "devDependencies": {
-        "@types/bun": "^1.3.9",
-        "@types/node": "^25.3.0",
-        "@types/node-cron": "^3.0.11",
-        "typescript": "^5.9.3"
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
     }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.3.15",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.0",
+    "node-cron": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/node": "^25.3.0",
+    "@types/node-cron": "^3.0.11",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/index.ts

@@ -5,8 +5,8 @@
  * All with Convex-compatible DX patterns.
  */
 
-export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx } from "./reactive";
-export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler } from "./reactive";
+export { query, mutation, httpAction, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
 export type { Storage } from "./storage";
 export { createScheduler, getSchedulerInfo } from "./scheduler";
 export type { Scheduler } from "./scheduler";

package/src/reactive.ts

@@ -61,6 +61,41 @@ type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) =>
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
 
+/**
+ * httpAction 핸들러의 Request/Response 타입.
+ * Hono의 Context를 직접 받아 full HTTP 제어 가능.
+ */
+export type HttpActionHandler = (ctx: GencowCtx, req: HttpActionRequest) => Promise<HttpActionResponse>;
+
+export interface HttpActionRequest {
+    /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** URL path (e.g. /api/cli/auth-start) */
+    path: string;
+    /** Route params (e.g. { id: "abc" } for /api/apps/:id) */
+    params: Record<string, string>;
+    /** Query string params */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Parse JSON body */
+    json: <T = unknown>() => Promise<T>;
+    /** Parse form data */
+    formData: () => Promise<FormData>;
+    /** Raw body as ArrayBuffer */
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    /** Raw body as text */
+    text: () => Promise<string>;
+}
+
+export interface HttpActionResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+
 export interface QueryDef<TSchema = any, TReturn = any> {
     key: string;
     handler: QueryHandler<InferArgs<TSchema>, TReturn>;
@@ -81,6 +116,18 @@ export interface MutationDef<TSchema = any, TReturn = any> {
     _return?: TReturn;
 }
 
+/** httpAction 정의. 커스텀 HTTP 엔드포인트를 선언적으로 등록. */
+export interface HttpActionDef {
+    /** HTTP method */
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** URL path (Hono 패턴 — /api/cli/:code 형태 지원) */
+    path: string;
+    /** true = 인증 없이 접근 가능, false(기본) = auth 필수 */
+    isPublic: boolean;
+    /** 핸들러 */
+    handler: HttpActionHandler;
+}
+
 // ─── Registry ───────────────────────────────────────────
 //
 // globalThis 기반 — 서버 번들(인라인)과 node_modules/@gencow/core 양쪽에서
@@ -96,15 +143,19 @@ declare global {
     var __gencow_subscribers: Map<string, Set<WSContext>>;
     // eslint-disable-next-line no-var
     var __gencow_connectedClients: Set<WSContext>;
+    // eslint-disable-next-line no-var
+    var __gencow_httpActionRegistry: HttpActionDef[];
 }
 
 if (!globalThis.__gencow_queryRegistry) globalThis.__gencow_queryRegistry = new Map();
 if (!globalThis.__gencow_mutationRegistry) globalThis.__gencow_mutationRegistry = [];
 if (!globalThis.__gencow_subscribers) globalThis.__gencow_subscribers = new Map();
 if (!globalThis.__gencow_connectedClients) globalThis.__gencow_connectedClients = new Set();
+if (!globalThis.__gencow_httpActionRegistry) globalThis.__gencow_httpActionRegistry = [];
 
 const queryRegistry = globalThis.__gencow_queryRegistry;
 const mutationRegistry = globalThis.__gencow_mutationRegistry;
+const httpActionRegistry = globalThis.__gencow_httpActionRegistry;
 const subscribers = globalThis.__gencow_subscribers;
 
 /**
@@ -174,6 +225,53 @@ export function mutation<TSchema = any, TReturn = any>(
     return def;
 }
 
+// ─── httpAction (커스텀 HTTP 엔드포인트) ────────────────
+
+/**
+ * 커스텀 HTTP 엔드포인트를 선언적으로 등록합니다.
+ * query/mutation은 RPC 패턴이지만, httpAction은 RESTful HTTP 라우트를 직접 정의합니다.
+ *
+ * 사용 사례:
+ *   - CLI Device Auth (POST /api/cli/auth-start)
+ *   - 파일 업로드 (POST /api/apps/:id/deploy)
+ *   - Webhook 수신
+ *   - 외부 서비스 콜백
+ *
+ * @example
+ * ```typescript
+ * import { httpAction } from "@gencow/core";
+ *
+ * export const authStart = httpAction({
+ *     method: "POST",
+ *     path: "/api/cli/auth-start",
+ *     public: true,
+ *     handler: async (ctx, req) => {
+ *         const code = crypto.randomUUID().slice(0, 8);
+ *         return { body: { code, url: `https://gencow.com/cli-auth?code=${code}` } };
+ *     },
+ * });
+ * ```
+ */
+export function httpAction(def: {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    public?: boolean;
+    handler: HttpActionHandler;
+}): HttpActionDef {
+    const actionDef: HttpActionDef = {
+        method: def.method,
+        path: def.path,
+        isPublic: def.public === true,
+        handler: def.handler,
+    };
+    httpActionRegistry.push(actionDef);
+    return actionDef;
+}
+
+export function getRegisteredHttpActions(): HttpActionDef[] {
+    return [...httpActionRegistry];
+}
+
 // ─── WebSocket subscription management ──────────────────
 
 export function subscribe(queryKey: string, ws: WSContext) {