@corgelabs/corge 0.0.1 → 1.0.0

package/infra/firestore.base.indexes.json

@@ -0,0 +1,138 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "chat",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "chat",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "file",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "messages",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "messages",
+      "queryScope": "COLLECTION",
+      "fields": [
+        {
+          "fieldPath": "embedding",
+          "vectorConfig": { "dimension": 768, "flat": {} }
+        }
+      ]
+    },
+    {
+      "collectionGroup": "messages",
+      "queryScope": "COLLECTION_GROUP",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        {
+          "fieldPath": "embedding",
+          "vectorConfig": { "dimension": 768, "flat": {} }
+        }
+      ]
+    },
+    {
+      "collectionGroup": "email_log",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "externalMessageId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "email_log",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "to", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "email_log",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "payment_usage",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "payment_transaction",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "userId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "payment_customer",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "stripeCustomerId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "payment_customer",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dodoCustomerId", "order": "ASCENDING" },
+        { "fieldPath": "deleted", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": [
+    {
+      "collectionGroup": "_tasks",
+      "fieldPath": "expiresAt",
+      "ttl": true,
+      "indexes": []
+    },
+    {
+      "collectionGroup": "auth_tokens",
+      "fieldPath": "expiresAt",
+      "ttl": true,
+      "indexes": []
+    },
+    {
+      "collectionGroup": "_idempotency",
+      "fieldPath": "expiresAt",
+      "ttl": true,
+      "indexes": []
+    }
+  ]
+}

package/infra/firestore.base.rules

