@agent-native/core 0.128.0 → 0.128.2

package/corpus/templates/clips/server/lib/transactional-email-templates.ts

@@ -0,0 +1,270 @@
+import {
+  emailStrong,
+  getAppProductionUrl,
+  renderEmail,
+  sendEmail,
+} from "@agent-native/core/server";
+
+const CLIPS_BRAND_NAME = "Clips";
+const EMAIL_SEND_TIMEOUT_MS = 60_000;
+const FRIENDLY_REPLY_TO = "hello@agent-native.com";
+const UNTITLED_CLIP = "Untitled Clip";
+
+interface TransactionalEmailBase {
+  to: string;
+}
+
+export type ClipsTransactionalEmailInput =
+  | (TransactionalEmailBase & {
+      kind: "first-view";
+      recordingId: string;
+      title?: string | null;
+      viewerEmail?: string | null;
+    })
+  | (TransactionalEmailBase & {
+      kind: "unviewed-reminder";
+      recordingId: string;
+      title?: string | null;
+      senderEmail?: string | null;
+      senderName?: string | null;
+      brandLogoUrl?: string | null;
+    })
+  | (TransactionalEmailBase & {
+      kind: "first-import";
+      recordingId: string;
+      title?: string | null;
+    })
+  | (TransactionalEmailBase & {
+      kind: "two-clips";
+      generatedSummary?: string | null;
+    });
+
+export interface ClipsTransactionalEmailRenderOptions {
+  appUrl: string;
+  appBasePath?: string;
+}
+
+export interface RenderedClipsTransactionalEmail {
+  subject: string;
+  html: string;
+  text: string;
+}
+
+function singleLine(value: string | null | undefined): string {
+  return (value ?? "").replace(/[\r\n]+/g, " ").trim();
+}
+
+function clipTitle(value: string | null | undefined): string {
+  return singleLine(value) || UNTITLED_CLIP;
+}
+
+export function normalizeEmailDisplayName(
+  value: string | null | undefined,
+  fallback: string,
+): string {
+  const email = singleLine(value);
+  const match = /^([A-Za-z]+(?:[._-][A-Za-z]+)*)@[^\s@]+$/.exec(email);
+  if (!match) return email || fallback;
+
+  return match[1]
+    .split(/[._-]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function normalizeBasePath(value: string | undefined): string {
+  const normalized = singleLine(value).replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalized ? `/${normalized}` : "";
+}
+
+function appUrlForPath(
+  path: string,
+  { appUrl, appBasePath }: ClipsTransactionalEmailRenderOptions,
+): string {
+  const url = new URL(appUrl);
+  let basePath = normalizeBasePath(url.pathname);
+  const configuredBasePath = normalizeBasePath(appBasePath);
+
+  if (
+    configuredBasePath &&
+    basePath !== configuredBasePath &&
+    !basePath.endsWith(configuredBasePath)
+  ) {
+    basePath = `${basePath}${configuredBasePath}`;
+  }
+
+  return new URL(`${basePath}${path}`, url.origin).toString();
+}
+
+function clipUrl(
+  recordingId: string,
+  options: ClipsTransactionalEmailRenderOptions,
+): string {
+  return appUrlForPath(`/r/${encodeURIComponent(recordingId)}`, options);
+}
+
+function recordUrl(options: ClipsTransactionalEmailRenderOptions): string {
+  return appUrlForPath("/record", options);
+}
+
+function resolveBrandLogoUrl(
+  value: string | null | undefined,
+  options: ClipsTransactionalEmailRenderOptions,
+): string | undefined {
+  const candidate = singleLine(value);
+  if (!candidate) return undefined;
+  try {
+    const url = new URL(candidate, options.appUrl);
+    return url.protocol === "https:" || url.protocol === "http:"
+      ? url.toString()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function validReplyTo(value: string | null | undefined): string | undefined {
+  const candidate = singleLine(value).toLowerCase();
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(candidate) ? candidate : undefined;
+}
+
+export function renderClipsTransactionalEmail(
+  input: ClipsTransactionalEmailInput,
+  options: ClipsTransactionalEmailRenderOptions,
+): RenderedClipsTransactionalEmail {
+  const title = input.kind === "two-clips" ? undefined : clipTitle(input.title);
+
+  switch (input.kind) {
+    case "first-view": {
+      const viewer = normalizeEmailDisplayName(input.viewerEmail, "Someone");
+      const subject = `Your Clip “${title}” got its first view`;
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        preheader: subject,
+        heading: "Someone watched your Clip",
+        paragraphs: [
+          `${emailStrong(viewer)} registered the first view of ${emailStrong(title!)}.`,
+          "Clips tracks advanced analytics on your viewers' activity, and can even tell you whether your recipient took AI actions with your link. Come back to Clips to view analytics, or configure Clips AI to take agentic actions on your behalf.",
+        ],
+        cta: {
+          label: "See Clip activity",
+          url: clipUrl(input.recordingId, options),
+        },
+        footer:
+          "You received this one-time note because this Clip got its first registered view.",
+      });
+      return { subject, ...rendered };
+    }
+
+    case "unviewed-reminder": {
+      const sender =
+        singleLine(input.senderName) ||
+        normalizeEmailDisplayName(input.senderEmail, "Someone");
+      const subject = `Still need to watch “${title}”?`;
+      const url = clipUrl(input.recordingId, options);
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        brandLogoUrl: resolveBrandLogoUrl(input.brandLogoUrl, options),
+        preheader: subject,
+        heading: `${sender} shared a Clip with you`,
+        paragraphs: [
+          `${emailStrong(title!)} is waiting whenever you have a moment.`,
+        ],
+        linkBlock: {
+          intro:
+            "Don't have a moment to spare? Share the below link with your own AI agent and ask it for a summary:",
+          url,
+        },
+        cta: {
+          label: "Watch the Clip Manually",
+          url,
+        },
+        footer: `You received this reminder because ${sender} shared this Clip with you two days ago.`,
+      });
+      return { subject, ...rendered };
+    }
+
+    case "first-import": {
+      const subject = "Your first imported video is now Agent-Native";
+      const url = clipUrl(input.recordingId, options);
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        preheader: subject,
+        heading: "Your video is ready for more than playback",
+        paragraphs: [
+          `${emailStrong(title!)} is now an Agent-Native Clip.`,
+          "Its speech and on-screen visuals are available as agent-readable context for summaries, exact-moment lookup, tickets, emails, and follow-up work.",
+        ],
+        cta: {
+          label: "Open your Agent-Native Clip",
+          url,
+        },
+        linkBlock: {
+          intro: "Or just feed this link to your own AI agent:",
+          url,
+          placement: "after-cta",
+        },
+        footer:
+          "You received this one-time note because your first imported video is ready.",
+      });
+      return { subject, ...rendered };
+    }
+
+    case "two-clips": {
+      const summary =
+        singleLine(input.generatedSummary) ||
+        "Two people shared Clips with you, giving you a quick look at what Agent-Native video can do.";
+      const subject = "You've received two Clips. What would you create?";
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        preheader: subject,
+        heading: "You’ve received two Agent-Native Clips",
+        paragraphs: [
+          emailStrong(summary),
+          "Clips are screen recordings that are friendly for both human viewing and AI agent use. What would you create with yours?",
+        ],
+        cta: {
+          label: "Record an Agent-Native Clip",
+          url: recordUrl(options),
+        },
+        footer:
+          "This one-time note was sent after two Clips were shared with you.",
+      });
+      return { subject, ...rendered };
+    }
+  }
+}
+
+export async function sendClipsTransactionalEmail(
+  input: ClipsTransactionalEmailInput,
+): Promise<void> {
+  const rendered = renderClipsTransactionalEmail(input, {
+    appUrl: getAppProductionUrl(),
+    appBasePath: process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH,
+  });
+
+  const reminderSender =
+    input.kind === "unviewed-reminder"
+      ? singleLine(input.senderName) ||
+        normalizeEmailDisplayName(input.senderEmail, "Someone")
+      : undefined;
+
+  await sendEmail({
+    to: input.to,
+    subject: rendered.subject,
+    html: rendered.html,
+    text: rendered.text,
+    fromName: reminderSender
+      ? `${reminderSender} (via Agent-Native Clips)`
+      : undefined,
+    replyTo:
+      input.kind === "unviewed-reminder"
+        ? (validReplyTo(input.senderEmail) ?? FRIENDLY_REPLY_TO)
+        : FRIENDLY_REPLY_TO,
+    timeoutMs: EMAIL_SEND_TIMEOUT_MS,
+  });
+}
+
+export const renderTransactionalEmail = renderClipsTransactionalEmail;
+export const sendTransactionalEmail = sendClipsTransactionalEmail;
+export type TransactionalEmailInput = ClipsTransactionalEmailInput;

