@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/notifications/access-request-copy.ts

@@ -5,74 +5,105 @@
  * post-generation enforcement to ensure required directives always appear.
  */
 
-// ── Local string utilities ──────────────────────────────────────────────────
-//
-// Tiny helpers duplicated from copy-composer to keep this module
-// dependency-free (avoiding a circular import with copy-composer, which
-// imports access-request helpers for its templates).
-
-function str(value: unknown, fallback: string): string {
-  if (typeof value === "string" && value.length > 0) return value;
-  return fallback;
+import { z } from "zod";
+
+import { buildApprovalCardBlocks } from "./approval-card-builder.js";
+import {
+  nonEmpty,
+  sanitizeIdentityField,
+  sanitizeMessagePreview,
+} from "./notification-utils.js";
+
+// ── Zod schema for access-request payloads ──────────────────────────────────
+
+/** Accepts string, null, or any other type — coerces non-strings to undefined. */
+const optStr = z
+  .unknown()
+  .transform((v) => (typeof v === "string" ? v : undefined));
+
+/** Accepts boolean or any other type — coerces non-true to undefined. */
+const optBool = z.unknown().transform((v) => (v === true ? true : undefined));
+
+export const AccessRequestPayloadSchema = z.object({
+  requestId: optStr,
+  requestCode: optStr,
+  sourceChannel: optStr,
+  conversationExternalId: optStr,
+  actorExternalId: optStr,
+  actorDisplayName: optStr,
+  actorUsername: optStr,
+  senderIdentifier: optStr,
+  guardianBindingChannel: optStr,
+  guardianResolutionSource: optStr,
+  previousMemberStatus: optStr,
+  messagePreview: optStr,
+  isStranger: optBool,
+  isRestricted: optBool,
+  messageTs: optStr,
+});
+
+export type ParsedAccessRequestPayload = z.infer<
+  typeof AccessRequestPayloadSchema
+>;
+
+export function parseAccessRequestPayload(
+  payload: Record<string, unknown>,
+): ParsedAccessRequestPayload {
+  return AccessRequestPayloadSchema.parse(payload);
 }
 
-function nonEmpty(value: string | undefined): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
+// ── Warnings ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a list of human-readable warning strings for an access request.
+ * Used by both the Slack Block Kit card and the plain-text contract.
+ */
+export function buildAccessRequestWarnings(
+  p: ParsedAccessRequestPayload,
+): string[] {
+  const warnings: string[] = [];
+  if (p.previousMemberStatus === "revoked") {
+    warnings.push("This user was previously revoked.");
+  }
+  if (p.isStranger) {
+    warnings.push("External Slack user (not in this workspace).");
+  }
+  if (p.isRestricted) {
+    warnings.push("Guest / restricted account.");
+  }
+  return warnings;
 }
 
-// ── Identity sanitization ───────────────────────────────────────────────────
+// ── Slack conversation helpers ───────────────────────────────────────────────
 
-const IDENTITY_FIELD_MAX_LENGTH = 120;
+/** Slack DM conversation IDs start with `D` followed by alphanumeric chars. */
+export function isSlackDmConversation(conversationExternalId: string): boolean {
+  return /^D[A-Z0-9]+$/i.test(conversationExternalId);
+}
 
 /**
- * Sanitize an untrusted identity field for inclusion in notification copy.
- *
- * - Strips control characters (U+0000–U+001F, U+007F–U+009F) and newlines.
- * - Clamps to IDENTITY_FIELD_MAX_LENGTH characters.
- * - Wraps in quotes to neutralize instruction-like payload text.
+ * Build a Slack message permalink from a channel ID and message timestamp.
+ * Format: https://slack.com/archives/{channelId}/p{ts_without_dot}
+ * Workspace-agnostic — resolves for any authenticated Slack viewer.
  */
-export function sanitizeIdentityField(value: string): string {
-  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
-  const clamped =
-    stripped.length > IDENTITY_FIELD_MAX_LENGTH
-      ? stripped.slice(0, IDENTITY_FIELD_MAX_LENGTH) + "…"
-      : stripped;
-  return clamped;
+export function buildSlackMessagePermalink(
+  conversationExternalId: string,
+  messageTs: string,
+): string {
+  return `https://slack.com/archives/${conversationExternalId}/p${messageTs.replace(".", "")}`;
 }
 
-export function buildAccessRequestIdentityLine(
-  payload: Record<string, unknown>,
-): string {
-  const requester = sanitizeIdentityField(
-    str(payload.senderIdentifier, "Someone"),
-  );
-  const sourceChannel =
-    typeof payload.sourceChannel === "string"
-      ? payload.sourceChannel
-      : undefined;
-  const callerName = nonEmpty(
-    typeof payload.actorDisplayName === "string"
-      ? payload.actorDisplayName
-      : undefined,
-  );
-  const actorUsername = nonEmpty(
-    typeof payload.actorUsername === "string"
-      ? payload.actorUsername
-      : undefined,
-  );
-  const actorExternalId = nonEmpty(
-    typeof payload.actorExternalId === "string"
-      ? payload.actorExternalId
-      : undefined,
-  );
+/** Internal typed implementation — avoids re-parsing when called from
+ *  buildAccessRequestContractText which has already parsed the payload. */
+function buildIdentityLineFromParsed(p: ParsedAccessRequestPayload): string {
+  const requester = sanitizeIdentityField(p.senderIdentifier || "Someone");
+  const callerName = nonEmpty(p.actorDisplayName);
+  const actorUsername = nonEmpty(p.actorUsername);
+  const actorExternalId = nonEmpty(p.actorExternalId);
 
-  if (sourceChannel === "phone" && callerName) {
+  if (p.sourceChannel === "phone" && callerName) {
     const safeName = sanitizeIdentityField(callerName);
-    const safeId = sanitizeIdentityField(
-      str(payload.actorExternalId, requester),
-    );
+    const safeId = sanitizeIdentityField(p.actorExternalId || requester);
     return `${safeName} (${safeId}) is calling and requesting access to the assistant.`;
   }
 
@@ -84,11 +115,10 @@ export function buildAccessRequestIdentityLine(
   const sanitizedExternalId = actorExternalId
     ? sanitizeIdentityField(actorExternalId)
     : undefined;
-  // When the requester is a raw Slack user ID (e.g. the fallback path in
-  // access-request-helper sets senderIdentifier to the raw actorExternalId),
-  // format it as a Slack mention so it renders as a clickable display name.
+  // When the requester is a raw Slack user ID, format it as a Slack mention
+  // so Slack auto-renders it as a clickable display name.
   const formattedRequester =
-    sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(requester)
+    p.sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(requester)
       ? `<@${requester}>`
       : requester;
   const parts = [formattedRequester];
@@ -100,39 +130,23 @@ export function buildAccessRequestIdentityLine(
     sanitizedExternalId !== requester &&
     sanitizedExternalId !== sanitizedUsername
   ) {
-    // For Slack, use the <@U...> mention format so Slack auto-renders
-    // the user ID as a clickable display name.
     const formattedId =
-      sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(sanitizedExternalId)
+      p.sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(sanitizedExternalId)
         ? `<@${sanitizedExternalId}>`
         : `[${sanitizedExternalId}]`;
     parts.push(formattedId);
   }
-  if (sourceChannel) {
-    parts.push(`via ${sourceChannel}`);
+  if (p.sourceChannel) {
+    parts.push(`via ${p.sourceChannel}`);
   }
 
   return `${parts.join(" ")} is requesting access to the assistant.`;
 }
 
-// ── Message preview ─────────────────────────────────────────────────────────
-
-export const MESSAGE_PREVIEW_MAX_LENGTH = 200;
-
-/**
- * Sanitize an untrusted message preview for inclusion in notification copy.
- *
- * Like {@link sanitizeIdentityField} but uses the higher
- * MESSAGE_PREVIEW_MAX_LENGTH limit (200 chars) instead of the identity
- * field limit (120 chars).
- */
-export function sanitizeMessagePreview(value: string): string {
-  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
-  const clamped =
-    stripped.length > MESSAGE_PREVIEW_MAX_LENGTH
-      ? stripped.slice(0, MESSAGE_PREVIEW_MAX_LENGTH) + "…"
-      : stripped;
-  return clamped;
+export function buildAccessRequestIdentityLine(
+  payload: Record<string, unknown>,
+): string {
+  return buildIdentityLineFromParsed(parseAccessRequestPayload(payload));
 }
 
 /**
@@ -142,13 +156,10 @@ export function sanitizeMessagePreview(value: string): string {
  *
  * Returns `undefined` when no usable preview is available.
  */
-function buildAccessRequestMessagePreview(
-  payload: Record<string, unknown>,
+function buildMessagePreviewFromParsed(
+  p: ParsedAccessRequestPayload,
 ): string | undefined {
-  const raw =
-    typeof payload.messagePreview === "string"
-      ? payload.messagePreview
-      : undefined;
+  const raw = p.messagePreview;
   if (!raw) return undefined;
 
   const sanitized = sanitizeMessagePreview(raw);
@@ -252,32 +263,35 @@ export function hasInviteFlowDirective(text: string | undefined): boolean {
 export function buildAccessRequestContractText(
   payload: Record<string, unknown>,
 ): string {
-  const requestCode = nonEmpty(
-    typeof payload.requestCode === "string" ? payload.requestCode : undefined,
-  );
-  const previousMemberStatus =
-    typeof payload.previousMemberStatus === "string"
-      ? payload.previousMemberStatus
-      : undefined;
-
-  const guardianResolutionSource =
-    typeof payload.guardianResolutionSource === "string"
-      ? payload.guardianResolutionSource
-      : undefined;
-  const sourceChannel =
-    typeof payload.sourceChannel === "string"
-      ? payload.sourceChannel
-      : undefined;
+  const p = parseAccessRequestPayload(payload);
+  const requestCode = nonEmpty(p.requestCode);
 
   const lines: string[] = [];
-  lines.push(buildAccessRequestIdentityLine(payload));
-  const preview = buildAccessRequestMessagePreview(payload);
+  lines.push(buildIdentityLineFromParsed(p));
+
+  const preview = buildMessagePreviewFromParsed(p);
   if (preview) {
     lines.push(preview);
   }
-  if (previousMemberStatus === "revoked") {
-    lines.push("Note: this user was previously revoked.");
+
+  // Unified warnings: revoked status + trust signals.
+  for (const warning of buildAccessRequestWarnings(p)) {
+    lines.push(`Note: ${warning.charAt(0).toLowerCase()}${warning.slice(1)}`);
   }
+
+  // Conversation context: source channel + permalink when available.
+  if (p.sourceChannel === "slack" && p.conversationExternalId) {
+    const permalink = p.messageTs
+      ? buildSlackMessagePermalink(p.conversationExternalId, p.messageTs)
+      : undefined;
+    const isDm = isSlackDmConversation(p.conversationExternalId);
+    const channelLabel = isDm ? "Direct message" : p.conversationExternalId;
+    const source = permalink
+      ? `Source: Slack — ${channelLabel} (${permalink})`
+      : `Source: Slack — ${channelLabel}`;
+    lines.push(source);
+  }
+
   if (requestCode) {
     const code = requestCode.toUpperCase();
     lines.push(
@@ -285,14 +299,87 @@ export function buildAccessRequestContractText(
     );
   }
   lines.push(buildAccessRequestInviteDirective());
+
   if (
-    (guardianResolutionSource === "vellum-anchor" ||
-      guardianResolutionSource === "none") &&
-    sourceChannel
+    (p.guardianResolutionSource === "vellum-anchor" ||
+      p.guardianResolutionSource === "none") &&
+    p.sourceChannel
   ) {
     lines.push(
-      `Note: You haven't verified your identity on ${sourceChannel} yet. If this was you trying to message your assistant, say "help me verify as guardian on ${sourceChannel}" to set up direct access.`,
+      `Note: You haven't verified your identity on ${p.sourceChannel} yet. If this was you trying to message your assistant, say "help me verify as guardian on ${p.sourceChannel}" to set up direct access.`,
     );
   }
   return lines.join("\n");
 }
+
+// ── Seed content blocks (Surface-based rendering) ───────────────────────────
+
+/**
+ * Build structured content blocks for an access request notification seed
+ * message. Produces a `ui_surface` card block that the web/macOS/iOS apps
+ * render as an interactive card via `SurfaceRouter → CardSurface`, plus a
+ * plain-text fallback block for search, CLI display, and backward-compatible
+ * clients that don't support surfaces.
+ */
+export function buildAccessRequestSeedContentBlocks(
+  payload: Record<string, unknown>,
+): unknown[] {
+  const p = parseAccessRequestPayload(payload);
+
+  const rawName = nonEmpty(p.actorDisplayName) ?? nonEmpty(p.senderIdentifier);
+  const displayName = rawName ? sanitizeIdentityField(rawName) : "Someone";
+
+  const metadata: Array<{ label: string; value: string }> = [];
+
+  if (p.actorUsername) {
+    metadata.push({
+      label: "Username",
+      value: `@${sanitizeIdentityField(p.actorUsername)}`,
+    });
+  }
+
+  if (p.sourceChannel === "slack" && p.conversationExternalId) {
+    const isDm = isSlackDmConversation(p.conversationExternalId);
+    metadata.push({
+      label: "Source",
+      value: isDm
+        ? "Slack — Direct message"
+        : `Slack — #${p.conversationExternalId}`,
+    });
+  } else if (p.sourceChannel) {
+    metadata.push({ label: "Source", value: p.sourceChannel });
+  }
+
+  const warnings = buildAccessRequestWarnings(p);
+  const bodyParts: string[] = [];
+
+  if (p.messagePreview) {
+    bodyParts.push(`> "${sanitizeMessagePreview(p.messagePreview)}"`);
+  }
+  for (const w of warnings) {
+    bodyParts.push(`⚠️ ${w}`);
+  }
+  if (p.sourceChannel === "slack" && p.conversationExternalId && p.messageTs) {
+    const permalink = buildSlackMessagePermalink(
+      p.conversationExternalId,
+      p.messageTs,
+    );
+    bodyParts.push(`[View message](${permalink})`);
+  }
+
+  const body =
+    bodyParts.length > 0
+      ? bodyParts.join("\n\n")
+      : "No additional context available.";
+
+  return buildApprovalCardBlocks({
+    surfaceIdPrefix: "access-request",
+    cardTitle: "Access Request",
+    requesterName: displayName,
+    subtitle: "Requesting access to the assistant",
+    body,
+    metadata,
+    requestId: p.requestId,
+    fallbackText: buildAccessRequestContractText(payload),
+  });
+}