@gencow/core 0.1.27 → 0.1.29

package/dist/auth-config.d.ts

@@ -7,6 +7,18 @@
  * shadcn 패턴: auth.ts는 사용자가 소유하고 직접 수정할 수 있는 파일.
  * defineAuth()는 타입 안전한 설정 헬퍼일 뿐, 런타임 로직은 server에서 처리.
  */
+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;
@@ -16,16 +28,91 @@ export interface AuthEmailVerification {
     autoSignInAfterVerification?: boolean;
     /** 인증 메일 발송 함수 — 사용자가 직접 구현 */
     sendVerificationEmail: (data: {
-        user: {
-            email: string;
-            name: string;
-        };
+        user: AuthUserLike;
+        url: string;
+        token: string;
+    }, 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;
-    }) => Promise<void>;
+    }, 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>;
+}
+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[];
 }
 export interface GencowAuthConfig {
     emailVerification?: AuthEmailVerification;
+    socialProviders?: SocialProvidersConfig;
+    oauth?: AuthOAuthConfig;
+    passwordReset?: AuthPasswordReset;
+    events?: AuthEvents;
 }
 /**
  * Auth 설정 정의 헬퍼.

package/dist/config.d.ts

@@ -0,0 +1,107 @@
+/**
+ * User-facing project configuration for `gencow.config.ts`.
+ *
+ * The config file is intentionally small today, but we expose a stable typed
+ * contract so editors can offer autocomplete and inline explanations.
+ */
+/**
+ * Cloud deployment settings written to `gencow.config.ts`.
+ *
+ * @example
+ * ```ts
+ * deploy: {
+ *   app: "my-todo",
+ * }
+ * ```
+ */
+export interface GencowDeployConfig {
+    /**
+     * Default cloud app name to target for CLI flows that attach project metadata.
+     *
+     * This is commonly added automatically after `gencow app create`.
+     */
+    app?: string;
+}
+/**
+ * Local database settings for the Gencow dev server.
+ *
+ * @example
+ * ```ts
+ * db: {
+ *   url: "./.gencow/data",
+ * }
+ * ```
+ */
+export interface GencowDbConfig {
+    /**
+     * Local database path used by the default PGlite setup.
+     *
+     * Default: `"./.gencow/data"`
+     */
+    url?: string;
+}
+/**
+ * Project configuration for `gencow.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@gencow/core";
+ *
+ * export default defineConfig({
+ *   functionsDir: "./gencow",
+ *   schema: ["./gencow/schema.ts", "./gencow/auth-schema.ts"],
+ *   codegenOutDir: "./src/gencow",
+ *   storage: "./.gencow/uploads",
+ *   db: { url: "./.gencow/data" },
+ *   port: 5456,
+ *   deploy: { app: "my-app" },
+ * });
+ * ```
+ */
+export interface GencowConfig {
+    /**
+     * Directory containing your backend modules such as `index.ts`, `schema.ts`,
+     * and optional files like `crons.ts` or `seed.ts`.
+     *
+     * Default: `"./gencow"`
+     */
+    functionsDir?: string;
+    /**
+     * Path to the Drizzle schema file, or multiple schema files when your project
+     * splits auth and application tables.
+     *
+     * Default: `"./gencow/schema.ts"`
+     */
+    schema?: string | string[];
+    /**
+     * Output directory for generated frontend codegen artifacts such as `api.ts`
+     * and declaration files.
+     *
+     * Default: `"./src/gencow"`
+     */
+    codegenOutDir?: string;
+    /**
+     * Directory used for uploaded file storage in local development.
+     *
+     * Default: `"./.gencow/uploads"`
+     */
+    storage?: string;
+    /**
+     * Local database configuration.
+     */
+    db?: GencowDbConfig;
+    /**
+     * Port used by the local dev server.
+     *
+     * Default: `5456`
+     */
+    port?: number;
+    /**
+     * Optional cloud deployment metadata.
+     */
+    deploy?: GencowDeployConfig;
+}
+/**
+ * Helper for authoring typed `gencow.config.ts` files with editor autocomplete.
+ */
+export declare function defineConfig(config: GencowConfig): GencowConfig;

package/dist/config.js

