kempo-tax 0.2.0 → 0.2.2

package/README.md

@@ -117,10 +117,22 @@ is different: it says "sold here, no tax", and it is reported on a return as an
 | `rate` | A percentage with up to four decimals: `6`, `7.25`, `6.625` |
 | `level` | `country`, `state`, `county`, `city`, `district` or `special` — worked out from the place if left blank |
 | `appliesToShipping` | Whether this row taxes shipping charges. Shipping is only taxed by rows that say so |
+| `shippingProportional` | With `appliesToShipping`: tax shipping only in proportion to the taxable goods. See below |
 | `effectiveFrom` / `effectiveTo` | `YYYY-MM-DD`. `effectiveTo` is exclusive |
 | `jurisdiction`, `label` | The name a report uses, and the name a receipt may show |
 | `priority`, `enabled`, `note` | |
 
+### Shipping
+
+A row with `appliesToShipping` taxes the shipping charge **in full**. Add `shippingProportional` and
+it taxes only the share of shipping that matches the taxable goods in the order: with $49.99 of
+taxable goods, $10.00 of exempt goods and $8.00 of shipping, five-sixths of the shipping is taxed.
+Which one applies is your tax authority's rule, and some states work proportionally. Stripe does for
+Vermont, which is why this exists: the two providers agree to the cent on the same cart.
+
+Proportional applies to tax added on top. A tax-inclusive shipping charge is taxed in full, because
+the tax already inside a price cannot be split by what else was bought.
+
 ### A rate is ended, not edited
 
 When a rate changes, **end** the old row and add a new one. A sale quoted last month must still be
@@ -316,22 +328,33 @@ should refuse to complete.
 and Avalara are the intended extensibility targets — each a new file there, not a change to
 anything that ever called `calculateTax`.
 
-### Verifying the Stripe provider
-
-The Stripe module is written against the installed SDK's own type definitions and its request and
-response shaping is covered by tests, but **the default test run never calls Stripe**, and it has
-not been exercised against a live account in this repository. Before relying on it:
-
-1. Use a **test-mode** key from an account with Stripe Tax switched on, and a head office address.
-2. On **Settings**, save the key, set provider to Stripe, and open the **Where tax is collected**
-   tab — it should report the account as active.
-3. Add a test registration for a place in the dashboard, then **Try a calculation** for an address
-   there. Expect `collecting: true` and a rate. For an unregistered place expect `collecting: false`.
-4. Record the sale through the API and confirm the transaction appears under *Tax > Transactions* in
-   the Stripe dashboard, then reverse it.
-5. Open **Settings** and compare each class name against the category Stripe lists
-   (`GET /tax/api/tax-codes`). The ids behind `saas` and `saas-business` in particular should be
-   checked before selling under them.
+### Stripe Tax, as it actually behaves
+
+Verified against a live **test-mode** Stripe account on 2026-10-14: a calculation for a registered
+state, an unregistered one, recording a sale and finding the transaction at Stripe under the same
+reference, idempotent re-recording, a partial reversal and the remainder (each found at Stripe,
+pointing at the sale), a refused over-reversal, and a report that nets to zero. The default test run
+never calls Stripe; to repeat the check yourself, use a test-mode key from an account with Stripe Tax
+switched on and a head office address, add a test registration, and run a calculation, a record and
+a reversal through the API.
+
+Things that only a live run showed, and that are worth knowing:
+
+- **Stripe combines the layers of a place into one rate.** Vermont's 6% and a town's 1% arrive as a
+  single `7.0`, with no jurisdiction names, so a Stripe-backed report groups by state (`VT`, rate
+  `7`). The rate table is what gives a per-layer breakdown.
+- **Stripe taxes shipping in proportion to the goods.** With $49.99 taxable and $10 exempt, only
+  that share of an $8 shipping charge is taxed. Give the rate table's shipping rows
+  `shippingProportional` and the two agree: a head-to-head of 21 carts across Burlington,
+  Montpelier and Rutland (goods, mixed carts, digital, SaaS, odd cents, shipping) matched Stripe to
+  the cent once the table held the same rows. Where they differed it was data — a local-option town
+  that was not in the table — not arithmetic.
+- **Stripe returns a rate for any address and `not_collecting` outside your registrations**, which
+  is what `collecting` reports.
+- **The six class names resolve to the right categories.** Each id was checked against Stripe's own
+  list of 677 codes: `txcd_99999999` General - Tangible Goods, `txcd_10000000` Electronically
+  Supplied Services, `txcd_10103000` / `txcd_10103001` SaaS personal / business use,
+  `txcd_00000000` Nontaxable, `txcd_92010001` Shipping.
 
 ## Not here
 

package/admin/components/TaxRates.js

