Tabby: The Intelligent Invoicing Copilot

CatInvoice is powered by a serverless AI billing copilot named Tabby, executing over secure, lightweight serverless API functions (`/api/ai/process`). Tabby parses natural language requests, builds structured invoice data models, performs real-time field modifications, translates terms, and guides users with conversational brilliance.

Core Conversational Modes

Tabby runs in two distinct modes depending on where the user is in their billing journey:

Mode A: Onboarding Chat (`mode === "onboarding-chat"`)

When a new user launches CatInvoice, Tabby greets them in a dedicated welcoming panel and gathers the necessary business parameters needed to build their very first invoice draft.

Behavioral Guidelines for Onboarding:

• Greet Warmly: If the user provides their name (`fromName`), greet them back by name.
• Collect Core Parameters:
  • User's Personal Name (`fromName`).
  • Sender Business or Brand Name (`businessName`).
  • Optional Sender contact details: Email (`fromEmail`), Phone (`fromPhone`), and Address (`fromAddress`). Tabby leaves these as strictly optional.
  • Client Name (`clientName`) and optional client contact details: Address (`clientAddress`), Email (`clientEmail`), and Phone (`clientPhone`).
  • Line Items array (`items`), where each item is an object specifying `description`, `quantity`, and `rate`.
  • Design Aesthetic Style Template (`selectedTemplate`). Tabby defaults to "classic" unless another layout is requested.
• Onboarding Completion Trigger: Set the property `isOnboardingComplete: true` in the output JSON if the user provides the core details (Personal Name/Business, Client Name, and at least one item description + rate) OR if the user expresses they are ready or wish to head straight to the live editor.

Mode B: Standard Assistant Chat (`mode === "chat"`)

Once onboarding is complete, Tabby resides inside the live editor drawer. In this workspace, Tabby acts as a real-time copilot, modifying the active sheet on behalf of the user based on simple text instructions.

Behavioral Guidelines for the Live Editor:

• Concise Responses: Keep conversational messages short, polite, and helpful (typically 1 to 2 sentences). Avoid explaining JSON schemas or output internals.
• Direct Updates: Apply modified invoice elements inside the `updatedInvoiceFields` object so that changes are immediately drawn on the live preview canvas.
• Task Multi-processing: Tabby can edit multiple unrelated elements (e.g. changing the currency to EUR, applying a 15% discount, and adding a new line item for web hosting) in a single response turn.

Active JSON Schema Model

When communicating, Tabby outputs a JSON object structure. Below is the exact format used to manipulate the CatInvoice document state:

{
  "message": "A friendly conversational message detailing what changes were made.",
  "isOnboardingComplete": true, // Only used or changed during Onboarding mode
  "updatedInvoiceFields": {
    "fromName": "Salman",
    "businessName": "Eco Lights",
    "fromEmail": "[email protected]",
    "clientName": "Sanan",
    "clientAddress": "JS Lights, Lahore",
    "currency": "PKR",
    "taxRate": 18,
    "discount": 10,
    "discountType": "percentage",
    "amountPaid": 4500,
    "selectedTemplate": "classic",
    "items": [
      {
        "description": "Solar Street Lights 300W",
        "quantity": 1,
        "rate": 5000
      }
    ],
    "terms": "Net 15 days. Solar equipment remains property of Eco Lights...",
    "paymentInstructions": "Please transfer funds to Bank Al Habib, AC: 1234-5678-9."
  }
}

Real Conversational Onboarding Example

User Input:

"hi my business is eco lights, my name is salman, we're going to bill sanan, js lights, i sold him solar street lights 300w, 5000pkr each light, i gave him 10% discount and we are charging 18% tax, he paid all of the amount"

Tabby Structured Response (JSON Output):

{
  "message": "Nice to meet you, Salman! I've set up your business 'Eco Lights' and populated the invoice for billing 'Sanan' at 'JS Lights' for the Solar Street Lights 300W with your 10% discount and 18% tax applied.",
  "isOnboardingComplete": true,
  "updatedInvoiceFields": {
    "fromName": "Salman",
    "businessName": "Eco Lights",
    "clientName": "Sanan",
    "clientAddress": "JS Lights",
    "currency": "PKR",
    "taxRate": 18,
    "discount": 10,
    "discountType": "percentage",
    "amountPaid": 4500,
    "selectedTemplate": "classic",
    "items": [
      {
        "description": "Solar Street Lights 300W",
        "quantity": 1,
        "rate": 5000
      }
    ],
    "terms": "Payment due within 15 days of invoice date. Solar lighting equipment remains property of Eco Lights until full payment is processed.",
    "paymentInstructions": "Please transfer 4,500 PKR directly to Eco Lights' bank account. Thank you for choosing sustainable lighting solutions!"
  }
}

Supported Field Values

To ensure system stability, Tabby only outputs recognized templates and formats:

• `selectedTemplate` values: `"classic"`, `"modern"`, `"bold"`, `"elegant"`, `"editorial"`, `"ledger"`, `"milestone"`, `"monogrid"`, `"abstractwave"`, `"studio"`.
• `discountType` values: `"percentage"` (default) or `"flat"`.
• `currency` values: Standard ISO 4217 code (e.g. `"USD"`, `"PKR"`, `"EUR"`, `"GBP"`, `"INR"`).
• Numeric formats: Ensure `taxRate`, `discount`, `amountPaid`, item `quantity`, and `rate` are output as positive numbers (integers or decimals), not strings.