@comchatx/cx-amazon-finance-playbook 0.0.0-stage → 0.1.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 (71) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +13 -2
  3. package/README.zh-CN.md +14 -0
  4. package/package.json +107 -4
  5. package/prompts/fees-review.md +5 -0
  6. package/prompts/money-where.md +5 -0
  7. package/prompts/product-earnings.md +5 -0
  8. package/prompts/refunds-review.md +5 -0
  9. package/prompts/settlement-check.md +5 -0
  10. package/research/README.md +65 -0
  11. package/research/areas/fulfilment-charges.md +881 -0
  12. package/research/areas/money-flow.md +1204 -0
  13. package/research/areas/product-profit.md +719 -0
  14. package/research/areas/reconciliation.md +722 -0
  15. package/research/areas/refunds-reimbursements-adjustments.md +813 -0
  16. package/research/areas/selling-fees.md +1019 -0
  17. package/research/areas/tax-and-invoices.md +721 -0
  18. package/research/beyond/sellers-tools-and-research.md +930 -0
  19. package/research/method/finance-surface.md +928 -0
  20. package/skills/fees-and-charges/SKILL.md +36 -0
  21. package/skills/fees-and-charges/references/fulfilment-charges.md +92 -0
  22. package/skills/fees-and-charges/references/inbound-freight.md +51 -0
  23. package/skills/fees-and-charges/references/program-fees.md +69 -0
  24. package/skills/fees-and-charges/references/selling-fees.md +87 -0
  25. package/skills/fees-and-charges/references/where-fees-land.md +51 -0
  26. package/skills/money-flow/SKILL.md +37 -0
  27. package/skills/money-flow/references/booking.md +18 -0
  28. package/skills/money-flow/references/currency.md +56 -0
  29. package/skills/money-flow/references/deferral.md +44 -0
  30. package/skills/money-flow/references/holds.md +46 -0
  31. package/skills/money-flow/references/payouts.md +73 -0
  32. package/skills/money-flow/references/reads.md +60 -0
  33. package/skills/money-flow/references/reserves.md +32 -0
  34. package/skills/money-reads/SKILL.md +39 -0
  35. package/skills/money-reads/references/finances.md +42 -0
  36. package/skills/money-reads/references/history.md +40 -0
  37. package/skills/money-reads/references/payouts.md +32 -0
  38. package/skills/money-reads/references/products.md +26 -0
  39. package/skills/money-reads/references/questions.md +54 -0
  40. package/skills/money-reads/references/reports.md +32 -0
  41. package/skills/money-reads/references/roles-and-tools.md +34 -0
  42. package/skills/product-earnings/SKILL.md +39 -0
  43. package/skills/product-earnings/references/amazon-views.md +58 -0
  44. package/skills/product-earnings/references/economics-dataset.md +52 -0
  45. package/skills/product-earnings/references/import-tax.md +42 -0
  46. package/skills/product-earnings/references/profit-choices.md +88 -0
  47. package/skills/product-earnings/references/research.md +12 -0
  48. package/skills/product-earnings/references/stock-and-landed-cost.md +60 -0
  49. package/skills/refunds-and-reimbursements/SKILL.md +41 -0
  50. package/skills/refunds-and-reimbursements/references/claims.md +41 -0
  51. package/skills/refunds-and-reimbursements/references/lines-and-reads.md +53 -0
  52. package/skills/refunds-and-reimbursements/references/refunds.md +58 -0
  53. package/skills/refunds-and-reimbursements/references/reimbursements.md +87 -0
  54. package/skills/refunds-and-reimbursements/references/tools.md +20 -0
  55. package/skills/refunds-and-reimbursements/references/value-recovery.md +72 -0
  56. package/skills/settlement-reconcile/SKILL.md +40 -0
  57. package/skills/settlement-reconcile/references/accounts-and-stores.md +36 -0
  58. package/skills/settlement-reconcile/references/books-and-tools.md +92 -0
  59. package/skills/settlement-reconcile/references/completeness.md +41 -0
  60. package/skills/settlement-reconcile/references/outside-the-settlement.md +59 -0
  61. package/skills/settlement-reconcile/references/payouts-and-transactions.md +63 -0
  62. package/skills/settlement-reconcile/references/settlement-report.md +42 -0
  63. package/skills/settlement-reconcile/references/timing-and-deferral.md +66 -0
  64. package/skills/tax-lines/SKILL.md +37 -0
  65. package/skills/tax-lines/references/china.md +61 -0
  66. package/skills/tax-lines/references/eu-uk.md +58 -0
  67. package/skills/tax-lines/references/imports.md +18 -0
  68. package/skills/tax-lines/references/lines.md +48 -0
  69. package/skills/tax-lines/references/other-marketplaces.md +37 -0
  70. package/skills/tax-lines/references/reads.md +40 -0
  71. package/skills/tax-lines/references/us.md +37 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ComChatX
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.md CHANGED
@@ -1,3 +1,14 @@
1
- # Temporary Holding Version
1
+ cx matches each Amazon settlement to its payout and explains each difference, then works out each product's profit after Amazon's fees and your costs, as entered at Amazon or told to cx, in every marketplace you connected.
2
2
 
