@lionrapid/cli 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,212 @@
 All notable changes to `@lionrapid/cli`. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this package follows semver.
 
+## Unreleased
+
+### Added
+
+- **`push` reports the jobs it queued, and `lionrapid status` says what became
+  of them.** `sync/batch` answers `202 Accepted` — queued, not stored — and the
+  CLI discarded that response body at the transport layer (`syncBatch` returned
+  `void`). A push whose backend job later failed or dead-lettered was therefore
+  indistinguishable from one that worked: `pushed N string(s)` described the
+  CLI's own outbox and nothing else. Now:
+
+  - `syncBatch` returns the server's `BatchSyncJobResponse`, and `push` collects
+    every `job_ids` entry (not just the legacy `job_id`, so multi-locale batches
+    stay observable);
+  - `push` prints those ids with a `lionrapid status <job-id>` hint, and says so
+    explicitly when a server returns none;
+  - new **`lionrapid status [job-id|list]`**: one job's verdict from
+    `GET /sync/jobs/{id}` (status, error, retry history, dead-letter reason), or
+    the whole local job log newest-first, falling back to `/sync/queue-health`
+    and `/sync/dead-letter-queue` when this machine has nothing recorded.
+
+- **Push receipts persist in `~/.lionrapid/jobs.json`.** Job id, project,
+  file(s), key count, push time and last-seen status, so `status` still answers
+  after the terminal is closed — and after the server's ~1h job retention has
+  purged the job. Terminal states are recorded and answered from disk with no
+  network call; anything unresolved is re-checked. Deliberately a separate file
+  from `credentials` (different lifetime and sensitivity — a corrupt history
+  must never cost you your login), 0600, written via temp-file + rename, and
+  pruned to 500 entries / 30 days.
+
+- **Field-level drift guard on the sync response.** `BATCH_SYNC_RESPONSE_FIELDS`
+  plus a type-level assertion make a required server field missing from the
+  CLI's `SyncBatchResponse` a `tsc --noEmit` failure — `job_id`/`job_ids` were
+  silently dropped for exactly as long as nothing checked. (Guard lives in
+  `src/`, since tsconfig excludes tests from typechecking.)
+
+### Fixed
+
+- **A `GET` 404 is no longer retried as "sync already processing".** That
+  retry-on-404 heuristic is the enqueue path's; `GET /sync/jobs/{id}` returns the
+  same `SYNC_JOB_NOT_FOUND` code for a job that simply does not exist, which made
+  `status` back off three times before answering.
+
+- **Every request carries `X-LR-Surface: cli`.** The server's surface registry
+  tells a customer which integration surfaces are live, but snippet, WordPress
+  and the CLI share the same project-wide key and were indistinguishable — so
+  each client now tags its requests with which surface it is. Older servers
+  ignore the header; no behavior changes.
+
+## 0.2.2 — 2026-07-27
+
+### Added
+
+- **`files[].flat` — dotted keys round-trip as dotted.** JSON/YAML targets are
+  written nested by default, so a key pushed flat (`hero.title`) came back as
+  `{"hero": {"title": …}}` — breaking flat-keyed consumers (CMS imports,
+  webhook payloads) that fed the file back in. `flat: true` on a `files` entry
+  keeps dotted keys literal on `pull`. Only valid for `json`/`yaml` (every
+  other format is flat by nature); glob entries carry the flag onto each
+  expanded file.
+
+- **`lionrapid login` / `lionrapid logout`.** The credentials file the CLI
+  reads finally has an author: `login` verifies the key against the server
+  _before_ persisting (a failed ping writes nothing), writes
+  `~/.lionrapid/credentials` `0600` in a `0700` dir, and merges entries — bare
+  `login` writes `default`, `--server <url>` writes the server-scoped entry
+  that 0.2.1's trust boundary requires for non-LionRapid hosts. Omitting
+  `--key` gives a hidden interactive prompt; the key is never echoed. `logout`
+  removes an entry and deletes the file when empty. At read time the CLI now
+  warns (once per file) when the credentials file is world-readable.
+- **Glob file entries with derived namespaces.** `files[].source` may be a
+  glob (`locales/en/*.json`); `target` and `namespace` then carry a
+  `{basename}` token substituted per matched file with its extension-less
+  name. One stanza replaces N hand-written entries (e.g. one file per page
+  slug → one namespace per page). Expansion happens at config load, is
+  deterministic (sorted), and a glob matching nothing warns instead of
+  silently doing nothing. A glob without `{basename}` in _both_ `target` and
+  `namespace` is rejected as ambiguous.
+- **Per-attempt request timeouts.** Every request carries a fresh
+  `AbortSignal.timeout` budget (default 30 s) so a hung connection can no
+  longer block `push`/`pull`/`doctor` forever. Timeouts are retried like other
+  transient failures and report "timed out after Xms". Tune via
+  `LIONRAPID_TIMEOUT` or the global `--timeout <ms>` flag.
+- **`validate --allow-locked`** downgrades locked (unapproved) namespaces to a
+  warning so brand-new namespaces don't fail CI.
+- **Modern `init`: layout detection, prompts, and locale prefill.** `init`
+  detects a per-namespace `locales/en/<ns>.json` layout and scaffolds the glob
+  stanza for it (flat layouts keep the concrete entry). On a TTY it prompts
+  for the project label, server URL, and — new — an optional API key
+  (`--key`, stored credentials, or a hidden prompt) used to prefill
+  `sourceLocale`/`targetLocales` from the project's dashboard configuration
+  via `GET /api/integrations/project-config`. Everything degrades gracefully:
+  non-TTY runs never block, and offline/older servers fall back to the static
+  defaults. A project that simply has **no target languages yet** is reported
+  as exactly that — with the remediation (add them in the dashboard, re-run
+  `init --force`) and a warning that the scaffolded `targetLocales` are
+  placeholders — rather than being misreported as an unreachable server. The
+  overwrite guard fires before any prompt, and next-steps route credentials
+  through `lionrapid login` (and skip that advice when a stored credential
+  was already used).
+- **`init` re-runs safely and stops asking for what it already knows.** It
+  defaults its server to the repo's config or the one you logged into (so
+  `lionrapid login` then a bare `lionrapid init` is the whole setup), and
+  re-running it is no longer an error: newly-detected files and locales merge
+  in and are listed, anything that would _change_ a value you set is reported
+  as a conflict (`yours:` / `project:`) and left untouched, and a run with
+  nothing new leaves the file byte-identical — hand-edits and comments
+  survive. `--force` still rewrites wholesale.
+- **`init` no longer invents locales.** When neither the project nor the repo
+  yields target languages, `targetLocales` is written empty with a warning
+  saying so, instead of scaffolding a fabricated `[es, fr]` that produced
+  phantom pending keys on every later `pull`/`validate`.
+- **`init` detects `.po`, XLIFF and standalone YAML catalogs.** Detection is
+  no longer limited to Flutter/iOS/Android/Rails/JSON: conventional catalog
+  roots (`po/`, `locale/`, `locales/`, `translations/`, `i18n/`, `src/locale/`,
+  `Content/Localization/`, …) are searched for `.po`, `.xlf`/`.xliff` and
+  `.yml`/`.yaml`, and the source→target stanza is derived from the files that
+  actually exist — covering gettext `locale/{locale}/LC_MESSAGES/…`, flat
+  `po/{locale}.po`, locale-suffixed `messages.{locale}.xlf`, and Unreal/Godot's
+  `Content/Localization/<Target>/{locale}/…`. Formats accumulate, so a repo
+  with both JSON and PO trees gets both stanzas.
+- **`init` detects the locales already in your repo.** Locale resolution is
+  now a ladder — explicit `--source`/`--targets`, then the project's server
+  config, then locales found on disk by matching the detected `target`
+  pattern (`locales/{locale}/…`, `app_{locale}.arb`, `values-{locale}/…`,
+  `{locale}.lproj/…`), then static placeholders. Offline or on a project with
+  no targets yet, `init` scaffolds what the repo actually has instead of
+  guessing. When the server _does_ have targets it stays authoritative, and a
+  locale that exists only on disk is reported as a mismatch (`present in your
+files but not configured on the project`) rather than silently merged —
+  those files would never be filled by `pull`.
+
+### Changed
+
+- **`push` makes partial progress instead of aborting.** One failing
+  file/namespace (a rate limit on a many-namespace site, one corrupt source
+  file) no longer zeroes the run: the remaining files still upload, failures
+  render per file with a summary and appear as `error` fields in the `--json`
+  envelope (`ok: false`), and the exit code is 5 (PARTIAL). Because the sync
+  endpoints upsert by composite key, re-running `push` retries just the
+  failures. When every attempted file fails, the first error is rethrown with
+  the usual exit taxonomy.
+- **A `429` without `Retry-After` now waits a rate-limit window (30 s), not
+  millisecond jitter.** The server's rate-limit responses carry no
+  `Retry-After` header and its limits are per-minute windows — the old jittered
+  backoff (~2 s total across all retries) could never outlive one, so every
+  429 exhausted its retries and was effectively fatal. Concretely: a site with
+  more than 30 namespaces died mid-push at the sync endpoint's 30/min limit;
+  now push rides the window out and completes.
+- **`pull` makes partial progress instead of aborting.** On a multi-namespace
+  pull, a failing namespace (or a corrupt local target) no longer zeroes the
+  run: successful files still write, failures render per file with a summary
+  and appear as `error` fields in the `--json` envelope (`ok: false`), and the
+  exit code is 5 (PARTIAL). When every file fails, the first error is rethrown
+  with the usual exit taxonomy.
+- **`login` and `doctor` verify via `project-config` (`config:read`).** The
+  previous probe (`editor/workflow`) requires `targets:write`, which
+  publishable keys don't carry — so pk\_ keys failed verification even though
+  the whole standard loop (push/pull/validate/prefill) runs on them. Doctor's
+  server check now also echoes the project's configured locales.
+- **`pull` is non-destructive by default.** Existing targets are merged, not
+  overwritten: the server wins per key, local-only keys and comments survive
+  (comments even on server-updated keys), existing key order is preserved and
+  new keys append. Each file reports `{added, updated, keptLocal}` diff counts
+  in prose and `--json`; `--dry-run` computes the diff without writing.
+  `pull --force` restores the previous wholesale overwrite.
+- **`validate` reports a locked (423) namespace as one namespace-level
+  `locked` issue** per locale instead of N spurious `missing` lines. Locked
+  still fails `--ci` by default. Envelope note: `issues[].key` is now optional
+  and `locked` joins the issue types.
+
+### Fixed
+
+- **Nested keys were silently lost on `pull`.** The endpoint accepts flat
+  dotted keys on write but answers **nested** on read (a pushed `nav.cart`
+  comes back as `{"nav": {"cart": …}}`, because the SDK resolves nested
+  paths). Every CLI adapter is built on flat keys, so whole subtrees vanished:
+  `pull` wrote fewer keys than it pushed and `validate` reported the missing
+  ones forever. `getNamespace` now flattens the tree back to `dotted.key`
+  using the server's own leaf rule (a string, or an object carrying `text`, is
+  a value; any other object is a container).
+- **`validate` no longer crashes on a malformed server value.** Reading
+  `.text` off a value that wasn't a ContentUnit threw
+  `Cannot read properties of undefined (reading 'trim')` and exit 1 — an
+  uncategorized crash on a normal run. The same normalization pass wraps bare
+  strings into `{ text, styles: {} }`, defaults a missing `styles`, and drops
+  a genuinely unusable leaf with a warning; `validate` treats an unusable
+  value as `empty` rather than assuming shape.
+- **Clear error for keys with non-header-safe characters.** Pasting the
+  dashboard's truncated key display (`sk_eng_…last4`) used to surface as a
+  misleading "server could not be reached" network error — the U+2026
+  ellipsis can't be encoded into the `Authorization` header. The CLI now
+  rejects such keys at every resolution point (env, credentials file,
+  `login`) with exit 3, naming the offending character and the likely
+  truncated-copy cause, before any request is sent.
+- **Security — codegen injection in `types generate`.** With `--server`, keys
+  and select-option labels are server-controlled; labels are now whitelisted
+  to `[A-Za-z0-9_]+` before reaching type position (non-conforming ones drop,
+  all-hostile falls back to `string`) and key escaping `\u`-escapes control
+  characters and JS line terminators, so no remote string can inject
+  declarations into the generated `.d.ts`.
+- **Security — path containment for config-derived writes.** Pull targets,
+  multi-locale catalogs, snapshot outputs, and the generated `.d.ts` path must
+  resolve inside the project directory; `../` escapes and absolute paths are
+  rejected with exit 2 naming the offending path.
+
 ## 0.2.1 — 2026-07-20
 
 Security batch (PLAN items 19–23).

