@agent-native/core 0.121.2 → 0.122.1

package/corpus/templates/clips/server/db/schema.ts

@@ -166,6 +166,8 @@ export const recordings = table("recordings", {
     .default("uploading"),
   uploadProgress: integer("upload_progress").notNull().default(0),
   failureReason: text("failure_reason"),
+  loomImportClaimId: text("loom_import_claim_id"),
+  loomImportClaimedAt: text("loom_import_claimed_at"),
 
   // Non-destructive edits: JSON `{ trims: [{startMs,endMs,excluded}], blurs: [...], speed: [...] }`
   editsJson: text("edits_json").notNull().default("{}"),
@@ -382,6 +384,31 @@ export const recordingViews = table("recording_views", {
   viewedAt: text("viewed_at").notNull().default(now()),
 });
 
+// Agent views — one row per (clip, agent, time bucket). Deliberately separate
+// from `recording_viewers` / `recording_views` so no human-view count can ever
+// pick agents up by forgetting a filter: the human tables stay agent-free.
+export const recordingAgentViews = table(
+  "recording_agent_views",
+  {
+    id: text("id").primaryKey(),
+    recordingId: text("recording_id").notNull(),
+    // sha256 of user-agent + request IP. Never stores the raw IP.
+    agentKey: text("agent_key").notNull(),
+    agentLabel: text("agent_label"),
+    // Time bucket that collapses one agent's burst of context/transcript/frame
+    // polls into a single view.
+    viewSessionId: text("view_session_id").notNull(),
+    firstSeenAt: text("first_seen_at").notNull().default(now()),
+    lastSeenAt: text("last_seen_at").notNull().default(now()),
+    requestCount: integer("request_count").notNull().default(1),
+  },
+  (view) => ({
+    recordingAgentViewSessionUnique: uniqueIndex(
+      "recording_agent_views_session_unique_idx",
+    ).on(view.recordingId, view.agentKey, view.viewSessionId),
+  }),
+);
+
 // -----------------------------------------------------------------------------
 // Meetings (Granola-style) — recording + transcript + AI notes anchored to
 // a calendar event or an ad-hoc meeting block. Composes with the existing

package/corpus/templates/clips/server/lib/agent-views.ts

@@ -0,0 +1,145 @@
+/**
+ * Agent views — counting when an *outside agent* reads a clip through the
+ * public agent APIs (`/api/agent-context.json`, `/api/agent-transcript.json`,
+ * `/api/agent-frame.jpg`), as opposed to a human opening the player.
+ *
+ * Those routes are agent-only surfaces: a human watching a clip never hits
+ * them, so a request on one is the signal. Counts live in their own table so
+ * every existing human-view query stays agent-free by construction.
+ */
+
+import { createHash } from "node:crypto";
+
+import { count, desc, eq, sql } from "drizzle-orm";
+import { getRequestHeader, getRequestIP, type H3Event } from "h3";
+
+import { getDb, schema } from "../db/index.js";
+import { nanoid } from "./recordings.js";
+
+/**
+ * One agent's burst of context + transcript + frame polls is one view.
+ * Fixed windows mean a burst straddling a boundary counts twice; switch to
+ * last-seen-gap dedup if that ever shows up in the numbers.
+ */
+export const AGENT_VIEW_SESSION_MS = 30 * 60 * 1000;
+
+const AGENT_LABELS: [RegExp, string][] = [
+  [/claude|anthropic/i, "Claude"],
+  [/chatgpt|gptbot|oai-searchbot|openai/i, "ChatGPT"],
+  [/perplexity/i, "Perplexity"],
+  [/gemini|google-extended|googleother/i, "Gemini"],
+  [/copilot/i, "Copilot"],
+  [/cursor/i, "Cursor"],
+  [/bingbot|bingpreview/i, "Bing"],
+  [/applebot/i, "Apple Intelligence"],
+  [/meta-external|facebookbot/i, "Meta AI"],
+  [/bytespider|amazonbot|ccbot|diffbot|youbot/i, "Crawler"],
+];
+
+export const UNKNOWN_AGENT_LABEL = "Agent";
+
+export function agentLabelFromUserAgent(userAgent: string): string {
+  for (const [pattern, label] of AGENT_LABELS) {
+    if (pattern.test(userAgent)) return label;
+  }
+  return UNKNOWN_AGENT_LABEL;
+}
+
+export function agentViewSessionId(
+  now: number,
+  bucketMs = AGENT_VIEW_SESSION_MS,
+): string {
+  return String(Math.floor(now / bucketMs));
+}
+
+/** Hashed so an agent is distinguishable across polls without storing its IP. */
+export function agentKeyFor(userAgent: string, ip: string): string {
+  return createHash("sha256")
+    .update(`${userAgent}|${ip}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Best-effort: never let view accounting fail an agent's read of a clip.
+ */
+export async function recordAgentView(
+  event: H3Event,
+  recordingId: string,
+  nowMs: number = Date.now(),
+): Promise<void> {
+  try {
+    const userAgent = (getRequestHeader(event, "user-agent") ?? "").slice(
+      0,
+      512,
+    );
+    const ip = getRequestIP(event) || "unknown";
+    const now = new Date(nowMs).toISOString();
+
+    await getDb()
+      .insert(schema.recordingAgentViews)
+      .values({
+        id: nanoid(),
+        recordingId,
+        agentKey: agentKeyFor(userAgent, ip),
+        agentLabel: agentLabelFromUserAgent(userAgent),
+        viewSessionId: agentViewSessionId(nowMs),
+        firstSeenAt: now,
+        lastSeenAt: now,
+        requestCount: 1,
+      })
+      .onConflictDoUpdate({
+        target: [
+          schema.recordingAgentViews.recordingId,
+          schema.recordingAgentViews.agentKey,
+          schema.recordingAgentViews.viewSessionId,
+        ],
+        set: {
+          lastSeenAt: now,
+          requestCount: sql`${schema.recordingAgentViews.requestCount} + 1`,
+        },
+      });
+  } catch (err) {
+    console.warn("[agent-views] failed to record agent view:", err);
+  }
+}
+
+export async function countRecordingAgentViews(
+  recordingId: string,
+): Promise<number> {
+  const [row] = await getDb()
+    .select({ value: count() })
+    .from(schema.recordingAgentViews)
+    .where(eq(schema.recordingAgentViews.recordingId, recordingId));
+  return Number(row?.value ?? 0);
+}
+
+export interface AgentViewerSummary {
+  agentLabel: string;
+  views: number;
+  lastSeenAt: string;
+}
+
+/** Agents that read this clip, most recent first, grouped by product label. */
+export async function listRecordingAgentViewers(
+  recordingId: string,
+  limit = 8,
+): Promise<AgentViewerSummary[]> {
+  const rows = await getDb()
+    .select({
+      agentLabel: schema.recordingAgentViews.agentLabel,
+      views: count(),
+      lastSeenAt: sql<string>`MAX(${schema.recordingAgentViews.lastSeenAt})`,
+    })
+    .from(schema.recordingAgentViews)
+    .where(eq(schema.recordingAgentViews.recordingId, recordingId))
+    .groupBy(schema.recordingAgentViews.agentLabel)
+    .orderBy(desc(sql`MAX(${schema.recordingAgentViews.lastSeenAt})`))
+    .limit(limit);
+
+  return rows.map((r) => ({
+    agentLabel: r.agentLabel || UNKNOWN_AGENT_LABEL,
+    views: Number(r.views ?? 0),
+    lastSeenAt: r.lastSeenAt,
+  }));
+}

package/corpus/templates/clips/server/lib/post-finalize-dispatch.ts

@@ -11,7 +11,8 @@ export type PostFinalizeJobKind =
   | "media-ready"
   | "seekable"
   | "transcript"
-  | "brain-export";
+  | "brain-export"
+  | "loom-import";
 
 export const POST_FINALIZE_JOB_TOKEN_KIND = "clips-post-finalize-job";
 

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -31,6 +31,7 @@ import {
 } from "../../shared/transcript-segments.js";
 import { resolveTranscriptPresentation } from "../../shared/transcript-status.js";
 import { getDb, schema } from "../db/index.js";
+import { recordAgentView } from "./agent-views.js";
 import { verifySharePassword } from "./share-password.js";
 
 export type PublicAgentRecording = typeof schema.recordings._.inferSelect;
@@ -290,6 +291,12 @@ export async function loadPublicAgentAccess(
     }
   }
 
+  // Every agent API route funnels through here, so this is the one place that
+  // sees an outside agent read a clip. Owner requests are previews, not views.
+  if (!viewerIsOwner) {
+    await recordAgentView(event, recording.id);
+  }
+
   return {
     ok: true,
     access: {

package/corpus/templates/clips/server/lib/recording-share-grant.ts

@@ -0,0 +1,79 @@
+/**
+ * Explicit share-grant lookup for the direct `/r/:id` recording page.
+ *
+ * Lives beside `recording-page-access.ts` rather than inside it so that module
+ * stays free of database imports and their registration side effects. Every
+ * surface that decides whether a viewer may open the authenticated recording
+ * page — the player action and the public share endpoint that auto-redirects
+ * into it — must use this helper, or the share page and the page it redirects
+ * to will disagree and ping-pong.
+ */
+
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { and, eq, or, sql } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+import type { RecordingPageAccessRole } from "./recording-page-access.js";
+import type { RecordingVisibility } from "./recordings.js";
+
+export interface RecordingShareGrantInput {
+  recordingId: string;
+  role: RecordingPageAccessRole;
+  visibility: RecordingVisibility;
+  hasPassword: boolean;
+  /** Agent/MCP/A2A callers, which may open password-less public clips. */
+  isAgentCaller?: boolean;
+  /** Omit to read the ambient request context. */
+  userEmail?: string | null;
+  /** Omit to read the ambient request context. */
+  orgId?: string | null;
+}
+
+export async function hasExplicitRecordingShare(
+  input: RecordingShareGrantInput,
+): Promise<boolean> {
+  if (input.role === "owner") return true;
+  if (input.visibility !== "public") return false;
+  if (!input.hasPassword && input.isAgentCaller) return true;
+
+  const userEmail = (
+    input.userEmail === undefined ? getRequestUserEmail() : input.userEmail
+  )
+    ?.trim()
+    .toLowerCase();
+  const orgId = input.orgId === undefined ? getRequestOrgId() : input.orgId;
+
+  const principals = [];
+  if (userEmail) {
+    principals.push(
+      and(
+        eq(schema.recordingShares.principalType, "user"),
+        sql`lower(${schema.recordingShares.principalId}) = ${userEmail}`,
+      ),
+    );
+  }
+  if (orgId) {
+    principals.push(
+      and(
+        eq(schema.recordingShares.principalType, "org"),
+        eq(schema.recordingShares.principalId, orgId),
+      ),
+    );
+  }
+  if (principals.length === 0) return false;
+
+  const [share] = await getDb()
+    .select({ id: schema.recordingShares.id })
+    .from(schema.recordingShares)
+    .where(
+      and(
+        eq(schema.recordingShares.resourceId, input.recordingId),
+        or(...principals),
+      ),
+    )
+    .limit(1);
+  return Boolean(share);
+}

package/corpus/templates/clips/server/lib/recordings.ts

@@ -1,11 +1,11 @@
 import { readAppState } from "@agent-native/core/application-state";
-import { orgMembers } from "@agent-native/core/org";
+import { implicitServiceOrgRole, orgMembers } from "@agent-native/core/org";
 import { getSession } from "@agent-native/core/server";
 import {
   getRequestUserEmail,
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
-import { and, desc, eq, sql } from "drizzle-orm";
+import { and, count, desc, eq, sql } from "drizzle-orm";
 import { HTTPError, type H3Event } from "h3";
 
 import { getDb, schema } from "../db/index.js";
@@ -142,7 +142,11 @@ export async function getOrganizationRoleForEmail(
     // org_members table may not exist yet on first boot before migrations finish.
   }
 
-  return null;
+  return implicitServiceOrgRole({
+    email,
+    orgId: organizationId,
+    requestOrgId: getRequestOrgId(),
+  });
 }
 
 export async function requireOrganizationAccess(
@@ -362,3 +366,47 @@ export function shouldCountView(
 ): boolean {
   return totalWatchMs >= 5000 || completedPct >= 75 || scrubbedToEnd;
 }
+
+/**
+ * The single definition of a counted *viewer*: one `recording_viewers` row
+ * whose `countedView` flag is set. That is one row per person, so it answers
+ * "how many distinct viewers", not "how many views" — use
+ * `countRecordingViews` for the total. The in-memory twin is
+ * `isCountedViewerRow` in `shared/view-analytics.ts`.
+ */
+export function countedViewCondition() {
+  return eq(schema.recordingViewers.countedView, true);
+}
+
+/**
+ * Total views for a recording: one per counted view *session*, so a returning
+ * viewer's second visit counts again. Every surface that reports a view count
+ * (library list, insights, player, public share page) goes through this.
+ */
+export async function countRecordingViews(
+  recordingId: string,
+): Promise<number> {
+  const db = getDb();
+  const [viewerRow] = await db
+    .select({ value: count() })
+    .from(schema.recordingViewers)
+    .where(
+      and(
+        eq(schema.recordingViewers.recordingId, recordingId),
+        countedViewCondition(),
+      ),
+    );
+  const [viewLogRow] = await db
+    .select({ value: count() })
+    .from(schema.recordingViews)
+    .where(eq(schema.recordingViews.recordingId, recordingId));
+
+  // `recording_views` only exists from migration v46, so clips recorded before
+  // it have zero log rows. Floor the total at the counted-viewer count so those
+  // clips keep reporting a real number instead of dropping to 0, and so the
+  // total can never read below the unique-viewer count beside it.
+  return Math.max(
+    Number(viewLogRow?.value ?? 0),
+    Number(viewerRow?.value ?? 0),
+  );
+}

package/corpus/templates/clips/server/plugins/auth.ts

@@ -7,7 +7,7 @@ export default createAuthPlugin({
   // callback can handle both normal sign-in and the Calendar connect flow.
   mountGoogleOAuthRoutes: false,
   marketing: {
-    appName: "Agent-Native Clips",
+    appName: "Clips",
     tagline:
       "Your AI agent transcribes, summarizes, and searches everything you record alongside you.",
     features: [

package/corpus/templates/clips/server/plugins/db.ts

@@ -850,6 +850,37 @@ const migrations = runMigrations(
         `UPDATE organization_settings SET default_visibility = 'public' WHERE default_visibility = 'private' AND updated_at = created_at`,
       ].join("; "),
     },
+    // -------------------------------------------------------------------------
+    // Agent views — external agents polling a public clip's agent context,
+    // transcript, or frame APIs. Kept in its own table so human view counts
+    // cannot accidentally include agents.
+    // -------------------------------------------------------------------------
+    {
+      version: 51,
+      name: "recording-agent-views",
+      sql: [
+        `CREATE TABLE IF NOT EXISTS recording_agent_views (
+          id TEXT PRIMARY KEY,
+          recording_id TEXT NOT NULL,
+          agent_key TEXT NOT NULL,
+          agent_label TEXT,
+          view_session_id TEXT NOT NULL,
+          first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+          last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+          request_count INTEGER NOT NULL DEFAULT 1
+        )`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS recording_agent_views_session_unique_idx ON recording_agent_views (recording_id, agent_key, view_session_id)`,
+        `CREATE INDEX IF NOT EXISTS recording_agent_views_recording_idx ON recording_agent_views (recording_id, last_seen_at)`,
+      ].join("; "),
+    },
+    {
+      version: 52,
+      name: "recording-loom-import-claim-lease",
+      sql: [
+        `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS loom_import_claim_id TEXT`,
+        `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS loom_import_claimed_at TEXT`,
+      ].join("; "),
+    },
   ],
   { table: "clips_migrations" },
 );

