@happyvertical/smrt-ads 0.57.36 → 0.57.38

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-ads",
-  "packageVersion": "0.57.36",
+  "packageVersion": "0.57.38",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "4f30b02bd348086a2613781f7ae92b3e4db553338e72ac4817346a4a3f9aa1dc",
-    "packageJson": "d541791941b2e8a8a0f6942614eeb4d126245289289d4199660ffbeb937710e1",
-    "agents": "876d4834346e5033011df69c99da0767db466b3855bf03fec787cd44f7290679"
+    "manifest": "b45f708391040d3a6b925b2ed785de6c230ede8cae79a602487c74c0bf3731ee",
+    "packageJson": "360d40ede9f544e786bde15db22ab274cfcee08610f16628f6694469fae3d2e5",
+    "agents": "a74f5ff1aea757073496bcd3fe01802b5a4e2f59b39a04c1bb0d11b81343f660"
   },
   "exports": [
     ".",
@@ -1167,27 +1167,31 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the tier is called, for example Sponsorship, Standard or House."
         },
         {
           "name": "priority",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "The order tiers are tried in: 1 is tried first, then 2, and so on."
         },
         {
           "name": "pricingModel",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "How ads in this tier are charged: a fixed price, per thousand showings, per click, or per sale."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A note about what this tier is for."
         }
       ],
       "relationships": [],
@@ -1547,34 +1551,39 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the size is called, for example Leaderboard."
         },
         {
           "name": "width",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How wide the ad is, in pixels."
         },
         {
           "name": "height",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How tall the ad is, in pixels."
         },
         {
           "name": "formatType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "What kind of ad fits this size: a picture, a piece written to look like your own content, or a video."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A note about where this size is usually used."
         }
       ],
       "relationships": [],
@@ -1739,28 +1748,32 @@
           "type": "crossPackageRef",
           "required": false,
           "related": "@happyvertical/smrt-commerce:SalesContract",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The sales contract this campaign is sold under, if there is one."
         },
         {
           "name": "tierId",
           "type": "foreignKey",
           "required": false,
           "related": "AdDeliveryTier",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The priority tier the campaign runs in. Tiers are tried in order when more than one campaign could show."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call the campaign, for example Summer sale."
         },
         {
           "name": "verticalSlug",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The category the campaign belongs to, such as retail."
         },
         {
           "name": "targeting",
@@ -1780,33 +1793,38 @@
           "name": "startDate",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "The first day the campaign can show."
         },
         {
           "name": "endDate",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "The last day the campaign can show."
         },
         {
           "name": "dailyBudget",
           "type": "decimal",
           "required": false,
           "columnType": "REAL",
-          "default": 0
+          "default": 0,
+          "description": "The most to spend in one day. The app shows this but does not stop the campaign by itself."
         },
         {
           "name": "totalBudget",
           "type": "decimal",
           "required": false,
           "columnType": "REAL",
-          "default": 0
+          "default": 0,
+          "description": "The most to spend over the whole campaign."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Where the campaign stands: draft, active, paused or completed. Only active campaigns show ads."
         }
       ],
       "relationships": [
@@ -2215,69 +2233,79 @@
           "type": "foreignKey",
           "required": false,
           "related": "AdGroup",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The campaign this ad belongs to."
         },
         {
           "name": "formatId",
           "type": "foreignKey",
           "required": false,
           "related": "AdFormat",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The ad size this ad is made for."
         },
         {
           "name": "assetId",
           "type": "crossPackageRef",
           "required": false,
           "related": "@happyvertical/smrt-assets:Asset",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The picture people see."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call this ad, for example Version A, blue button."
         },
         {
           "name": "clickUrl",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The web address people go to when they tap the ad."
         },
         {
           "name": "altText",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A few words that describe the picture for people who cannot see it."
         },
         {
           "name": "weight",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 1
+          "default": 1,
+          "description": "How often this ad shows compared with the others in its campaign: an ad with weight 2 shows twice as often as one with weight 1."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Where the ad stands: draft, active or paused. Only active ads show."
         },
         {
           "name": "impressions",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How many times the ad has been shown. The app counts this as it serves ads and refreshes it a little later."
         },
         {
           "name": "clicks",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How many times the ad has been tapped. The app counts this as it serves ads and refreshes it a little later."
         }
       ],
       "relationships": [
@@ -3221,7 +3249,232 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 30
   },
