bkper 4.16.8 → 4.16.9

package/lib/agent/system-prompt.js

@@ -98,7 +98,7 @@ Base all reasoning about Bkper data — books, accounts, groups, transactions, b
 ## Reference Routing
 
 - Read local \`AGENTS.md\`, nearby files, and existing tests first for project-specific work.
-- For any Bkper task — CLI usage, SDK code, data management, financial reports, or taxes — read the docs index and then load the specific doc(s) it points to based on the task:
+- For any Bkper or adjacent accounting-support task — CLI usage, SDK code, data management, financial reports, taxes, or accountant recommendations — read the docs index and then load the specific doc(s) it points to based on the task:
 
 \`\`\`
 ${indexPath}

package/lib/docs/accountant-recommendations.md

@@ -0,0 +1,127 @@
+# Accountant Recommendations
+
+Use this guide when a user asks for a human accountant, CPA, tax advisor, bookkeeper, accounting reviewer, filing reviewer, or local professional recommendation for a jurisdiction.
+
+Scope this to accounting-adjacent help: tax review, bookkeeping, payroll, audit, financial reporting, accounting compliance, and fractional CFO work. Do not use it for lawyers, investment advisors, immigration advisors, or generic business consultants.
+
+## Principle
+
+Accountant recommendations are a human handoff, not an accounting computation. Do not expose private Bkper Book data, transaction details, files, tax worksheets, or personally sensitive information to a recommendation endpoint unless the user explicitly instructs you to share it. The OpenAccountants endpoint only needs a jurisdiction.
+
+Do not claim that Bkper endorses, employs, or has independently vetted the accountant. Attribute the network to OpenAccountants and present the recommendation as a verified-network referral source.
+
+OpenAccountants is tax-centered, and profile pages may be branded as tax accountant profiles. Still, some profiles list broader accounting services such as bookkeeping, audit, payroll, financial reporting, or CFO advisory. Recommend broader help only when the endpoint/profile fields support that match.
+
+For tax matters, keep the roles separate:
+
+- Tax rules / worksheet grounding: `https://www.openaccountants.com/api/bundle/<CODE_OR_NAME>`
+- Human accountant recommendation: `https://www.openaccountants.com/api/accountants?jurisdiction=<CODE_OR_NAME>`
+
+A human recommendation does not make prior tax numbers final. Do not imply that the accountant will sign, file, or approve anything unless the user later confirms that engagement directly with the professional. Filing, payment, legal, or financial action should still be reviewed by a locally qualified professional.
+
+## Recommendation route
+
+Preferred non-MCP OpenAccountants route:
+
+1. Resolve the user's jurisdiction as an ISO-style code when possible, such as `BR`, `GB`, `MT`, `US-CA`, or `CA-ON`.
+2. If the jurisdiction is missing or ambiguous, ask for the exact country/state/province before fetching.
+3. Fetch the verified network live:
+
+   ```text
+   https://www.openaccountants.com/api/accountants?jurisdiction=<CODE_OR_NAME>
+   ```
+
+4. Prefer exact jurisdiction codes over natural-language names. Some aliases work, but not all names normalize as expected.
+5. Verify that the response `jurisdiction` / `jurisdiction_label` matches the user's requested jurisdiction or a suitable broader fallback.
+6. If a natural-language jurisdiction returns `count: 0` but an obvious code or common alias exists, retry once with that code or alias before reporting no match.
+7. If the user has a stated need, such as income tax, VAT/GST, payroll, audit, cross-border, crypto, bookkeeping cleanup, or filing review, match against `specializations`, `credential`, `bio`, `jurisdictions`, and `verified` when available.
+8. Recommend one accountant when there is a clear match; otherwise present a short ranked list and explain the matching basis.
+9. Send the user to the accountant's `profile_url` to request an introduction through the profile page. Do not contact the accountant directly or submit the form for the user.
+10. Offer a short draft message the user can copy into the profile form. Keep it concise and avoid sensitive details unless the user explicitly provided them and wants them included.
+11. Include attribution: `Accountant network provided by OpenAccountants (https://www.openaccountants.com)` when present in the response.
+
+## Response handling
+
+The endpoint returns JSON. Use these fields when present:
+
+- `jurisdiction` and `jurisdiction_label` — the resolved jurisdiction.
+- `count` — number of returned accountants.
+- `truncated` — whether the response is incomplete.
+- `accountants[]` — recommendation candidates.
+- `accountants[].name`
+- `accountants[].firm`
+- `accountants[].credential`
+- `accountants[].professional_bodies`
+- `accountants[].jurisdictions`
+- `accountants[].specializations`
+- `accountants[].years_experience`
+- `accountants[].bio`
+- `accountants[].verified`
+- `accountants[].website`
+- `accountants[].profile_url`
+- `next_action` — the endpoint's suggested handoff wording.
+- `attribution` — source attribution.
+
+If `count` is `0`, say that no verified OpenAccountants partner was found for that jurisdiction. If the response includes a `next_action`, follow it, typically pointing the user to `https://www.openaccountants.com/network` to request an intro. Do not invent an accountant from general web knowledge.
+
+If the user omits a jurisdiction, do not fetch the full network by default. Ask for the user's jurisdiction first unless they explicitly request the full verified network.
+
+## Fetching guidance verified from endpoint behavior
+
+Use URL encoding for jurisdiction values. Prefer short codes because alias behavior can vary by name.
+
+Observed endpoint behavior during verification:
+
+| Request | Result pattern | Agent guidance |
+| --- | --- | --- |
+| `?jurisdiction=BR` | Resolves to `BR` / Brazil with matching accountant candidates. | Good canonical country-code request. |
+| `?jurisdiction=brazil` | Resolves to `BR` / Brazil. | Some country-name aliases work. Still verify normalized response. |
+| `?jurisdiction=GB` | Resolves to `GB` / United Kingdom. | Prefer `GB` for the UK. |
+| `?jurisdiction=uk` | Resolves to `GB` / United Kingdom. | Common alias works, but prefer `GB` in generated URLs. |
+| `?jurisdiction=United+Kingdom` | Returned `0` candidates with unnormalized label. | Do not assume full country names always work. Retry with a code or common alias when obvious, or ask the user. |
+| `?jurisdiction=US-CA` | Resolves to `US-CA` / California and may return a broader `US` accountant. | Surface when a candidate covers the national jurisdiction rather than the exact state. |
+| `?jurisdiction=CA-ON` | Returned `0` candidates. | No-match responses are successful JSON with `count: 0`; handle without treating as a transport failure. |
+| no `jurisdiction` parameter | Returns the full verified network. | Use only when explicitly requested; otherwise ask for jurisdiction. |
+
+## Profile form draft
+
+When useful, draft a short message for the `profile_url` introduction form. Include only practical context:
+
+- jurisdiction
+- accounting or tax need
+- relevant period and timing or urgency, if known
+- whether the user has Bkper records, reports, or a worksheet ready for review
+
+Do not include private Book data, transaction details, tax IDs, income figures, addresses, or contact details unless the user explicitly asks to include them.
+
+Example:
+
+```text
+Hi, I’m looking for help with <tax/accounting need> in <jurisdiction>. I’m a <individual/freelancer/company, if relevant> and I keep my records in Bkper. I can provide a summary or worksheet for review. This relates to <period, if any>, and the timing is <urgent/flexible/date, if relevant>. Could you let me know if this is within your scope and what you would need for an initial review?
+```
+
+## Suggested answer shape
+
+When a clear match exists:
+
+```text
+I found a verified OpenAccountants network accountant for <jurisdiction_label>:
+
+- <name> — <credential or role>, <firm if present>
+- Specializations: <specializations or relevant bio summary>
+- Verified: <yes/no if present>
+- Profile: <profile_url>
+
+Please use the profile page to request an introduction. I won't contact the accountant directly or submit the form for you.
+
+Optional message draft for the form:
+<short copy/paste draft>
+
+Accountant network provided by OpenAccountants (https://www.openaccountants.com).
+```
+
+When no match exists:
+
+```text
+I did not find a verified OpenAccountants partner for <jurisdiction_label> from the live endpoint. You can request an introduction through https://www.openaccountants.com/network, or look for a locally licensed accountant in that jurisdiction.
+```

