@lionrapid/cli 0.2.1 → 0.3.0

package/dist/api-client.js

@@ -8,13 +8,52 @@
  * uses native `fetch`. `fetch` is injectable so the client is unit-testable
  * without a live server.
  */
+/**
+ * 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 const BATCH_SYNC_RESPONSE_FIELDS = [
+    'job_id',
+    'job_ids',
+    'status',
+    'total_keys',
+    'message',
+];
 /** Default number of retries for transient failures. */
 export const DEFAULT_RETRIES = 3;
+/** Default per-attempt request timeout. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
 /** Base backoff in ms; grows exponentially per attempt, capped at {@link MAX_BACKOFF_MS}. */
 const BASE_BACKOFF_MS = 300;
 const MAX_BACKOFF_MS = 10_000;
 /** Cap on an honored `Retry-After` so a hostile/misconfigured header can't hang the CLI. */
 const MAX_RETRY_AFTER_MS = 30_000;
+/**
+ * Wait for a 429 that carries no `Retry-After` header. tm-server's rate-limit
+ * responses send none, and its limits are per-minute windows — the jittered
+ * sub-second backoff below can never outlive one, so without this floor every
+ * 429 exhausted its retries and was effectively fatal (e.g. a push past the
+ * 30/min sync limit died at namespace 31).
+ */
+const RATE_LIMIT_FALLBACK_MS = 30_000;
+/**
+ * Surface self-identification for the server's surface registry: snippet,
+ * WordPress and the CLI all share the same project-wide key, so each client
+ * tags its requests with which surface it is. Older servers ignore unknown
+ * headers — additive and inert.
+ */
+const SURFACE_HEADER = { 'X-LR-Surface': 'cli' };
 /** Transient statuses worth retrying: rate-limit (429) and any 5xx. */
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
@@ -98,6 +137,101 @@ export class NetworkError extends Error {
 function compositeKey(locale, namespace, key) {
     return `${locale}:${namespace}:${key}`;
 }
+/**
+ * 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 function normalizeTranslations(raw) {
+    const out = {};
+    const walk = (node, prefix) => {
+        if (node === null || typeof node !== 'object') {
+            console.error(`warning: skipped key "${prefix}" — server returned no usable text`);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === 'string') {
+                out[path] = { text: value, styles: {} };
+                continue;
+            }
+            if (value !== null && typeof value === 'object') {
+                const unit = value;
+                if (typeof unit.text === 'string') {
+                    out[path] = { text: unit.text, styles: (unit.styles ?? {}) };
+                }
+                else {
+                    walk(value, path); // a container, not a value
+                }
+                continue;
+            }
+            console.error(`warning: skipped key "${path}" — server returned no usable text`);
+        }
+    };
+    if (raw === null || typeof raw !== 'object')
+        return {};
+    walk(raw, '');
+    return out;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * 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 function normalizeSyncBatchResponse(raw) {
+    const body = isRecord(raw) ? raw : {};
+    const primary = asString(body['job_id']);
+    const ids = asStringArray(body['job_ids']);
+    // The server sets job_id = job_ids[0]; tolerate either side being absent so
+    // one missing field never costs us the other.
+    const jobIds = ids.length > 0 ? ids : primary ? [primary] : [];
+    return {
+        job_id: primary ?? jobIds[0] ?? '',
+        job_ids: jobIds,
+        status: asString(body['status']) ?? '',
+        total_keys: typeof body['total_keys'] === 'number' ? body['total_keys'] : 0,
+        message: asString(body['message']) ?? '',
+    };
+}
+/** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
+export function normalizeSyncJob(raw) {
+    const body = isRecord(raw) ? raw : {};
+    return {
+        jobId: asString(body['job_id']) ?? '',
+        status: asString(body['status']) ?? 'unknown',
+        createdAt: asString(body['created_at']),
+        startedAt: asString(body['started_at']),
+        completedAt: asString(body['completed_at']),
+        result: isRecord(body['result']) ? body['result'] : undefined,
+        error: asString(body['error']),
+        retryCount: typeof body['retry_count'] === 'number' ? body['retry_count'] : 0,
+        maxRetries: typeof body['max_retries'] === 'number' ? body['max_retries'] : 0,
+        nextRetryAt: asString(body['next_retry_at']),
+        retryErrors: asStringArray(body['retry_errors']),
+        isDeadLettered: body['is_dead_lettered'] === true,
+        deadLetterReason: asString(body['dead_letter_reason']),
+    };
+}
 export class LionRapidApiClient {
     baseUrl;
     apiKey;
@@ -105,6 +239,7 @@ export class LionRapidApiClient {
     fetchImpl;
     retries;
     sleep;
+    timeoutMs;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/$/, '');
         this.apiKey = opts.apiKey;
@@ -113,6 +248,7 @@ export class LionRapidApiClient {
         this.retries = Math.max(0, opts.retries ?? DEFAULT_RETRIES);
         this.sleep =
             opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.timeoutMs = Math.max(1, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     }
     /** True when this client holds an editor token and can publish (mark-ready). */
     get canPublish() {
@@ -123,19 +259,80 @@ export class LionRapidApiClient {
         const res = (await this.request('GET', '/api/integrations/editor/workflow'));
         return { isPmAdmin: !!res?.is_pm_admin };
     }
+    /**
+     * 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.
+     */
+    async getProjectConfig() {
+        const res = (await this.request('GET', '/api/integrations/project-config'));
+        return {
+            defaultLocale: typeof res?.defaultLocale === 'string' ? res.defaultLocale : '',
+            languages: Array.isArray(res?.languages)
+                ? res.languages.filter((l) => typeof l === '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}.
      */
     async syncBatch(sourceLocale, namespace, items) {
         const translations = items.map((it) => ({
             key: compositeKey(sourceLocale, namespace, it.key),
             value: it.value,
         }));
-        await this.request('POST', '/api/integrations/sync/batch', {
+        const res = await this.request('POST', '/api/integrations/sync/batch', {
             translations,
             format: 'contentunit',
         });
+        return normalizeSyncBatchResponse(res);
+    }
+    /**
+     * 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).
+     */
+    async getSyncJob(jobId) {
+        const res = await this.request('GET', `/api/integrations/sync/jobs/${encodeURIComponent(jobId)}`);
+        return normalizeSyncJob(res);
+    }
+    /**
+     * 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).
+     */
+    async getDeadLetterQueue() {
+        const res = await this.request('GET', '/api/integrations/sync/dead-letter-queue');
+        const jobs = isRecord(res) && Array.isArray(res['jobs']) ? res['jobs'] : [];
+        return jobs.map(normalizeSyncJob);
+    }
+    /** Queue-wide metrics. GET /api/integrations/sync/queue-health (`ops:queue`). */
+    async getQueueHealth() {
+        const res = await this.request('GET', '/api/integrations/sync/queue-health');
+        const body = isRecord(res) ? res : {};
+        const counts = {};
+        if (isRecord(body['status_counts'])) {
+            for (const [k, v] of Object.entries(body['status_counts'])) {
+                if (typeof v === 'number')
+                    counts[k] = v;
+            }
+        }
+        return {
+            totalJobs: typeof body['total_jobs'] === 'number' ? body['total_jobs'] : 0,
+            queueDepth: typeof body['queue_depth'] === 'number' ? body['queue_depth'] : 0,
+            statusCounts: counts,
+            dlqCount: typeof body['dlq_count'] === 'number' ? body['dlq_count'] : 0,
+            workerRunning: body['worker_running'] === true,
+        };
     }
     /**
      * Write target-locale translations as drafts (editor-visible, not public
@@ -187,7 +384,7 @@ export class LionRapidApiClient {
         }
         const data = (await res.json());
         return {
-            translations: data.translations ?? {},
+            translations: normalizeTranslations(data.translations),
             version: data.meta?.version != null ? String(data.meta.version) : undefined,
             notModified: false,
             locked: false,
@@ -231,11 +428,18 @@ export class LionRapidApiClient {
             try {
                 // `redirect: 'error'` pins every request to the configured host: a 3xx
                 // fails loudly instead of relying on the runtime to strip the
-                // Authorization header on a cross-origin redirect.
-                res = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init, redirect: 'error' });
+                // Authorization header on a cross-origin redirect. The timeout signal
+                // is per-attempt, so every retry gets a fresh budget.
+                res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    ...init,
+                    headers: { ...SURFACE_HEADER, ...init.headers },
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
             }
             catch (err) {
-                netErr = new NetworkError(method, path, err);
+                const isTimeout = err instanceof Error && err.name === 'TimeoutError';
+                netErr = new NetworkError(method, path, isTimeout ? new Error(`timed out after ${this.timeoutMs}ms`, { cause: err }) : err);
                 // A refused redirect is the server's answer, not a transient failure.
                 if (isRedirectFailure(err))
                     throw netErr;
@@ -245,7 +449,13 @@ export class LionRapidApiClient {
                 // Exception: a 404 that's really "a sync is already processing for this
                 // project" is transient. Peek at the body (only for 404s); retry if it's
                 // that case and attempts remain, otherwise hand the body back intact.
-                if (res.status === 404 && attempt < this.retries) {
+                //
+                // Writes only: that 404 is the enqueue path's answer. `GET
+                // /sync/jobs/{id}` returns the same SYNC_JOB_NOT_FOUND code for a job
+                // that genuinely does not exist (unknown id, or one purged after the
+                // server's ~1h retention), and `lionrapid status` must answer that
+                // immediately instead of backing off three times first.
+                if (res.status === 404 && method !== 'GET' && attempt < this.retries) {
                     const body = await safeText(res);
                     if (isSyncInProgress(body)) {
                         await this.sleep(backoffMs(attempt, Math.random));
@@ -261,8 +471,11 @@ export class LionRapidApiClient {
                     return res;
                 throw netErr;
             }
-            const retryAfter = res?.status === 429 ? parseRetryAfter(res.headers.get('retry-after'), Date.now()) : null;
-            const delay = retryAfter ?? backoffMs(attempt, Math.random);
+            // A 429 is a rate-limit window, not a blip: honor `Retry-After` when the
+            // server sent one, else wait window-sized instead of jittering.
+            const delay = res?.status === 429
+                ? (parseRetryAfter(res.headers.get('retry-after'), Date.now()) ?? RATE_LIMIT_FALLBACK_MS)
+                : backoffMs(attempt, Math.random);
             await this.sleep(delay);
         }
     }

package/dist/cli.d.ts

@@ -4,8 +4,7 @@
  * PO) with the LionRapid backend.
  *
  * This file wires up the command surface. Each command's behaviour lives in
- * `src/commands/*`; commands not yet implemented print a clear "not implemented
- * yet" notice and exit non-zero so scripts never silently succeed.
+ * `src/commands/*`.
  */
 import { Command } from 'commander';
 /**