@iann29/rastro 0.1.0 → 0.3.0

package/docs/upgrading.md

@@ -22,12 +22,35 @@ hosts still on them.
 | `0.1.0-alpha.10`                                      | Install `0.1.0-alpha.12` directly; new tables and fields are additive; re-export the configure functions to opt in                              | `/rastro/health` reports `tracker.version: "0.1.0-alpha.12"`        |
 | `0.1.0-alpha.11`                                      | Install `0.1.0-alpha.12` directly; same code, the package now ships `src/tracker/generated.ts`                                                  | A `convex/` test importing `@iann29/rastro/test` typechecks on push |
 | `0.1.0-alpha.12`                                      | Install `0.1.0` directly; every schema change is an optional field or a new table; add `analytics:public` to a grant only to allow public links | `/rastro/health` reports `tracker.version: "0.1.0"`                 |
+| `0.1.0`                                               | Install `0.2.0` directly; add the optional host callback and grant version to enable transfers                                                  | Health reports `0.2.0`; opted-in connectors advertise `transfer`    |
 | Any release whose packed declarations lack federation | Stop and request an eligible exact registry release                                                                                             | Packed declarations contain the federation exports                  |
 
 Do not upgrade a populated legacy deployment directly to a release that removes
 the `events` table. Schema acceptance alone does not prove that telemetry was
 migrated.
 
+## Organization transfers (0.2.0)
+
+Install `@iann29/rastro@0.2.0` after rehearsing on a non-production snapshot.
+The analytics component has no schema change or telemetry migration in this
+release. The tracker reports the new package version; its behavior is unchanged.
+
+To enable **Conexões → Transferir organização**, follow
+[the host changes in the federation setup guide](federation-setup.md#transfer-a-connection-to-another-organization):
+add optional `version` to the host's grant table, return it from
+`resolveConnection`, persist the destination organization and incremented
+version in `transferConnection`, and export that mutation. Keep existing
+versions when provisioning grants. Transfers also require `analytics:configure`
+in the local grant; read-only grants remain read-only after the package upgrade.
+
+Reverify the connection in **Conexões** after deploying so the control plane
+refreshes its capabilities and permissions. Acceptance: `/rastro/health` reports
+`tracker.version: "0.2.0"`, the opted-in connector manifest includes `transfer`,
+and a rehearsal transfer preserves site IDs and reports while rejecting the
+source organization's old token. If a response is lost, resume the same transfer
+through the dashboard; do not reset grant versions or clear the pending intent
+manually.
+
 ## Legacy event migration
 
 `0.1.0-alpha.2` is the published migration bridge. A DEV or snapshot deployment
@@ -384,3 +407,31 @@ control-plane issuer.
 
 Record the package version, deployment target, migration output, and verifier in
 the project's release evidence.
+
+### Session details and complete revenue lists
+
+After upgrading the package, export `getSession` and `revenueSummary` from the
+object returned by `exposeFederatedAnalyticsApi` in
+`convex/rastroFederation.ts`, then deploy the host and reverify its dashboard
+connection. The manifest advertises `sessionDetails` and `revenueSummary`;
+advertising them without exporting the functions leaves an incomplete host
+surface.
+
+`getSession({siteId, sessionId})` returns the retained session metadata (or
+null). The dashboard pairs it with the existing paginated `sessionJourney` so a
+copied session link keeps its duration, entry/exit and counters even after a
+reload. Older hosts still provide scoped session events, but cannot restore all
+metadata.
+
+`revenueSummary({siteIds, from, to})` returns exact `commissionCents` for the
+inclusive period. Revenue, conversion count, average order and currency reuse
+`overview` totals. The commission report reads existing daily affiliate stats
+for complete UTC days and trusted conversion records only for partial edge days;
+renamed/deleted affiliate definitions do not remove historical commissions. It
+rejects unavailable retained sources, mixed currencies and periods requiring
+more than 5,000 source rows instead of presenting partial totals. No new table,
+backfill or ingestion change is required. Older hosts show commissions as
+unavailable, never as the sum of a loaded list page.
+
+Session and conversion lists now expose per-site keyset continuation, merge rows
+in chronological order and label search as filtering only loaded records.

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/amageweb/amage-rastro/issues"
   },
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/src/component/_generated/component.ts

@@ -362,6 +362,47 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         }>,
         Name
       >;