3
- 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.
3
+ Some things you can ask:
4
+
5
+ - Why was my last payout so much lower than my sales?
6
+ - Why did Amazon charge my card last month?
7
+ - Which lines on my German settlement carry VAT, and who pays it?
8
+
9
+ To see what holding stock costs and when to restock, also install [Amazon Stock Playbook](https://www.npmjs.com/package/@comchatx/cx-amazon-stock-playbook).
10
+
11
+ ## What it uses
12
+
13
+ - **[Amazon SP-API](https://www.npmjs.com/package/cx-amazon-sp-api):** your Amazon selling account, connected on the Amazon SP-API plugin. cx reads your transactions, settlements, payouts and fees there.
14
+ - **[Amazon Ads API](https://www.npmjs.com/package/@comchatx/cx-amazon-ads),** where you have it: where Amazon's per-product figures cannot be read, cx reads each product's ad spend here.
@@ -0,0 +1,14 @@
1
+ cx 把亚马逊的每期结算和回款对上,说清每笔差额从哪来;再扣掉亚马逊的各项费用和你的成本,算出每个商品赚了多少。成本用你在亚马逊后台填写的,或你告诉 cx 的。cx 读取你连接的每个站点的交易、费用、退款、赔偿和结算。
2
+
3
+ 你可以这样问:
4
+
5
+ - 为什么上一笔回款比销售额少这么多?
6
+ - 上个月亚马逊为什么扣了我信用卡里的钱?
7
+ - 德国站结算里哪些行带增值税,由谁缴?
8
+
9
+ 如果想知道库存压着要花多少钱、什么时候该补货,再装上[亚马逊库存分析手册](https://www.npmjs.com/package/@comchatx/cx-amazon-stock-playbook)。
10
+
11
+ ## 用到的数据
12
+
13
+ - **[亚马逊卖家接口](https://www.npmjs.com/package/cx-amazon-sp-api)**:你的亚马逊卖家账户,在亚马逊卖家接口插件里连接。cx 在这里读取交易、结算、回款和费用。
14
+ - **[亚马逊广告接口](https://www.npmjs.com/package/@comchatx/cx-amazon-ads)**(如果你装了):亚马逊的单品数据读不到时,cx 从这里读每个商品的广告花费。
package/package.json CHANGED
@@ -1,6 +1,109 @@
1
1
  {
2
2
  "name": "@comchatx/cx-amazon-finance-playbook",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Ties out your Amazon payouts, and each product's profit.",
5
+ "license": "MIT",
6
+ "author": "ComChatX",
7
+ "homepage": "https://github.com/comchatx/cx-amazon-finance-playbook#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/comchatx/cx-amazon-finance-playbook.git"
11
+ },
12
+ "bugs": "https://github.com/comchatx/cx-amazon-finance-playbook/issues",
13
+ "keywords": [
14
+ "pi-package"
15
+ ],
16
+ "type": "module",
17
+ "pi": {
18
+ "skills": [
19
+ "./skills"
20
+ ],
21
+ "prompts": [
22
+ "./prompts"
23
+ ]
24
+ },
25
+ "files": [
26
+ "skills",
27
+ "prompts",
28
+ "research",
29
+ "README.zh-CN.md"
30
+ ],
31
+ "scripts": {
32
+ "typecheck": "tsc --noEmit",
33
+ "test": "vitest run"
34
+ },
35
+ "comchatx": {
36
+ "name": "Amazon Finance Playbook",
37
+ "nameZh": "亚马逊财务分析手册",
38
+ "about": "对上亚马逊每期结算和回款,算出每个商品的利润。",
39
+ "mark": {
40
+ "line": "table"
41
+ },
42
+ "section": "extensions",
43
+ "order": 56,
44
+ "skills": {
45
+ "money-flow": {
46
+ "zh": "查清钱在哪:递延、预留、可用,何时回款。",
47
+ "en": "Where your money is, and when the next payout goes."
48
+ },
49
+ "fees-and-charges": {
50
+ "zh": "说清亚马逊每种费用怎么算、何时扣。",
51
+ "en": "Each Amazon fee: how it is worked out, when it posts."
52
+ },
53
+ "refunds-and-reimbursements": {
54
+ "zh": "分析退款、索赔和赔偿对回款的影响。",
55
+ "en": "What refunds, claims and reimbursements do to your money."
56
+ },
57
+ "product-earnings": {
58
+ "zh": "算出每个商品扣掉费用和成本后的利润。",
59
+ "en": "What each product earns after fees and costs."
60
+ },
61
+ "settlement-reconcile": {
62
+ "zh": "把结算和回款、账本对上,说清差额。",
63
+ "en": "Settlements matched to payouts and your books."
64
+ },
65
+ "tax-lines": {
66
+ "zh": "分清每笔钱里的税,以及由谁缴。",
67
+ "en": "The tax in each money line, and who pays it."
68
+ },
69
+ "money-reads": {
70
+ "zh": "说明每项财务数据从哪读、多久更新。",
71
+ "en": "Where each money figure is read, and how late it lands."
72
+ }
73
+ },
74
+ "prompts": {
75
+ "money-where": {
76
+ "zh": "看看亚马逊的钱在哪,下一笔回款哪天发出。"
77
+ },
78
+ "fees-review": {
79
+ "zh": "查看上个月亚马逊扣的费用、算法和变化。"
80
+ },
81
+ "product-earnings": {
82
+ "zh": "算出上个月每个商品扣掉费用和成本后赚了多少。"
83
+ },
84
+ "settlement-check": {
85
+ "zh": "把最近一期结算和回款对上,说清每笔差额。"
86
+ },
87
+ "refunds-review": {
88
+ "zh": "查看上个月的退款、赔偿和调整,各对应哪个订单或货件。"
89
+ }
90
+ },
91
+ "builds": [
92
+ {
93
+ "on": "cx-amazon-sp-api",
94
+ "need": "required"
95
+ },
96
+ {
97
+ "on": "@comchatx/cx-amazon-ads",
98
+ "need": "optional"
99
+ }
100
+ ]
101
+ },
102
+ "devDependencies": {
103
+ "@earendil-works/pi-ai": "1.5.0",
104
+ "@earendil-works/pi-coding-agent": "1.5.0",
105
+ "@types/node": "26.2.0",
106
+ "typescript": "7.0.2",
107
+ "vitest": "4.1.11"
108
+ }
109
+ }
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: "See which fees Amazon took last month, how each was worked out, and what changed."
3
+ argument-hint: "[month, marketplaces or SKUs, and your words]"
4
+ ---
5
+ Show me which fees Amazon took from me last month, how each one was worked out, and what changed against the months before. $@
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: "See where your Amazon money is now and when the next payout is due."
3
+ argument-hint: "[marketplaces and your words]"
4
+ ---
5
+ Tell me where my Amazon money is now: how much is available, how much is deferred and how much is held in reserve, and when my next payout is due. $@
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: "Work out what each product earned last month after Amazon's fees and your costs."
3
+ argument-hint: "[SKUs or ASINs, month, and your words]"
4
+ ---
5
+ Work out what each of my products earned on Amazon last month, after Amazon's fees and my own costs, and ask me for any cost you cannot find. $@
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: "See last month's refunds, reimbursements and adjustments, and the orders or shipments each ties to."
3
+ argument-hint: "[month, marketplaces, and your words]"
4
+ ---
5
+ Show me last month's refunds, reimbursements and adjustments, how much each came to, and which orders or shipments each ties back to. $@
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: "Match your latest settlement to its payout, and explain each difference."
3
+ argument-hint: "[settlement, marketplace, and your words]"
4
+ ---
5
+ Match my latest Amazon settlement to its payout, and explain where each difference comes from. $@
@@ -0,0 +1,65 @@
1
+ # Research for the Amazon finance playbook
2
+
3
+ This directory is the research base for a pi skill pack over `cx-amazon-sp-api`, ComChatX's open door to Amazon's Selling Partner API (`cx raw amazon-sp-api`). The pack covers where a seller's Amazon money is and what each product earned. Brief 2026-11-03-306 asked for the research first; its correction 1 governs every value that changes by marketplace or by year.
4
+
5
+ ## How the files were made
6
+
7
+ - Nine research files were written by nine seats on 2026-11-09/10. Each file was then checked by an adversarial verifier, who re-read quotes from raw pages and the models clone and corrected the file in place.
8
+ - Two completeness critics then named 24 gaps, which were filled with sources: a US/EU controller of an eight-figure seller, and a 财务总监 of a large Chinese cross-border seller.
9
+ - Correction 1 was then applied. Every position whose substance is a value that differs by marketplace or year says where cx reads it ("Read at run time: …"). Where no operation or page gives the value, the position says so and keeps the value with its marketplace and date.
10
+
11
+ ## Rules of the files
12
+
13
+ **Source order:**
14
+ 1. Amazon's own words, tagged **[official]**: Seller Forums News and staff posts, sell.amazon.*, globalselling.amazon.com, sellingpartners.aboutamazon.com, developer-docs, the SP-API models, rate-card PDFs;
15
+ 2. named practitioners and tools, tagged **[opinion]**, English and Chinese alike;
16
+ 3. published research, tagged **[research]**.
17
+
18
+ **A [seat] line** is the writing seat's own reasoning and enters no skill.
19
+
20
+ **Kept out:**
21
+ - no Amazon API host was called;
22
+ - no Seller Central help-hub content call was made (plain GET of a help page returns a JavaScript shell, so each file names the route it used instead);
23
+ - no seller data is held here.
24
+
25
+ **Positions** are facts and discipline under decision D233. Each is a definition, a rule of Amazon's, a dated deadline, a pitfall of the data, a measured effect, or a fact about a named tool or practitioner. None says when to ask the seller, imposes an order of work, sets a threshold of ours, or puts a ceiling on what cx may read or change.
26
+
27
+ **Values that move** (rates, bands, caps, windows, schedules, tax rates) are kept in a position only as evidence, with the marketplace, the date read and the citation; the position names where the value is read.
28
+
29
+ ## Files
30
+
31
+ | File | Covers | Positions |
32
+ |---|---|---|
33
+ | `areas/money-flow.md` | order to bank: deferred, reserve, available, disbursed, on-demand payouts, negative balances, currencies and the CNY leg, held funds, per-store schedules | P-flow-1…51 |
34
+ | `areas/selling-fees.md` | selling, programme and service fees: computation, posting, names; promotions, Vine, ads in finances, Haul, EPR, ACCS | P-sell-1…52 |
35
+ | `areas/fulfilment-charges.md` | FBA, storage, inbound, removal, returns, capacity, MCF, AGL and freight charges as money | P-ful-1…40 |
36
+ | `areas/refunds-reimbursements-adjustments.md` | refunds, A-to-z, chargebacks, SAFE-T, reimbursements and their value and windows, reversals, adjustments, value recovery | P-ref-1…51 |
37
+ | `areas/product-profit.md` | per-product earnings: Amazon's definition and surfaces, the seller's costs, the counting choices, stock as an asset, import VAT | P-prof-1…55 |
38
+ | `areas/reconciliation.md` | settlement V2, the documents' clocks, Date Range and deferred reports, payout-to-transactions, money outside the settlement, multi-account layout, retention | P-rec-1…59 |
39
+ | `areas/tax-and-invoices.md` | the four kinds of tax in a money line, tax documents and their roles, US nexus, the China side, import VAT | P-tax-1…47 |
40
+ | `method/finance-surface.md` | every money read with path, rate, role and deprecation; the role grid; pitfalls; borrow-first; the door | P-api-1…38 |
41
+ | `beyond/sellers-tools-and-research.md` | sellers' paid tools and practice (English and Chinese), where they disagree, practitioners, published research | P-tool-1…37 |
42
+
43
+ Each file has the same layout:
44
+ 1. what it covers;
45
+ 2. Amazon's rules;
46
+ 3. the SP-API and report faces;
47
+ 4. practitioners;
48
+ 5. published research;
49
+ 6. stable enough for a skill;
50
+ 7. read at run time;
51
+ 8. what only Seller Central shows;
52
+ 9. facts for human readers only;
53
+ 10. pages read;
54
+ 11. open questions;
55
+ 12. positions;
56
+ 13. verification.
57
+
58
+ ## What the pack holds (proposed at stop point 1; Jack passed it on 2026-11-10)
59
+
60
+ - **Skills:** `money-flow`, `fees-and-charges`, `refunds-and-reimbursements`, `product-earnings`, `settlement-reconcile`, `tax-lines`, `money-reads`.
61
+ - **Templates:** `/money-where`, `/fees-review`, `/product-earnings`, `/settlement-check`, `/refunds-review`.
62
+ - **Packages named:**
63
+ - `cx-amazon-sp-api` is required;
64
+ - `cx-amazon-ads` is optional, for ad spend per product.
65
+ - **Script:** none.