@opengeni/contracts 3.1.0-canary.2 → 3.1.2

package/src/session-message-search.ts

@@ -0,0 +1,61 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Literal Unicode case-insensitive search, without trimming or normalization. */
+export const SessionMessageSearchRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      query: z.string().min(1).max(200),
+      sessionId: z.string().uuid().optional(),
+      groupBy: z.literal("session").optional(),
+      archiveStatus: z.enum(["active", "archived", "all"]).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      cursor: z.string().min(1).max(4096).optional(),
+    })
+    .strict()
+    .refine((request) => !request.groupBy || !request.sessionId, {
+      message: "groupBy=session is only supported for workspace search without sessionId",
+      path: ["groupBy"],
+    }),
+);
+export type SessionMessageSearchRequest = z.infer<typeof SessionMessageSearchRequest>;
+
+export const SessionMessageSearchMatch = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    sessionId: z.string().uuid(),
+    sessionTitle: z.string().nullable(),
+    eventId: z.string().uuid(),
+    sequence: z.number().int().positive(),
+    turnId: z.string().uuid().nullable(),
+    role: z.enum(["user", "assistant"]),
+    messageId: z.string().nullable(),
+    /** All offsets are zero-based UTF-16 code units; ends are exclusive. */
+    messageMatchOffset: z.number().int().nonnegative(),
+    snippet: z.object({
+      text: z.string(),
+      matchStart: z.number().int().nonnegative(),
+      matchEnd: z.number().int().nonnegative(),
+    }),
+  }),
+);
+export type SessionMessageSearchMatch = z.infer<typeof SessionMessageSearchMatch>;
+
+/** A bounded scan page, not necessarily a full page of matches. Continue even
+ * after an empty page while hasMore is true. Counts describe this live traversal,
+ * not a frozen snapshot; restart to reflect concurrent changes. All non-overlapping
+ * literal occurrences in user messages and completed assistant messages.
+ * With groupBy=session, matches and both matched counts describe one first-hit
+ * representative per matching session, not full message/occurrence totals.
+ */
+export const SessionMessageSearchResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    matches: z.array(SessionMessageSearchMatch).max(50),
+    nextCursor: z.string().nullable(),
+    hasMore: z.boolean(),
+    scannedMessages: z.number().int().nonnegative(),
+    matchedMessageCount: z.number().int().nonnegative(),
+    matchedOccurrenceCount: z.number().int().nonnegative(),
+    countIsExact: z.boolean(),
+  }),
+);
+export type SessionMessageSearchResponse = z.infer<typeof SessionMessageSearchResponse>;

package/src/session-target.ts

@@ -0,0 +1,57 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Conversational context only. Never an authority or an implicit dispatch destination. */
+export const SessionTargetContext = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.number().int().nonnegative(),
+      sessionId: z.string().uuid().nullable(),
+      operationId: z.string().uuid().nullable(),
+    })
+    .strict(),
+);
+export type SessionTargetContext = z.infer<typeof SessionTargetContext>;
+
+export const SetSessionTargetRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      sessionId: z.string().uuid().nullable(),
+      expectedVersion: z.number().int().nonnegative(),
+      operationId: z.string().uuid(),
+    })
+    .strict(),
+);
+export type SetSessionTargetRequest = z.infer<typeof SetSessionTargetRequest>;
+
+export const SESSION_TARGET_CONTEXT_KEY = "conversationTargetV1";
+
+export function sessionTargetContext(metadata: Record<string, unknown>): SessionTargetContext {
+  return SessionTargetContext.parse(
+    metadata[SESSION_TARGET_CONTEXT_KEY] ?? {
+      version: 0,
+      sessionId: null,
+      operationId: null,
+    },
+  );
+}
+
+/** CAS plus exact retry replay; an old retry cannot restore a subsequently cleared target. */
+export function nextSessionTargetContext(
+  current: SessionTargetContext,
+  request: SetSessionTargetRequest,
+): SessionTargetContext {
+  SetSessionTargetRequest.parse(request);
+  if (current.operationId === request.operationId) {
+    if (current.sessionId !== request.sessionId || current.version !== request.expectedVersion + 1)
+      throw new Error("Session target operation was reused with different input");
+    return current;
+  }
+  if (current.version !== request.expectedVersion)
+    throw new Error("Session target changed; read it again");
+  return {
+    version: current.version + 1,
+    sessionId: request.sessionId,
+    operationId: request.operationId,
+  };
+}