+      getSession: FunctionReference<
+        "query",
+        "internal",
+        { sessionId: string; siteId: string },
+        {
+          _creationTime: number;
+          _id: string;
+          affiliateAttributedAt?: number;
+          affiliateExpiresAt?: number;
+          affiliateId?: string;
+          affiliateSlug?: string;
+          browser: string;
+          city?: string;
+          conversionCount: number;
+          country?: string;
+          currency?: string;
+          device: string;
+          durationMs: number;
+          entryPath: string;
+          eventCount: number;
+          exitPath: string;
+          lastSeenAt: number;
+          latitude?: number;
+          longitude?: number;
+          newVisitor?: boolean;
+          os: string;
+          pageviewCount: number;
+          referrer?: string;
+          revenueCents: number;
+          sessionId: string;
+          siteId: string;
+          source: string;
+          startedAt: number;
+          utmCampaign?: string;
+          utmMedium?: string;
+          utmSource?: string;
+          visitorId: string;
+          visitorKey?: string;
+        } | null,
+        Name
+      >;
       goalsReport: FunctionReference<
         "query",
         "internal",
@@ -676,6 +717,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      revenueSummary: FunctionReference<
+        "query",
+        "internal",
+        { from: number; siteIds: Array<string>; to: number },
+        { commissionCents: number },
+        Name
+      >;
       sessionJourney: FunctionReference<
         "query",
         "internal",

package/src/component/ingest.ts