package/README.md

@@ -22,6 +22,7 @@ Phase 1 (file-sync dev-loop) is implemented. Command surface:
 | ----------------- | ------ | ------------------------------------------------------------------- |
 | `init`            | ✅     | Scaffold a `lionrapid.yml` (detects Flutter/iOS/Android/Rails/JS)   |
 | `push`            | ✅     | Upload source strings to the backend (server handles MT)            |
+| `status [job-id]` | ✅     | What the backend actually did with what `push` queued               |
 | `pull [--types]`  | ✅     | Download translations into target files; optionally regen types     |
 | `validate [--ci]` | ✅     | Check local files vs the backend for missing/orphan/empty keys      |
 | `types generate`  | ✅     | Generate a typed `.d.ts` from your source files (offline)           |
@@ -47,6 +48,35 @@ files:
   - { format: json, source: app/en.json,    target: app/{locale}.json } # → namespace: app
 ```
 
+**Glob entries:** `source` may be a glob (`*`/`?`); `target` and `namespace`
+must then carry a `{basename}` token, replaced per matched file with its
+extension-less name. One stanza covers a whole directory of per-page (or
+per-feature) catalogs, each in its own namespace:
+
+```yaml
+files:
+  - format: json
+    source: locales/en/*.json # locales/en/home.json, pricing.json, …
+    target: locales/{locale}/{basename}.json
+    namespace: '{basename}' # → namespaces home, pricing, …
+```
+
+Globs expand once at config load (sorted, so behavior is deterministic) —
+`push`/`pull`/`validate` see one concrete entry per matched file, and `doctor`
+reports the expanded count. A glob that matches nothing prints a warning
+instead of silently doing nothing; a glob entry without `{basename}` in _both_
+`target` and `namespace` is rejected as ambiguous.
+
+**Flat output:** JSON/YAML targets are written nested by default (a pushed
+`hero.title` comes back as `{"hero": {"title": …}}`). Set `flat: true` on a
+`files` entry to keep dotted keys literal on `pull`, so a flat-keyed file
+round-trips flat for flat-keyed consumers (CMS imports, webhook payloads):
+
+```yaml
+files:
+  - { format: json, source: locales/en.json, target: locales/{locale}.json, flat: true }
+```
+
 ## Reliability & automation
 
 Built for CI and AI agents — every networked command is resilient and scriptable.
@@ -61,9 +91,26 @@ Built for CI and AI agents — every networked command is resilient and scriptab
 - **Exit codes** (stable, gate CI on them): `0` ok · `1` unexpected · `2`
   validation/config · `3` auth · `4` network/5xx · `5` partial.
 - **Automatic retries**: transient failures (network error, `5xx`, `429`) are
-  retried with exponential backoff + jitter; a `429` honors `Retry-After`. Tune
-  with `LIONRAPID_RETRIES` (default `3`; `0` disables). Writes are safe to retry —
-  the integration endpoints upsert by composite key.
+  retried with exponential backoff + jitter. A `429` honors `Retry-After` when
+  the server sends it; when it doesn't, the CLI waits a rate-limit-window 30 s
+  instead of jittering, so a many-namespace push rides out a per-minute limit.
+  Tune with `LIONRAPID_RETRIES` (default `3`; `0` disables). Writes are safe to
+  retry — the integration endpoints upsert by composite key.
+- **Partial progress** (`push`, `pull`): one failing namespace or file doesn't
+  zero the run — the rest complete, failures are listed per file (and as
+  `error` fields under `--json`), and the exit code is `5` (partial).
+  Re-running retries just the failures; pushes upsert, so that's always safe.
+- **Pushed ≠ stored (`push` → `status`)**: `sync/batch` answers `202 Accepted`,
+  so `push`'s counts are what the CLI **sent**; the backend stores them in a
+  background job that can still fail or dead-letter. `push` therefore prints the
+  job ids it queued and saves them to `~/.lionrapid/jobs.json`, and
+  `lionrapid status <job-id>` reports the server's verdict — stored, still
+  queued, retrying, or dead-lettered (with the reason and every failed attempt).
+  Bare `lionrapid status` lists every job this machine pushed, newest first,
+  re-checking only the unresolved ones; with nothing recorded it falls back to
+  the server's queue health + dead-letter queue. Offline, it still prints the
+  local record, labelled `(last known)`. History is capped at 500 entries /
+  30 days and never shares a file with your credentials.
 - **Concurrent `pull`**: namespace fetches fan out with bounded concurrency
   (`LIONRAPID_CONCURRENCY`, default `6`) and show interactive progress on a TTY.
   Output stays deterministic — only the network fan-out is parallelized.
@@ -143,7 +190,9 @@ already translated on your website are translated in the app for free.
 
 ```bash
 lionrapid init --project <id> --targets es,fr
-lionrapid push
+lionrapid push                 # prints the job ids it queued
+lionrapid status               # …and what the backend did with them
+lionrapid status <job-id>      # the full story on one job
 lionrapid pull --types
 lionrapid validate --ci
 

package/dist/adapters/json.d.ts

@@ -3,10 +3,10 @@
  * node backends). Nested objects flatten to dot-notation keys (`home.cta`) and
  * unflatten back on serialize, preserving insertion order.
  */
