@tracken/cli 0.0.0-stage → 0.2.1

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 (143) hide show
  1. package/CHANGELOG.md +404 -0
  2. package/LICENSE +21 -0
  3. package/README.md +310 -2
  4. package/dist/bin/tracken.d.ts +2 -0
  5. package/dist/bin/tracken.js +5 -0
  6. package/dist/cli/args.d.ts +17 -0
  7. package/dist/cli/args.js +114 -0
  8. package/dist/cli/commands/api.d.ts +2 -0
  9. package/dist/cli/commands/api.js +73 -0
  10. package/dist/cli/commands/auth.d.ts +8 -0
  11. package/dist/cli/commands/auth.js +141 -0
  12. package/dist/cli/commands/mcp.d.ts +19 -0
  13. package/dist/cli/commands/mcp.js +89 -0
  14. package/dist/cli/commands/org.d.ts +24 -0
  15. package/dist/cli/commands/org.js +123 -0
  16. package/dist/cli/context.d.ts +54 -0
  17. package/dist/cli/context.js +135 -0
  18. package/dist/cli/execute.d.ts +16 -0
  19. package/dist/cli/execute.js +112 -0
  20. package/dist/cli/help.d.ts +8 -0
  21. package/dist/cli/help.js +153 -0
  22. package/dist/cli/main.d.ts +2 -0
  23. package/dist/cli/main.js +114 -0
  24. package/dist/cli/operation-args.d.ts +25 -0
  25. package/dist/cli/operation-args.js +245 -0
  26. package/dist/core/auth/oauth.d.ts +39 -0
  27. package/dist/core/auth/oauth.js +102 -0
  28. package/dist/core/auth/scopes.d.ts +19 -0
  29. package/dist/core/auth/scopes.js +49 -0
  30. package/dist/core/auth/secret-store.d.ts +60 -0
  31. package/dist/core/auth/secret-store.js +141 -0
  32. package/dist/core/auth/session.d.ts +75 -0
  33. package/dist/core/auth/session.js +200 -0
  34. package/dist/core/catalog.d.ts +12 -0
  35. package/dist/core/catalog.js +33 -0
  36. package/dist/core/client.d.ts +22 -0
  37. package/dist/core/client.js +45 -0
  38. package/dist/core/config.d.ts +27 -0
  39. package/dist/core/config.js +109 -0
  40. package/dist/core/environments.d.ts +21 -0
  41. package/dist/core/environments.js +53 -0
  42. package/dist/core/errors.d.ts +96 -0
  43. package/dist/core/errors.js +248 -0
  44. package/dist/core/index.d.ts +21 -0
  45. package/dist/core/index.js +22 -0
  46. package/dist/core/jobs.d.ts +15 -0
  47. package/dist/core/jobs.js +19 -0
  48. package/dist/core/operations.d.ts +108 -0
  49. package/dist/core/operations.js +7 -0
  50. package/dist/core/output/format.d.ts +19 -0
  51. package/dist/core/output/format.js +62 -0
  52. package/dist/core/output/render.d.ts +53 -0
  53. package/dist/core/output/render.js +229 -0
  54. package/dist/core/pagination.d.ts +2 -0
  55. package/dist/core/pagination.js +3 -0
  56. package/dist/core/request.d.ts +29 -0
  57. package/dist/core/request.js +109 -0
  58. package/dist/core/version.d.ts +10 -0
  59. package/dist/core/version.js +13 -0
  60. package/dist/generated/mcp-tools.d.ts +2 -0
  61. package/dist/generated/mcp-tools.js +5937 -0
  62. package/dist/generated/operations.d.ts +4 -0
  63. package/dist/generated/operations.js +17701 -0
  64. package/dist/mcp/errors.d.ts +34 -0
  65. package/dist/mcp/errors.js +100 -0
  66. package/dist/mcp/live.d.ts +3 -0
  67. package/dist/mcp/live.js +5 -0
  68. package/dist/mcp/prompts.d.ts +23 -0
  69. package/dist/mcp/prompts.js +101 -0
  70. package/dist/mcp/resources.d.ts +25 -0
  71. package/dist/mcp/resources.js +125 -0
  72. package/dist/mcp/server.d.ts +20 -0
  73. package/dist/mcp/server.js +59 -0
  74. package/dist/mcp/session.d.ts +60 -0
  75. package/dist/mcp/session.js +105 -0
  76. package/dist/mcp/tools.d.ts +17 -0
  77. package/dist/mcp/tools.js +181 -0
  78. package/dist/mcp/types.d.ts +25 -0
  79. package/dist/mcp/types.js +2 -0
  80. package/node_modules/@tracken/sdk/LICENSE +21 -0
  81. package/node_modules/@tracken/sdk/README.md +76 -0
  82. package/node_modules/@tracken/sdk/SOURCE.json +10 -0
  83. package/node_modules/@tracken/sdk/dist/client.d.ts +94 -0
  84. package/node_modules/@tracken/sdk/dist/client.js +258 -0
  85. package/node_modules/@tracken/sdk/dist/credentials.d.ts +60 -0
  86. package/node_modules/@tracken/sdk/dist/credentials.js +122 -0
  87. package/node_modules/@tracken/sdk/dist/decimal.d.ts +20 -0
  88. package/node_modules/@tracken/sdk/dist/decimal.js +67 -0
  89. package/node_modules/@tracken/sdk/dist/environments.d.ts +14 -0
  90. package/node_modules/@tracken/sdk/dist/environments.js +16 -0
  91. package/node_modules/@tracken/sdk/dist/errors.d.ts +150 -0
  92. package/node_modules/@tracken/sdk/dist/errors.js +190 -0
  93. package/node_modules/@tracken/sdk/dist/generated/operations.d.ts +1955 -0
  94. package/node_modules/@tracken/sdk/dist/generated/operations.js +2746 -0
  95. package/node_modules/@tracken/sdk/dist/generated/schema.d.ts +17988 -0
  96. package/node_modules/@tracken/sdk/dist/generated/schema.js +5 -0
  97. package/node_modules/@tracken/sdk/dist/index.d.ts +27 -0
  98. package/node_modules/@tracken/sdk/dist/index.js +24 -0
  99. package/node_modules/@tracken/sdk/dist/jobs.d.ts +23 -0
  100. package/node_modules/@tracken/sdk/dist/jobs.js +80 -0
  101. package/node_modules/@tracken/sdk/dist/operations.d.ts +23 -0
  102. package/node_modules/@tracken/sdk/dist/operations.js +2 -0
  103. package/node_modules/@tracken/sdk/dist/pagination.d.ts +19 -0
  104. package/node_modules/@tracken/sdk/dist/pagination.js +49 -0
  105. package/node_modules/@tracken/sdk/dist/request.d.ts +27 -0
  106. package/node_modules/@tracken/sdk/dist/request.js +10 -0
  107. package/node_modules/@tracken/sdk/dist/runtime.d.ts +22 -0
  108. package/node_modules/@tracken/sdk/dist/runtime.js +33 -0
  109. package/node_modules/@tracken/sdk/dist/tracken.d.ts +74 -0
  110. package/node_modules/@tracken/sdk/dist/tracken.js +203 -0
  111. package/node_modules/@tracken/sdk/dist/types.d.ts +130 -0
  112. package/node_modules/@tracken/sdk/dist/types.js +1 -0
  113. package/node_modules/@tracken/sdk/dist/version.d.ts +2 -0
  114. package/node_modules/@tracken/sdk/dist/version.js +2 -0
  115. package/node_modules/@tracken/sdk/package.json +42 -0
  116. package/node_modules/openapi-fetch/CHANGELOG.md +565 -0
  117. package/node_modules/openapi-fetch/CONTRIBUTING.md +102 -0
  118. package/node_modules/openapi-fetch/LICENSE +21 -0
  119. package/node_modules/openapi-fetch/README.md +122 -0
  120. package/node_modules/openapi-fetch/dist/index.cjs +547 -0
  121. package/node_modules/openapi-fetch/dist/index.cjs.map +1 -0
  122. package/node_modules/openapi-fetch/dist/index.d.cts +337 -0
  123. package/node_modules/openapi-fetch/dist/index.d.mts +335 -0
  124. package/node_modules/openapi-fetch/dist/index.d.ts +337 -0
  125. package/node_modules/openapi-fetch/dist/index.mjs +531 -0
  126. package/node_modules/openapi-fetch/dist/index.mjs.map +1 -0
  127. package/node_modules/openapi-fetch/package.json +77 -0
  128. package/node_modules/openapi-fetch/src/index.d.ts +345 -0
  129. package/node_modules/openapi-fetch/src/index.js +689 -0
  130. package/node_modules/openapi-typescript-helpers/CHANGELOG.md +98 -0
  131. package/node_modules/openapi-typescript-helpers/LICENSE +21 -0
  132. package/node_modules/openapi-typescript-helpers/README.md +5 -0
  133. package/node_modules/openapi-typescript-helpers/dist/index.cjs +3 -0
  134. package/node_modules/openapi-typescript-helpers/dist/index.cjs.map +1 -0
  135. package/node_modules/openapi-typescript-helpers/dist/index.d.cts +167 -0
  136. package/node_modules/openapi-typescript-helpers/dist/index.d.mts +167 -0
  137. package/node_modules/openapi-typescript-helpers/dist/index.d.ts +167 -0
  138. package/node_modules/openapi-typescript-helpers/dist/index.mjs +2 -0
  139. package/node_modules/openapi-typescript-helpers/dist/index.mjs.map +1 -0
  140. package/node_modules/openapi-typescript-helpers/package.json +39 -0
  141. package/openapi/SOURCE.json +10 -0
  142. package/openapi/openapi.yaml +30514 -0
  143. package/package.json +63 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,404 @@
