@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/src/lib/workflow.ts

@@ -0,0 +1,48 @@
+/**
+ * Workflow selection for new projects. A project stores a single `workflow`
+ * string: either `template:<smartcatTemplateId>` or one of the standard presets.
+ * The browser sets it at creation; the export Function decodes it into the
+ * Smartcat `createProject` params (a template id, or explicit workflow stages).
+ *
+ * Dependency-free so it bundles into the thin export Function.
+ */
+
+export const TEMPLATE_PREFIX = 'template:'
+export const STANDARD_AI_HUMAN = 'standard:ai-human'
+export const STANDARD_AI = 'standard:ai'
+
+/** Backwards-compatible default: matches the previous hard-coded behavior. */
+export const DEFAULT_WORKFLOW = STANDARD_AI_HUMAN
+
+/** Labels for the two standard presets (rendered under the "Standard workflows" group). */
+export const STANDARD_WORKFLOW_OPTIONS: {value: string; label: string}[] = [
+  {value: STANDARD_AI_HUMAN, label: 'AI Translation + Human Review'},
+  {value: STANDARD_AI, label: 'AI Translation'},
+]
+
+export interface WorkflowCreateParams {
+  templateId?: string
+  workflowStages?: string[]
+}
+
+/**
+ * Whether a `workflow` value is currently selectable: the standard presets always
+ * are; a `template:<id>` is valid only while that id still exists in the cached
+ * template list. Empty / unknown values are invalid (no selection).
+ */
+export function isWorkflowValid(workflow: string, templateIds: string[]): boolean {
+  if (workflow === STANDARD_AI_HUMAN || workflow === STANDARD_AI) return true
+  if (workflow.startsWith(TEMPLATE_PREFIX)) {
+    return templateIds.includes(workflow.slice(TEMPLATE_PREFIX.length))
+  }
+  return false
+}
+
+/** Decodes a stored `workflow` value into Smartcat create-project params. */
+export function resolveWorkflowCreateParams(workflow?: string): WorkflowCreateParams {
+  if (workflow && workflow.startsWith(TEMPLATE_PREFIX)) {
+    return {templateId: workflow.slice(TEMPLATE_PREFIX.length)}
+  }
+  if (workflow === STANDARD_AI) return {workflowStages: ['translation']}
+  return {workflowStages: ['translation', 'postediting']}
+}

package/src/lib/zip.fixtures.ts

@@ -0,0 +1,75 @@
+/**
+ * Test-only ZIP builder: assembles a minimal, structurally valid archive
+ * (local headers + central directory + EOCD) for exercising the reader.
+ * CRCs are zeroed — the reader doesn't verify them, and neither do we.
+ */
+
+export interface ZipFixtureEntry {
+  name: string
+  content: string
+  /** 0 = stored (default), 8 = deflate. */
+  method?: 0 | 8
+}
+
+export async function buildZip(entries: ZipFixtureEntry[]): Promise<Uint8Array> {
+  const encoder = new TextEncoder()
+  const chunks: Uint8Array[] = []
+  const central: Uint8Array[] = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const method = entry.method ?? 0
+    const nameBytes = encoder.encode(entry.name)
+    const raw = encoder.encode(entry.content)
+    const data = method === 8 ? await deflateRaw(raw) : raw
+
+    const local = new Uint8Array(30 + nameBytes.length)
+    const lv = new DataView(local.buffer)
+    lv.setUint32(0, 0x04034b50, true)
+    lv.setUint16(4, 20, true) // version needed
+    lv.setUint16(8, method, true)
+    lv.setUint32(18, data.length, true) // compressed size
+    lv.setUint32(22, raw.length, true) // uncompressed size
+    lv.setUint16(26, nameBytes.length, true)
+    local.set(nameBytes, 30)
+    chunks.push(local, data)
+
+    const dir = new Uint8Array(46 + nameBytes.length)
+    const dv = new DataView(dir.buffer)
+    dv.setUint32(0, 0x02014b50, true)
+    dv.setUint16(4, 20, true) // version made by
+    dv.setUint16(6, 20, true) // version needed
+    dv.setUint16(10, method, true)
+    dv.setUint32(20, data.length, true)
+    dv.setUint32(24, raw.length, true)
+    dv.setUint16(28, nameBytes.length, true)
+    dv.setUint32(42, offset, true) // local header offset
+    dir.set(nameBytes, 46)
+    central.push(dir)
+
+    offset += local.length + data.length
+  }
+
+  const centralSize = central.reduce((sum, c) => sum + c.length, 0)
+  const eocd = new Uint8Array(22)
+  const ev = new DataView(eocd.buffer)
+  ev.setUint32(0, 0x06054b50, true)
+  ev.setUint16(8, entries.length, true) // entries on this disk
+  ev.setUint16(10, entries.length, true) // entries total
+  ev.setUint32(12, centralSize, true)
+  ev.setUint32(16, offset, true) // central directory offset
+
+  const total = offset + centralSize + eocd.length
+  const out = new Uint8Array(total)
+  let pos = 0
+  for (const chunk of [...chunks, ...central, eocd]) {
+    out.set(chunk, pos)
+    pos += chunk.length
+  }
+  return out
+}
+
+async function deflateRaw(data: Uint8Array): Promise<Uint8Array> {
+  const stream = new Blob([data.slice()]).stream().pipeThrough(new CompressionStream('deflate-raw'))
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}