package/corpus/templates/clips/server/routes/api/_agent-native-background/post-finalize-worker.post.ts

@@ -1,8 +1,10 @@
+import { randomUUID } from "node:crypto";
+
 import {
   runWithRequestContext,
   verifyScopedAgentAccessToken,
 } from "@agent-native/core/server";
-import { eq } from "drizzle-orm";
+import { and, eq, isNull, lt, or } from "drizzle-orm";
 import {
   defineEventHandler,
   readBody,
@@ -14,6 +16,7 @@ import { z } from "zod";
 import exportToBrain from "../../../../actions/export-to-brain.js";
 import finalizeRecording from "../../../../actions/finalize-recording.js";
 import { ensureRecordingSeekable } from "../../../../actions/lib/ensure-seekable-video.js";
+import { runLoomImportJob } from "../../../../actions/lib/loom-import-job.js";
 import requestTranscript from "../../../../actions/request-transcript.js";
 import { getDb, schema } from "../../../db/index.js";
 import {
@@ -24,13 +27,21 @@ import {
 
 const bodySchema = z.object({
   recordingId: z.string().min(1).max(200),
-  kind: z.enum(["media-ready", "seekable", "transcript", "brain-export"]),
+  kind: z.enum([
+    "media-ready",
+    "seekable",
+    "transcript",
+    "brain-export",
+    "loom-import",
+  ]),
   token: z.string().min(1),
   delayMs: z.number().int().min(0).max(30_000).optional(),
   retryAttempt: z.number().int().min(1).max(10).optional(),
   regenerate: z.boolean().optional(),
 });
 
+const LOOM_IMPORT_LEASE_MS = 30 * 60 * 1000;
+
 export default defineEventHandler(async (event: H3Event) => {
   const parsed = bodySchema.safeParse(await readBody(event).catch(() => null));
   if (!parsed.success) {
@@ -63,7 +74,8 @@ export default defineEventHandler(async (event: H3Event) => {
     setResponseStatus(event, 404);
     return { ok: false, error: "Recording not found" };
   }
-  const requiredStatus = kind === "media-ready" ? "processing" : "ready";
+  const requiredStatus =
+    kind === "media-ready" || kind === "loom-import" ? "processing" : "ready";
   if (recording.status !== requiredStatus) {
     return {
       ok: true,
@@ -112,6 +124,47 @@ export default defineEventHandler(async (event: H3Event) => {
         return { ok: true, kind, result };
       }
 
+      if (kind === "loom-import") {
+        const claimId = randomUUID();
+        const claimStartedAt = new Date().toISOString();
+        const claimExpiredBefore = new Date(
+          Date.now() - LOOM_IMPORT_LEASE_MS,
+        ).toISOString();
+        const [claimed] = await getDb()
+          .update(schema.recordings)
+          .set({
+            loomImportClaimId: claimId,
+            loomImportClaimedAt: claimStartedAt,
+          })
+          .where(
+            and(
+              eq(schema.recordings.id, recordingId),
+              eq(schema.recordings.status, "processing"),
+              or(
+                isNull(schema.recordings.loomImportClaimId),
+                isNull(schema.recordings.loomImportClaimedAt),
+                lt(schema.recordings.loomImportClaimedAt, claimExpiredBefore),
+              ),
+            ),
+          )
+          .returning({ id: schema.recordings.id });
+        if (!claimed) {
+          return {
+            ok: true,
+            recordingId,
+            kind,
+            skipped: true,
+            reason: "loom-import-already-running",
+          };
+        }
+        const result = await runLoomImportJob({
+          recordingId,
+          ownerEmail: recording.ownerEmail,
+          claimId,
+        });
+        return { ok: true, kind, result };
+      }
+
       if (kind === "brain-export") {
         const result = await exportToBrain.run({
           recordingId,

package/corpus/templates/clips/server/routes/api/public-recording.get.ts

@@ -46,8 +46,16 @@ import { isMediaVerificationPending } from "../../lib/media-verification-state.j
 import { resolvePlayerThumbnailUrl } from "../../lib/player-thumbnail-url.js";
 import { resolvePlayerVideoUrl } from "../../lib/player-video-url.js";
 import {
+  canOpenDirectRecordingPage,
+  isRecordingExpired,
+  type RecordingPageAccessRole,
+} from "../../lib/recording-page-access.js";
+import { hasExplicitRecordingShare } from "../../lib/recording-share-grant.js";
+import {
+  countRecordingViews,
   getOrganizationRoleForEmail,
   parseSpaceIds,
+  type RecordingVisibility,
 } from "../../lib/recordings.js";
 import { verifySharePassword } from "../../lib/share-password.js";
 
@@ -258,12 +266,10 @@ export default defineEventHandler(async (event) => {
   }
 
   // Expiry check
-  if (rec.expiresAt) {
-    const expires = new Date(rec.expiresAt).getTime();
-    if (isFinite(expires) && expires < Date.now()) {
-      setResponseStatus(event, 410);
-      return { error: "Recording has expired", expired: true };
-    }
+  const recordingExpired = isRecordingExpired(rec.expiresAt);
+  if (recordingExpired) {
+    setResponseStatus(event, 410);
+    return { error: "Recording has expired", expired: true };
   }
 
   // Password check
@@ -405,6 +411,32 @@ export default defineEventHandler(async (event) => {
     recordingStatus: rec.status,
   });
 
+  const viewCount = await countRecordingViews(recordingId);
+
+  const viewerRole =
+    viewerAccess?.role ?? (viewerIsOrgMember ? "viewer" : null);
+  // Mirrors the gate in `get-recording-player-data` exactly: the share page
+  // auto-redirects on this flag, so a false positive bounces the viewer
+  // between /share/:id and /r/:id forever. Only a resolved access role can
+  // open the direct page — the org-member fallback above is a display role,
+  // not access the player action would grant.
+  const canOpenDashboard =
+    Boolean(session?.email) && viewerAccess && !recordingExpired
+      ? canOpenDirectRecordingPage({
+          role: viewerAccess.role as RecordingPageAccessRole,
+          visibility: rec.visibility as RecordingVisibility,
+          hasPassword: Boolean(rec.password),
+          hasExplicitShare: await hasExplicitRecordingShare({
+            recordingId,
+            role: viewerAccess.role as RecordingPageAccessRole,
+            visibility: rec.visibility as RecordingVisibility,
+            hasPassword: Boolean(rec.password),
+            userEmail: session?.email ?? null,
+            orgId: session?.orgId ?? null,
+          }),
+        })
+      : false;
+
   return {
     recording: {
       id: rec.id,
@@ -439,6 +471,8 @@ export default defineEventHandler(async (event) => {
       updatedAt: rec.updatedAt,
     },
     agentContextUrl,
+    // Aggregate count only — never viewer identities on this public payload.
+    viewCount,
     transcript: transcript
       ? {
           status: transcriptPresentation.status,
@@ -479,17 +513,15 @@ export default defineEventHandler(async (event) => {
       placement: c.placement,
     })),
     viewer: session?.email
-      ? (() => {
-          const role =
-            viewerAccess?.role ?? (viewerIsOrgMember ? "viewer" : null);
-          const canEdit =
-            role === "owner" || role === "admin" || role === "editor";
-          return {
-            canEdit,
-            isOwner: role === "owner",
-            role: role ?? "viewer",
-          };
-        })()
+      ? {
+          canEdit:
+            viewerRole === "owner" ||
+            viewerRole === "admin" ||
+            viewerRole === "editor",
+          isOwner: viewerRole === "owner",
+          role: viewerRole ?? "viewer",
+          canOpenDashboard,
+        }
       : null,
   };
 });

package/corpus/templates/clips/shared/recording-link.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical share URL for a recording, shared by every surface that hands a
+ * user a link to paste: the web recorder, the desktop app, and the Chrome
+ * extension.
+ *
+ * `/share/<id>` is the public viewer page — SSR-rendered, password/expiry
+ * aware, and the shape Slack unfurls. `/r/<id>` is the owner dashboard: it
+ * renders client-side only and shows a sign-in prompt to a recipient. Copying
+ * `/r/<id>` produces a link that works for the author and looks broken to
+ * everyone they send it to, so share flows must build URLs from here rather
+ * than hand-rolling a path.
+ */
+import { withShareAttribution } from "./share-attribution";
+
+/** Public share path for a recording, relative to the app base path. */
+export function recordingSharePath(recordingId: string): string {
+  return `/share/${encodeURIComponent(recordingId)}`;
+}
+
+export interface RecordingShareUrlParams {
+  recordingId: string;
+  /** Absolute origin, e.g. `https://clips.example.com` or a desktop serverUrl. */
+  origin: string;
+  /** App base path when the app is mounted under a subpath. */
+  basePath?: string;
+  /** Non-PII owner id for viral attribution. Omitted when unknown. */
+  ownerId?: string | null;
+}
+
+/**
+ * Absolute, ready-to-paste share URL for a recording, carrying the same
+ * attribution params the Share dialog mints so auto-copied links measure the
+ * signup funnel identically.
+ */
+export function buildRecordingShareUrl(
+  params: RecordingShareUrlParams,
+): string {
+  const { recordingId, origin, basePath = "", ownerId } = params;
+  const trimmedOrigin = origin.trim().replace(/\/+$/, "");
+  const trimmedBase = basePath.trim().replace(/\/+$/, "");
+  const url = `${trimmedOrigin}${trimmedBase}${recordingSharePath(recordingId)}`;
+  return withShareAttribution(url, ownerId);
+}

package/corpus/templates/clips/shared/share-attribution.ts

@@ -21,6 +21,10 @@ export const CLIP_SHARE_REF = "clip_share";
 export const REF_PARAM = "ref";
 export const VIA_PARAM = "via";
 
+/** Marker used only when `/r/:id` falls back to the public share route. */
+export const DASHBOARD_REDIRECT_PARAM = "dashboard_redirect";
+export const DASHBOARD_REDIRECT_VALUE = "1";
+
 /**
  * Append `ref=clip_share` (and `via=<ownerId>` when a non-PII owner id is
  * known) to an absolute share/embed URL, preserving any existing query params.