Payroll Journal

There is no Gusto integration in this codebase. Payroll is run in Gusto, Gusto posts a journal entry into QuickBooks Online for each run, and this application connects to QuickBooks. PRD.md records the chain plainly: “Gusto → QuickBooks → App pipeline for payroll data”.

The consequence is that the application receives accounting artefacts rather than payroll records. A journal entry does not have a field called gross pay. It has a set of lines, each with an amount, a posting type of Debit or Credit, an account reference, an optional description, and sometimes an entity reference naming an employee. Everything the payroll dashboard shows has to be inferred from those lines.

This is why the parser is the largest single piece of domain logic in the repository, and why it is tested against twenty-one hand-constructed journal entries covering benefit deductions, missing cash accounts, absent employee references and empty line arrays.

A standard authorisation-code flow, with two details worth noting: the state token is 32 bytes of randomness rendered as 64 hex characters, and the token response carries two independent lifetimes — one hour for access, 101 days for refresh.

Scopes and endpoints

Only the accounting scope is requested by default; the others are available to generateAuthorizationUrl(state, scopes) as an override. Environment defaults to sandbox when QUICKBOOKS_ENVIRONMENT is unset, so a misconfigured deployment talks to the sandbox rather than to live company data.

Configuration and its failure modes

getQuickBooksConfig() reads four variables and throws a distinct message for each of the three that are mandatory. The messages are asserted individually, which makes a misconfiguration self-diagnosing.

QUICKBOOKS_CLIENT_ID      missing → 'QUICKBOOKS_CLIENT_ID environment variable is not set'
QUICKBOOKS_CLIENT_SECRET  missing → 'QUICKBOOKS_CLIENT_SECRET environment variable is not set'
QUICKBOOKS_REDIRECT_URI   missing → 'QUICKBOOKS_REDIRECT_URI environment variable is not set'
QUICKBOOKS_ENVIRONMENT    missing → defaults to 'sandbox'  // does not throw

Client behaviour

request(path)

Prefixes /v3/company/<realmId> and sends Authorization: Bearer <access token>. Retries 5xx after a base delay; does not retry 4xx — a 404 issues exactly one fetch.

Error parsing

Intuit's Fault.Error[0].Message is lifted into the thrown QuickBooksError, so callers see 'Object Not Found' rather than a JSON blob.

getCompanyInfo()

Hits /companyinfo/<realmId>. Used to confirm a connection is live.

queryJournalEntries(start?, end?)

Builds SELECT * FROM JournalEntry, appending TxnDate >= '…' and TxnDate <= '…' when bounds are supplied, and URL-encodes the whole statement into a ?query= parameter.

revokeToken(token)

Resolves on success and on 400 — a token that is already revoked is not an error. Any other failure throws 'Failed to revoke token'.

The 600 row exists because the retry predicate is a bounded range check rather than status >= 500. A malformed status outside the HTTP range is not retried.

A QuickBooks refresh token is a hundred-day credential to a company's accounting file. It is stored encrypted, with a key derived per-record rather than reused.

13const SALT_LENGTH     = 16;
14const IV_LENGTH       = 12;
15const AUTH_TAG_LENGTH = 16;
16const KEY_LENGTH      = 32;

// stored value = base64( salt | iv | authTag | ciphertext )
//                        16     12      16       remainder

18function deriveKey(masterKey, salt) {
19  return crypto.scryptSync(masterKey, salt, KEY_LENGTH);
20}

// decrypt: slice the four regions, re-derive the key from the
// embedded salt, then aes-256-gcm with the embedded auth tag
39const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
40decipher.setAuthTag(authTag);

The salt is stored alongside the ciphertext, so every encryption derives a fresh key from the same master secret. That is what makes the next property possible.

Properties asserted of the token cipher

Expiry arithmetic

isRefreshTokenExpired takes no buffer — it is a plain comparison against the present moment. There is nothing useful to do with a nearly-expired refresh token except use it.

parseGustoJournalEntry(entry) is pure: a journal entry in, a ParsedPayrollData out, no I/O. Amounts arrive from QuickBooks in dollars and leave in cents.

Is this entry payroll?

Three tests establish the detection rule, and a fourth establishes what it must reject.

By note

The string Gusto appearing in PrivateNote is sufficient on its own — an entry noted “Payroll by Gusto — week ending …” is recognised even with only a generic Wages/Cash pair of lines.

By shape

With no Gusto marker at all, an entry debiting Salaries Expense and crediting Payroll Tax Liability and a bank account is still recognised.

Rejection

An entry debiting Office Supplies and crediting Accounts Payable returns isGustoPayroll: false.

Empty

An entry with an empty Line array returns all four totals as 0, no employee payments, and isGustoPayroll: false — it does not throw.

Pay period

The period is scavenged from the note. An ISO range such as Period: 2024-01-16 - 2024-01-31 is parsed into periodStart and periodEnd exactly. Where no range can be found, periodEnd is the TxnDate and periodStart is set fourteen days earlier — a fortnightly assumption, applied silently.

