business-obligations 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/CHANGELOG.md +48 -0
  2. package/COVERAGE.md +4 -4
  3. package/README.md +14 -0
  4. package/data/cities/LA.json +18 -0
  5. package/data/cities/WV.json +30 -0
  6. package/data/counties/PA.json +16 -0
  7. package/dist/cli.js +1214 -16
  8. package/dist/index.cjs +1085 -15
  9. package/dist/index.d.cts +2 -2
  10. package/dist/index.d.ts +2 -2
  11. package/dist/index.js +1085 -15
  12. package/dist/{types-CBgL6hFd.d.cts → types-dcI6srbz.d.cts} +97 -1
  13. package/dist/{types-CBgL6hFd.d.ts → types-dcI6srbz.d.ts} +97 -1
  14. package/package.json +17 -6
  15. package/schema/business-profile.schema.json +39 -0
  16. package/schema/compliance-result.schema.json +118 -0
package/CHANGELOG.md CHANGED
@@ -5,6 +5,8 @@ project follows [Semantic Versioning](https://semver.org/) with the data-aware p
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.3.0] - 2026-10-16
9
+
8
10
  ### Fixed
9
11
 
10
12
  - "Today" is now the local calendar date, not the UTC date. Default start dates, "days until" figures and the CLI's
@@ -12,6 +14,10 @@ project follows [Semantic Versioning](https://semver.org/) with the data-aware p
12
14
 
13
15
  ### Changed
14
16
 
17
+ - **Releases are automatic.** Merging a PR with a `feat`, `fix`, `perf`, `revert` or breaking Conventional Commit title
18
+ opens a release pull request that sets the version and generates the changelog; merging it publishes to npm and
19
+ tags the release. PR titles are checked in CI.
20
+
15
21
  - **Renamed to `business-obligations`** (was `compliance-rules-engine`): npm package, CLI command, repository and
16
22
  playground address. Import from `business-obligations` and `business-obligations/zip`; the CLI is now
17
23
  `business-obligations`. Calendar exports use `@business-obligations` in event UIDs.
@@ -26,9 +32,45 @@ project follows [Semantic Versioning](https://semver.org/) with the data-aware p
26
32
  - The repository is now an npm-workspaces monorepo (`packages/core`, `apps/web`). The published package is unchanged.
27
33
  - The playground is rebuilt with Next.js (static export), React and Tamagui, and reports usage, the form values you enter
28
34
  when generating a plan, and unhandled errors with PostHog when configured (no cookies, no session recording).
35
+ - Local data: seeds for Huntington, WV and Shreveport, LA cities and for Fayette and Schuylkill counties, PA.
29
36
 
30
37
  ### Added
31
38
 
39
+ - **Seed data can express precedence.** City and county seed items accept `appliesWhen`, `exemptions`, `supersedes`
40
+ (item ids or rule ids), `preemptedBy`, `formId`, `filingMethod`, `processingTime` and `renewal`; they are passed
41
+ through to the emitted items. Superseded items come back marked `preemptedBy`.
42
+ - **`provenance.compiledOn` on every item**, the date of the bundled dataset, so items that were never individually
43
+ checked still have an age. `reviewBy` and `stale` now apply to every item (counted from `checkedOn`, or from
44
+ `compiledOn` when never checked).
45
+ - **Seeded city and county items inherit the seed's `checkedOn`** and are reported as `checked` (they were `compiled`
46
+ with no date although the seed records when it was checked against the official pages).
47
+
48
+ - **Trust and review fields on every item.** `provenance.reviewBy` and `provenance.stale` (data checked more than a year
49
+ before `asOf` is stale), `provenance.sourceDetails` (kind, retrieval date and an Internet Archive link per source),
50
+ `jurisdictionId` (`US`, `US-TX`, `US-TX/city/austin`), `stateFips`, and `feedbackUrl` (a pre-filled data-correction
51
+ issue). `npm run report:stale -w business-obligations` lists states that need re-verification.
52
+ - **Applicability and precedence fields:** `appliesWhen` (machine-readable conditions), `exemptions`, `supersedes` and
53
+ `preemptedBy`, available to rules and data packs. The new stormwater rule is the first to populate them.
54
+ - **Filing mechanics:** optional `formId`, `filingMethod`, `processingTime` and `renewal` on items (set for the EIN).
55
+ - **Census FIPS codes and incorporated status.** County items carry a 5-digit `fips`, city items a 7-digit place `fips`
56
+ and `incorporated`, for the 310 of 312 counties and 305 of 307 cities in `data/` that match the 2020 Census (consolidated city-counties
57
+ such as Nashville and independent cities such as Baltimore are matched explicitly; Honolulu, Edison and two
58
+ Connecticut planning regions are not in the Census place or county files and are left out). Regenerate with
59
+ `node scripts/build-places.mjs <census dir>`.
60
+ - **Precedence is resolved.** An item listing another item's id in `supersedes` marks it `preemptedBy`.
61
+ - **New rules for the new inputs:** sign permit (`hasSignage`), building permit (`projectValueUsd`), food permit for
62
+ non-restaurants (`foodService`); the certificate-of-occupancy and contractor items now use `floorAreaSqFt` and
63
+ `licenseClass`; `naics` implies an industry for construction, food service, retail, real estate and healthcare.
64
+ - `renewal` is derived for licences, permits and registrations that recur annually, every two years or every five
65
+ years ("Renew every two years; due ...").
66
+ - Sourced facts: the Form 1023 / 1023-EZ item carries the IRS's published processing figures, and Florida
67
+ construction items state that cities and counties cannot require their own license for scopes outside the state
68
+ contractor categories (s. 163.211, Florida Statutes).
69
+ - `formId` and `filingMethod` on the federal income tax return, Form 941, Form 940, Form 1099-NEC and Form 1023.
70
+ - **New profile inputs:** `naics`, `activities`, `projectValueUsd`, `disturbedAcres`, `licenseClass`, `floorAreaSqFt`,
71
+ `hasSignage`, `foodService`. `disturbedAcres` of 1 or more adds the NPDES construction stormwater permit for
72
+ construction businesses; the others are accepted and validated for upcoming local rules.
73
+
32
74
  - Local seeds: Charleston, WV (registration, B&O tax and City Service Fee items from the city's own page), Des Moines, IA and Kanawha County, WV (unverified); Western Connecticut is skipped as a planning region.
33
75
 
34
76
  - Counties: `data/counties/<STATE>.json` seeds county-level filings for the 300 largest US counties, mainly the
@@ -133,6 +175,12 @@ project follows [Semantic Versioning](https://semver.org/) with the data-aware p
133
175
  - Dead agency URLs replaced (FL, IA, LA, ME, NY, NH, VT, WY, MA) and city URLs repaired.
134
176
  - Report data refined: MA/ME/HI corporate fees, NE occupation tax schedule, OK corporations (franchise tax repealed).
135
177
 
178
+ ### Added
179
+
180
+ - **cli:** add --version flag
181
+ - precedence in seed data, compiledOn on every item
182
+ - Census FIPS codes, rules for new profile inputs, precedence and renewal
183
+
136
184
  ## [0.2.0] - 2026-10-13
137
185
 
138
186
  ### Added
package/COVERAGE.md CHANGED
@@ -8,8 +8,8 @@ page on the date shown; everything not listed as checked is compiled from public
8
8
 
9
9
  - **Jurisdictions:** 51 (50 states and DC)
10
10
  - **States with unconfirmed fields:** 1
11
- - **Seeded cities:** 305: 162 with city-specific rules, 25 checked with no general city license or tax, 118 researched but unconfirmed (all other cities get the state's local licensing regime named for the city and county)
12
- - **Seeded counties:** 310: 145 with county-specific filings (mainly business personal property returns), the rest researched but unconfirmed or with nothing county-level
11
+ - **Seeded cities:** 307: 164 with city-specific rules, 25 checked with no general city license or tax, 118 researched but unconfirmed (all other cities get the state's local licensing regime named for the city and county)
12
+ - **Seeded counties:** 312: 145 with county-specific filings (mainly business personal property returns), the rest researched but unconfirmed or with nothing county-level
13
13
  - **300 largest counties** (approximate): 297 of 300 covered
14
14
  - **300 largest cities** (2020 census; ranks beyond 100 are approximate): 300 of 300 covered
15
15
 
@@ -33,7 +33,7 @@ page on the date shown; everything not listed as checked is compiled from public
33
33
  | IN | 2026-10-13 | LLC, CORP, LP, LLP | checked | text | 2026 | Evansville, Fort Wayne, Indianapolis, South Bend | — |
34
34
  | KS | 2026-10-13 | LLC, CORP, LP, LLP | checked | text | 2026 | Kansas City, Olathe, Overland Park, Topeka, Wichita | — |
35
35
  | KY | 2026-10-13 | LLC, CORP | checked | text | 2026 | Lexington, Louisville | — |
36
- | LA | 2026-10-13 | LLC, CORP, LLP | checked | text | 2026 | Baton Rouge, Lafayette, New Orleans | — |
36
+ | LA | 2026-10-13 | LLC, CORP, LLP | checked | text | 2026 | Baton Rouge, Lafayette, New Orleans, Shreveport | — |
37
37
  | MA | 2026-10-13 | LLC, CORP, LP, LLP | checked | text | 2026 | Boston, Cambridge, Lowell, Quincy, Springfield, Worcester | — |
38
38
  | MD | 2026-10-13 | LLC, CORP | checked | text | 2026 | Baltimore | — |
39
39
  | ME | 2026-10-13 | LLC, CORP | checked | text | 2026 | — | — |
@@ -64,7 +64,7 @@ page on the date shown; everything not listed as checked is compiled from public
64
64
  | VT | 2026-10-13 | LLC, CORP, LLP | checked | text | 2026 | — | — |
65
65
  | WA | 2026-10-13 | LLC, CORP | checked | text | 2026 | Bellevue, Bellingham, Everett, Pasco, Renton, Seattle, Spokane, Tacoma, Vancouver | — |
66
66
  | WI | 2026-10-13 | LLC, CORP | checked | text | 2026 | Green Bay, Kenosha, Madison, Milwaukee | — |
67
- | WV | 2026-10-13 | LLC, CORP, LLP | checked | text | 2026 | Charleston | — |
67
+ | WV | 2026-10-13 | LLC, CORP, LLP | checked | text | 2026 | Charleston, Huntington | — |
68
68
  | WY | 2026-10-13 | LLC, CORP | checked | text | 2026 | — | — |
69
69
 
70
70
  ## Columns
package/README.md CHANGED
@@ -6,6 +6,9 @@
6
6
 
7
7
  <p align="center">
8
8
  <a href="https://github.com/Alisa007/business-obligations/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Alisa007/business-obligations/actions/workflows/ci.yml/badge.svg" /></a>
9
+ <a href="https://www.npmjs.com/package/business-obligations"><img alt="npm version" src="https://img.shields.io/npm/v/business-obligations.svg" /></a>
10
+ <a href="https://www.npmjs.com/package/business-obligations"><img alt="npm downloads" src="https://img.shields.io/npm/dm/business-obligations.svg" /></a>
11
+ <img alt="Node 20+" src="https://img.shields.io/node/v/business-obligations.svg" />
9
12
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
10
13
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6.svg" />
11
14
  <img alt="Zero dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" />
@@ -15,6 +18,13 @@
15
18
 
16
19
  **[Try it in your browser](https://alisa007.github.io/business-obligations/)**: no install; the plan is computed in your browser.
17
20
 
21
+ <!-- Add a short GIF or screenshot of the playground here, e.g. docs/playground.gif:
22
+ <p align="center"><img alt="Playground: an LLC in Austin gets an ordered plan of filings, licenses and deadlines" src="docs/playground.gif" width="720" /></p>
23
+ -->
24
+
25
+ **Built for** formation and compliance tools, accounting and payroll software, SaaS onboarding flows, and anyone who
26
+ needs "what does this business owe, to whom, and by when?" as data rather than a pile of agency pages.
27
+
18
28
  Starting or running a business in the US means a pile of obligations spread over the IRS, 50 state agencies and your
19
29
  city: formation, EIN, state tax accounts, licenses, annual reports, payroll filings, insurance. They depend on the
20
30
  entity type, the state, headcount, industry and more, and the answers live in dozens of scattered agency pages.
@@ -56,6 +66,10 @@ const { items } = evaluate({
56
66
  | Output in another language | `localize(result, catalog)` |
57
67
  | The command line | `npx business-obligations --zip 78701 --entity llc` |
58
68
 
69
+ Each item also carries a `provenance.reviewBy` date and `stale` flag, per-source archive links, a stable
70
+ `jurisdictionId` (for example `US-TX/city/austin`) and a `feedbackUrl` that opens a pre-filled correction issue. Where
71
+ the trigger is a number, `appliesWhen` and `exemptions` state it.
72
+
59
73
  Every item says **why** it applies (`reason`), **who** to deal with (`authority`, `url`), **when** (`nextDue`),
60
74
  **how much** (`cost`, `penalty`) and **how sure we are** (`provenance`: checked, compiled or unconfirmed, with sources).
61
75
 
package/data/cities/LA.json CHANGED
@@ -49,5 +49,23 @@
49
49
  "appliesTo": ["all"]
50
50
  }
51
51
  ]
52
+ },
53
+ {
54
+ "state": "LA",
55
+ "city": "Shreveport",
56
+ "counties": ["Caddo"],
57
+ "items": [
58
+ {
59
+ "id": "shreveport-la.occupational-license",
60
+ "title": "Obtain an annual Shreveport occupational license",
61
+ "category": "license",
62
+ "authority": "City of Shreveport Department of Finance, Revenue Division",
63
+ "description": "All businesses within the Shreveport corporate limits must obtain an annual business license, paid before business begins. The tax varies with gross receipts, fees or commissions, with a $50 minimum for every business type. The page does not state a renewal due date.",
64
+ "frequency": "annual",
65
+ "url": "https://shreveportla.gov/286/Occupational-License-Tax",
66
+ "appliesTo": ["all"]
67
+ }
68
+ ],
69
+ "checkedOn": "2026-10-16"
52
70
  }
53
71
  ]
package/data/cities/WV.json CHANGED
@@ -37,5 +37,35 @@
37
37
  }
38
38
  ],
39
39
  "checkedOn": "2026-10-15"
40
+ },
41
+ {
42
+ "state": "WV",
43
+ "city": "Huntington",
44
+ "counties": ["Cabell"],
45
+ "items": [
46
+ {
47
+ "id": "huntington-wv.business-license",
48
+ "title": "Obtain and renew the Huntington business license",
49
+ "category": "license",
50
+ "authority": "City of Huntington Finance Division",
51
+ "description": "Anyone conducting business in the City of Huntington must obtain a Huntington Business License. The page gives a $20 fee, notes that fees vary by license type and are not prorated, and says the license term runs July 1 to June 30 with a renewal notice sent around the first of June.",
52
+ "frequency": "annual",
53
+ "deadline": "License term July 1 to June 30",
54
+ "url": "https://www.cityofhuntington.com/business/new-business/license/",
55
+ "appliesTo": ["all"]
56
+ },
57
+ {
58
+ "id": "huntington-wv.b-and-o-tax",
59
+ "title": "File the City of Huntington Business & Occupation tax return",
60
+ "category": "filing",
61
+ "authority": "City of Huntington Finance Division",
62
+ "description": "Any business engaged in activity with the object of gaining economic benefit files a quarterly B&O return listing gross income for the period, including a return showing no activity when there was none. The page does not state a rate and notes that the Retail, Restaurant & Others classification was waived on September 13, 2021.",
63
+ "frequency": "quarterly",
64
+ "deadline": "30 days after each filing period ends (periods end March 31, June 30, September 30 and December 31)",
65
+ "url": "https://www.cityofhuntington.com/business/taxes-and-fees/b-o-tax/",
66
+ "appliesTo": ["all"]
67
+ }
68
+ ],
69
+ "checkedOn": "2026-10-16"
40
70
  }
41
71
  ]
package/data/counties/PA.json CHANGED
@@ -63,6 +63,14 @@
63
63
  "items": [],
64
64
  "checkedOn": "2026-10-13"
65
65
  },
66
+ {
67
+ "state": "PA",
68
+ "county": "Fayette",
69
+ "status": "unverified",
70
+ "note": "The official county site's Businesses and License & Permit Fees pages describe no county business license, business tax or business filing; no explicit statement that none exists was found.",
71
+ "items": [],
72
+ "checkedOn": "2026-10-16"
73
+ },
66
74
  {
67
75
  "state": "PA",
68
76
  "county": "Lancaster",
@@ -111,6 +119,14 @@
111
119
  "items": [],
112
120
  "checkedOn": "2026-10-13"
113
121
  },
122
+ {
123
+ "state": "PA",
124
+ "county": "Schuylkill",
125
+ "status": "unverified",
126
+ "note": "The official county site's tax pages cover real estate and per capita taxes only; no county business license, business tax or business filing was confirmed.",
127
+ "items": [],
128
+ "checkedOn": "2026-10-16"
129
+ },
114
130
  {
115
131
  "state": "PA",
116
132
  "county": "Westmoreland",