@smartcat/sanity-functions 1.0.0

package/bin/cli.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+// bin/cli.ts
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { createClient } from "@sanity/client";
+
+// src/cli/resolve.ts
+function isComplete(creds) {
+  return Boolean(creds?.server && creds?.workspaceId && creds?.apiKey);
+}
+function credsFromEnv(env) {
+  const creds = {
+    server: env.SMARTCAT_API_SERVER ?? "",
+    workspaceId: env.SMARTCAT_WORKSPACE_ID ?? "",
+    apiKey: env.SMARTCAT_API_KEY ?? ""
+  };
+  return isComplete(creds) ? creds : null;
+}
+async function resolveCreds(env, readConfig, prompt) {
+  const fromEnv = credsFromEnv(env);
+  if (fromEnv) return fromEnv;
+  const fromConfig = readConfig();
+  if (isComplete(fromConfig)) return fromConfig;
+  return prompt();
+}
+function resolveSanityAuth(env) {
+  const token = env.SANITY_AUTH_TOKEN;
+  return token ? { mode: "token", token } : { mode: "login" };
+}
+function resolveProjectId(env, flag, readCliConfig) {
+  if (flag) return flag;
+  const fromEnv = env.SANITY_STUDIO_PROJECT_ID || env.SANITY_PROJECT_ID;
+  if (fromEnv) return fromEnv;
+  const fromConfig = readCliConfig();
+  if (fromConfig) return fromConfig;
+  throw new Error(
+    "Could not resolve a Sanity project id. Pass --project <id>, set SANITY_STUDIO_PROJECT_ID (or SANITY_PROJECT_ID), or configure it in sanity.cli.ts."
+  );
+}
+function isUnknownVersion(version) {
+  return version === null || version === "unknown";
+}
+function skewWarning(pluginVersion, deployedVersion) {
+  if (isUnknownVersion(pluginVersion) || isUnknownVersion(deployedVersion)) return null;
+  if (pluginVersion === deployedVersion) return null;
+  return `Version mismatch: @smartcat/sanity-plugin is v${pluginVersion} but the deployed Functions are v${deployedVersion}. Redeploy with the deploy CLI to bring them in sync.`;
+}
+
+// src/cli/deploy.ts
+async function deploy(deps) {
+  const creds = await resolveCreds(deps.env, deps.readSmartcatConfig, async () => {
+    const entered = await deps.promptSmartcatCreds();
+    deps.writeSmartcatConfig(entered);
+    return entered;
+  });
+  const sanityAuth = resolveSanityAuth(deps.env);
+  const projectId = resolveProjectId(deps.env, deps.args.project, deps.readSanityCliConfig);
+  const childEnv = {
+    ...deps.env,
+    SMARTCAT_API_SERVER: creds.server,
+    SMARTCAT_WORKSPACE_ID: creds.workspaceId,
+    SMARTCAT_API_KEY: creds.apiKey
+  };
+  if (sanityAuth.mode === "token") childEnv.SANITY_AUTH_TOKEN = sanityAuth.token;
+  const stack = deps.args.stack || deps.env.SANITY_STACK || "production";
+  const cliArgs = ["blueprints", "deploy", "--project-id", projectId, "--stack", stack];
+  const result = await deps.runSanityCli(cliArgs, { cwd: deps.blueprintCwd, env: childEnv });
+  if (result.stdout) deps.log(result.stdout);
+  if (result.code !== 0) {
+    if (result.stderr) deps.log(result.stderr);
+    if (sanityAuth.mode === "login") {
+      deps.log("Run: npx sanity login (or set SANITY_AUTH_TOKEN) and re-run deploy.");
+    }
+    return { code: result.code };
+  }
+  const deployedVersion = await deps.fetchDeployedVersion({ projectId, sanityAuth });
+  const warning = skewWarning(deps.installedPluginVersion, deployedVersion);
+  if (warning) deps.log(warning);
+  return { code: 0 };
+}
+
+// bin/cli.ts
+var packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+var cwd = process.cwd();
+var smartcatConfigPath = path.join(cwd, ".smartcat", "credentials.json");
+function parseArgs(argv) {
+  const rest = [...argv];
+  const command = rest[0] && !rest[0].startsWith("-") ? rest.shift() : void 0;
+  const out = { command };
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--project" && rest[i + 1] !== void 0) out.project = rest[++i];
+    else if (rest[i] === "--stack" && rest[i + 1] !== void 0) out.stack = rest[++i];
+  }
+  return out;
+}
+function readSmartcatConfig() {
+  if (!existsSync(smartcatConfigPath)) return null;
+  try {
+    return JSON.parse(readFileSync(smartcatConfigPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeSmartcatConfig(creds) {
+  mkdirSync(path.dirname(smartcatConfigPath), { recursive: true });
+  writeFileSync(smartcatConfigPath, `${JSON.stringify(creds, null, 2)}
+`);
+}
+async function promptSmartcatCreds() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log(
+      "No Smartcat credentials found (SMARTCAT_API_SERVER/_WORKSPACE_ID/_API_KEY). Enter them once \u2014 they will be saved to .smartcat/credentials.json (gitignored)."
+    );
+    const server = await rl.question("Smartcat API server (e.g. us.smartcat.com): ");
+    const workspaceId = await rl.question("Smartcat workspace id: ");
+    const apiKey = await rl.question("Smartcat API key: ");
+    return { server: server.trim(), workspaceId: workspaceId.trim(), apiKey: apiKey.trim() };
+  } finally {
+    rl.close();
+  }
+}
+function readSanityCliConfig() {
+  for (const file of ["sanity.cli.ts", "sanity.config.ts"]) {
+    const filePath = path.join(cwd, file);
+    if (!existsSync(filePath)) continue;
+    const match = readFileSync(filePath, "utf8").match(/projectId\s*:\s*['"]([a-z0-9]+)['"]/i);
+    if (match) return match[1];
+  }
+  return null;
+}
+function runSanityCli(args, opts) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("npx", ["sanity@latest", ...args], { cwd: opts.cwd, env: opts.env, shell: true });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+async function fetchDeployedVersion(opts) {
+  if (opts.sanityAuth.mode !== "token") return null;
+  try {
+    const dataset = process.env.SANITY_STUDIO_DATASET || process.env.SANITY_DATASET || "production";
+    const client = createClient({
+      projectId: opts.projectId,
+      dataset,
+      apiVersion: "2025-02-01",
+      token: opts.sanityAuth.token,
+      useCdn: false
+    });
+    const version = await client.fetch('*[_id == "smartcat.settings"][0].addonVersion');
+    return version ?? null;
+  } catch {
+    return null;
+  }
+}
+function readInstalledPluginVersion() {
+  try {
+    const require2 = createRequire(path.join(cwd, "package.json"));
+    const pkgPath = require2.resolve("@smartcat/sanity-plugin/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const { command, project, stack } = parseArgs(process.argv.slice(2));
+  if (command !== "deploy") {
+    console.error(
+      'Usage: smartcat-sanity-functions deploy [--project <id>] [--stack <name>, defaults to "production"]'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const deps = {
+    env: process.env,
+    args: { project, stack },
+    blueprintCwd: packageRoot,
+    readSmartcatConfig,
+    writeSmartcatConfig,
+    promptSmartcatCreds,
+    readSanityCliConfig,
+    runSanityCli,
+    fetchDeployedVersion,
+    installedPluginVersion: readInstalledPluginVersion(),
+    log: (line) => console.log(line)
+  };
+  const result = await deploy(deps);
+  process.exitCode = result.code;
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/bin/cli.ts

@@ -0,0 +1,162 @@
+import {createRequire} from 'node:module'
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs'
+import path from 'node:path'
+import {fileURLToPath} from 'node:url'
+import {spawn} from 'node:child_process'
+import {createInterface} from 'node:readline/promises'
+import {createClient} from '@sanity/client'
+import {deploy} from '../src/cli/deploy'
+import type {DeployDeps, SanityCliResult} from '../src/cli/deploy'
+import type {SmartcatCreds} from '../src/cli/resolve'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const cwd = process.cwd()
+const smartcatConfigPath = path.join(cwd, '.smartcat', 'credentials.json')
+
+function parseArgs(argv: string[]): {command?: string; project?: string; stack?: string} {
+  const rest = [...argv]
+  const command = rest[0] && !rest[0].startsWith('-') ? rest.shift() : undefined
+  const out: {command?: string; project?: string; stack?: string} = {command}
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--project' && rest[i + 1] !== undefined) out.project = rest[++i]
+    else if (rest[i] === '--stack' && rest[i + 1] !== undefined) out.stack = rest[++i]
+  }
+  return out
+}
+
+/** Reads Smartcat creds saved by a previous interactive run. `null` if missing/unreadable. */
+function readSmartcatConfig(): Partial<SmartcatCreds> | null {
+  if (!existsSync(smartcatConfigPath)) return null
+  try {
+    return JSON.parse(readFileSync(smartcatConfigPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** Saves prompted Smartcat creds to the gitignored `.smartcat/credentials.json`. */
+function writeSmartcatConfig(creds: SmartcatCreds): void {
+  mkdirSync(path.dirname(smartcatConfigPath), {recursive: true})
+  writeFileSync(smartcatConfigPath, `${JSON.stringify(creds, null, 2)}\n`)
+}
+
+async function promptSmartcatCreds(): Promise<SmartcatCreds> {
+  const rl = createInterface({input: process.stdin, output: process.stdout})
+  try {
+    console.log(
+      'No Smartcat credentials found (SMARTCAT_API_SERVER/_WORKSPACE_ID/_API_KEY). ' +
+        'Enter them once — they will be saved to .smartcat/credentials.json (gitignored).',
+    )
+    const server = await rl.question('Smartcat API server (e.g. us.smartcat.com): ')
+    const workspaceId = await rl.question('Smartcat workspace id: ')
+    const apiKey = await rl.question('Smartcat API key: ')
+    return {server: server.trim(), workspaceId: workspaceId.trim(), apiKey: apiKey.trim()}
+  } finally {
+    rl.close()
+  }
+}
+
+/** Best-effort Sanity project id extraction from the customer's `sanity.cli.ts`/`sanity.config.ts`
+ * in the current working directory. Regex-based (no TS execution) since either file may import
+ * things this CLI has no business loading. */
+function readSanityCliConfig(): string | null {
+  for (const file of ['sanity.cli.ts', 'sanity.config.ts']) {
+    const filePath = path.join(cwd, file)
+    if (!existsSync(filePath)) continue
+    const match = readFileSync(filePath, 'utf8').match(/projectId\s*:\s*['"]([a-z0-9]+)['"]/i)
+    if (match) return match[1]
+  }
+  return null
+}
+
+/** Shells out to the Sanity CLI via `npx sanity@latest` — avoids `@sanity/cli` as a direct
+ * dependency of this package; customers already have Sanity CLI access via `npx`. */
+function runSanityCli(args: string[], opts: {cwd: string; env: NodeJS.ProcessEnv}): Promise<SanityCliResult> {
+  return new Promise((resolve, reject) => {
+    // `shell: true` is required for `npx` to resolve on Windows (spawning `npx.cmd` directly
+    // without a shell fails with EINVAL there). Args come from resolved config/flags supplied by
+    // whoever is running their own deploy — not an attacker-controlled boundary.
+    const child = spawn('npx', ['sanity@latest', ...args], {cwd: opts.cwd, env: opts.env, shell: true})
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdout += chunk
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', (code) => resolve({code: code ?? 1, stdout, stderr}))
+  })
+}
+
+/** Reads the version the deployed Functions stamped onto `smartcat.settings`. Only attempted in
+ * token mode — an interactive `sanity login` session isn't a bearer token this CLI can reuse to
+ * query the content API directly, so the skew check is skipped rather than skipping the deploy. */
+async function fetchDeployedVersion(opts: {
+  projectId: string
+  sanityAuth: {mode: 'token'; token: string} | {mode: 'login'}
+}): Promise<string | null> {
+  if (opts.sanityAuth.mode !== 'token') return null
+  try {
+    const dataset = process.env.SANITY_STUDIO_DATASET || process.env.SANITY_DATASET || 'production'
+    const client = createClient({
+      projectId: opts.projectId,
+      dataset,
+      apiVersion: '2025-02-01',
+      token: opts.sanityAuth.token,
+      useCdn: false,
+    })
+    const version = await client.fetch<string | null>('*[_id == "smartcat.settings"][0].addonVersion')
+    return version ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Installed `@smartcat/sanity-plugin` version, resolved from the *customer's* `node_modules`
+ * (relative to `cwd`, not this package's own install location). `null` if not found. */
+function readInstalledPluginVersion(): string | null {
+  try {
+    const require = createRequire(path.join(cwd, 'package.json'))
+    const pkgPath = require.resolve('@smartcat/sanity-plugin/package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+async function main(): Promise<void> {
+  const {command, project, stack} = parseArgs(process.argv.slice(2))
+
+  if (command !== 'deploy') {
+    console.error(
+      'Usage: smartcat-sanity-functions deploy [--project <id>] [--stack <name>, defaults to "production"]',
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const deps: DeployDeps = {
+    env: process.env,
+    args: {project, stack},
+    blueprintCwd: packageRoot,
+    readSmartcatConfig,
+    writeSmartcatConfig,
+    promptSmartcatCreds,
+    readSanityCliConfig,
+    runSanityCli,
+    fetchDeployedVersion,
+    installedPluginVersion: readInstalledPluginVersion(),
+    log: (line) => console.log(line),
+  }
+
+  const result = await deploy(deps)
+  process.exitCode = result.code
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err)
+  process.exitCode = 1
+})

package/functions/smartcat-export/index.ts

@@ -0,0 +1,34 @@
+import {documentEventHandler} from '@sanity/functions'
+import {createClient} from '@sanity/client'
+import {SmartcatClient} from '@smartcat/sanity-plugin/smartcat'
+import {runExportUpload} from '@smartcat/sanity-plugin/export'
+
+/**
+ * Thin export Function: triggered when a project's status becomes "queued".
+ * The browser has already serialized content into the project's `outbox`; this
+ * function just creates the Smartcat project and uploads those files.
+ *
+ * Requires SMARTCAT_API_SERVER, SMARTCAT_WORKSPACE_ID, SMARTCAT_API_KEY env vars.
+ */
+export const handler = documentEventHandler<{_id: string}>(async ({context, event}) => {
+  const sanity = createClient({...context.clientOptions, apiVersion: '2025-02-01'})
+  const smartcat = new SmartcatClient({
+    server: process.env.SMARTCAT_API_SERVER as string,
+    workspaceId: process.env.SMARTCAT_WORKSPACE_ID as string,
+    apiKey: process.env.SMARTCAT_API_KEY as string,
+  })
+
+  try {
+    const result = await runExportUpload({sanity, smartcat, projectId: event.data._id})
+    console.log(
+      `Exported ${event.data._id} → Smartcat ${result.smartcatProjectId} ` +
+        `(${result.created} created, ${result.updated} updated, ${result.deleted} deleted, ${result.failed} failed)`,
+    )
+  } catch (err) {
+    // The failure is already recorded on the document (status "error" + lastError)
+    // by runExportUpload. Swallow it here so the platform does NOT retry: createProject
+    // is not idempotent, and a retry can duplicate the Smartcat project or overwrite a
+    // concurrent success with a stale error. The user re-sends to retry.
+    console.error(`Export failed for ${event.data._id}:`, err instanceof Error ? err.message : err)
+  }
+})

package/functions/smartcat-import/index.ts

@@ -0,0 +1,35 @@
+import {documentEventHandler} from '@sanity/functions'
+import {createClient} from '@sanity/client'
+import {SmartcatClient} from '@smartcat/sanity-plugin/smartcat'
+import {runImportDownload} from '@smartcat/sanity-plugin/import'
+
+/**
+ * Thin import Function: triggered when a project's status becomes "importing".
+ * Downloads each translated document's LocJSON from Smartcat into the project's
+ * `inbox` and sets status to "downloaded". The browser then turns the inbox into
+ * locale-variant documents.
+ *
+ * Requires SMARTCAT_API_SERVER, SMARTCAT_WORKSPACE_ID, SMARTCAT_API_KEY env vars.
+ */
+export const handler = documentEventHandler<{_id: string}>(async ({context, event}) => {
+  const sanity = createClient({...context.clientOptions, apiVersion: '2025-02-01'})
+  const smartcat = new SmartcatClient({
+    server: process.env.SMARTCAT_API_SERVER as string,
+    workspaceId: process.env.SMARTCAT_WORKSPACE_ID as string,
+    apiKey: process.env.SMARTCAT_API_KEY as string,
+  })
+
+  const result = await runImportDownload({
+    sanity,
+    smartcat,
+    projectId: event.data._id,
+    // Mirror the run's log into the Function console, so `sanity functions
+    // logs smartcat-import` tells the whole story (batch sizes, timings,
+    // fallbacks) without reading the project document.
+    onLog: (line) => console.log(`[${line.level}] ${line.message}`),
+  })
+  console.log(
+    `Downloaded ${result.downloaded} translated file(s) for ${event.data._id}` +
+      (result.remaining ? ` (${result.remaining} deferred — run Import again to continue)` : ''),
+  )
+})

package/functions/smartcat-progress/index.ts

@@ -0,0 +1,35 @@
+import {documentEventHandler} from '@sanity/functions'
+import {createClient} from '@sanity/client'
+import {SmartcatClient} from '@smartcat/sanity-plugin/smartcat'
+import {runProgressSync} from '@smartcat/sanity-plugin/progress'
+
+/**
+ * Thin progress Function: triggered when the dashboard bumps a project's
+ * `progressRequestedAt` (on page load or the "Refresh progress" button).
+ * Fetches the Smartcat project and mirrors its per-document, per-stage progress
+ * onto the project's `progress` array. Read-only with respect to Smartcat — it
+ * never downloads or creates variants.
+ *
+ * Requires SMARTCAT_API_SERVER, SMARTCAT_WORKSPACE_ID, SMARTCAT_API_KEY env vars.
+ */
+export const handler = documentEventHandler<{_id: string}>(async ({context, event}) => {
+  const sanity = createClient({...context.clientOptions, apiVersion: '2025-02-01'})
+  const smartcat = new SmartcatClient({
+    server: process.env.SMARTCAT_API_SERVER as string,
+    workspaceId: process.env.SMARTCAT_WORKSPACE_ID as string,
+    apiKey: process.env.SMARTCAT_API_KEY as string,
+    // Abort the Smartcat call at 9m30s — safely under this Function's 10-minute
+    // hard timeout — so a slow project fetch fails fast and runProgressSync can
+    // record it (functionLog + lastError) before the platform would kill the run.
+    requestTimeoutMs: 570_000,
+  })
+
+  const {summary, error} = await runProgressSync({sanity, smartcat, projectId: event.data._id})
+  if (error) {
+    console.error(`Progress sync failed for ${event.data._id}: ${error}`)
+  } else {
+    console.log(
+      `Synced progress for ${event.data._id}: ${summary.complete}/${summary.total} targets complete`,
+    )
+  }
+})

package/functions/smartcat-templates/index.ts

@@ -0,0 +1,33 @@
+import {documentEventHandler} from '@sanity/functions'
+import {createClient} from '@sanity/client'
+import {SmartcatClient} from '@smartcat/sanity-plugin/smartcat'
+import {runTemplatesSync} from '@smartcat/sanity-plugin/templates'
+import packageJson from '../../package.json'
+
+/**
+ * Thin templates Function: triggered when the Studio bumps the settings
+ * singleton's `templatesRequestedAt` (on first load or when a create dialog
+ * opens). Fetches the workspace's project templates from Smartcat and caches
+ * them onto `smartcat.settings`. Read-only with respect to Smartcat.
+ *
+ * Also stamps `addonVersion` (this package's own version) onto the settings singleton on
+ * every run — the deploy CLI's skew check reads it back to compare against the Studio's
+ * installed `@smartcat/sanity-plugin` version. This is the only Function that already
+ * patches the settings doc, so it doubles as the version heartbeat; the stamp only refreshes
+ * when this Function actually fires (Studio init / create-dialog open), not immediately on
+ * deploy.
+ *
+ * Requires SMARTCAT_API_SERVER, SMARTCAT_WORKSPACE_ID, SMARTCAT_API_KEY env vars.
+ */
+export const handler = documentEventHandler<{_id: string}>(async ({context, event}) => {
+  const sanity = createClient({...context.clientOptions, apiVersion: '2025-02-01'})
+  const smartcat = new SmartcatClient({
+    server: process.env.SMARTCAT_API_SERVER as string,
+    workspaceId: process.env.SMARTCAT_WORKSPACE_ID as string,
+    apiKey: process.env.SMARTCAT_API_KEY as string,
+  })
+
+  const {count} = await runTemplatesSync({sanity, smartcat, settingsId: event.data._id})
+  await sanity.patch(event.data._id).set({addonVersion: packageJson.version}).commit()
+  console.log(`Synced ${count} Smartcat templates (addon v${packageJson.version})`)
+})

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@smartcat/sanity-functions",
+  "version": "1.0.0",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "smartcat-sanity-functions": "./bin/cli.js"
+  },
+  "files": [
+    "functions",
+    "sanity.blueprint.ts",
+    "bin"
+  ],
+  "dependencies": {
+    "@smartcat/sanity-plugin": "1.0.0",
+    "@sanity/blueprints": "^0.20.1",
+    "@sanity/functions": "^1.3.1",
+    "@sanity/client": "^7.22.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "peerDependencies": {},
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "npm run build:cli",
+    "build:cli": "esbuild bin/cli.ts --bundle --platform=node --format=esm --outfile=bin/cli.js --packages=external --banner:js=\"#!/usr/bin/env node\""
+  }
+}

package/sanity.blueprint.ts

@@ -0,0 +1,88 @@
+import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
+
+const PROJECT_TYPE = 'smartcat.translationProject'
+const SETTINGS_TYPE = 'smartcat.settings'
+
+/**
+ * Shared Smartcat credentials for all three Functions (Option B): declared once
+ * here and resolved from the deploy-time environment, so the secret stays out of
+ * this committed file. Make sure these are present in your shell/CI (e.g. sourced
+ * from `.env`) when running `sanity blueprints deploy`.
+ */
+const smartcatEnv = {
+  SMARTCAT_API_SERVER: process.env.SMARTCAT_API_SERVER as string,
+  SMARTCAT_WORKSPACE_ID: process.env.SMARTCAT_WORKSPACE_ID as string,
+  SMARTCAT_API_KEY: process.env.SMARTCAT_API_KEY as string,
+}
+
+export default defineBlueprint({
+  resources: [
+    defineDocumentFunction({
+      name: 'smartcat-export',
+      // Uploads are batched (50 files per request) and parallelized (concurrency
+      // 10), so this 900s timeout has ample headroom even for a few hundred files.
+      timeout: 900,
+      env: smartcatEnv,
+      event: {
+        on: ['create', 'update'],
+        // Fires only on the transition INTO "queued" — not on every update while
+        // queued. The handler patches the project mid-run (e.g. persisting
+        // smartcatProjectId before uploads) while status is still "queued"; without
+        // the delta guard those writes re-trigger the export, spawning concurrent
+        // runs that collide on Smartcat (409 "document already exists").
+        filter: `_type == "${PROJECT_TYPE}" && status == "queued" && delta::changedAny(status)`,
+        projection: '{_id}',
+      },
+    }),
+    defineDocumentFunction({
+      name: 'smartcat-import',
+      // Downloads are batched (50 docs per Smartcat task, 4 tasks in parallel)
+      // and the run self-limits to a 10-minute budget, deferring the rest to
+      // the next cycle — so it always exits well before this hard timeout.
+      timeout: 900,
+      env: smartcatEnv,
+      event: {
+        on: ['create', 'update'],
+        // Fires only on the transition INTO "importing" (dashboard click or
+        // auto-continue). The delta guard stops unrelated patches (e.g. the
+        // progress Function writing while an import is running) from spawning
+        // duplicate concurrent runs. The handler always leaves "importing"
+        // (→ "downloaded"/"error") thanks to its internal time budget.
+        filter: `_type == "${PROJECT_TYPE}" && status == "importing" && delta::changedAny(status)`,
+        projection: '{_id}',
+      },
+    }),
+    defineDocumentFunction({
+      name: 'smartcat-progress',
+      // Read-only: one getProject call plus a patch. Usually quick, but a project
+      // with many documents returns a large unpaginated payload that can be slow,
+      // and the call has no in-code timeout — give it 10 minutes of headroom.
+      timeout: 600,
+      env: smartcatEnv,
+      event: {
+        on: ['create', 'update'],
+        // Fires when the dashboard bumps `progressRequestedAt` (page load / refresh).
+        // The handler writes `progress`/`progressSyncedAt` but never touches
+        // `progressRequestedAt`, so delta::changedAny stops it re-triggering.
+        filter: `_type == "${PROJECT_TYPE}" && defined(smartcatProjectId) && delta::changedAny(progressRequestedAt)`,
+        projection: '{_id}',
+      },
+    }),
+    defineDocumentFunction({
+      name: 'smartcat-templates',
+      // Read-only: one getTemplates call plus a patch. The default 10s is plenty.
+      timeout: 30,
+      env: smartcatEnv,
+      event: {
+        on: ['create', 'update'],
+        // Fires whenever a refresh is pending — on the singleton's first creation
+        // (no sync yet) or when the Studio bumps `templatesRequestedAt` past the
+        // last sync. The handler writes a later `templatesSyncedAt`, so the
+        // condition flips false on its own write and it won't re-trigger.
+        // (delta::changedAny is avoided here: it doesn't match the create event.)
+        filter: `_type == "${SETTINGS_TYPE}" && defined(templatesRequestedAt) && (!defined(templatesSyncedAt) || templatesRequestedAt > templatesSyncedAt)`,
+        projection: '{_id}',
+      },
+    }),
+  ],
+})