cx-keepa 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComChatX
+
+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/package.json

@@ -1,6 +1,21 @@
 {
   "name": "cx-keepa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HS-Jack-YZY/ComChatX.git",
+    "directory": "src/source-packages/cx-keepa"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "comchatx": {
+    "mcp": "keepa"
+  }
+}

package/skills/keepa/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: keepa
+description: Amazon product facts from Keepa — current price and price history, coupons, sales rank, monthly sales, offers and Buy Box, listing and release dates — by ASIN or by product name, and a seller's profile by seller id, on Amazon US, UK, DE, FR, JP, CA, IT, ES, IN, MX or BR. Use for any question about a product or a seller on Amazon, including whether a product can be fetched or looked up, before the first data call. Needs cx-sources; if no cx-sources skill is listed, it is not installed, and the seller installs it in Plugins.
+---
+
+Keepa supplies Amazon product facts through `cx`; read cx-sources first. Keepa's own MCP tools are a second way: read [references/mcp.md](references/mcp.md) before calling one. An installed skill is not an enabled source: if Keepa is off, the seller turns its plugin on in Plugins.
+
+## Find and fetch
+
+Use the marketplace the seller named; if none was named, ask. Buy only an ASIN the seller gave or a search or fetched file shows, competitors and similar products too; search or ask about a recalled one. A product name is a search term: search it, verify the returned product's title and model, and let the seller choose between ambiguous matches.
+
+```sh
+cx raw keepa --method GET --path /search --query domain=1 --query type=product --query 'term=PRODUCT NAME' --query asins-only=1
+cx get amazon/us/ASIN/product --source keepa
+```
+
+`domain` and the market segment follow the seller's marketplace: `1` us, `2` uk, `3` de, `4` fr, `5` jp, `6` ca, `8` it, `9` es, `10` in, `11` mx, `12` br. Typed paths exist for `amazon/us/<asin>/product` and `amazon/jp/<asin>/product`; other markets use raw `GET /product` with `domain` and one ASIN. Search returns ASINs only and is a separate paid call. A seller is looked up by its id on raw `GET /seller`.
+
+Typed requests include history, `stats=90`, `offers=20`, `buybox=1`, `rating=1`; each product path reserves 14 tokens, settling at stated consumption. `latest` accepts a copy up to 1h old. Every raw call reserves 50 tokens, settling likewise; reservations are not charges; tokens are Keepa's meter, not a price. Read the landed file rather than repeating a successful call. `cx raw keepa --record <id> [--part <n>]` reads a kept reply without another purchase. Never name `key`; the gate attaches the credential.
+
+## Read the file
+
+A product file is one product object from Keepa's `products` array, unchanged; a raw reply carries the whole array under `products`. A fetched product is answered with its facts: current price and coupon, rank in its named category, monthly sales, and listing and release timing. Each is computed by the conversions in [references/product-file.md](references/product-file.md), read before the first fact is stated — never `cat` the file whole; `listedSince` is the earliest listing, not a release date. Before a raw request other than the search above, read [references/raw-routes.md](references/raw-routes.md).

package/skills/keepa/references/mcp.md

@@ -0,0 +1,29 @@
+# Keepa's own MCP tools
+
+Keepa runs an MCP server, and it is carried here whole: the tools, their descriptions and the token price each description states are Keepa's words. Its tools are named `mcp__keepa__<name>`.
+
+## Calling a tool
+
+Call a tool from a codemode script, as `await tools.mcp__keepa__<name>({ ... })`; the result arrives whole there. Called directly, outside a script, a tool answers `Tool mcp__keepa__<name> not found`. A script told `tools.mcp__keepa__<name> does not exist` means Keepa's server did not connect when the session started.
+
+## Money
+
+A call reserves the most its arguments can cost and settles at what the reply states in `apiTokens.consumedByThisCall`. `product_finder_fields` and `get_price_graph` reply without that figure and settle 0 and 1 tokens. A reservation is not a charge.
+
+A refusal starting `MCP HTTP request failed with status 402` is the wallet's floor, not Keepa's: the balance is under the call's reservation.
+
+Closed on the platform's key, and refused before any spend: `tracking_add`, `tracking_remove`, `tracking_list`, `tracking_get_notifications`, `tracking_set_webhook`. `get_products` by `codes` is refused the same way; look a product up by ASIN.
+
+## The two ways to a product
+
+| | `cx get amazon/<market>/<asin>/product` | `get_products` |
+|---|---|---|
+| Buys | history, statistics, offers, Buy Box and rating, always | the product; Buy Box and offers only when the arguments ask |
+| Settled in the trial | 6 tokens | 1 token |
+| Lands | an observation, cited by its path and reused while fresh | nothing; the reply is the script's result |
+
+In the trial the MCP way was faster and cheaper per read, and most of its prompt went to finding the tools.
+
+## What the compact reply leaves out
+
+`get_products` replies in a compact form that carries `listedSince` and no release date. A release date comes only from `get_products` with `raw: true`, which returns Keepa's product object; read it by the conversions in [product-file.md](product-file.md). A seller is looked up by `get_seller` with its seller id.