package/corpus/templates/clips/server/plugins/calendar-jobs.ts

@@ -11,6 +11,7 @@ import registerMediaVerificationJob from "../jobs/media-verification.js";
 import registerMeetingRemindersJob from "../jobs/meeting-reminders.js";
 import registerPollCalendarsJob from "../jobs/poll-calendars.js";
 import registerStaleMeetingSweeperJob from "../jobs/stale-meeting-sweeper.js";
+import registerTransactionalEmailsJob from "../jobs/transactional-emails.js";
 
 export default () => {
   // The reminder job registers the `meeting-reminder` event on every
@@ -22,4 +23,5 @@ export default () => {
   registerMediaVerificationJob();
   registerPollCalendarsJob();
   registerStaleMeetingSweeperJob();
+  registerTransactionalEmailsJob();
 };

package/corpus/templates/clips/server/routes/api/view-event.post.ts

@@ -33,11 +33,16 @@ import {
   runWithRequestContext,
 } from "@agent-native/core/server";
 import { resolveAccess } from "@agent-native/core/sharing";
-import { and, asc, eq, isNull, sql } from "drizzle-orm";
+import { and, asc, eq, isNull, not, or, sql } from "drizzle-orm";
 import { defineEventHandler, getRequestIP, setResponseStatus } from "h3";
 
 import { getDb, schema } from "../../db/index.js";
-import { nanoid, shouldCountView } from "../../lib/recordings.js";
+import {
+  nanoid,
+  ownerEmailMatches,
+  shouldCountView,
+} from "../../lib/recordings.js";
+import { transactionalEmailStore } from "../../lib/transactional-email-store.js";
 
 interface ViewEventBody {
   recordingId?: string;
@@ -408,6 +413,58 @@ export default defineEventHandler(async (event) => {
         return updated;
       });
 
+      const ownerEmail = rec.ownerEmail?.trim();
+      const transitionedToCountedView =
+        !existing.countedView && persisted.countedView;
+      const viewerIsOwner =
+        Boolean(viewerEmail && ownerEmail) &&
+        viewerEmail!.trim().toLowerCase() === ownerEmail!.toLowerCase();
+      if (transitionedToCountedView && ownerEmail && !viewerIsOwner) {
+        try {
+          const { enabledAt } = await transactionalEmailStore.ensureEnabledAt();
+          const [firstNonOwnerView] = await db
+            .select({
+              id: schema.recordingViews.id,
+              viewerKey: schema.recordingViews.viewerKey,
+              viewSessionId: schema.recordingViews.viewSessionId,
+              viewedAt: schema.recordingViews.viewedAt,
+            })
+            .from(schema.recordingViews)
+            .where(
+              and(
+                eq(schema.recordingViews.recordingId, recordingId),
+                or(
+                  isNull(schema.recordingViews.viewerEmail),
+                  not(
+                    ownerEmailMatches(
+                      schema.recordingViews.viewerEmail,
+                      ownerEmail,
+                    ),
+                  ),
+                ),
+              ),
+            )
+            .orderBy(
+              asc(schema.recordingViews.viewedAt),
+              asc(schema.recordingViews.id),
+            )
+            .limit(1);
+          const isCurrentCountedView =
+            firstNonOwnerView?.viewerKey === viewerKey &&
+            firstNonOwnerView.viewSessionId === countedViewSessionId;
+          if (isCurrentCountedView && firstNonOwnerView.viewedAt >= enabledAt) {
+            await transactionalEmailStore.enqueue(`first-view:${recordingId}`, {
+              type: "first-view",
+              recipient: ownerEmail,
+              recordingIds: [recordingId],
+              requestedBy: ownerEmail,
+            });
+          }
+        } catch (err) {
+          console.warn("[view-event] first-view email enqueue failed:", err);
+        }
+      }
+
       // Only broadcast a refresh signal on "meaningful" events to avoid
       // spamming the polling clients every 2s with watch-progress
       // heartbeats. Skip for anonymous viewers — application_state writes

package/corpus/templates/content/.agents/skills/document-editing/references/databases.md

@@ -161,8 +161,14 @@ adding fields without returning to the table header. The New property picker
 supports searching property types by label or machine name.
 
 In unconstrained table views, row drag handles can reorder database item
-pages through `move-database-item`; clear search, sort, and filters before
-manual reordering. Creating a database row returns the created item IDs and
+pages through `move-database-item`; pass both `databaseId` and `itemId` so the
+membership target is exact, and clear search, sort, and filters before manual
+reordering. Pinned and workspace-root sidebar rows also reorder exact
+memberships, but they are references: moving one never reparents, transfers,
+or changes access to the referenced page. Files sidebar Custom order is
+different again: persist it per user and per database view with
+`update-content-database-personal-view`, without changing the shared Files
+membership order. Creating a database row returns the created item IDs and
 opens the new row page in the side preview. Duplicating a database row
 returns the duplicate item IDs and opens the copied row in the side preview
 so users can continue editing the new page immediately, including from

package/corpus/templates/content/AGENTS.md

@@ -88,3 +88,11 @@ Every action carries its own schema, and the rest of the app-specific surface
 (comments, sharing, databases, Notion, local file sources such as
 `remove-local-file-source`) is registered too — use `tool-search` instead of
 scanning a table here.
+
+Sidebar ordering has two deliberately different meanings. Reordering Pinned or
+workspace roots moves the exact database membership identified by both
+`databaseId` and `itemId`; it never reparents or moves the referenced document.
+Files sidebar Custom order is a per-user database-view preference written with
+`update-content-database-personal-view`, so it must not change shared Files
+membership positions. Ordinary unconstrained database row reordering remains a
+shared database mutation through `move-database-item`.

package/corpus/templates/content/_gitignore

@@ -8,8 +8,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/content/actions/_content-database-personal-view.ts

@@ -42,6 +42,11 @@ export const filterSchema = z.object({
   parentFilterGroupId: z.string().optional(),
 });
 
+export const sidebarOrderSchema = z.object({
+  mode: z.enum(["custom", "last_edited", "name", "created"]),
+  itemIds: z.array(z.string()),
+});
+
 const personalViewOverridesFields = {
   activeViewId: z.string().optional(),
   views: z.array(
@@ -50,6 +55,7 @@ const personalViewOverridesFields = {
       sorts: z.array(sortSchema).default([]),
       filters: z.array(filterSchema).default([]),
       filterMode: z.enum(["and", "or"]).default("and"),
+      sidebarOrder: sidebarOrderSchema.optional(),
     }),
   ),
 };
@@ -59,6 +65,24 @@ export const personalViewOverridesSchema = z.object({
   ...personalViewOverridesFields,
 });
 
+export function normalizePersonalDatabaseViewOverrides(
+  overrides: z.infer<typeof personalViewOverridesSchema>,
+  validItemIds?: ReadonlySet<string>,
+) {
+  return {
+    ...overrides,
+    views: overrides.views.map((view) => ({
+      ...view,
+      sidebarOrder: {
+        mode: view.sidebarOrder?.mode ?? "custom",
+        itemIds: [...new Set(view.sidebarOrder?.itemIds ?? [])].filter(
+          (itemId) => !validItemIds || validItemIds.has(itemId),
+        ),
+      },
+    })),
+  };
+}
+
 const legacyPersonalViewOverridesSchema = z.object({
   version: z.literal(1),
   ...personalViewOverridesFields,
@@ -94,7 +118,8 @@ export async function readPersonalDatabaseViewOverrides(
     personalDatabaseViewSettingKey(databaseId),
   );
   const parsed = personalViewOverridesSchema.safeParse(stored);
-  if (parsed.success) return parsed.data;
+  if (parsed.success)
+    return normalizePersonalDatabaseViewOverrides(parsed.data);
 
   const legacy = legacyPersonalViewOverridesSchema.safeParse(stored);
   if (!legacy.success) return null;
@@ -103,7 +128,7 @@ export async function readPersonalDatabaseViewOverrides(
     .from(schema.contentDatabases)
     .where(eq(schema.contentDatabases.id, databaseId));
   const legacyParentKey = filesParentPropertyId(databaseId);
-  return {
+  return normalizePersonalDatabaseViewOverrides({
     ...legacy.data,
     version: PERSONAL_DATABASE_VIEW_OVERRIDES_VERSION,
     views: legacy.data.views.map((view) => ({
@@ -120,5 +145,5 @@ export async function readPersonalDatabaseViewOverrides(
             )
           : view.filters,
     })),
-  };
+  });
 }

package/corpus/templates/content/actions/_property-utils.ts

@@ -128,7 +128,31 @@ export async function getDatabaseMembershipForDocument(
 
 export async function resolvePropertyDatabaseForDocument(
   document: DocumentRow,
+  databaseId?: string,
+  role: "viewer" | "editor" | "admin" = "viewer",
 ): Promise<ContentDatabaseRow | null> {
+  if (databaseId) {
+    const database = await getDatabaseById(databaseId);
+    if (!database) throw new Error(`Database "${databaseId}" not found`);
+    await assertAccess("document", database.documentId, role);
+    if (database.documentId === document.id) return database;
+
+    const db = getDb();
+    const [membership] = await db
+      .select({ id: schema.contentDatabaseItems.id })
+      .from(schema.contentDatabaseItems)
+      .where(
+        and(
+          eq(schema.contentDatabaseItems.databaseId, databaseId),
+          eq(schema.contentDatabaseItems.documentId, document.id),
+        ),
+      );
+    if (!membership) {
+      throw new Error("Document is not part of this database.");
+    }
+    return database;
+  }
+
   const ownedDatabase = await getDatabaseForDocument(document.id);
   if (ownedDatabase) return ownedDatabase;
   const membership = await getDatabaseMembershipForDocument(document.id);
@@ -456,8 +480,14 @@ function normalizeStringList(value: unknown) {
     : [];
 }
 
-export async function listPropertiesForDocument(document: DocumentRow) {
-  const database = await resolvePropertyDatabaseForDocument(document);
+export async function listPropertiesForDocument(
+  document: DocumentRow,
+  databaseId?: string,
+) {
+  const database = await resolvePropertyDatabaseForDocument(
+    document,
+    databaseId,
+  );
   if (!database) return [];
   // Read path: PURE read. Seeding the primary Blocks field happens at create
   // time and via the one-time startup repair (repairUnseededBlocksFields) —

package/corpus/templates/content/actions/configure-document-property.ts

@@ -35,6 +35,12 @@ export default defineAction({
     documentId: z
       .string()
       .describe("Document ID used to scope the property workspace"),
+    databaseId: z
+      .string()
+      .optional()
+      .describe(
+        "Database ID that owns the property; omit only for context-free entry points",
+      ),
     name: z.string().min(1).describe("Property name"),
     description: z
       .string()
@@ -96,7 +102,11 @@ export default defineAction({
     const name = args.name.trim();
     const type = args.type as DocumentPropertyType;
     let optionsJson = optionsForNewProperty(type, args.options as any);
-    const database = await resolvePropertyDatabaseForDocument(document);
+    const database = await resolvePropertyDatabaseForDocument(
+      document,
+      args.databaseId,
+      "editor",
+    );
     if (!database) {
       throw new Error(
         "Properties belong to databases. Create or open a database before adding properties.",
@@ -226,7 +236,7 @@ export default defineAction({
     return {
       documentId: args.documentId,
       databaseId: database.id,
-      properties: await listPropertiesForDocument(document),
+      properties: await listPropertiesForDocument(document, database.id),
     };
   },
 });

package/corpus/templates/content/actions/delete-document-property.ts

@@ -21,13 +21,23 @@ export default defineAction({
     "Delete a Notion-style property definition and its stored document values.",
   schema: z.object({
     documentId: z.string().describe("Document ID used to scope access"),
+    databaseId: z
+      .string()
+      .optional()
+      .describe(
+        "Database ID that owns the property; omit only for context-free entry points",
+      ),
     propertyId: z.string().describe("Property definition ID to delete"),
   }),
-  run: async ({ documentId, propertyId }) => {
+  run: async ({ documentId, databaseId, propertyId }) => {
     const access = await assertAccess("document", documentId, "editor");
     const document = access.resource;
     const db = getDb();
-    const database = await resolvePropertyDatabaseForDocument(document);
+    const database = await resolvePropertyDatabaseForDocument(
+      document,
+      databaseId,
+      "editor",
+    );
     if (!database) throw new Error("Document is not part of a database.");
 
     const [definition] = await db
@@ -129,7 +139,7 @@ export default defineAction({
     return {
       documentId,
       databaseId: database.id,
-      properties: await listPropertiesForDocument(document),
+      properties: await listPropertiesForDocument(document, database.id),
     };
   },
 });

package/corpus/templates/content/actions/duplicate-document-property.ts

@@ -25,13 +25,23 @@ export default defineAction({
     "Duplicate a Notion-style property definition and copy its stored values.",
   schema: z.object({
     documentId: z.string().describe("Document ID used to scope access"),
+    databaseId: z
+      .string()
+      .optional()
+      .describe(
+        "Database ID that owns the property; omit only for context-free entry points",
+      ),
     propertyId: z.string().describe("Property definition ID to duplicate"),
   }),
-  run: async ({ documentId, propertyId }) => {
+  run: async ({ documentId, databaseId, propertyId }) => {
     const access = await assertAccess("document", documentId, "editor");
     const document = access.resource;
     const db = getDb();
-    const database = await resolvePropertyDatabaseForDocument(document);
+    const database = await resolvePropertyDatabaseForDocument(
+      document,
+      databaseId,
+      "editor",
+    );
     if (!database) throw new Error("Document is not part of a database.");
 
     const [definition] = await db
@@ -123,7 +133,7 @@ export default defineAction({
     return {
       documentId,
       databaseId: database.id,
-      properties: await listPropertiesForDocument(document),
+      properties: await listPropertiesForDocument(document, database.id),
     };
   },
 });

package/corpus/templates/content/actions/list-content-spaces.ts

@@ -1,6 +1,6 @@
 import { defineAction } from "@agent-native/core";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
-import { and, eq, inArray, isNull } from "drizzle-orm";
+import { and, asc, eq, inArray, isNull } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -65,7 +65,8 @@ export default defineAction({
           ),
           isNull(schema.contentSpaces.archivedAt),
         ),
-      );
+      )
+      .orderBy(asc(schema.contentDatabaseItems.position));
     const filesDatabaseIds = rows.map((row) => row.space.filesDatabaseId);
     const databaseIds = [...filesDatabaseIds, favoritesIds.databaseId];
     const filesDatabases = databaseIds.length
@@ -90,6 +91,7 @@ export default defineAction({
       role: string;
       catalogItemId: string;
       catalogDocumentId: string;
+      catalogPosition: number;
     }>;
     for (const row of rows) {
       if (
@@ -117,6 +119,7 @@ export default defineAction({
         role,
         catalogItemId: row.mapping.databaseItemId,
         catalogDocumentId: row.mapping.documentId,
+        catalogPosition: row.item.position,
       });
     }
     return {