package/src/lib/zip.test.ts

@@ -0,0 +1,110 @@
+import {describe, expect, it} from 'vitest'
+import {isZip, unzip, unzipText} from './zip'
+import {buildZip} from './zip.fixtures'
+
+/**
+ * A REAL Smartcat-format export archive: generated with the exact library and
+ * settings production uses — Smartcat.Fork.SharpZipLib 1.5.1, `ZipOutputStream
+ * { UseZip64 = On }`, streamed entries with `IsUnicodeText = true` (see
+ * ExportDocumentsProcessor.cs:1525 in the smartcat repo). Forced ZIP64 means
+ * every central-directory entry carries 0xFFFFFFFF size placeholders with the
+ * real values in ZIP64 extra fields — the format that a non-ZIP64 reader fails
+ * on (which silently degraded every batch to per-document fallback in v1).
+ */
+const SMARTCAT_ZIP64_ARCHIVE_B64 =
+  'UEsDBC0AAAgIAAeK6FzGlJGm//////////8iABQAcGFnZS9BYm91dC1hYmMxMjM0NShmci1GUikubG9janNvbgEAEAB8AAAAAAAA' +
+  'AGwAAAAAAAAAFYsxDsMgEAT/sjUukjiNS1fJGyIKgk8RNuEsOKREiL/7vNVqZ7Zhz7xTlkAFU8NvKC4F+Z99YV+/lOS5YIJ7+8v1' +
+  'Nt4H0qB3g6qefl4NG6kPCRIJBoVr9qQAD4qRYQ3E5Q/JOc2cVuWw3fYDUEsDBC0AAAgIAAeK6Fxyl2Ox//////////8iABQAcGFn' +
+  'ZS9Iw7ZtZS1kZWY2Nzg5MChmci1GUikubG9janNvbgEAEAB7AAAAAAAAAHEAAAAAAAAAFYsxDsIwEAT/srUjUZGQH1BQp0AuotwF' +
+  'WQQ7Op8lkOVv8QE+xmWr1exsxS5pZ9HAGWPFu8tzDPo5OqWlvDjqlTCCeD33w+XUrRa05lDMs8+94snmQ4NuDIeciixsA6YkG8E7' +
+  '6CwP1gPdft9IDN98+wNQSwMELQAACAgAB4roXGMJtzf//////////ysAFAByZXNwb25zaXZlSW1hZ2UvQWx0LTk5ODg3NzY2KGZy' +
+  'LUZSKS5sb2Nqc29uAQAQAEUAAAAAAAAAQQAAAAAAAACrViooyi9ILSrJTC1WsqpWqtAtTszLLKkEsVPyk0tzU/NKPFOUrJQsLS0s' +
+  'zM3NzHQTgUCptlZHqRSoDqgnOrYWAFBLAQIzAC0AAAgIAAeK6FzGlJGm//////////8iABQAAAAAAAAAAAAAAAAAAABwYWdlL0Fi' +
+  'b3V0LWFiYzEyMzQ1KGZyLUZSKS5sb2Nqc29uAQAQAHwAAAAAAAAAbAAAAAAAAABQSwECMwAtAAAICAAHiuhccpdjsf//////////' +
+  'IgAUAAAAAAAAAAAAAADAAAAAcGFnZS9Iw7ZtZS1kZWY2Nzg5MChmci1GUikubG9janNvbgEAEAB7AAAAAAAAAHEAAAAAAAAAUEsB' +
+  'AjMALQAACAgAB4roXGMJtzf//////////ysAFAAAAAAAAAAAAAAAhQEAAHJlc3BvbnNpdmVJbWFnZS9BbHQtOTk4ODc3NjYoZnIt' +
+  'RlIpLmxvY2pzb24BABAARQAAAAAAAABBAAAAAAAAAFBLBQYAAAAAAwADADUBAAAjAgAAAAA='
+
+function fromBase64(b64: string): Uint8Array {
+  const bin = atob(b64)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+describe('isZip', () => {
+  it('recognizes the PK magic', async () => {
+    const zip = await buildZip([{name: 'a.txt', content: 'hello'}])
+    expect(isZip(zip)).toBe(true)
+  })
+
+  it('rejects plain text and short payloads', () => {
+    expect(isZip(new TextEncoder().encode('{"units":[]}'))).toBe(false)
+    expect(isZip(new Uint8Array([0x50, 0x4b]))).toBe(false)
+  })
+})
+
+describe('unzip', () => {
+  it('parses a real Smartcat production-format archive (SharpZipLib, forced ZIP64)', async () => {
+    const bytes = fromBase64(SMARTCAT_ZIP64_ARCHIVE_B64)
+    expect(isZip(bytes)).toBe(true)
+
+    const entries = await unzipText(bytes)
+    expect(entries.map((e) => e.name)).toEqual([
+      'page/About-abc12345(fr-FR).locjson',
+      'page/Höme-def67890(fr-FR).locjson',
+      'responsiveImage/Alt-99887766(fr-FR).locjson',
+    ])
+    // Contents parse as LocJSON and carry the x-sanity correlation metadata.
+    const first = JSON.parse(entries[0].content)
+    expect(first.properties['x-sanity'].documentId).toBe('abc12345-eeee')
+    expect(first.units[0].target).toEqual(['Bonjour'])
+    const second = JSON.parse(entries[1].content)
+    expect(second.properties['x-sanity'].documentId).toBe('def67890-ffff')
+    expect(second.units[0].target).toEqual(['Mönde'])
+    const third = JSON.parse(entries[2].content)
+    expect(third.properties['x-sanity'].documentId).toBe('99887766-aaaa')
+  })
+
+  it('extracts stored entries', async () => {
+    const zip = await buildZip([
+      {name: 'page/About-abc12345(fr).locjson', content: '{"a":1}'},
+      {name: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+    const entries = await unzipText(zip)
+    expect(entries).toEqual([
+      {name: 'page/About-abc12345(fr).locjson', content: '{"a":1}'},
+      {name: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+  })
+
+  it('inflates deflate-compressed entries', async () => {
+    const long = 'translated content '.repeat(200)
+    const zip = await buildZip([{name: 'doc.locjson', content: long, method: 8}])
+    const entries = await unzipText(zip)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].content).toBe(long)
+  })
+
+  it('skips directory entries', async () => {
+    const zip = await buildZip([
+      {name: 'page/', content: ''},
+      {name: 'page/About.locjson', content: '{}'},
+    ])
+    const entries = await unzip(zip)
+    expect(entries.map((e) => e.name)).toEqual(['page/About.locjson'])
+  })
+
+  it('preserves non-ASCII entry names and contents', async () => {
+    const zip = await buildZip([{name: 'sida/Åh nej-abc12345(sv).locjson', content: '{"t":"översättning"}', method: 8}])
+    const entries = await unzipText(zip)
+    expect(entries[0].name).toBe('sida/Åh nej-abc12345(sv).locjson')
+    expect(entries[0].content).toBe('{"t":"översättning"}')
+  })
+
+  it('throws on payloads without an end-of-central-directory record', async () => {
+    await expect(unzip(new TextEncoder().encode('PK\x03\x04 not really a zip'))).rejects.toThrow(
+      /end-of-central-directory/,
+    )
+  })
+})

package/src/lib/zip.ts

@@ -0,0 +1,164 @@
+/**
+ * Minimal ZIP reader for Smartcat batch-export archives.
+ *
+ * Dependency-free by design (like the rest of the Function-side code): built on
+ * `DataView` + the global `DecompressionStream` (Node 18+ / browsers). Supports
+ * the two compression methods Smartcat archives use — stored (0) and deflate (8).
+ *
+ * ZIP64 is REQUIRED, not an edge case: Smartcat writes export archives with
+ * SharpZipLib's `UseZip64 = On` (forced), so central-directory size/offset
+ * fields hold `0xFFFFFFFF` placeholders with the real 64-bit values in each
+ * entry's ZIP64 extra field — even for tiny archives. Large archives
+ * additionally use the ZIP64 end-of-central-directory record.
+ */
+
+export interface ZipEntry {
+  /** Entry path inside the archive (folders separated by `/`). */
+  name: string
+  data: Uint8Array
+}
+
+const LOCAL_HEADER_SIG = 0x04034b50
+const CENTRAL_HEADER_SIG = 0x02014b50
+const EOCD_SIG = 0x06054b50
+const ZIP64_EOCD_SIG = 0x06064b50
+const ZIP64_EOCD_LOCATOR_SIG = 0x07064b50
+/** EOCD record is 22 bytes + an optional comment of up to 65535 bytes. */
+const EOCD_MIN_SIZE = 22
+/** ZIP64 EOCD locator is a fixed 20 bytes, sitting right before the classic EOCD. */
+const ZIP64_LOCATOR_SIZE = 20
+/** Placeholder meaning "the real value is in the ZIP64 extra field / record". */
+const U32_MAX = 0xffffffff
+const U16_MAX = 0xffff
+/** Extra-field header id of the ZIP64 extended information block. */
+const ZIP64_EXTRA_ID = 0x0001
+
+/** Whether the payload looks like a ZIP archive (`PK\x03\x04` magic). */
+export function isZip(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === 0x50 &&
+    bytes[1] === 0x4b &&
+    bytes[2] === 0x03 &&
+    bytes[3] === 0x04
+  )
+}
+
+/** Extracts all file entries (directories are skipped). */
+export async function unzip(bytes: Uint8Array): Promise<ZipEntry[]> {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const eocd = findEndOfCentralDirectory(view)
+  const entries: ZipEntry[] = []
+
+  let offset = eocd.centralDirectoryOffset
+  for (let i = 0; i < eocd.entryCount; i++) {
+    if (view.getUint32(offset, true) !== CENTRAL_HEADER_SIG) {
+      throw new Error(`Invalid ZIP: bad central directory entry at ${offset}`)
+    }
+    const method = view.getUint16(offset + 10, true)
+    let compressedSize: number = view.getUint32(offset + 20, true)
+    let uncompressedSize: number = view.getUint32(offset + 24, true)
+    const nameLength = view.getUint16(offset + 28, true)
+    const extraLength = view.getUint16(offset + 30, true)
+    const commentLength = view.getUint16(offset + 32, true)
+    let localHeaderOffset: number = view.getUint32(offset + 42, true)
+    const name = new TextDecoder().decode(bytes.subarray(offset + 46, offset + 46 + nameLength))
+
+    // ZIP64: any field at its 32-bit max is a placeholder; the real value lives
+    // in the entry's ZIP64 extra block, in a fixed order, holding ONLY the
+    // fields that overflowed (Smartcat's forced-ZIP64 writer always defers the
+    // sizes this way, even for small files).
+    if (compressedSize === U32_MAX || uncompressedSize === U32_MAX || localHeaderOffset === U32_MAX) {
+      const extraStart = offset + 46 + nameLength
+      const extraEnd = extraStart + extraLength
+      let p = extraStart
+      while (p + 4 <= extraEnd) {
+        const id = view.getUint16(p, true)
+        const size = view.getUint16(p + 2, true)
+        if (id === ZIP64_EXTRA_ID) {
+          let q = p + 4
+          if (uncompressedSize === U32_MAX) {
+            uncompressedSize = Number(view.getBigUint64(q, true))
+            q += 8
+          }
+          if (compressedSize === U32_MAX) {
+            compressedSize = Number(view.getBigUint64(q, true))
+            q += 8
+          }
+          if (localHeaderOffset === U32_MAX) {
+            localHeaderOffset = Number(view.getBigUint64(q, true))
+          }
+          break
+        }
+        p += 4 + size
+      }
+      if (compressedSize === U32_MAX || localHeaderOffset === U32_MAX) {
+        throw new Error(`Invalid ZIP: "${name}" needs ZIP64 sizes but has no ZIP64 extra field`)
+      }
+    }
+    offset += 46 + nameLength + extraLength + commentLength
+
+    if (name.endsWith('/')) continue // directory entry
+
+    // The local header repeats name/extra with its own lengths; the data
+    // follows it. Sizes come from the central directory (authoritative even
+    // when the local header deferred them to a data descriptor).
+    if (view.getUint32(localHeaderOffset, true) !== LOCAL_HEADER_SIG) {
+      throw new Error(`Invalid ZIP: bad local header for "${name}"`)
+    }
+    const localNameLength = view.getUint16(localHeaderOffset + 26, true)
+    const localExtraLength = view.getUint16(localHeaderOffset + 28, true)
+    const dataStart = localHeaderOffset + 30 + localNameLength + localExtraLength
+    const compressed = bytes.subarray(dataStart, dataStart + compressedSize)
+
+    entries.push({name, data: await decompress(method, compressed, name)})
+  }
+  return entries
+}
+
+/** Convenience: unzip and decode every file entry as UTF-8 text. */
+export async function unzipText(bytes: Uint8Array): Promise<{name: string; content: string}[]> {
+  const entries = await unzip(bytes)
+  const decoder = new TextDecoder()
+  return entries.map((e) => ({name: e.name, content: decoder.decode(e.data)}))
+}
+
+function findEndOfCentralDirectory(view: DataView): {
+  entryCount: number
+  centralDirectoryOffset: number
+} {
+  const lowest = Math.max(0, view.byteLength - EOCD_MIN_SIZE - 0xffff)
+  for (let i = view.byteLength - EOCD_MIN_SIZE; i >= lowest; i--) {
+    if (view.getUint32(i, true) !== EOCD_SIG) continue
+
+    let entryCount: number = view.getUint16(i + 10, true)
+    let centralDirectoryOffset: number = view.getUint32(i + 16, true)
+
+    // ZIP64: placeholder values defer to the ZIP64 EOCD record, found via the
+    // fixed-size locator that sits immediately before the classic EOCD.
+    if (entryCount === U16_MAX || centralDirectoryOffset === U32_MAX) {
+      const locator = i - ZIP64_LOCATOR_SIZE
+      if (locator < 0 || view.getUint32(locator, true) !== ZIP64_EOCD_LOCATOR_SIG) {
+        throw new Error('Invalid ZIP: ZIP64 values without a ZIP64 end-of-central-directory locator')
+      }
+      const zip64Eocd = Number(view.getBigUint64(locator + 8, true))
+      if (view.getUint32(zip64Eocd, true) !== ZIP64_EOCD_SIG) {
+        throw new Error('Invalid ZIP: bad ZIP64 end-of-central-directory record')
+      }
+      entryCount = Number(view.getBigUint64(zip64Eocd + 32, true))
+      centralDirectoryOffset = Number(view.getBigUint64(zip64Eocd + 48, true))
+    }
+    return {entryCount, centralDirectoryOffset}
+  }
+  throw new Error('Invalid ZIP: end-of-central-directory record not found')
+}
+
+async function decompress(method: number, data: Uint8Array, name: string): Promise<Uint8Array> {
+  if (method === 0) return data // stored
+  if (method === 8) {
+    // Copy into a fresh ArrayBuffer so the Blob sees exactly this entry's bytes.
+    const stream = new Blob([data.slice()]).stream().pipeThrough(new DecompressionStream('deflate-raw'))
+    return new Uint8Array(await new Response(stream).arrayBuffer())
+  }
+  throw new Error(`Unsupported ZIP compression method ${method} for "${name}"`)
+}