Each of the following account names is exercised by a test that constructs a journal entry around it and asserts the parser reaches the right conclusion. Matching is case-insensitive: PAYROLL EXPENSE and CHECKING ACCOUNT appear in the fixtures specifically to prove it.

A separate fixture demonstrates the tax bucket accumulating across four distinct account names in one entry — Federal Tax Payable, State Tax Payable, Social Security Payable and Medicare Payable — summing to a single totalTaxes. Individual tax types are not preserved; the schema has one taxes column, not four.

Some journal entries name employees; some do not. The parser handles both, and normalises the two naming conventions it encounters into one.

Where a description uses the accounting convention Surname, Forename, it is rewritten into natural order before storage. The transformation is asserted directly, so the same person never appears twice under two orderings.

Pay types

payroll_line_items.pay_type is NOT NULL, so every line needs a classification. Four values are produced, matched from the description text.

salary is the default, not a match. An unrecognised description is recorded as salaried rather than rejected or left null.

Payroll and contractor spend arrive by two different routes and land in the same tables. src/lib/quickbooks/team-compensation.ts is the module that reads them back as one picture, and it is the newest substantial feature in the repository.

The organising idea is a five-value classification stored on employees.employment_type. Migration 0002 introduced the column with the default 'w2_fulltime'; the other four values are written by the seed and setup paths.

The numeric order is a literal sort map in team-compensation.tsx; within a class, members are ordered by total paid, descending. Only the first two classes count toward the “fulltime team” headcount on the payroll page, which filters is_active = true AND employment_type IN ('w2_fulltime','1099_fulltime').

How a total is assembled

fetchTeamCompensation(months) takes a lookback in months, or null meaning year to date — in which case the window starts at 1 January of the current year. It selects active employees, splits them by classification, and for each person sums gross_pay across payroll_line_items joined to payroll_runs where the pay date falls inside the window. Each member comes back as { id, name, employmentType, totalPaid, paymentCount, lastPayment }, with amounts in cents.

Filtering out the parser's own artefacts

Because employees are created automatically from names parsed out of journal entries, a mis-parse becomes a person. The module carries a literal exclusion list to undo that.

const INVALID_EMPLOYEE_NAMES = ['Regular Wages', 'Bonus', 'Debit tax', 'Debit net pay'];

These are Gusto journal line labels — the same four strings the totalling regexes key on. When extractEmployeePayments falls back to reading a name out of a description, a line described Debit net pay yields an “employee” of that name. The same four strings are also hard-coded into POST /api/debug/cleanup-employees, which deactivates any employee row matching them.

The presentation layer, src/components/payroll/team-compensation.tsx, is a pure function of its props: a card per classification, each with a count badge and a right-aligned total, and a row per member showing payment count and last payment date. It hard-codes no names and no figures.

check-qb.js sits at the repository root: a ninety-seven-line diagnostic that bypasses the application entirely. It opens the database directly with @neondatabase/serverless, decrypts the stored access token with a local copy of the crypto routine, and queries QuickBooks for recent journal entries so a developer can see the raw line structure the parser will receive.

$ node check-qb.js

ENCRYPTION_KEY loaded: true
Realm ID: <redacted>
Access token decrypted, length: 1024
Querying QuickBooks for journal entries...

[ entry dump withheld — the remaining output is live accounting data:
  journal ids, private notes, document numbers, totals and per-line
  account names and amounts. It is not reproduced in this record. ]

// the withheld section prints, per entry:
//   Entry <n> - ID: <id>, Date: <TxnDate>
//     PrivateNote: <note or "(none)">
//     DocNumber:   <number or "(none)">
//     Total:       $<TotalAmt>
//     Lines:       <count>
//       - $<Amount> <PostingType> "<AccountRef.name>" <Description>

Label strings are quoted verbatim from check-qb.js; the values are withheld. The token length shown is illustrative of the field's magnitude only. The script's query is SELECT * FROM JournalEntry WHERE TxnDate >= '2024-01-01' MAXRESULTS 20 against the production host, and it prints the first five lines of each entry.

Coverage gaps on this cluster

Four items in TASKS.md Phase 10 remain unticked, and all four are tests. The OAuth client, the token cipher and the journal parser are covered; the parts that write to the database and render the page are not.

Consistent with the file listing: there is no __tests__/components/payroll/ directory, and none of the eight payroll and compensation handlers is invoked anywhere in tool-handlers.test.ts — though all eight are implemented.

The debug surface

Nine routes live under src/app/api/debug/, all of them written to support this payroll work: dumping QuickBooks journal entries, exercising the parser against live data, re-running the payroll sync, reconciling against a Gusto export, and repairing employee rows the parser created in error. Four carry an explicit DELETE THIS ENDPOINT BEFORE PRODUCTION! comment.

They are unauthenticated. src/middleware.ts lists /api/debug(.*) among its public matchers — with its own comment, // Debug endpoints (REMOVE IN PRODUCTION) — and no route file performs a check of its own. Four mutate data, one of them destructively. Because their whole purpose is to print payroll internals, their responses are the most sensitive in the application. They are enumerated on Sheet 6, and no output from any of them appears in this record.