bitsnap 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,110 @@
+# bitsnap CLI for agents
+
+`bitsnap` is a CLI for the Bitsnap public API (`/api/v1`). Run it with
+`npx bitsnap …` or install it. Always pass `--json`.
+
+## Rules
+
+- Authenticate with `BITSNAP_API_KEY` (preferred in agent sandboxes) or
+  `bitsnap login --key <key>`. Use a **test key** (`bs_test_…`) unless the user asked
+  for live. Never print, log or commit a key; the CLI masks keys as
+  `bs_test_…ab12`, keep it that way. Do not put the key in the project's client code.
+- Check first: `bitsnap whoami --json` shows project, `environment`
+  (`ENVIRONMENT_TEST` / `ENVIRONMENT_LIVE`), `scopes` and `canWrite`.
+- `--json`: result on stdout, errors on stderr as one line
+  `{"error":{"kind":"usage|api|auth|network|timeout","message","detail?","hint?","reason?","code?","status?","requestId?"}}`.
+  Branch on `reason` (stable), not on `message`.
+- Exit codes: `0` ok · `1` API or usage error · `2` auth error (no/bad key) · `3` network error.
+- No command prompts. Missing input is a usage error (exit 1).
+- Money is an integer in minor units: `--price 4900` = 49.00 PLN.
+- Writes send an `Idempotency-Key` (random UUID). To make a retry safe, pass the
+  same `--idempotency-key <key>` with the same arguments; the API returns the first
+  result instead of creating a second product or order. The same key with
+  different arguments fails with `idempotency_key_reused`.
+- `--json` prints the API's response body verbatim (Connect JSON: lowerCamelCase,
+  enums by name such as `ORDER_STATUS_PAID`, timestamps RFC 3339). Fields may be added.
+- Global options: `--json`, `--host <url>`, `--idempotency-key <key>`, `-h/--help`.
+
+## Commands and `--json` output
+
+| Command | stdout with `--json` |
+| --- | --- |
+| `login --key K` | `GetAccount` fields + `key` (masked), `host`, `configPath` |
+| `logout` | `{ok, removed, configPath}` |
+| `whoami` | `{projectId, projectName, environment, credentialType, scopes[], canWrite, key (masked), keySource: "env"\|"config", host}` |
+| `products list [--search t] [--limit 1-100] [--drafts] [--cursor c]` | `{products: Product[], nextCursor}` (`nextCursor` `""` = last page) |
+| `products get ID` | `{product}` |
+| `products create --name N --price MINOR [--currency PLN] [--status draft\|published\|unpublished] [--stock n] [--image URL]…` | `{product}` (draft unless `--status`) |
+| `orders list [--status paid]… [--limit n] [--cursor c]` | `{orders: Order[], nextCursor, totalCount}` |
+| `orders get ID` | `{order}` |
+| `coupons list` | `{coupons: Coupon[]}` |
+| `checkout create --product ID [--variant ID] [--quantity n] [--success-url U] [--cancel-url U] [--email E] [--reference R]` | `{url, orderId, environment}` (without `--json` only the URL is printed) |
+| `payments settle ORDER_ID [--fail]` | `{orderId, outcome: "TEST_PAYMENT_OUTCOME_PAID"\|"TEST_PAYMENT_OUTCOME_FAILED"}`; exit 1 locally for live keys |
+| `webhooks list` | `{webhooks: Webhook[]}` |
+| `webhooks create --url HTTPS_URL [--name N] [--event E]…` | `{webhook, signingSecret}` (secret shown once; omit `--event` for all) |
+| `webhooks delete ID` | `{}` |
+| `webhooks listen [--forward URL] [--poll] [--max-events n] [--timeout s]` | NDJSON, see below |
+| `webhooks trigger [EVENT]` | `{eventId, event, deliveredTo}` (default `TRANSACTION_SUCCESS`) |
+| `openapi [--format yaml\|json] [--out F]` | the document on stdout (json with `--json`); with `--out`: `{ok, path, format, bytes}` |
+| `stats [--from D] [--to D]` | `{from, to, orders, unitsSold, revenue: Money[], daily: [{date, units, revenue}]}`; `D` is `YYYY-MM-DD` or RFC 3339, a plain `--to` date covers that whole day |
+
+`Product`: `{id, name, status: PRODUCT_STATUS_DRAFT|UNPUBLISHED|PUBLISHED, price?: {amount, currency}, availableQuantity?, images[], variants[{id, name, price?, availableQuantity?}], revision, createdAt, updatedAt}`.
+`Order`: `{id, status: ORDER_STATUS_*, environment, createdAt, customer{email,name,phone}, items[{productId,name,quantity,unitPrice}], total, paymentGateway, couponCode, deliveryPrice?}`.
+Order statuses for `--status`: `created paid unpaid canceled sent completed issue returned in_progress`.
+
+### `webhooks listen`
+
+Test keys only. One JSON object per line:
+
+```json
+{"type":"ready","secret":"whsec_…","projectId":"…","host":"https://bitsnap.pl","mode":"sse"}
+{"type":"event","id":"evt_1","event":"TRANSACTION_SUCCESS","signature":"<hex hmac-sha512>","payload":"<exact JSON body string>","forward":{"url":"http://localhost:3000/api/webhooks","status":200,"ok":true,"durationMs":12}}
+{"type":"status","state":"reconnecting"}
+```
+
+`forward` is present with `--forward`; on a connection failure it is
+`{"url","error","durationMs"}`; a non-2xx answer adds `body`. `payload` is the exact
+string that was signed; `JSON.parse` it, never re-serialize it before verifying.
+The signature is HMAC-SHA512 (hex) of `payload` with the signing secret, sent as
+`X-Content-Signature` and `?sig=`. The command runs until Ctrl+C; use
+`--max-events 1 --timeout 120` to wait for a single event (exit 0 when received,
+exit 1 `kind: "timeout"` when not). Tip: run it in the background, trigger the
+event (`bitsnap webhooks trigger` or `bitsnap payments settle`), then read the output.
+
+## Error reasons and what to do
+
+| `reason` | Meaning | Do |
+| --- | --- | --- |
+| `missing_credentials`, `invalid_credentials` (exit 2) | No/bad key | Ask the user for a key from Settings → Developer |
+| `writes_disabled` | Key has writes off | Ask the user to turn on writes for the key in Settings → Developer |
+| `missing_scope` (`metadata.scope`) | Key lacks the scope | Ask the user to add the scope |
+| `test_mode_only` | Command needs a test key | Use a `bs_test_…` key |
+| `invalid_request` (`metadata.field`) | Bad argument | Fix the field named in `detail` |
+| `*_not_found` | Wrong id or environment | List first (`products list`, `orders list`) |
+| `product_not_purchasable`, `checkout_unavailable` | Product is a draft / no stock / shop has no gateway | Publish the product; set up the test gateway in the dashboard |
+| `order_not_settleable` | Not an open test order of the Bitsnap test gateway (cancelled, expired, live, or another gateway). Settling twice is not an error: it returns the first outcome | Create a new checkout with a test key |
+| `idempotency_key_in_progress` | Same key still running | Retry in seconds with the same key |
+| `rate_limited`, `daily_write_limit`, `service_unavailable`, `internal` | Server side limits | Wait and retry (`daily_write_limit` resets 00:00 UTC) |
+
+## Recipes
+
+```sh
+# 1. Is the key right?
+bitsnap whoami --json
+
+# 2. A product to sell (published so it can be bought)
+bitsnap products create --name "Ebook" --price 4900 --status published --json
+
+# 3. Buy it in test mode without a card
+URL_JSON=$(bitsnap checkout create --product "$PRODUCT_ID" --success-url http://localhost:3000/thanks --json)
+bitsnap payments settle "$ORDER_ID" --json
+
+# 4. See the webhook arrive in the user's dev server
+bitsnap webhooks listen --forward http://localhost:3000/api/webhooks --json --max-events 1 --timeout 120 &
+bitsnap payments settle "$ORDER_ID" --json
+wait
+```
+
+Set `BITSNAP_WEBHOOK_SECRET` in the app's local env to the `secret` of the `ready`
+record. The `bitsnap-js` package verifies the forwarded request unchanged
+(`handleWebhook(rawBody, request.url, headers, secret)`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piotr Michalik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# bitsnap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line tool for the [Bitsnap](https://bitsnap.pl) public API. Create
+products, make test checkout links, settle test payments and forward test
+webhooks to your local dev server, from a terminal or from an AI coding agent.
+
+```sh
+npx bitsnap --help
+npm install -g bitsnap     # or: bun add -g bitsnap
+```
+
+Needs Node.js 20 or newer. No runtime dependencies.
+
+## Log in
+
+Create an API key in **Settings → Developer** of your Bitsnap dashboard. Use a
+**test key** (`bs_test_…`) while you build: test orders move no money.
+
+```sh
+bitsnap login --key bs_test_…
+bitsnap whoami
+```
+
+`login` checks the key with the API and stores it in
+`~/.config/bitsnap/config.json` (or `$XDG_CONFIG_HOME/bitsnap/config.json`) with
+mode `0600`. `BITSNAP_API_KEY` always wins over the stored key, which is the
+better choice in CI and for agents. `--host` / `BITSNAP_HOST` change the API
+host (default `https://bitsnap.pl`). A key is never printed in full
+(`bs_test_…ab12`). `bitsnap logout` deletes the stored key.
+
+Writes (create product, checkout links, webhooks) need the key's write switch
+and the matching scope; if they are off the CLI says so and where to turn them
+on.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `login --key <key>` / `logout` / `whoami` | Store, remove or inspect the credentials. |
+| `products list [--search] [--limit] [--drafts] [--cursor]` | List products. |
+| `products get <id>` | One product with its variants. |
+| `products create --name --price <minor units> [--currency PLN] [--status draft\|published\|unpublished] [--stock n] [--image url]…` | Create a product. `--price 4900` is 49.00 PLN. |
+| `orders list [--status paid]… [--limit] [--cursor]` / `orders get <id>` | Orders of the key's environment. |
+| `coupons list` | Coupons and their codes. |
+| `checkout create --product <id> [--variant] [--quantity] [--success-url] [--cancel-url] [--email]` | Prints the checkout URL. |
+| `payments settle <orderId> [--fail]` | Settle a **test** order as paid (or failed). Refused locally for live keys. |
+| `webhooks list` / `create --url <https>` / `delete <id>` | Manage webhook endpoints. |
+| `webhooks listen [--forward <url>]` | Stream test webhook events; forward them to your local server. |
+| `webhooks trigger [event]` | Send a sample event (default `TRANSACTION_SUCCESS`). |
+| `openapi [--format yaml\|json] [--out file]` | Download the OpenAPI document (no key needed). |
+| `stats [--from] [--to]` | Sales summary. |
+
+`bitsnap <command> --help` shows every option.
+
+## Test a purchase end to end
+
+```sh
+bitsnap products create --name "Ebook" --price 4900 --status published
+bitsnap checkout create --product prodv2_… --success-url http://localhost:3000/thanks
+# open the URL, or skip paying and settle the test order:
+bitsnap payments settle <orderId>
+```
+
+## Receive webhooks on localhost
+
+```sh
+bitsnap webhooks listen --forward http://localhost:3000/api/webhooks
+```
+
+It prints the signing secret; set it as `BITSNAP_WEBHOOK_SECRET` in your app. Each
+event is `POST`ed to your URL with the exact payload as body, the HMAC-SHA512
+signature in `X-Content-Signature` and also as `?sig=`, so your normal webhook
+verification (for example `handleWebhook` from `bitsnap-js`) works unchanged. The
+stream reconnects by itself (with `Last-Event-ID`) and falls back to long
+polling if the event stream is blocked. `bitsnap webhooks trigger` sends a
+sample event so you can see it arrive.
+
+## For scripts and agents
+
+- `--json` on any command: result as JSON on stdout. Errors go to stderr as
+  `{"error":{"kind","message","hint","reason",…}}`.
+- Exit codes: `0` ok, `1` API or usage error, `2` auth error, `3` network error.
+- The CLI never asks questions.
+- Writes send an `Idempotency-Key` (random UUID; set it with `--idempotency-key`),
+  so a retry cannot create a second product or order.
+- `bitsnap --help --json` lists every command and option.
+
+See [AGENTS.md](./AGENTS.md) for the JSON shapes and recipes.
+
+## Develop
+
+This package lives in the Bitsnap monorepo as `packages/cli` (workspace name
+`@bitsnap/cli`; the published name is `bitsnap`).
+
+```sh
+bun run typecheck && bun test && bun run build
+node dist/cli.js --help
+bun run release:prepare      # assembles release/ with the public `bitsnap` manifest
+```
+
+Releases go out through the `Publish CLI` workflow
+(`.github/workflows/publish.yml`): bump the version in `package.json`, commit,
+then tag and push `cli-vX.Y.Z`. The workflow authenticates with npm trusted
+publishing, so no token is involved.
+
+MIT licensed.