@corgelabs/corge 0.0.1 → 1.0.1

package/src/attachments/service.ts

@@ -0,0 +1,315 @@
+import type { JevQuestion } from '../ai'
+import type { SelectModel } from '../db'
+import { fileScan, fileScanError, type FileRef, type FileScan, type FileScanError } from '../files'
+import type { Core } from '../index'
+import type { StepRunner } from '../tasks'
+import {
+  getRegisteredAttachmentTypes,
+  processAttachmentsOutput,
+  scanAttachmentInput,
+  scanAttachmentOutput,
+  type AttachmentTypesMap,
+  type ProcessedAttachment,
+  type ProcessAttachmentsInput,
+  type ProcessAttachmentsOutput,
+  type ScanAttachmentInput,
+  type ScanAttachmentOutput
+} from './schema'
+import {
+  buildScanError,
+  classifyPermanentScanDefect,
+  extractAttachmentTasks,
+  parseFields,
+  schemaFor
+} from './utils'
+
+export class AttachmentsService {
+  readonly #core: Core
+
+  constructor(coreClient: Core) {
+    this.#core = coreClient
+  }
+
+  #wrapScanStep = async <T>(fn: () => Promise<T>, onDefect: (defect: FileScanError) => void): Promise<T> => {
+    try {
+      return await fn()
+    } catch (err) {
+      const defect = classifyPermanentScanDefect(err)
+      if (defect) {
+        onDefect(defect)
+        return this.#core.errors.nonRetryableError(defect.agentHint, defect.reason)
+      }
+      throw err
+    }
+  }
+
+  #findCrossUserByShaSum = async (
+    ref: FileRef,
+    shaSum: string,
+    requestedType?: string
+  ): Promise<{ scan?: FileScan; scanError?: FileScanError } | undefined> => {
+    if (!shaSum || shaSum.length < 24) return undefined
+    try {
+      await this.#core.internals.resilience.acquireLimit('firestore')
+      const snap = await this.#core.db.firestore().collection('file').where('shaSum', '==', shaSum).limit(5).get()
+      for (const doc of snap.docs) {
+        if (doc.id === ref) continue
+        const data = doc.data()
+        if (data.deleted === true) continue
+        if (data.scan) {
+          const parsedScan = fileScan.safeParse(data.scan)
+          if (parsedScan.success && (!requestedType || parsedScan.data.type === requestedType)) {
+            return { scan: parsedScan.data }
+          }
+        }
+        if (data.scanError) {
+          const parsedErr = fileScanError.safeParse(data.scanError)
+          if (parsedErr.success) {
+            return { scanError: parsedErr.data }
+          }
+        }
+      }
+    } catch {}
+    return undefined
+  }
+
+  classify = async (
+    attachmentContent: string,
+    types: AttachmentTypesMap = getRegisteredAttachmentTypes()
+  ): Promise<{ attachmentType: string; confidence: number }> => {
+    const entries = Object.entries(types)
+    if (!entries.length) return { attachmentType: 'other', confidence: 1 }
+    const questions: Record<string, JevQuestion> = {
+      documentType: {
+        type: 'choice',
+        instructions:
+          'Classify the attached document (its full text is the state) into exactly one type. Choose "other" when it matches none of the specific types.',
+        criteria: {
+          ...Object.fromEntries(entries.map(([k, v]) => [k, v.description])),
+          other: 'Unrecognized document, plain image/diagram, or none of the specific attachment types'
+        }
+      }
+    }
+    const { answers } = await this.#core.ai.decide({ document: attachmentContent.slice(0, 80_000) }, questions)
+    const ans = answers.documentType
+    return ans?.type === 'choice'
+      ? { attachmentType: ans.choice, confidence: ans.confidence }
+      : { attachmentType: 'other', confidence: 0 }
+  }
+
+  #executeScanOcrAndClassify = async (opts: {
+    ref: FileRef
+    contentType: string
+    initialType?: string
+    types: AttachmentTypesMap
+    step: StepRunner
+    onDefect: (d: FileScanError) => void
+  }): Promise<FileScan> => {
+    const { ref, contentType, initialType, types, step, onDefect } = opts
+    const isImage = contentType.startsWith('image/')
+    let dataUrlP: Promise<string> | undefined
+    const getDataUrl = () =>
+      (dataUrlP ??= (async () =>
+        `data:${contentType};base64,${(await this.#core.files.download(ref)).toString('base64')}`)())
+
+    const hasTypes = Object.keys(types).length > 0
+    let resolvedType: string | undefined = hasTypes ? initialType : 'other'
+    let confidence = 1
+    let markdown = ''
+
+    if (!resolvedType || resolvedType === 'other') {
+      const ocrRes = await step('ocr', ({ signal }) =>
+        this.#wrapScanStep(async () => this.#core.ai.vision(await getDataUrl(), { signal }), onDefect)
+      )
+      markdown = ocrRes.markdown
+      if (!markdown) {
+        markdown = await step('vision', ({ signal }) =>
+          this.#wrapScanStep(async () => this.#core.ai.describeImage(await getDataUrl(), signal), onDefect)
+        )
+        resolvedType = 'other'
+      } else {
+        if (!resolvedType) {
+          const classified = await step('classify', () =>
+            this.#wrapScanStep(() => this.classify(markdown, types), onDefect)
+          )
+          resolvedType = classified.attachmentType
+          confidence = classified.confidence
+        }
+        if (hasTypes && resolvedType === 'other' && isImage) {
+          const visionDesc = await step('vision', ({ signal }) =>
+            this.#wrapScanStep(async () => this.#core.ai.describeImage(await getDataUrl(), signal), onDefect)
+          )
+          markdown = `${markdown}\n\n${visionDesc}`.trim()
+        }
+      }
+    }
+
+    let fields: Record<string, unknown> = {}
+    const schema = resolvedType && resolvedType !== 'other' ? schemaFor(resolvedType, types) : undefined
+    if (schema && resolvedType) {
+      const extract = await step('extract', ({ signal }) =>
+        this.#wrapScanStep(async () => this.#core.ai.vision(await getDataUrl(), { schema, signal }), onDefect)
+      )
+      fields = parseFields(resolvedType, extract.annotation, types)
+      if (!markdown) markdown = extract.markdown
+    }
+
+    if (markdown.trim().length < 5 && Object.keys(fields).length === 0) {
+      const defect = buildScanError(
+        'EMPTY_OR_UNREADABLE',
+        'The uploaded document appears blank or unreadable (fewer than 5 characters detected). Please upload a clear, legible scan or photo of the document.'
+      )
+      onDefect(defect)
+      return this.#core.errors.nonRetryableError(defect.agentHint, defect.reason)
+    }
+
+    return { type: resolvedType ?? 'other', confidence, fields, markdown }
+  }
+
+  scan = async (
+    raw: ScanAttachmentInput,
+    opts?: { types?: AttachmentTypesMap; step?: StepRunner; preloadedFile?: SelectModel<'file'> }
+  ): Promise<ScanAttachmentOutput> => {
+    const step = opts?.step ?? this.#core.step
+    const types = opts?.types ?? getRegisteredAttachmentTypes()
+    const preloadedFile = opts?.preloadedFile
+    const { ref, type } = scanAttachmentInput.parse(raw)
+    if (type && type !== 'other' && Object.keys(types).length > 0 && !(type in types)) {
+      throw new Error(`Invalid attachment type: ${type}`)
+    }
+
+    return this.#core.internals.resilience.singleflight(
+      `scan:${this.#core.env.isDev ? 'dev' : 'prod'}:${ref}:${type ?? ''}`,
+      async () => {
+        const entry =
+          preloadedFile ?? (await step('read-meta', () => this.#core.db.read('file', ref, false, { bypassRbac: true })))
+        if (!entry) throw new Error(`File not found: ${ref}`)
+        if (entry.scan) return scanAttachmentOutput.parse(entry.scan)
+        if (entry.scanError) {
+          return this.#core.errors.nonRetryableError(entry.scanError.agentHint, entry.scanError.reason)
+        }
+
+        const shaSum = entry.shaSum || ref.slice(-24)
+        const crossUserMatch = await this.#findCrossUserByShaSum(ref, shaSum, type)
+        if (crossUserMatch?.scan) {
+          await step('persist', () =>
+            this.#core.db.update('file', ref, { scan: crossUserMatch.scan!, scanError: null }, { bypassRbac: true })
+          )
+          return scanAttachmentOutput.parse(crossUserMatch.scan)
+        }
+        if (crossUserMatch?.scanError) {
+          await this.#core.db
+            .update('file', ref, { scanError: crossUserMatch.scanError, scan: null }, { bypassRbac: true })
+            .catch(() => {})
+          return this.#core.errors.nonRetryableError(
+            crossUserMatch.scanError.agentHint,
+            crossUserMatch.scanError.reason
+          )
+        }
+
+        let capturedDefect: FileScanError | undefined
+        try {
+          const scan = await this.#executeScanOcrAndClassify({
+            ref,
+            contentType: entry.contentType || 'application/pdf',
+            initialType: type,
+            types,
+            step,
+            onDefect: (d) => {
+              capturedDefect = d
+            }
+          })
+          await step('persist', () =>
+            this.#core.db.update('file', ref, { scan, scanError: null }, { bypassRbac: true })
+          )
+          return scanAttachmentOutput.parse(scan)
+        } catch (err) {
+          const defect = capturedDefect ?? classifyPermanentScanDefect(err)
+          if (defect) {
+            await this.#core.db
+              .update('file', ref, { scanError: defect, scan: null }, { bypassRbac: true })
+              .catch(() => {})
+            if (err instanceof this.#core.errors.NonRetryableError) throw err
+            return this.#core.errors.nonRetryableError(defect.agentHint, defect.reason)
+          }
+          throw err
+        }
+      }
+    )
+  }
+
+  #scanShortCircuit = async ({ input }: { input: ScanAttachmentInput }): Promise<ScanAttachmentOutput | undefined> => {
+    const entry = await this.#core.db.read('file', input.ref, false, { bypassRbac: true })
+    if (entry?.scan) return scanAttachmentOutput.parse(entry.scan)
+    if (entry?.scanError) {
+      return this.#core.errors.nonRetryableError(entry.scanError.agentHint, entry.scanError.reason)
+    }
+    return undefined
+  }
+
+  #scanTask = async ({
+    input,
+    step,
+    types,
+    preloadedFile
+  }: {
+    input: ScanAttachmentInput
+    step: StepRunner
+    types?: AttachmentTypesMap
+    preloadedFile?: SelectModel<'file'>
+  }): Promise<ProcessedAttachment> => {
+    try {
+      return { ref: input.ref, scan: await this.scan(input, { step, types, preloadedFile }) }
+    } catch (err) {
+      if (this.#core.errors.isNonRetryableError(err)) {
+        return { ref: input.ref, error: err instanceof Error ? err.message : String(err) }
+      }
+      return { ref: input.ref, error: 'Temporary scanning service unavailability. Please retry.' }
+    }
+  }
+
+  process = async (
+    raw: ProcessAttachmentsInput,
+    opts?: { types?: AttachmentTypesMap; step?: StepRunner }
+  ): Promise<ProcessAttachmentsOutput> => {
+    const tasks = extractAttachmentTasks(raw)
+    const step = opts?.step ?? this.#core.step
+
+    const uniqueRefs = [...new Set(tasks.map((t) => t.ref))]
+    const existingFiles = await this.#core.db.list('file', { ids: uniqueRefs }, { bypassRbac: true })
+    const fileMap = new Map<FileRef, SelectModel<'file'>>(existingFiles.map((f) => [f.id, f]))
+
+    const attachments = await step.map(
+      'process-attachments',
+      tasks,
+      (taskInput) =>
+        this.#scanTask({
+          input: taskInput,
+          step: this.#core.internals.workflows.createStepRunner('workflow'),
+          types: opts?.types,
+          preloadedFile: fileMap.get(taskInput.ref)
+        }),
+      {
+        timeout: `${this.#core.config.tasks.scanDeadlineSeconds}s`,
+        shortCircuit: (taskInput) => {
+          const fileDoc = fileMap.get(taskInput.ref)
+          if (fileDoc?.scan) {
+            return { ref: taskInput.ref, scan: scanAttachmentOutput.parse(fileDoc.scan) }
+          }
+          if (fileDoc?.scanError) {
+            return { ref: taskInput.ref, error: fileDoc.scanError.agentHint }
+          }
+          return undefined
+        }
+      }
+    )
+
+    return processAttachmentsOutput.parse({ attachments })
+  }
+
+  get internals() {
+    return {
+      scanShortCircuit: this.#scanShortCircuit
+    }
+  }
+}

