@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/src/progress/core.ts

@@ -0,0 +1,409 @@
+import type {SmartcatProject, SmartcatDocument, RequestLogger} from '../smartcat/types'
+import {toSanityLanguage, type SmartcatLanguageMapping} from '../lib/languageMap'
+import {ITEM_ID, itemDocDerefRespectingDraft} from '../lib/projectItems'
+import type {LogLine} from '../lib/log'
+
+/**
+ * Per-document, per-language, per-stage translation progress mirrored from
+ * Smartcat onto a `smartcat.translationProject`.
+ *
+ * This module is intentionally **dependency-free** (no DOM, no @sanity/* runtime)
+ * so it bundles cleanly into the thin `smartcat-progress` / `smartcat-import`
+ * Functions. All keys are deterministic, so repeated refreshes patch the same
+ * array members in place instead of churning `_key`s.
+ */
+
+export interface StageProgress {
+  /** Stable key for the Sanity array item (always set by `stagesFromDocument`). */
+  _key?: string
+  name: string
+  /** 0–100, rounded. */
+  percent: number
+}
+
+export interface TargetProgress {
+  _key: string
+  language: string
+  /** Smartcat target document id (`<fileGuid>_<languageNumber>`). */
+  smartcatDocumentId?: string
+  stages: StageProgress[]
+  /** All stages at 100%. */
+  complete: boolean
+  /** A locale variant has been built from this target (set by the browser). */
+  imported: boolean
+  syncedAt?: string
+}
+
+export interface DocProgress {
+  _key: string
+  sourceDocId: string
+  title?: string
+  targets: TargetProgress[]
+}
+
+/** Sanitizes an arbitrary string into a stable, Sanity-safe array `_key`. */
+export function keyify(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '-') || 'x'
+}
+
+/** Builds a progress target's `_key` from its document + language. */
+export function targetKey(sourceDocId: string, language: string): string {
+  return keyify(`${sourceDocId}__${language}`)
+}
+
+function clampPercent(value: number | undefined): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) return 0
+  return Math.max(0, Math.min(100, Math.round(value)))
+}
+
+/** Strips a `drafts.` prefix from a Sanity document id. */
+function stripDraft(id: string): string {
+  return id.replace(/^drafts\./, '')
+}
+
+function titleCase(value: string): string {
+  return value ? value.charAt(0).toUpperCase() + value.slice(1) : value
+}
+
+/**
+ * Builds a stage-id → display-name map from a project's `workflowStages`. On
+ * Smartcat, document-level stages carry only `{id, progress}` — the human name
+ * (`stageType`, e.g. "translation") lives on the project-level stages.
+ */
+export function buildStageNameMap(scProject: SmartcatProject): Map<string, string> {
+  const map = new Map<string, string>()
+  ;(scProject.workflowStages ?? []).forEach((stage, i) => {
+    if (stage.id) map.set(stage.id, titleCase(stage.stageType || stage.stageName || `Stage ${i + 1}`))
+  })
+  return map
+}
+
+/** Maps a Smartcat document's workflow stages to display-ready stage progress. */
+export function stagesFromDocument(
+  doc: SmartcatDocument,
+  stageNames: Map<string, string>,
+): StageProgress[] {
+  const stages = doc.workflowStages ?? []
+  return stages.map((stage, i) => ({
+    _key: stage.id || `s${i}`,
+    name:
+      (stage.id && stageNames.get(stage.id)) ||
+      titleCase(stage.stageType || stage.stageName || `Stage ${i + 1}`),
+    percent: clampPercent(stage.progress),
+  }))
+}
+
+/** A target is complete when it has stages and every one is at 100%. */
+export function isTargetComplete(stages: StageProgress[]): boolean {
+  return stages.length > 0 && stages.every((s) => s.percent >= 100)
+}
+
+/**
+ * Whether a target has any content confirmed at any stage — i.e. there is
+ * something worth importing. Used to gate `mode=confirmed` downloads so we skip
+ * targets with nothing confirmed yet (which would otherwise come back as source).
+ */
+export function hasConfirmedContent(stages: StageProgress[]): boolean {
+  return stages.some((s) => s.percent > 0)
+}
+
+/** Average completion across a target's stages (0–100). */
+export function targetPercent(stages: StageProgress[]): number {
+  if (stages.length === 0) return 0
+  return Math.round(stages.reduce((sum, s) => sum + s.percent, 0) / stages.length)
+}
+
+/** A project item we correlate Smartcat documents back to. */
+export interface ProjectItem {
+  _id: string
+  title?: string
+}
+
+/**
+ * Extracts the 8-char source-id prefix Smartcat preserves in a document's
+ * filename (built as `<title>-<idPrefix>.locjson`, or `<title>-<idPrefix>-draft.locjson`
+ * when the content came from the document's draft). Used to correlate a Smartcat
+ * document back to a Sanity source document.
+ *
+ * A trailing `-draft` marker is stripped first, so a draft-sourced file resolves
+ * to the same id as its published counterpart. The prefix is then always the
+ * final 8 characters before the (marker and) extension, so take the tail rather
+ * than splitting on a dash — the title or the id prefix itself can
+ * contain dashes (e.g. a custom id like `demo-pdpA` → prefix `demo-pdp`), which
+ * would make a last-dash split return the wrong fragment.
+ *
+ * Only a literal `.locjson` extension is stripped (Smartcat's API often returns
+ * the name without it). A generic strip-after-last-dot would eat the tail of any
+ * DOTTED title — e.g. micro-copy keys like `aiAssistantModal.resetChat-11AKrV8G`
+ * — leaving the wrong 8 chars, so those documents silently never correlate,
+ * never import, and re-syncs duplicate them instead of updating.
+ */
+export function sourceIdPrefix(doc: SmartcatDocument): string {
+  const base = doc.name || doc.filename || doc.fullPath || ''
+  const leaf = base.split('/').pop() ?? ''
+  const noExt = leaf.replace(/\.locjson$/i, '')
+  // Draft-sourced files carry a trailing `-draft` marker (informational only, so
+  // a project never holds both a document's draft and its published version).
+  // Strip it before taking the tail so a draft file correlates to the same source
+  // id as its published counterpart — the id prefix is what identifies the item.
+  const noDraft = noExt.replace(/-draft$/, '')
+  return noDraft.slice(-8)
+}
+
+/**
+ * Builds the full progress array from a freshly fetched Smartcat project and the
+ * project's items — independent of any export-time skeleton, so it works for
+ * projects exported before progress tracking existed.
+ *
+ * Documents are correlated to items by the 8-char id prefix in their filename;
+ * `imported` flags are carried over from the previous progress (by source doc +
+ * language) so importing isn't forgotten on refresh.
+ *
+ * `mappings` invert Smartcat's returned target codes back to Sanity ids, so all
+ * stored progress uses Sanity locale tags. When omitted, codes pass through
+ * unchanged (identity) — keeping legacy projects working.
+ */
+export function buildProgress(
+  items: ProjectItem[],
+  scProject: SmartcatProject,
+  previous: DocProgress[] | undefined,
+  now: string,
+  mappings?: SmartcatLanguageMapping[],
+): DocProgress[] {
+  const stageNames = buildStageNameMap(scProject)
+
+  const importedSet = new Set<string>()
+  // Titles are computed Sanity-native in the Studio and shipped on the outbox, so
+  // they may not be re-derivable server-side. Carry the previously-stored title
+  // forward so a progress sync (which only has the raw `doc.title`) can't clobber
+  // it with an "Untitled" for types that have no literal title field.
+  const titleByDoc = new Map<string, string>()
+  for (const doc of previous ?? []) {
+    if (doc.title) titleByDoc.set(doc.sourceDocId, doc.title)
+    for (const target of doc.targets) {
+      if (target.imported) importedSet.add(`${doc.sourceDocId}__${target.language}`)
+    }
+  }
+
+  const itemByPrefix = new Map<string, ProjectItem>()
+  for (const item of items) itemByPrefix.set(stripDraft(item._id).slice(0, 8), item)
+
+  const byDoc = new Map<string, DocProgress>()
+  for (const scDoc of scProject.documents ?? []) {
+    if (!scDoc.targetLanguage) continue
+    const item = itemByPrefix.get(sourceIdPrefix(scDoc))
+    if (!item) continue
+
+    // Store the Sanity locale tag, not Smartcat's code.
+    const language = toSanityLanguage(mappings, scDoc.targetLanguage)
+
+    let docProgress = byDoc.get(item._id)
+    if (!docProgress) {
+      const title = item.title || titleByDoc.get(item._id)
+      docProgress = {_key: targetKey(item._id, 'doc'), sourceDocId: item._id, title, targets: []}
+      byDoc.set(item._id, docProgress)
+    }
+    const stages = stagesFromDocument(scDoc, stageNames)
+    docProgress.targets.push({
+      _key: targetKey(item._id, language),
+      language,
+      smartcatDocumentId: scDoc.id,
+      stages,
+      complete: isTargetComplete(stages),
+      imported: importedSet.has(`${item._id}__${language}`),
+      syncedAt: now,
+    })
+  }
+
+  // Preserve item order; sort each doc's targets by language for stable display.
+  const result: DocProgress[] = []
+  for (const item of items) {
+    const docProgress = byDoc.get(item._id)
+    if (!docProgress) continue
+    docProgress.targets.sort((a, b) => a.language.localeCompare(b.language))
+    result.push(docProgress)
+  }
+  return result
+}
+
+export interface CompletionSummary {
+  /** Total (document × language) targets. */
+  total: number
+  /** Targets whose stages are all at 100%. */
+  complete: number
+  /** Targets a variant has been built for. */
+  imported: number
+  /** True when every target is complete and imported (and there is ≥1 target). */
+  allDone: boolean
+  /** True when at least one stage shows any progress. */
+  anyProgress: boolean
+}
+
+/** Summarizes a progress array for status decisions and the dashboard. */
+export function summarizeCompletion(progress: DocProgress[]): CompletionSummary {
+  let total = 0
+  let complete = 0
+  let imported = 0
+  let anyProgress = false
+  for (const doc of progress) {
+    for (const target of doc.targets) {
+      total++
+      if (target.complete) complete++
+      if (target.imported) imported++
+      if (target.stages.some((s) => s.percent > 0)) anyProgress = true
+    }
+  }
+  return {
+    total,
+    complete,
+    imported,
+    allDone: total > 0 && complete === total && imported === total,
+    anyProgress,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Function-side orchestration: refresh progress from Smartcat
+// ---------------------------------------------------------------------------
+
+/** Minimal structural subset of @sanity/client used by the progress refresh. */
+export interface SanityLikeClient {
+  fetch<T = unknown>(query: string, params?: Record<string, unknown>): Promise<T>
+  patch(id: string): {
+    set(attrs: Record<string, unknown>): {commit(): Promise<unknown>}
+  }
+}
+
+/** Structural subset of SmartcatClient the progress refresh needs. */
+export interface SmartcatProgressClient {
+  getProject(projectId: string): Promise<SmartcatProject>
+  /** Optional: trace every HTTP call so a timeout/error reaches the functionLog. */
+  setRequestLogger?(logger: RequestLogger): void
+}
+
+export interface RunProgressSyncOptions {
+  sanity: SanityLikeClient
+  smartcat: SmartcatProgressClient
+  /** `_id` of the `smartcat.translationProject` to refresh. */
+  projectId: string
+  now?: () => string
+}
+
+export interface RunProgressSyncResult {
+  summary: CompletionSummary
+  /** Set when the Smartcat fetch failed (e.g. timed out); the run was recorded, not thrown. */
+  error?: string
+}
+
+const PROGRESS_QUERY = `*[_id == $id][0]{
+  _id,
+  status,
+  smartcatProjectId,
+  smartcatLanguages[]{sanityId, smartcatLanguage},
+  "items": items[]{ "_id": ${ITEM_ID}, "title": ${itemDocDerefRespectingDraft('.title')} },
+  progress[]{_key, sourceDocId, title, targets[]{_key, language, smartcatDocumentId, stages, complete, imported, syncedAt}}
+}`
+
+interface ProgressProjectData {
+  _id: string
+  status?: string
+  smartcatProjectId?: string
+  smartcatLanguages?: SmartcatLanguageMapping[]
+  items?: ProjectItemRef[]
+  progress?: DocProgress[]
+}
+
+/** A project item as read for correlation: its stored id (always present) plus a
+ * best-effort title. `doc` is the legacy shape — some callers still project it. */
+interface ProjectItemRef {
+  _id?: string
+  title?: string
+  doc?: {_id?: string; title?: string} | null
+}
+
+/**
+ * Resolves a project's items into the lightweight shape we correlate on. The id
+ * is the item's stored `docId` — NOT a dereferenced document — so an item whose
+ * document exists only as a draft (never published) still correlates instead of
+ * being silently dropped. Tolerates the legacy `{doc}` projection.
+ */
+export function itemsFromProject(project: {items?: ProjectItemRef[]}): ProjectItem[] {
+  const result: ProjectItem[] = []
+  for (const item of project.items ?? []) {
+    const _id = item?._id ?? item?.doc?._id
+    if (!_id) continue
+    result.push({_id, title: item?.title ?? item?.doc?.title ?? undefined})
+  }
+  return result
+}
+
+/**
+ * Thin progress step run by the `smartcat-progress` Function: fetches the
+ * Smartcat project and mirrors its per-stage progress onto the project's
+ * `progress` array. Read-only with respect to Smartcat — it never downloads or
+ * creates variants, so it is cheap to run on every dashboard page load.
+ */
+export async function runProgressSync(
+  options: RunProgressSyncOptions,
+): Promise<RunProgressSyncResult> {
+  const {sanity, smartcat, projectId, now = () => new Date().toISOString()} = options
+
+  const project = await sanity.fetch<ProgressProjectData | null>(PROGRESS_QUERY, {id: projectId})
+  if (!project) throw new Error(`Translation project ${projectId} not found`)
+  if (!project.smartcatProjectId) {
+    throw new Error('Project has no smartcatProjectId — export it first')
+  }
+
+  const timestamp = now()
+
+  // Trace HTTP failures into a functionLog so a timeout/error surfaces in the UI.
+  // Successful calls are left unlogged: this Function runs on every page load, and
+  // functionLog is shared with export/import — writing it on every success would
+  // wipe a useful export/import log.
+  const log: LogLine[] = []
+  smartcat.setRequestLogger?.(({method, path, status, body}) => {
+    if (status >= 200 && status < 300) return
+    log.push({
+      level: 'error',
+      message: status ? `Error ${status} while performing ${method} ${path}` : `${method} ${path} did not complete`,
+    })
+    if (body) log.push({level: 'error', indent: true, message: body})
+  })
+
+  try {
+    const scProject = await smartcat.getProject(project.smartcatProjectId)
+    const progress = buildProgress(
+      itemsFromProject(project),
+      scProject,
+      project.progress,
+      timestamp,
+      project.smartcatLanguages,
+    )
+    const summary = summarizeCompletion(progress)
+
+    const patch: Record<string, unknown> = {progress, progressSyncedAt: timestamp, lastError: null}
+    // Gentle one-way nudge: once Smartcat reports any work, reflect it in the badge.
+    // Completion remains owned by the import flow.
+    if (project.status === 'sent' && summary.anyProgress) {
+      patch.status = 'translating'
+    }
+
+    await sanity.patch(projectId).set(patch).commit()
+
+    return {summary}
+  } catch (err) {
+    // Record the failure and return instead of throwing: a throw would let the
+    // platform retry, and a timed-out fetch has nothing transient to gain. Leave
+    // the existing `progress` untouched (no zeroing-out) and only stamp the error
+    // plus a fresh `progressSyncedAt`, which releases the UI refresh spinner and
+    // makes the log land where the dashboard reads it.
+    const message = err instanceof Error ? err.message : String(err)
+    if (!log.some((l) => l.level === 'error')) log.push({level: 'error', message})
+    await sanity
+      .patch(projectId)
+      .set({lastError: message, functionLog: JSON.stringify(log), progressSyncedAt: timestamp})
+      .commit()
+      .catch(() => {})
+    return {summary: summarizeCompletion(project.progress ?? []), error: message}
+  }
+}

package/src/progress/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Public entry for the `./progress` subpath. The implementation lives in
+ * `./core` so the other build entries (`./export`, `./import`) can import the
+ * shared helpers via a deep path without pkg-utils treating one entry as an
+ * external of another.
+ */
+export * from './core'