@madewithremy/admin 0.1.25 → 0.1.27

package/README.md

@@ -1,6 +1,6 @@
 # @madewithremy/admin
 
-Admin SDK + CLI for managing production Remy apps: request logs, analytics, releases, users, secrets, database, files, email (including custom sending/receiving domains), scheduled jobs, and more. Every operation wraps the same management API the dashboard uses, so anything answerable in the console is answerable here — from the terminal or from code.
+Admin SDK + CLI for managing production Remy apps: request logs, analytics, releases, users, secrets, database, files, email (including custom sending/receiving domains), scheduled jobs, QA replays, and more. Almost every operation wraps the same management API the dashboard uses, so anything answerable in the console is answerable here — from the terminal or from code. The exception is `qa-recordings export`, which renders a video on the dev box and therefore only runs inside a sandbox.
 
 One surface, two skins: every CLI command (`remy-admin <group> <sub>`) is also a typed client method (`admin.<group>.<sub>()`). Both are thin layers over the same ops core.
 
@@ -28,6 +28,7 @@ Configuration is read from the environment and the workspace — there are no co
 | `API_BASE_URL` | API origin (default `https://api.mindstudio.ai`) |
 | `WORKSPACE_DIR` | Workspace root (default `/home/vercel-sandbox/workspace`) |
 | `${WORKSPACE_DIR}/mindstudio.json` | `appId` — which app the CLI manages |
+| `REMY_SIDECAR_URL` | Sandbox sidecar for `qa-recordings export` (default `http://127.0.0.1:4388`) |
 
 ## Import layer
 

package/dist/index.d.ts

