@iann29/rastro 0.7.0 → 0.8.0

package/src/component/schema.ts

@@ -1,8 +1,11 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
 import {
+  adCatalogFieldsValidator,
   affiliateFieldsValidator,
   aggregateFieldsValidator,
+  leadEventTypeValidator,
+  leadFieldsValidator,
   batchedEventValidator,
   funnelFieldsValidator,
   goalFieldsValidator,
@@ -391,6 +394,48 @@ export default defineSchema({
     bots: v.number(),
   }).index("by_linkId_and_dayStart_and_shard", ["linkId", "dayStart", "shard"]),
 
+  // Leads the host's server reports (see leads.ts), one per host conversation.
+  leads: defineTable(leadFieldsValidator)
+    .index("by_siteId_and_leadKey", ["siteId", "leadKey"])
+    .index("by_siteId_and_firstAt", ["siteId", "firstAt"])
+    .index("by_siteId_and_ad_and_firstAt", ["siteId", "ad.adId", "firstAt"]),
+
+  // What happened to a lead, append-only; `eventId` makes a retry a no-op.
+  leadEvents: defineTable({
+    siteId: v.id("sites"),
+    leadId: v.id("leads"),
+    eventId: v.string(),
+    type: leadEventTypeValidator,
+    at: v.number(),
+    revenueCents: v.optional(v.number()),
+  })
+    .index("by_siteId_and_eventId", ["siteId", "eventId"])
+    .index("by_leadId_and_at", ["leadId", "at"]),
+
+  // One row per site, UTC cohort day, dimension and key. Lead volume is human
+  // scale (a conversation each), so a row is never a write hot spot.
+  leadDailyRollups: defineTable({
+    siteId: v.id("sites"),
+    dayStart: v.number(),
+    dimension: v.union(v.literal("origin"), v.literal("ad")),
+    key: v.string(),
+    leads: v.number(),
+    qualified: v.number(),
+    won: v.number(),
+    revenueCents: v.number(),
+  }).index("by_siteId_and_dimension_and_dayStart_and_key", [
+    "siteId",
+    "dimension",
+    "dayStart",
+    "key",
+  ]),
+
+  // Names the host fetches from the Meta Marketing API for the ads it saw.
+  adCatalog: defineTable(adCatalogFieldsValidator).index("by_siteId_and_adId", [
+    "siteId",
+    "adId",
+  ]),
+
   visitorSecrets: defineTable({
     key: v.literal("current"),
     value: v.string(),

package/src/component/validators.ts

@@ -373,6 +373,79 @@ export const trackedLinkFieldsValidator = v.object({
   disabledAt: v.optional(v.number()),
 });
 
+/**
+ * Leads (0.8.0): a conversation the host's server reports, with no web session
+ * behind it. Today the channel is WhatsApp; the stage follows the host's
+ * pipeline as `lead` → `qualified` → `won`, or `lost`.
+ */
+export const leadChannelValidator = v.literal("whatsapp");
+export const leadStageValidator = v.union(
+  v.literal("lead"),
+  v.literal("qualified"),
+  v.literal("won"),
+  v.literal("lost"),
+);
+/** What the host may move a lead to; `open` undoes a sale or a loss. */
+export const leadStageChangeValidator = v.union(
+  v.literal("qualified"),
+  v.literal("won"),
+  v.literal("lost"),
+  v.literal("open"),
+);
+export const leadEventTypeValidator = v.union(
+  v.literal("created"),
+  v.literal("qualified"),
+  v.literal("won"),
+  v.literal("lost"),
+  v.literal("open"),
+);
+
+/** The Meta Click-to-WhatsApp ad a lead came from, as the message carried it. */
+export const leadAdValidator = v.object({
+  adId: v.optional(v.string()),
+  sourceApp: v.optional(v.string()),
+  sourceUrl: v.optional(v.string()),
+  ctwaClid: v.optional(v.string()),
+  title: v.optional(v.string()),
+});
+
+export const leadFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  /** The host's opaque id for the lead (never a phone number). */
+  leadKey: v.string(),
+  channel: leadChannelValidator,
+  /** The channel's raw entry point, as the host received it. */
+  entryPoint: v.optional(v.string()),
+  /** The bucket reports group by: `ctwa_ad` for any ad, else the entry point or `none`. */
+  originKey: v.string(),
+  ad: v.optional(leadAdValidator),
+  /** A short display name the host chooses to share, if any. */
+  label: v.optional(v.string()),
+  /** The web visitor this lead came from, when a tracked link bridged them. */
+  visitorId: v.optional(v.string()),
+  stage: leadStageValidator,
+  revenueCents: v.number(),
+  firstAt: v.number(),
+  /** UTC day of `firstAt`: the cohort every later stage is counted in. */
+  dayStart: v.number(),
+  stageAt: v.number(),
+  qualifiedAt: v.optional(v.number()),
+  wonAt: v.optional(v.number()),
+  updatedAt: v.number(),
+});
+
+export const adCatalogFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  adId: v.string(),
+  adName: v.optional(v.string()),
+  adsetId: v.optional(v.string()),
+  adsetName: v.optional(v.string()),
+  campaignId: v.optional(v.string()),
+  campaignName: v.optional(v.string()),
+  thumbnailUrl: v.optional(v.string()),
+  updatedAt: v.number(),
+});
+
 export const ingestResultValidator = v.object({
   accepted: v.number(),
   duplicates: v.number(),
@@ -399,3 +472,94 @@ export type FunnelStep = Infer<typeof funnelStepValidator>;
 export type EventType = Infer<typeof eventTypeValidator>;
 export type Channel = Infer<typeof channelValidator>;
 export type Evidence = Infer<typeof evidenceValidator>;
+
+// Lead reports. Ids are plain strings so the host's own functions can return
+// these shapes unchanged across the component boundary.
+const leadCountersFields = {
+  leads: v.number(),
+  qualified: v.number(),
+  won: v.number(),
+  revenueCents: v.number(),
+};
+
+export const leadAdRowValidator = v.object({
+  adId: v.string(),
+  adName: v.union(v.string(), v.null()),
+  sourceApp: v.union(v.string(), v.null()),
+  sourceUrl: v.union(v.string(), v.null()),
+  title: v.union(v.string(), v.null()),
+  thumbnailUrl: v.union(v.string(), v.null()),
+  ...leadCountersFields,
+});
+
+export const leadAdsetRowValidator = v.object({
+  adsetId: v.union(v.string(), v.null()),
+  adsetName: v.union(v.string(), v.null()),
+  ...leadCountersFields,
+  ads: v.array(leadAdRowValidator),
+});
+
+export const leadCampaignRowValidator = v.object({
+  campaignId: v.union(v.string(), v.null()),
+  campaignName: v.union(v.string(), v.null()),
+  ...leadCountersFields,
+  adsets: v.array(leadAdsetRowValidator),
+});
+
+export const leadsReportValidator = v.object({
+  from: v.number(),
+  to: v.number(),
+  /** The sites' currency, or null when they differ (revenue then mixes). */
+  currency: v.union(v.string(), v.null()),
+  totals: v.object(leadCountersFields),
+  origins: v.array(v.object({ key: v.string(), ...leadCountersFields })),
+  /**
+   * Campaign → ad set → ad, with ads the catalog does not name yet grouped
+   * under a null campaign and a null ad set.
+   */
+  campaigns: v.array(leadCampaignRowValidator),
+});
+
+export const leadSummaryValidator = v.object({
+  leadId: v.string(),
+  siteId: v.string(),
+  label: v.union(v.string(), v.null()),
+  channel: leadChannelValidator,
+  originKey: v.string(),
+  entryPoint: v.union(v.string(), v.null()),
+  adId: v.union(v.string(), v.null()),
+  sourceApp: v.union(v.string(), v.null()),
+  stage: leadStageValidator,
+  revenueCents: v.number(),
+  firstAt: v.number(),
+  stageAt: v.number(),
+  /** Whether a web journey is linked, through a tracked link. */
+  hasVisitor: v.boolean(),
+});
+
+export const leadJourneyValidator = v.union(
+  v.null(),
+  v.object({
+    lead: leadSummaryValidator,
+    ad: v.union(
+      v.null(),
+      v.object({
+        adId: v.union(v.string(), v.null()),
+        adName: v.union(v.string(), v.null()),
+        adsetName: v.union(v.string(), v.null()),
+        campaignName: v.union(v.string(), v.null()),
+        sourceApp: v.union(v.string(), v.null()),
+        sourceUrl: v.union(v.string(), v.null()),
+        title: v.union(v.string(), v.null()),
+      }),
+    ),
+    visitorId: v.union(v.string(), v.null()),
+    events: v.array(
+      v.object({
+        type: leadEventTypeValidator,
+        at: v.number(),
+        revenueCents: v.union(v.number(), v.null()),
+      }),
+    ),
+  }),
+);

package/src/tracker/generated.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/build-tracker.mjs. Do not edit.
-export const RASTRO_VERSION = "0.7.0";
+export const RASTRO_VERSION = "0.8.0";
 export const TRACKER_SOURCE = "(()=>{const t=document.currentScript,e=t?.dataset.site,i=t?.dataset.endpoint||t?.src&&new URL(\"events\",t.src).href;if(!e||!i)return;const n=()=>crypto.randomUUID?.()||Math.random()+\"\",r=new URLSearchParams(location.search),s=r.get(\"ref\")?.slice(0,64);let o;for(const t of[\"source\",\"medium\",\"campaign\",\"term\",\"content\"]){const e=r.get(\"utm_\"+t)?.slice(0,64);e&&((o??={})[\"utm_\"+t]=e)}const a=\"gclid gbraid wbraid msclkid ttclid twclid li_fat_id ScCid rdt_cid dclid epik srsltid mc_cid mc_eid _hsenc igsh igshid fbclid\".split(\" \").filter(t=>r.has(t)).slice(0,8);let c,d,l,h,f=t.dataset.visitor||\"\",p=Boolean(f);try{f||=localStorage._rv||=n()}catch{}try{d=sessionStorage,l=d._r,c=d._ri==f&&d._rt,h=s||d._a,h&&(d._a=h),o||=d._u&&JSON.parse(d._u),o&&(d._u=JSON.stringify(o))}catch{h=s}let v,g=0;const u=[];let m=document.referrer.split(\"/\",3).join(\"/\")||void 0;const _=t=>{const n=u.splice(0,50);if(!n.length)return;const r=()=>new Blob([JSON.stringify({siteId:e,events:n,sentAt:Date.now()})]);let s=r();for(;s.size>64e3&&n.length>1;)u.unshift(n.pop()),s=r();t&&navigator.sendBeacon(i,s)||fetch(i,{method:\"POST\",body:s,keepalive:1}).catch(()=>{}),u.length&&_(t)},y=(t,e,i)=>{const r=Date.now(),s=r-c;c=r,s<18e5||(l=n(),\"pageview\"!=t&&(S=\"\",w()));try{d._r=l,d._ri=f,d._rt=r}catch{}u.push({eventId:`${l}.${r.toString(36)}.${g}`,sessionId:l,visitorId:f||l,type:t,name:e,path:location.pathname.slice(0,256),referrer:m,timestamp:r,sequence:g++,affiliateSlug:h,...i}),clearTimeout(v),v=setTimeout(_,1200)};let S;const w=()=>{const t=location.pathname;t!=S&&(S=t,y(\"pageview\",void 0,{properties:o,clid:a.length?a:void 0}))};window.rastro=(e,i,r)=>{if(\"context\"==e)return{sessionId:l,visitorId:f||l,identified:p};if(\"identify\"==e||\"reset\"==e){if(\"identify\"==e&&(!i||i.length>128||!/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(i)))return;if(\"identify\"==e&&i==f)return;_();const r=\"reset\"==e||p;if(p=\"identify\"==e,f=\"identify\"==e?i:n(),t.dataset.visitor=\"identify\"==e?f:\"\",r){h=void 0,o=void 0,m=void 0,a.length=0;try{\"reset\"==e&&(localStorage._rv=f),d._a=\"\",d._u=\"\"}catch{}}c=0,g=0,S=\"\",w()}\"event\"==e&&y(\"custom\",`${i||\"event\"}`.slice(0,80),r&&JSON.stringify(r).length>2e4?void 0:{properties:r})},document.addEventListener(\"click\",t=>{const e=t.target?.closest(\"a,button,[data-rastro-event]\");if(!e)return;const i=e.dataset.rastroEvent,n=e.href,r=n&&new URL(n),s=/^https?:$/.test(r?.protocol),o=s&&r.origin!=location.origin;y(i?\"custom\":o?\"outbound\":\"click\",i,{target:(e.dataset.rastroLabel||e.innerText||e.tagName).slice(0,64),href:s?((o?r.origin:\"\")+r.pathname).slice(0,256):void 0})},1);for(const t of[\"pushState\",\"replaceState\"]){const e=history[t];history[t]=(...t)=>{e.apply(history,t),w()}}addEventListener(\"popstate\",w);let b=0;const I=()=>{y(\"heartbeat\"),_()},L=()=>{b&&(clearInterval(b),b=0,y(\"leave\"),_(1))},E=()=>{document.hidden?L():b||(I(),b=setInterval(I,2e4))};addEventListener(\"pagehide\",L),addEventListener(\"pageshow\",E),document.addEventListener(\"visibilitychange\",E),b=setInterval(I,2e4),w(),E()})();";
 export const TRACKER_GZIP_BASE64 = "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";
 export const TRACKER_RAW_BYTES = 2999;