@@ -0,0 +1,12 @@
+/**
+ * User-facing project configuration for `gencow.config.ts`.
+ *
+ * The config file is intentionally small today, but we expose a stable typed
+ * contract so editors can offer autocomplete and inline explanations.
+ */
+/**
+ * Helper for authoring typed `gencow.config.ts` files with editor autocomplete.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/context.d.ts

@@ -0,0 +1,139 @@
+import type { Storage } from "./storage.js";
+import type { Scheduler } from "./scheduler.js";
+import type { HybridSearchOptions, SearchOptions, SearchResponse, VectorSearchOptions } from "./search-types.js";
+import type { GencowServicesCtx } from "./document-types.js";
+import type { GroundingRuntime } from "./grounded-answer-types.js";
+import type { RetryOptions } from "./retry.js";
+import type { GencowProcedureDef } from "./procedure.js";
+export interface UserIdentity {
+    id: string;
+    email: string;
+    name?: string;
+}
+export interface AuthCtx {
+    /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
+    getUserIdentity(): UserIdentity | null;
+    /** 현재 유저 반환 (비로그인 시 401 throw) */
+    requireAuth(): UserIdentity;
+}
+/**
+ * mutation handler 내에서 구독자들에게 데이터를 즉시 push합니다.
+ * 클라이언트는 이 데이터를 받아 re-fetch 없이 state를 업데이트합니다.
+ */
+export interface RealtimeCtx {
+    /**
+     * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
+     * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
+     *
+     * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
+     * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
+     *
+     * @example
+     *   const freshList = await ctx.db.select().from(tasks);
+     *   ctx.realtime.emit("tasks.list", freshList);
+     */
+    emit(queryKey: string, data: unknown): void;
+    /**
+     * 특정 queryKey 구독자에게 재조회 신호만 보냅니다.
+     * private/RLS query처럼 서버가 안전하게 full payload를 만들 수 없는 경우 기본값입니다.
+     */
+    invalidate(queryKey: string | string[]): void;
+    /**
+     * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
+     * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
+     * 복잡한 JOIN query도 queryKey만 지정하면 됩니다.
+     *
+     * @param queryKey - re-run할 쿼리 키 (예: "dashboard.revenue")
+     *
+     * @example
+     *   mutation("orders.place", {
+     *       handler: async (ctx, args) => {
+     *           await ctx.db.insert(orders).values(args);
+     *           ctx.realtime.refresh("orders.list");
+     *           ctx.realtime.refresh("dashboard.revenue");  // JOIN query도 OK
+     *       }
+     *   });
+     */
+    refresh(queryKey: string): void;
+}
+export type RealtimeNotifyEvent = {
+    type: "emit";
+    queryKey: string;
+    data: unknown;
+} | {
+    type: "invalidate";
+    queryKeys: string[];
+};
+/**
+ * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
+ * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
+ * fs, child_process 등 원시 Node.js API는 노출되지 않음.
+ */
+export interface AIMessage {
+    role: "user" | "system" | "assistant";
+    content: string;
+}
+export interface AIResult {
+    text: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    creditsCharged: number;
+    model: string;
+}
+export interface AIContext {
+    /** AI 텍스트 생성 */
+    chat: (opts: {
+        model?: string;
+        messages: AIMessage[];
+        /** System prompt — shorthand for adding a system message */
+        system?: string;
+        temperature?: number;
+        maxTokens?: number;
+        /** Response format — e.g. { type: "json_object" } for JSON mode */
+        responseFormat?: {
+            type: string;
+        };
+    }) => Promise<AIResult>;
+    /** 텍스트 임베딩 (단일) */
+    embed: (text: string) => Promise<number[]>;
+    /** 배치 임베딩 */
+    embedMany: (texts: string[]) => Promise<number[][]>;
+}
+export interface GencowCtx {
+    /** Drizzle DB 인스턴스 (scoped) — 스키마 filter 자동 적용, execute 차단 */
+    db: any;
+    /** Raw Drizzle DB — 필터 없음, execute 허용. ⚠️ 이름이 곧 경고. */
+    unsafeDb: any;
+    /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
+    auth: AuthCtx;
+    /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
+    storage: Storage;
+    /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
+    scheduler: Scheduler;
+    /** 실시간 push — ctx.realtime.emit(queryKey, data) */
+    realtime: RealtimeCtx;
+    /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
+    retry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+    /** 프레임워크 서비스 헬퍼 — workflow 전용 service는 별도 ctx에서 노출 */
+    services: GencowServicesCtx;
+    /** AI 헬퍼 */
+    ai?: AIContext;
+    /** Full-text / hybrid search helper */
+    search: (table: string, query: string, options: SearchOptions) => Promise<SearchResponse>;
+    /** Vector / semantic search helper */
+    vectorSearch: (table: string, options: VectorSearchOptions) => Promise<SearchResponse>;
+    /** Hybrid search helper (lexical + vector) */
+    hybridSearch: (table: string, query: string, options: HybridSearchOptions) => Promise<SearchResponse>;
+    /** Grounded answer helper over canonical rag_* tables */
+    grounding?: GroundingRuntime;
+}
+export interface GencowDefinition {
+    [procedureName: string]: GencowProcedureDef<any, any, any, any>;
+}
+export interface GencowApiDefinition {
+    procedures: GencowDefinition;
+}
+export declare function defineApi<const TApi extends GencowApiDefinition>(api: TApi): TApi;

