@gencow/core 0.1.28 → 0.1.30

package/dist/storage.d.ts

@@ -1,5 +1,7 @@
 import type { Storage, StorageOptions } from "./storage-shared.js";
+import type { StorageMeteringOptions } from "./storage-metering.js";
 export type { Storage, StorageFile, StorageOptions, StoredFile } from "./storage-shared.js";
+export type { StorageImageTransformMetric, StorageMeteringOptions } from "./storage-metering.js";
 /**
  * Create a storage instance — Convex storage 패턴 재현
  *
@@ -43,7 +45,7 @@ export interface StorageImageTierConfig {
  * - 디스크 캐시: uploads/.cache/{uuid}_{params}.{ext}
  * - 원본 보존: 원본 파일은 절대 수정하지 않음
  */
-export declare function storageRoutes(storage: ReturnType<typeof createStorage>, rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>, storageDir?: string, tierConfig?: StorageImageTierConfig): (c: {
+export declare function storageRoutes(storage: ReturnType<typeof createStorage>, rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>, storageDir?: string, tierConfig?: StorageImageTierConfig, meteringOptions?: StorageMeteringOptions): (c: {
     req: {
         param: (key: string) => string;
         query: (key: string) => string | undefined;

package/dist/storage.js

@@ -3,6 +3,7 @@ import * as fsSync from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { DEFAULT_STORAGE_QUOTA, MAX_FILE_SIZE, formatBytes, loadStorageMeta, } from "./storage-shared.js";
+import { recordStorageImageTransform } from "./storage-metering.js";
 // ─── Implementation ─────────────────────────────────────
 const metaStore = new Map();
 /**
@@ -42,6 +43,7 @@ async function ensureFilesTable(rawSql) {
 async function checkStorageQuota(rawSql, newFileSize, quota) {
     if (quota <= 0)
         return; // 무제한
+    await ensureFilesTable(rawSql);
     const rows = await rawSql(`SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM _system_files`);
     const currentUsage = Number(rows[0]?.total || "0");
     const projectedUsage = currentUsage + newFileSize;
@@ -343,7 +345,7 @@ async function getCacheEntryCount(cacheDir) {
  * - 디스크 캐시: uploads/.cache/{uuid}_{params}.{ext}
  * - 원본 보존: 원본 파일은 절대 수정하지 않음
  */
-export function storageRoutes(storage, rawSql, storageDir, tierConfig) {
+export function storageRoutes(storage, rawSql, storageDir, tierConfig, meteringOptions) {
     const baseTierConfig = {
         autoWebp: tierConfig?.autoWebp ?? true,
         autoMaxWidth: tierConfig?.autoMaxWidth ?? 0, // 0 = 제한 없음
@@ -561,14 +563,16 @@ export function storageRoutes(storage, rawSql, storageDir, tierConfig) {
                 }
                 // 변환 실행 → 캐시에 저장
                 await pipeline.toFile(cachePath);
+                const cacheStats = await recordStorageImageTransform(meteringOptions, cachePath, {
+                    sourceBytes: meta.size,
+                    format: outputFormat || meta.type.replace(/^image\//, ""),
+                    autoWebp: isAutoWebp,
+                });
                 // WebP/AVIF가 원본보다 큰 경우 → 캐시 삭제 + 원본 서빙
                 // (Static Deploy와 동일 전략 — apps.ts L840-847)
-                if (isAutoWebp) {
-                    const cacheStats = await fs.stat(cachePath);
-                    if (cacheStats.size >= meta.size) {
-                        await fs.unlink(cachePath).catch(() => { });
-                        return serveOriginal(c, meta);
-                    }
+                if (isAutoWebp && cacheStats.size >= meta.size) {
+                    await fs.unlink(cachePath).catch(() => { });
+                    return serveOriginal(c, meta);
                 }
                 return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
             }

package/dist/wake-app-result.d.ts

@@ -0,0 +1,22 @@
+export type WakeAppSuccessStatus = "already_running" | "woke";
+export type WakeAppDeferredStatus = "capacity_rejected" | "queue_timeout";
+export type WakeAppSuccessResult = {
+    ok: true;
+    status: WakeAppSuccessStatus;
+    port: number;
+};
+export type WakeAppDeferredResult = {
+    ok: false;
+    status: WakeAppDeferredStatus;
+    retryAfterSec: number;
+};
+export type WakeAppBootFailedResult = {
+    ok: false;
+    status: "boot_failed";
+    error: string;
+};
+export type WakeAppResult = WakeAppSuccessResult | WakeAppDeferredResult | WakeAppBootFailedResult;
+export declare const DEFAULT_WAKE_RETRY_AFTER_SEC = 30;
+export declare function buildWakeAppSuccessResult(status: WakeAppSuccessStatus, port: number): WakeAppSuccessResult;
+export declare function buildWakeAppBootFailedResult(error: unknown): WakeAppBootFailedResult;
+export declare function isWakeAppDeferredResult(result: WakeAppResult): result is WakeAppDeferredResult;

package/dist/wake-app-result.js

@@ -0,0 +1,11 @@
+export const DEFAULT_WAKE_RETRY_AFTER_SEC = 30;
+export function buildWakeAppSuccessResult(status, port) {
+    return { ok: true, status, port };
+}
+export function buildWakeAppBootFailedResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, status: "boot_failed", error: message };
+}
+export function isWakeAppDeferredResult(result) {
+    return !result.ok && (result.status === "capacity_rejected" || result.status === "queue_timeout");
+}

package/dist/workflow-json.d.ts

@@ -0,0 +1,2 @@
+import { sql } from "drizzle-orm";
+export declare function workflowJsonb(value: unknown): ReturnType<typeof sql>;

package/dist/workflow-json.js

@@ -0,0 +1,5 @@
+import { sql } from "drizzle-orm";
+export function workflowJsonb(value) {
+    const json = JSON.stringify(value ?? {});
+    return sql `${json}::text::jsonb`;
+}

package/dist/workflow-types.d.ts

@@ -1,4 +1,4 @@
-import type { GencowCtx } from "./reactive.js";
+import type { GencowCtx } from "./context.js";
 import type { WorkflowDocumentServicesCtx } from "./document-types.js";
 import type { InferArgs } from "./v.js";
 export type WorkflowStatus = "pending" | "running" | "completed" | "failed";
@@ -12,6 +12,7 @@ export interface WorkflowSummary {
     derivedStatus: WorkflowDerivedStatus;
     currentStep: string | null;
     error: string | null;
+    errorCode: string | null;
     retryCount: number;
     maxRetries: number;
     maxDurationMs: number;
@@ -57,6 +58,9 @@ export interface WorkflowResumePayload {
 export interface WorkflowCtx extends Omit<GencowCtx, "services"> {
     workflowId: string;
     workflowName: string;
+    runId?: string;
+    attempt?: number;
+    stepAttempt?: number;
     services: GencowCtx["services"] & WorkflowDocumentServicesCtx;
     step<TResult>(name: string, run: () => Promise<TResult>): Promise<TResult>;
     sleep(duration: WorkflowDuration): Promise<void>;
@@ -69,7 +73,11 @@ export type WorkflowHandler<TArgs, TReturn> = (wf: WorkflowCtx, args: TArgs) =>
 export interface WorkflowOptions<TSchema = any, TReturn = any> {
     args?: TSchema;
     public?: boolean;
+    version?: string;
     maxDuration?: WorkflowDuration;
+    maxActiveDuration?: WorkflowDuration;
+    lifecycleTimeout?: WorkflowDuration;
+    concurrency?: number;
     retries?: number;
     handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
 }
@@ -77,7 +85,11 @@ export interface WorkflowDef<TSchema = any, TReturn = any> {
     name: string;
     argsSchema?: TSchema;
     isPublic: boolean;
+    version?: string;
     maxDurationMs: number;
+    maxActiveDurationMs: number;
+    lifecycleTimeoutMs: number | null;
+    concurrency: number | null;
     maxRetries: number;
     handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
 }

package/dist/workflow.d.ts

@@ -1,4 +1,4 @@
-import type { MutationDef } from "./reactive.js";
+import type { MutationDef } from "./reactive-mutation-types.js";
 import type { WorkflowDef, WorkflowDuration, WorkflowOptions, WorkflowStartResult } from "./workflow-types.js";
 declare global {
     var __gencow_workflowRegistry: Map<string, WorkflowDef<any, any>>;

package/dist/workflow.js

@@ -1,5 +1,6 @@
 import { sql } from "drizzle-orm";
-import { mutation } from "./reactive.js";
+import { mutation } from "./reactive-mutation.js";
+import { workflowJsonb } from "./workflow-json.js";
 import { registerWorkflowsApi } from "./workflows-api.js";
 const workflowRegistry = (globalThis.__gencow_workflowRegistry ??= new Map());
 export const DEFAULT_WORKFLOW_MAX_DURATION_MS = 30 * 60 * 1000;
@@ -57,10 +58,112 @@ export function parseWorkflowDurationMs(raw, label = "workflow duration") {
     }
     return parseDurationString(raw, label);
 }
-function normalizeMaxDurationMs(maxDuration) {
+function normalizeMaxDurationMs(maxDuration, label = "workflow() maxDuration") {
     if (maxDuration == null)
         return DEFAULT_WORKFLOW_MAX_DURATION_MS;
-    return parseWorkflowDurationMs(maxDuration, "workflow() maxDuration");
+    return parseWorkflowDurationMs(maxDuration, label);
+}
+function normalizeOptionalDurationMs(duration, label) {
+    return duration == null ? null : parseWorkflowDurationMs(duration, label);
+}
+function normalizeConcurrency(concurrency) {
+    if (concurrency == null)
+        return null;
+    if (!Number.isFinite(concurrency) || concurrency <= 0) {
+        throw new Error(`workflow() concurrency must be a positive finite number, got "${concurrency}"`);
+    }
+    return Math.floor(concurrency);
+}
+function isMissingWorkflowV2SchemaError(error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    const cause = error && typeof error === "object" && "cause" in error ? error.cause : null;
+    const causeCode = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+    const message = error instanceof Error ? error.message : String(error);
+    return (code === "42P01" ||
+        code === "42703" ||
+        causeCode === "42P01" ||
+        causeCode === "42703" ||
+        message.includes('relation "_gencow_workflow_runs_v2" does not exist') ||
+        message.includes("relation _gencow_workflow_runs_v2 does not exist") ||
+        message.includes('relation "_gencow_workflow_outbox_v2" does not exist') ||
+        message.includes("relation _gencow_workflow_outbox_v2 does not exist") ||
+        message.includes('column "max_active_duration_ms"') ||
+        message.includes('column "retry_count"') ||
+        message.includes('column "user_id"'));
+}
+async function tryInsertWorkflowV2Run(options) {
+    try {
+        await options.db.execute(sql `
+      WITH inserted_run AS (
+        INSERT INTO _gencow_workflow_runs_v2 (
+          id,
+          workflow_name,
+          workflow_version,
+          args_json,
+          user_id,
+          max_active_duration_ms,
+          lifecycle_deadline_at,
+          retry_count,
+          max_retries,
+          max_attempts
+        )
+        VALUES (
+          ${options.workflowId},
+          ${options.workflowName},
+          ${options.workflowVersion ?? null},
+          ${workflowJsonb(options.args)},
+          ${options.userId},
+          ${options.maxActiveDurationMs},
+          CASE
+            WHEN ${options.lifecycleTimeoutMs}::bigint IS NULL THEN NULL
+            ELSE NOW() + (${options.lifecycleTimeoutMs}::bigint * INTERVAL '1 millisecond')
+          END,
+          0,
+          ${options.maxRetries},
+          ${options.maxRetries + 1}
+        )
+        RETURNING id
+      ),
+      inserted_outbox AS (
+        INSERT INTO _gencow_workflow_outbox_v2 (
+          id,
+          run_id,
+          kind,
+          available_at,
+          status
+        )
+        SELECT
+          'start:' || inserted_run.id,
+          inserted_run.id,
+          'wake_run',
+          NOW(),
+          'pending'
+        FROM inserted_run
+        ON CONFLICT (id) DO NOTHING
+        RETURNING id
+      )
+      SELECT id
+      FROM inserted_run
+    `);
+        return true;
+    }
+    catch (error) {
+        if (isMissingWorkflowV2SchemaError(error))
+            return false;
+        throw error;
+    }
+}
+async function tryDeleteWorkflowV2Run(db, workflowId) {
+    try {
+        await db.execute(sql `
+      DELETE FROM _gencow_workflow_runs_v2
+      WHERE id = ${workflowId}
+    `);
+    }
+    catch (error) {
+        if (!isMissingWorkflowV2SchemaError(error))
+            throw error;
+    }
 }
 export function getWorkflowResumeActionName(name) {
     return `${WORKFLOW_RESUME_ACTION_PREFIX}.${name}`;
@@ -85,13 +188,18 @@ export function getRegisteredWorkflows() {
  */
 export function workflow(name, options) {
     registerWorkflowsApi();
-    const maxDurationMs = normalizeMaxDurationMs(options.maxDuration);
+    const maxActiveDurationMs = normalizeMaxDurationMs(options.maxActiveDuration ?? options.maxDuration, options.maxActiveDuration == null ? "workflow() maxDuration" : "workflow() maxActiveDuration");
+    const lifecycleTimeoutMs = normalizeOptionalDurationMs(options.lifecycleTimeout, "workflow() lifecycleTimeout");
     const maxRetries = clampRetries(options.retries);
     const def = {
         name,
         argsSchema: options.args,
         isPublic: options.public === true,
-        maxDurationMs,
+        version: options.version,
+        maxDurationMs: maxActiveDurationMs,
+        maxActiveDurationMs,
+        lifecycleTimeoutMs,
+        concurrency: normalizeConcurrency(options.concurrency),
         maxRetries,
         handler: options.handler,
     };
@@ -120,16 +228,28 @@ export function workflow(name, options) {
                 VALUES (
                     ${workflowId},
                     ${name},
-                    ${JSON.stringify(persistedArgs)}::jsonb,
-                    ${realtimeToken},
-                    'pending',
-                    0,
-                    ${maxRetries},
-                    ${maxDurationMs},
-                    ${ownerId}
+                    ${workflowJsonb(persistedArgs)},
+                  ${realtimeToken},
+                  'pending',
+                  0,
+                  ${maxRetries},
+                  ${maxActiveDurationMs},
+                  ${ownerId}
                 )
             `);
+            let insertedWorkflowV2 = false;
             try {
+                insertedWorkflowV2 = await tryInsertWorkflowV2Run({
+                    db: ctx.unsafeDb,
+                    workflowId,
+                    workflowName: name,
+                    workflowVersion: options.version ?? null,
+                    args: persistedArgs,
+                    userId: ownerId,
+                    maxActiveDurationMs,
+                    lifecycleTimeoutMs,
+                    maxRetries,
+                });
                 const scheduledJobId = ctx.scheduler.runAfter(0, resumeAction, { workflowId });
                 return {
                     id: workflowId,
@@ -143,6 +263,9 @@ export function workflow(name, options) {
                     DELETE FROM _gencow_workflows
                     WHERE id = ${workflowId}
                 `);
+                if (insertedWorkflowV2) {
+                    await tryDeleteWorkflowV2Run(ctx.unsafeDb, workflowId);
+                }
                 throw error;
             }
         },

package/dist/workflows-api.js

@@ -1,6 +1,8 @@
 import { sql } from "drizzle-orm";
-import { mutation, query } from "./reactive.js";
+import { query } from "./reactive-query.js";
+import { mutation } from "./reactive-mutation.js";
 import { createWorkflowRealtimeToken, deserializeWorkflowValue, getWorkflowResumeActionName, getWorkflowRealtimeKey, serializeWorkflowValue, } from "./workflow.js";
+import { workflowJsonb } from "./workflow-json.js";
 import { GencowValidationError, v } from "./v.js";
 import { deriveWorkflowStatus } from "./workflow-types.js";
 const WORKFLOW_STATUSES = new Set(["pending", "running", "completed", "failed"]);
@@ -40,6 +42,7 @@ function mapWorkflowSummary(row) {
         derivedStatus: deriveWorkflowStatus(row.status, row.current_step),
         currentStep: row.current_step,
         error: row.error,
+        errorCode: row.error_code,
         retryCount: row.retry_count,
         maxRetries: row.max_retries,
         maxDurationMs: Number(row.max_duration_ms),
@@ -125,9 +128,66 @@ async function loadWorkflowSignalTarget(db, workflowId) {
         FROM _gencow_workflows
         WHERE id = ${workflowId}
         LIMIT 1
-    `);
+  `);
     return rowsFromResult(result)[0] ?? null;
 }
+function isMissingWorkflowV2SignalSchemaError(error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    const cause = error && typeof error === "object" && "cause" in error ? error.cause : null;
+    const causeCode = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+    const message = error instanceof Error ? error.message : String(error);
+    return (code === "42P01" ||
+        code === "42703" ||
+        causeCode === "42P01" ||
+        causeCode === "42703" ||
+        ((code === "23503" || causeCode === "23503") && message.includes("_gencow_workflow_signals_v2")) ||
+        message.includes('relation "_gencow_workflow_signals_v2" does not exist') ||
+        message.includes("relation _gencow_workflow_signals_v2 does not exist") ||
+        message.includes('relation "_gencow_workflow_runs_v2" does not exist') ||
+        message.includes("relation _gencow_workflow_runs_v2 does not exist"));
+}
+async function tryRecordWorkflowV2Signal(options) {
+    try {
+        await options.db.execute(sql `
+      WITH inserted AS (
+        INSERT INTO _gencow_workflow_signals_v2 (
+          id,
+          run_id,
+          event_name,
+          payload_json,
+          idempotency_key
+        )
+        VALUES (
+          ${crypto.randomUUID()},
+          ${options.workflowId},
+          ${options.event},
+          ${workflowJsonb(options.payload)},
+          ${crypto.randomUUID()}
+        )
+        RETURNING run_id
+      )
+      UPDATE _gencow_workflow_runs_v2 run
+      SET
+        status = 'queued',
+        runnable_at = NOW(),
+        lease_owner = NULL,
+        lease_expires_at = NULL,
+        heartbeat_at = NULL,
+        updated_at = NOW()
+      FROM inserted
+      WHERE run.id = inserted.run_id
+        AND run.status = 'waiting'
+        AND run.completed_at IS NULL
+        AND run.cancel_requested_at IS NULL
+    `);
+        return true;
+    }
+    catch (error) {
+        if (isMissingWorkflowV2SignalSchemaError(error))
+            return false;
+        throw error;
+    }
+}
 export async function loadWorkflowSnapshot(db, workflowId, options) {
     const workflowResult = await db.execute(sql `
         SELECT
@@ -138,6 +198,7 @@ export async function loadWorkflowSnapshot(db, workflowId, options) {
             current_step,
             result,
             error,
+            error_code,
             retry_count,
             max_retries,
             max_duration_ms,
@@ -237,9 +298,15 @@ export function registerWorkflowsApi() {
                     ${crypto.randomUUID()},
                     ${workflow.id},
                     ${normalizedEvent},
-                    ${JSON.stringify(persistedPayload)}::jsonb
+                  ${workflowJsonb(persistedPayload)}
                 )
             `);
+            await tryRecordWorkflowV2Signal({
+                db: ctx.unsafeDb,
+                workflowId: workflow.id,
+                event: normalizedEvent,
+                payload: persistedPayload,
+            });
             let scheduledJobId = null;
             if (workflow.status === "pending" && workflow.current_step?.startsWith("wait:")) {
                 try {
@@ -279,6 +346,7 @@ export function registerWorkflowsApi() {
                         current_step,
                         result,
                         error,
+                        error_code,
                         retry_count,
                         max_retries,
                         max_duration_ms,
@@ -300,6 +368,7 @@ export function registerWorkflowsApi() {
                         current_step,
                         result,
                         error,
+                        error_code,
                         retry_count,
                         max_retries,
                         max_duration_ms,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gencow/core",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
   "type": "module",
   "main": "dist/index.js",
@@ -24,10 +24,13 @@
   "scripts": {
     "db:generate:fixture-basic": "drizzle-kit generate --config ./src/__tests__/fixtures/basic/drizzle.config.ts",
     "build": "tsc",
+    "test:coverage": "node ../../scripts/run-package-coverage.mjs",
+    "coverage:compare": "node ../../scripts/compare-package-coverage.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
     "node-cron": "^4.2.1"
   },
   "peerDependencies": {

package/src/auth-config.ts

@@ -10,6 +10,20 @@
 
 // ─── Email Verification ──────────────────────────────────
 
+export interface AuthHookContext {
+  db?: unknown;
+  request?: unknown;
+}
+
+export interface AuthUserLike {
+  id?: string;
+  email: string;
+  name?: string | null;
+  emailVerified?: boolean;
+  createdAt?: Date | string;
+  updatedAt?: Date | string;
+}
+
 export interface AuthEmailVerification {
   /** 가입 시 인증 메일 자동 발송 (default: true) */
   sendOnSignUp?: boolean;
@@ -19,18 +33,105 @@ export interface AuthEmailVerification {
   autoSignInAfterVerification?: boolean;
   /** 인증 메일 발송 함수 — 사용자가 직접 구현 */
   sendVerificationEmail: (data: {
-    user: { email: string; name: string };
+    user: AuthUserLike;
     url: string;
     token: string;
-  }) => Promise<void>;
+  }, context?: AuthHookContext) => Promise<void>;
+  /** 인증 직전 훅 — better-auth의 emailVerification.beforeEmailVerification으로 전달 */
+  beforeEmailVerification?: (user: AuthUserLike, context?: AuthHookContext) => Promise<void>;
+  /** 인증 완료 훅 — 환영 메일 등 idempotent 후처리에 사용 */
+  afterEmailVerification?: (user: AuthUserLike, context?: AuthHookContext) => Promise<void>;
+}
+
+export interface AuthPasswordReset {
+  /** 비밀번호 재설정 메일 발송 함수 — reset URL은 반드시 사용자에게 전달되어야 한다. */
+  sendResetPassword: (data: {
+    user: AuthUserLike;
+    url: string;
+    token: string;
+  }, context?: AuthHookContext) => Promise<void>;
+  /** 비밀번호 재설정 완료 후 훅 */
+  onPasswordReset?: (data: { user: AuthUserLike }, context?: AuthHookContext) => Promise<void>;
+  /** reset token 유효 시간(초). default: better-auth 기본값 3600초 */
+  resetPasswordTokenExpiresIn?: number;
+}
+
+export interface AuthEvents {
+  /** 회원가입 성공 후 실행. 운영 알림처럼 실패해도 가입을 막지 않아야 하는 작업에 사용. */
+  afterSignUp?: (data: { user: AuthUserLike; inviteCode?: string | null }, context?: AuthHookContext) => Promise<void>;
+}
+
+// ─── Social Login / OAuth ───────────────────────────────
+
+export interface SocialProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  /** Provider-specific callback override. Most apps should leave this unset. */
+  redirectURI?: string;
+}
+
+export interface OAuthUserInfo {
+  id: string;
+  email: string;
+  name?: string;
+  image?: string;
+  emailVerified?: boolean;
+}
+
+export interface CustomOAuthProvider {
+  clientId: string;
+  clientSecret?: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+  scopes?: string[];
+  pkce?: boolean;
+  /** Provider-specific callback override. Most apps should leave this unset. */
+  redirectURI?: string;
+  /** Map provider profile responses such as Naver/Kakao into better-auth user fields. */
+  mapProfileToUser?: (profile: Record<string, unknown>) => Partial<OAuthUserInfo> | Promise<Partial<OAuthUserInfo>>;
+}
+
+export type KakaoConfig = SocialProviderConfig & Partial<CustomOAuthProvider>;
+export type NaverConfig = SocialProviderConfig & Partial<CustomOAuthProvider>;
+
+export type SocialProvidersConfig = {
+  google?: SocialProviderConfig;
+  apple?: SocialProviderConfig;
+  /**
+   * Kakao/Naver use Gencow's built-in OAuth endpoint defaults.
+   * Override any CustomOAuthProvider field when a provider dashboard requires it.
+   */
+  kakao?: KakaoConfig;
+  naver?: NaverConfig;
+  /** Additional OAuth providers can be configured with explicit OAuth endpoints. */
+  [providerId: string]:
+    | SocialProviderConfig
+    | KakaoConfig
+    | NaverConfig
+    | CustomOAuthProvider
+    | undefined;
+};
+
+export interface AuthOAuthConfig {
+  /**
+   * Frontend route that receives the short-lived OAuth handoff code.
+   * If omitted, Gencow uses APP_PUBLIC_DOMAIN + /auth/callback, then falls back to the auth server origin.
+   */
+  callbackURL?: string;
+  /** Extra allowed frontend callback URLs for local development or multi-frontend apps. */
+  allowedCallbackURLs?: string[];
 }
 
 // ─── Auth Config ─────────────────────────────────────────
 
 export interface GencowAuthConfig {
   emailVerification?: AuthEmailVerification;
+  socialProviders?: SocialProvidersConfig;
+  oauth?: AuthOAuthConfig;
+  passwordReset?: AuthPasswordReset;
+  events?: AuthEvents;
   // 확장 예정:
-  // socialProviders?: { ... }
   // passwordPolicy?: { ... }
   // sessionExpiry?: number
 }