@koda-sl/baker-cli 0.380.0-dev.d26778d3f → 0.381.0-dev.3442c3753

package/README.md

@@ -3688,6 +3688,12 @@ No write surface against HubSpot itself — a form's fields, redirect, or consen
 
 ---
 
+### Shopify sign-up offers
+
+`baker shopify signup-offers` lists active, ended and this chat's staged offers, permissions, codes given and recent refused sign-ups. Stage an offer with `baker shopify change signup-offer set welcome-10 --name "Welcome" --percent 10 --valid-days 14 --max-codes 1000`; use `--amount` instead of `--percent` for a fixed amount, `--products` or `--collections` for eligibility, and `--minimum`, `--ends`, `--prefix` or `--combines` for its terms. `--json` / `--file` also accept the terms. `baker shopify change signup-offer end welcome-10` stops giving new codes after Publish; existing codes keep their terms. Both changes require the user's approval.
+
+Forms use the `shopifyCustomer` side effect: map its `customer` fields with `baker flows map`, name an optional offer handle and show the result with `<ShopifySignupCode form="newsletter" />`. Email and SMS consent each require a separate optional, visible, initially unticked checkbox. Every lead receives at most one code for an offer; Shopify shows one discount per lead.
+
 ### `baker shopify store | products | product | collections | stock | sales | buyers | buyer | countries | best-sellers | cohorts | segments | promotions | stock-holds`
 
 Read-only view of the company's **connected Shopify store**, from **Baker's own copy** of its catalog and the store's own orders — never a live call to Shopify. Baker keeps the copy current from the store (a change usually shows within about a minute) and checks the whole catalog daily; product photos are already in the image library.
