@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/dist/progress.d.cts

@@ -0,0 +1,277 @@
+/**
+ * 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 declare function buildProgress(
+  items: ProjectItem[],
+  scProject: SmartcatProject,
+  previous: DocProgress[] | undefined,
+  now: string,
+  mappings?: SmartcatLanguageMapping[],
+): DocProgress[];
+
+/**
+ * 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 declare function buildStageNameMap(
+  scProject: SmartcatProject,
+): Map<string, string>;
+
+export declare 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;
+}
+
+export declare interface DocProgress {
+  _key: string;
+  sourceDocId: string;
+  title?: string;
+  targets: TargetProgress[];
+}
+
+/**
+ * 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 declare function hasConfirmedContent(stages: StageProgress[]): boolean;
+
+/** A target is complete when it has stages and every one is at 100%. */
+export declare function isTargetComplete(stages: StageProgress[]): boolean;
+
+/**
+ * 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 declare function itemsFromProject(project: {
+  items?: ProjectItemRef[];
+}): ProjectItem[];
+
+/** Sanitizes an arbitrary string into a stable, Sanity-safe array `_key`. */
+export declare function keyify(value: string): string;
+
+/** A project item we correlate Smartcat documents back to. */
+export declare interface ProjectItem {
+  _id: string;
+  title?: string;
+}
+
+/** 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. */
+declare interface ProjectItemRef {
+  _id?: string;
+  title?: string;
+  doc?: {
+    _id?: string;
+    title?: string;
+  } | null;
+}
+
+/** Sink for per-request tracing; attach with `SmartcatClient.setRequestLogger`. */
+declare type RequestLogger = (info: RequestLogInfo) => void;
+
+/** One Smartcat HTTP call, reported to a {@link RequestLogger} for tracing. */
+declare interface RequestLogInfo {
+  method: string;
+  /** Request path incl. query string (no host, no secrets). */
+  path: string;
+  status: number;
+  /** Raw response body text — carries Smartcat's error detail on failures. */
+  body: string;
+}
+
+/**
+ * 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 declare function runProgressSync(
+  options: RunProgressSyncOptions,
+): Promise<RunProgressSyncResult>;
+
+export declare interface RunProgressSyncOptions {
+  sanity: SanityLikeClient;
+  smartcat: SmartcatProgressClient;
+  /** `_id` of the `smartcat.translationProject` to refresh. */
+  projectId: string;
+  now?: () => string;
+}
+
+export declare interface RunProgressSyncResult {
+  summary: CompletionSummary;
+  /** Set when the Smartcat fetch failed (e.g. timed out); the run was recorded, not thrown. */
+  error?: string;
+}
+
+/** Minimal structural subset of @sanity/client used by the progress refresh. */
+export declare interface SanityLikeClient {
+  fetch<T = unknown>(
+    query: string,
+    params?: Record<string, unknown>,
+  ): Promise<T>;
+  patch(id: string): {
+    set(attrs: Record<string, unknown>): {
+      commit(): Promise<unknown>;
+    };
+  };
+}
+
+/** A document within a Smartcat project (one per source file × target language). */
+declare interface SmartcatDocument {
+  /** Target document id, formatted `<fileGuid>_<languageNumber>`. */
+  id: string;
+  name?: string;
+  fullPath?: string;
+  filename?: string;
+  /** Shared id of the uploaded source file (the `<fileGuid>` part of `id`). */
+  externalId?: string;
+  sourceLanguage?: string;
+  targetLanguage?: string;
+  /** Per-stage progress. On documents these carry only `{id, progress}`; the
+   * stage names live on the project-level `workflowStages` (keyed by `id`). */
+  workflowStages?: SmartcatWorkflowStage[];
+}
+
+/**
+ * Sanity ↔ Smartcat language-code mapping.
+ *
+ * Sanity locale tags (`id`) don't always match the codes Smartcat understands
+ * (e.g. Sanity "PL-PL" vs Smartcat "pl"). The browser resolves the mapping from
+ * plugin config and stamps the relevant pairs onto the project; the thin
+ * Functions read them back. This module is dependency-free so it bundles into
+ * both the Studio and the Functions.
+ *
+ * The invariant: everything stored in Sanity uses the Sanity `id`; only the
+ * Smartcat HTTP calls use `smartcatLanguage`. So callers map forward (id → code)
+ * when talking to Smartcat and invert (code → id) when storing what comes back.
+ */
+declare interface SmartcatLanguageMapping {
+  sanityId: string;
+  smartcatLanguage: string;
+}
+
+/** Structural subset of SmartcatClient the progress refresh needs. */
+export declare interface SmartcatProgressClient {
+  getProject(projectId: string): Promise<SmartcatProject>;
+  /** Optional: trace every HTTP call so a timeout/error reaches the functionLog. */
+  setRequestLogger?(logger: RequestLogger): void;
+}
+
+/** A Smartcat project as returned by the API. */
+declare interface SmartcatProject {
+  id: string;
+  name?: string;
+  sourceLanguage?: string;
+  targetLanguages?: string[];
+  /** Project-level stages, where each `id` maps to a `stageType` (e.g. "translation"). */
+  workflowStages?: SmartcatWorkflowStage[];
+  documents?: SmartcatDocument[];
+}
+
+declare interface SmartcatWorkflowStage {
+  id?: string;
+  /** Stage type/name, e.g. "translation" / "editing" (casing varies by API). */
+  stageType?: string;
+  /** Human-readable stage name, when the API provides one. */
+  stageName?: string;
+  /** Completion percentage for this stage, 0–100. */
+  progress?: number;
+  /** Word counts, when present — useful for a weighted progress view. */
+  wordsTranslated?: number;
+  totalWordsCount?: number;
+}
+
+/**
+ * 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 declare function sourceIdPrefix(doc: SmartcatDocument): string;
+
+/**
+ * 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 declare interface StageProgress {
+  /** Stable key for the Sanity array item (always set by `stagesFromDocument`). */
+  _key?: string;
+  name: string;
+  /** 0–100, rounded. */
+  percent: number;
+}
+
+/** Maps a Smartcat document's workflow stages to display-ready stage progress. */
+export declare function stagesFromDocument(
+  doc: SmartcatDocument,
+  stageNames: Map<string, string>,
+): StageProgress[];
+
+/** Summarizes a progress array for status decisions and the dashboard. */
+export declare function summarizeCompletion(
+  progress: DocProgress[],
+): CompletionSummary;
+
+/** Builds a progress target's `_key` from its document + language. */
+export declare function targetKey(
+  sourceDocId: string,
+  language: string,
+): string;
+
+/** Average completion across a target's stages (0–100). */
+export declare function targetPercent(stages: StageProgress[]): number;
+
+export declare 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 {};