@@ -0,0 +1,152 @@
+rules_version = '2';
+
+// ===============================================================
+// Assumed Data Model
+// ===============================================================
+//
+// All mutations and schema enforcement happen server-side through the
+// Firebase Functions 2nd Gen backend (firebase-admin/firestore with
+// defineCollection, z.strictObject(), and mandatory FirestoreDataConverter<T>)
+// in me-central1. Direct client SDK writes are denied across all collections.
+//
+// Collection: user/{userId}
+// Document ID: Firebase Auth UID
+// Fields (enforced server-side):
+//   - id: string (required, immutable)
+//   - email: string (required, valid email)
+//   - displayName: string (optional)
+//   - role: string ('user' | 'admin')
+//   - createdAt: timestamp (required, immutable)
+//   - updatedAt: timestamp (required)
+//
+// Collection: chat/{chatId}
+// Document ID: Auto-generated ID (entryId: ^[A-Za-z0-9_-]{1,128}$)
+// Fields (enforced server-side via coreCollections.chat):
+//   - id: string (required, immutable, entryId)
+//   - userId: string (required, immutable, owner UID)
+//   - agentId: string | null (optional, agent identifier)
+//   - title: string | null (optional)
+//   - model: string | null (optional, model identifier)
+//   - messageCount: int (required, defaults to 0, non-negative)
+//   - summary: string | null (optional, rolling conversation summary)
+//   - activeGenerationId: string | null (optional, active stream generation ID)
+//   - deleted: bool (required, defaults to false, soft-delete flag)
+//   - createdAt: timestamp (required, immutable)
+//   - updatedAt: timestamp (required)
+//
+// Subcollection: chat/{chatId}/messages/{messageId}
+// Document ID: Auto-generated ID (entryId: ^[A-Za-z0-9_-]{1,128}$)
+// Fields (enforced server-side):
+//   - id: string (required, immutable, entryId)
+//   - chatId: string (required, immutable, parent chat entryId)
+//   - userId: string (required, immutable, owner UID)
+//   - role: string (required, 'system' | 'user' | 'assistant' | 'tool')
+//   - content: string (required, message text)
+//   - parts: list | null (optional, structured message parts)
+//   - toolInvocations: list | null (optional, tool call/result metadata)
+//   - attachments: list<string> | null (optional, attached fileRef IDs)
+//   - tokenCount: int | null (optional, non-negative)
+//   - cancelled: bool (optional, defaults to false)
+//   - createdAt: timestamp (required, immutable)
+//   - embedding: vector | list<float> | null (optional, 768-dim vector embedding)
+//
+// Collection: file/{fileId}
+// Document ID: Auto-generated ID (fileRef: ^[A-Za-z0-9_-]{1,128}_[a-f0-9]{24}$)
+// Fields (enforced server-side via coreCollections.file):
+//   - id: string (required, immutable, fileRef)
+//   - userId: string (required, immutable, owner UID)
+//   - shaSum: string (required, SHA-256 hex digest)
+//   - fileName: string (required)
+//   - contentType: string (required, MIME type)
+//   - size: int (required, non-negative)
+//   - scan: map | null (optional, fileScan metadata)
+//   - scanError: map | null (optional, fileScanError negative cache metadata)
+//   - deleted: bool (required, defaults to false, soft-delete flag)
+//   - createdAt: timestamp (required, immutable)
+//   - updatedAt: timestamp (required)
+//
+// Server-Only Admin SDK Collections (zero direct client read/write access;
+// denied by the default `match /{document=**} { allow read, write: if false; }` fallback rule):
+//   - email_log/{emailId}: Transactional email delivery & webhook audit log (coreCollections.email_log)
+//   - email_suppression/{emailHash}: Hard-bounce, spam-complaint & manual suppression list (coreCollections.email_suppression)
+//   - user_auth_meta/{userId}: Internal authentication & linked OAuth provider metadata (coreCollections.user_auth_meta)
+//   - auth_tokens/{tokenId}: Hashed verification, password-reset & recovery tokens (coreCollections.auth_tokens)
+//   - payment_customer/{userId}: 1:1 customer billing state, active subscription tier & bonus token balances (coreCollections.payment_customer)
+//   - payment_usage/{usageId}: Per-period AI token & custom metric consumption ledger (coreCollections.payment_usage)
+//   - payment_transaction/{txId}: Immutable payment & webhook event audit ledger (coreCollections.payment_transaction)
+//   - _tasks/{taskId}: Durable task queue state & execution leases
+//   - _idempotency/{key}: Request & webhook idempotency locks
+//   - _system/{docId}: Internal system state, rate limits & circuit-breaker metadata
+//
+// ===============================================================
+
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    // ===============================================================
+    // Helper Functions
+    // ===============================================================
+
+    function isAuthenticated() {
+      return request.auth != null;
+    }
+
+    function isOwner(userId) {
+      return isAuthenticated() && request.auth.uid == userId;
+    }
+
+    function isAdmin() {
+      return isAuthenticated() && (request.auth.token.admin == true || request.auth.token.role == 'admin');
+    }
+
+    function isResourceOwner() {
+      return isAuthenticated() && resource.data.userId == request.auth.uid;
+    }
+
+    function isNotDeleted() {
+      return resource.data.deleted != true;
+    }
+
+    // ===============================================================
+    // Collection Rules
+    // ===============================================================
+
+    // User profiles: owners can read their own profile, admins can read any profile.
+    // All writes are server-side only via Firebase Admin SDK.
+    match /user/{userId} {
+      allow read: if isOwner(userId) || isAdmin();
+      allow write: if false;
+    }
+
+    // Chats: authenticated users can read non-deleted chats they own.
+    // All writes are server-side only via Firebase Admin SDK.
+    match /chat/{chatId} {
+      allow read: if request.auth != null && resource.data.userId == request.auth.uid && resource.data.deleted != true;
+      allow write: if false;
+    }
+
+    // Chat messages: authenticated users can read messages they own (including collectionGroup('messages') queries).
+    // All writes are server-side only via Firebase Admin SDK.
+    match /chat/{chatId}/messages/{messageId} {
+      allow read: if request.auth != null && resource.data.userId == request.auth.uid;
+      allow write: if false;
+    }
+
+    match /{path=**}/messages/{messageId} {
+      allow read: if request.auth != null && resource.data.userId == request.auth.uid;
+      allow write: if false;
+    }
+
+    // File metadata: authenticated users can read non-deleted file metadata they own.
+    // All writes are server-side only via Firebase Admin SDK.
+    match /file/{fileId} {
+      allow read: if request.auth != null && resource.data.userId == request.auth.uid && resource.data.deleted != true;
+      allow write: if false;
+    }
+
+    // Default fallback: deny all direct client reads and writes across all other paths.
+    match /{document=**} {
+      allow read, write: if false;
+    }
+  }
+}

package/infra/storage.base.rules

