PSA/ee/docs/plans/2026-01-14-extension-invoicing-manual-invoices/SCRATCHPAD.md

Scratchpad — Extension Invoicing (Manual Invoice MVP)

• Plan slug: extension-invoicing-manual-invoices
• Created: 2026-01-14

What This Is

Rolling notes for implementing an invoicing host API capability for extensions (MVP: create draft manual invoices).

Starting Context / Relevant Existing Code

• Capability registry: ee/server/src/lib/extensions/providers.ts
• Install config + provider grants: ee/server/src/lib/extensions/installConfig.ts
• Gateway passes install + providers + user info to Runner:
  • server/src/app/api/ext/[extensionId]/[[...path]]/route.ts
• Existing internal host API pattern (scheduler):
  • Server host API: ee/server/src/lib/extensions/schedulerHostApi.ts
  • Internal route: ee/server/src/app/api/internal/ext-scheduler/install/[installId]/route.ts
  • Runner calls internal route: ee/runner/src/engine/host_api.rs (scheduler_request)
  • Runner capability constants: ee/runner/src/providers/mod.rs
  • WIT: ee/runner/wit/extension-runner.wit
  • JS SDK types: sdk/extension-runtime/src/index.ts

Invoice Domain Touchpoints

• Manual invoice API route (user-authenticated):
  • server/src/app/api/v1/invoices/manual/route.ts
  • server/src/lib/api/controllers/ApiInvoiceController.ts → invoiceService.generateManualInvoice(...)
• Core manual invoice creation expects permissions + user attribution:
  • server/src/lib/api/services/InvoiceService.ts (generateManualInvoice uses context.userId)
• Manual invoice schemas (for input shape parity):
  • server/src/lib/api/schemas/invoiceSchemas.ts (manualInvoiceRequestSchema, manualInvoiceItemSchema)

Open Decisions

• Capability naming: decided cap:invoice.manual.create
• Authorization model: decided capability-only (no user required)
• Output shape: decided minimal { invoiceId, invoiceNumber, totals }
• Inputs: decided include invoice header fields (invoiceDate, dueDate, poNumber)
• Prepayments: deferred (no isPrepayment / expirationDate in MVP)
• Invoice attribution (MVP): implemented using a tenant user id fallback (first users.user_id for tenant) to satisfy required created_by fields when persisting invoice charges. This is a stopgap until we add a dedicated “extension/system principal” strategy.

Commands / Runbooks

• Validate plan folder: python3 scripts/validate_plan.py ee/docs/plans/2026-01-14-extension-invoicing-manual-invoices

Implementation Notes

• server/src/lib/services/invoiceService.ts now uses import type { Session } from 'next-auth' and a dynamic import for getSession() so the shared invoice helpers can be imported from non-Next contexts (e.g., EE server tests / host APIs) without pulling in next-auth at module load time.
• SDK sample extension: sdk/samples/component/invoicing-demo/ demonstrates host.invoicing.createManualInvoice from an iframe UI.