deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/plays/share/metrics.ts

@@ -0,0 +1,140 @@
+/**
+ * Package-owned metric aggregation for the public read model.
+ *
+ * Hard rules (see docs/shareable-play-pages-plan.md + AGENTS.md):
+ * - Only Deepline credits are aggregated here. Provider spend (USD) is never
+ *   passed into this module.
+ * - Cost is exposed only when the owner opted in.
+ * - Latency is exposed only when the owner opted in AND the revision has no map.
+ * - Denominator-specific metrics return null when row/contact counts are
+ *   missing or ambiguous.
+ */
+import type { PlayCostBasis, PublishedPlayPageMetrics } from './types';
+
+/**
+ * One completed run, reduced to the only facts the public metrics need.
+ * `providerCostUsd` deliberately does not exist on this type.
+ */
+export type ShareRunMetricSample = {
+  /** Total Deepline credits for the run (sum of usageEvents.credits). */
+  credits: number;
+  /** Number of input rows processed, when reliably known. */
+  inputRowCount: number | null;
+  /** Number of output leads/contacts produced, when reliably known. */
+  outputLeadCount: number | null;
+  /** Wall-clock run latency in ms, when valid timing exists. */
+  latencyMs: number | null;
+};
+
+export type ComputePublicMetricsOptions = {
+  showAverageDeeplineCost: boolean;
+  showAverageLatency: boolean;
+  /** Latency is meaningless for mapped (fan-out) revisions. */
+  hasMap: boolean;
+  /** Which credit denominator the page may render; see `classifyCostBasis`. */
+  costBasis: PlayCostBasis;
+};
+
+function mean(values: number[]): number | null {
+  if (values.length === 0) {
+    return null;
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return total / values.length;
+}
+
+function roundTo(value: number, decimals: number): number {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/**
+ * Aggregate a bounded sample of completed runs into public, credit-only metrics.
+ */
+export function computePublicMetrics(
+  samples: ShareRunMetricSample[],
+  options: ComputePublicMetricsOptions,
+): PublishedPlayPageMetrics {
+  const sampleRunCount = samples.length;
+
+  const empty: PublishedPlayPageMetrics = {
+    averageDeeplineCostCredits: null,
+    averageCostPerInputRowCredits: null,
+    averageCostPerOutputLeadCredits: null,
+    averageLatencyMs: null,
+    sampleRunCount,
+    costBasis: options.costBasis,
+  };
+
+  if (sampleRunCount === 0) {
+    return empty;
+  }
+
+  const metrics: PublishedPlayPageMetrics = { ...empty };
+
+  if (options.showAverageDeeplineCost) {
+    const creditValues = samples
+      .map((sample) => sample.credits)
+      .filter((value) => Number.isFinite(value) && value >= 0);
+    const avgCredits = mean(creditValues);
+    metrics.averageDeeplineCostCredits =
+      avgCredits === null ? null : roundTo(avgCredits, 2);
+
+    metrics.averageCostPerInputRowCredits = ratioOverDenominator(
+      samples,
+      (sample) => sample.inputRowCount,
+    );
+    metrics.averageCostPerOutputLeadCredits = ratioOverDenominator(
+      samples,
+      (sample) => sample.outputLeadCount,
+    );
+  }
+
+  if (options.showAverageLatency && !options.hasMap) {
+    const latencyValues = samples
+      .map((sample) => sample.latencyMs)
+      .filter(
+        (value): value is number =>
+          value !== null && Number.isFinite(value) && value >= 0,
+      );
+    const avgLatency = mean(latencyValues);
+    metrics.averageLatencyMs =
+      avgLatency === null ? null : Math.round(avgLatency);
+  }
+
+  return metrics;
+}
+
+/**
+ * total credits / total denominator, considering only runs where the
+ * denominator is a reliable positive number. Returns null if no such run.
+ */
+function ratioOverDenominator(
+  samples: ShareRunMetricSample[],
+  pick: (sample: ShareRunMetricSample) => number | null,
+): number | null {
+  let creditSum = 0;
+  let denominatorSum = 0;
+  let usableRuns = 0;
+
+  for (const sample of samples) {
+    const denominator = pick(sample);
+    if (
+      denominator === null ||
+      !Number.isFinite(denominator) ||
+      denominator <= 0 ||
+      !Number.isFinite(sample.credits) ||
+      sample.credits < 0
+    ) {
+      continue;
+    }
+    creditSum += sample.credits;
+    denominatorSum += denominator;
+    usableRuns += 1;
+  }
+
+  if (usableRuns === 0 || denominatorSum <= 0) {
+    return null;
+  }
+  return roundTo(creditSum / denominatorSum, 4);
+}

package/dist/bundling-sources/shared_libs/plays/share/public-read-model.ts

@@ -0,0 +1,86 @@
+/**
+ * Package-owned assembler for the bounded `PublishedPlayPagePackage`.
+ *
+ * This is the ONLY object the public page and public API expose. It is built
+ * from already-gathered, already-sanitized inputs — this function performs no
+ * I/O and makes no access decisions.
+ */
+import {
+  buildInputSchemaShape,
+  buildOutputSchemaShape,
+  buildPublicSubsteps,
+  buildStaticPipelineSummary,
+} from './static-pipeline-summary';
+// This Module is bundled by Convex through its workspace dependency graph.
+import { buildShareCanonicalPath } from '../slug';
+import type {
+  PlayShareGeneratedCopy,
+  PlayShareSeoIndexing,
+  PublishedPlayPageMetrics,
+  PublishedPlayPagePackage,
+} from './types';
+
+export type BuildPublishedPlayPagePackageInput = {
+  shareSlug: string;
+  /** Org URL handle; the public page is namespaced `/p/:orgSlug/:playName`. */
+  orgSlug: string;
+  /** Page-level SEO posture; applied only to the published version. */
+  pageSeoIndexing: PlayShareSeoIndexing;
+  publishedVersion: number;
+  publishedAt: number;
+  definitionName: string;
+  ownerDisplayName: string | null;
+  revision: {
+    id: string;
+    version: number;
+    graphHash: string | null;
+    staticPipeline: unknown;
+  };
+  copy: PlayShareGeneratedCopy;
+  metrics: PublishedPlayPageMetrics;
+};
+
+export function buildPublishedPlayPagePackage(
+  input: BuildPublishedPlayPagePackageInput,
+): PublishedPlayPagePackage {
+  const isPublishedVersion = input.revision.version === input.publishedVersion;
+
+  // Non-published (historical) versions default to noindex regardless of the
+  // page setting, so old copies never compete with the canonical version.
+  const seoIndexing: PlayShareSeoIndexing = isPublishedVersion
+    ? input.pageSeoIndexing
+    : 'noindex';
+
+  return {
+    page: {
+      shareSlug: input.shareSlug,
+      orgSlug: input.orgSlug,
+      visibility: 'unlisted',
+      seoIndexing,
+      canonicalPath: buildShareCanonicalPath(
+        input.orgSlug,
+        input.definitionName,
+        input.publishedVersion,
+      ),
+      isPublishedVersion,
+      publishedAt: input.publishedAt,
+    },
+    definition: {
+      name: input.definitionName,
+      ownerDisplayName: input.ownerDisplayName,
+    },
+    revision: {
+      id: input.revision.id,
+      version: input.revision.version,
+      graphHash: input.revision.graphHash,
+      staticPipelineSummary: buildStaticPipelineSummary(
+        input.revision.staticPipeline,
+      ),
+      substeps: buildPublicSubsteps(input.revision.staticPipeline),
+      inputSchema: buildInputSchemaShape(input.revision.staticPipeline),
+      outputSchema: buildOutputSchemaShape(input.revision.staticPipeline),
+    },
+    copy: input.copy,
+    publicMetrics: input.metrics,
+  };
+}

package/dist/bundling-sources/shared_libs/plays/share/seo-quality.ts

@@ -0,0 +1,181 @@
+import type { PublishedPlayPagePackage } from './types';
+
+// SEO quality is deterministic authoring policy, not a web-app adapter.
+
+export type PlayPageSeoQualitySignal =
+  | 'unique_title'
+  | 'unique_description'
+  | 'required_body_sections'
+  | 'concrete_inputs'
+  | 'concrete_outputs'
+  | 'workflow_structure'
+  | 'provider_or_tool_count'
+  | 'related_links'
+  | 'json_ld_ready'
+  | 'canonical'
+  | 'h1'
+  | 'no_placeholder_copy';
+
+export type PlayPageSeoQualityResult = {
+  score: number;
+  maxScore: number;
+  passed: boolean;
+  passedSignals: PlayPageSeoQualitySignal[];
+  failedSignals: PlayPageSeoQualitySignal[];
+};
+
+export const PLAY_PAGE_REQUIRED_BODY_SECTIONS = [
+  'What this workflow does',
+  'Inputs you need',
+  'Outputs you get',
+  'How it works',
+  'Cost/latency when available',
+  'Common edits',
+  'Related workflows',
+  'Run or fork with Deepline CLI',
+] as const;
+
+const MIN_SCORE_TO_INDEX = 10;
+const PLACEHOLDER_PATTERNS = [
+  /\blorem ipsum\b/i,
+  /\btbd\b/i,
+  /\bcoming soon\b/i,
+  /\bplaceholder\b/i,
+  /\bTODO\b/,
+  /\bexample workflow\b/i,
+  /\bgeneric workflow\b/i,
+];
+
+function cleanWords(value: string): Set<string> {
+  return new Set(
+    value
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, ' ')
+      .split(/\s+/)
+      .filter((word) => word.length >= 4),
+  );
+}
+
+function overlapRatio(a: string, b: string): number {
+  const left = cleanWords(a);
+  const right = cleanWords(b);
+  if (left.size === 0 || right.size === 0) return 1;
+  let overlap = 0;
+  for (const word of left) {
+    if (right.has(word)) overlap += 1;
+  }
+  return overlap / Math.min(left.size, right.size);
+}
+
+function hasConcreteFields(fields: string[] | undefined): boolean {
+  const concrete = (fields ?? [])
+    .map((field) => field.trim())
+    .filter(Boolean)
+    .filter(
+      (field) =>
+        !/^(run parameters|input rows?|output table|results?)$/i.test(field),
+    );
+  return concrete.length > 0;
+}
+
+function hasNoPlaceholderCopy(pkg: PublishedPlayPagePackage): boolean {
+  const searchable = [
+    pkg.copy.title,
+    pkg.copy.shortDescription,
+    pkg.copy.jtbd,
+    pkg.copy.llmSummary,
+    pkg.copy.seoTitle,
+    pkg.copy.seoDescription,
+    ...pkg.copy.whenToUse,
+    ...pkg.copy.inputs,
+    ...pkg.copy.outputs,
+  ].join('\n');
+  return !PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(searchable));
+}
+
+export function evaluatePlayPageSeoQuality(input: {
+  pkg: PublishedPlayPagePackage;
+  relatedLinkCount: number;
+}): PlayPageSeoQualityResult {
+  const { pkg, relatedLinkCount } = input;
+  const checks: Array<[PlayPageSeoQualitySignal, boolean]> = [
+    [
+      'unique_title',
+      pkg.copy.seoTitle.trim().length >= 18 &&
+        pkg.copy.title.trim().length > 0 &&
+        overlapRatio(pkg.copy.seoTitle, pkg.copy.seoDescription) < 0.82,
+    ],
+    [
+      'unique_description',
+      pkg.copy.seoDescription.trim().length >= 80 &&
+        pkg.copy.seoDescription.trim().length <= 170 &&
+        overlapRatio(pkg.copy.seoDescription, pkg.copy.shortDescription) < 0.95,
+    ],
+    ['required_body_sections', PLAY_PAGE_REQUIRED_BODY_SECTIONS.length === 8],
+    [
+      'concrete_inputs',
+      hasConcreteFields(pkg.copy.inputs) ||
+        hasConcreteFields(pkg.revision.inputSchema?.fields),
+    ],
+    [
+      'concrete_outputs',
+      hasConcreteFields(pkg.copy.outputs) ||
+        hasConcreteFields(pkg.revision.outputSchema?.fields),
+    ],
+    [
+      'workflow_structure',
+      pkg.revision.staticPipelineSummary.stepCount > 0 &&
+        pkg.revision.staticPipelineSummary.previewNodes.length > 0,
+    ],
+    [
+      'provider_or_tool_count',
+      pkg.revision.staticPipelineSummary.providerCount > 0 ||
+        pkg.revision.staticPipelineSummary.stepCount >= 2,
+    ],
+    ['related_links', relatedLinkCount >= 1],
+    [
+      'json_ld_ready',
+      pkg.copy.llmSummary.trim().length > 0 &&
+        pkg.copy.agentPrompt.trim().length > 0,
+    ],
+    [
+      'canonical',
+      /^\/p\/[^/]+\/[^/]+\/v\/\d+$/.test(pkg.page.canonicalPath) &&
+        pkg.page.canonicalPath.includes(
+          encodeURIComponent(pkg.definition.name),
+        ),
+    ],
+    ['h1', pkg.copy.title.trim().length > 0],
+    ['no_placeholder_copy', hasNoPlaceholderCopy(pkg)],
+  ];
+
+  const passedSignals = checks
+    .filter(([, passed]) => passed)
+    .map(([signal]) => signal);
+  const failedSignals = checks
+    .filter(([, passed]) => !passed)
+    .map(([signal]) => signal);
+
+  return {
+    score: passedSignals.length,
+    maxScore: checks.length,
+    passed:
+      passedSignals.length >= MIN_SCORE_TO_INDEX && failedSignals.length === 0,
+    passedSignals,
+    failedSignals,
+  };
+}
+
+export function applyPlayPageSeoQuality(input: {
+  pkg: PublishedPlayPagePackage;
+  relatedLinkCount: number;
+}): PublishedPlayPagePackage {
+  const result = evaluatePlayPageSeoQuality(input);
+  return {
+    ...input.pkg,
+    page: {
+      ...input.pkg.page,
+      seoIndexing: result.passed ? input.pkg.page.seoIndexing : 'noindex',
+    },
+  };
+}