package/src/session-titles.ts

@@ -18,7 +18,7 @@ export const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
 // Session creation accepts a body far larger than a navigation label. Bound
 // the source before any replace/split/normalization so a persisted large prompt
 // cannot amplify memory or CPU on every client render.
-const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
+export const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
 
 const SESSION_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -254,6 +254,45 @@ function stripAutomaticTitleBoilerplate(value: string): string {
   return title;
 }
 
+const AUTOMATIC_TITLE_TRAILING_PUNCTUATION = /[\s.!?,;:\-–—]+$/u;
+
+// Closing quote and markdown marks, mapped to the distinct opening mark that
+// would pair with them inside the title.
+const TRAILING_WRAPPER_MARKS = new Map<string, string | null>([
+  ['"', null],
+  ["'", null],
+  ["`", null],
+  ["*", null],
+  ["”", "“"],
+  ["’", "‘"],
+  ["»", "«"],
+]);
+
+/**
+ * Remove trailing punctuation and a closing quote or markdown mark whose
+ * opening counterpart was already stripped as a leading wrapper, so
+ * `"Pod Crash Debugging"` and `**Pod Crash Debugging**` do not keep a dangling
+ * closing mark. A mark that still pairs with one inside the title stays.
+ */
+function trimAutomaticTitleEnd(value: string): string {
+  let title = value;
+  for (let pass = 0; pass < 4; pass += 1) {
+    const before = title;
+    title = title.replace(AUTOMATIC_TITLE_TRAILING_PUNCTUATION, "");
+    const last = title.at(-1);
+    const opening = last === undefined ? undefined : TRAILING_WRAPPER_MARKS.get(last);
+    if (last !== undefined && opening !== undefined) {
+      let rest = title;
+      while (rest.endsWith(last)) rest = rest.slice(0, -last.length);
+      if (!rest.includes(last) && (opening === null || !rest.includes(opening))) {
+        title = rest;
+      }
+    }
+    if (title === before) break;
+  }
+  return title.trim();
+}
+
 function automaticTitleGraphemes(value: string): string[] {
   if (titleSegmenter === undefined) {
     titleSegmenter =
@@ -285,6 +324,39 @@ function automaticTitleGraphemes(value: string): string[] {
   return graphemes;
 }
 
+/**
+ * Model control tokens such as `<|fim_suffix|>`, `<|im_end|>` or `<｜end▁of▁sentence｜>`
+ * sometimes leak into generated text. They are never title content: each one
+ * becomes a line break, so a title keeps only its first real segment.
+ */
+const MODEL_CONTROL_TOKEN = /<[|｜][^<>|｜\s]{1,64}[|｜]>/gu;
+
+function withoutModelControlTokens(value: string): string {
+  return value.replace(MODEL_CONTROL_TOKEN, "\n");
+}
+
+/**
+ * Read-side cleanup for a durable title. Automatic titles written before
+ * control-token stripping can still hold a token ("Release plan<|fim_suffix|>");
+ * those keep only their first real segment, and a token-only title reads as no
+ * title. Human renames and titles without a token are returned unchanged.
+ */
+export function cleanStoredSessionTitle(
+  title: string | null | undefined,
+  titleSource: string | null | undefined,
+): string | null {
+  if (title === null || title === undefined) return null;
+  if (titleSource === "user") return title;
+  const stripped = withoutModelControlTokens(title);
+  if (stripped === title) return title;
+  return (
+    stripped
+      .split("\n")
+      .map((part) => part.trim())
+      .find(Boolean) ?? null
+  );
+}
+
 /** Bound an already-normalized automatic-title candidate without splitting graphemes. */
 export function boundAutomaticSessionTitle(value: string): string {
   const words = value.split(/\s+/u);
@@ -306,7 +378,7 @@ export function boundAutomaticSessionTitle(value: string): string {
  * title (normally {@link AUTOMATIC_SESSION_TITLE_FALLBACK}) in that case.
  */
 export function normalizeAutomaticSessionTitle(value: string): string | null {
-  const firstLine = value
+  const firstLine = withoutModelControlTokens(value)
     .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
     .split(/\n+/u)
     .map((line) => line.trim())
@@ -319,10 +391,9 @@ export function normalizeAutomaticSessionTitle(value: string): string | null {
     return null;
   }
 
-  let title = stripAutomaticTitleBoilerplate(firstLine)
-    .replace(/\s+/gu, " ")
-    .replace(/[\s.!?,;:\-–—]+$/u, "")
-    .trim();
+  let title = trimAutomaticTitleEnd(
+    stripAutomaticTitleBoilerplate(firstLine).replace(/\s+/gu, " "),
+  );
   if (
     !title ||
     !hasVisibleAutomaticTitleContent(title) ||
@@ -331,9 +402,7 @@ export function normalizeAutomaticSessionTitle(value: string): string | null {
     return null;
   }
 
-  title = boundAutomaticSessionTitle(title)
-    .replace(/[\s.!?,;:\-–—]+$/u, "")
-    .trim();
+  title = trimAutomaticTitleEnd(boundAutomaticSessionTitle(title));
   if (!title || !hasVisibleAutomaticTitleContent(title)) return null;
   return title;
 }
@@ -414,7 +483,8 @@ export function deriveSessionDisplayTitle(
     return title || automaticSessionReferenceTitle(input.id);
   }
   if (title && !sessionTitleIsPending(input)) {
-    return title;
+    const clean = cleanStoredSessionTitle(title, input.titleSource)?.trim();
+    if (clean) return clean;
   }
 
   for (const key of options.metadataKeys ?? []) {

package/src/session-topology-primitives.ts

@@ -1,21 +1,28 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const SessionStatus = z.enum([
-  "queued",
-  "running",
-  "idle",
-  "requires_action",
-  "recovering",
-  "waiting_capacity",
-  "failed",
-  "cancelled",
-]);
+export const SessionStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "queued",
+    "running",
+    "idle",
+    "requires_action",
+    "recovering",
+    "waiting_capacity",
+    "failed",
+    "cancelled",
+  ]),
+);
 export type SessionStatus = z.infer<typeof SessionStatus>;
 
-export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
+export const SessionGoalStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "paused", "completed"]),
+);
 export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
 
 /** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
 export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
-export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+export const NestedAgentDepthValue = /* @__PURE__ */ defineSchema(() =>
+  z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH),
+);
 export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;