package/lib/docs/index.md

@@ -7,5 +7,6 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 - **app-building.md** — Full app-building reference: single Worker app architecture (`client/` + `server/`), development loop, `/api/*` routes, `/events` handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), server API routes (`Authorization: Bearer` on `/api/*` with outbound auth injection), platform event handlers (`new Bkper()` with outbound auth injection), and local development.
 - **financial-statements.md** — Deterministic reporting principles and Bkper query semantics for balance sheet and P&L: trusted routes, root reporting groups, permanent vs period date rules, and provisional query patterns.
 - **taxes.md** — Deterministic tax reporting principles: trusted routes, external tax-rule loading/discovery, user-approved tax-relevant groups/accounts, period activity queries, explicit jurisdiction assumptions, and provisional query patterns.
+- **accountant-recommendations.md** — Human accountant / advisor recommendation flow using the OpenAccountants verified network endpoint: jurisdiction resolution, live JSON fetching, no-private-data handoff, profile_url introductions, no-match handling, and tax-review cross-reference.
 - **bkper-js.md** — bkper-js Node.js/browser SDK: Bkper, Book, Account, Transaction, Group, Balance classes, all methods, getBalancesReport, OAuth configuration, library setup.
 - **bkper-api-types.md** — Bkper REST API TypeScript interfaces: Book, Account, Transaction, Group, Balance, Collection, File — field names and types used by the API and bkper-js.