@@ -0,0 +1,8 @@
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /{allPaths=**} {
+      allow read, write: if false;
+    }
+  }
+}

package/package.json

@@ -1,18 +1,64 @@
 {
   "name": "@corgelabs/corge",
-  "version": "0.0.1",
-  "description": "Corge (Core + Forge) — All-in-one Serverless AI, MCP & Durable Workflow SDK for modern Agentic SaaS.",
+  "version": "1.0.0",
+  "description": "Corge: High-load serverless AI, durable workflow, payments & auth SDK for GCP Cloud Functions v2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/corgelabs/corge.git"
+  },
   "type": "module",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "keywords": [
-    "corge",
-    "ai",
-    "mcp",
-    "agentic",
-    "saas",
-    "workflow",
-    "sdk"
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "corge": "./dist/bin/corge.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./spec": "./docs/SDK_SPEC.md"
+  },
+  "files": [
+    "dist",
+    "src",
+    "infra",
+    "tests",
+    "docs/SDK_SPEC.md",
+    "tsconfig.base.json"
   ],
-  "license": "MIT"
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --platform=node --target=node24 --format=esm --packages=external --sourcemap --outfile=dist/index.js && esbuild bin/corge.ts --bundle --platform=node --target=node24 --format=esm --packages=external --banner:js=\"#!/usr/bin/env node\" --outfile=dist/bin/corge.js && chmod +x dist/bin/corge.js",
+    "check": "tsc --noEmit",
+    "test": "node dist/bin/corge.js test",
+    "test:chaos": "node dist/bin/corge.js test:chaos",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "dependencies": {
+    "@ai-sdk/google-vertex": "^5.0.121",
+    "@hono/node-server": "^1.19.17",
+    "@mistralai/mistralai": "^2.7.0",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@typesafe-ai/sdk": "^0.7.0",
+    "ai": "^7.0.150",
+    "esbuild": "^0.25.0",
+    "firebase-admin": "^14.5.0",
+    "firebase-functions": "^7.0.0",
+    "hono": "^4.13.13",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2"
+  },
+  "overrides": {
+    "body-parser": "^2.4.0",
+    "uuid": "^11.1.1",
+    "zod": "^4.6.7"
+  }
 }

package/src/ai/index.ts

@@ -0,0 +1,2 @@
+export * from './schema'
+export { AiService } from './service'

package/src/ai/schema.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+
+export type JevQuestion =
+  | { type: 'noul'; instructions: string; criteria?: { true: string; false: string } }
+  | { type: 'choice'; instructions: string; criteria: Record<string, string> }
+  | { type: 'score'; instructions: string; criteria: string[] }
+
+export const answerSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('noul'), noul: z.number().min(0).max(1) }),
+  z.object({
+    type: z.literal('choice'),
+    choice: z.string(),
+    probabilities: z.record(z.string(), z.number()),
+    confidence: z.number()
+  }),
+  z.object({
+    type: z.literal('score'),
+    score: z.number(),
+    probabilities: z.record(z.string(), z.number()),
+    confidence: z.number()
+  })
+])
+
+export const envelopeSchema = z.object({ model: z.string(), answers: z.record(z.string(), answerSchema) })
+
+export interface AiUsageSummary {
+  model: string
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+  pages?: number
+}
+
+export type JevAnswer = z.infer<typeof answerSchema>
+export type DecideResult = z.infer<typeof envelopeSchema> & { usage?: AiUsageSummary }
+
+export interface VisionOptions {
+  schema?: Record<string, unknown>
+  prompt?: string
+  fallbackVision?: boolean
+  signal?: AbortSignal
+}
+
+export interface VisionResult {
+  markdown: string
+  annotation: Record<string, unknown>
+  usage?: AiUsageSummary
+}
+
+export interface AiGenerateOptions<O = string> {
+  model?: string
+  system?: string
+  schema?: z.ZodType<O>
+  signal?: AbortSignal
+}
+
+export interface AiGenerateResult<O = string> {
+  text: string
+  output: O
+  usage: unknown
+}
+
+export const DEFAULT_EXTRACTION_PROMPT =
+  'Extract the document fields as JSON matching the schema. Transcribe values exactly as printed, translate non-English into English, transliterate names, use Western digits. Empty string if not visible.'