package/skills/keepa/references/product-file.md

@@ -0,0 +1,91 @@
+# Reading a Keepa product file
+
+Run these JavaScript conversions on the file's values. UTC is the time basis. `null`, `0` and `-1` are absent field dates, not dates to display; other negative Keepa minutes predate 2011.
+
+## Clocks and units
+
+Keepa minutes (`listedSince`, `trackingSince`, `lastUpdate`, field-update stamps and history entry times):
+```js
+const keepaDate = n => n == null || n === 0 || n === -1 ? null : new Date((n + 21564000) * 60000).toISOString();
+```
+Packed dates (`releaseDate`, `publicationDate`) keep their stated precision: YYYY, YYYYMM or YYYYMMDD:
+```js
+const calendarDate = n => n == null || n <= 0 ? null : String(n).match(/^\d{4}|\d{2}/g).join('-').replace(/-00.*$/, '');
+```
+The reply's `timestamp` is Unix milliseconds:
+```js
+const replyDate = n => n == null || n <= 0 ? null : new Date(n).toISOString();
+```
+`refillIn` is milliseconds until refill, not days; `refillRate` is tokens per minute:
+```js
+const refillSeconds = n => n == null || n < 0 ? null : n / 1000;
+```
+Prices are minor units, except Japan's whole yen; `0` is a real price/count, `-1` absent, `-2` undetermined:
+```js
+const price = (n, domainId) => n == null || n < 0 ? null : n / (domainId === 5 ? 1 : 100);
+```
+`coupon` is a pair, one-time then subscribe-and-save, with its own sign convention; never pass it to `price` directly:
+```js
+const couponPart = (n, domainId) => n == null || n === 0 ? null : n < 0 ? { percent: -n } : { amount: price(n, domainId) };
+const coupon = (pair, domainId) => pair == null ? null : { oneTime: couponPart(pair[0], domainId), subscribeAndSave: couponPart(pair[1], domainId) };
+```
+
+`listedSince` is earliest listing, not release. Include listing and release timing in a product summary, stating absent dates plainly. For `releaseDate` `0` or `-1`, say “Keepa has no release date”. `lastUpdate: -1` is read here as no product data — the platform's reading, in no reply kept so far; the sidecar's arithmetic `as_of` is then not a valid observation time. `lastUpdate` records a check, `lastPriceChange` a change; an unchanged price is not stale just because its event is old. The sidecar's `as_of` is Keepa's `lastUpdate`, when Keepa last checked the product; tolerance is measured against `observed_at`, when the platform bought the observation. A newly bought observation need not contain newly checked product data.
+
+## History and present state
+
+`csv[i]` and `salesRanks[category]` are flat time/value pairs; delivered-price slots and `offerCSV` are time/price/shipping triples. Statistics use the same slot indices; `stats.min[i]` is `null` or time/value. Use Keepa's own statistics (`stats.min`, `stats.max`, `stats.isLowest`, `stats.outOfStockPercentage90`, `stats.salesRankDrops30`, `stats.totalOfferCount`), not recomputed extrema from change-only history. `stats.salesRankDrops30` is `-1` with no rank data; `0` is a real count. `stats.outOfStockPercentage90[i]` is `-1` with too little data or a non-price slot; `0` is never out of stock. Code converts the supplied values and dates; it does not reconstruct a 90-day low. A file without `stats` states the changes it holds, not a computed low. Unknown shipping stays unknown.
+
+| Slots | Meaning |
+|---|---|
+| 0, 1, 2, 4, 5, 6, 8, 9, 10, 30, 33 | Amazon, new, used, list, collectible, refurbished, lightning, warehouse, FBA, trade-in, Prime prices |
+| 7, 18, 19–22, 23–26, 27, 28, 29, 32 | FBM, Buy Box, used conditions, collectible conditions, refurbished, eBay new/used, used Buy Box; delivered prices |
+| 3 | reference sales rank; `-1` is no rank at that time, as in `salesRanks[category]` |
+| 11–14, 34, 35 | new/used/refurbished/collectible, FBA/FBM offer counts |
+| 15 | offers fetched; negative means more existed, not absence |
+| 16, 17 | rating in tenths (divide by 10 in code), rating count, not written reviews; `-1` in either is no data at that time, not zero |
+
+The terminal entry is current, including a terminal absence. Do not revive a past positive price or a category ending in `-1`. Name rank categories from `categoryTree` where the id appears there; `salesRankReference` is not necessarily the leaf category. Rank drops are not unit sales. `monthlySold` is “at least” that many bought in the past month, not an exact estimate. With no current `monthlySold` there is no badge now, whatever the history held.
+
+`couponHistory` is time/one-time/subscribe-and-save triples. An ended coupon means “no coupon now”, not the last discount. A null coupon is no current coupon reported.
+
+Only `liveOffersOrder` indices identify current offers. If requested offers failed (`offersSuccessful: false`), their absence proves nothing. A null, `"-1"` or `"-2"` seller id in `stats.buyBoxSellerId` or `buyBoxSellerIdHistory` identifies no seller. Eligible offers are not a Buy Box winner. `stats.buyBoxPrice` is the item's price and `stats.buyBoxShipping` its shipping; `stats.current[18]` is the two together. `availabilityAmazon: -1` means no Amazon offer, not no marketplace offers.
+
+Dimensions/weights are millimetres/grams; `0` or `-1` means unavailable. `fbaFees.pickAndPackFee` is money. `productType: 4` is no data; `5` is a variation parent.
+
+## Codes
+
+These codes describe the field, not the whole marketplace.
+
+| Offer `condition` | Meaning |
+|---|---|
+| 0 | unknown |
+| 1 | new |
+| 2 | used, like new |
+| 3 | used, very good |
+| 4 | used, good |
+| 5 | used, acceptable |
+| 6 | refurbished |
+| 7 | collectible, like new |
+| 8 | collectible, very good |
+| 9 | collectible, good |
+| 10 | collectible, acceptable |
+| 11 | rental |
+
+| `availabilityAmazon` | Meaning |
+|---|---|
+| -1 | no Amazon offer, not no marketplace offers |
+| 0 | in stock |
+| 1 | preorderable |
+| 2 | unknown |
+| 3 | backorderable |
+| 4 | delayed |
+
+| `productType` | Meaning |
+|---|---|
+| 0 | standard |
+| 1 | downloadable |
+| 2 | ebook |
+| 3 | inaccessible: no price, rating or offers data |
+| 4 | no data (invalid or deprecated ASIN) |
+| 5 | variation parent |