@@ -22,7 +22,7 @@ const CLASSES = ['physical', 'digital', 'saas', 'saas-business'];
 
 const blank = () => ({
   country: 'US', state: '', locality: '', postalPattern: '', taxClass: 'physical', level: '', kind: 'taxable',
-  rate: '', appliesToShipping: false, jurisdiction: '', label: '', priority: 0, effectiveFrom: '', effectiveTo: '', note: '',
+  rate: '', appliesToShipping: false, shippingProportional: false, jurisdiction: '', label: '', priority: 0, effectiveFrom: '', effectiveTo: '', note: '',
 });
 
 export default class TaxRates extends ShadowComponent {
@@ -43,7 +43,7 @@ export default class TaxRates extends ShadowComponent {
     this.rates = [];
     this.loaded = false;
     this.editing = null;
-    this.quick = { country: 'US', state: '', stateRate: '', jurisdiction: '', taxable: ['physical'], exempt: ['nontaxable'], shippingTaxable: false, locals: '' };
+    this.quick = { country: 'US', state: '', stateRate: '', jurisdiction: '', taxable: ['physical'], exempt: ['nontaxable'], shipping: 'none', locals: '' };
     this.importing = false;
     this.csv = '';
     this.error = '';
@@ -109,7 +109,7 @@ export default class TaxRates extends ShadowComponent {
   };
 
   runQuickStart = async () => {
-    const { country, state, stateRate, jurisdiction, taxable, exempt, shippingTaxable, locals } = this.quick;
+    const { country, state, stateRate, jurisdiction, taxable, exempt, shipping, locals } = this.quick;
 
     const localRates = locals.split('\n').map(line => line.trim()).filter(Boolean).map(line => {
       const [locality, rate] = line.split('=').map(part => part.trim());
@@ -118,7 +118,7 @@ export default class TaxRates extends ShadowComponent {
 
     this.busy = true;
     const [error, data] = await quickStart({
-      country, state, stateRate, jurisdiction, taxableClasses: taxable, exemptClasses: exempt, shippingTaxable, localRates,
+      country, state, stateRate, jurisdiction, taxableClasses: taxable, exemptClasses: exempt, shipping, localRates,
     });
     this.busy = false;
 
@@ -207,6 +207,12 @@ export default class TaxRates extends ShadowComponent {
           <input type="checkbox" .checked=${!!rate.appliesToShipping} @change=${event => this.set('appliesToShipping', event.target.checked)} />
           This row applies to shipping charges
         </label>
+        ${rate.appliesToShipping ? html`
+          <label class="field">
+            <input type="checkbox" .checked=${!!rate.shippingProportional} @change=${event => this.set('shippingProportional', event.target.checked)} />
+            …and only in proportion to the taxable goods in the order
+          </label>
+        ` : ''}
         <button class="primary" ?disabled=${this.busy} @click=${this.save}>${this.busy ? 'Saving…' : 'Save'}</button>
         <button class="secondary" @click=${() => { this.editing = null; }}>Cancel</button>
       </div>
@@ -219,7 +225,7 @@ export default class TaxRates extends ShadowComponent {
     return html`
       <div class="card">
         <h2>Quick start</h2>
-        <p class="small tc-muted">
+        <p class="tc-muted">
           Answer five questions and the matching rows are created for you — real rows, which you can then edit.
           <strong>Get the rate from your tax authority</strong>; this does not look it up or guess it.
         </p>
@@ -244,8 +250,16 @@ export default class TaxRates extends ShadowComponent {
         `)}
 
         <label class="field">
-          <input type="checkbox" .checked=${quick.shippingTaxable} @change=${event => this.setQuick('shippingTaxable', event.target.checked)} />
-          Shipping is taxed here
+          <span class="d-b">Is shipping taxed here?</span>
+          <span class="tc-muted d-b">
+            <em>In proportion</em> taxes shipping only for the share of the order that is taxable — a $60 order with $50 of
+            taxable goods taxes five-sixths of the shipping. Your tax authority's instructions say which applies.
+          </span>
+          <select .value=${quick.shipping} @change=${event => this.setQuick('shipping', event.target.value)}>
+            <option value="none" ?selected=${quick.shipping === 'none'}>No</option>
+            <option value="full" ?selected=${quick.shipping === 'full'}>Yes, in full</option>
+            <option value="proportional" ?selected=${quick.shipping === 'proportional'}>Yes, in proportion to the taxable goods</option>
+          </select>
         </label>
 
         <label class="field">
@@ -263,13 +277,13 @@ export default class TaxRates extends ShadowComponent {
 
     return html`
       ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
-      ${this.notice ? html`<p class="tc-success small">${this.notice}</p>` : ''}
+      ${this.notice ? html`<p class="tc-success">${this.notice}</p>` : ''}
 
       ${this.editing ? this.#renderEditor() : ''}
       ${!this.rates.length && !this.editing ? this.#renderQuickStart() : ''}
 
       ${this.rates.length ? html`
-        <p class="small tc-muted">
+        <p class="tc-muted">
           Rates stack by level: the most specific row at each level applies, and the levels add. To change a rate going
           forward, <strong>end</strong> the old row and add a new one — a sale quoted last month keeps last month's rate.
         </p>
@@ -285,12 +299,12 @@ export default class TaxRates extends ShadowComponent {
                 <td>${rate.level}</td>
                 <td>${rate.kind === 'exempt' ? html`<em>exempt</em>` : `${rate.rate}%`}</td>
                 <td>${rate.appliesToShipping ? 'yes' : ''}</td>
-                <td class="small">${rate.effectiveFrom || '—'} → ${rate.effectiveTo || 'now'}</td>
+                <td >${rate.effectiveFrom || '—'} → ${rate.effectiveTo || 'now'}</td>
                 <td>${rate.jurisdiction}</td>
                 <td>
-                  <button class="link small" @click=${() => { this.editing = { ...rate }; }}>Edit</button>
-                  ${rate.effectiveTo ? '' : html`<button class="link small" @click=${() => this.end(rate)}>End</button>`}
-                  <button class="link small tc-danger" @click=${() => this.remove(rate)}>Delete</button>
+                  <button class="link" @click=${() => { this.editing = { ...rate }; }}>Edit</button>
+                  ${rate.effectiveTo ? '' : html`<button class="link" @click=${() => this.end(rate)}>End</button>`}
+                  <button class="link tc-danger" @click=${() => this.remove(rate)}>Delete</button>
                 </td>
               </tr>
             `)}
@@ -306,7 +320,7 @@ export default class TaxRates extends ShadowComponent {
 
       ${this.importing ? html`
         <div class="card">
-          <p class="small tc-muted">
+          <p class="tc-muted">
             Columns: country, state, locality, postalPattern, taxClass, level, kind, rate, appliesToShipping, taxType,
             jurisdiction, label, priority, enabled, effectiveFrom, effectiveTo, note. Only country and rate are required.
             It only adds rows, and if any row is wrong nothing is added.
@@ -318,7 +332,7 @@ export default class TaxRates extends ShadowComponent {
 
       ${this.rates.length && !this.editing ? html`
         <details>
-          <summary class="small tc-muted">Run the quick start again</summary>
+          <summary class="tc-muted">Run the quick start again</summary>
           ${this.#renderQuickStart()}
         </details>
       ` : ''}

package/admin/components/TaxRegistrations.js

@@ -78,7 +78,7 @@ export default class TaxRegistrations extends ShadowComponent {
       return html`
         <div class="card banner tc-warning">
           <strong>Not connected.</strong>
-          <p class="small">No tax can be looked up until a Stripe secret key is saved under Settings.</p>
+          <p >No tax can be looked up until a Stripe secret key is saved under Settings.</p>
         </div>
       `;
     }
@@ -87,7 +87,7 @@ export default class TaxRegistrations extends ShadowComponent {
       return html`
         <div class="card banner tc-danger">
           <strong>Stripe would not talk to this key.</strong>
-          <p class="small">${this.accountError}</p>
+          <p >${this.accountError}</p>
         </div>
       `;
     }
@@ -96,7 +96,7 @@ export default class TaxRegistrations extends ShadowComponent {
       return html`
         <div class="card banner tc-warning">
           <strong>Stripe Tax is not switched on for this account yet.</strong>
-          <p class="small">
+          <p >
             Open Tax in the Stripe dashboard and finish the setup${this.account?.missingFields?.length
               ? html` — it still needs: <span class="ff-mono">${this.account.missingFields.join(', ')}</span>`
               : ''}.
@@ -109,7 +109,7 @@ export default class TaxRegistrations extends ShadowComponent {
       return html`
         <div class="card banner tc-warning">
           <strong>The rate table is empty, so no tax is being collected anywhere.</strong>
-          <p class="small">Use the quick start on the Rates tab to add the rate for the place you collect in.</p>
+          <p >Use the quick start on the Rates tab to add the rate for the place you collect in.</p>
         </div>
       `;
     }
@@ -118,7 +118,7 @@ export default class TaxRegistrations extends ShadowComponent {
       return html`
         <div class="card banner tc-warning">
           <strong>Connected, but registered nowhere — so no tax is being collected.</strong>
-          <p class="small">
+          <p >
             That is correct until a sales threshold is crossed or an obligation begins. Calculations
             still return the rate that <em>would</em> apply, marked as not collecting. Add a
             registration in the Stripe dashboard when you need to charge tax somewhere.
@@ -128,7 +128,7 @@ export default class TaxRegistrations extends ShadowComponent {
     }
 
     return html`
-      <div class="card banner ${this.status.livemode ? 'tc-danger' : 'tc-success'}">
+      <div class="card banner ${this.status.livemode && this.status.provider !== 'rates' ? 'tc-danger' : 'tc-success'}">
         <strong>
           ${this.status.livemode
             ? (this.status.provider === 'rates' ? 'Collecting from the rate table.' : 'Connected in live mode — tax is collected for real.')
@@ -164,7 +164,7 @@ export default class TaxRegistrations extends ShadowComponent {
         </table>
       ` : ''}
 
-      <p class="small tc-muted">
+      <p class="tc-muted">
         ${this.status?.provider === 'rates'
           ? html`These are the places that have a rate in your rate table.`
           : html`Registrations are managed in the <a href="https://dashboard.stripe.com/tax/registrations" target="_blank" rel="noopener">Stripe dashboard</a>.`}

package/admin/components/TaxReports.js

@@ -106,15 +106,15 @@ export default class TaxReports extends ShadowComponent {
     return html`
       <h2>${currency.toUpperCase()}</h2>
       <div class="cards">
-        <div class="card"><span class="small tc-muted d-b">Tax collected</span><strong>${money(t.taxCollected)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Tax reversed (refunds)</span><strong>${money(t.taxReversed)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Net tax owed</span><strong>${money(t.taxNet)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Sales</span><strong>${money(t.sales)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Taxable sales</span><strong>${money(t.taxable)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Exempt sales</span><strong>${money(t.exempt)}</strong></div>
-        <div class="card"><span class="small tc-muted d-b">Not collected</span><strong>${money(t.uncollected)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Tax collected</span><strong>${money(t.taxCollected)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Tax reversed (refunds)</span><strong>${money(t.taxReversed)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Net tax owed</span><strong>${money(t.taxNet)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Sales</span><strong>${money(t.sales)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Taxable sales</span><strong>${money(t.taxable)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Exempt sales</span><strong>${money(t.exempt)}</strong></div>
+        <div class="card"><span class="tc-muted d-b">Not collected</span><strong>${money(t.uncollected)}</strong></div>
       </div>
-      <p class="small tc-muted">${t.salesCount} sale${t.salesCount === 1 ? '' : 's'}, ${t.reversalsCount} refund${t.reversalsCount === 1 ? '' : 's'}.
+      <p class="tc-muted">${t.salesCount} sale${t.salesCount === 1 ? '' : 's'}, ${t.reversalsCount} refund${t.reversalsCount === 1 ? '' : 's'}.
         <em>Not collected</em> is sold where this site has no rate — it appears on no return.</p>
 
       ${data.jurisdictions.length ? html`
@@ -123,7 +123,7 @@ export default class TaxReports extends ShadowComponent {
           <tbody>
             ${data.jurisdictions.map(row => html`
               <tr>
-                <td>${row.jurisdiction}${row.state ? ` (${row.state})` : ''}</td>
+                <td>${row.jurisdiction}${row.state && row.state !== row.jurisdiction ? ` (${row.state})` : ''}</td>
                 <td>${row.level}</td>
                 <td>${row.rate ?? ''}%</td>
                 <td>${money(row.taxableAmount)}</td>
@@ -166,12 +166,12 @@ export default class TaxReports extends ShadowComponent {
         ` : html`
           <input type="date" .value=${this.from} @input=${event => { this.from = event.target.value; }} />
           <input type="date" .value=${this.to} @input=${event => { this.to = event.target.value; }} />
-          <span class="small tc-muted">to is exclusive</span>
+          <span class="tc-muted">to is exclusive</span>
         `}
         <button class="primary" ?disabled=${this.loading} @click=${this.run}>${this.loading ? 'Loading…' : 'Run report'}</button>
       </div>
 
-      <p class="small tc-muted">
+      <p class="tc-muted">
         A record of what this site collected — <strong>not a tax return</strong>. File and pay on your tax authority's own
         portal. A refund counts in the period it happened in.
       </p>
@@ -183,15 +183,16 @@ export default class TaxReports extends ShadowComponent {
       ${currencies.map(([currency, data]) => this.#renderCurrency(currency, data))}
 
       ${this.entries.length ? html`
-        <h2>Ledger <span class="small tc-muted">(${this.entries.length} of ${this.total})</span></h2>
+        <h2>Ledger <span class="tc-muted">(${this.entries.length} of ${this.total})</span></h2>
         <table>
-          <thead><tr><th>When</th><th>Kind</th><th>Reference</th><th>Place</th><th>Sales</th><th>Tax</th></tr></thead>
+          <thead><tr><th>When</th><th>Kind</th><th>Reference</th><th>Provider</th><th>Place</th><th>Sales</th><th>Tax</th></tr></thead>
           <tbody>
             ${this.entries.map(entry => html`
               <tr>
-                <td class="small">${new Date(entry.occurredAt).toLocaleString()}</td>
+                <td >${new Date(entry.occurredAt).toLocaleString()}</td>
                 <td>${entry.kind}</td>
-                <td class="ff-mono small">${entry.reference}</td>
+                <td class="ff-mono">${entry.reference}</td>
+                <td>${entry.provider}</td>
                 <td>${[entry.country, entry.state].filter(Boolean).join(' ')}</td>
                 <td>${this.#money(entry.salesAmount, entry.currency)}</td>
                 <td>${this.#money(entry.taxAmount, entry.currency)}</td>
@@ -204,7 +205,7 @@ export default class TaxReports extends ShadowComponent {
         <a class="button secondary" href=${exportUrls.ledger(this.report ? { from: this.report.from || '', to: this.report.to || '' } : {})}>Export this period's ledger (CSV)</a>
         <a class="button secondary" href=${exportUrls.ledger({})}>Export the whole ledger</a>
       </p>
-      <p class="small tc-muted">
+      <p class="tc-muted">
         The ledger is your legal record of tax collected. It is deleted if this extension is uninstalled —
         export it first.
       </p>

package/admin/components/TaxSettings.js

@@ -141,7 +141,7 @@ export default class TaxSettings extends ShadowComponent {
       return html`
         <div class="card banner tc-danger">
           <strong>SETTINGS_ENCRYPTION_KEY is not set on this server.</strong>
-          <p class="small">
+          <p >
             The Stripe key is encrypted with it, so none can be stored until it exists. Generate one with
             <code class="ff-mono">node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"</code>,
             put it in the site’s environment, and restart. Back it up — losing it makes every stored secret unrecoverable.
@@ -154,7 +154,7 @@ export default class TaxSettings extends ShadowComponent {
       return html`
         <div class="card banner tc-success">
           <strong>Using the rate table.</strong>
-          <p class="small">No external service is involved. Tax comes from the rows on the Rates tab, so it is only as current as you keep them.</p>
+          <p >No external service is involved. Tax comes from the rows on the Rates tab, so it is only as current as you keep them.</p>
         </div>
       `;
     }
@@ -163,7 +163,7 @@ export default class TaxSettings extends ShadowComponent {
       return html`
         <div class="card banner tc-warning">
           <strong>Not connected.</strong>
-          <p class="small">Save a Stripe secret key below, or install kempo-payments and connect Stripe there.</p>
+          <p >Save a Stripe secret key below, or install kempo-payments and connect Stripe there.</p>
         </div>
       `;
     }
@@ -173,7 +173,7 @@ export default class TaxSettings extends ShadowComponent {
         <strong>
           ${this.status.livemode ? 'Using a live key — calculations are real.' : 'Using a test key. No real tax is reported.'}
         </strong>
-        <p class="small">
+        <p >
           ${this.status.keySource === 'payments'
             ? 'The key is borrowed from kempo-payments. Save one below to give tax its own.'
             : 'The key is stored on this screen.'}
@@ -189,8 +189,8 @@ export default class TaxSettings extends ShadowComponent {
 
       return html`
         <label class="field">
-          <span class="d-b">${field.label} ${isSet ? html`<span class="small tc-success">· set</span>` : ''}</span>
-          <span class="small tc-muted d-b">${field.help}</span>
+          <span class="d-b">${field.label} ${isSet ? html`<span class="tc-success">· set</span>` : ''}</span>
+          <span class="tc-muted d-b">${field.help}</span>
           <input
             type="password"
             autocomplete="off"
@@ -198,7 +198,7 @@ export default class TaxSettings extends ShadowComponent {
             .value=${typeof value === 'string' ? value : ''}
             @input=${event => this.edit(field.name, event.target.value)}
           />
-          ${isSet ? html`<button class="link small" ?disabled=${this.saving} @click=${() => this.clear(field.name)}>Clear this key</button>` : ''}
+          ${isSet ? html`<button class="link" ?disabled=${this.saving} @click=${() => this.clear(field.name)}>Clear this key</button>` : ''}
         </label>
       `;
     });
@@ -211,11 +211,11 @@ export default class TaxSettings extends ShadowComponent {
     return html`
       ${this.#renderBanner()}
       ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
-      ${this.notice ? html`<p class="tc-success small">${this.notice}</p>` : ''}
+      ${this.notice ? html`<p class="tc-success">${this.notice}</p>` : ''}
 
       <h2>Provider</h2>
       <label class="field">
-        <span class="small tc-muted d-b">What works out the tax</span>
+        <span class="tc-muted d-b">What works out the tax</span>
         <select .value=${this.values.provider} @change=${event => this.set('provider', event.target.value)}>
           ${this.providers.map(entry => html`<option value=${entry.name} ?selected=${entry.name === this.values.provider}>${entry.label}</option>`)}
         </select>
@@ -224,7 +224,7 @@ export default class TaxSettings extends ShadowComponent {
       ${this.#renderCredentials()}
 
       <h2>Where you are based</h2>
-      <p class="small tc-muted">
+      <p class="tc-muted">
         Used to warn you when a sale at home is recorded with no tax collected — the case that makes a return short without
         anything looking wrong. Use the same codes your checkout sends for the address (such as VT).
       </p>
@@ -238,7 +238,7 @@ export default class TaxSettings extends ShadowComponent {
       <h2>Defaults</h2>
       <label class="field">
         <span class="d-b">Currency</span>
-        <span class="small tc-muted d-b">Used when whatever asks for a calculation does not name one</span>
+        <span class="tc-muted d-b">Used when whatever asks for a calculation does not name one</span>
         <input type="text" maxlength="3" .value=${this.values.currency} @input=${event => this.set('currency', event.target.value)} />
       </label>
 
@@ -247,7 +247,7 @@ export default class TaxSettings extends ShadowComponent {
           <input type="checkbox" .checked=${!!this.values.includesTax} @change=${event => this.set('includesTax', event.target.checked)} />
           Prices already include tax
         </span>
-        <span class="small tc-muted d-b">
+        <span class="tc-muted d-b">
           Turn on for VAT-style pricing where the sticker price is what is paid. Leave off for US-style
           pricing where tax is added at checkout. A caller can still say otherwise per line.
         </span>
@@ -255,7 +255,7 @@ export default class TaxSettings extends ShadowComponent {
 
       <label class="field">
         <span class="d-b">Default tax class</span>
-        <span class="small tc-muted d-b">
+        <span class="tc-muted d-b">
           For an item whose caller names none — a class name such as <span class="ff-mono">physical</span>, or a Stripe
           category id. Whether it is taxable, and at what rate, is decided per place. Shipping uses its own class.
         </span>
@@ -268,7 +268,7 @@ export default class TaxSettings extends ShadowComponent {
 
       <label class="field">
         <span class="d-b">Rounding</span>
-        <span class="small tc-muted d-b">
+        <span class="tc-muted d-b">
           <em>Each line</em> rounds the tax on every line. <em>Whole invoice</em> rounds once per tax layer and spreads it back
           over the lines. Use whichever your tax authority's instructions describe (rate table only).
         </span>

package/admin/components/TaxTry.js

@@ -88,7 +88,7 @@ export default class TaxTry extends ShadowComponent {
 
   render(){
     return html`
-      <p class="small tc-muted">A quote only — nothing is recorded or reported.</p>
+      <p class="tc-muted">A quote only — nothing is recorded or reported.</p>
 
       <div class="grid">
         ${this.#field('Country', 'country', { placeholder: 'US' })}
@@ -128,7 +128,7 @@ export default class TaxTry extends ShadowComponent {
                   <td>${entry.rate === null ? '—' : `${entry.rate}%`}</td>
                   <td>${this.#money(entry.taxableAmount)}</td>
                   <td>${this.#money(entry.amount)}</td>
-                  <td class="small">${entry.reason}</td>
+                  <td >${entry.reason}</td>
                 </tr>
               `)}
             </tbody>

package/install.js

@@ -17,6 +17,15 @@ import db from 'kempo/server/db/index.js';
   the rate table never needs it, so this says what it affects instead of insisting.
 */
 
+/*
+  Columns added since 0.2.0. `CREATE TABLE IF NOT EXISTS` leaves an existing table alone, so a site
+  that installed an earlier version needs these applied, and `IF NOT EXISTS` makes them safe to run
+  on every install and update.
+*/
+export const COLUMNS = [
+  sql`ALTER TABLE "kempoTaxRate" ADD COLUMN IF NOT EXISTS "shippingProportional" boolean NOT NULL DEFAULT false`,
+];
+
 export const INDEXES = [
   sql`CREATE UNIQUE INDEX IF NOT EXISTS "kempoTaxEntry_reference_idx" ON "kempoTaxEntry" ("kind", "reference")`,
   sql`CREATE INDEX IF NOT EXISTS "kempoTaxEntry_occurred_idx" ON "kempoTaxEntry" ("occurredAt")`,
@@ -26,6 +35,14 @@ export const INDEXES = [
 ];
 
 export default async () => {
+  for(const statement of COLUMNS){
+    try {
+      await db.execute(statement);
+    } catch(error) {
+      console.warn(`[kempo-tax] Could not add a column: ${error.message}`);
+    }
+  }
+
   for(const statement of INDEXES){
     try {
       await db.execute(statement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-tax",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Sales tax, VAT and GST for kempo — look up what to charge for an address and items, with Stripe Tax built in",
   "license": "MIT",
   "author": "Dustin Poissant",

package/server/db/schema.js

@@ -35,6 +35,13 @@ export const kempoTaxRate = pgTable('kempoTaxRate', {
   kind: text('kind').notNull().default('taxable'),
   rateMicro: integer('rateMicro').notNull().default(0),
   appliesToShipping: boolean('appliesToShipping').notNull().default(false),
+
+  /*
+    How shipping is taxed by a row that applies to it. Off, shipping is taxed in full. On, it is
+    taxed in proportion to the goods that are taxable: $50 of taxable goods and $10 of exempt ones
+    tax five-sixths of the shipping charge. Some states work this way, and Stripe does.
+  */
+  shippingProportional: boolean('shippingProportional').notNull().default(false),
   taxType: text('taxType').notNull().default('sales_tax'),
 
   /*

package/server/utils/ledger/entries.js

@@ -65,7 +65,7 @@ export const entryFromResult = (result, { address = {}, reference, occurredAt, q
   by largest remainder. So a reversal always satisfies `sales + tax = -amount` exactly, which is
   what lets "how much of this sale is left to reverse" be answered with plain subtraction.
 */
-export const reversalFromEntry = (original, { amount, reference, occurredAt, note }) => {
+export const reversalFromEntry = (original, { amount, reference, occurredAt, note, providerRef }) => {
   const total = original.salesAmount + original.taxAmount;
   const whole = amount === undefined || amount === null;
 
@@ -106,7 +106,7 @@ export const reversalFromEntry = (original, { amount, reference, occurredAt, not
     reference,
     originalEntryId: original.id,
     provider: original.provider,
-    providerRef: null,
+    providerRef: providerRef || null,
     quoteId: original.quoteId,
     livemode: original.livemode,
     currency: original.currency,

package/server/utils/ledger/report.js

@@ -1,3 +1,5 @@
+import { formatPercent, parsePercent } from '../tax/percent.js';
+
 /*
   The numbers a return asks for, built from ledger entries. Pure.
 
@@ -12,6 +14,29 @@
   Figures are grouped by currency first, because adding 100 JPY to 100 GBP produces 200 of nothing.
 */
 
+/*
+  A ledger row is permanent, and the code that wrote it may be older than the code reading it. So a
+  jurisdiction is read defensively: an entry recorded before Stripe's breakdown was named by state
+  has no jurisdiction and a rate of "7.0", and it must land on the same report row as the "VT" / "7"
+  that the same sale would produce today, or one place appears twice.
+*/
+/*
+  The entry itself records where the sale went, so a jurisdiction row with no place in it at all —
+  the earliest Stripe entries — still lands on the right one rather than on a blank.
+*/
+const stateOf = (part, entry) => part.state || entry.state || '';
+
+const countryOf = (part, entry) => part.country || entry.country || '';
+
+const placeOf = (part, entry) => part.jurisdiction || stateOf(part, entry) || countryOf(part, entry) || '—';
+
+const levelOf = (part, entry) => part.level || (stateOf(part, entry) ? 'state' : countryOf(part, entry) ? 'country' : '');
+
+const rateOf = part => {
+  const micro = parsePercent(String(part.rate ?? ''));
+  return micro === null ? (part.rate ?? '') : formatPercent(micro);
+};
+
 const empty = () => ({
   sales: 0,
   taxable: 0,
@@ -63,14 +88,19 @@ export const buildReport = (entries, { from = null, to = null } = {}) => {
     apply(bucket.months.get(month));
 
     for(const part of entry.jurisdictions || []){
-      const key = [part.country, part.state, part.level, part.jurisdiction, part.rate].join('|');
+      const jurisdiction = placeOf(part, entry);
+      const level = levelOf(part, entry);
+      const rate = rateOf(part);
+      const country = countryOf(part, entry);
+      const state = stateOf(part, entry);
+      const key = [country, state, level, jurisdiction, rate].join('|');
       if(!bucket.jurisdictions.has(key)){
         bucket.jurisdictions.set(key, {
-          country: part.country,
-          state: part.state,
-          level: part.level,
-          jurisdiction: part.jurisdiction,
-          rate: part.rate,
+          country,
+          state,
+          level,
+          jurisdiction,
+          rate,
           taxableAmount: 0,
           taxAmount: 0,
         });

package/server/utils/rates/csv.js

@@ -15,6 +15,7 @@ export const RATE_COLUMNS = [
   { key: 'kind' },
   { key: 'rate' },
   { key: 'appliesToShipping' },
+  { key: 'shippingProportional' },
   { key: 'taxType' },
   { key: 'jurisdiction' },
   { key: 'label' },

package/server/utils/rates/quickstart.js

@@ -65,8 +65,18 @@ export const quickstartRows = input => {
 
   for(const taxClass of exempt) add({ taxClass, kind: 'exempt' });
 
-  if(input.shippingTaxable){
-    add({ taxClass: 'shipping', kind: 'taxable', rate: input.stateRate, appliesToShipping: true }, 'shipping');
+  /*
+    `shippingTaxable` is the older boolean. `shipping` is one of none, full, proportional: whether
+    delivery charges are taxed at all, in full, or only in proportion to the taxable goods.
+  */
+  const shipping = input.shipping || (input.shippingTaxable ? 'full' : 'none');
+  if(!['none', 'full', 'proportional'].includes(shipping)){
+    return [{ code: 400, msg: 'Shipping must be none, full or proportional' }, null];
+  }
+  const proportional = shipping === 'proportional';
+
+  if(shipping !== 'none'){
+    add({ taxClass: 'shipping', kind: 'taxable', rate: input.stateRate, appliesToShipping: true, shippingProportional: proportional }, 'shipping');
     for(const local of locals){
       add({
         taxClass: 'shipping',
@@ -76,6 +86,7 @@ export const quickstartRows = input => {
         locality: local.locality,
         jurisdiction: local.jurisdiction || `${local.locality} local option`,
         appliesToShipping: true,
+        shippingProportional: proportional,
       }, 'shipping, local option');
     }
   }

package/server/utils/rates/validate.js

@@ -74,6 +74,7 @@ export const cleanRate = input => {
     kind,
     rateMicro,
     appliesToShipping: input.appliesToShipping === true || input.appliesToShipping === 'true' || input.appliesToShipping === '1' || input.appliesToShipping === 1,
+    shippingProportional: input.shippingProportional === true || input.shippingProportional === 'true' || input.shippingProportional === '1' || input.shippingProportional === 1,
     taxType: text(input.taxType || 'sales_tax', 40) || 'sales_tax',
     jurisdiction,
     label: text(input.label),
@@ -99,6 +100,7 @@ export const presentRate = row => ({
   kind: row.kind,
   rate: row.kind === 'exempt' ? '0' : formatPercent(row.rateMicro),
   appliesToShipping: row.appliesToShipping,
+  shippingProportional: !!row.shippingProportional,
   taxType: row.taxType,
   jurisdiction: row.jurisdiction,
   label: row.label,

package/server/utils/tax/rates.js

@@ -171,19 +171,42 @@ export const calculateWithRates = (request, rows, options = {}) => {
     return { item, layers, taxable, totalMicro: taxable.reduce((sum, row) => sum + row.rateMicro, 0) };
   });
 
+  /*
+    How much of the goods is taxable, for a shipping row that taxes shipping in proportion. Free
+    lines are not goods here, and shipping is never part of its own share.
+  */
+  const goods = resolved.filter(entry => !entry.item.isShipping && entry.item.amount > 0);
+  const goodsTotal = goods.reduce((sum, entry) => sum + entry.item.amount, 0);
+  const goodsTaxable = goods.filter(entry => entry.taxable.length).reduce((sum, entry) => sum + entry.item.amount, 0);
+
   // 2. The tax for each (item, layer).
   const shares = resolved.map(entry => entry.taxable.map(row => {
     const inclusive = entry.item.taxBehavior === 'inclusive';
-    return {
-      row,
-      inclusive,
-      exact: inclusive
-        ? { numerator: BigInt(entry.item.amount) * BigInt(row.rateMicro), denominator: BigInt(ONE + entry.totalMicro) }
-        : { numerator: BigInt(entry.item.amount) * BigInt(row.rateMicro), denominator: BigInt(ONE) },
-      tax: inclusive
-        ? taxInclusive(entry.item.amount, row.rateMicro, entry.totalMicro)
-        : taxExclusive(entry.item.amount, row.rateMicro),
-    };
+
+    /*
+      Proportional shipping applies to tax added on top. A tax-inclusive shipping charge is taxed
+      in full, because the share of tax already inside a price cannot be split by what else was
+      bought; the README says so.
+    */
+    const proportional = entry.item.isShipping && row.shippingProportional && !inclusive;
+
+    let exact;
+    let tax;
+    if(inclusive){
+      exact = { numerator: BigInt(entry.item.amount) * BigInt(row.rateMicro), denominator: BigInt(ONE + entry.totalMicro) };
+      tax = taxInclusive(entry.item.amount, row.rateMicro, entry.totalMicro);
+    } else if(proportional){
+      exact = {
+        numerator: BigInt(entry.item.amount) * BigInt(row.rateMicro) * BigInt(goodsTaxable),
+        denominator: BigInt(ONE) * BigInt(Math.max(goodsTotal, 1)),
+      };
+      tax = roundDiv(exact.numerator, exact.denominator);
+    } else {
+      exact = { numerator: BigInt(entry.item.amount) * BigInt(row.rateMicro), denominator: BigInt(ONE) };
+      tax = taxExclusive(entry.item.amount, row.rateMicro);
+    }
+
+    return { row, inclusive, exact, tax };
   }));
 
   // 3. Invoice rounding: one rounded figure per layer, spread back over the lines that used it.

package/server/utils/tax/shape.js

@@ -1,3 +1,5 @@
+import { formatPercent, parsePercent } from './percent.js';
+
 /*
   Turning what a caller hands in into what a provider needs, and what a provider answers into one
   vocabulary — with no network and no database anywhere in this file.
@@ -305,14 +307,34 @@ export const toStripeParams = request => ({
 */
 const NOT_COLLECTING = new Set(['not_collecting', 'not_supported']);
 
+/*
+  What Stripe actually returns for a breakdown, found by running it against a live account rather
+  than from the type definitions: a calculation names a place only by `state` and `country` inside
+  `tax_rate_details`, there is no jurisdiction object and no per-line breakdown, and the layers of
+  a place are **combined** into one row — Vermont's 6% and Burlington's 1% arrive as a single 7.0.
+
+  So the jurisdiction is the state (or the country, where there is none), at level `state` or
+  `country`, and the rate is the combined one. A per-layer breakdown is what the rate table gives;
+  with Stripe a return can only be broken down as far as Stripe says. The fields are read
+  defensively, so a version that does send a jurisdiction object is used as sent.
+*/
+const place = entry => entry.jurisdiction?.state || entry.tax_rate_details?.state || entry.jurisdiction?.country || entry.tax_rate_details?.country || null;
+
+const normalisedRate = value => {
+  const micro = parsePercent(String(value ?? ''));
+  return micro === null ? (value ?? null) : formatPercent(micro);
+};
+
 const breakdownFrom = entry => ({
-  jurisdiction: entry.jurisdiction?.display_name || null,
-  level: entry.jurisdiction?.level || null,
-  country: entry.jurisdiction?.country || null,
-  state: entry.jurisdiction?.state || null,
+  jurisdiction: entry.jurisdiction?.display_name || place(entry),
+  level: entry.jurisdiction?.level
+    || (entry.tax_rate_details?.state || entry.jurisdiction?.state ? 'state' : place(entry) ? 'country' : null),
+  country: entry.jurisdiction?.country || entry.tax_rate_details?.country || null,
+  state: entry.jurisdiction?.state || entry.tax_rate_details?.state || null,
   taxType: entry.tax_rate_details?.tax_type || null,
-  name: entry.tax_rate_details?.display_name || null,
-  rate: entry.tax_rate_details?.percentage_decimal ?? null,
+  name: entry.tax_rate_details?.display_name
+    || [place(entry), entry.tax_rate_details?.tax_type?.replace(/_/g, ' ')].filter(Boolean).join(' ') || null,
+  rate: normalisedRate(entry.tax_rate_details?.percentage_decimal),
   taxableAmount: entry.taxable_amount ?? 0,
   amount: entry.amount ?? 0,
   inclusive: !!entry.inclusive,

package/server/utils/tax/transactions.js

@@ -178,16 +178,18 @@ export const reverseTransaction = async ({ transactionId, reference, amount, occ
   */
   const reverseAmount = amount || (reversed > 0 ? remaining : undefined);
 
+  let providerReversalRef = null;
   if(original.provider !== 'rates' && original.providerRef){
     const [providerError, provider] = getProvider(original.provider);
     if(providerError) return [providerError, null];
 
-    const [error] = await provider.reverseTransaction({
+    const [error, reversal] = await provider.reverseTransaction({
       transactionId: original.providerRef,
       reference: cleaned,
       amount: reverseAmount,
     });
     if(error) return [error, null];
+    providerReversalRef = reversal.transactionId;
   }
 
   const entry = reversalFromEntry(original, {
@@ -195,6 +197,7 @@ export const reverseTransaction = async ({ transactionId, reference, amount, occ
     reference: cleaned,
     occurredAt: occurredAt ? new Date(occurredAt) : new Date(),
     note,
+    providerRef: providerReversalRef,
   });
 
   const [insertError, saved] = await insertEntry(entry);