1
+ # Changelog
2
+
3
+ Each release is a git tag `v<version>` and a GitHub release that carries the CLI's `npm pack`
4
+ tarball (with `@tracken/sdk` bundled inside) and the SDK's own tarball. From v0.2.0 the same two
5
+ tarballs are also published to npm as `@tracken/cli` and `@tracken/sdk`. The API document a
6
+ release was built from is in `openapi/SOURCE.json`, and `tracken --version` prints it.
7
+
8
+ ## v0.2.1 (16.11.2026)
9
+
10
+ Built from Tracken Accounts' public API document `2026-11-09` (`x-stability: draft`),
11
+ accounting_software `24e91d230`. Requires Node.js 22 or later. Additive: nothing that worked with
12
+ v0.2.0 changes.
13
+
14
+ ### Trial limits: `409` `TRIAL_LIMIT_REACHED`
15
+
16
+ Sign-up to Tracken Accounts opens to everyone, so a company on a free trial may send only a set
17
+ number of customer e-mails a day and digitize only a set number of documents a month (Tracken sets
18
+ the numbers; today 50 and 100). While the subscription is switched off this is never answered, and
19
+ a company on a chosen plan never meets it.
20
+
21
+ - **`409` `TRIAL_LIMIT_REACHED`** on `tracken sales-invoices send` and `tracken quotes send` (the
22
+ day's e-mails) and on `tracken documents digitize` (the month's documents). Nothing was sent or
23
+ started. The CLI exits 7 and says which allowance is used, its number and the day it resets
24
+ (`context.resets_on`; days and months are counted in Europe/Tallinn): do not retry before then;
25
+ an owner choosing a plan in the app lifts it at once. `context.limit` is an open list
26
+ (`emails_per_day` and `ocr_per_month` here; the app's own operations also answer `companies`,
27
+ `firm_companies` and `ai_per_month`), so a value the CLI does not know is shown as sent. An
28
+ allowance with no reset day lasts until an owner chooses a plan.
29
+ - **`tracken mcp`** tells the model which allowance is used and not to retry before the reset day
30
+ (`send_sales_invoice`, `digitize_document`).
31
+ - **SDK:** a `TrackenTrialLimitError`, still a `TrackenConflictError`, with `limit` (`TrialLimit`,
32
+ an open type), `max` and `resetsOn`. Nothing retries it.
33
+
34
+ Known error codes 328 → 329; still 184 operations and 50 MCP tools.
35
+
36
+ ## v0.2.0 (14.11.2026)
37
+
38
+ Built from Tracken Accounts' public API document `2026-11-09` (`x-stability: draft`),
39
+ accounting_software `a2e2b6432`. Requires Node.js 22 or later. The first release on npm, under
40
+ the MIT license: `npm i -g @tracken/cli`, and `npm i @tracken/sdk` for the SDK on its own.
41
+
42
+ ### Upgrading from v0.1.0
43
+
44
+ The API is still a draft, so this release breaks some clients. Check these first; each has its
45
+ details below.
46
+
47
+ - Sales invoices and quotes are separate resources (`SalesInvoice`, `Quote`), and every invoice,
48
+ quote and payment field uses its public name only.
49
+ - Refusals about a record's state answer `409` (exit 7) instead of `400` (exit 9): issuing a
50
+ non-draft, sending a draft, an expired quote, a cancelled purchase invoice, an archived
51
+ customer or supplier, a prepayment already deducted, a credit note's uncreditable source and
52
+ the rest. `error.code` is unchanged.
53
+ - A bank statement's `closing_balance` is `statement_balance`, and a statement names its
54
+ `currency`.
55
+ - The permission `billing.manage` is `subscription.manage`.
56
+ - Two action paths are camelCase (`/objects:assignPaymentReferences`,
57
+ `/webhook-endpoints/{id}:rotateSecret`); the commands keep their names.
58
+ - A bank statement in another currency than its bank account is refused at import, and a
59
+ purchase invoice line on the accounts payable or receivable control account is refused.
60
+ - Retired codes: `INVOICE_TRANSACTION_CURRENCY_UNSUPPORTED`, `OPENING_STATE_CURRENCY_NOT_EUR` and
61
+ `BANK_STATEMENT_LINE_BLOCKED_CURRENCY`.
62
+ - New refusals from the paid subscription (none is answered while it is switched off): `402`
63
+ `SUBSCRIPTION_INACTIVE` (exit 13; the SDK's `TrackenPaymentRequiredError`), `409`
64
+ `PLAN_LIMIT_REACHED`, `409` `WORK_MONTH_CONFIRM_REQUIRED` and `EXTRA_MONTH_CONFIRM_REQUIRED` (a
65
+ person confirms the month in the app, then the same command runs again), and `403`
66
+ `PLAN_FEATURE_NOT_INCLUDED` and `SANDBOX_ACTION_BLOCKED`. Nothing retries them automatically.
67
+ - SDK, TypeScript only: response enums are open types, so an exhaustive `switch` over one needs a
68
+ `default` branch. A fixed asset's figures may carry up to 10 decimal places.
69
+
70
+ New: journals, accounts, bank accounts, bank lines, billing plans and the opening state in other
71
+ currencies, and foreign documents in a migration's history; an `ETag` on every create; billing
72
+ values computed from a purchase invoice; per-operation error codes; the subscription refusals,
73
+ with exit 13 for a `402`. Known error codes 291 → 328; still 184 operations and 50 MCP tools.
74
+
75
+ ### Subscription refusals: `402`, plan limits, month confirmation and the test copy
76
+
77
+ Tracken Accounts is moving to a paid subscription. While it is switched off none of these is
78
+ answered, but clients handle them now. None is worth retrying unchanged, and the CLI and the SDK
79
+ retry none of them.
80
+
81
+ - **`402` `SUBSCRIPTION_INACTIVE`, exit 13 (new).** The organization's subscription is not active,
82
+ so every operation is refused, reads included, except `users get-me`, `organization get` and the
83
+ data export. The CLI says why (`context.reason`: `trial_ended`, `not_paid`, `cancelled`,
84
+ `payer_stopped`, an open list, so another value is shown as sent) and until when the data can
85
+ still be exported (`context.export_until`), and asks for an owner to reopen the subscription in
86
+ the app. The SDK raises a `TrackenPaymentRequiredError` (status `402`) with `reason`
87
+ (`SubscriptionInactiveReason`, an open type) and `exportUntil`.
88
+ - **`409` `WORK_MONTH_CONFIRM_REQUIRED` and `EXTRA_MONTH_CONFIRM_REQUIRED`** on the writes that
89
+ change the books, and on `bank-statements import`. The write would start a month the
90
+ subscription bills (`context.month`, `price`, `currency`). A person confirms it in the app (an
91
+ API credential cannot), then the same command runs again; the CLI says so and does not retry by
92
+ itself.
93
+ - **`409` `PLAN_LIMIT_REACHED`** (`transactions create`, `sales-invoices issue`,
94
+ `purchase-invoices post`, `bank-lines reconcile`): the month holds the plan's document limit;
95
+ the CLI names the plan an owner moves to (`context.next_plan`).
96
+ - **`403` `PLAN_FEATURE_NOT_INCLUDED`**: the plan does not include the feature
97
+ (`context.capability`, `context.required_plan`); for an API credential without API access, every
98
+ operation that names an organization. **`403` `SANDBOX_ACTION_BLOCKED`**: a test copy of a
99
+ company does not hand out the KMD and VD files (`vat-returns get --format kmd|vd`).
100
+ - `tracken mcp` tells the model the same, with "do not retry before they have acted".
101
+ - Known error codes 322 → 328: `EXTRA_MONTH_CONFIRM_REQUIRED`, `PLAN_FEATURE_NOT_INCLUDED`,
102
+ `PLAN_LIMIT_REACHED`, `SANDBOX_ACTION_BLOCKED`, `SUBSCRIPTION_INACTIVE` and
103
+ `WORK_MONTH_CONFIRM_REQUIRED`.
104
+
105
+ ### Open response enums, an ETag on every create, and the subscription permission
106
+
107
+ - **Breaking: the permission `billing.manage` is `subscription.manage`** in `users get-me`
108
+ (`getCurrentUser`, `data.organizations[].permissions[]`): an owner's right over the company's
109
+ Tracken subscription. No operation required it.
110
+ - **Response enums are open types in the SDK.** The document marks each enum that appears only in
111
+ responses `x-extensible-enum: true` (88 of them: a job's `status`, a sales invoice's `status`,
112
+ `ExchangeRateSource`, `Permission` and the rest), meaning the API may add values. The SDK now
113
+ types them as the known values plus any string, for example
114
+ `"ecb" | "manual" | "derived" | "import" | (string & {})`, so editors still complete the known
115
+ values and an unknown one is not a type error. A request enum stays closed. Code that checks
116
+ such a field with an exhaustive `switch` needs a `default` branch. openapi-typescript ignores
117
+ the extension, so the codegen types these itself (`codegen/open-enums.ts`); the generated JSDoc
118
+ of an open enum no longer carries `@enum`.
119
+ - **Every create answers an `ETag`** on its `201`: contacts, items, accounts, transactions,
120
+ quotes, payments, bank accounts, documents, fixed assets, billing plans, VAT returns and the
121
+ rest (`createDocumentLink` excepted), as the two invoice creates already did. The SDK returns it
122
+ as the result's `etag`, so `ifMatch: created` guards the first update without a read. A new VAT
123
+ return is a draft, so its tag is weak (`W/"..."`): a cache validator for `If-None-Match` only,
124
+ since no VAT return operation takes `If-Match`. The `200` a create answers for an existing
125
+ `external_ref` carries no `ETag`.
126
+ - `billing-plans create`: `start_period` null means not chosen yet; the plan saves as a draft,
127
+ approving it needs a start, and a copy (`based_on_plan_id`) refuses null.
128
+
129
+ ### Foreign currencies in journals, accounts, bank accounts, billing plans and the opening state
130
+
131
+ - **Breaking: a bank statement's `closing_balance` is `statement_balance`.** `BankStatement`
132
+ (`bank-statements list|get`) renames it, with no alias, and gains `currency`, the bank account's
133
+ currency, which its balances and lines are in. The CLI's table output prints
134
+ `statement_balance` as money; a script that reads `closing_balance` reads `statement_balance`.
135
+ - **Bank lines carry their rate.** `BankLine` (`bank-lines list|get|reconcile|unreconcile`) gains
136
+ `exchange_rate` (the ECB rate of the booking date, line-currency units per 1 EUR),
137
+ `book_amount` (the line in EUR) and `rate_date` (the ECB publication day). A line in EUR reads
138
+ `1`, its own `amount` and no `rate_date`; a foreign line with no rate yet reads null in all three.
139
+
140
+ - **Journals.** A transaction may be kept in a currency the organization has activated
141
+ (`CURRENCY_NOT_ACTIVE` otherwise), one currency and one rate per transaction:
142
+ `transactions create|update` take `--exchange-rate` (omitted, the ECB rate of the date). In
143
+ another currency each entry sends `foreign_debit` or `foreign_credit`, and its EUR `debit` and
144
+ `credit` are computed. A read answers `exchange_rate`, `book_currency`, `exchange_rate_source`
145
+ and `foreign_total`, and each entry's `foreign_amount` and `currency`. `fx_revaluation` is a new
146
+ `origin`. `TRANSACTION_CURRENCY_NOT_SUPPORTED` now refuses only a move to another foreign
147
+ currency without entries typed in it; this replaces "a journal entry is in the book currency
148
+ only".
149
+ - **Accounts.** `accounts create|update --currency`: the currency an account is kept in, null for
150
+ EUR, and the read-only `currency_locked`. Refusals: 400 `ACCOUNT_CURRENCY_IS_BOOK_CURRENCY` and
151
+ `ACCOUNT_OPENING_IN_CURRENCY`; 409 `ACCOUNT_CURRENCY_SET_BY_BANK_ACCOUNT`,
152
+ `ACCOUNT_CURRENCY_HAS_BOOK_POSTINGS` and `ACCOUNT_CURRENCY_HAS_FOREIGN_POSTINGS`. A posting to
153
+ an account kept in a currency carries its amount in it (400 `FX_ACCOUNT_CURRENCY_MISMATCH`).
154
+ - **Bank accounts.** A bank account in another currency keeps its GL account in that currency:
155
+ `bank-accounts create|update` answer 409 `BANK_ACCOUNT_GL_CURRENCY_CONFLICT`,
156
+ `BANK_ACCOUNT_GL_CURRENCY_MISMATCH` and `BANK_ACCOUNT_CURRENCY_LOCKED`, and a bank account reads
157
+ `currency_locked`. `bank-statements import` refuses a statement or line in another currency than
158
+ the account (400 `BANK_STATEMENT_CURRENCY_MISMATCH`; nothing is imported), and
159
+ `bank-lines reconcile` answers 400 `BANK_LINE_CURRENCY_MISMATCH`.
160
+ - **Billing.** `billing-plans create|update --currency` (omitted on a create, the book currency),
161
+ the read-only `currency_locked`, and 409 `BILLING_PLAN_CURRENCY_LOCKED` once an invoice from the
162
+ plan is issued. `billing-runs create --exchange-rate` for a currency the ECB publishes no rate
163
+ for. A run answers its `currency`, and each recipient its `currency`, `exchange_rate` and
164
+ `book_total`.
165
+ - **Opening state.** An account balance takes `currency`, `foreign_amount` and `exchange_rate`
166
+ (for an account kept in a currency); an advance takes `currency`, `exchange_rate` and
167
+ `book_amount`; an open invoice takes `book_outstanding`, the EUR still open as the source books
168
+ hold it.
169
+ - The SDK refuses a JSON number at every new decimal field (`foreign_debit`, `foreign_credit`, the
170
+ rates, `foreign_amount`, `book_amount`, `book_outstanding`) before anything is sent.
171
+
172
+ ### Purchases, fixed assets and figures out of range
173
+
174
+ - `purchase-invoices create|update` naming an archived supplier is 409
175
+ `BUSINESS_PARTNER_ARCHIVED` (exit 7), as the sales documents are; `error.context` names the
176
+ partner.
177
+ - A fixed asset's figures (`acquisition_cost`, `residual_value`,
178
+ `opening_accumulated_depreciation`, `accumulated_depreciation`, `book_value`, and a schedule
179
+ row's `accumulated` and `book_value`) are read exactly as stored: `LineDecimal`, up to 10
180
+ decimal places. Writes still take cents.
181
+ - A figure out of its column's range is 400 `VALIDATION_ERROR` (`context.reason`
182
+ `value_too_large`, exit 9) instead of 500 `INTERNAL_ERROR` (exit 11). Nothing is written.
183
+ - The "Migration & sync" area says to create a contact's documents before archiving the contact.
184
+ - Known error codes: 311 → 322. New: `ACCOUNT_CURRENCY_HAS_BOOK_POSTINGS`,
185
+ `ACCOUNT_CURRENCY_HAS_FOREIGN_POSTINGS`, `ACCOUNT_CURRENCY_IS_BOOK_CURRENCY`,
186
+ `ACCOUNT_CURRENCY_SET_BY_BANK_ACCOUNT`, `ACCOUNT_OPENING_IN_CURRENCY`,
187
+ `BANK_ACCOUNT_CURRENCY_LOCKED`, `BANK_ACCOUNT_GL_CURRENCY_CONFLICT`,
188
+ `BANK_ACCOUNT_GL_CURRENCY_MISMATCH`, `BANK_LINE_CURRENCY_MISMATCH`,
189
+ `BANK_STATEMENT_CURRENCY_MISMATCH`, `BILLING_PLAN_CURRENCY_LOCKED` and
190
+ `FX_ACCOUNT_CURRENCY_MISMATCH`. Retired: `BANK_STATEMENT_LINE_BLOCKED_CURRENCY`, replaced by
191
+ `BANK_STATEMENT_CURRENCY_MISMATCH` at import and `BANK_LINE_CURRENCY_MISMATCH` at
192
+ reconciliation.
193
+
194
+ ### Sales invoices and quotes
195
+
196
+ - Sales invoices and quotes are separate resources over a shared `SalesDocument` base:
197
+ `SalesInvoice.kind` is `invoice`, `credit_note`, `prepayment_invoice` or `late_fee`, and
198
+ `Quote.kind` is `quote` only. A quote no longer carries the invoice-only fields (payments,
199
+ `amount_paid`, `amount_due`, `issued_at` and the rest), and an invoice no longer carries
200
+ `quote_status` or `valid_until`.
201
+ - Every invoice, quote and payment field uses its public name only; an old spelling is
202
+ refused with `extra_forbidden`.
203
+
204
+ ### A refusal about a record's state is 409, not 400
205
+
206
+ The error body and `error.code` are unchanged; only the HTTP status moves, so these commands now
207
+ exit 7 (conflict) where they exited 9 (invalid). A script that switches on `error.code` sees no
208
+ change.
209
+
210
+ - `sales-invoices issue` (`issueSalesInvoice`): `INVOICE_NOT_DRAFT`, including an issue that lost
211
+ a race to a concurrent one.
212
+ - `sales-invoices send` (`sendSalesInvoice`): `INVOICE_NOT_ISSUED` for a draft.
213
+ - `quotes accept` (`acceptQuote`): `QUOTE_EXPIRED`; `sales-invoices create` from an expired quote
214
+ answers it as 409 too.
215
+ - `sales-invoices update` (`updateSalesInvoice`): `PREPAYMENT_INVOICE_NOT_EDITABLE`.
216
+ - `purchase-invoices update` (`updatePurchaseInvoice`): `PURCHASE_INVOICE_CANCELLED` and
217
+ `PREPAYMENT_INVOICE_NOT_EDITABLE`.
218
+ - `payments create` (`createPayment`) and `bank-lines reconcile` (`reconcileBankLine`):
219
+ `PAYMENT_INVOICE_NOT_ISSUED` (the invoice is not issued, is voided or is archived).
220
+ - `objects create` (`createObject`): `BILLING_OBJECT_TYPE_ARCHIVED` (the object's type is
221
+ archived).
222
+ - `sales-invoices create` (a credit note's `credits_invoice_id`) and `purchase-invoices create`
223
+ (`kind: credit_note`): `CREDIT_NOTE_SOURCE_NOT_CREDITABLE`, when the credited invoice is not
224
+ issued, is partly paid or paid, or deducts a prepayment. `CREDIT_NOTE_SOURCE_NOT_INVOICE` (the
225
+ source is not an invoice at all) stays 400.
226
+ - New codes, answered as 409:
227
+ - `BUSINESS_PARTNER_ARCHIVED` and `PARTNER_ARCHIVED_MATCH` on `sales-invoices create|update`
228
+ and `quotes create|update` when the customer is, or resolves to, an archived partner;
229
+ `details` names the partner.
230
+ - `PREPAYMENT_ALREADY_DEDUCTED` on `sales-invoices create|update|issue` and
231
+ `purchase-invoices post` when another invoice already deducts the prepayment. A purchase
232
+ draft reserves nothing, so `purchase-invoices create|update` save a second one and posting it
233
+ is refused.
234
+
235
+ ### Two action paths renamed
236
+
237
+ Every action after the `:` is one camelCase word in the document now; the last two kebab spellings
238
+ were renamed, with no alias for the old paths.
239
+
240
+ - `objects assign-payment-references` (`assignObjectPaymentReferences`) calls
241
+ `POST /objects:assignPaymentReferences`. The command, the SDK method, the body and the answer
242
+ are unchanged; only a request sent by path (`tracken api`) moves to the new spelling.
243
+ - `rotateWebhookEndpointSecret` is `POST /webhook-endpoints/{id}:rotateSecret`. It is `later`, so
244
+ it is not a command yet.
245
+ - The command tree spells a camelCase action in kebab case (`:assignPaymentReferences` →
246
+ `assign-payment-references`), so every command word stays kebab case.
247
+
248
+ ### Added
249
+
250
+ - Each operation's error responses name the codes it answers with that status, and the shared
251
+ responses name the codes any operation can answer (`VALIDATION_ERROR`, `INSUFFICIENT_SCOPE`,
252
+ `DEMO_ORG_ACTION_BLOCKED`, `IDEMPOTENCY_KEY_REUSED` and the rest), so the reference says which
253
+ codes to expect from which operation. Responses the server already gave and the
254
+ document now declares: `users get-me` 409 `ACCOUNT_EMAIL_CONFLICT`, `organization get` 404
255
+ `ORG_NOT_FOUND`, `vat-returns get` 400 `VAT_RETURN_SCHEMA_INVALID`, `dimensions list-values` 404
256
+ `DIMENSION_NOT_FOUND`, and `objects create|update` 503 `ADDRESS_STORE_UNAVAILABLE` (a service
257
+ the operation depends on is briefly unavailable). The SDK retries that 503 on `objects create`
258
+ (a POST with its `Idempotency-Key`) but not on the PATCH of `objects update`; the CLI exits 11
259
+ when it stays unavailable. The SDK's response types gain these statuses.
260
+ - The 201 of `createSalesInvoice` and `createPurchaseInvoice` carries an `ETag`, the same version
261
+ a read of the new invoice answers. In the SDK the create's result has it as `etag`, so
262
+ `ifMatch: created` guards the first update without a read.
263
+ - Opening state in other currencies: an open invoice of `opening-state replace`
264
+ (`replaceOpeningState`) may be in the book currency or any currency the organization has
265
+ activated (`CURRENCY_NOT_ACTIVE` otherwise; before, only `EUR`), with an optional
266
+ `exchange_rate`, the source system's rate. Omitted, the ECB rate of the balances date; `1` is
267
+ refused on a foreign invoice (`OPENING_STATE_FOREIGN_RATE_OF_ONE`). `opening-state get` reads
268
+ the stored rate back.
269
+ - History of foreign documents: an issued create linked to an imported transaction
270
+ (`transaction_id`) may be in another currency and ties in EUR at the `exchange_rate` sent, or at
271
+ the rate the journal was booked at. A payment linked to an imported transaction may settle a
272
+ foreign document, in EUR or in the document's currency.
273
+ - Billing: a plan's `asked` number variable takes an `invoice_formula`, how a run computes the
274
+ value it takes from a purchase invoice's chosen lines (for example
275
+ `sum_lines(line.amount / line.quantity)`; null is the lines' sum). Formulas gain the `invoice`
276
+ and `line` scopes and `sum_lines`; `billing-formulas parse` takes the `invoice` context, and
277
+ the catalogue lists the `invoice` and `lines` references. A run's variable value is a
278
+ `VariableDecimal` (at most 6 decimal places, kept as sent), and a run's values read back the
279
+ `invoice_formula` they were computed with. The SDK's `DECIMAL_PATTERNS` has `VariableDecimal`.
280
+
281
+ ### Behaviour
282
+
283
+ - A purchase invoice line on the organization's accounts payable or receivable control account is
284
+ refused (400 `PURCHASE_LINE_CONTROL_ACCOUNT` at the line), except a kept line that stays on the
285
+ account it already has.
286
+ - An update that sends an `exchange_rate` to an invoice brought in by an import is 409
287
+ `IMPORTED_INVOICE_RATE_SET_SEPARATELY` (an opening item's: 409
288
+ `OPENING_INVOICE_EDIT_IN_OPENING_STATE`); before, it answered 200 and dropped the rate.
289
+ - A purchase invoice's `book_tax_total` input is the printed VAT of the supply: a prepayment
290
+ deduction keeps its prepayment's VAT, so the stored figure is that less the deducted VAT.
291
+ - The open-item reports (`contact-balances`, `aging`, the `open_items` rows of `control-totals`)
292
+ add each open invoice at its book value in EUR, not at its face, and a sales invoice PDF's
293
+ balance block covers only the invoice's own currency.
294
+ - Known error codes: 292 → 311. New: `BILLING_PLAN_VARIABLE_INVOICE_FORMULA_INVALID`,
295
+ `BILLING_RUN_PURCHASE_FORMULA_NO_VALUE`, `BUSINESS_PARTNER_ARCHIVED`, `CURRENCY_NOT_ACTIVE`,
296
+ `IMPORTED_INVOICE_RATE_SET_SEPARATELY`, `OPENING_STATE_FOREIGN_RATE_OF_ONE`,
297
+ `PARTNER_ARCHIVED_MATCH`, `PREPAYMENT_ALREADY_DEDUCTED`, `PURCHASE_LINE_CONTROL_ACCOUNT`, and
298
+ the opening-state rules `opening-state replace` already answered with 400:
299
+ `OPENING_STATE_AS_OF_DATE_INVALID`, `OPENING_STATE_UNRESOLVED_REF`,
300
+ `OPENING_STATE_INVALID_ACCOUNT_TYPE`, `OPENING_STATE_UNBALANCED`,
301
+ `OPENING_STATE_SUBLEDGER_MISMATCH`, `OPENING_STATE_CONTROL_ACCOUNT_UNRESOLVED`,
302
+ `OPENING_STATE_NO_ZERO_TAX_CODE`, `OPENING_STATE_DUPLICATE_ENTRY`,
303
+ `OPENING_STATE_LINES_TOTAL_MISMATCH`, `OPENING_STATE_NEGATIVE_AMOUNT`,
304
+ `OPENING_STATE_FIXED_ASSET_INVALID` and `OPENING_STATE_PREPAYMENT_INVALID`. Retired (no longer
305
+ answered): `INVOICE_TRANSACTION_CURRENCY_UNSUPPORTED` and `OPENING_STATE_CURRENCY_NOT_EUR`.
306
+
307
+ ## v0.1.0 (09.11.2026)
308
+
309
+ The first release, built from Tracken Accounts' public API document `2026-11-09`
310
+ (`x-stability: draft`), accounting_software `6ad55dcca`. Requires Node.js 22 or later.
311
+
312
+ ### The CLI runs on `@tracken/sdk`
313
+
314
+ - `@tracken/sdk` is a typed TypeScript client for the public API, generated from the same document.
315
+ It lives in this repository as an npm workspace (`packages/sdk/`).
316
+ - The CLI's transport, pagination, job polling and errors are the SDK's. The CLI adds its own
317
+ wording and maps each error to an exit code.
318
+ - The CLI tarball bundles the SDK (`bundleDependencies`), so it installs with no registry access to
319
+ `@tracken/sdk`. The SDK's tarball comes with every release for direct use.
320
+ - SDK conventions:
321
+ - bodies are the `{"data": …}` envelope;
322
+ - money, prices and quantities are decimal strings;
323
+ - every POST carries an `Idempotency-Key`;
324
+ - `waitForJob` polls 202 jobs;
325
+ - `nextSince` is returned for sync reads;
326
+ - a rendition's 303 is followed to its file;
327
+ - the known error codes come from the document's `x-error-codes`, and any other code is still a
328
+ valid string.
329
+ - A request field with a `default` in the document is optional in the generated types. Callers do
330
+ not have to send what the server fills in itself, such as a transaction's `currency` and `origin`.
331
+
332
+ ### Commands
333
+
334
+ - Every operation the API serves is a command: 184 operations, generated from the document's
335
+ `x-availability`. The form is `tracken <resource> <verb> [ids…] [flags]`.
336
+ - `tracken api <METHOD> <path>` sends any request as the API takes it.
337
+ - Flags:
338
+ - `--since` reads in order of change and passes on `next_since`;
339
+ - `--all` and `--ndjson`;
340
+ - `--idempotency-key`;
341
+ - `--if-match`;
342
+ - `--wait` for background jobs.
343
+ - Errors print the API's code, message, field pointers and request id. Fixed exit codes run from
344
+ 0 to 12 (see the README).
345
+
346
+ ### Sign-in and organizations
347
+
348
+ - `tracken login` signs in through Tracken ID with the device authorization grant.
349
+ - It is read-only by default. `--write` adds the write scopes of the served operations, and
350
+ `--scope` names exact scopes.
351
+ - Tokens are kept in the OS keychain. Where there is none, they go to a file only you can read.
352
+ - `tracken logout` revokes the session.
353
+ - Organizations:
354
+ - `tracken org list|use|current` reads your organizations from `GET /users/me`, which needs no
355
+ scope.
356
+ - `org use` refuses an organization you cannot open.
357
+ - `--org` / `TRACKEN_ORG` overrides the choice for one command.
358
+ - `tracken whoami` shows where the CLI acts without calling the API. `--verify` confirms it with
359
+ the API, and for an API credential it adds the credential's name, expiry and idle limit.
360
+ - Machine mode: `TRACKEN_CLIENT_ID` / `TRACKEN_CLIENT_SECRET` exchange an API credential for a
361
+ short-lived token (client credentials).
362
+ - A `401` is never hidden. The session or credential is renewed once, and then the API's answer is
363
+ shown with what to run. A `403 INSUFFICIENT_SCOPE` prints the exact `tracken login --scope …` that
364
+ adds the missing scope.
365
+ - Environments: `--env prod|dev|local` (`TRACKEN_ENV`). Each environment keeps its own sessions
366
+ and chosen organization.
367
+
368
+ ### `Tracken-Agent`
369
+
370
+ - Every request names the program that sends it, and Accounts' audit log records the label beside
371
+ the token's client:
372
+ - the CLI sends `tracken-cli/<version>`;
373
+ - the MCP server sends its client's name and version;
374
+ - the SDK sends `tracken-sdk/<version>` unless the caller sets its own.
375
+ - The header is a label only. It changes nothing the token may do.
376
+
377
+ ### `tracken mcp`
378
+
379
+ - A local Model Context Protocol server on stdio, for Claude Code, Claude Desktop, Cursor and
380
+ VS Code. `--print-config claude|cursor|vscode` prints the client's configuration.
381
+ - Tools:
382
+ - 50 tools, generated from the operations the document marks for assistants (`x-mcp`);
383
+ - each tool has MCP annotations and a model-facing description;
384
+ - each failure carries an `action` that tells the assistant what to do.
385
+ - Resources: accounts, tax codes, dimensions, items, object types, fiscal years, periods and reports.
386
+ - Prompts: `month_end_check`, `record_supplier_invoice`, `explain_report` and `billing_run_preview`.
387
+ - Safety:
388
+ - The server is read-only until you run `tracken login --write`.
389
+ - Every write tool supports `dry_run`, and destructive tools ask the model to dry-run first and
390
+ get your confirmation.
391
+ - The server follows the CLI's session and organization with no restart.
392
+
393
+ ### End-to-end harness
394
+
395
+ - `scripts/e2e-dev.sh` is the machine-mode end-to-end run against the dev environment.
396
+ - It reads one API credential from 1Password once per run and keeps it in memory only.
397
+ - It works through the document's tags (Contacts, Sales, Billing, Banking, Fixed assets and the
398
+ rest), creating its records with dry runs first and counting them by the run's own `external_ref`.
399
+ - It checks that each response carries only the public schema's keys.
400
+ - It checks that every created record has an audit row with the credential as actor.
401
+ - It checks that no request sends `X-Organization-ID` and that every request carries the run's
402
+ `Tracken-Agent`.
403
+ - It starts `tracken mcp` with no credential.
404
+ - `e2e/dev/PERSON-CHECKLIST.md` is the person-mode checklist for the same environment.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tracken Technologies OÜ
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.