package/src/session-usage-limit-refusal.ts

@@ -0,0 +1,101 @@
+/**
+ * Browser/React Native-safe session usage limit helpers. Deliberately free of
+ * the zod runtime so synchronous timeline projection can use it; contract
+ * parity tests keep it aligned with `session-usage-limits.ts`.
+ */
+
+/** `turn.completed.segmentLimit` for a stop caused by a task usage limit. */
+export const SESSION_USAGE_LIMIT_SEGMENT = "session_usage_limit" as const;
+/** `SessionGoal.pausedReason` for a goal paused by a task usage limit. */
+export const SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON = "session_usage_limit" as const;
+
+const BASIS = "model_api_equivalent_v1";
+const MAX_LIMIT_MICROS = 10_000_000 * 1_000_000;
+const MESSAGE_MAX_UTF8_BYTES = 1_024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export type ParsedSessionUsageLimitReachedRefusal = {
+  code: "session_usage_limit_reached";
+  basis: "model_api_equivalent_v1";
+  rootSessionId: string;
+  limitMicros: number;
+  usedMicros: number;
+  message: string;
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function micros(value: unknown, max = Number.MAX_SAFE_INTEGER): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= max;
+}
+
+function boundedMessage(value: string): string {
+  const normalized = value
+    .slice(0, MESSAGE_MAX_UTF8_BYTES * 2)
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .trim();
+  const bytes = new TextEncoder().encode(normalized);
+  let end = Math.min(bytes.length, MESSAGE_MAX_UTF8_BYTES);
+  while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return new TextDecoder().decode(bytes.slice(0, end)).trim();
+}
+
+/**
+ * Select only the public refusal fields from an API error body (fields may sit
+ * in `details`), a `turn.completed` payload's `sessionUsageLimit` record, or a
+ * refusal object. Anything malformed returns null instead of a guessed amount.
+ */
+export function parseSessionUsageLimitReachedRefusal(
+  value: unknown,
+): ParsedSessionUsageLimitReachedRefusal | null {
+  const outer = record(value);
+  if (!outer) return null;
+  const source = record(outer.sessionUsageLimit) ?? outer;
+  if (source.code !== "session_usage_limit_reached") return null;
+  const fields = record(source.details) ?? source;
+  if (
+    fields.basis !== BASIS ||
+    typeof fields.rootSessionId !== "string" ||
+    !UUID.test(fields.rootSessionId) ||
+    !micros(fields.limitMicros, MAX_LIMIT_MICROS) ||
+    !micros(fields.usedMicros)
+  ) {
+    return null;
+  }
+  const refusal = {
+    code: "session_usage_limit_reached" as const,
+    basis: BASIS as "model_api_equivalent_v1",
+    rootSessionId: fields.rootSessionId.toLowerCase(),
+    limitMicros: fields.limitMicros,
+    usedMicros: fields.usedMicros,
+    message: "",
+  };
+  const message = typeof source.message === "string" ? boundedMessage(source.message) : "";
+  return { ...refusal, message: message || sessionUsageLimitReachedMessage(refusal) };
+}
+
+/**
+ * "$12.34" for known amounts, "<$0.01" for a positive amount under a cent.
+ * Callers must not pass unknown usage: render "Preparing usage" or
+ * "Usage unavailable" instead of a dollar figure.
+ */
+export function formatSessionUsageMicros(value: number): string {
+  if (value > 0 && value < 10_000) return "<$0.01";
+  const dollars = value / 1_000_000;
+  return `$${dollars.toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })}`;
+}
+
+/** Fixed, bounded wording: no reset date, purchase remedy or invoice claim. */
+export function sessionUsageLimitReachedMessage(refusal: {
+  limitMicros: number;
+  usedMicros: number;
+}): string {
+  return `This task's usage limit is reached (${formatSessionUsageMicros(refusal.usedMicros)} of ${formatSessionUsageMicros(refusal.limitMicros)} API-equivalent model usage). A person can raise or remove the limit to continue.`;
+}