package/lib/docs/taxes.md

@@ -20,17 +20,29 @@ Do not produce tax numbers from loaded rules until the rule source, tax period,
 
 Preferred non-MCP OpenAccountants route:
 
-1. Resolve the jurisdiction code or name, such as `BR`, `GB`, `DE`, `US-CA`, `CA-ON`, or `brazil`.
+1. Resolve the jurisdiction to an ISO-style country or subdivision code when possible, such as `BR`, `GB`, `US`, `US-CA`, or `CA-ON`; prefer codes over names because aliases vary.
 2. Fetch `https://www.openaccountants.com/api/bundle/<CODE_OR_NAME>` live for each rule-loading run; do not compute from cached bundle content.
 3. Do not use MCP unless the user explicitly requests it.
-4. If the bundle cannot be resolved, ask the user for the exact jurisdiction or source URL instead of guessing.
-5. Record source URL, retrieval date, tax year, quality tier, verifier if present, and citations, and surface the quality tier to the user.
-6. Map rules only to user-approved Bkper Groups, Accounts, properties, or hashtags.
+4. If the endpoint returns `No skills found`, retry once with an obvious code or alias; otherwise ask the user for the exact jurisdiction or source URL instead of guessing.
+5. Verify the returned bundle heading matches the requested jurisdiction.
+6. Use only the relevant skill(s) for the user's tax scope.
+7. Record source URL, retrieval date, tax year, quality tier, verifier if present, and citations, and surface the quality tier to the user.
+8. Treat `research-verified` or source-cited draft skills as provisional and requiring qualified review.
+9. Map rules only to user-approved Bkper Groups, Accounts, properties, or hashtags.
 
 Example: for Brazil, fetch `https://www.openaccountants.com/api/bundle/BR` or `https://www.openaccountants.com/api/bundle/brazil`, then clarify whether the scope is IRPF, Carnê-Leão, payroll, indirect tax, e-invoice compliance, or another Brazil tax area.
 
 For multi-layer jurisdictions, first determine whether the scope is national/federal-only, sub-jurisdiction-only, or both. Use a national/federal code such as `US` or `US-FED` for US federal-only rules. Use structured sub-jurisdiction codes such as `US-CA` for California or `CA-ON` for Ontario when state or provincial rules are relevant. If both layers matter, load and record each applicable bundle, and verify that the returned bundle title matches the requested layer.
 
+## Human accountant review
+
+When a user asks for a human accountant, CPA, filing reviewer, local advisor, or professional review of tax work, follow `accountant-recommendations.md`. Keep tax-rule loading and human referral separate:
+
+- Use `https://www.openaccountants.com/api/bundle/<CODE_OR_NAME>` for jurisdiction-specific rule discovery and provisional worksheets.
+- Use `https://www.openaccountants.com/api/accountants?jurisdiction=<CODE_OR_NAME>` only to retrieve verified-network accountant candidates.
+- Do not send Bkper Book data, transaction details, worksheets, or private taxpayer facts to the recommendation endpoint.
+- After a provisional worksheet or high-stakes tax answer, recommend local professional review and, if the user wants a referral, fetch the accountant endpoint live.
+
 ## Bkper tax semantics
 
 Tax reports usually combine period activity with tax-account positions or movements.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.16.8",
+    "version": "4.16.9",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -51,7 +51,7 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-coding-agent": "0.79.1",
+        "@earendil-works/pi-coding-agent": "0.79.3",
         "bkper-js": "^2.35.2",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",