@@ -3721,7 +3727,7 @@ baker shopify stock-holds --product <id>           # ads Baker paused because th
 **`products`:** `--search <words>`, `--collection <handle|id>`, `--stock`, `--limit <1-100>`, `--cursor`; `--full` adds vendor, type, option count, photo link, visibility and status. Every price, here and in `product` (`price`, `compareAt`, each option's price, `pricesByCountry`), is one string with its currency beside each amount: `"USD 785.95"`, `"USD 9.95 – USD 49.95"`. A row's `availability` is absent when the product is on the store, `link_only` when it is buyable only through its link, `not_for_sale` (with `status`) when it can't be bought on the online store.
 **`product`:** positional `<ref>` — the numeric id, the handle, a store product link (`…/products/<handle>`, even an all-digit handle), a Baker Products link, a Shopify admin product link (`admin.shopify.com/store/<shop>/products/<n>`), or `gid://shopify/Product/<n>`. Returns options (50 per page, `--variants-cursor` for more; 250 with `--full`), `outOptions` (up to 50, `outOptionsMore` for the rest), `pricesByCountry` when the store sells at more than one price, `photos[]` (`imageId` + a Baker-hosted `url`, never a Shopify link), `url` (the product's page in Baker) and `storeUrl` (the product's page on the store — never a buy button's link). `--full` adds the whole description, SEO, category, the admin link and each option's SKU, barcode, feed id and prices by country. `NOT_FOUND` carries a hint to search instead.
 
-**Details and buy links (`product`):** every option carries `buyUrl` — the link for a page's buy button, following the store's own setting (`buyDestination`: `checkout`, `store_cart` or `product_page`) — with `buyUrlKind`, `unavailable` when it can't be bought, and `notes` for what a link can't do (`password_protected`, `subscription_only`, `subscription_optional`, `own_storefront`, `details_pending`). `--quantity <1-99>` sets how many it adds. `videos[]` lists the product's videos in the library (`videoId`, `playbackId`); `contentSummary` names what else Baker keeps. `--content` adds `content`: the formatted description, every custom field by its name (long values previewed, `truncated: true`), the rating, subscriptions, bundle, YouTube/Vimeo and 3D links, translations, and `unreadable` for content the store owner hasn't let Baker read yet. `--field <name|namespace.key>` returns one field whole. `--full` adds `--content`, all three links per option and each option's weight, unit price, shipping and tax. `store` adds `buyDestination`, `passwordProtected`, `languages`, `policies` (`--full`: their text, and the store's brand).
+**Details and buy links (`product`):** every option carries `buyUrl` — its buy link for ads, emails and messages (a landing places `<ShopifyProduct product="…" />` instead, which shows the options, price and stock and hands the shopper to the store), following the store's own setting (`buyDestination`: `checkout`, `store_cart` or `product_page`) — with `buyUrlKind`, `unavailable` when it can't be bought, and `notes` for what a link can't do (`password_protected`, `subscription_only`, `subscription_optional`, `own_storefront`, `details_pending`). `--quantity <1-99>` sets how many it adds. `videos[]` lists the product's videos in the library (`videoId`, `playbackId`); `contentSummary` names what else Baker keeps. `--content` adds `content`: the formatted description, every custom field by its name (long values previewed, `truncated: true`), the rating, subscriptions, bundle, YouTube/Vimeo and 3D links, translations, and `unreadable` for content the store owner hasn't let Baker read yet. `--field <name|namespace.key>` returns one field whole. `--full` adds `--content`, all three links per option and each option's weight, unit price, shipping and tax. `store` adds `buyDestination`, `passwordProtected`, `languages`, `policies` (`--full`: their text, and the store's brand).
 **`collections`:** `--search <words>`; each row has `handle`, Shopify's product count and, on a store with an online store, `onStore`.
 **`stock`:** `--collection`, `--limit <1-200>` (default 50 per list), `--full` (SKUs and Baker links). Options that keep selling at zero or don't track stock are not out of stock.
 **`sales`:** `--days <1-395>` (default 30), `--by day|product|campaign|landing` (default `day`), `--limit <1-100>`, `--full` (each row's source, medium, campaign, click platform, landing or product id). `data.totals` (`orders`, `sales`, `added`, `refunded`, `net`) in `data.currency`; `data.rows[]` with a `label` and, by campaign or landing, a `credit` (`campaign` · `order` · `landing` · `unattributed` · `before_baker` · `other`), adding up to the totals. A sale counts when it is paid, at what was received; by day and product each fact counts when it happened, by campaign and landing each order paid in the period carries what was added and refunded on it since. `meta.salesReporting` (`meta`, `google`: `baker` · `shopify_channel` · `undecided`) says who reports the sales to the ad platforms; `meta.history` is `importing` while past orders still come in.
@@ -3737,7 +3743,7 @@ baker shopify stock-holds --product <id>           # ads Baker paused because th
 - **`cohorts`:** `--months <3-36>` (default 12); retention at months 1, 2, 3, 6, 12 and net per buyer by month 12 (`--full`: every month).
 - **`segments`:** each segment's buyers, share, net, average orders, days since the last order, top countries and first products, and its rule in this store's numbers.
 
-**`promotions`:** positional `<ref>` like `product`. Reads the product, scans this workspace's `src/pages/*` (import graph, ≤ 300 pages, files ≤ 256 KB) for its buy link, `/products/<handle>` or an option id, then `POST /api/shopify/promotions` with the linked landings. `data.ads[]` (`platform`, `level` ad|asset_group, `name`, `campaign`, `status` active|paused, `via` product_page|buy_link|landing), `data.landings[]` (`published`, `via` links_to_product|visitors_went_on), `data.shopping[]`, `data.catalog_ads`, `data.checked` (`not_checked` names a platform it could not read). A read made outside a Session says so in `hints`: only a read that carried a Session and named an ad lets “Restart ads when a product is back” later stage turning a pause from it back on, for review. `--full` adds ids, accounts, campaign / ad group / ad set ids, the Google `resource`, the URL and `data.remembered`.
+**`promotions`:** positional `<ref>` like `product`. Reads the product, scans this workspace's `src/pages/*` (import graph, ≤ 300 pages, files ≤ 256 KB) for its buy link, `/products/<handle>`, an option id or a `<ShopifyProduct>` / `<ShopifyBuyButton>` naming it (evidence `buy_button`), then `POST /api/shopify/promotions` with the linked landings. `data.ads[]` (`platform`, `level` ad|asset_group, `name`, `campaign`, `status` active|paused, `via` product_page|buy_link|landing), `data.landings[]` (`published`, `via` links_to_product|visitors_went_on), `data.shopping[]`, `data.catalog_ads`, `data.checked` (`not_checked` names a platform it could not read). A read made outside a Session says so in `hints`: only a read that carried a Session and named an ad lets “Restart ads when a product is back” later stage turning a pause from it back on, for review. `--full` adds ids, accounts, campaign / ad group / ad set ids, the Google `resource`, the URL and `data.remembered`.
 
 **`stock-holds`:** `--product <ref>`, `--all` (resolved holds too). Compact: `data.resume[]` — the one command to stage per ad Baker may turn back on now (`{ ad, command }`); `data.tell_user[]` — one sentence per ad, and per piece of out-of-stock work still waiting for review, written for the marketer; `data.pages[]` — landings the out-of-stock run changed, with the `baker chats diff … --surface landings` read of those changes. With `--product` it speaks only of that product's ads, including the ones Baker did not pause when it ran out. `--full` adds the codes behind each sentence: `holds[]` with each `verdict` read live from the ad platform, `pending_sessions[]`, `recently_closed[]`, `not_paused[]`, `pages_changed[]`.