package/src/session-usage-limits.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+
+/**
+ * Per-task (root session) usage limits.
+ *
+ * One optional limit belongs to a root session and is shared by every
+ * descendant. It is measured in integer USD micros ($1 = 1,000,000) of the
+ * canonical pre-margin API-equivalent model cost (`estimatedProviderCostMicros`)
+ * recorded when a model response settles, whatever funds the call (Opengeni
+ * credits, a connected subscription or a workspace-owned key).
+ *
+ * The limit is checked before each new model request; it is not a reservation.
+ * Requests already admitted may finish and take recorded usage above the
+ * limit, and concurrently admitted requests may overshoot together. Usage
+ * without a known price is excluded from the total and disclosed as partial
+ * coverage instead of being valued at zero. It is not an invoice cap.
+ */
+
+/** Versioned measurement basis, exposed so a future basis cannot be confused with this one. */
+export const SESSION_USAGE_LIMIT_BASIS = "model_api_equivalent_v1" as const;
+export const SessionUsageLimitBasis = z.literal(SESSION_USAGE_LIMIT_BASIS);
+export type SessionUsageLimitBasis = z.infer<typeof SessionUsageLimitBasis>;
+
+export const SESSION_USAGE_LIMIT_MICROS_PER_DOLLAR = 1_000_000;
+/** $10M: the largest configurable limit, far inside safe integers. Usage itself is never clamped. */
+export const SESSION_USAGE_LIMIT_MAX_MICROS = 10_000_000 * SESSION_USAGE_LIMIT_MICROS_PER_DOLLAR;
+
+/** A configured limit. Zero is a valid immediate stop; `null` (not this schema) means no limit. */
+export const SessionUsageLimitMicros = z
+  .number()
+  .int()
+  .nonnegative()
+  .safe()
+  .max(SESSION_USAGE_LIMIT_MAX_MICROS);
+export type SessionUsageLimitMicros = z.infer<typeof SessionUsageLimitMicros>;
+
+/** Recorded usage is a non-negative safe integer and may exceed the configured maximum. */
+const UsageMicros = z.number().int().nonnegative().safe();
+const Count = z.number().int().nonnegative().safe();
+const Version = z.number().int().nonnegative().safe();
+
+const OperationId = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine(
+    (value) =>
+      value.trim().length > 0 &&
+      !value.includes("\0") &&
+      !/[\uD800-\uDFFF]/u.test(value) &&
+      new TextEncoder().encode(value).byteLength <= 256,
+  );
+
+/**
+ * - `unlimited`: no limit is configured; usage is still recorded.
+ * - `within`: a limit is configured and recorded usage is below it.
+ * - `reached`: recorded usage is at or above the limit; new model requests are refused.
+ * - `preparing`: historical usage for a task created before this feature is
+ *   still being imported; the total is not yet meaningful and a new limit
+ *   cannot be set until it finishes.
+ * - `unavailable`: the usage state could not be read. Never treat it as zero or unlimited.
+ */
+export const SessionUsageLimitStatus = z.enum([
+  "unlimited",
+  "within",
+  "reached",
+  "preparing",
+  "unavailable",
+]);
+export type SessionUsageLimitStatus = z.infer<typeof SessionUsageLimitStatus>;
+
+/**
+ * `complete`: every recorded model response of this task was metered live.
+ * `legacy_partial`: the task predates usage limits; available historical cost
+ * snapshots were imported, but older usage may be missing. This never upgrades
+ * to complete, because a missing old record is not proof of no usage.
+ * `preparing`: the historical import has not finished.
+ */
+export const SessionUsageLimitHistory = z.enum(["complete", "legacy_partial", "preparing"]);
+export type SessionUsageLimitHistory = z.infer<typeof SessionUsageLimitHistory>;
+
+export const SessionUsageLimit = z
+  .object({
+    basis: SessionUsageLimitBasis,
+    /** The task root whose limit applies. Equal to the session id for a root. */
+    rootSessionId: z.string().uuid(),
+    /** True when this projection was read through a descendant: edit the root's limit instead. */
+    inherited: z.boolean(),
+    status: SessionUsageLimitStatus,
+    /** Configured limit; null means no limit. Meaningless while `status` is `unavailable`. */
+    limitMicros: SessionUsageLimitMicros.nullable(),
+    /**
+     * Recorded known (priced or known-free) usage of the whole task tree, in USD
+     * micros. Null while `preparing` or `unavailable`: never render it as $0.
+     * May exceed `limitMicros`.
+     */
+    usedMicros: UsageMicros.nullable(),
+    /** Configuration version for compare-and-set writes. Survives clearing. */
+    version: Version,
+    /** Monotonic usage revision; increases whenever a usage receipt changes the total or coverage. */
+    usageRevision: Version,
+    history: SessionUsageLimitHistory,
+    /** `partial` when any usage has unknown cost or history is legacy/preparing: show "at least". */
+    coverage: z.enum(["complete", "partial"]),
+    pricedCalls: Count,
+    /** Responses with a known price of zero; they count as zero, unlike unpriced usage. */
+    freeCalls: Count,
+    /** Responses whose cost is unknown; they are excluded from `usedMicros`. */
+    unpricedCalls: Count,
+    updatedAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict();
+export type SessionUsageLimit = z.infer<typeof SessionUsageLimit>;
+
+/**
+ * Compare-and-set write of a root task's limit. `expectedVersion` is the
+ * `version` the caller last read; a stale version returns 409. A replay of the
+ * same `operationId` with the same request returns the committed result.
+ */
+export const SetSessionUsageLimitRequest = z
+  .object({
+    limitMicros: SessionUsageLimitMicros.nullable(),
+    expectedVersion: Version,
+    operationId: OperationId,
+  })
+  .strict();
+export type SetSessionUsageLimitRequest = z.infer<typeof SetSessionUsageLimitRequest>;
+
+/** Typed refusal for a fresh model request, message or goal resume after the limit is reached. */
+export const SessionUsageLimitReachedRefusal = z
+  .object({
+    code: z.literal("session_usage_limit_reached"),
+    basis: SessionUsageLimitBasis,
+    rootSessionId: z.string().uuid(),
+    limitMicros: SessionUsageLimitMicros,
+    usedMicros: UsageMicros,
+    message: z.string().max(1_024),
+  })
+  .strict();
+export type SessionUsageLimitReachedRefusal = z.infer<typeof SessionUsageLimitReachedRefusal>;
+
+/** Typed error codes for the usage-limit routes. */
+export const SessionUsageLimitErrorCode = z.enum([
+  "session_usage_limit_reached",
+  "session_usage_limit_conflict",
+  "session_usage_limit_not_root",
+  "session_usage_limit_preparing",
+  "session_usage_limit_unavailable",
+  "session_usage_limit_disabled",
+  "session_usage_limit_forbidden",
+]);
+export type SessionUsageLimitErrorCode = z.infer<typeof SessionUsageLimitErrorCode>;
+
+/** The durable event appended to a root's stream when an authorized person changes its limit. */
+export const SessionUsageLimitUpdatedPayload = z
+  .object({
+    basis: SessionUsageLimitBasis,
+    limitMicros: SessionUsageLimitMicros.nullable(),
+    previousLimitMicros: SessionUsageLimitMicros.nullable(),
+    version: Version,
+  })
+  .strict();
+export type SessionUsageLimitUpdatedPayload = z.infer<typeof SessionUsageLimitUpdatedPayload>;
+
+export {
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  sessionUsageLimitReachedMessage,
+} from "./session-usage-limit-refusal";

package/src/signup-attribution.ts

@@ -0,0 +1,86 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/**
+ * First-touch marketing parameters accepted on the web app landing URL. The
+ * browser keeps them in memory only and forwards them with a sign-up request,
+ * so nothing is written to the device before analytics consent.
+ */
+export const SIGNUP_ATTRIBUTION_URL_PARAMETERS = {
+  utmSource: "utm_source",
+  utmMedium: "utm_medium",
+  utmCampaign: "utm_campaign",
+  utmContent: "utm_content",
+  ref: "ref",
+} as const;
+
+/** Maximum retained length of one attribution value. */
+export const SIGNUP_ATTRIBUTION_VALUE_MAX_LENGTH = 100;
+
+/**
+ * Campaign labels are marketer-chosen slug tokens such as `hero-cta` or
+ * `opengeni.ai`. The closed character set has no space, `@`, `:`, `/`, `?`,
+ * `=`, or `%`, so free text, email addresses, and URL payloads are rejected
+ * before they reach any sink. The web boot capture and the session-set social
+ * start request mirror this rule; tests pin each copy to it.
+ */
+export const SIGNUP_ATTRIBUTION_VALUE_PATTERN = /^[A-Za-z0-9._~+-]+$/;
+
+const SignupAttributionValue = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .trim()
+    .min(1)
+    .max(SIGNUP_ATTRIBUTION_VALUE_MAX_LENGTH)
+    .regex(SIGNUP_ATTRIBUTION_VALUE_PATTERN),
+);
+
+export const SignupAttribution = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      utmSource: SignupAttributionValue.optional(),
+      utmMedium: SignupAttributionValue.optional(),
+      utmCampaign: SignupAttributionValue.optional(),
+      utmContent: SignupAttributionValue.optional(),
+      ref: SignupAttributionValue.optional(),
+    })
+    .strict(),
+);
+export type SignupAttribution = z.infer<typeof SignupAttribution>;
+
+/** Closed acquisition channels reported by server-side sign-up metrics. */
+export const SIGNUP_ACQUISITION_SOURCES = ["producthunt", "website", "direct", "other"] as const;
+export type SignupAcquisitionSource = (typeof SIGNUP_ACQUISITION_SOURCES)[number];
+
+/**
+ * Normalize untrusted first-touch attribution to a closed channel. Missing
+ * attribution is `direct`; malformed or unrecognized attribution is `other`.
+ */
+export function signupAcquisitionSource(input: unknown): SignupAcquisitionSource {
+  if (input === undefined || input === null) return "direct";
+  const parsed = SignupAttribution.safeParse(input);
+  if (!parsed.success) return "other";
+  const attribution = parsed.data;
+  const values = Object.values(attribution).filter((value) => value !== undefined);
+  if (values.length === 0) return "direct";
+  const source = attribution.utmSource?.toLowerCase();
+  const medium = attribution.utmMedium?.toLowerCase();
+  const ref = attribution.ref?.toLowerCase();
+  if ([source, ref].some((value) => value !== undefined && isProductHunt(value))) {
+    return "producthunt";
+  }
+  if (
+    source === "opengeni.ai" ||
+    source?.endsWith(".opengeni.ai") ||
+    source === "opengeni" ||
+    medium === "website"
+  ) {
+    return "website";
+  }
+  return "other";
+}
+
+function isProductHunt(value: string): boolean {
+  const compact = value.replace(/[\s._-]/g, "");
+  return compact === "ph" || compact.includes("producthunt");
+}