package/dist/context.js

@@ -0,0 +1,3 @@
+export function defineApi(api) {
+    return api;
+}

package/dist/crud.d.ts

@@ -130,7 +130,7 @@ export declare function parseFilterNode(node: Record<string, unknown>, table: an
  * ```
  */
 export declare function crud<T extends PgTable>(table: T, options?: CrudOptions<T>): {
-    list: import("./reactive.js").QueryDef<{
+    list: import("./reactive-query-types.js").QueryDef<{
         page: import("./v.js").Validator<number | undefined>;
         limit: import("./v.js").Validator<number | undefined>;
         search: import("./v.js").Validator<string | undefined>;
@@ -141,12 +141,12 @@ export declare function crud<T extends PgTable>(table: T, options?: CrudOptions<
         data: any;
         total: number;
     }> | undefined;
-    get: import("./reactive.js").QueryDef<{
+    get: import("./reactive-query-types.js").QueryDef<{
         id: import("./v.js").Validator<string> | import("./v.js").Validator<number>;
     }, any> | undefined;
-    create: import("./reactive.js").MutationDef<any, any> | undefined;
-    update: import("./reactive.js").MutationDef<any, any> | undefined;
-    remove: import("./reactive.js").MutationDef<any, {
+    create: import("./reactive-mutation-types.js").MutationDef<any, any> | undefined;
+    update: import("./reactive-mutation-types.js").MutationDef<any, any> | undefined;
+    remove: import("./reactive-mutation-types.js").MutationDef<any, {
         success: boolean;
     }> | undefined;
 };

package/dist/crud.js

@@ -36,7 +36,9 @@
  */
 import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, or, and, count as drizzleCount, getTableName, getTableColumns, } from "drizzle-orm";
 import { getTableConfig } from "drizzle-orm/pg-core";
-import { query, mutation } from "./reactive.js";
+import { buildQuerySubscriptionKey } from "./reactive-realtime.js";
+import { query } from "./reactive-query.js";
+import { mutation } from "./reactive-mutation.js";
 import { v } from "./v.js";
 import { getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 // ─── ownerRls 감지 추적 (부트 로그용) ──────────────────
@@ -339,23 +341,11 @@ export function crud(table, options) {
         }
         return await fn(db);
     }
-    // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
-    // Runs inside db.transaction so createRlsDb() RLS session vars apply for RLS.
-    // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
-    // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
-    async function fetchListWithTotal(db, whereClause, userId) {
-        // ownerRls 적용 시 realtime emit에도 userId 필터 추가
-        // → 다른 사용자에게 타인 데이터가 push되지 않도록
-        let effectiveWhere = whereClause;
-        if (ownerMeta && userId && !ownerMeta.readPublic) {
-            const ownerFilter = eq(ownerMeta.column, userId);
-            effectiveWhere = effectiveWhere ? and(effectiveWhere, ownerFilter) : ownerFilter;
-        }
-        return await inRlsOrPlainTx(db, async (tx) => {
-            const data = await tx.select().from(anyTable).where(effectiveWhere).orderBy(desc(defaultOrderCol));
-            const countResult = await tx.select({ count: drizzleCount() }).from(anyTable).where(effectiveWhere);
-            return { data, total: Number(countResult[0]?.count ?? 0) };
-        });
+    function invalidateListRealtime(ctx) {
+        ctx.realtime.invalidate(`${prefix}.list`);
+    }
+    function invalidateGetRealtime(ctx, id) {
+        ctx.realtime.invalidate(buildQuerySubscriptionKey(`${prefix}.get`, { id }));
     }
     // ── methods 필터링: 지정된 메서드만 레지스트리 등록 ──
     // methods 옵션 미지정 시 전체 5개 등록 (하위호환)
@@ -477,13 +467,9 @@ export function crud(table, options) {
                     insertData = await options.hooks.beforeCreate(insertData);
                 }
                 const [result] = await inRlsOrPlainTx(ctx.db, async (tx) => tx.insert(anyTable).values(insertData).returning());
-                // Realtime push — { data, total } 형태로 emit
-                // ownerRls 시 해당 사용자 데이터만 push (타 사용자에게 누출 방지)
-                // S5: requireAuth로 확실한 userId 획득 (getUserIdentity null 방지)
+                // Realtime push: list는 payload 없이 invalidation으로 갱신
                 if (useRealtime && enabledMethods.has("list")) {
-                    const currentUserId = user?.id;
-                    const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-                    ctx.realtime.emit(`${prefix}.list`, listResult);
+                    invalidateListRealtime(ctx);
                 }
                 return result;
             },
@@ -519,16 +505,17 @@ export function crud(table, options) {
                     updateData = await options.hooks.beforeUpdate(updateData);
                 }
                 const [result] = await inRlsOrPlainTx(ctx.db, async (tx) => tx.update(anyTable).set(updateData).where(updateWhere).returning());
-                // Realtime push (list + get 양쪽) — { data, total } 형태
-                // S5: ownerRls 시 user.id 사용 (getUserIdentity null 방지)
+                // Realtime push: list는 invalidation, public exact-id get만 full payload 유지
                 if (useRealtime) {
-                    const currentUserId = ownerMeta ? user?.id : undefined;
                     if (enabledMethods.has("list")) {
-                        const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-                        ctx.realtime.emit(`${prefix}.list`, listResult);
+                        invalidateListRealtime(ctx);
                     }
                     if (enabledMethods.has("get")) {
-                        ctx.realtime.emit(`${prefix}.get`, result);
+                        const getKey = buildQuerySubscriptionKey(`${prefix}.get`, { id });
+                        if (isPublic && !ownerMeta)
+                            ctx.realtime.emit(getKey, result);
+                        else
+                            invalidateGetRealtime(ctx, id);
                     }
                 }
                 return result;
@@ -560,12 +547,9 @@ export function crud(table, options) {
                         await tx.delete(anyTable).where(deleteWhere);
                     }
                 });
-                // Realtime push — { data, total } 형태
-                // S5: ownerRls 시 user.id 사용
+                // Realtime push: list는 payload 없이 invalidation으로 갱신
                 if (useRealtime && enabledMethods.has("list")) {
-                    const currentUserId = ownerMeta ? user?.id : undefined;
-                    const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-                    ctx.realtime.emit(`${prefix}.list`, listResult);
+                    invalidateListRealtime(ctx);
                 }
                 return { success: true };
             },

package/dist/document-types.d.ts

@@ -0,0 +1,65 @@
+export type DocumentVisibility = "private" | "shared" | "public";
+export type DocumentConvertMode = "auto" | "text-only" | "no-external-provider" | "prefer-external" | "force-external" | "force-ocr";
+export type DocumentConvertProvider = "auto" | "local_text" | "opendataloader" | "gemini" | "openai" | "ocr" | "custom_vlm";
+export type DocumentResolvedProvider = Exclude<DocumentConvertProvider, "auto">;
+export type DocumentProviderRoute = "local_text" | "opendataloader" | "vlm" | "ocr_fallback";
+export type DocumentCacheArtifact = "convert" | "embedding" | "summary" | "rerank";
+export type DocumentConvertInput = {
+    storageId: string;
+    filename?: string;
+    mimeType?: string;
+    corpus: string;
+    visibility: DocumentVisibility;
+    ownerUserId?: string;
+    mode?: DocumentConvertMode;
+    provider?: DocumentConvertProvider;
+};
+export type DocumentPage = {
+    page: number;
+    charStart: number;
+    charEnd: number;
+    previewText?: string;
+};
+export type DocumentSection = {
+    id: string;
+    title?: string;
+    depth: number;
+    path: string[];
+    pageStart?: number;
+    pageEnd?: number;
+    charStart: number;
+    charEnd: number;
+};
+export type DocumentProviderTrace = {
+    provider: DocumentResolvedProvider;
+    route: DocumentProviderRoute;
+    external: boolean;
+    requestId?: string;
+    durationMs: number;
+    bytes: number;
+};
+export type DocumentConvertResult = {
+    text: string;
+    markdown: string;
+    pages: DocumentPage[];
+    sections: DocumentSection[];
+    warnings: string[];
+    providerTrace: DocumentProviderTrace;
+};
+export interface GencowServicesCtx {
+}
+export interface WorkflowDocumentServicesCtx {
+    document: {
+        convert(input: DocumentConvertInput): Promise<DocumentConvertResult>;
+    };
+}
+export type DocumentCacheKeyInput = {
+    appId: string;
+    ownerUserId?: string | null;
+    corpus: string;
+    sourceKey: string;
+    checksum: string;
+    provider: DocumentResolvedProvider;
+    artifact: DocumentCacheArtifact;
+};
+export declare function buildDocumentCacheKey(input: DocumentCacheKeyInput): string;

package/dist/document-types.js

@@ -0,0 +1,15 @@
+function normalizeCachePart(value) {
+    return value.trim() || "unknown";
+}
+export function buildDocumentCacheKey(input) {
+    const owner = input.ownerUserId?.trim() ? input.ownerUserId.trim() : "shared";
+    return [
+        `app:${normalizeCachePart(input.appId)}`,
+        `user:${normalizeCachePart(owner)}`,
+        `corpus:${normalizeCachePart(input.corpus)}`,
+        `source:${normalizeCachePart(input.sourceKey)}`,
+        `checksum:${normalizeCachePart(input.checksum)}`,
+        `provider:${normalizeCachePart(input.provider)}`,
+        `artifact:${normalizeCachePart(input.artifact)}`,
+    ].join(":");
+}

package/dist/grounded-answer-types.d.ts

@@ -0,0 +1,62 @@
+import type { SearchFilter, SearchScope } from "./search-types.js";
+export type CitationCoverage = "direct" | "partial" | "context";
+export type ClaimSupportStatus = "supported" | "partially_supported" | "insufficient_evidence";
+export type GroundedAnswerMode = "qa" | "compare" | "topic";
+export type Citation = {
+    sourceId: string;
+    sourceTitle: string;
+    sectionId?: string;
+    sectionPath?: string[];
+    pageStart?: number;
+    pageEnd?: number;
+    chunkIds: string[];
+    snippet: string;
+    coverage: CitationCoverage;
+    confidence: number;
+};
+export type ClaimEvidenceMap = {
+    claimId: string;
+    claimText: string;
+    status: ClaimSupportStatus;
+    citations: Citation[];
+    missingEvidenceReasons?: string[];
+};
+export type GroundedAnswer = {
+    answer: string;
+    claims: ClaimEvidenceMap[];
+    citations: Citation[];
+    warnings: string[];
+    grounded: boolean;
+};
+export type GroundingBudget = {
+    maxVerifyLoops: number;
+    maxResearchQueriesPerLoop: number;
+    maxCitationsPerClaim: number;
+    maxClaimsPerAnswer: number;
+};
+export declare const DEFAULT_GROUNDING_BUDGET: GroundingBudget;
+export type GroundedClaimInput = {
+    claimId?: string;
+    claimText: string;
+    requiredTerms?: string[];
+};
+export type GroundedCompareInput = {
+    left: string;
+    right: string;
+};
+export type GroundedTopicInput = {
+    minDistinctSections?: number;
+};
+export type GroundedAnswerInput = {
+    question: string;
+    scope: SearchScope;
+    filters?: SearchFilter;
+    claims?: GroundedClaimInput[];
+    mode?: GroundedAnswerMode;
+    compare?: GroundedCompareInput;
+    topic?: GroundedTopicInput;
+    budget?: Partial<GroundingBudget>;
+};
+export type GroundingRuntime = {
+    answer(input: GroundedAnswerInput): Promise<GroundedAnswer>;
+};

package/dist/grounded-answer-types.js

@@ -0,0 +1,6 @@
+export const DEFAULT_GROUNDING_BUDGET = {
+    maxVerifyLoops: 2,
+    maxResearchQueriesPerLoop: 3,
+    maxCitationsPerClaim: 3,
+    maxClaimsPerAnswer: 12,
+};