package/dist/progress.d.ts

@@ -0,0 +1,277 @@
+/**
+ * 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 declare function buildProgress(
+  items: ProjectItem[],
+  scProject: SmartcatProject,
+  previous: DocProgress[] | undefined,
+  now: string,
+  mappings?: SmartcatLanguageMapping[],
+): DocProgress[];
+
+/**
+ * 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 declare function buildStageNameMap(
+  scProject: SmartcatProject,
+): Map<string, string>;
+
+export declare 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;
+}
+
+export declare interface DocProgress {
+  _key: string;
+  sourceDocId: string;
+  title?: string;
+  targets: TargetProgress[];
+}
+
+/**
+ * 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 declare function hasConfirmedContent(stages: StageProgress[]): boolean;
+
+/** A target is complete when it has stages and every one is at 100%. */
+export declare function isTargetComplete(stages: StageProgress[]): boolean;
+
+/**
+ * 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 declare function itemsFromProject(project: {
+  items?: ProjectItemRef[];
+}): ProjectItem[];
+
+/** Sanitizes an arbitrary string into a stable, Sanity-safe array `_key`. */
+export declare function keyify(value: string): string;
+
+/** A project item we correlate Smartcat documents back to. */
+export declare interface ProjectItem {
+  _id: string;
+  title?: string;
+}
+
+/** 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. */
+declare interface ProjectItemRef {
+  _id?: string;
+  title?: string;
+  doc?: {
+    _id?: string;
+    title?: string;
+  } | null;
+}
+
+/** Sink for per-request tracing; attach with `SmartcatClient.setRequestLogger`. */
+declare type RequestLogger = (info: RequestLogInfo) => void;
+
+/** One Smartcat HTTP call, reported to a {@link RequestLogger} for tracing. */
+declare interface RequestLogInfo {
+  method: string;
+  /** Request path incl. query string (no host, no secrets). */
+  path: string;
+  status: number;
+  /** Raw response body text — carries Smartcat's error detail on failures. */
+  body: string;
+}
+
+/**
+ * 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 declare function runProgressSync(
+  options: RunProgressSyncOptions,
+): Promise<RunProgressSyncResult>;
+
+export declare interface RunProgressSyncOptions {
+  sanity: SanityLikeClient;
+  smartcat: SmartcatProgressClient;
+  /** `_id` of the `smartcat.translationProject` to refresh. */
+  projectId: string;
+  now?: () => string;
+}
+
+export declare interface RunProgressSyncResult {
+  summary: CompletionSummary;
+  /** Set when the Smartcat fetch failed (e.g. timed out); the run was recorded, not thrown. */
+  error?: string;
+}
+
+/** Minimal structural subset of @sanity/client used by the progress refresh. */
+export declare interface SanityLikeClient {
+  fetch<T = unknown>(
+    query: string,
+    params?: Record<string, unknown>,
+  ): Promise<T>;
+  patch(id: string): {
+    set(attrs: Record<string, unknown>): {
+      commit(): Promise<unknown>;
+    };
+  };
+}
+
+/** A document within a Smartcat project (one per source file × target language). */
+declare interface SmartcatDocument {
+  /** Target document id, formatted `<fileGuid>_<languageNumber>`. */
+  id: string;
+  name?: string;
+  fullPath?: string;
+  filename?: string;
+  /** Shared id of the uploaded source file (the `<fileGuid>` part of `id`). */
+  externalId?: string;
+  sourceLanguage?: string;
+  targetLanguage?: string;
+  /** Per-stage progress. On documents these carry only `{id, progress}`; the
+   * stage names live on the project-level `workflowStages` (keyed by `id`). */
+  workflowStages?: SmartcatWorkflowStage[];
+}
+
+/**
+ * Sanity ↔ Smartcat language-code mapping.
+ *
+ * Sanity locale tags (`id`) don't always match the codes Smartcat understands
+ * (e.g. Sanity "PL-PL" vs Smartcat "pl"). The browser resolves the mapping from
+ * plugin config and stamps the relevant pairs onto the project; the thin
+ * Functions read them back. This module is dependency-free so it bundles into
+ * both the Studio and the Functions.
+ *
+ * The invariant: everything stored in Sanity uses the Sanity `id`; only the
+ * Smartcat HTTP calls use `smartcatLanguage`. So callers map forward (id → code)
+ * when talking to Smartcat and invert (code → id) when storing what comes back.
+ */
+declare interface SmartcatLanguageMapping {
+  sanityId: string;
+  smartcatLanguage: string;
+}
+
+/** Structural subset of SmartcatClient the progress refresh needs. */
+export declare interface SmartcatProgressClient {
+  getProject(projectId: string): Promise<SmartcatProject>;
+  /** Optional: trace every HTTP call so a timeout/error reaches the functionLog. */
+  setRequestLogger?(logger: RequestLogger): void;
+}
+
+/** A Smartcat project as returned by the API. */
+declare interface SmartcatProject {
+  id: string;
+  name?: string;
+  sourceLanguage?: string;
+  targetLanguages?: string[];
+  /** Project-level stages, where each `id` maps to a `stageType` (e.g. "translation"). */
+  workflowStages?: SmartcatWorkflowStage[];
+  documents?: SmartcatDocument[];
+}
+
+declare interface SmartcatWorkflowStage {
+  id?: string;
+  /** Stage type/name, e.g. "translation" / "editing" (casing varies by API). */
+  stageType?: string;
+  /** Human-readable stage name, when the API provides one. */
+  stageName?: string;
+  /** Completion percentage for this stage, 0–100. */
+  progress?: number;
+  /** Word counts, when present — useful for a weighted progress view. */
+  wordsTranslated?: number;
+  totalWordsCount?: number;
+}
+
+/**
+ * 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 declare function sourceIdPrefix(doc: SmartcatDocument): string;
+
+/**
+ * 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 declare interface StageProgress {
+  /** Stable key for the Sanity array item (always set by `stagesFromDocument`). */
+  _key?: string;
+  name: string;
+  /** 0–100, rounded. */
+  percent: number;
+}
+
+/** Maps a Smartcat document's workflow stages to display-ready stage progress. */
+export declare function stagesFromDocument(
+  doc: SmartcatDocument,
+  stageNames: Map<string, string>,
+): StageProgress[];
+
+/** Summarizes a progress array for status decisions and the dashboard. */
+export declare function summarizeCompletion(
+  progress: DocProgress[],
+): CompletionSummary;
+
+/** Builds a progress target's `_key` from its document + language. */
+export declare function targetKey(
+  sourceDocId: string,
+  language: string,
+): string;
+
+/** Average completion across a target's stages (0–100). */
+export declare function targetPercent(stages: StageProgress[]): number;
+
+export declare 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 {};

package/dist/progress.js

@@ -0,0 +1,16 @@
+import { buildProgress, buildStageNameMap, hasConfirmedContent, isTargetComplete, itemsFromProject, keyify, runProgressSync, sourceIdPrefix, stagesFromDocument, summarizeCompletion, targetKey, targetPercent } from "./_chunks-es/index.js";
+export {
+  buildProgress,
+  buildStageNameMap,
+  hasConfirmedContent,
+  isTargetComplete,
+  itemsFromProject,
+  keyify,
+  runProgressSync,
+  sourceIdPrefix,
+  stagesFromDocument,
+  summarizeCompletion,
+  targetKey,
+  targetPercent
+};
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}