@@ -413,10 +413,8 @@ export const ingestBatch = mutation({
       }
 
       if (event.type === "leave") {
-        // A departure only shortens live presence: it stores no telemetry,
-        // touches no aggregates, and never extends anything, so a replayed
-        // or late leave is inert. The read side filters by expiresAt and the
-        // sweep deletes the row, so the dashboard sees the exit in seconds.
+        // A departure closes the final duration interval without telemetry
+        // or new presence. Older departures cannot retire a bfcache return.
         if (!existingSession) {
           rejected += 1;
           continue;
@@ -441,7 +439,33 @@ export const ingestBatch = mutation({
           batchState,
         );
         const liveSession = liveState.current;
-        if (liveSession) {
+        if (liveSession && event.timestamp >= liveSession.lastSeenAt) {
+          // Only the still-covered tail is trusted; a delayed departure
+          // cannot lengthen an expired visit or move its start backwards.
+          if (
+            event.timestamp > existingSession.lastSeenAt &&
+            event.timestamp >= now - LIVE_SESSION_TTL_MS &&
+            event.timestamp <= liveSession.expiresAt
+          ) {
+            const durationMs = Math.max(
+              existingSession.durationMs,
+              event.timestamp - existingSession.startedAt,
+            );
+            sessionRow.current = {
+              ...existingSession,
+              lastSeenAt: event.timestamp,
+              exitPath: event.path,
+              durationMs,
+            };
+            sessionRow.dirty = true;
+            foldSessionDuration(
+              aggregateDeltas,
+              args.siteId,
+              event,
+              durationMs - existingSession.durationMs,
+              timezone,
+            );
+          }
           const expiresAt = Math.min(
             liveSession.expiresAt,
             now + LIVE_LEAVE_GRACE_MS,
@@ -2404,7 +2428,7 @@ function aggregateBucketStart(
   return Math.floor(timestamp / interval) * interval;
 }
 
-/** Folds only session duration growth, for heartbeats. */
+/** Folds session duration growth without telemetry, for heartbeats and leaves. */
 function foldSessionDuration(
   aggregateDeltas: AggregateDeltas,
   siteId: Id<"sites">,

package/src/component/reports.ts

@@ -932,6 +932,102 @@ async function readRouteRollups(
   return { rows, completeFrom: cutAt + DAY_MS };
 }
 
+/** Metadata for a selected session, independent of list pagination. */
+export const getSession = query({
+  args: { siteId: v.id("sites"), sessionId: v.string() },
+  returns: v.union(sessionDocumentValidator, v.null()),
+  handler: async (ctx, args) => {
+    const session = await ctx.db
+      .query("sessions")
+      .withIndex("by_siteId_and_sessionId", (q) =>
+        q.eq("siteId", args.siteId).eq("sessionId", args.sessionId),
+      )
+      .unique();
+    if (!session) return null;
+    const {
+      geoLookupAttemptedAt: _geo,
+      lastPageviewAt: _pageview,
+      ...result
+    } = session;
+    return result;
+  },
+});
+
+/** Exact commissions alongside overview's period revenue/conversion totals. */
+export const revenueSummary = query({
+  args: { siteIds: v.array(v.id("sites")), from: v.number(), to: v.number() },
+  returns: v.object({ commissionCents: v.number() }),
+  handler: async (ctx, args) => {
+    const siteIds = validateSiteIds(args.siteIds);
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const fullFrom = Math.ceil(args.from / DAY_MS) * DAY_MS;
+    const fullTo = Math.floor((args.to + 1) / DAY_MS) * DAY_MS;
+    let commissionCents = 0;
+    let rowsRead = 0;
+    const currencies = new Set<string>();
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      currencies.add(site.currency ?? "USD");
+      if (currencies.size > 1)
+        fail("CURRENCY_MISMATCH", "revenue sites must use the same currency");
+      if (fullFrom < fullTo) {
+        await assertSourceAvailable(
+          ctx,
+          [siteId],
+          ["affiliateStats"],
+          fullFrom,
+        );
+        const stats = await ctx.db
+          .query("affiliateDailyStats")
+          .withIndex("by_siteId_and_bucketStart", (q) =>
+            q
+              .eq("siteId", siteId)
+              .gte("bucketStart", fullFrom)
+              .lt("bucketStart", fullTo),
+          )
+          .take(MAX_REPORT_BUCKETS - rowsRead + 1);
+        rowsRead += stats.length;
+        failIfIncomplete(
+          stats,
+          MAX_REPORT_BUCKETS - (rowsRead - stats.length),
+          "commission buckets",
+        );
+        for (const row of stats) commissionCents += row.commissionCents;
+      }
+      // ponytail: boundary scans cap at MAX_REPORT_BUCKETS; add hourly commission
+      // rollups if busy partial days exceed this explicit report limit.
+      // Daily stats cannot answer partial days (24h and local-day windows).
+      // Read only those edges from the trusted ledger, never round the period.
+      const edges: Array<[number, number]> =
+        fullFrom < fullTo
+          ? [
+              [args.from, fullFrom - 1],
+              [fullTo, args.to],
+            ]
+          : [[args.from, args.to]];
+      for (const [from, to] of edges) {
+        if (from > to) continue;
+        await assertSourceAvailable(ctx, [siteId], ["conversions"], from);
+        const rows = await ctx.db
+          .query("conversions")
+          .withIndex("by_siteId_and_timestamp", (q) =>
+            q.eq("siteId", siteId).gte("timestamp", from).lte("timestamp", to),
+          )
+          .take(MAX_REPORT_BUCKETS - rowsRead + 1);
+        rowsRead += rows.length;
+        failIfIncomplete(
+          rows,
+          MAX_REPORT_BUCKETS - (rowsRead - rows.length),
+          "commission boundary conversions",
+        );
+        for (const row of rows) commissionCents += row.commissionCents;
+      }
+    }
+    return { commissionCents };
+  },
+});
+
 export const listSessions = query({
   args: {
     siteId: v.id("sites"),

package/src/tracker/generated.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/build-tracker.mjs. Do not edit.
-export const RASTRO_VERSION = "0.1.0";
+export const RASTRO_VERSION = "0.3.0";
 export const TRACKER_SOURCE = "(()=>{const e=document.currentScript,t=e?.dataset.site,s=e?.dataset.endpoint||e?.src&&new URL(\"events\",e.src).href;if(!t||!s)return;const o=()=>crypto.randomUUID?.()||Math.random()+\"\",n=new URLSearchParams(location.search),r=n.get(\"ref\")?.slice(0,64);let a,i,c;for(const e of[\"source\",\"medium\",\"campaign\",\"term\",\"content\"]){const t=n.get(\"utm_\"+e)?.slice(0,64);t&&((a??={})[\"utm_\"+e]=t)}try{i=sessionStorage._r||o(),sessionStorage._r=i,c=r||sessionStorage._a,c&&(sessionStorage._a=c),a||=sessionStorage._u&&JSON.parse(sessionStorage._u),a&&(sessionStorage._u=JSON.stringify(a))}catch{i=o(),c=r}let d=e.dataset.visitor;try{d||=localStorage._rv||=o()}catch{}d||=i;let l,p=0;const g=[],h=document.referrer?new URL(document.referrer).origin:void 0,u=e=>{const o=g.splice(0,50);if(!o.length)return;const n=()=>new Blob([JSON.stringify({siteId:t,events:o,sentAt:Date.now()})]);let r=n();for(;r.size>64e3&&o.length>1;)g.unshift(o.pop()),r=n();e&&navigator.sendBeacon(s,r)||fetch(s,{method:\"POST\",body:r,keepalive:1}).catch(()=>{}),g.length&&u(e)},m=(e,t,s)=>{const o=Date.now();g.push({eventId:`${i}.${o.toString(36)}.${p}`,sessionId:i,visitorId:d,type:e,name:t,path:location.pathname.slice(0,256),referrer:h,timestamp:o,sequence:p++,affiliateSlug:c,...s}),clearTimeout(l),l=setTimeout(u,1200)};let v;const f=()=>{const e=location.pathname;e!==v&&(v=e,m(\"pageview\",void 0,a&&{properties:a}))};window.rastro=(e,t,s)=>{if(\"context\"===e)return{sessionId:i,visitorId:d};\"event\"===e&&m(\"custom\",`${t||\"event\"}`.slice(0,80),s&&JSON.stringify(s).length>2e4?void 0:{properties:s})},document.addEventListener(\"click\",e=>{const t=e.target?.closest(\"a,button,[data-rastro-event]\");if(!t)return;const s=t.dataset.rastroEvent,o=t.href,n=o&&new URL(o),r=/^https?:$/.test(n?.protocol),a=r&&n.origin!==location.origin;m(s?\"custom\":a?\"outbound\":\"click\",s,{target:(t.dataset.rastroLabel||t.innerText||t.tagName).slice(0,64),href:r?((a?n.origin:\"\")+n.pathname).slice(0,256):void 0})},1);const S=e=>{const t=history[e];history[e]=(...e)=>{t.apply(history,e),f()}};S(\"pushState\"),S(\"replaceState\"),addEventListener(\"popstate\",f),addEventListener(\"pagehide\",()=>{m(\"leave\"),u(1)}),addEventListener(\"pageshow\",e=>{e.persisted&&(m(\"heartbeat\"),u(1))}),setInterval(()=>{m(\"heartbeat\"),u()},2e4),f()})();";
 export const TRACKER_GZIP_BASE64 = "H4sIAAAAAAACA3VV227cNhD9FZswBBKeMLbjGIUEZtEgfXDhJkE3eTLcmKZGEhGJVMnROtuV/r2QVuv1JXmTZsi5nDlnyLlQ7zbGu0gHqHJvugYdSdOFgI6WJtiWgBQuZK5JRyQZLSHExxZ0eeuto77HhYzBJInD+4Ovf19xhit0FBngaBeyClhktuCH1PeHUQSkLrhsm92rsRQT1i15GbTLffP16+WHheSi7//SVM1GLo4ZA6fmHEvUwVSfddBN5LU3mqx3Mk5WAUE5WSJxFrBgYiFjbQ3yE7g4F1mNdKDBgskKH/gMwYEvrln0XTDIgDWY265hwIxuWm1Lx4ARhsniHaEjdiNm9GiXqqPmGzvGZ9koSTjXi4XaDOJ6d+ZGkRgorDdWRYzRerckH3SJ8lvoe88FvDArC0aFvn/u0GCShL+wKiNA9/2L8F2S/Ln89FG2OkR8ca0ToH8SrVPTnUjButIWa66FGIwmU22sGqs1KgwjrLnCB3asbLTkQza2mfe9GmdU7/tZ9f14dQ4zjCfsNJoaWnUyc6NU1zdQ7ekZsMAQMCx2RHvhEdIHW1qXrrzND06gU/jAc69KGdt5Nm9PxMRIL2t0JVVPSekmUo5Z3tf+jl8/638ziuEyTwm2RE89RHT0O6UfNKF0/p6LQdxsuRaU42LiWhZktP/hu4tzfJMku8zvTjNRys7FyhbEvWx9y8VEYS4yTBKnV7bU5IOM6PL3qI13PEIQfV8gmYpH2DRIlc9T9vnT8guDO5+v0wDfEVtd2xWmp4OQE9B8kv0goJyTJ0nHUQzQKI5AEMUjtPa9ZKVsu1jxzdTuZZ7eHm3sII82XpJfTrDwNxditLTD7Y68l3lqYabBZZ7mQOsWUwSnG0wJWk1V+qDc8W90PIjn7O2FgN1Y0wrINhhJN+0E9r8dOoNpe3wMuihsbTXhsu7K1ICUMg4CTI06fLEN+o54LaBWEWn338Hp2cmJGKYBreahF+rJUnxRWoaHSq2ShK8UQsNZq0tcWbxnMJNNJ8mmDb7FQBZjqgchhuzeutzfy6AjBf8IZVvw7TL5QUwphTMBN78Ab8i2S3U6myQNZ6aL5BsGt0cb6vvZO9w+APjbiYA4y31P3Sh2tDvD88W28PRx1XEQAzzoSuf5H2PgKxsJHQbOTG3NdwZ7WZFCSTqUSAtpah8xEmca7joi7+B63Aevtt2/mmq8YVvl0VPJRUUPu2N7fEoMXtH0foBTfv/C+FEgr/+piNq4SI9eSxrTuoVsgydvfC1Aq5Akbt4Hh2o/z60la3hc7EBM9YL5ju5853KW7nqMsNk2lvLntV3pO6z7nqR1DsMX/EHjD+nyo25QPH4BYCw+DYvxFdjlThkTx3tiiSekn1fXOIZTMYOzVI/xrmwkH9bXeJPtPxWXUuLILJK6bes1n32AAgouhiFbcjbKeEmakAlYjs9jW2uDO8vLabe+jZMTip+6dYmVzZHBJJ2Gsxr1agzV8VMx/OpKrPz9lkIoWwxxdOZJwhvOKtSB7lDTHGMMEpEuHWFY6Zrv8jw9JwY4w/Ntn4KL7H/zTKaM3wgAAA==";
 export const TRACKER_RAW_BYTES = 2271;