@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
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Errors and the exit codes scripts can branch on. Each API failure class has its own code, so a
3
+ * script can tell "sign in again" from "you may not" from "it changed under you" without parsing text.
4
+ */
5
+ import { TrackenApiError, TrackenAuthError, TrackenError, TrackenJobFailedError, TrackenNetworkError, TrackenUsageError } from "@tracken/sdk";
6
+ import { formatDate, formatDecimal } from "./output/format.js";
7
+ export const EXIT = {
8
+ ok: 0,
9
+ /** Anything not listed below. */
10
+ failure: 1,
11
+ /** The command line itself is wrong (unknown command or flag, bad value). */
12
+ usage: 2,
13
+ /** The API or Tracken ID could not be reached. */
14
+ network: 3,
15
+ /** 401, or no session: sign in again. */
16
+ unauthenticated: 4,
17
+ /** 403: a scope or the role does not allow it. */
18
+ forbidden: 5,
19
+ notFound: 6,
20
+ /** 409: the record's state does not allow it, or it already exists. */
21
+ conflict: 7,
22
+ /** 412: `If-Match` did not match; the record changed since it was read. */
23
+ preconditionFailed: 8,
24
+ /** 400 and 422: the request was refused as invalid; `details` point at the fields. */
25
+ invalid: 9,
26
+ /** 429 after the CLI's own retries. */
27
+ rateLimited: 10,
28
+ /** 5xx after the CLI's own retries. */
29
+ server: 11,
30
+ /** `--wait`: the job finished as failed. */
31
+ jobFailed: 12,
32
+ /** 402: the organization's subscription is not active; export the data or ask an owner to reopen it. */
33
+ paymentRequired: 13,
34
+ };
35
+ /**
36
+ * The SDK's errors are the CLI's: an API failure, a request refused before it was sent, an
37
+ * unreachable host and a failed job come from `@tracken/sdk` and map to exit codes in `exitCodeOf`.
38
+ */
39
+ export { TrackenApiError as ApiError, TrackenError, TrackenJobFailedError as JobFailedError, TrackenNetworkError as NetworkError, TrackenUsageError as UsageError, } from "@tracken/sdk";
40
+ /** A failure of the CLI itself, with the exit code it ends the process with. */
41
+ export class CliError extends TrackenError {
42
+ exitCode;
43
+ constructor(message, exitCode = EXIT.failure) {
44
+ super(message);
45
+ this.exitCode = exitCode;
46
+ }
47
+ }
48
+ export class AuthError extends CliError {
49
+ constructor(message) {
50
+ super(message, EXIT.unauthenticated);
51
+ }
52
+ }
53
+ /** An OAuth error answer from Tracken ID (RFC 6749 §5.2, RFC 8628 §3.5). */
54
+ export class OAuthError extends CliError {
55
+ error;
56
+ description;
57
+ status;
58
+ constructor(error, description, status) {
59
+ super(description ? `${error}: ${description}` : error, EXIT.unauthenticated);
60
+ this.error = error;
61
+ this.description = description;
62
+ this.status = status;
63
+ }
64
+ }
65
+ export function exitCodeForStatus(status) {
66
+ if (status === 401)
67
+ return EXIT.unauthenticated;
68
+ if (status === 402)
69
+ return EXIT.paymentRequired;
70
+ if (status === 403)
71
+ return EXIT.forbidden;
72
+ if (status === 404)
73
+ return EXIT.notFound;
74
+ if (status === 409)
75
+ return EXIT.conflict;
76
+ if (status === 412)
77
+ return EXIT.preconditionFailed;
78
+ if (status === 400 || status === 422)
79
+ return EXIT.invalid;
80
+ if (status === 429)
81
+ return EXIT.rateLimited;
82
+ if (status >= 500)
83
+ return EXIT.server;
84
+ return EXIT.failure;
85
+ }
86
+ /** The exit code a failure ends the CLI with. */
87
+ export function exitCodeOf(error) {
88
+ if (error instanceof CliError)
89
+ return error.exitCode;
90
+ if (error instanceof TrackenUsageError)
91
+ return EXIT.usage;
92
+ if (error instanceof TrackenApiError)
93
+ return exitCodeForStatus(error.status);
94
+ if (error instanceof TrackenNetworkError)
95
+ return EXIT.network;
96
+ if (error instanceof TrackenJobFailedError)
97
+ return EXIT.jobFailed;
98
+ if (error instanceof TrackenAuthError)
99
+ return EXIT.unauthenticated;
100
+ return EXIT.failure;
101
+ }
102
+ /** What a 401 after the renewal means for an API credential. */
103
+ export const MACHINE_CREDENTIAL_REFUSED = "The API credential was refused (disabled, expired or rotated?): check it under Settings → API access, or set TRACKEN_CLIENT_ID and TRACKEN_CLIENT_SECRET to a current one.";
104
+ const envFlag = (environment) => (environment && environment !== "prod" ? ` --env ${environment}` : "");
105
+ /**
106
+ * The one scope to add from those a 403 says would each admit the call: the only specific one when
107
+ * there is one (`contacts:read` over the `read` shorthand), else `read` when it is among them (any
108
+ * read scope admits a deletions feed), else the first.
109
+ */
110
+ export function scopeToAdd(admitting) {
111
+ const specific = admitting.filter((scope) => scope.includes(":"));
112
+ if (specific.length === 1)
113
+ return specific[0];
114
+ if (admitting.includes("read"))
115
+ return "read";
116
+ return admitting[0];
117
+ }
118
+ function scopeAdvice(error, context) {
119
+ const listed = error.admittingScopes.length > 1 ? `one of ${error.admittingScopes.join(", ")}` : error.missingScope;
120
+ if (!error.missingScope)
121
+ return error.code === "INSUFFICIENT_SCOPE" ? [" No scope admits this operation for this kind of sign-in."] : [];
122
+ const add = scopeToAdd(error.admittingScopes);
123
+ if (context.credentials === "machine") {
124
+ return [` Missing scope: ${listed}. Grant the API credential ${add} under Settings → API access (and include it in TRACKEN_SCOPE if that is set).`];
125
+ }
126
+ // `tracken login --scope` replaces the session's scopes, so the command keeps what it holds.
127
+ const scopes = [...new Set([...(context.grantedScopes ?? []), add])];
128
+ return [` Missing scope: ${listed}. Sign in with it: \`tracken login${envFlag(context.environment)} --scope ${scopes.join(" ")}\``];
129
+ }
130
+ /** What `context.reason` of `SUBSCRIPTION_INACTIVE` means; the list is open, so another value is shown as sent. */
131
+ const SUBSCRIPTION_REASONS = {
132
+ trial_ended: "the trial ended without a plan",
133
+ not_paid: "a payment is overdue",
134
+ cancelled: "the subscription was cancelled",
135
+ payer_stopped: "the accounting firm that paid for it stopped",
136
+ };
137
+ const contextText = (error, key) => {
138
+ const value = error.context?.[key];
139
+ return typeof value === "string" && value ? value : typeof value === "number" ? String(value) : undefined;
140
+ };
141
+ /** `2026-11` → `11.2026`, as the app writes a month; anything else as sent. */
142
+ const formatMonth = (value) => value.replace(/^(\d{4})-(\d{2})$/, "$2.$1");
143
+ export const TRIAL_LIMIT_REACHED = "TRIAL_LIMIT_REACHED";
144
+ /** What `context.limit` of `TRIAL_LIMIT_REACHED` counts; the list is open, so another value is shown as sent. */
145
+ const TRIAL_LIMITS = {
146
+ emails_per_day: "daily allowance of customer e-mails",
147
+ ocr_per_month: "monthly allowance of digitized documents",
148
+ companies: "allowance of companies per person",
149
+ firm_companies: "allowance of client companies per accounting firm",
150
+ ai_per_month: "monthly allowance of AI requests",
151
+ };
152
+ export function trialLimitFacts(error) {
153
+ const limit = contextText(error, "limit");
154
+ const max = contextText(error, "max");
155
+ const what = limit ? (TRIAL_LIMITS[limit] ?? `limit ${limit}`) : "limit";
156
+ const resetsOn = contextText(error, "resets_on");
157
+ return { used: `The trial's ${what}${max ? ` (${max})` : ""} is used`, resetsOn: resetsOn ? formatDate(resetsOn) : undefined };
158
+ }
159
+ /**
160
+ * What a subscription refusal means, in one sentence: what happened and who can change it. `retry` is
161
+ * what to do once they have ("run the same command again"; the MCP server says "call <tool> again").
162
+ * None of them is worth retrying unchanged, and nothing retries them automatically. Undefined for
163
+ * every other error.
164
+ */
165
+ export function subscriptionAdvice(error, retry = "run the same command again") {
166
+ switch (error.code) {
167
+ case "SUBSCRIPTION_INACTIVE": {
168
+ const reason = contextText(error, "reason");
169
+ const why = reason ? ` (${SUBSCRIPTION_REASONS[reason] ?? `reason: ${reason}`})` : "";
170
+ const until = contextText(error, "export_until");
171
+ const exportAdvice = until ? `Its data can still be exported in the app until ${formatDate(until)}` : "Its data can still be exported in the app";
172
+ return `The organization's subscription is not active${why}. ${exportAdvice}; ask an owner to reopen the subscription in the app. Until then every request fails the same way.`;
173
+ }
174
+ case "WORK_MONTH_CONFIRM_REQUIRED":
175
+ case "EXTRA_MONTH_CONFIRM_REQUIRED": {
176
+ const month = contextText(error, "month");
177
+ const price = contextText(error, "price");
178
+ const currency = contextText(error, "currency");
179
+ const what = month ? `the month ${formatMonth(month)}` : "the month";
180
+ const cost = price ? ` (${formatDecimal(price)}${currency ? ` ${currency}` : ""})` : "";
181
+ return `This write starts ${what}${cost} on the subscription: a person confirms it in the Tracken Accounts app (an API credential cannot), then ${retry}.`;
182
+ }
183
+ case "PLAN_LIMIT_REACHED": {
184
+ const month = contextText(error, "month");
185
+ const limit = contextText(error, "limit");
186
+ const next = contextText(error, "next_plan");
187
+ const reached = `The plan's document limit${limit ? ` (${limit})` : ""}${month ? ` for ${formatMonth(month)}` : ""} is reached`;
188
+ return next
189
+ ? `${reached}: an owner moves to the ${next} plan in the app, then ${retry}.`
190
+ : `${reached}, and no larger plan exists: contact Tracken.`;
191
+ }
192
+ case "PLAN_FEATURE_NOT_INCLUDED": {
193
+ const capability = contextText(error, "capability");
194
+ const required = contextText(error, "required_plan");
195
+ return `The organization's plan does not include ${capability ?? "this feature"}${required ? `; the ${required} plan does` : ""}. An owner changes the plan in the app.`;
196
+ }
197
+ case "SANDBOX_ACTION_BLOCKED":
198
+ return "A test copy of a company does not hand out e-MTA declaration files: take the file from the real company, or remove the copy mark in the app if this company is now the real one.";
199
+ case TRIAL_LIMIT_REACHED: {
200
+ const { used, resetsOn } = trialLimitFacts(error);
201
+ return resetsOn
202
+ ? `${used}; it resets on ${resetsOn}. Do not retry before then; an owner can choose a plan in the app.`
203
+ : `${used} until an owner chooses a plan in the app. Do not retry before then.`;
204
+ }
205
+ default:
206
+ return undefined;
207
+ }
208
+ }
209
+ /** The API's refusal of an operation it does not serve publicly (yet), or not to this kind of principal. */
210
+ export const OPERATION_NOT_PUBLIC = "OPERATION_NOT_PUBLIC";
211
+ /** The human rendering of any error, for stderr. */
212
+ export function renderError(error, context = {}) {
213
+ if (error instanceof TrackenApiError) {
214
+ const lines = [`Error ${error.status} ${error.code}: ${error.message}`];
215
+ if (error.code === OPERATION_NOT_PUBLIC) {
216
+ const where = context.environment ?? "this environment";
217
+ // The CLI only offers operations its document marks live, so the environment lags the document
218
+ // (prod behind main), or the operation is served to the web app but not to this kind of sign-in.
219
+ lines.push(` Not yet available in ${where}: the API document this CLI was built from lists it, but ${where} does not serve it (yet) to this kind of sign-in.`);
220
+ }
221
+ for (const detail of error.details) {
222
+ const where = detail.pointer ? `${detail.pointer}: ` : "";
223
+ const code = detail.code ? ` (${detail.code})` : "";
224
+ lines.push(` ${where}${detail.message ?? ""}${code}`.trimEnd());
225
+ }
226
+ const advice = subscriptionAdvice(error, context.retry);
227
+ if (advice)
228
+ lines.push(` ${advice}`);
229
+ else if (error.status === 403)
230
+ lines.push(...scopeAdvice(error, context));
231
+ if (error.status === 401) {
232
+ lines.push(` ${error.hint ?? (context.credentials === "machine" ? MACHINE_CREDENTIAL_REFUSED : `Sign in again with \`tracken login${envFlag(context.environment)}\`.`)}`);
233
+ }
234
+ if (error.existingId)
235
+ lines.push(` Existing record: ${error.existingId}`);
236
+ if (error.retryAfter !== undefined && error.status === 429)
237
+ lines.push(` Retry after ${error.retryAfter} s.`);
238
+ if (error.requestId)
239
+ lines.push(` Request id: ${error.requestId}`);
240
+ if (error.docUrl)
241
+ lines.push(` See ${error.docUrl}`);
242
+ return lines.join("\n");
243
+ }
244
+ if (error instanceof Error)
245
+ return `Error: ${error.message}`;
246
+ return `Error: ${String(error)}`;
247
+ }
248
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The reusable core: environments, sign-in and sessions, the API client, request building,
3
+ * pagination, jobs and output. The CLI's commands sit on top of it, and so will the local MCP server.
4
+ */
5
+ export * from "./auth/oauth.js";
6
+ export * from "./auth/scopes.js";
7
+ export * from "./auth/secret-store.js";
8
+ export * from "./auth/session.js";
9
+ export * from "./catalog.js";
10
+ export * from "./client.js";
11
+ export * from "./config.js";
12
+ export * from "./environments.js";
13
+ export * from "./errors.js";
14
+ export * from "./jobs.js";
15
+ export * from "./operations.js";
16
+ export * from "./output/format.js";
17
+ export * from "./output/render.js";
18
+ export * from "./pagination.js";
19
+ export * from "./request.js";
20
+ export * from "./version.js";
21
+ export { DOCUMENT, OPERATIONS, SCOPES } from "../generated/operations.js";
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The reusable core: environments, sign-in and sessions, the API client, request building,
3
+ * pagination, jobs and output. The CLI's commands sit on top of it, and so will the local MCP server.
4
+ */
5
+ export * from "./auth/oauth.js";
6
+ export * from "./auth/scopes.js";
7
+ export * from "./auth/secret-store.js";
8
+ export * from "./auth/session.js";
9
+ export * from "./catalog.js";
10
+ export * from "./client.js";
11
+ export * from "./config.js";
12
+ export * from "./environments.js";
13
+ export * from "./errors.js";
14
+ export * from "./jobs.js";
15
+ export * from "./operations.js";
16
+ export * from "./output/format.js";
17
+ export * from "./output/render.js";
18
+ export * from "./pagination.js";
19
+ export * from "./request.js";
20
+ export * from "./version.js";
21
+ export { DOCUMENT, OPERATIONS, SCOPES } from "../generated/operations.js";
22
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * `--wait`: the SDK polls the job an asynchronous operation started (`waitForJob`); the CLI only
3
+ * words the timeout as a command to run.
4
+ */
5
+ import { type WaitOptions as SdkWaitOptions } from "@tracken/sdk";
6
+ import type { ApiResponse, TrackenClient } from "./client.js";
7
+ import type { ApiRequest } from "./request.js";
8
+ export { pollPath } from "@tracken/sdk";
9
+ export interface WaitOptions extends SdkWaitOptions {
10
+ timeoutMs: number;
11
+ now(): number;
12
+ sleep(ms: number): Promise<void>;
13
+ }
14
+ /** Polls until the job is done; answers the final response, or throws `JobFailedError`. */
15
+ export declare function waitForJob(client: TrackenClient, accepted: ApiResponse, request: ApiRequest, options: WaitOptions): Promise<ApiResponse>;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * `--wait`: the SDK polls the job an asynchronous operation started (`waitForJob`); the CLI only
3
+ * words the timeout as a command to run.
4
+ */
5
+ import { TrackenJobTimeoutError, waitForJob as sdkWaitForJob } from "@tracken/sdk";
6
+ import { CliError } from "./errors.js";
7
+ export { pollPath } from "@tracken/sdk";
8
+ /** Polls until the job is done; answers the final response, or throws `JobFailedError`. */
9
+ export async function waitForJob(client, accepted, request, options) {
10
+ try {
11
+ return await sdkWaitForJob(client, accepted, request, options);
12
+ }
13
+ catch (error) {
14
+ if (!(error instanceof TrackenJobTimeoutError))
15
+ throw error;
16
+ throw new CliError(`Gave up waiting after ${Math.round(error.timeoutMs / 1000)} s; the job is still ${error.jobStatus ?? "pending"}. Poll it with \`tracken api GET ${error.path}\`.`);
17
+ }
18
+ }
19
+ //# sourceMappingURL=jobs.js.map
@@ -0,0 +1,108 @@
1
+ /**
2
+ * The shape of the command tree generated from the public API document (`src/generated/operations.ts`).
3
+ * One entry per v1 operation; the CLI derives its commands, flags and help from it, and the MCP server
4
+ * (a later lane) its tool list, so it carries everything either needs beyond the raw document.
5
+ */
6
+ export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
7
+ export type ScalarType = "string" | "integer" | "number" | "boolean";
8
+ /**
9
+ * Whether the API serves an operation: `live` operations are commands and MCP tools; `planned` ones
10
+ * are listed under "Coming" and refused locally; `later` ones (specified, built after v1) are left
11
+ * out of the generated tables altogether.
12
+ */
13
+ export type Availability = "live" | "planned" | "later";
14
+ /** How a value is shown in table output; decided by the schema, never guessed from the value. */
15
+ export type DisplayFormat = "decimal" | "date" | "date-time" | "integer" | "number";
16
+ /** Display formats of a record's properties; a nested map describes an object or an array of objects. */
17
+ export interface DisplayHints {
18
+ [property: string]: DisplayFormat | DisplayHints;
19
+ }
20
+ export interface ParamSpec {
21
+ /** The name on the wire (`updated_since`, `Idempotency-Key`). */
22
+ name: string;
23
+ /** The CLI flag without dashes (`updated-since`, `idempotency-key`). */
24
+ flag: string;
25
+ in: "path" | "query" | "header";
26
+ required: boolean;
27
+ type: ScalarType | "array";
28
+ /** For arrays: the item type. */
29
+ items?: ScalarType;
30
+ enum?: string[];
31
+ format?: string;
32
+ /** For arrays: repeat the parameter (`true`) or join the values with commas (`false`). */
33
+ explode?: boolean;
34
+ default?: string | number | boolean;
35
+ description: string;
36
+ }
37
+ export type FieldType = ScalarType | "object" | "array" | "file" | "any";
38
+ export interface FieldSpec {
39
+ name: string;
40
+ /** The CLI flag for body options and form fields (`on-conflict`); unused for `data` fields. */
41
+ flag: string;
42
+ type: FieldType;
43
+ nullable: boolean;
44
+ required: boolean;
45
+ format?: string;
46
+ enum?: string[];
47
+ description: string;
48
+ }
49
+ export interface BodySpec {
50
+ contentType: "application/json" | "multipart/form-data";
51
+ required: boolean;
52
+ /** JSON bodies: the fields of the `data` object (`--data`, `--set`). */
53
+ fields: FieldSpec[];
54
+ /** JSON bodies: operation options beside `data` (`on_conflict`, `effective_from`), as flags. */
55
+ options: FieldSpec[];
56
+ /** Multipart bodies: the form fields, as flags (`--file`, `--bank-account-id`). */
57
+ form: FieldSpec[];
58
+ }
59
+ export interface McpSpec {
60
+ name: string;
61
+ description: string;
62
+ annotations: Record<string, boolean>;
63
+ }
64
+ export interface OperationSpec {
65
+ operationId: string;
66
+ method: HttpMethod;
67
+ /** The path template relative to the API base (`/sales-invoices/{id}:issue`). */
68
+ path: string;
69
+ tag: string;
70
+ summary: string;
71
+ description: string;
72
+ /** The command: `tracken <resource> <verb> [positionals…]`. */
73
+ resource: string;
74
+ verb: string;
75
+ /** Path parameter names, in path order; given as positionals. */
76
+ positionals: string[];
77
+ params: ParamSpec[];
78
+ body?: BodySpec;
79
+ /** The oauth2 scopes the operation needs. */
80
+ scopes: string[];
81
+ /** Whether a person's token must name the organization (`X-Organization-ID`). */
82
+ organization: boolean;
83
+ /** A cursor-paginated list (`--all` follows `meta.pagination.next_cursor`). */
84
+ paginated: boolean;
85
+ /** Answers 202 with a job-like record (`--wait`). */
86
+ async: boolean;
87
+ /** Non-JSON content types a success may carry inline (`application/xml` for a VAT return's KMD file). */
88
+ binary: string[];
89
+ /** Answers a file instead of JSON when asked (`format=pdf`): inline (`binary`) or as a 303 to a pre-signed link. */
90
+ rendition: boolean;
91
+ display: DisplayHints;
92
+ /** Never `later`: those operations are not in the generated table. */
93
+ availability: Exclude<Availability, "later">;
94
+ mcp?: McpSpec;
95
+ }
96
+ export interface ScopeSpec {
97
+ name: string;
98
+ description: string;
99
+ }
100
+ export interface DocumentInfo {
101
+ title: string;
102
+ version: string;
103
+ sha256: string;
104
+ /** The accounting_software commit the document was synced from (`openapi/SOURCE.json`). */
105
+ commit: string;
106
+ /** The ref it was synced from (`origin/main`, a lane branch), when recorded. */
107
+ ref?: string;
108
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The shape of the command tree generated from the public API document (`src/generated/operations.ts`).
3
+ * One entry per v1 operation; the CLI derives its commands, flags and help from it, and the MCP server
4
+ * (a later lane) its tool list, so it carries everything either needs beyond the raw document.
5
+ */
6
+ export {};
7
+ //# sourceMappingURL=operations.js.map
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Estonian number and date formats, used in table output in every language (owner rule):
3
+ * `1 234,50`, `12.10.2026`, `24.10.2026 12:30`. Decimals keep the digits the API sent; nothing is
4
+ * rounded or passed through a float.
5
+ */
6
+ import type { DisplayFormat } from "../operations.js";
7
+ /** `"1234.50"` → `1 234,50`; a value that is not a decimal string comes back unchanged. */
8
+ export declare function formatDecimal(value: string): string;
9
+ /** `"2026-10-12"` → `12.10.2026`. */
10
+ export declare function formatDate(value: string): string;
11
+ /** An RFC 3339 instant in the given time zone (the machine's by default): `24.10.2026 12:30`. */
12
+ export declare function formatDateTime(value: string, timeZone?: string): string;
13
+ /** A JSON number: integers grouped (`12 345`), fractions with a decimal comma. */
14
+ export declare function formatNumber(value: number): string;
15
+ export interface CellOptions {
16
+ timeZone?: string | undefined;
17
+ }
18
+ /** One table cell: the schema's format decides how a value is shown, never the value's look. */
19
+ export declare function formatCell(value: unknown, format: DisplayFormat | undefined, options?: CellOptions): string;
@@ -0,0 +1,62 @@
1
+ const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?$/;
2
+ const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
3
+ const group = (digits) => digits.replace(/\B(?=(\d{3})+(?!\d))/g, " ");
4
+ /** `"1234.50"` → `1 234,50`; a value that is not a decimal string comes back unchanged. */
5
+ export function formatDecimal(value) {
6
+ const match = DECIMAL.exec(value);
7
+ if (!match)
8
+ return value;
9
+ const [, sign, whole, fraction] = match;
10
+ return `${sign}${group(whole)}${fraction !== undefined ? `,${fraction}` : ""}`;
11
+ }
12
+ /** `"2026-10-12"` → `12.10.2026`. */
13
+ export function formatDate(value) {
14
+ const match = DATE.exec(value);
15
+ return match ? `${match[3]}.${match[2]}.${match[1]}` : value;
16
+ }
17
+ /** An RFC 3339 instant in the given time zone (the machine's by default): `24.10.2026 12:30`. */
18
+ export function formatDateTime(value, timeZone) {
19
+ const date = new Date(value);
20
+ if (Number.isNaN(date.getTime()) || !/^\d{4}-\d{2}-\d{2}T/.test(value))
21
+ return value;
22
+ const parts = new Intl.DateTimeFormat("en-GB", {
23
+ timeZone,
24
+ year: "numeric",
25
+ month: "2-digit",
26
+ day: "2-digit",
27
+ hour: "2-digit",
28
+ minute: "2-digit",
29
+ hourCycle: "h23",
30
+ }).formatToParts(date);
31
+ const part = (type) => parts.find((entry) => entry.type === type)?.value ?? "";
32
+ return `${part("day")}.${part("month")}.${part("year")} ${part("hour")}:${part("minute")}`;
33
+ }
34
+ /** A JSON number: integers grouped (`12 345`), fractions with a decimal comma. */
35
+ export function formatNumber(value) {
36
+ if (!Number.isFinite(value))
37
+ return String(value);
38
+ const text = String(value);
39
+ return /e/i.test(text) ? text.replace(".", ",") : formatDecimal(text);
40
+ }
41
+ /** One table cell: the schema's format decides how a value is shown, never the value's look. */
42
+ export function formatCell(value, format, options = {}) {
43
+ if (value === null || value === undefined)
44
+ return "";
45
+ if (typeof value === "string") {
46
+ if (format === "decimal")
47
+ return formatDecimal(value);
48
+ if (format === "date")
49
+ return formatDate(value);
50
+ if (format === "date-time")
51
+ return formatDateTime(value, options.timeZone);
52
+ return value;
53
+ }
54
+ if (typeof value === "number")
55
+ return format === "integer" || format === "number" || format === "decimal" ? formatNumber(value) : String(value);
56
+ if (typeof value === "boolean")
57
+ return value ? "true" : "false";
58
+ if (Array.isArray(value))
59
+ return value.every((entry) => typeof entry !== "object" || entry === null) ? value.join(", ") : `[${value.length}]`;
60
+ return JSON.stringify(value);
61
+ }
62
+ //# sourceMappingURL=format.js.map
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Output modes. `json` is the API's answer as it came; `table` is for people (Estonian number and
3
+ * date formats, chosen by the schema); `csv` is for spreadsheets and scripts (raw values, one row
4
+ * per record); `ndjson` is one record per line, for agents and reads too large to hold.
5
+ */
6
+ import type { DisplayHints } from "../operations.js";
7
+ export declare const OUTPUT_MODES: readonly ["json", "table", "csv", "ndjson"];
8
+ export type OutputMode = (typeof OUTPUT_MODES)[number];
9
+ export interface RenderOptions {
10
+ hints?: DisplayHints | undefined;
11
+ /** `--columns`: the fields to show, in order. */
12
+ columns?: string[] | undefined;
13
+ timeZone?: string | undefined;
14
+ }
15
+ type Row = Record<string, unknown>;
16
+ /** A plain text table; numeric columns align right. */
17
+ export declare function renderTable(headers: string[], rows: string[][], rightAligned?: boolean[]): string;
18
+ export declare function chooseColumns(items: Row[], requested?: string[]): string[];
19
+ export declare function renderListTable(items: unknown[], options: RenderOptions): string;
20
+ interface ReportColumn {
21
+ key: string;
22
+ label: string;
23
+ type?: string;
24
+ }
25
+ /** A report's own columns and indented rows (`ReportResult`), in table form. */
26
+ export declare function renderReportTable(report: {
27
+ name?: unknown;
28
+ columns: ReportColumn[];
29
+ rows: Row[];
30
+ }): string;
31
+ export declare function csvLine(values: unknown[]): string;
32
+ /** CSV columns: every field of the records, nested ones as JSON, unless `--columns` names them. */
33
+ export declare function csvColumns(items: unknown[], requested?: string[]): string[];
34
+ export declare function renderCsv(items: unknown[], requested?: string[]): string;
35
+ /** Renders a whole JSON answer in the chosen mode. */
36
+ export declare function renderBody(body: unknown, mode: OutputMode, options?: RenderOptions): string;
37
+ /**
38
+ * Writes `--all` output a page at a time: JSON, NDJSON and CSV stream (one page in memory); a table
39
+ * needs every row for its column widths, so it collects them.
40
+ */
41
+ export declare class ListWriter {
42
+ private readonly mode;
43
+ private readonly write;
44
+ private readonly options;
45
+ private count;
46
+ private csvHeader;
47
+ private readonly collected;
48
+ constructor(mode: OutputMode, write: (text: string) => void, options?: RenderOptions);
49
+ add(items: unknown[]): void;
50
+ /** `meta` closes a JSON document beside `data` (the pass's `sync.next_since`); other modes ignore it. */
51
+ end(meta?: Record<string, unknown>): void;
52
+ }
53
+ export {};