package/skills/keepa/references/raw-routes.md

@@ -0,0 +1,35 @@
+# Keepa raw routes
+
+`domain`: `1` us, `2` uk, `3` de, `4` fr, `5` jp, `6` ca, `8` it, `9` es, `10` in, `11` mx, `12` br. Other Amazon marketplaces are unavailable here.
+
+| Route | Parameters |
+|---|---|
+| `GET /product` | `domain`, `asin` (one ASIN only, never a list); optional `stats`, `update`, `history`, `days`, `offers`, `only-live-offers`, `rating`, `buybox`, `stock`, `aplus`, `videos` |
+| `GET /query` | `domain`, `selection` (finder JSON) |
+| `POST /query` | `domain`; finder selection in the `--body` file |
+| `GET /search` | `domain`, `type=product`, `term`, `asins-only=1`, optional `page` |
+| `GET /seller` | `domain`, `seller`, optional `storefront` |
+| `GET /category` | `domain`, `category`, optional `parents` |
+| `GET /bestsellers` | `domain`, `category`, optional `range` |
+| `GET /deal` | `selection` (deal JSON) |
+| `POST /deal` | deal selection in the `--body` file |
+
+Never name `key`; the gate attaches the credential. Admission refusals state the parameter rule before spending. A route outside this table is unavailable. Raw `/product` accepts one ASIN only; typed product asks handle lists. A failed typed request may still name kept replies; `cx raw keepa --record <id> [--part <n>]` reads one back, part 0 first.
+
+## Request units
+
+`stats` is in days; `update` is in hours; `category` is one category id on `/bestsellers` and up to ten comma-separated ids on `/category`. `update=0` asks for a refresh and may cost one more token.
+
+## Retained raw consumption
+
+These amounts record past replies, not a price list for future requests. Every raw request reserves 50 tokens; settlement uses the supplier's stated consumption.
+
+| Route | Retained consumption |
+|---|---|
+| `/query` finder page | 11 tokens |
+| `/search` | 10 tokens |
+| `/seller` with storefront | 10 tokens |
+| `/bestsellers` | 50 tokens |
+| `/deal` page | 5 tokens |
+
+Raw `/product` consumption depends on requested data; do not infer a fixed charge from the raw reservation.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.