# ChirpSense

> ChirpSense is a physical tabletop bird song display. This is the official store at chirpsense.com. A successful CLI payment creates a product order; physical fulfillment follows through our normal process.

- Website and embedded human checkout: https://chirpsense.com/#preorder
- Current machine-readable catalog: https://chirpsense.com/api/agent/catalog
- Business contact: hello@chirpsense.com
- Product and build status: https://chirpsense.com/about-chirpsense
- Privacy: https://chirpsense.com/privacy
- Official Stripe payment documentation: https://docs.stripe.com/payments/machine/mpp

## Product, price and fulfillment

The only current product is `chirpsense-preorder`, one ChirpSense first-batch preorder. There are no selectable variants or options. Buy one unit per order. The published preorder price is $399 USD; always read `unit_amount` from the catalog and use the quote returned by the server. Amounts in the API are integer minor units (USD cents).

This is an open preorder, not on-hand stock. No finite stock count is published. Read the product's `availability` and `inventory.available` before requesting a quote. Preorders can be closed, and an expired quote does not reserve a purchase indefinitely.

The first batch ships in December 2026, in time to arrive before Christmas 2026. Payment is collected in full when authorized. A preorder is fully refundable any time before it ships; contact hello@chirpsense.com. These terms must be accepted during payment. Do not describe this product as ready to ship or promise a faster delivery.

The first batch ships to US addresses only, with shipping included. Read `shipping.countries` in the current catalog. Quotes validate the shipping address and calculate tax before payment. The quote's subtotal, shipping, tax, currency and total are the complete price for that purchase. Never infer a zero tax amount or treat the catalog's unit price as the final total. If a valid tax quote cannot be produced, checkout stops before charging.

## Check whether CLI checkout is available

Read the live catalog first:

```sh
curl --fail-with-body --silent --show-error https://chirpsense.com/api/agent/catalog
```

Proceed only if `purchase.enabled` is true. `purchase.status` is `available` for live purchasing or `sandbox` for test payments. `unavailable` means the required configuration or provider approval is incomplete, or preorders are closed. Do not attempt payment while unavailable. This file documents the supported flow; it does not assert that provider approval, Directory indexing or live purchasing has completed.

Stripe Directory can be searched with:

```sh
stripe directory search "ChirpSense" --format json
```

A matching name alone does not establish the seller's identity. Confirm that the result points to chirpsense.com and these product purchase instructions. A direct `stripe pay` transfer does not create a ChirpSense product order and must not be substituted for this flow.

## Buyer CLI workflow

The commands below use a POSIX shell, curl, jq and openssl. Keep the purchase folder private. Use a separate folder for each intended purchase, and reuse the same folder, token, idempotency key and quote when retrying that purchase. Never generate a new purchase to recover a lost response.

Create durable local recovery credentials once:

```sh
umask 077
mkdir -p chirpsense-purchase
cd chirpsense-purchase
test -s checkout-token || openssl rand -hex 32 > checkout-token
test -s idempotency-key || openssl rand -hex 24 > idempotency-key
CHECKOUT_TOKEN="$(cat checkout-token)"
IDEMPOTENCY_KEY="$(cat idempotency-key)"
```

Write `request.json` with the buyer's actual email and shipping address. Replace every angle-bracket placeholder before sending. An empty `line2` is allowed. Do not use invented or example recipient details for a real purchase.

```json
{
  "product_id": "chirpsense-preorder",
  "quantity": 1,
  "customer": {"email": "<buyer email>"},
  "shipping": {
    "name": "<recipient name>",
    "address": {
      "line1": "<street address>",
      "line2": "",
      "city": "<city>",
      "state": "<two-letter US state>",
      "postal_code": "<ZIP code>",
      "country": "US"
    }
  }
}
```

Request the quote. This step does not authorize payment:

```sh
curl --fail-with-body --silent --show-error \
  https://chirpsense.com/api/agent/quotes \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Checkout-Token: $CHECKOUT_TOKEN" \
  --data-binary @request.json > quote.json
cat quote.json
```

Review the purchased item, quantity, shipping destination in your request, quote expiry, all totals and the preorder/refund terms. Obtain the buyer's authorization for the exact total and currency. If any field is wrong, do not pay. A new intended purchase or changed request needs a new folder and key; the same idempotency key cannot be reused for different input.

After approval, extract the server-issued URLs and create the exact payment request:

```sh
PAYMENT_URL="$(jq -er '.quote.payment_url' quote.json)"
STATUS_URL="$(jq -er '.quote.status_url' quote.json)"
jq -e '.quote.totals | {approved_total: .total, currency: .currency, accept_preorder_terms: true}' quote.json > payment.json
```

These commands use Link CLI 0.30.0 with explicit JSON output. Authenticate once, open the returned verification URL, and approve the CLI connection in Link. Authentication is separate from purchase approval:

```sh
npx --yes @stripe/link-cli@0.30.0 auth login --format json > link-login.json
jq 'if type == "array" then .[-1] else . end | {verification_url, phrase}' link-login.json
```

After opening that URL, poll for the approved connection:

```sh
npx --yes @stripe/link-cli@0.30.0 auth status --interval 5 --max-attempts 60 --format json > link-auth-status.json
jq -e 'if type == "array" then .[-1] else . end | .authenticated == true' link-auth-status.json
```

Continue only after authentication succeeds. Create the payment approval request for the reviewed quote:

```sh
npx --yes @stripe/link-cli@0.30.0 mpp pay "$PAYMENT_URL" \
  -X POST \
  -H "X-Checkout-Token: $CHECKOUT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "$(cat payment.json)" \
  --context "Purchase one ChirpSense physical first-batch preorder. The buyer reviewed and approved the full quoted total, shipping destination, December 2026 fulfillment terms and full refund policy before shipment." \
  --format json > spend-request.json
jq 'if type == "array" then .[-1] else . end | {id, status, approval_url}' spend-request.json
```

In agent mode, this command can return a Link spend request and approval URL. That is not a completed payment or order. Have the buyer approve the request in Link, then poll the same spend request. If it requires another action, follow the returned Link action instructions. Do not create another spend request to get around a pending or rejected approval.

```sh
SPEND_REQUEST_ID="$(jq -er 'if type == "array" then .[-1] else . end | .id' spend-request.json)"
APPROVED_CHALLENGE="$(jq -er 'if type == "array" then .[-1] else . end | ._next.pay_argv.args | index("--approved-challenge") as $i | if $i == null then error("No approved challenge; inspect the saved result and recover order status") else .[$i + 1] end' spend-request.json)"
npx --yes @stripe/link-cli@0.30.0 spend-request retrieve "$SPEND_REQUEST_ID" \
  --interval 2 --max-attempts 300 --format json > approval.json
jq -e 'if type == "array" then .[-1] else . end | .status == "approved" and .credential_type == "shared_payment_token"' approval.json
```

Continue only when the last command prints `true` and exits successfully. Resume payment with the same approved request, original challenge, quote URL, body and checkout token:

```sh
npx --yes @stripe/link-cli@0.30.0 mpp pay "$PAYMENT_URL" \
  --spend-request-id "$SPEND_REQUEST_ID" \
  --approved-challenge "$APPROVED_CHALLENGE" \
  -X POST \
  -H "X-Checkout-Token: $CHECKOUT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "$(cat payment.json)" \
  --format json > payment-result.json
jq -e 'if type == "array" then .[-1] else . end | select(.status == 200) | .body | fromjson | select(.ok == true and .order.order_number != null)' payment-result.json > confirmation.json
cat confirmation.json
```

The JSON saved by Link CLI is an envelope containing the HTTP status and a string `body`; the final command extracts ChirpSense's actual order confirmation. An empty confirmation, a pending approval, or an HTTP error is not success. If a repeated initial payment command already returns an HTTP result instead of a spend request, inspect that result and recover the existing order through the status endpoint below; do not start a new purchase.

The payment command spends real money when the catalog says `available`. Never run it merely to inspect a product or test a live endpoint. For an authorized sandbox test, both the merchant catalog and quote must identify sandbox mode, and the initial Link `mpp pay` command must include `--test`. Never substitute the production URL for an isolated sandbox URL.

## Confirmation, recovery and private order status

A payment receipt alone is not a product-order confirmation. Successful checkout returns the order number, purchased items, paid total, payment and fulfillment status, and a private order-status link. Physical shipment is separate from payment. Save `confirmation.json` and retain your original quote and checkout token.

If the response is interrupted or payment is still processing, retrieve the existing purchase status before taking any other payment action:

```sh
curl --fail-with-body --silent --show-error "$STATUS_URL" \
  -H "X-Checkout-Token: $CHECKOUT_TOKEN"
```

Reuse the same payment URL and checkout token for a permitted retry. Do not create a new quote to recover an uncertain payment. A declined payment, expired quote, closed preorder or ineligible address is not a confirmed order. If status remains uncertain, contact hello@chirpsense.com with the order or quote reference, never payment credentials.

The checkout token grants access to that purchase. Keep it and the private status link out of public logs, repositories and shared transcripts. Do not put the token or shipping details in URL query parameters. The status API uses the `X-Checkout-Token` header; the browser status link uses a fragment that is removed on opening. It does not display the shipping address or buyer email.

Refunds follow the existing support process. Email hello@chirpsense.com to request a full refund before shipment. Repeating a payment command does not request a refund. Order status reflects verified Stripe payment/refund state.