@koda-sl/baker-cli 0.370.0-dev.1981aa822 → 0.370.0-dev.886bf7ec3

package/README.md

@@ -3704,7 +3704,7 @@ baker shopify stock --limit 20                     # every product with every op
 **`meta.store`** is on every answer: `connection` (`connected` · `needs_reconnect` · `disconnected`), `catalog` (`starting` · `importing` · `ready` · `failed`, with `importProgress` while importing), `unreadable` (products Baker couldn't read; `unreadableCapped` past 100), `checksFailing` (Baker couldn't check the store for changes lately), `storefront` (`online_store`, or `own` for a store that sells through its own site) and `lastActivity` (when Baker last heard from the store — not a promise the copy is current). `hints[]` turn each of these into what to tell the user.
 **`store`:** `--full` adds the admin link and every country. `capped: true` means a count stopped at its ceiling — `outOfStock` and `partlyOut` at 100, `collections` at 500 — so that count reads "that many or more"; a hint says which.
 **`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`. `--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.
+**`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).
 **`collections`:** `--search <words>`; each row has `handle`, Shopify's product count and, on a store with an online store, `onStore`.

package/dist/cli.js

@@ -5897,7 +5897,11 @@ var REJECTION_CODES = [
   "missing_identity",
   "invalid_timestamp",
   "invalid_value",
-  "batch_too_large"
+  "batch_too_large",
+  // Appended, never inserted: the set a client branches on grows, and no code
+  // it already handles changes meaning.
+  "invalid_items",
+  "invalid_consent"
 ];
 var EVENT_INGEST_BATCH_MAX = 500;
 var EVENT_INGEST_BODY_MAX_BYTES = 8 * 1024 * 1024;
@@ -5910,12 +5914,15 @@ function validateEventName(name) {
   if (value === "" || value.length > MAX_EVENT_NAME || !EVENT_NAME.test(value)) return "invalid_name";
   return null;
 }
+var MAX_ITEM_QUANTITY = 1e6;
 var REJECTION_MESSAGES = {
   invalid_event_id: "event_id, when sent, must be 1-128 characters of A-Z a-z 0-9 . _ : -",
   invalid_name: "event_name is required: up to 80 characters of letters (any language), digits, spaces, . _ and -, starting with a letter or a digit",
   missing_identity: "user_data named nobody, and no url named a page",
   invalid_timestamp: "event_time must be an ISO-8601 instant with an offset or Unix seconds, and not in the future",
   invalid_value: "value and currency go together: a non-negative decimal and an ISO-4217 code",
+  invalid_items: "each item names a product_id, variant_id or feed_id; quantity is a whole number from 1 to 1000000; price is a non-negative decimal sent with a currency",
+  invalid_consent: "consent.analytics and consent.marketing, when sent, are granted or denied",
   batch_too_large: `a request carries at most ${EVENT_INGEST_BATCH_MAX} events and ${EVENT_INGEST_BODY_MAX_BYTES / (1024 * 1024)} MB`
 };
 
@@ -7294,7 +7301,8 @@ var TRIGGER_KINDS = {
       "utm_source",
       "utm_medium",
       "utm_campaign",
-      "properties.<name>"
+      "properties.<name>",
+      "items"
     ],
     keywords: ["purchase", "signup", "conversion", "analytics", "tracking", "hubspot", "crm", "deal", "funnel", "lead"]
   },
@@ -14906,8 +14914,22 @@ var ANALYTICS_EVENT_TYPES = [
    * page, `ingest` for a third party's server — and every report that needs to
    * tell them apart filters on that.
    */
-  "custom"
+  "custom",
+  /**
+   * A fact about the business that names no person — a product changed, a
+   * variant went out of stock.
+   *
+   * Only a commerce door writes it (`ingestShopifyFacts`), and it is a type of
+   * its own rather than a `custom` event with no identity for one reason:
+   * every report that lists named events whitelists `custom`, so an
+   * operational fact would otherwise appear in the conversion picker, the
+   * funnel and the sends. Here it reaches the raw feed and the agents that
+   * listen for its name, and no person-level report. The row builder blanks
+   * every identity column on it, whatever it carried.
+   */
+  "operational"
 ];
