Update to Zid | زد

{
  "description": "Report a Zid store's sales and profit for any period. Use for a daily brief, a period comparison, a profit and loss estimate, best sellers, a breakdown by channel, city or payment method, or a report across several stores.",
  "included_files": [],
  "name": "sales-report",
  "skill_md_contents": "---\nname: sales-report\ndescription: Report a Zid store's sales and profit for any period. Use for a daily brief, a period comparison, a profit and loss estimate, best sellers, a breakdown by channel, city or payment method, or a report across several stores.\n---\n\n# Sales report\n\nAnswers \"how did the store do\" with numbers the merchant can check, and says\nwhere each number came from.\n\n## Ground rules\n\n- The merchant's explicit instructions take precedence over this skill.\n- Read only. This skill changes nothing in the store.\n- Every figure names its source (report or orders) and period. Estimates are\n  labelled as estimates, with what they leave out.\n- Amounts are in the store currency; dates are `YYYY-MM-DD`, and report periods\n  resolve in Asia/Riyadh.\n\n## 1. Settle the question\n\nPeriod, comparison (previous period, same weekday last week, same month last\nyear), and the figures wanted: sales and orders, profit, products, channels,\ncustomers. For a daily brief, default to yesterday against the same weekday a\nweek earlier.\n\n## 2. Read the numbers\n\n| Figure | Read |\n| --- | --- |\n| Headline totals: sales, orders, sessions, conversion | `zid_reports.sales_summary` with `period` (`yesterday`, `last_7_days`, `this_month`, `last_month` …) or `date_from` and `date_to`; `compare` true adds the previous period |\n| Revenue, discounts, shipping, tax, cost of goods, margin, returns | `zid_reports.sales_report`; `components` breaks it down by `periods`, `channel`, `location`, `products`, `category`, `coupons`, `city`, `payment_methods` and more; `peak` finds the busiest weekday or hour |\n| Best sellers | `zid_reports.top_products`, or `zid_reports.products_performance` for one row per product |\n| Today, as it happens | `zid_reports.live_sales` |\n| How current the data is | `zid_reports.data_freshness` |\n\n**When the store has no analytics access**, the reports answer that analytics is\nnot available. Then:\n\n1. `zid_orders.list_orders` with `dateFrom` and `dateTo`, `perPage` 100, every page.\n2. Leave out `cancelled` orders and orders whose payment failed; count the rest.\n3. Total the order amounts, discounts, shipping and VAT, and say the figures were\n   computed from orders. `zid_reports.live_sales` still works for today.\n\n## 3. Profit and loss\n\nReports give gross margin as a percentage, not profit. Build profit as:\n\n| Line | Source |\n| --- | --- |\n| Net sales | `zid_reports.sales_report` (or the order totals), after discounts and returns, without VAT |\n| − Cost of goods | `cogs` in `zid_reports.sales_report`; it needs a cost on each product. Name the best sellers without a cost and leave them out of the estimate |\n| − Payment fees | `zid_payments.get_account_statement` for ZidPay, or the rates in `zid_payments.get_fee_plan` × card sales |\n| − Shipping costs | `zid_shipping.list_shipping_charges` for Zid Ship labels and fees; other carriers from the merchant's invoice |\n| − Other costs | Ads, salaries, rent: only what the merchant provides |\n| = Profit (estimate) | Show each line, so the merchant can correct one |\n\n## 4. Several stores\n\nEach store has its own connection. Report each store separately, then a total\nrow, converting currencies only at the merchant's exchange rate.\n\n## Output\n\n- **Daily brief**: sales, orders, average order value and conversion against the\n  comparison, with the change in percent; top 5 products; one line on anything\n  unusual (a sales drop over 20%, a product that stopped selling, a spike in\n  returns); and orders waiting in `new` for more than a day.\n- **Period report**: the table of figures with sources, the breakdown asked for,\n  then two or three observations backed by the numbers.\n- **P&L**: the line table above with the estimate flagged and the missing costs listed.\n\nDone when every figure names its source and period, and every comparison shows both values.\n\nTo send the brief every morning, use the `zid-ops` skill for scheduled jobs.\n"
}