tarcajs 0.0.0-stage → 0.1.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.
- package/LICENSE +21 -0
- package/README.en.md +66 -0
- package/README.md +1342 -2
- package/agents/README.md +39 -0
- package/agents/api.md +544 -0
- package/agents/pitfalls.md +80 -0
- package/agents/recipes.md +391 -0
- package/agents/skills/migrate-from-codingsans-billingo-client/SKILL.md +60 -0
- package/agents/skills/tarca/SKILL.md +35 -0
- package/dist/batch/index.cjs +537 -0
- package/dist/batch/index.d.cts +99 -0
- package/dist/batch/index.d.ts +100 -0
- package/dist/batch/index.js +529 -0
- package/dist/billingo-kYbrCOR2.d.cts +746 -0
- package/dist/billingo-kYbrCOR2.d.ts +746 -0
- package/dist/cli.cjs +608 -0
- package/dist/cli.d.cts +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +608 -0
- package/dist/client-B5sbMcaa.d.cts +115 -0
- package/dist/client-BPdbzvwm.js +1239 -0
- package/dist/client-BtTb3DIP.d.ts +133 -0
- package/dist/client-ChPDxCuZ.cjs +1274 -0
- package/dist/context-CepqOz1d.d.cts +129 -0
- package/dist/context-Cx225-4t.d.ts +129 -0
- package/dist/context-DvzE8iuQ.cjs +767 -0
- package/dist/context-q0b9qY-Q.js +690 -0
- package/dist/crypto-B0PAHKJB.cjs +64 -0
- package/dist/crypto-BqGn_oGu.js +35 -0
- package/dist/currencies-D_iPOU9V.d.ts +18 -0
- package/dist/currencies-DvuhRMEZ.d.cts +18 -0
- package/dist/dates-BuQuw-Hb.js +73 -0
- package/dist/dates-C3RiQone.cjs +108 -0
- package/dist/defaults-DdRto5Af.d.ts +13 -0
- package/dist/documents-DWLmA2UZ.d.ts +161 -0
- package/dist/documents-Kmaufm0I.d.cts +189 -0
- package/dist/enums-D-StgzDb.cjs +199 -0
- package/dist/enums-DaGcpiuS.js +158 -0
- package/dist/errors-B78UvT2v.js +197 -0
- package/dist/errors-DQToaasD.cjs +256 -0
- package/dist/index.cjs +23 -0
- package/dist/index.d.cts +10 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +6 -0
- package/dist/input-BHRlTNYs.js +286 -0
- package/dist/input-DWepz0Ys.cjs +339 -0
- package/dist/journal/index.cjs +484 -0
- package/dist/journal/index.d.cts +124 -0
- package/dist/journal/index.d.ts +124 -0
- package/dist/journal/index.js +473 -0
- package/dist/json-COC9rDwf.cjs +60 -0
- package/dist/json-D3Bx7NhF.d.ts +2 -0
- package/dist/json-as-6J7d-.js +31 -0
- package/dist/mcp/index.cjs +103 -0
- package/dist/mcp/index.d.cts +116 -0
- package/dist/mcp/index.d.ts +116 -0
- package/dist/mcp/index.js +91 -0
- package/dist/money-BqqwFRF7.cjs +112 -0
- package/dist/money-D8kMBSEg.js +89 -0
- package/dist/node/index.cjs +137 -0
- package/dist/node/index.d.cts +33 -0
- package/dist/node/index.d.ts +33 -0
- package/dist/node/index.js +133 -0
- package/dist/observe/index.cjs +361 -0
- package/dist/observe/index.d.cts +67 -0
- package/dist/observe/index.d.ts +67 -0
- package/dist/observe/index.js +352 -0
- package/dist/once-guard-BEvRKBKp.cjs +160 -0
- package/dist/once-guard-D3vZUwUH.js +137 -0
- package/dist/payments/barion.cjs +212 -0
- package/dist/payments/barion.d.cts +22 -0
- package/dist/payments/barion.d.ts +23 -0
- package/dist/payments/barion.js +206 -0
- package/dist/payments/index.cjs +1128 -0
- package/dist/payments/index.d.cts +215 -0
- package/dist/payments/index.d.ts +215 -0
- package/dist/payments/index.js +1100 -0
- package/dist/payments/paypal.cjs +362 -0
- package/dist/payments/paypal.d.cts +55 -0
- package/dist/payments/paypal.d.ts +56 -0
- package/dist/payments/paypal.js +349 -0
- package/dist/payments/revolut.cjs +264 -0
- package/dist/payments/revolut.d.cts +42 -0
- package/dist/payments/revolut.d.ts +43 -0
- package/dist/payments/revolut.js +255 -0
- package/dist/payments/simplepay.cjs +358 -0
- package/dist/payments/simplepay.d.cts +80 -0
- package/dist/payments/simplepay.d.ts +81 -0
- package/dist/payments/simplepay.js +346 -0
- package/dist/payments/stripe.cjs +392 -0
- package/dist/payments/stripe.d.cts +45 -0
- package/dist/payments/stripe.d.ts +46 -0
- package/dist/payments/stripe.js +381 -0
- package/dist/query-BK3Kr5hF.d.ts +48 -0
- package/dist/query-C8qI5cTz.d.cts +48 -0
- package/dist/receipts-CqvAFVwx.d.ts +42 -0
- package/dist/receipts-WI8ohoec.d.cts +43 -0
- package/dist/server-BXJAICMO.cjs +2731 -0
- package/dist/server-CWJpwRcy.js +2642 -0
- package/dist/shared-BC5gHprk.js +107 -0
- package/dist/shared-CAYGnPSu.cjs +226 -0
- package/dist/storage/fs.cjs +93 -0
- package/dist/storage/fs.d.cts +11 -0
- package/dist/storage/fs.d.ts +11 -0
- package/dist/storage/fs.js +92 -0
- package/dist/storage/index.cjs +647 -0
- package/dist/storage/index.d.cts +266 -0
- package/dist/storage/index.d.ts +266 -0
- package/dist/storage/index.js +622 -0
- package/dist/store-D9jI3jXM.d.cts +10 -0
- package/dist/store-D9jI3jXM.d.ts +10 -0
- package/dist/stores/index.cjs +523 -0
- package/dist/stores/index.d.cts +97 -0
- package/dist/stores/index.d.ts +97 -0
- package/dist/stores/index.js +509 -0
- package/dist/testing/index.cjs +3009 -0
- package/dist/testing/index.d.cts +131 -0
- package/dist/testing/index.d.ts +131 -0
- package/dist/testing/index.js +3006 -0
- package/dist/types-Bfs08Mrc.d.cts +24 -0
- package/dist/types-Bfs08Mrc.d.ts +24 -0
- package/dist/version-Nq_vcsXH.js +3 -0
- package/dist/version-tFDvo6Cc.cjs +8 -0
- package/dist/webhook-BgE5MkyK.js +289 -0
- package/dist/webhook-BpSTBUO2.d.cts +84 -0
- package/dist/webhook-DQsdIw_0.cjs +408 -0
- package/dist/webhook-b9h-_0E2.d.ts +83 -0
- package/llms.txt +18 -0
- package/package.json +256 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 futozs
|
|
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.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# tarca (English overview)
|
|
2
|
+
|
|
3
|
+
tarca is a zero-dependency TypeScript client for the [Billingo](https://www.billingo.hu) API v3, a Hungarian invoicing service. The main README is in Hungarian, because the domain (Hungarian VAT, NAV reporting, receipt rules) is Hungarian. This page is a short entry point for developers who do not read Hungarian.
|
|
4
|
+
|
|
5
|
+
tarca is an independent open-source project. It is not made by Billingo and is not affiliated with or endorsed by Billingo.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install tarcajs
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { createTarca } from 'tarcajs'
|
|
13
|
+
|
|
14
|
+
const tarca = createTarca() // reads BILLINGO_API_KEY
|
|
15
|
+
|
|
16
|
+
const invoice = await tarca.documents.create({
|
|
17
|
+
partner: {
|
|
18
|
+
name: 'Vevő Kft.',
|
|
19
|
+
address: { postCode: '1111', city: 'Budapest', address: 'Fő utca 1.' },
|
|
20
|
+
emails: ['vevo@ceg.hu'],
|
|
21
|
+
},
|
|
22
|
+
items: [{ name: 'Web development', quantity: 10, unit: 'óra', netUnitPrice: 15_000, vat: 27 }],
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
console.log(invoice.invoiceNumber, invoice.grossTotal)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
tarca finds the partner or creates it, and fills in the document block, the fulfillment date, the 8-day payment deadline and the VAT code. Invalid input is rejected before the request is sent.
|
|
29
|
+
|
|
30
|
+
For webshops and webhooks, use `createOnce()` with the order ID as `vendorId`. It looks the document up first, so running the same call twice (a webhook delivered twice, a retried job) never issues a second invoice.
|
|
31
|
+
|
|
32
|
+
## Status
|
|
33
|
+
|
|
34
|
+
tarca is 0.x. All 57 Billingo API v3 operations are implemented: the 54 documented in the 3.0.14 and 3.0.15 OpenAPI specs plus 3 undocumented document block routes that work in production. Every operation runs in a live end-to-end test against a Billingo developer test profile. The API may still change between 0.x releases; see the [changelog](CHANGELOG.md) (in Hungarian).
|
|
35
|
+
|
|
36
|
+
- Documents: invoices, proformas, advance and final invoices, drafts, copies, cancellations, modification documents, `createOnce` (exactly-once issuing through `vendorId`), PDF and POS PDF download, public URLs, sending by e-mail, reminders, NAV status, payments (`tarca.documents.*`)
|
|
37
|
+
- Receipts: `tarca.receipts.create()`, `createOnce()`, `finalizeDraft()`
|
|
38
|
+
- Partners (including `findOrCreate()`), products, inventory, document blocks, bank accounts, spendings, exports
|
|
39
|
+
- Organization data, tax number check, server time, legacy ID conversion, exchange rates
|
|
40
|
+
- `tarcajs/testing`: an in-memory fake Billingo (`createFakeBillingoFetch()`) and `createMockTarca()` for your own tests
|
|
41
|
+
- Full TypeScript types generated from the official OpenAPI spec, corrected where the live API differs: `import type { Billingo } from 'tarcajs'`
|
|
42
|
+
|
|
43
|
+
Add-ons, each a separate subpath that the root `tarcajs` entry never loads:
|
|
44
|
+
|
|
45
|
+
- `tarcajs/payments` (`/stripe`, `/simplepay`, `/barion`, `/revolut`, `/paypal`): verifies the provider's webhook without its SDK and issues a receipt or an invoice exactly once, with the payment id as `vendorId`. Refunds become a cancellation or, for a partial refund, a modification invoice.
|
|
46
|
+
- `tarcajs/storage` and `tarcajs/storage/fs` (Node): stores document PDFs in S3, Cloudflare R2, Vercel Blob, Supabase, UploadThing or on disk. S3 is signed with SigV4 over `fetch`, no AWS SDK.
|
|
47
|
+
- `tarcajs/stores`: Upstash, Redis, Durable Object and Cloudflare KV adapters for the cross-process `createOnce` lock, the journal, webhook dedupe and the refund ledger.
|
|
48
|
+
- `tarcajs/journal`: an append-only record of every issued, cancelled and modified document, reconciled against Billingo.
|
|
49
|
+
- `tarcajs/batch`: bulk and recurring invoicing, exactly once and paced under the rate limit, with a dry run.
|
|
50
|
+
- `tarcajs/observe`: redacted structured logs, OpenTelemetry-compatible spans and Prometheus metrics.
|
|
51
|
+
- `tarcajs/node`: mounts the web-standard handlers under Node `http`, Express, NestJS and Fastify with the raw body intact.
|
|
52
|
+
- `tarcajs/mcp` and the `tarcajs` command: `npx tarcajs doctor` checks the key, profile, NAV connection, subscription and document blocks read-only; `npx tarcajs mcp` is an MCP server for AI assistants that issues documents only with `--allow-write` and a confirmation code from a preview.
|
|
53
|
+
|
|
54
|
+
Planned: a documentation website.
|
|
55
|
+
|
|
56
|
+
## How it behaves
|
|
57
|
+
|
|
58
|
+
- Zero runtime dependencies, native `fetch`. ESM and CommonJS builds. CI runs the built package on Node.js 22+, Bun, Deno and Cloudflare workerd.
|
|
59
|
+
- Each `createTarca()` instance has its own API key and settings, so one process can serve several Billingo accounts.
|
|
60
|
+
- Field names are camelCase in TypeScript; tarca converts to and from Billingo's snake_case at the boundary.
|
|
61
|
+
- Reads (GET) are retried after 429, 5xx, network errors and timeouts, honouring `Retry-After`, 3 attempts by default. Writes (POST, PUT, DELETE) are never retried automatically.
|
|
62
|
+
- Errors are `BillingoError` with a `category` (`auth`, `nav_unavailable`, `subscription`, `forbidden`, `not_found`, `validation`, `rate_limit`, `server`, `not_ready`, `network`, `timeout`, `configuration`, `unexpected_response`, `in_progress`, `store_unavailable`), plus `fieldErrors`, `traceId` and a `hint`. Messages are in Hungarian.
|
|
63
|
+
- Hooks (`onRequest`, `onResponse`, `onError`, `onComplete`, `onWarning`, and `onDocument` for every new document) never receive the API key.
|
|
64
|
+
- Sends no telemetry.
|
|
65
|
+
|
|
66
|
+
License: MIT.
|