@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/smartcat/client.test.ts

@@ -0,0 +1,222 @@
+import {describe, expect, it, vi} from 'vitest'
+import {SmartcatClient, SmartcatError, SmartcatTimeoutError} from './client'
+import {buildZip} from '../lib/zip.fixtures'
+
+function mockFetch(status: number, body: unknown) {
+  return vi.fn(async () =>
+    new Response(typeof body === 'string' ? body : JSON.stringify(body), {status}),
+  ) as unknown as typeof fetch
+}
+
+const opts = {
+  server: 'us.smartcat.com',
+  workspaceId: '784fbe10-4ef5-4519-8acc-9a3cd956d614',
+  apiKey: 'test-key',
+}
+
+describe('SmartcatClient', () => {
+  it('sends Basic auth derived from workspaceId:apiKey', async () => {
+    const fetchImpl = mockFetch(200, {id: 'p1'})
+    const client = new SmartcatClient({...opts, fetchImpl})
+    await client.getProject('p1')
+
+    const [, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    const expected = `Basic ${btoa(`${opts.workspaceId}:${opts.apiKey}`)}`
+    expect((init.headers as Record<string, string>).Authorization).toBe(expected)
+  })
+
+  it('createProject posts multipart body and returns the project', async () => {
+    const fetchImpl = mockFetch(200, {id: 'guid-123', name: 'Demo'})
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const project = await client.createProject({
+      name: 'Demo',
+      sourceLanguage: 'en',
+      targetLanguages: ['fr', 'zh-Hans'],
+    })
+
+    expect(project.id).toBe('guid-123')
+    const [url, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(url).toBe('https://us.smartcat.com/api/integration/v1/project/create')
+    expect(init.method).toBe('POST')
+    expect(init.body).toBeInstanceOf(FormData)
+    expect((init.body as FormData).get('body')).toContain('"sourceLanguage":"en"')
+  })
+
+  it('uploadDocument targets the project and normalizes the response to an array', async () => {
+    const fetchImpl = mockFetch(200, {id: 'doc1'})
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const docs = await client.uploadDocument('guid-123', 'page/About-abc.locjson', '{}')
+    expect(docs).toEqual([{id: 'doc1'}])
+
+    const [url, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(url).toBe(
+      'https://us.smartcat.com/api/integration/v1/project/document?projectId=guid-123',
+    )
+    expect((init.body as FormData).get('file')).toBeInstanceOf(Blob)
+  })
+
+  it('uploadDocuments posts a multi-file body and normalizes the response to an array', async () => {
+    const fetchImpl = mockFetch(200, [{id: 'd1'}, {id: 'd2'}])
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const docs = await client.uploadDocuments('guid-123', [
+      {filename: 'page/About-abc.locjson', content: '{"a":1}'},
+      {filename: 'page/Home-def.locjson', content: '{"b":2}'},
+    ])
+    expect(docs).toEqual([{id: 'd1'}, {id: 'd2'}])
+
+    const [url, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(url).toBe('https://us.smartcat.com/api/integration/v1/project/document?projectId=guid-123')
+    expect(init.method).toBe('POST')
+    const body = init.body as FormData
+    expect(body.getAll('file')).toHaveLength(2)
+    expect(body.get('model')).toBeInstanceOf(Blob)
+    expect(JSON.parse(await (body.get('model') as Blob).text())).toEqual([{}, {}])
+  })
+
+  it('uploadDocuments normalizes a single-object response to an array', async () => {
+    const fetchImpl = mockFetch(200, {id: 'd1'})
+    const client = new SmartcatClient({...opts, fetchImpl})
+    const docs = await client.uploadDocuments('guid-123', [{filename: 'f.locjson', content: '{}'}])
+    expect(docs).toEqual([{id: 'd1'}])
+  })
+
+  it('exportDocument requests a task then polls until 200', async () => {
+    const responses = [
+      {status: 200, text: async () => JSON.stringify({id: 'task-1'})}, // POST export
+      {status: 204, text: async () => ''}, // poll: not ready
+      {status: 200, text: async () => '{"units":[]}'}, // poll: ready
+    ]
+    const fetchImpl = vi.fn(async () => responses.shift()!) as unknown as typeof fetch
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const content = await client.exportDocument('doc-1', {sleep: async () => {}, pollIntervalMs: 0})
+    expect(content).toBe('{"units":[]}')
+
+    const calls = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls
+    expect(calls[0][0]).toContain('/document/export?documentIds=doc-1&mode=confirmed&type=target')
+    expect(calls[1][0]).toContain('/document/export/task-1')
+    expect(calls).toHaveLength(3)
+  })
+
+  it('exportDocumentsBatch requests one task for all ids and unpacks the ZIP result', async () => {
+    const zip = await buildZip([
+      {name: 'page/About-abc12345(fr).locjson', content: '{"a":1}', method: 8},
+      {name: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+    const responses = [
+      new Response(JSON.stringify({id: 'task-9'}), {status: 200}), // POST export
+      new Response(null, {status: 204}), // poll: not ready
+      new Response(zip.slice(), {status: 200}), // poll: ready (archive)
+    ]
+    const fetchImpl = vi.fn(async () => responses.shift()!) as unknown as typeof fetch
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const files = await client.exportDocumentsBatch(['g_25', 'h_25'], {sleep: async () => {}})
+    expect(files).toEqual([
+      {filename: 'page/About-abc12345(fr).locjson', content: '{"a":1}'},
+      {filename: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+
+    const calls = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls
+    expect(calls[0][0]).toContain('/document/export?documentIds=g_25&documentIds=h_25&mode=confirmed&type=target')
+    expect(calls[1][0]).toContain('/document/export/task-9')
+    expect(calls).toHaveLength(3)
+  })
+
+  it('exportDocumentsBatch handles a bare (non-ZIP) single-file result', async () => {
+    const responses = [
+      new Response(JSON.stringify({id: 'task-1'}), {status: 200}),
+      new Response('{"units":[]}', {status: 200}),
+    ]
+    const fetchImpl = vi.fn(async () => responses.shift()!) as unknown as typeof fetch
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    const files = await client.exportDocumentsBatch(['g_25'], {sleep: async () => {}})
+    expect(files).toEqual([{filename: '', content: '{"units":[]}'}])
+  })
+
+  it('exportDocumentsBatch surfaces poll errors as SmartcatError', async () => {
+    const responses = [
+      new Response(JSON.stringify({id: 'task-1'}), {status: 200}),
+      new Response('boom', {status: 500}),
+    ]
+    const fetchImpl = vi.fn(async () => responses.shift()!) as unknown as typeof fetch
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    await expect(client.exportDocumentsBatch(['g_25', 'h_25'], {sleep: async () => {}})).rejects.toBeInstanceOf(
+      SmartcatError,
+    )
+  })
+
+  it('deleteDocument sends a DELETE with the document id as a query param', async () => {
+    // Smartcat returns 204 (no body); the Response ctor forbids a body for 204.
+    const fetchImpl = vi.fn(async () => new Response(null, {status: 204})) as unknown as typeof fetch
+    const client = new SmartcatClient({...opts, fetchImpl})
+
+    await client.deleteDocument('c11963b35c862b1c61a8c99a_12')
+
+    const [url, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(url).toBe(
+      'https://us.smartcat.com/api/integration/v1/document?documentIds=c11963b35c862b1c61a8c99a_12',
+    )
+    expect(init.method).toBe('DELETE')
+  })
+
+  it('throws SmartcatError on non-2xx', async () => {
+    const fetchImpl = mockFetch(401, 'Unauthorized')
+    const client = new SmartcatClient({...opts, fetchImpl})
+    await expect(client.getProject('p1')).rejects.toBeInstanceOf(SmartcatError)
+  })
+
+  it('strips protocol/trailing slash from the server', async () => {
+    const fetchImpl = mockFetch(200, {id: 'p1'})
+    const client = new SmartcatClient({...opts, server: 'https://us.smartcat.com/', fetchImpl})
+    await client.getProject('p1')
+    const [url] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(url).toBe('https://us.smartcat.com/api/integration/v1/project/p1')
+  })
+
+  describe('request timeout', () => {
+    it('passes an AbortSignal when requestTimeoutMs is set, and none when it is not', async () => {
+      const withTimeout = mockFetch(200, {id: 'p1'})
+      await new SmartcatClient({...opts, fetchImpl: withTimeout, requestTimeoutMs: 570_000}).getProject('p1')
+      const [, initA] = (withTimeout as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+      expect(initA.signal).toBeInstanceOf(AbortSignal)
+
+      const noTimeout = mockFetch(200, {id: 'p1'})
+      await new SmartcatClient({...opts, fetchImpl: noTimeout}).getProject('p1')
+      const [, initB] = (noTimeout as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+      expect(initB.signal).toBeUndefined()
+    })
+
+    it('translates a fetch abort into a SmartcatTimeoutError and logs it', async () => {
+      const fetchImpl = vi.fn(async () => {
+        const err = new Error('aborted')
+        err.name = 'TimeoutError'
+        throw err
+      }) as unknown as typeof fetch
+      const logged: {status: number; body: string}[] = []
+      const client = new SmartcatClient({...opts, fetchImpl, requestTimeoutMs: 570_000})
+      client.setRequestLogger(({status, body}) => logged.push({status, body}))
+
+      const error = await client.getProject('p1').catch((e) => e)
+      expect(error).toBeInstanceOf(SmartcatTimeoutError)
+      expect(error.message).toContain('9m30s')
+      // The failed call is traced (synthetic status 0) so it reaches the log.
+      expect(logged).toEqual([{status: 0, body: expect.stringContaining('9m30s')}])
+    })
+
+    it('leaves non-abort fetch errors unchanged', async () => {
+      const fetchImpl = vi.fn(async () => {
+        throw new Error('network down')
+      }) as unknown as typeof fetch
+      const client = new SmartcatClient({...opts, fetchImpl, requestTimeoutMs: 570_000})
+      const error = await client.getProject('p1').catch((e) => e)
+      expect(error).not.toBeInstanceOf(SmartcatTimeoutError)
+      expect((error as Error).message).toBe('network down')
+    })
+  })
+})

package/src/smartcat/client.ts

@@ -0,0 +1,351 @@
+import {isZip, unzipText} from '../lib/zip'
+import type {
+  CreateProjectInput,
+  RequestLogger,
+  SmartcatClientOptions,
+  SmartcatDocument,
+  SmartcatProject,
+  SmartcatTemplatesResponse,
+} from './types'
+
+const API_BASE = '/api/integration/v1'
+
+/** One file from a (batch) export: archive entry name + LocJSON text. */
+export interface ExportedFile {
+  /** Path inside the export archive; empty for a single-file response. */
+  filename: string
+  content: string
+}
+
+/** Error thrown when the Smartcat API returns a non-2xx response. */
+export class SmartcatError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+  ) {
+    super(`Smartcat API error ${status}: ${body}`)
+    this.name = 'SmartcatError'
+  }
+}
+
+/** Error thrown when a request is aborted by the configured `requestTimeoutMs`. */
+export class SmartcatTimeoutError extends Error {
+  constructor(
+    public readonly method: string,
+    public readonly path: string,
+    public readonly timeoutMs: number,
+  ) {
+    super(`Smartcat did not respond within ${formatDuration(timeoutMs)} for ${method} ${path}`)
+    this.name = 'SmartcatTimeoutError'
+  }
+}
+
+/** Human-readable duration, e.g. 570000 → "9m30s", 30000 → "30s". */
+function formatDuration(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000)
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  if (!minutes) return `${seconds}s`
+  return seconds ? `${minutes}m${seconds}s` : `${minutes}m`
+}
+
+/** True for an abort/timeout rejection from `fetch` (DOMException-style). */
+function isAbortError(err: unknown): boolean {
+  const name = (err as {name?: string} | undefined)?.name
+  return name === 'TimeoutError' || name === 'AbortError'
+}
+
+/**
+ * Minimal client for the Smartcat integration API.
+ *
+ * Uses Basic auth (`base64(workspaceId:apiKey)`). Built on global `fetch`,
+ * `FormData` and `Blob` (Node 18+ / the Functions runtime); no Node-only APIs,
+ * so it is portable. Secrets are required, so this only runs server-side.
+ */
+export class SmartcatClient {
+  private readonly server: string
+  private readonly authHeader: string
+  private readonly fetchImpl: typeof fetch
+  private readonly requestTimeoutMs?: number
+  private requestLogger?: RequestLogger
+
+  constructor(options: SmartcatClientOptions) {
+    this.server = options.server.replace(/^https?:\/\//, '').replace(/\/$/, '')
+    this.authHeader = `Basic ${btoa(`${options.workspaceId}:${options.apiKey}`)}`
+    this.fetchImpl = options.fetchImpl ?? fetch
+    this.requestTimeoutMs = options.requestTimeoutMs
+  }
+
+  /** An `AbortSignal` that fires after `requestTimeoutMs`, or undefined if unset. */
+  private timeoutSignal(): AbortSignal | undefined {
+    return this.requestTimeoutMs ? AbortSignal.timeout(this.requestTimeoutMs) : undefined
+  }
+
+  /** Attach a sink that receives every HTTP call (method, path, status, body). */
+  setRequestLogger(logger: RequestLogger): void {
+    this.requestLogger = logger
+  }
+
+  /** Creates a project and returns it (including its generated `id` GUID). */
+  async createProject(input: CreateProjectInput): Promise<SmartcatProject> {
+    const {templateId, ...rest} = input
+    // A template fully owns its workflow, MT/TM and pretranslation config, so we
+    // send only the project identity + template id. The standard flow sets the
+    // MT/TM/pretranslation flags here; `workflowStages` is supplied by the caller
+    // (it's what distinguishes AI+human from AI-only).
+    const body = templateId
+      ? {assignToVendor: false, externalTag: 'smartcat-sanity-plugin', templateId, ...rest}
+      : {
+          assignToVendor: false,
+          externalTag: 'smartcat-sanity-plugin',
+          useMT: true,
+          useTranslationMemory: true,
+          pretranslate: true,
+          autoPropagateRepetitions: true,
+          minTranslationAssuranceLevel: 'regular',
+          ...rest,
+        }
+    const form = new FormData()
+    form.append('body', JSON.stringify(body))
+    return this.request('POST', `${API_BASE}/project/create`, form)
+  }
+
+  /** Lists the workspace's project templates. */
+  async getTemplates(): Promise<SmartcatTemplatesResponse> {
+    return this.request('GET', `${API_BASE}/template`)
+  }
+
+  /** Uploads one source file into a project. `filename` may include a folder path. */
+  async uploadDocument(
+    projectId: string,
+    filename: string,
+    content: string,
+  ): Promise<SmartcatDocument[]> {
+    const form = new FormData()
+    // Use a generic content type: declaring application/json makes Smartcat try
+    // to map the file to an API model instead of importing it as a document.
+    form.append('file', new Blob([content], {type: 'application/octet-stream'}), filename)
+    const result = await this.request<SmartcatDocument[] | SmartcatDocument>(
+      'POST',
+      `${API_BASE}/project/document?projectId=${encodeURIComponent(projectId)}`,
+      form,
+    )
+    return Array.isArray(result) ? result : result ? [result] : []
+  }
+
+  /**
+   * Uploads many source files into a project in a single request — the
+   * multi-file sibling of {@link uploadDocument}. Mirrors the reference
+   * `AddDocuments` multipart contract: one `model` part carrying a JSON array
+   * with one (default-settings) entry per file, plus one `file` part per file.
+   * Returns the created documents (files × target languages).
+   */
+  async uploadDocuments(
+    projectId: string,
+    files: {filename: string; content: string}[],
+  ): Promise<SmartcatDocument[]> {
+    const form = new FormData()
+    // One settings object per file, positional with the file parts (empty = default
+    // disassembly, as the single-file path). Correlation never relies on this order.
+    form.append('model', new Blob([JSON.stringify(files.map(() => ({})))], {type: 'application/json'}), 'model')
+    for (const f of files) {
+      form.append('file', new Blob([f.content], {type: 'application/octet-stream'}), f.filename)
+    }
+    const result = await this.request<SmartcatDocument[] | SmartcatDocument>(
+      'POST',
+      `${API_BASE}/project/document?projectId=${encodeURIComponent(projectId)}`,
+      form,
+    )
+    return Array.isArray(result) ? result : result ? [result] : []
+  }
+
+  /**
+   * Updates an existing document's source content by re-uploading the file.
+   * Smartcat re-imports and merges, preserving translations of unchanged
+   * segments. `documentId` is a target document id (`<fileGuid>_<langNum>`).
+   */
+  async updateDocument(
+    documentId: string,
+    filename: string,
+    content: string,
+  ): Promise<SmartcatDocument[]> {
+    const form = new FormData()
+    form.append('file', new Blob([content], {type: 'application/octet-stream'}), filename)
+    const result = await this.request<SmartcatDocument[] | SmartcatDocument>(
+      'PUT',
+      `${API_BASE}/document/update?documentId=${encodeURIComponent(documentId)}`,
+      form,
+    )
+    return Array.isArray(result) ? result : result ? [result] : []
+  }
+
+  /** Fetches a project (including its documents and per-stage progress). */
+  async getProject(projectId: string): Promise<SmartcatProject> {
+    return this.request('GET', `${API_BASE}/project/${encodeURIComponent(projectId)}`)
+  }
+
+  /**
+   * Deletes a document from its project. The id is a target document id
+   * (`<fileGuid>_<langNum>`), but Smartcat removes the whole document — every
+   * target language — in a single call.
+   */
+  async deleteDocument(documentId: string): Promise<void> {
+    await this.request('DELETE', `${API_BASE}/document?documentIds=${encodeURIComponent(documentId)}`)
+  }
+
+  /** Builds the Smartcat web URL for a project's overview page. */
+  projectUrl(projectId: string): string {
+    return `https://${this.server}/projects/${projectId}/general`
+  }
+
+  /**
+   * Exports a document's target (translated) content and returns it as text.
+   * Two-step: request an export task, then poll until ready.
+   *
+   * `mode` defaults to `confirmed` — only segments confirmed at any workflow
+   * stage are returned (unconfirmed/untranslated segments fall back to source),
+   * so we never import unvetted machine-translation drafts. Use `current` to pull
+   * the live state including unconfirmed edits.
+   */
+  async exportDocument(
+    documentId: string,
+    options: {
+      mode?: 'confirmed' | 'current'
+      pollIntervalMs?: number
+      maxAttempts?: number
+      sleep?: (ms: number) => Promise<void>
+    } = {},
+  ): Promise<string> {
+    const {mode = 'confirmed', pollIntervalMs = 3000, maxAttempts = 20, sleep = defaultSleep} = options
+
+    const task = await this.request<{id: string}>(
+      'POST',
+      `${API_BASE}/document/export?documentIds=${encodeURIComponent(documentId)}&mode=${mode}&type=target`,
+    )
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const {status, text} = await this.requestRaw('GET', `${API_BASE}/document/export/${task.id}`)
+      if (status === 200) return text
+      if (status === 204) {
+        await sleep(pollIntervalMs)
+        continue
+      }
+      throw new SmartcatError(status, text)
+    }
+    throw new Error(`Smartcat export for ${documentId} timed out`)
+  }
+
+  /**
+   * Exports many documents' target content in **one** export task. Smartcat
+   * fans the work out server-side and (for more than one document) returns a
+   * ZIP archive of the individual files, so the per-document request+poll
+   * round-trip is paid once per batch instead of once per document.
+   *
+   * Identity comes from each LocJSON's own `x-sanity` metadata, not the entry
+   * name, so callers should correlate on the parsed content.
+   */
+  async exportDocumentsBatch(
+    documentIds: string[],
+    options: {
+      mode?: 'confirmed' | 'current'
+      pollIntervalMs?: number
+      maxAttempts?: number
+      sleep?: (ms: number) => Promise<void>
+    } = {},
+  ): Promise<ExportedFile[]> {
+    if (documentIds.length === 0) return []
+    // Bigger batches take longer to assemble server-side; poll longer, not faster.
+    const {mode = 'confirmed', pollIntervalMs = 3000, maxAttempts = 60, sleep = defaultSleep} = options
+
+    const query = documentIds.map((id) => `documentIds=${encodeURIComponent(id)}`).join('&')
+    const task = await this.request<{id: string}>(
+      'POST',
+      `${API_BASE}/document/export?${query}&mode=${mode}&type=target`,
+    )
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const {status, bytes} = await this.requestBytes('GET', `${API_BASE}/document/export/${task.id}`)
+      if (status === 200) {
+        // A single-document task returns the bare file; multi-document tasks
+        // return a ZIP. Decide by content, not by count — Smartcat may drop
+        // documents it can't export from the archive.
+        if (isZip(bytes)) {
+          return (await unzipText(bytes)).map(({name, content}) => ({filename: name, content}))
+        }
+        return [{filename: '', content: new TextDecoder().decode(bytes)}]
+      }
+      if (status === 204) {
+        await sleep(pollIntervalMs)
+        continue
+      }
+      throw new SmartcatError(status, new TextDecoder().decode(bytes))
+    }
+    throw new Error(`Smartcat batch export of ${documentIds.length} document(s) timed out`)
+  }
+
+  private async request<T = unknown>(method: string, path: string, body?: BodyInit): Promise<T> {
+    const {status, text} = await this.requestRaw(method, path, body)
+    if (status < 200 || status >= 300) throw new SmartcatError(status, text)
+    return (text ? JSON.parse(text) : null) as T
+  }
+
+  /**
+   * Normalizes a `fetch` rejection. A timeout abort becomes a
+   * {@link SmartcatTimeoutError} — traced through the request logger first (with
+   * a synthetic status 0) so it surfaces in the same log as HTTP failures — while
+   * anything else is rethrown unchanged.
+   */
+  private onFetchError(method: string, path: string, err: unknown): unknown {
+    if (isAbortError(err) && this.requestTimeoutMs) {
+      const timeout = new SmartcatTimeoutError(method, path, this.requestTimeoutMs)
+      this.requestLogger?.({method, path, status: 0, body: timeout.message})
+      return timeout
+    }
+    return err
+  }
+
+  private async requestRaw(
+    method: string,
+    path: string,
+    body?: BodyInit,
+  ): Promise<{status: number; text: string}> {
+    let res: Response
+    try {
+      res = await this.fetchImpl(`https://${this.server}${path}`, {
+        method,
+        headers: {Authorization: this.authHeader},
+        body,
+        signal: this.timeoutSignal(),
+      })
+    } catch (err) {
+      throw this.onFetchError(method, path, err)
+    }
+    const text = await res.text()
+    this.requestLogger?.({method, path, status: res.status, body: text})
+    return {status: res.status, text}
+  }
+
+  /** Like {@link requestRaw} but preserves the body as bytes (ZIP downloads). */
+  private async requestBytes(method: string, path: string): Promise<{status: number; bytes: Uint8Array}> {
+    let res: Response
+    try {
+      res = await this.fetchImpl(`https://${this.server}${path}`, {
+        method,
+        headers: {Authorization: this.authHeader},
+        signal: this.timeoutSignal(),
+      })
+    } catch (err) {
+      throw this.onFetchError(method, path, err)
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    // Log a size placeholder for successful binary payloads; error bodies are
+    // text (Smartcat's error detail) and stay readable in the trace.
+    const logBody = res.status >= 200 && res.status < 300 ? `<${bytes.length} bytes>` : new TextDecoder().decode(bytes)
+    this.requestLogger?.({method, path, status: res.status, body: logBody})
+    return {status: res.status, bytes}
+  }
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/smartcat/index.ts

@@ -0,0 +1,10 @@
+export {SmartcatClient, SmartcatError, SmartcatTimeoutError} from './client'
+export type {
+  SmartcatClientOptions,
+  CreateProjectInput,
+  SmartcatProject,
+  SmartcatDocument,
+  SmartcatWorkflowStage,
+  SmartcatTemplate,
+  SmartcatTemplatesResponse,
+} from './types'

package/src/smartcat/types.ts

@@ -0,0 +1,99 @@
+/** Credentials + server for a Smartcat workspace. */
+export interface SmartcatClientOptions {
+  /** API server hostname, e.g. "us.smartcat.com". */
+  server: string
+  /** Workspace ID (GUID). */
+  workspaceId: string
+  /** API token. */
+  apiKey: string
+  /** Override fetch (defaults to global fetch). Useful for tests. */
+  fetchImpl?: typeof fetch
+  /**
+   * Per-request timeout in ms. When set, each HTTP call is aborted after this
+   * long (via `AbortSignal.timeout`) and rejected as a {@link SmartcatTimeoutError},
+   * so a stalled Smartcat response fails fast with a clear, loggable error instead
+   * of the whole Sanity Function being platform-killed. Unset ⇒ no timeout.
+   */
+  requestTimeoutMs?: number
+}
+
+/** One Smartcat HTTP call, reported to a {@link RequestLogger} for tracing. */
+export 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
+}
+
+/** Sink for per-request tracing; attach with `SmartcatClient.setRequestLogger`. */
+export type RequestLogger = (info: RequestLogInfo) => void
+
+/** Input for creating a Smartcat project. */
+export interface CreateProjectInput {
+  name: string
+  description?: string
+  /** Source language code (e.g. "en"). */
+  sourceLanguage: string
+  /** Target language codes (e.g. ["fr", "zh-Hans"]). */
+  targetLanguages: string[]
+  assignToVendor?: boolean
+  pretranslate?: boolean
+  autoPropagateRepetitions?: boolean
+  /** Workflow stages, e.g. ["translation", "postediting"]. */
+  workflowStages?: string[]
+  /** Create from a Smartcat project template; the template defines the workflow. */
+  templateId?: string
+}
+
+/** A Smartcat project template (from `GET /template`). */
+export interface SmartcatTemplate {
+  id: string
+  name: string
+}
+
+/** Response shape of `GET /template`. */
+export interface SmartcatTemplatesResponse {
+  templates: SmartcatTemplate[]
+}
+
+export 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
+}
+
+/** A document within a Smartcat project (one per source file × target language). */
+export 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[]
+}
+
+/** A Smartcat project as returned by the API. */
+export 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[]
+}