TimeBill — Friday Invoice Run

remedy:
  id: timebill.invoice-run
  name: TimeBill — Friday Invoice Run
  domain: timebill
kind: tool
intent: >
  Pull the past week's Toggl time entries, group them by client, draft invoices
  in Xero, let the operator review and confirm per-invoice before submission.
  The canonical weekly Friday workflow.
owners:
  - petitgen-ltd
  - [email protected]
tags:
  - invoicing
  - toggl
  - xero
  - weekly
entities:
  - time-entry
  - client
  - invoice
  - line-item
files:
  spec:
    ext: .md
    path: SPEC.md
    required: true
  design:
    ext: .md
    pattern: design/*.md
    required: false
  fixtures:
    ext: .yml
    pattern: fixtures/*.yml
    required: false
features:
  - id: pull-week-entries
    intent: Fetch the past 7 days of time entries from Toggl for the active workspace.
    triggers:
      - user.invokes: pull-week
    preconditions:
      - toggl.credentials.present
    steps:
      - fetch: toggl.time_entries
      - filter: within-last-week
      - persist: time-entries
    outputs:
      - time-entries.count
    errors:
      - toggl.unauthorised
      - toggl.rate-limited
    tags:
      - ingest
    version: 0.1.0
  - id: group-by-client
    intent: Group time entries by Toggl client and resolve to a Xero contact.
    triggers:
      - after: pull-week-entries
    steps:
      - group: time-entries by-client
      - resolve: toggl-client to xero-contact
      - flag: unresolved-clients
    outputs:
      - client-groups
      - unresolved-clients
    errors:
      - xero.contact-not-found
    tags:
      - transform
    version: 0.1.0
  - id: draft-invoices
    intent: Draft one Xero invoice per resolved client from the week's entries.
    triggers:
      - after: group-by-client
    preconditions:
      - xero.credentials.present
      - unresolved-clients.count: 0
    steps:
      - for-each: client-group
      - compose: invoice from entries
      - create: xero.invoice (status=draft)
    outputs:
      - draft-invoice.ids
    errors:
      - xero.unauthorised
      - xero.invalid-line-item
    tags:
      - xero
      - draft
    version: 0.1.0
  - id: confirm-and-submit
    intent: Operator reviews each draft; approved drafts are sent; rejected are
      discarded.
    triggers:
      - after: draft-invoices
    steps:
      - present: drafts to-operator
      - collect: per-draft decision { approve | reject | edit }
      - submit: approved-drafts
      - archive: run-summary
    outputs:
      - submitted.count
      - rejected.count
    errors:
      - xero.submit-failed
    tags:
      - operator
      - submit
    version: 0.1.0
flows:
  - id: friday-run
    intent: The full weekly loop from Toggl pull to Xero submission.
    steps:
      - invoke: pull-week-entries
      - invoke: group-by-client
      - invoke: draft-invoices
      - invoke: confirm-and-submit
    outputs:
      - submitted.count
    version: 0.1.0
integrations:
  - toggl
  - xero
permissions:
  operator:
    - pull-week-entries
    - draft-invoices
    - confirm-and-submit
  viewer:
    - pull-week-entries
ui:
  landing: flow.friday-run
  density: comfortable
design:
  palette: petitgen-dark
  voice: direct; no emoji; weekly-ritual tone
runtime: sovereign
version: 0.1.0