-import type { FormatAdapter, TranslationEntry } from './types.js';
+import type { FormatAdapter, SerializeOptions, TranslationEntry } from './types.js';
 export declare class JsonAdapter implements FormatAdapter {
     readonly format: "json";
     parse(content: string): TranslationEntry[];
-    serialize(entries: TranslationEntry[]): string;
+    serialize(entries: TranslationEntry[], options?: SerializeOptions): string;
 }
 //# sourceMappingURL=json.d.ts.map

package/dist/adapters/json.js

@@ -3,7 +3,7 @@
  * node backends). Nested objects flatten to dot-notation keys (`home.cta`) and
  * unflatten back on serialize, preserving insertion order.
  */
-import { flattenObject, unflattenEntries } from './nested.js';
+import { flatEntriesObject, flattenObject, unflattenEntries } from './nested.js';
 export class JsonAdapter {
     format = 'json';
     parse(content) {
@@ -24,8 +24,9 @@ export class JsonAdapter {
         flattenObject(data, '', out);
         return out;
     }
-    serialize(entries) {
-        return `${JSON.stringify(unflattenEntries(entries), null, 2)}\n`;
+    serialize(entries, options) {
+        const tree = options?.flat ? flatEntriesObject(entries) : unflattenEntries(entries);
+        return `${JSON.stringify(tree, null, 2)}\n`;
     }
 }
 //# sourceMappingURL=json.js.map

package/dist/adapters/nested.d.ts

@@ -5,5 +5,11 @@
  */
 import type { TranslationEntry } from './types.js';
 export declare function flattenObject(obj: Record<string, unknown>, prefix: string, out: TranslationEntry[]): void;
+/**
+ * Flat serialize: dotted keys stay literal (`"hero.title"`), nothing re-nests.
+ * Built with Object.fromEntries so a hostile key like `__proto__` lands as a
+ * plain own property instead of touching the prototype.
+ */
+export declare function flatEntriesObject(entries: TranslationEntry[]): Record<string, unknown>;
 export declare function unflattenEntries(entries: TranslationEntry[], onSkippedKey?: (key: string) => void): Record<string, unknown>;
 //# sourceMappingURL=nested.d.ts.map

package/dist/adapters/nested.js

@@ -18,6 +18,14 @@ export function flattenObject(obj, prefix, out) {
         }
     }
 }