package/src/attachments/utils.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+import type { FileScanError, UnparseableReason } from '../files'
+import {
+  getRegisteredAttachmentTypes,
+  processAttachmentsInput,
+  type AttachmentTypesMap,
+  type ProcessAttachmentsInput,
+  type ScanAttachmentInput
+} from './schema'
+
+export const schemaFor = (
+  type: string,
+  types: AttachmentTypesMap = getRegisteredAttachmentTypes()
+): Record<string, unknown> | undefined =>
+  type in types ? (z.toJSONSchema(types[type]!.schema, { io: 'output' }) as Record<string, unknown>) : undefined
+
+export const parseFields = (
+  type: string,
+  fields: Record<string, unknown>,
+  types: AttachmentTypesMap = getRegisteredAttachmentTypes()
+): Record<string, unknown> => (type in types ? (types[type]!.schema.parse(fields) as Record<string, unknown>) : {})
+
+export const extractAttachmentTasks = (input: ProcessAttachmentsInput): ScanAttachmentInput[] =>
+  processAttachmentsInput.parse(input).refs.map((item) => (typeof item === 'string' ? { ref: item } : item))
+
+export const buildScanError = (
+  reason: UnparseableReason,
+  agentHint: string,
+  diagnosticMessage?: string
+): FileScanError => ({
+  status: 'unparseable',
+  reason,
+  agentHint,
+  ...(diagnosticMessage ? { diagnosticMessage: diagnosticMessage.slice(0, 500) } : {}),
+  failedAt: new Date().toISOString()
+})
+
+export const extractHttpStatus = (err: unknown): number | undefined => {
+  if (!err || typeof err !== 'object') return undefined
+  const rec = err as Record<string, unknown>
+  if (typeof rec.statusCode === 'number') return rec.statusCode
+  if (typeof rec.status === 'number') return rec.status
+  const msg = err instanceof Error ? err.message : String(err)
+  const match = /\b(?:status(?:\s+code)?|http)\s*[:=]?\s*(4\d\d|5\d\d)\b/i.exec(msg)
+  return match?.[1] ? Number(match[1]) : undefined
+}
+
+const TRANSIENT_TOKENS = ['aborted', 'timed out', 'econnreset', 'etimedout', 'socket hang up', 'rate limit']
+
+const DEFECT_RULES: ReadonlyArray<{
+  reason: UnparseableReason
+  hint: string
+  match: (status: number | undefined, lower: string) => boolean
+}> = [
+  {
+    reason: 'PASSWORD_PROTECTED',
+    hint: 'This document is password-protected or encrypted and cannot be read. Please upload an unlocked copy of the document.',
+    match: (_, lower) => lower.includes('password') || lower.includes('encrypted')
+  },
+  {
+    reason: 'UNSUPPORTED_FORMAT',
+    hint: 'This file format is not supported by the document scanner. Please upload a valid PDF or standard image (JPEG, PNG, WebP).',
+    match: (status, lower) =>
+      status === 415 || lower.includes('unsupported media') || lower.includes('unsupported format')
+  },
+  {
+    reason: 'EMPTY_OR_UNREADABLE',
+    hint: 'The uploaded document appears blank or unreadable. Please upload a clear, legible scan or photo of the document.',
+    match: (_, lower) =>
+      lower.includes('empty description') ||
+      lower.includes('empty_or_unreadable') ||
+      lower.includes('no readable text')
+  },
+  {
+    reason: 'CLASSIFICATION_REJECTED',
+    hint: 'The document could not be classified into a valid document type. Please upload a clear, complete document.',
+    match: (_, lower) => lower.includes('classification_rejected')
+  },
+  {
+    reason: 'CORRUPTED_FILE',
+    hint: 'This file appears corrupted or malformed and could not be parsed. Please export or re-upload a valid PDF or image file.',
+    match: (status, lower) =>
+      status === 400 ||
+      status === 422 ||
+      lower.includes('corrupt') ||
+      lower.includes('malformed') ||
+      lower.includes('invalid pdf') ||
+      lower.includes('invalid image') ||
+      lower.includes('failed to process document') ||
+      lower.includes('could not parse')
+  }
+]
+
+export const classifyPermanentScanDefect = (err: unknown): FileScanError | null => {
+  if (!err) return null
+  const bodyStr =
+    typeof err === 'object' && 'body' in err && typeof (err as { body?: unknown }).body === 'string'
+      ? (err as { body: string }).body
+      : ''
+  const msg = `${err instanceof Error ? err.message : String(err)} ${bodyStr}`.trim()
+  const lower = msg.toLowerCase()
+  const status = extractHttpStatus(err)
+
+  if (
+    status === 408 ||
+    status === 429 ||
+    (status !== undefined && status >= 500) ||
+    TRANSIENT_TOKENS.some((t) => lower.includes(t))
+  ) {
+    return null
+  }
+
+  const matched = DEFECT_RULES.find((rule) => rule.match(status, lower))
+  return matched ? buildScanError(matched.reason, matched.hint, msg) : null
+}

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export * from './schema'
+export { AuthService } from './service'
+export { coreAuthRoutes } from './routes'