-  "agentDoc": "# @happyvertical/smrt-ads\n\nAd delivery with priority waterfall, weighted A/B testing, and immutable event tracking.\n\n## Models\n\n- **AdFormat**: IAB standard dimensions (width, height, type: banner/native/video)\n- **AdDeliveryTier**: priority levels — Sponsorship (1, FIXED pricing) > Standard (2, CPM) > House (3, fallback)\n- **AdGroup**: campaign with targeting, budget, zone restrictions\n- **AdVariation** (STI): creative variant with weighted selection for A/B. `weight=2` is 2x more likely than `weight=1`. Denormalized `impressions`/`clicks` fields.\n- **AdEvent** (STI, immutable): impression/click/conversion tracking. **Create-only** — no update/delete in API/MCP. `cli: false` (high-volume).\n\n## Cross-Package References (all plain string IDs)\n\n`contractId` → smrt-commerce `SalesContract`, `zoneId`/`siteId` → smrt-properties, `assetId` → smrt-assets, `verticalSlug` → smrt-tags\n\n## Tenancy\n\nOptional tenancy via `@TenantScoped({ mode: 'optional' })` is applied to the\nthree transactional models — `AdGroup`, `AdVariation`, and `AdEvent` — which\nparticipate in per-tenant ad serving and event tracking.\n\n`AdFormat` and `AdDeliveryTier` are deliberately **NOT** tenant-scoped: they\nare shared catalog/lookup tables.\n\n- `AdFormat` rows describe IAB standard ad dimensions (e.g. `728x90`\n  Leaderboard, `300x250` Medium Rectangle). The dimensions are an industry\n  standard, not a tenant-specific configuration.\n- `AdDeliveryTier` rows describe the priority waterfall for ad selection\n  (Sponsorship → Standard → House). Tiers are part of the package's\n  ad-serving contract; per-tenant tier definitions would fragment the\n  selection algorithm without a clear use case.\n\nEither model can still be filtered by tenant manually if a deployment ever\nneeds tenant-specific overrides, but the default is global. This mirrors the\ndocumented exception pattern in `packages/secrets/AGENTS.md` (`TenantKey`).\nEach `@smrt(...)` block on these two classes carries an inline comment\npointing back here.\n\n## Gotchas\n\n- **Priority waterfall**: lower priority number = higher priority in selection\n- **Weight is relative integer**: not percentage — probability calculated from total weight across variations\n- **Denormalized counts need async refresh**: impressions/clicks on AdVariation are eventually consistent\n- **No frequency capping or budget enforcement built-in**: external responsibility\n- **Targeting rules stored as JSON string**: no schema validation\n- **Optional tenancy** on `AdGroup`, `AdVariation`, `AdEvent` only — see Tenancy section above for `AdFormat`/`AdDeliveryTier` rationale\n",
+  "agentDoc": "# @happyvertical/smrt-ads\n\nAd delivery with priority waterfall, weighted A/B testing, and immutable event tracking.\n\n## Models\n\n- **AdFormat**: IAB standard dimensions (width, height, type: banner/native/video)\n- **AdDeliveryTier**: priority levels — Sponsorship (1, FIXED pricing) > Standard (2, CPM) > House (3, fallback)\n- **AdGroup**: campaign with targeting, budget, zone restrictions\n- **AdVariation** (STI): creative variant with weighted selection for A/B. `weight=2` is 2x more likely than `weight=1`. Denormalized `impressions`/`clicks` fields.\n- **AdEvent** (STI, immutable): impression/click/conversion tracking. **Create-only** — no update/delete in API/MCP. `cli: false` (high-volume).\n- **Recipe `ads.campaigns`** (`src/recipes.ts`, help in `src/campaigns.recipe.md`): lists ad campaigns, ads, ad sizes and priority tiers for the planner and other catalog hosts; `AdEvent` is left out (append-only serving log, nothing a person opens). Fields it shows carry `@field({ description })` in plain words; keep them when editing the models.\n\n## Cross-Package References (all plain string IDs)\n\n`contractId` → smrt-commerce `SalesContract`, `zoneId`/`siteId` → smrt-properties, `assetId` → smrt-assets, `verticalSlug` → smrt-tags\n\n## Tenancy\n\nOptional tenancy via `@TenantScoped({ mode: 'optional' })` is applied to the\nthree transactional models — `AdGroup`, `AdVariation`, and `AdEvent` — which\nparticipate in per-tenant ad serving and event tracking.\n\n`AdFormat` and `AdDeliveryTier` are deliberately **NOT** tenant-scoped: they\nare shared catalog/lookup tables.\n\n- `AdFormat` rows describe IAB standard ad dimensions (e.g. `728x90`\n  Leaderboard, `300x250` Medium Rectangle). The dimensions are an industry\n  standard, not a tenant-specific configuration.\n- `AdDeliveryTier` rows describe the priority waterfall for ad selection\n  (Sponsorship → Standard → House). Tiers are part of the package's\n  ad-serving contract; per-tenant tier definitions would fragment the\n  selection algorithm without a clear use case.\n\nEither model can still be filtered by tenant manually if a deployment ever\nneeds tenant-specific overrides, but the default is global. This mirrors the\ndocumented exception pattern in `packages/secrets/AGENTS.md` (`TenantKey`).\nEach `@smrt(...)` block on these two classes carries an inline comment\npointing back here.\n\n## Gotchas\n\n- **Priority waterfall**: lower priority number = higher priority in selection\n- **Weight is relative integer**: not percentage — probability calculated from total weight across variations\n- **Denormalized counts need async refresh**: impressions/clicks on AdVariation are eventually consistent\n- **No frequency capping or budget enforcement built-in**: external responsibility\n- **Targeting rules stored as JSON string**: no schema validation\n- **Optional tenancy** on `AdGroup`, `AdVariation`, `AdEvent` only — see Tenancy section above for `AdFormat`/`AdDeliveryTier` rationale\n",
+  "recipes": [
+    {
+      "id": "ads.campaigns",
+      "className": "AdsCampaignsRecipe",
+      "label": "Ads",
+      "summary": "Run ad campaigns on your site, choose which ads show where, and see which ones get clicked.",
+      "synonyms": [
+        "ads",
+        "advertising",
+        "ad campaigns",
+        "banner ads",
+        "advertisements",
+        "display ads"
+      ],
+      "models": [
+        "@happyvertical/smrt-ads:AdGroup",
+        "@happyvertical/smrt-ads:AdVariation",
+        "@happyvertical/smrt-ads:AdFormat",
+        "@happyvertical/smrt-ads:AdDeliveryTier"
+      ],
+      "nav": [
+        {
+          "label": "Ad campaigns",
+          "model": "@happyvertical/smrt-ads:AdGroup",
+          "icon": "tag",
+          "description": "Each campaign you run, with its dates, budget and where it stands.",
+          "noun": "ad campaign"
+        },
+        {
+          "label": "Ads",
+          "model": "@happyvertical/smrt-ads:AdVariation",
+          "icon": "fileText",
+          "description": "The ads inside each campaign, how often each shows and how many clicks it got.",
+          "noun": "ad"
+        },
+        {
+          "label": "Ad sizes",
+          "model": "@happyvertical/smrt-ads:AdFormat",
+          "icon": "layers",
+          "description": "The shapes and sizes an ad can be, shared by every campaign.",
+          "noun": "ad size"
+        },
+        {
+          "label": "Priority tiers",
+          "model": "@happyvertical/smrt-ads:AdDeliveryTier",
+          "icon": "settings",
+          "description": "The order campaigns are tried in when more than one could show.",
+          "noun": "tier"
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "grow",
+        "label": "Grow",
+        "icon": "tag",
+        "description": "Bring in new customers and reward the people who help."
+      },
+      "options": {
+        "@happyvertical/smrt-ads:AdGroup": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "status": {
+              "order": 2
+            },
+            "tierId": {
+              "label": "Priority tier",
+              "order": 3
+            },
+            "startDate": {
+              "label": "Starts on",
+              "order": 4
+            },
+            "endDate": {
+              "label": "Ends on",
+              "order": 5
+            },
+            "dailyBudget": {
+              "label": "Daily budget",
+              "order": 6
+            },
+            "totalBudget": {
+              "label": "Total budget",
+              "order": 7
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "contractId": {
+              "label": "Sales contract",
+              "visibility": "advanced"
+            },
+            "verticalSlug": {
+              "label": "Category",
+              "visibility": "advanced"
+            },
+            "targeting": {
+              "visibility": "hidden"
+            },
+            "zoneIds": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-ads:AdVariation": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "groupId": {
+              "label": "Ad campaign",
+              "order": 2
+            },
+            "formatId": {
+              "label": "Ad size",
+              "order": 3
+            },
+            "assetId": {
+              "label": "Picture",
+              "order": 4
+            },
+            "clickUrl": {
+              "label": "Link to",
+              "order": 5
+            },
+            "altText": {
+              "label": "Words for the picture",
+              "order": 6
+            },
+            "weight": {
+              "order": 7
+            },
+            "status": {
+              "order": 8
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "impressions": {
+              "label": "Times shown",
+              "locked": true,
+              "visibility": "advanced"
+            },
+            "clicks": {
+              "locked": true,
+              "visibility": "advanced"
+            }
+          }
+        },
+        "@happyvertical/smrt-ads:AdFormat": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "width": {
+              "order": 2
+            },
+            "height": {
+              "order": 3
+            },
+            "formatType": {
+              "label": "Kind",
+              "order": 4
+            },
+            "description": {
+              "order": 5
+            }
+          }
+        },
+        "@happyvertical/smrt-ads:AdDeliveryTier": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "priority": {
+              "order": 2
+            },
+            "pricingModel": {
+              "label": "How it is charged",
+              "order": 3
+            },
+            "description": {
+              "order": 4
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAds is where you run advertising on your own site. An ad campaign sets the\ndates, the budget and the priority tier; the ads inside it are the pictures\npeople actually see, each with a link. When a campaign has more than one ad,\nthe app shares the showings between them by weight, so you can try two\nversions and see which gets more clicks.\n\nAd sizes and priority tiers are shared lists. Set them up once; every campaign\npicks from them. When more than one campaign could show in the same place, the\ntier decides which is tried first.\n\nThe app counts every showing and click as it serves the ads. Those counts are\nrefreshed on the ad a little later; you read them, you do not type them.\n\n## Tasks\n\n### Add an ad size\n\n1. Open the ad sizes and choose **New**.\n2. Type the **{field:AdFormat.name}**, for example \"Leaderboard\".\n3. Enter the **{field:AdFormat.width}** and **{field:AdFormat.height}**.\n4. Pick the **{field:AdFormat.formatType}**: a picture, a piece written to look like your own content, or a video.\n5. Save. The usual sizes are 728 by 90, 300 by 250 and 320 by 50.\n\n### Set up the priority tiers\n\n1. Open the priority tiers and choose **New**.\n2. Type the **{field:AdDeliveryTier.name}**, for example \"Sponsorship\", \"Standard\" or \"House\".\n3. Set the **{field:AdDeliveryTier.priority}**: 1 is tried first, then 2, then 3.\n4. Pick **{field:AdDeliveryTier.pricingModel}** to say how ads in this tier are charged.\n5. Save. A \"House\" tier with the last priority is a good place for your own ads, so something always shows.\n\n### Start an ad campaign\n\n1. Open the ad campaigns and choose **New**.\n2. Type the **{field:AdGroup.name}**, for example \"Summer sale\".\n3. Pick the **{field:AdGroup.tierId}** it runs in.\n4. Set when it **{field:AdGroup.startDate}** and **{field:AdGroup.endDate}**.\n5. Enter the **{field:AdGroup.dailyBudget}** and the **{field:AdGroup.totalBudget}**. The app does not stop a campaign at its budget by itself; keep an eye on the counts.\n6. Leave the **{field:AdGroup.status}** as draft until the ads are ready, then set it to active.\n7. Save.\n\n### Add an ad to a campaign\n\n1. Open the ads and choose **New**.\n2. Type the **{field:AdVariation.name}**, for example \"Version A, blue button\".\n3. Pick the **{field:AdVariation.groupId}** it belongs to and the **{field:AdVariation.formatId}** it is made for.\n4. Choose the **{field:AdVariation.assetId}** people will see.\n5. Enter the web address it should **{field:AdVariation.clickUrl}** when someone taps it.\n6. Write a few **{field:AdVariation.altText}** for people who cannot see the picture.\n7. Set the **{field:AdVariation.weight}**. An ad with weight 2 shows twice as often as one with weight 1 in the same campaign.\n8. Set the **{field:AdVariation.status}** to active when it is ready to show.\n9. Save.\n\n### Pause or finish a campaign\n\n1. Open the ad campaign.\n2. Change the **{field:AdGroup.status}** to paused to stop it for now, or to completed when it is over.\n3. Save. The ads in it stop showing straight away.\n\n### See which ad is doing better\n\n1. Open the ads and find the ads in one campaign.\n2. Compare the **{field:AdVariation.impressions}** and **{field:AdVariation.clicks}** of each. These are counted by the app as it serves the ads and refreshed a little later.\n3. Give the better ad a higher **{field:AdVariation.weight}**, or pause the weaker one by changing its **{field:AdVariation.status}**.\n",
+        "fieldRefs": [
+          "AdDeliveryTier.name",
+          "AdDeliveryTier.pricingModel",
+          "AdDeliveryTier.priority",
+          "AdFormat.formatType",
+          "AdFormat.height",
+          "AdFormat.name",
+          "AdFormat.width",
+          "AdGroup.dailyBudget",
+          "AdGroup.endDate",
+          "AdGroup.name",
+          "AdGroup.startDate",
+          "AdGroup.status",
+          "AdGroup.tierId",
+          "AdGroup.totalBudget",
+          "AdVariation.altText",
+          "AdVariation.assetId",
+          "AdVariation.clickUrl",
+          "AdVariation.clicks",
+          "AdVariation.formatId",
+          "AdVariation.groupId",
+          "AdVariation.impressions",
+          "AdVariation.name",
+          "AdVariation.status",
+          "AdVariation.weight"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ads",
-  "version": "0.57.36",
+  "version": "0.57.38",
   "description": "Advertising delivery and tracking models for SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,13 +19,13 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.57.36",
-    "@happyvertical/smrt-tenancy": "0.57.36"
+    "@happyvertical/smrt-core": "0.57.38",
+    "@happyvertical/smrt-tenancy": "0.57.38"
   },
   "devDependencies": {
-    "@happyvertical/smrt-commerce": "0.57.36",
-    "@happyvertical/smrt-vitest": "0.57.36",
-    "@happyvertical/sql": "^0.109.0",
+    "@happyvertical/smrt-commerce": "0.57.38",
+    "@happyvertical/smrt-vitest": "0.57.38",
+    "@happyvertical/sql": "^0.110.0",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.6",