Files
hyperframes/packages/cli/src/cloud/errors.ts
T
James RussoandClaude Opus 4.7 a59ff0d91b feat(cli): migrate cloud-render upload to /v3/assets/direct-uploads (200MB) (#1844)
* chore(cli): regenerate cloud client for createAssetUpload + completeAssetUpload

Regenerated from experiment-framework `master` at commit `e74815f7af` (the
merge of EF#41085, which added `/v3/assets/direct-uploads` +
`/v3/assets/{asset_id}/complete` to the `TARGET_ENDPOINTS` allowlist in
`scripts/generate_hyperframes_cli_client.py`).

The `sync-hyperframes-codegen.yml` workflow that normally auto-opens this
PR failed with a `gh: Not Found (HTTP 404)` on the PR-creation step (run
28556975483); regenerated manually with:

  cd experiment-framework
  PYTHONPATH=. python3 scripts/generate_hyperframes_cli_client.py \\
    --out /path/to/hyperframes-oss

This commit is codegen-only — no hand edits. The direct-upload wire-up
that consumes the new `createAssetUpload` + `completeAssetUpload` methods
lands in the follow-up commit.

— Jerrai

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(cli): migrate cloud-render upload to /v3/assets/direct-uploads (200MB)

Replaces the legacy `client.uploadAsset(...)` multipart POST to
`/v3/assets` (32 MB in-memory proxy path) with the three-step direct-to-
S3 flow that lifts the practical per-project ceiling to 200 MB:

  1. `POST /v3/assets/direct-uploads` — declares filename, content-type,
     size, and SHA256 checksum; returns `asset_id`, presigned
     `upload_url`, and required `upload_headers`.
  2. Raw `PUT` to `upload_url` with the zip bytes + `upload_headers`
     verbatim. No CLI auth attached — the presigned URL signature carries
     authorization, and any extra headers would break the signature.
  3. `POST /v3/assets/{asset_id}/complete` — finalizes into a reusable
     asset. Retried up to 5x on 409 ("Uploaded object not found yet"), a
     documented race between S3 write consistency and the finalize check.

The returned `asset_id` is the same namespace the legacy path produced
(both write into `movio_asset`), so the downstream render submission at
`createRender({project: {type: "asset_id", asset_id}})` is unchanged.

Server-side context (EF#41085): the direct-upload endpoint now accepts
`application/zip` via a scoped `_ZIP_MIME_TO_EXT` map — the shared media/
PDF allowlist stays zip-free. The exact-MIME cross-check at the sniff
step guards against zip<->PDF confusion under the shared 'document'
category. Canonical S3 key layout matches the legacy proxy path
(`document/{asset_id}/original.zip`), so the render-side head_object
gate is transparent to which upload path produced the asset.

The prior codegen commit added the generated createAssetUpload +
completeAssetUpload methods this commit consumes.

— Jerrai

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-02 16:01:08 -07:00

90 lines
3.5 KiB
TypeScript

/**
* Shared API-error reporter for the cloud subverbs.
*
* Centralizes the three-branch `instanceof HyperframesApiError` → `Error`
* → `String` cascade so the curated `ERROR_CODE_HINTS` table is applied
* uniformly across `render`/`list`/`get`/`delete`. Without this, each
* subverb had to remember to consult the hint table (and most didn't,
* which is why review finding 10 was that `hyperframes_render_not_found`
* was unreachable from get/delete).
*/
import { errorBox } from "../ui/format.js";
import { HyperframesApiError } from "./_gen/client.js";
/**
* Hints surfaced when a HyperframesApiError carries a known machine-
* readable code. Keep entries actionable; if there's nothing useful to
* say, leave the code out and let the message stand on its own.
*/
const ERROR_CODE_HINTS: Record<string, string> = {
hyperframes_project_too_large:
"The zip exceeded the 200 MB limit. Trim large media (or pre-host them and reference by URL), then try again.",
hyperframes_render_not_found:
"The render_id no longer exists — either soft-deleted or never created.",
invalid_parameter:
"Check the listed parameter against `hyperframes cloud render --help` for the accepted values.",
authentication_failed:
"Run `hyperframes auth status` to confirm your credential; `hyperframes auth login` to re-auth.",
rate_limit_exceeded: "Retry after the duration in the Retry-After header.",
};
/**
* Print an errorBox and `process.exit(1)` for any unknown error from
* the cloud subverbs. The `stage` is the human-readable name of the
* step that failed (e.g. "Upload failed", "Submit failed", "Could not
* list cloud renders"). Returns `never` so call sites can `throw` from
* the catch block without a separate exit.
*
* Options:
* - `notFound`: short-circuit on a 404 with this friendly message
* (the render-id, asset-id, etc. that wasn't found).
* - `extraHints`: per-code overrides merged on top of
* `ERROR_CODE_HINTS`.
* - `suggestion`: a fallback line shown when no code-specific hint
* matches. Use this for caller-context that's always actionable
* (e.g. "Resume with: hyperframes cloud get hfr_X" on poll
* errors) so the user can recover without having to remember the
* render_id.
*/
// fallow-ignore-next-line complexity
export function reportApiError(
stage: string,
err: unknown,
options: {
notFound?: string;
extraHints?: Record<string, string>;
suggestion?: string;
} = {},
): never {
const hints = { ...ERROR_CODE_HINTS, ...options.extraHints };
if (err instanceof HyperframesApiError) {
if (err.status === 404 && options.notFound) {
errorBox("Not found", options.notFound);
process.exit(1);
}
const hint = err.code ? hints[err.code] : undefined;
const title = `${stage} (HTTP ${err.status})`;
// Priority: code-specific hint > caller suggestion > bare code
// label > no third line. Code-specific hints win because they
// address the specific failure mode; the caller suggestion is a
// generic-context fallback.
if (hint) {
errorBox(title, err.message, hint);
} else if (options.suggestion) {
errorBox(title, err.message, options.suggestion);
} else if (err.code) {
errorBox(title, err.message, `code: ${err.code}`);
} else {
errorBox(title, err.message);
}
process.exit(1);
}
if (err instanceof Error) {
errorBox(stage, err.message, options.suggestion);
process.exit(1);
}
errorBox(stage, String(err), options.suggestion);
process.exit(1);
}