@@ -635,16 +635,17 @@ interface EventsTailFrame {
 
 interface EventsScopeParams {
     /**
-     * Environment scope to inspect: `live` (default), `preview:<releaseId>`,
-     * or `dev:<sessionId>` — publishes and subscriptions never cross scopes,
-     * so a tunnel session's events are visible only under its `dev:` scope.
+     * Environment scope to inspect: `live` (the default for reads),
+     * `preview:<releaseId>`, or `dev:<sessionId>` — publishes and subscriptions
+     * never cross scopes, so a dev session's events are visible only under its
+     * `dev:` scope. A publish without one goes to the caller's own dev session.
      */
     scope?: string;
 }
 interface EventsPublishParams extends EventsScopeParams {
     /** Exact channel name(s) — no wildcards anywhere in app events. */
     channels: string | string[];
-    /** The payload subscribers receive (≤32k serialized characters). */
+    /** The payload subscribers receive (≤256k serialized characters). */
     data: unknown;
 }
 /**
@@ -665,10 +666,13 @@ declare function channelsList(ctx: AdminContext, params?: EventsScopeParams): Pr
  * same validation, same delivery, same metering. Lets a frontend subscriber
  * be verified before the backend trigger exists.
  *
- * `delivered` counts live subscriber connections per published channel;
- * `0` is normal (nobody listening), never an error.
+ * Without `scope` it goes to the caller's own dev session, the preview they
+ * are building in; `scope: 'live'` reaches real users. The result's `scope`
+ * says where it went. `delivered` counts live subscriber connections per
+ * published channel; `0` is normal (nobody listening), never an error.
  *
- * @throws AdminApiError `invalid_channels` / `payload_too_large` (400).
+ * @throws AdminApiError `invalid_channels` / `payload_too_large` (400), and
+ *   `no_dev_session` (400) with no `scope` when the caller has no dev session.
  * @example
  * const { delivered } = await admin.events.publish({
  *   channels: 'jobs:usr_123',
@@ -4660,7 +4664,7 @@ interface FilesLsParams {
  *   prefix: 'images/',
  * });
  */
-declare function ls(ctx: AdminContext, params: FilesLsParams): Promise<FilesLsResult>;
+declare function ls$1(ctx: AdminContext, params: FilesLsParams): Promise<FilesLsResult>;
 /**
  * Store-level summary: every store with object counts, total bytes, and
  * AV/PII scan status histograms.
@@ -4684,14 +4688,13 @@ type files_FileRef = FileRef;
 type files_FilesLsParams = FilesLsParams;
 type files_FilesPutParams = FilesPutParams;
 declare const files_fetchBytes: typeof fetchBytes;
-declare const files_ls: typeof ls;
 declare const files_put: typeof put;
 declare const files_remove: typeof remove;
 declare const files_sign: typeof sign;
 declare const files_stat: typeof stat;
 declare const files_summary: typeof summary;
 declare namespace files {
-  export { type files_FileAccess as FileAccess, type files_FileRef as FileRef, type files_FilesLsParams as FilesLsParams, type files_FilesPutParams as FilesPutParams, files_fetchBytes as fetchBytes, files_ls as ls, files_put as put, files_remove as remove, files_sign as sign, files_stat as stat, files_summary as summary };
+  export { type files_FileAccess as FileAccess, type files_FileRef as FileRef, type files_FilesLsParams as FilesLsParams, type files_FilesPutParams as FilesPutParams, files_fetchBytes as fetchBytes, ls$1 as ls, files_put as put, files_remove as remove, files_sign as sign, files_stat as stat, files_summary as summary };
 }
 
 /**
@@ -6399,6 +6402,129 @@ declare namespace prerender {
   export { type prerender_PrerenderInvalidateParams as PrerenderInvalidateParams, type prerender_PrerenderPagesParams as PrerenderPagesParams, type prerender_PrerenderViewParams as PrerenderViewParams, prerender_invalidate as invalidate, prerender_pages as pages, prerender_view as view };
 }
 
+/**
+ * Response types for browser-QA replay recordings.
+ *
+ * Chunks are ordinary private files in the app's `qa-recordings` store, keyed
+ * `{sessionId}/{runId}/{seq}.json`, so `ls` here is a grouped view over
+ * `files.ls` rather than its own endpoint. Transcribed from youai-api:
+ *   src/http/routes/V2Apps/develop/recordings.ts
+ *   src/common/Recordings/sessions.ts
+ *
+ * Export is the exception — it renders on the dev box (see ../ops/recordings).
+ */
+/** One document lifetime within a session: a page load and everything after it
+ *  until the next one. Its lowest-seq chunk carries the rrweb FullSnapshot. */
+interface QaRecordingRun {
+    runId: string;
+    chunks: number;
+    bytes: number;
+    /** Store-relative keys, in seq order. */
+    keys: string[];
+}
+/** One recording session — a single tunnel process's continuous recording. */
+interface QaRecordingSession {
+    sessionId: string;
+    chunks: number;
+    bytes: number;
+    /** ISO-8601, from the chunk objects' last-modified times. */
+    startedAt?: string;
+    endedAt?: string;
+    runs: QaRecordingRun[];
+}
+interface QaRecordingsLsResult {
+    store: string;
+    sessions: QaRecordingSession[];
+    /** Present when the listing was truncated — pass it back as `cursor`. */
+    cursor?: string;
+}
+interface QaRecordingsExportResult {
+    jobId: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    /** Public target only. A private one gives `store`/`key`; sign it with
+     *  `files sign` when you want a link. */
+    url?: string;
+    store?: string;
+    key?: string;
+    width?: number;
+    height?: number;
+    /** Length of the rendered clip, dead air already collapsed. */
+    durationMs?: number;
+    error?: string;
+    errorCode?: string;
+}
+
+/**
+ * Browser-QA replay recordings: list what the QA agent recorded, and render a
+ * replay to an mp4.
+ *
+ * `ls` is a grouped view over `files.ls` — a replay chunk is an ordinary
+ * private file in the app's `qa-recordings` store and needs no endpoint of its
+ * own.
+ *
+ * `export` is the one operation in this SDK that does NOT go through the
+ * management API. Rendering a replay means playing it in a real browser and
+ * encoding the frames, and the only machine set up to do that is the dev box
+ * the recording was made on: it already has the headless Chrome, the rrweb
+ * replayer and ffmpeg. So this talks to the sandbox's local sidecar, and says
+ * so plainly when there isn't one. (CLI-only paths are established here —
+ * `methods invoke --stream`, `jewels export --file` — but this is the first
+ * that needs local compute rather than local disk.)
+ */
+
+/** The app store QA replay chunks are written to (private). */
+declare const RECORDING_STORE = "qa-recordings";
+interface QaRecordingsLsParams {
+    /** Only this session. Omitted → every session in the store. */
+    sessionId?: string;
+    cursor?: string;
+    /** Chunk objects to scan, not sessions returned. */
+    limit?: number;
+}
+/**
+ * Recording sessions in this app, grouped from the chunk keys.
+ *
+ * @example
+ * const { sessions } = await admin.qaRecordings.ls({});
+ * // → [{ sessionId, chunks, bytes, runs: [{ runId, keys }] }]
+ */
+declare function ls(ctx: AdminContext, params?: QaRecordingsLsParams): Promise<QaRecordingsLsResult>;
+interface QaRecordingsExportParams {
+    /** The recording session to render (32 hex characters). */
+    sessionId: string;
+    /** Window of the session, as epoch milliseconds. Both required: a replay is
+     *  a slice of a continuous recording, not a file. */
+    from: number;
+    to: number;
+    /** Where the mp4 is written. Defaults to `assets`, public. */
+    store?: string;
+    access?: 'public' | 'private';
+    /** Milliseconds to wait for the render. */
+    timeoutMs?: number;
+}
+/**
+ * Render a window of a recording session to an mp4 on the dev box.
+ *
+ * Blocks for the whole render — the clip plays in real time, then encodes and
+ * uploads — and answers with where the video landed. Runs only on a Remy dev
+ * box, since that is where the browser and ffmpeg are.
+ *
+ * @example
+ * const { url } = await admin.qaRecordings.exportVideo({
+ *   sessionId, from: 1758000000000, to: 1758000042000,
+ * });
+ */
+declare function exportVideo(_ctx: AdminContext, params: QaRecordingsExportParams): Promise<QaRecordingsExportResult>;
+
+type qaRecordings_QaRecordingsExportParams = QaRecordingsExportParams;
+type qaRecordings_QaRecordingsLsParams = QaRecordingsLsParams;
+declare const qaRecordings_RECORDING_STORE: typeof RECORDING_STORE;
+declare const qaRecordings_exportVideo: typeof exportVideo;
+declare const qaRecordings_ls: typeof ls;
+declare namespace qaRecordings {
+  export { type qaRecordings_QaRecordingsExportParams as QaRecordingsExportParams, type qaRecordings_QaRecordingsLsParams as QaRecordingsLsParams, qaRecordings_RECORDING_STORE as RECORDING_STORE, qaRecordings_exportVideo as exportVideo, qaRecordings_ls as ls };
+}
+
 /**
  * Release operations: list, get, by-commit, dashboard live-release, and the
  * composite waitForCommit op that owns the two poll loops.
@@ -7590,6 +7716,7 @@ declare function buildClient(ctx: AdminContext): {
     jewels: BoundOps<typeof jewels>;
     methods: BoundOps<typeof methods>;
     prerender: BoundOps<typeof prerender>;
+    qaRecordings: BoundOps<typeof qaRecordings>;
     releases: BoundOps<typeof releases>;
     requests: BoundOps<typeof requests>;
     secrets: BoundOps<typeof secrets>;

package/dist/index.js

@@ -10,6 +10,7 @@ import path from "path";
 
 // src/config.ts
 var WORKSPACE_DIR = process.env["WORKSPACE_DIR"] || "/home/remy/workspace";
+var SIDECAR_URL = process.env["REMY_SIDECAR_URL"] || "http://127.0.0.1:4388";
 
 // src/parseJsonConfig.ts
 import JSON5 from "json5";
@@ -2415,6 +2416,112 @@ function invalidate(ctx, params = {}) {
   );
 }
 
+// src/ops/qaRecordings.ts
+var qaRecordings_exports = {};
+__export(qaRecordings_exports, {
+  RECORDING_STORE: () => RECORDING_STORE,
+  exportVideo: () => exportVideo,
+  ls: () => ls2
+});
+var RECORDING_STORE = "qa-recordings";
+async function ls2(ctx, params = {}) {
+  const page = await ls(ctx, {
+    store: RECORDING_STORE,
+    access: "private",
+    ...params.sessionId ? { prefix: `${params.sessionId}/` } : {},
+    ...params.cursor ? { cursor: params.cursor } : {},
+    ...params.limit ? { limit: params.limit } : {}
+  });
+  const sessions = /* @__PURE__ */ new Map();
+  for (const entry of page.files) {
+    const parts = entry.key.split("/");
+    if (parts.length !== 3) {
+      continue;
+    }
+    const [sessionId, runId] = parts;
+    let session = sessions.get(sessionId);
+    if (!session) {
+      session = { sessionId, chunks: 0, bytes: 0, runs: [] };
+      sessions.set(sessionId, session);
+    }
+    let run3 = session.runs.find((r) => r.runId === runId);
+    if (!run3) {
+      run3 = { runId, chunks: 0, bytes: 0, keys: [] };
+      session.runs.push(run3);
+    }
+    const size = entry.size ?? 0;
+    session.chunks += 1;
+    session.bytes += size;
+    run3.chunks += 1;
+    run3.bytes += size;
+    run3.keys.push(entry.key);
+    if (entry.updatedAt) {
+      if (!session.startedAt || entry.updatedAt < session.startedAt) {
+        session.startedAt = entry.updatedAt;
+      }
+      if (!session.endedAt || entry.updatedAt > session.endedAt) {
+        session.endedAt = entry.updatedAt;
+      }
+    }
+  }
+  for (const session of sessions.values()) {
+    for (const run3 of session.runs) {
+      run3.keys.sort((a, b) => seqOf(a) - seqOf(b));
+    }
+  }
+  return {
+    store: RECORDING_STORE,
+    sessions: [...sessions.values()].sort(
+      (a, b) => (b.endedAt ?? "").localeCompare(a.endedAt ?? "")
+    ),
+    ...page.cursor ? { cursor: page.cursor } : {}
+  };
+}
+function seqOf(key) {
+  const n = Number(
+    key.split("/").pop()?.replace(/\.json$/, "")
+  );
+  return Number.isFinite(n) ? n : 0;
+}
+var DEFAULT_EXPORT_TIMEOUT_MS = 66e4;
+async function exportVideo(_ctx, params) {
+  const body = {
+    recordingSessionId: params.sessionId,
+    startTs: params.from,
+    endTs: params.to,
+    ...params.store ? { store: params.store } : {},
+    ...params.access ? { access: params.access } : {}
+  };
+  let res;
+  try {
+    res = await fetch(`${SIDECAR_URL}/export-recording`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(
+        params.timeoutMs ?? DEFAULT_EXPORT_TIMEOUT_MS
+      )
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the sandbox at ${SIDECAR_URL} (${err instanceof Error ? err.message : String(err)}). Rendering a replay needs the dev box that recorded it \u2014 this command only works inside a Remy sandbox.`
+    );
+  }
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(
+      typeof payload.error === "string" ? payload.error : `The sandbox refused the export (HTTP ${res.status}).`
+    );
+  }
+  const status2 = payload.export;
+  if (!status2) {
+    throw new Error(
+      "The sandbox accepted the export but reported no result. Check the box's tunnel logs."
+    );
+  }
+  return status2;
+}
+
 // src/ops/requests.ts
 var requests_exports = {};
 __export(requests_exports, {
@@ -2748,6 +2855,7 @@ function buildClient(ctx) {
     jewels: bindOps(jewels_exports, ctx),
     methods: bindOps(methods_exports, ctx),
     prerender: bindOps(prerender_exports, ctx),
+    qaRecordings: bindOps(qaRecordings_exports, ctx),
     releases: bindOps(releases_exports, ctx),
     requests: bindOps(requests_exports, ctx),
     secrets: bindOps(secrets_exports, ctx),