+/**
+ * Flat serialize: dotted keys stay literal (`"hero.title"`), nothing re-nests.
+ * Built with Object.fromEntries so a hostile key like `__proto__` lands as a
+ * plain own property instead of touching the prototype.
+ */
+export function flatEntriesObject(entries) {
+    return Object.fromEntries(entries.map((e) => [e.key, fromContentUnit(e.value)]));
+}
 /** Path segments that would write onto the prototype chain instead of plain data. */
 const UNSAFE_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
 function warnSkippedKey(key) {

package/dist/adapters/types.d.ts

@@ -30,6 +30,8 @@ export interface SerializeOptions {
     locale?: string;
     /** Source locale, recorded by bilingual formats (e.g. XLIFF `source-language`). */
     sourceLocale?: string;
+    /** Keep dotted keys flat (JSON/YAML) instead of re-nesting them into objects. */
+    flat?: boolean;
 }
 export interface FormatAdapter {
     readonly format: FileFormat;

package/dist/adapters/yaml.js

@@ -8,7 +8,7 @@
  * JSON adapter; this adapter assumes the Rails/locale-rooted shape.)
  */
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { flattenObject, unflattenEntries } from './nested.js';
+import { flatEntriesObject, flattenObject, unflattenEntries } from './nested.js';
 function isObject(v) {
     return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
@@ -43,8 +43,8 @@ export class YamlAdapter {
         return out;
     }
     serialize(entries, options) {
-        const nested = unflattenEntries(entries);
-        const doc = options?.locale ? { [options.locale]: nested } : nested;
+        const tree = options?.flat ? flatEntriesObject(entries) : unflattenEntries(entries);
+        const doc = options?.locale ? { [options.locale]: tree } : tree;
         return stringifyYaml(doc);
     }
 }

package/dist/api-client.d.ts

@@ -14,6 +14,90 @@ export interface KeyedTranslation {
     key: string;
     value: ContentUnit;
 }
+/**
+ * The 202 body of `POST /api/integrations/sync/batch` — a mirror of the
+ * server's `BatchSyncJobResponse` (tm-server
+ * `backend/app/domains/integrations/contracts/responses.py`). Field names are
+ * the wire names on purpose: this type IS the contract, and
+ * {@link BATCH_SYNC_RESPONSE_FIELDS} guards it against server drift.
+ *
+ * 202 means **queued, not stored**. The rows only reach the database when the
+ * job queued here actually runs, so a push that returns 202 for every batch is
+ * still compatible with the backend later failing or dead-lettering the work.
+ * The job ids are the only way a client can tell those apart — discarding this
+ * body (as `syncBatch` used to) is what made a failed sync indistinguishable
+ * from a successful one.
+ */
+export interface SyncBatchResponse {
+    /** First queued job id — the server's legacy alias for `job_ids[0]`. */
+    job_id: string;
+    /** ALL queued job ids — one per locale group in the batch. */
+    job_ids: string[];
+    /** Job status at enqueue time (`pending`). */
+    status: string;
+    /** Number of keys the server accepted into the batch. */
+    total_keys: number;
+    /** Human-readable message — carries the server's own poll hint. */
+    message: string;
+}
+/**
+ * The REQUIRED fields of the server's `BatchSyncJobResponse`, transcribed from
+ * `contracts/responses.py` (a field with no default is required there).
+ *
+ * DRIFT GUARD, field level. `job_id`/`job_ids` existed server-side the whole
+ * time and the CLI silently dropped them — a `Promise<void>` cannot be caught
+ * by any test, because there is nothing to assert on. This list plus
+ * {@link SyncBatchResponseCoversContract} makes that failure a *compile* error:
+ * add a required field here without adding it to {@link SyncBatchResponse} and
+ * `npm run typecheck` fails, so the next server field can't vanish the same way.
+ *
+ * (Deliberately not derived from the server's OpenAPI: tm-server is a separate
+ * repo, so that check would need a network fetch or a snapshot to drift on its
+ * own. Hand-transcribing five names is the cheaper, non-flaky half.)
+ */
+export declare const BATCH_SYNC_RESPONSE_FIELDS: readonly ["job_id", "job_ids", "status", "total_keys", "message"];
+/** Compiles only when `T` is `never` — i.e. no contract field is unaccounted for. */
+type NoMissingContractFields<T extends never> = T;
+/**
+ * The guard itself. Exported as a type (not a value) so it costs no runtime and
+ * no lint suppression, and it is checked because `tsc --noEmit` covers `src/`.
+ */
+export type SyncBatchResponseCoversContract = NoMissingContractFields<Exclude<(typeof BATCH_SYNC_RESPONSE_FIELDS)[number], keyof SyncBatchResponse>>;
+/**
+ * A sync job's server-side state — `GET /api/integrations/sync/jobs/{id}`
+ * (`SyncJobStatusResponse`). Camel-cased because, unlike
+ * {@link SyncBatchResponse}, this is the CLI's own view rather than a guarded
+ * contract mirror.
+ *
+ * `status` is one of `pending` / `processing` / `retry_pending` / `completed` /
+ * `failed`. The server only ever sets `failed` from its dead-letter path, so a
+ * `failed` job is one the backend gave up on: those rows were never stored.
+ */
+export interface SyncJobStatus {
+    jobId: string;
+    status: string;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** Sync outcome on success (`keys_added`, `keys_updated`, …). */
+    result?: Record<string, unknown>;
+    error?: string;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt?: string;
+    /** One entry per failed attempt, oldest first. */
+    retryErrors: string[];
+    isDeadLettered: boolean;
+    deadLetterReason?: string;
+}
+/** Queue-wide metrics — `GET /api/integrations/sync/queue-health`. */
+export interface QueueHealth {
+    totalJobs: number;
+    queueDepth: number;
+    statusCounts: Record<string, number>;
+    dlqCount: number;
+    workerRunning: boolean;
+}
 /** Result of a namespace pull. `notModified` is true on a 304 (ETag hit). */
 export interface NamespaceBundle {
     translations: Record<string, ContentUnit>;
@@ -41,9 +125,17 @@ export interface ApiClientOptions {
     retries?: number;
     /** Injectable delay (defaults to real `setTimeout`). Tests pass a no-op. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Per-attempt request timeout in ms (each retry gets a fresh budget).
+     * Default {@link DEFAULT_TIMEOUT_MS}. A hung connection must never block
+     * push/pull/doctor forever — poison for CI.
+     */
+    timeoutMs?: number;
 }
 /** Default number of retries for transient failures. */
 export declare const DEFAULT_RETRIES = 3;
+/** Default per-attempt request timeout. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
 /**
  * Parse a `Retry-After` header → ms, or null if absent/unparseable. Accepts the
  * delta-seconds form (`120`) and the HTTP-date form; clamps to
@@ -68,6 +160,31 @@ export declare class ApiError extends Error {
 export declare class NetworkError extends Error {
     constructor(method: string, path: string, cause: unknown);
 }
+/**
+ * Coerce a namespace payload into flat `dotted.key` → {@link ContentUnit}.
+ *
+ * The endpoint takes flat keys on write but answers **nested** on read
+ * (`{"nav": {"cart": …}}` for a pushed `nav.cart`), because the SDK resolves
+ * nested paths. Every CLI adapter is built on flat dotted keys, so the tree
+ * has to be flattened back here or whole subtrees silently vanish. The leaf
+ * rule mirrors the server's: a string, or an object carrying `text`, is a
+ * value; any other object is a container to descend into. Bare strings are
+ * wrapped, a missing `styles` defaults to `{}`, and a genuinely unusable leaf
+ * is dropped with a warning rather than crashing the run.
+ */
+export declare function normalizeTranslations(raw: unknown): Record<string, ContentUnit>;
+/**
+ * Project the sync/batch body onto {@link SyncBatchResponse}, field by field.
+ *
+ * Written out explicitly rather than cast, so a dropped field is a *runtime*
+ * regression a test can see as well as a compile error (see
+ * {@link BATCH_SYNC_RESPONSE_FIELDS}). Every field degrades instead of throwing:
+ * an older server, a proxy that eats the body, or a 204 must leave push working
+ * — you simply get no job ids to report, which the CLI says out loud.
+ */
+export declare function normalizeSyncBatchResponse(raw: unknown): SyncBatchResponse;
+/** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
+export declare function normalizeSyncJob(raw: unknown): SyncJobStatus;
 export declare class LionRapidApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -75,6 +192,7 @@ export declare class LionRapidApiClient {
     private readonly fetchImpl;
     private readonly retries;
     private readonly sleep;
+    private readonly timeoutMs;
     constructor(opts: ApiClientOptions);
     /** True when this client holds an editor token and can publish (mark-ready). */
     get canPublish(): boolean;
@@ -82,11 +200,42 @@ export declare class LionRapidApiClient {
     ping(): Promise<{
         isPmAdmin: boolean;
     }>;
+    /**
+     * The project's dashboard-configured locales (for `init` prefill).
+     * GET /api/integrations/project-config — flat `{ defaultLocale, languages }`;
+     * `languages` includes the default locale. Malformed bodies normalize to
+     * empty values rather than throwing.
+     */
+    getProjectConfig(): Promise<{
+        defaultLocale: string;
+        languages: string[];
+    }>;
     /**
      * Register source-row text for `sourceLocale`. Mirrors what the edge does on
      * first visit when it encounters a missing key. POST /api/integrations/sync/batch.
+     *
+     * Returns the server's 202 body. It used to return `void` — the response was
+     * read and thrown away at the transport layer, which is why a push whose jobs
+     * later died looked exactly like one that worked. Callers get the job ids and
+     * can poll {@link getSyncJob}.
+     */
+    syncBatch(sourceLocale: string, namespace: string, items: KeyedTranslation[]): Promise<SyncBatchResponse>;
+    /**
+     * A queued sync job's state. GET /api/integrations/sync/jobs/{id}.
+     *
+     * The lookup is project-scoped server-side, and finished non-DLQ jobs are
+     * purged after ~1h — an unknown id 404s, which is why the CLI also keeps its
+     * own history (a job that completed yesterday can only be answered from disk).
+     */
+    getSyncJob(jobId: string): Promise<SyncJobStatus>;
+    /**
+     * Jobs the backend gave up on. GET /api/integrations/sync/dead-letter-queue.
+     * Needs the `ops:queue` scope (master keys have it; publishable `pk_` keys
+     * do not — those get a 403).
      */
-    syncBatch(sourceLocale: string, namespace: string, items: KeyedTranslation[]): Promise<void>;
+    getDeadLetterQueue(): Promise<SyncJobStatus[]>;
+    /** Queue-wide metrics. GET /api/integrations/sync/queue-health (`ops:queue`). */
+    getQueueHealth(): Promise<QueueHealth>;
     /**
      * Write target-locale translations as drafts (editor-visible, not public
      * until mark-ready). PUT /api/integrations/targets/batch.
@@ -120,4 +269,5 @@ export declare class LionRapidApiClient {
      */
     private doFetch;
 }
+export {};
 //# sourceMappingURL=api-client.d.ts.map