+var EVENT_ITEMS_MAX = 250;
 var ANALYTICS_DEVICE_TYPES = ["desktop", "mobile", "tablet", "bot", "unknown"];
 var ANALYTICS_BEACON_BATCH_MAX = 50;
 
@@ -30920,6 +30942,48 @@ var EVENT_FIELDS = [
     name: "properties",
     need: "optional",
     takes: "A flat object of strings \u2014 anything you want to break the event down by later."
+  },
+  {
+    name: "items",
+    need: "optional",
+    takes: "What was bought, one entry per product line \u2014 for a purchase, a cart or a refund.",
+    note: `Each line names its product by at least one of the ids below. value still carries the whole event's money. An order with more than ${EVENT_ITEMS_MAX} lines keeps the first ${EVENT_ITEMS_MAX}.`
+  },
+  {
+    name: "product_id, variant_id, feed_id",
+    need: "conditional",
+    under: true,
+    takes: "Your store's product id, its variant id, or the id the product has in your ads catalog. At least one per line, up to 255 characters each."
+  },
+  {
+    name: "quantity",
+    need: "optional",
+    under: true,
+    takes: `How many: a whole number from 1 to ${MAX_ITEM_QUANTITY.toLocaleString("en-US")}.`
+  },
+  {
+    name: "price",
+    need: "optional",
+    under: true,
+    takes: "The price of one unit, in the event's currency \u2014 so it needs currency. A decimal like value."
+  },
+  {
+    name: "consent",
+    need: "optional",
+    takes: "What the person allowed, if your site asked them.",
+    note: "Send it whenever you know it. A person who said no to marketing is still counted in your reports, and is never matched or sent to an ad platform."
+  },
+  {
+    name: "analytics",
+    need: "optional",
+    under: true,
+    takes: "granted or denied \u2014 whether they allowed being measured. Denied keeps the event and forgets who it was."
+  },
+  {
+    name: "marketing",
+    need: "optional",
+    under: true,
+    takes: "granted or denied \u2014 whether they allowed their visit to be used for advertising."
   }
 ];
 var RESPONSE_FIELDS = [
@@ -31249,7 +31313,37 @@ var ingestEventSchema = z39.strictObject({
    * left alone: masking one would rename the field and could collide with a
    * sibling.
    */
-  properties: z39.record(z39.string(), z39.string()).nullish()
+  properties: z39.record(z39.string(), z39.string()).nullish(),
+  /**
+   * What was bought, one entry per line — for a purchase, a cart, a refund.
+   *
+   * Flat and Meta-like for the same reason as the rest of this body: it is
+   * Meta's `contents` (`id`, `quantity`, `item_price`) and GA4's `items`
+   * (`item_id`, `quantity`, `price`) under one spelling a sender can map from
+   * either. A line names what it is by any of three ids — the store's product,
+   * its variant, or the id the product has in an ads catalog. `price` is the
+   * *unit* price in the event's `currency`; `value` stays the whole event's
+   * money. Structure only here; `validateItems` judges each line.
+   */
+  items: z39.array(
+    z39.strictObject({
+      product_id: z39.string().nullish(),
+      variant_id: z39.string().nullish(),
+      feed_id: z39.string().nullish(),
+      quantity: z39.union([z39.string(), z39.number()]).nullish(),
+      price: z39.union([z39.string(), z39.number()]).nullish()
+    })
+  ).nullish(),
+  /**
+   * What the person allowed, each `granted` or `denied`: `analytics` (being
+   * measured at all) and `marketing` (being matched and sent to an ad
+   * platform). Absent means the sender did not say. Enforced before anything
+   * is stored — see `./consent`. `validateConsent` judges the values.
+   */
+  consent: z39.strictObject({
+    analytics: z39.string().nullish(),
+    marketing: z39.string().nullish()
+  }).nullish()
 });
 var ingestBatchSchema = z39.strictObject({
   events: z39.array(ingestEventSchema).min(1).max(EVENT_INGEST_BATCH_MAX)
@@ -64584,6 +64678,8 @@ var shopifyProductRequestSchema = z50.object({
   content: flag.optional(),
   /** One custom field whole, by its name or `namespace.key`. */
   field: z50.string().min(1).max(200).optional(),
+  /** With `field`: the option (its `variantId`) whose field to return, when options share one. */
+  variant: z50.string().regex(/^\d{1,30}$/, "an option's variantId").optional(),
   /** How many of the option each buy link puts in the cart (1-99, default 1). */
   quantity: z50.coerce.number().int().min(1).max(SHOPIFY_MAX_BUY_QUANTITY).optional()
 });
@@ -64727,6 +64823,8 @@ var shopifyFieldRefSchema = z50.object({
   url: z50.string().optional(),
   mimeType: z50.string().optional(),
   alt: z50.string().optional(),
+  /** A video's preview image; its `url` is the video file itself. */
+  previewUrl: z50.string().optional(),
   /** A product's or a collection's title, from Baker's copy. */
   title: z50.string().optional(),
   /** An image brought into the library: its imageId, to place like the product's photos. */
@@ -64806,6 +64904,7 @@ var shopifyProductDetailSchema = z50.object({
   handle: z50.string(),
   /** The product's page in Baker — the link to share with the user. */
   url: z50.string(),
+  /** The product's page on the online store: to look at, never a buy button's link (that is each option's `buyUrl`). */
   storeUrl: z50.string().optional(),
   availability: shopifyAvailabilitySchema.optional(),
   status: shopifyProductStatusSchema.optional(),
@@ -65023,7 +65122,8 @@ function buyHints(product) {
   const hints2 = [];
   if (product.variants.some((variant) => variant.buyUrl)) {
     hints2.push(
-      `Use each option's \`buyUrl\` for the page's buy button \u2014 never build a Shopify link yourself (it follows the store's setting: ${product.buyDestination.replace("_", " ")}; \`--quantity <n>\` sets how many).`
+      `Use each option's \`buyUrl\` for the page's buy button \u2014 never build a Shopify link yourself (it follows the store's setting: ${product.buyDestination.replace("_", " ")}; \`--quantity <n>\` sets how many).`,
+      "Keep that `buyUrl` on the button: never `storeUrl` (a page to look at, not a buy link), and never drop or replace the buy button to get a page past its checks. The options to sell are `variants[]` alone \u2014 one buy button per option, each with its own `buyUrl`, never a size or colour picker made up from a size chart or other details. When the shopper must choose on the store, link the option's `productPage` (from `--full`)."
     );
   }
   const notes = new Set(product.variants.flatMap((variant) => variant.notes ?? []));
@@ -65051,7 +65151,8 @@ function contentHints(product) {
   }
   const truncated = product.content?.fields.find((field) => field.truncated);
   if (truncated) {
-    hints2.push(`Some fields are shown in part: read one whole with \`--field ${truncated.key}\`.`);
+    const option = truncated.variantId ? ` --variant ${truncated.variantId}` : "";
+    hints2.push(`Some fields are shown in part: read one whole with \`--field ${truncated.key}${option}\`.`);
   }
   if (product.content?.unreadable?.length || product.content?.fields.some((field) => field.unreadable)) {
     hints2.push(
@@ -65229,7 +65330,7 @@ registerSchema({
 });
 registerSchema({
   command: "shopify.product",
-  description: "One product of the connected store \u2014 accepts its id, its handle, a link to it on the store, in Baker or in Shopify admin. Returns its options with price, stock and `buyUrl` (the link for a page's buy button \u2014 never build a Shopify link yourself), prices by country, the options out of stock, its collections, its photos' library imageIds to place on a landing (`baker images download <imageIds> --out src/pages/<page>/_images/`) or pass to a creative, its videos' playbackIds (`<Video playbackId=\u2026/>`), and `contentSummary`: what else Baker keeps about it. Start here for a landing from a product: add `--content` for the formatted description, every custom field by its name (a size chart, care instructions), the rating, subscriptions and translations; `--field <name>` returns one field whole. `--out-of-stock` lists only the options out of stock.",
+  description: "One product of the connected store \u2014 accepts its id, its handle, a link to it on the store, in Baker or in Shopify admin. Returns its options with price, stock and `buyUrl` (the link for a page's buy button, one per option \u2014 never build a Shopify link yourself, never use `storeUrl` for it), prices by country, the options out of stock, its collections, its photos' library imageIds to place on a landing (`baker images download <imageIds> --out src/pages/<page>/_images/`) or pass to a creative, its videos' playbackIds (`<Video playbackId=\u2026/>`), and `contentSummary`: what else Baker keeps about it. Start here for a landing from a product: add `--content` for the formatted description, every custom field by its name (a size chart, care instructions), the rating, subscriptions and translations; `--field <name>` returns one field whole. `--out-of-stock` lists only the options out of stock.",
   args: {
     ref: { type: "positional", description: "Product id, handle, or a link to the product", required: true },
     "variants-cursor": {
@@ -65254,6 +65355,11 @@ registerSchema({
       description: 'One custom field whole, by its name or its key (e.g. "Size chart" or custom.size_chart)',
       required: false
     },
+    variant: {
+      type: "string",
+      description: "With --field: the option whose field to return, by its variantId (options share their fields, e.g. --field custom.fit --variant 102)",
+      required: false
+    },
     quantity: {
       type: "number",
       description: "How many of the option each buy link puts in the cart, 1-99 (default 1)",
@@ -65365,6 +65471,11 @@ var productCommand = defineCommand209({
       default: false
     },
     field: { type: "string", description: "One custom field whole, by its name or key", required: false },
+    variant: {
+      type: "string",
+      description: "With --field: the option whose field it is, by its variantId",
+      required: false
+    },
     quantity: {
       type: "string",
       description: "How many each buy link puts in the cart, 1-99 (default 1)",
@@ -65389,6 +65500,7 @@ var productCommand = defineCommand209({
           outOfStock: args5["out-of-stock"],
           content: args5.content,
           field: args5.field,
+          variant: args5.variant,
           quantity: args5.quantity,
           full: args5.full
         })
@@ -65464,6 +65576,7 @@ Examples:
   baker shopify product the-complete-snowboard       # one product: options with buyUrl, prices, photos, videos
   baker shopify product <handle> --content           # its whole details: description, custom fields, subscriptions
   baker shopify product <handle> --field "Size chart" # one custom field, whole
+  baker shopify product <handle> --field custom.fit --variant <variantId> # one option's field, whole
   baker shopify product <handle> --quantity 2        # buy links that put 2 in the cart
   baker shopify product <id> --out-of-stock          # only its options that are out of stock
   baker shopify stock                                # every product with options out of stock
@@ -65472,7 +65585,8 @@ Examples:
 Product photos are already in the image library: place them by imageId
 (baker images download <imageIds> --out src/pages/<page>/_images/), never by a cdn.shopify.com link.
 Product videos are in the video library: place them with <Video playbackId="\u2026" />.
-A page's buy button uses the option's buyUrl \u2014 never build a Shopify link yourself.
+A page's buy button uses the option's buyUrl, one button per option \u2014 never build a Shopify link
+yourself, and never use storeUrl (a page to look at) for it.
 NO_SHOPIFY_CONNECTION means no store is connected: follow error.fix. SHOPIFY_NOT_AVAILABLE means it cannot be
 connected here yet: carry on without it.
 Full guide: __tooling__/docs/tools/baker/shopify.md`