@hypit/hypit 0.1.6 → 0.1.8

package/README.md

@@ -16,7 +16,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/hypit-ai/hypit/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/hypit-ai/hypit?style=flat-square&color=FFD700&logo=github&logoColor=white&label=Stars"></a>
+  <img alt="Stars" src="https://img.shields.io/github/stars/hypit-ai/hypit?style=flat-square&color=FFD700&logo=github&logoColor=white&label=Stars">
   <a href="https://github.com/hypit-ai/hypit/blob/main/package.json"><img alt="Node 22.15+" src="https://img.shields.io/badge/Node.js-22.15%2B-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white"></a>
   <a href="https://github.com/hypit-ai/hypit/blob/main/package.json"><img alt="pnpm 10.33" src="https://img.shields.io/badge/pnpm-10.33-F69220?style=flat-square&logo=pnpm&logoColor=white"></a>
   <a href="https://github.com/hypit-ai/hypit/blob/main/package.json"><img alt="TypeScript 5.9" src="https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/cli/README.md

@@ -14,6 +14,11 @@ invent targets, candidates or Provider choices.
 Human and JSON output answer the same command-specific question. `--json` changes encoding;
 `--verbose` expands scope. Compiler, Runtime and Repository objects are not default reports.
 
+Argument errors use `CLI_USAGE` and point to the relevant `hypit help <command>`; JSON retains that
+command in `error.help`. Unknown help topics fail explicitly. Runtime and execution failures retain
+their own diagnostics and optional `--debug` trace. Result pagination changes only the `--before`
+cursor on the current query, preserving its project, Source filter and other options.
+
 | Command | Default scope | Explicit detail |
 | --- | --- | --- |
 | `check` | Validation, targets and counts | `--verbose`: exported names/types and historical references |
@@ -113,6 +118,9 @@ flow.
 execution phases and Provider diagnostics. It reads a finished Result directly, without opening the
 Runtime; an active Build is read through Runtime control. The selected Repository handles file access.
 `--lines` limits the tail and the report states the omitted count; JSON carries records plus that count.
+An unavailable log reports `source: "unavailable"` and exits unsuccessfully; a readable log with zero
+records is a successful empty result. The human report distinguishes a finished Result with no log
+from a lookup that still needs the Build's Runtime or correct project selection.
 `inspect` exposes an available log separately from authored Outputs. `hypit runtime logs` reads the
 Worker process log instead, for Runtime startup or process-level failures.
 

package/packages/cli/src/arguments.ts

@@ -13,6 +13,7 @@ import type {
   RuntimeSelectionCommand,
 } from "./command.js";
 import type { CliColorMode, CliOutputOptions } from "./output.js";
+import { CliUsageError } from "./usage-error.js";
 
 type RawOptions = {
   readonly presentation: CliOutputOptions;
@@ -48,6 +49,15 @@ type RawOptions = {
 const commonOptions = ["--json", "--color", "--no-color", "--verbose", "--debug"] as const;
 
 export function parseCommand(argv: readonly string[]): CliCommand {
+  try { return parseArguments(argv); }
+  catch (error) {
+    if (error instanceof CliUsageError) throw error;
+    throw new CliUsageError(error instanceof Error ? error.message : String(error),
+      argv[0] === undefined ? "hypit help" : `hypit help ${argv[0]}`, { cause: error });
+  }
+}
+
+function parseArguments(argv: readonly string[]): CliCommand {
   const [command, ...tail] = argv;
   switch (command) {
     case "check": {
@@ -246,7 +256,8 @@ export function parseCommand(argv: readonly string[]): CliCommand {
         ...optionalPackageRoot(options),
       };
     }
-    default: throw new Error(usage());
+    default: throw new CliUsageError(command === undefined ? "A command is required"
+      : `Unknown command ${JSON.stringify(command)}`, "hypit help");
   }
 }
 

package/packages/cli/src/commands/execution.ts

@@ -83,13 +83,19 @@ export async function runExecutionCommand(input: {
     const records = view?.records ?? [];
     const omitted = (view?.total ?? 0) - records.length;
     write({ format: "hypit.cli-logs@1", build: args.build, source, records, omittedRecords: omitted },
-      view === undefined ? "No execution log recorded" : "Build execution log", "info",
+      view === undefined ? "Execution log unavailable" : "Build execution log", view === undefined ? "warning" : "info",
       [["Build", args.build], ["Source", source]], [
+        ...(view !== undefined ? [] : [finished
+          ? "This Result has no saved execution log."
+          : activeProfile === undefined
+            ? "No saved log found in this project. Select the Build's Runtime with --runtime <profile> to check active execution."
+            : "No log found in this project's Results or the selected Runtime. Check the Build id and project selection."]),
         ...(omitted > 0 ? [`Showing last ${records.length} records; ${omitted} earlier records omitted. Use --lines to read more.`] : []),
         ...records.map((record) => `${new Date(record.time).toISOString()}  ${record.endpoint}  ${record.command}  ${
           record.kind === "phase" ? record.phase : record.kind === "diagnostic" || record.kind === "failed"
             ? `${record.kind}: ${record.message}` : record.kind}`),
       ]);
+    if (view === undefined) io.setExitCode?.(1);
     return;
   }
 

package/packages/cli/src/commands/results.ts

@@ -54,7 +54,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.id : `${item.title} · ${item.id}`;
       const run = item.run === undefined ? "" : ` · ${item.run}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}${run} · ${item.targetCount} target${item.targetCount === 1 ? "" : "s"}`;
-    }).concat(page.next === undefined ? [] : [`Older    hypit builds --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 
@@ -89,7 +91,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.build : `${item.title} · ${item.build}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}`
         + (args.presentation.verbose ? ` · ${item.output.kind} · ${item.output.type}` : "");
-    }).concat(page.next === undefined ? [] : [`Older    hypit history ${args.outputName} --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 

package/packages/cli/src/main.ts

@@ -62,7 +62,8 @@ export async function runCli(
   distribution: CliDistribution,
 ): Promise<void> {
   if (argv.length === 0 || argv[0] === "help" || argv.includes("--help")) {
-    const topic = argv[0] === "help" ? argv[1] : argv.includes("--help") ? argv[0] : undefined;
+    const topic = argv[0] === "help" ? argv[1] : argv[0] === "--help" ? undefined
+      : argv.includes("--help") ? argv[0] : undefined;
     writeCliHelp(io, topic);
     return;
   }

package/packages/cli/src/output.ts

@@ -3,6 +3,7 @@ import { relative, resolve } from "node:path";
 import type { CanonicalValue } from "@hypit/protocol";
 
 import type { OperationalMachineView } from "./machine-view.js";
+import { CliUsageError } from "./usage-error.js";
 
 export type CliTerminal = {
   readonly isTTY: boolean;
@@ -986,6 +987,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
       io.write(`${selected.join("\n")}\n`);
       return;
     }
+    throw new CliUsageError(`Unknown help topic ${JSON.stringify(topic)}`, "hypit help");
   }
   io.write([
     colors.accent(colors.strong("Hypit")),
@@ -1044,6 +1046,7 @@ export function renderCliError(error: unknown, options: {
       error: {
         code,
         message: source.message,
+        ...(source instanceof CliUsageError ? { help: source.help } : {}),
         ...(options.debug && trace !== undefined && trace.length > 0 ? { trace } : {}),
       },
     }, null, 2)}\n`;
@@ -1058,6 +1061,8 @@ export function renderCliError(error: unknown, options: {
   ];
   if (options.debug && trace !== undefined && trace.length > 0) {
     lines.push("", colors.dim(trace));
+  } else if (source instanceof CliUsageError) {
+    lines.push("", `Usage    ${source.help}`);
   } else {
     lines.push("", colors.dim("Run with --debug to include the internal stack trace."));
   }

package/packages/cli/src/usage-error.ts

@@ -0,0 +1,8 @@
+/** Argument errors point to public usage rather than an internal stack trace. */
+export class CliUsageError extends Error {
+  readonly code = "CLI_USAGE";
+  constructor(message: string, readonly help: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CliUsageError";
+  }
+}

package/packages/provider-hypihub/README.md

@@ -74,9 +74,13 @@ to the selected deployment's origin or an existing `/v1`/`/v1beta` base. The Run
 normalizes it to `/v1`; missing or insufficient user
 credentials should be resolved at [hypit.ai](https://hypit.ai). Referenced image, audio and video
 Resources are uploaded through a session from `POST /v1/files/uploads`, followed by the private
-regional multipart instructions returned by HypiHub. The Provider follows the server-selected part
+regional multipart instructions or `api_multipart` file POST selected by HypiHub. The latter sends
+one multipart/form-data file to the selected service's `/v1/files`, preserving reference purpose
+and person classification; an uncertain file POST is not repeated automatically.
+For direct multipart uploads, the Provider follows the server-selected part
 size and part concurrency, retries a failed part with a fresh signed URL, completes or cancels that
-one upload, and then passes the returned HTTPS URL to generation or transcription. One
+one upload, and then passes the returned HTTPS URL to generation or transcription. Signing requests
+contain at most the service's 128-part limit; all batches belong to the same upload. One
 Resource identity with the same declared person-reference classification is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
 cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
 the mapping declares it as a resource-transport field and the upload session receives
@@ -97,13 +101,23 @@ selected Store is writable. Its Endpoint receives only the credential slot it de
 operation for replacing that same slot; it cannot enumerate the Store, choose another key or read
 another Endpoint's credentials. A raw credential remains an ordinary static API key.
 
+Refresh uses `oauthRequestTimeoutMs` during generation, transcription, uploads and pricing too.
+It completes before the subsequent API request starts its own deadline. A stalled refresh reports
+an OAuth refresh timeout without starting that API request.
+
 The service currently requires whole-file and per-part SHA-256 values as fields of its signed upload
 protocol. They exist only while transferring bytes; Hypit never uses them as Resource identity,
 Result metadata, lookup keys or reuse evidence. Signed URLs and their query credentials are removed
 from surfaced upload errors.
 
 The default remote alignment model is `victor-upmeet/whisperx`; `transcriptionModel` may select another
-HypiHub model that exposes the `transcriptions` route. `hypit doctor` reads the authenticated model
+HypiHub model that exposes the `transcriptions` route. When transcription response headers include
+`X-Request-Id`, the Provider records it in the existing execution diagnostics before reading the body.
+A matching same-service `Location` is retained as the authenticated result lookup URL, including on
+an HTTP failure or interrupted response body. This is a receipt for investigation, not automatic
+resubmission or Build restoration. No receipt can be recorded if no response headers arrive.
+
+`hypit doctor` reads the authenticated model
 catalog to verify configured capabilities; ordinary preflight never makes that request. The package
 declares HypiHub's public pricing page, `https://hypit.ai/commercial/pricing/`, as its price source.
 For each selected Need, `readPricing` resolves the corresponding HypiHub model and returns the service's

package/packages/provider-hypihub/src/oauth.ts

@@ -65,7 +65,7 @@ export function createHypiHubAuth(options: {
       throw new Error("HypiHub OAuth credential is read-only; run hypit auth login with a writable Credential Store");
     }
     refreshing = (async () => {
-      const deadline = requestDeadline(options.requestTimeoutMs);
+      const deadline = requestDeadline(options.requestTimeoutMs, () => new Error("HypiHub OAuth refresh timed out"));
       try {
         const response = await deadline.wait(options.fetch(tokenEndpoint, {
           method: "POST",

package/packages/provider-hypihub/src/provider.ts

@@ -100,12 +100,14 @@ class HypiHubHttpError extends Error {
 class HypiHubClient {
   readonly baseUrl: string;
   readonly timeout: number;
+  readonly oauthTimeout: number;
   readonly downloadAttempts: number;
   readonly fetcher: typeof globalThis.fetch;
   readonly uploader: HypiHubUploader;
   constructor(options: {
     readonly baseUrl: string;
     readonly timeout: number;
+    readonly oauthTimeout: number;
     readonly uploadConcurrency: number;
     readonly uploadPartTimeout: number;
     readonly uploadPartAttempts: number;
@@ -114,6 +116,7 @@ class HypiHubClient {
   }) {
     this.baseUrl = options.baseUrl.replace(/\/$/u, "");
     this.timeout = options.timeout;
+    this.oauthTimeout = options.oauthTimeout;
     this.downloadAttempts = options.downloadAttempts;
     this.fetcher = options.fetcher;
     this.uploader = new HypiHubUploader({
@@ -125,14 +128,18 @@ class HypiHubClient {
       fetch: this.fetcher,
     });
   }
-  async json(path: string, auth: HypiHubAuth, init: RequestInit = {}, refreshOnUnauthorized = true): Promise<Record<string, unknown>> {
+  async json(path: string, auth: HypiHubAuth, init: RequestInit = {}, refreshOnUnauthorized = true,
+    onResponse?: (response: Response) => Promise<void>): Promise<Record<string, unknown>> {
+    const token = await auth.token();
     const deadline = requestDeadline(this.timeout);
     try {
-      const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, { ...init, signal: deadline.signal, headers: { authorization: `Bearer ${await auth.token()}`, ...(init.headers ?? {}) } }));
+      const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, { ...init, signal: deadline.signal, headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) } }));
+      if (response.status !== 401 && onResponse !== undefined) await deadline.wait(onResponse(response));
       const text = await deadline.wait(response.text()); let body: unknown = {};
       if (response.status === 401 && refreshOnUnauthorized && auth.canRefresh()) {
+        deadline.finish();
         await auth.refresh();
-        return await this.json(path, auth, init, false);
+        return await this.json(path, auth, init, false, onResponse);
       }
       if (!response.ok) throw new HypiHubHttpError(response.status, `HypiHub returned HTTP ${response.status}: ${text.slice(0, 300)}`);
       try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`HypiHub returned invalid JSON (${response.status})`); }
@@ -165,24 +172,40 @@ class HypiHubClient {
       ...(personReference === undefined ? {} : { isPersonReference: personReference }) }, auth);
   }
 
-  async transcribe(body: Record<string, unknown>, auth: HypiHubAuth): Promise<Record<string, unknown>> {
+  async transcribe(body: Record<string, unknown>, auth: HypiHubAuth,
+    report?: (message: string) => Promise<void>): Promise<Record<string, unknown>> {
     return await this.json("/audio/transcriptions", auth, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+    }, true, async (response) => {
+      const requestId = response.headers.get("x-request-id");
+      if (requestId === null || !/^[A-Za-z0-9_-]{1,200}$/u.test(requestId)) return;
+      let retrieval = "";
+      const location = response.headers.get("location");
+      if (location !== null) {
+        try {
+          const url = new URL(location, this.baseUrl);
+          const expected = new URL(`${this.baseUrl}/audio/transcriptions/${encodeURIComponent(requestId)}`);
+          if (url.href === expected.href) retrieval = `; result lookup: ${url.href}`;
+        } catch { /* A malformed Location does not erase the request identifier. */ }
+      }
+      await report?.(`HypiHub transcription request ${requestId} (HTTP ${response.status})${retrieval}`);
     });
   }
   async speech(auth: HypiHubAuth, body: Record<string, unknown>, refreshOnUnauthorized = true): Promise<readonly { readonly bytes: Uint8Array; readonly mediaType: string }[]> {
+    const token = await auth.token();
     const deadline = requestDeadline(this.timeout);
     try {
       const response = await deadline.wait(this.fetcher(`${this.baseUrl}/audio/speech`, {
         method: "POST",
-        headers: { authorization: `Bearer ${await auth.token()}`, "content-type": "application/json" },
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
         body: JSON.stringify({ ...body, output: "b64_json" }),
         signal: deadline.signal,
       }));
       const bytes = new Uint8Array(await deadline.wait(response.arrayBuffer()));
       if (response.status === 401 && refreshOnUnauthorized && auth.canRefresh()) {
+        deadline.finish();
         await auth.refresh();
         return await this.speech(auth, body, false);
       }
@@ -226,7 +249,7 @@ function authFor(context: EndpointInvocationContext, client: HypiHubClient): Hyp
   return createHypiHubAuth({
     credential: credential(context.credentials),
     baseUrl: client.baseUrl,
-    requestTimeoutMs: client.timeout,
+    requestTimeoutMs: client.oauthTimeout,
     fetch: client.fetcher,
   });
 }
@@ -235,7 +258,7 @@ function pricingAuth(credentials: Readonly<Record<string, EndpointCredential>>,
   return createHypiHubAuth({
     credential: credential(credentials),
     baseUrl: client.baseUrl,
-    requestTimeoutMs: client.timeout,
+    requestTimeoutMs: client.oauthTimeout,
     fetch: client.fetcher,
   });
 }
@@ -311,6 +334,7 @@ export async function diagnoseHypiHubProvider(
   const client = new HypiHubClient({
     baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"),
     timeout: options.requestTimeoutMs ?? 30_000,
+    oauthTimeout: options.oauthRequestTimeoutMs ?? 30_000,
     uploadConcurrency: options.uploadConcurrency ?? 8,
     uploadPartTimeout: options.uploadPartTimeoutMs ?? 5 * 60_000,
     uploadPartAttempts: options.uploadPartAttempts ?? 3,
@@ -320,7 +344,7 @@ export async function diagnoseHypiHubProvider(
   const auth = createHypiHubAuth({
     credential: { secret: apiKey },
     baseUrl: client.baseUrl,
-    requestTimeoutMs: client.timeout,
+    requestTimeoutMs: client.oauthTimeout,
     fetch: client.fetcher,
   });
   const response = await client.json("/models", auth);
@@ -487,6 +511,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
   const client = new HypiHubClient({
     baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"),
     timeout: requestTimeoutMs,
+    oauthTimeout: oauthRequestTimeoutMs,
     uploadConcurrency: options.uploadConcurrency ?? 8,
     uploadPartTimeout: uploadPartTimeoutMs,
     uploadPartAttempts,
@@ -496,6 +521,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
   const pricingClient = new HypiHubClient({
     baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"),
     timeout: pricingRequestTimeoutMs,
+    oauthTimeout: oauthRequestTimeoutMs,
     uploadConcurrency: options.uploadConcurrency ?? 8,
     uploadPartTimeout: uploadPartTimeoutMs,
     uploadPartAttempts,
@@ -531,7 +557,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
         response_format: "verbose_json",
         language: request.language,
         timestamp_granularities: ["segment", "word"],
-      }, auth);
+      }, auth, async (message) => { await context.reportDiagnostic?.({ level: "info", message }); });
       const evidence = sealAlignedTranscriptEvidence({
         passages: interpretWhisperXTranscript(response as WhisperXTranscriptResponse, request.sampleFrames),
       });

package/packages/provider-hypihub/src/upload.ts

@@ -120,7 +120,7 @@ async function acquireUploadSlot(origin: string, auth: UploadAuth, limit: number
   };
 }
 
-/** Uploads media through HypiHub's session-negotiated private regional S3 multipart flow. */
+/** Uploads media using the transfer mode negotiated by the selected HypiHub service. */
 export class HypiHubUploader {
   readonly baseUrl: string;
   readonly requestTimeout: number;
@@ -179,16 +179,18 @@ export class HypiHubUploader {
   }
 
   private async jsonOnce(path: string, auth: UploadAuth, init: RequestInit, timeoutMs: number, retryAuth = true): Promise<Record<string, unknown>> {
+    const token = await uploadToken(auth);
     const request = requestDeadline(timeoutMs);
     const deadline = Date.now() + timeoutMs;
     try {
       const response = await request.wait(this.fetcher(`${this.baseUrl}${path}`, {
         ...init,
         signal: request.signal,
-        headers: { authorization: `Bearer ${await uploadToken(auth)}`, ...(init.headers ?? {}) },
+        headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
       }));
       const text = await request.wait(response.text());
       if (response.status === 401 && retryAuth && uploadCanRefresh(auth)) {
+        request.finish();
         await (auth as HypiHubAuth).refresh();
         return await this.jsonOnce(path, auth, init, Math.max(1, deadline - Date.now()), false);
       }
@@ -214,6 +216,16 @@ export class HypiHubUploader {
   }
 
   private async signParts(uploadId: string, declarations: readonly PartDeclaration[], auth: UploadAuth): Promise<Map<number, Record<string, unknown>>> {
+    // HypiHub accepts at most 128 part declarations per signing request.
+    if (declarations.length > 128) {
+      const signed = new Map<number, Record<string, unknown>>();
+      for (let offset = 0; offset < declarations.length; offset += 128) {
+        for (const [number, part] of await this.signParts(uploadId, declarations.slice(offset, offset + 128), auth)) {
+          signed.set(number, part);
+        }
+      }
+      return signed;
+    }
     const startedAt = Date.now();
     this.log(`part signing started upload=${uploadId} parts=${declarations.length}`);
     const response = await this.json(`/files/uploads/${encodeURIComponent(uploadId)}/parts`, auth, {
@@ -396,9 +408,30 @@ export class HypiHubUploader {
       this.log(`upload session request failed elapsed=${this.elapsed(policyStartedAt)} reason=${this.safeReason(error)}`);
       throw error;
     }
-    assert(policy.upload_mode === "s3_multipart", "HypiHub returned an unknown upload mode");
-    const result = await this.uploadDirect(input.bytes, auth, policy);
+    assert(policy.upload_mode === "s3_multipart" || policy.upload_mode === "api_multipart",
+      "HypiHub returned an unknown upload mode");
+    const result = policy.upload_mode === "api_multipart"
+      ? await this.uploadApi(input, auth, policy)
+      : await this.uploadDirect(input.bytes, auth, policy);
     this.log(`upload finished bytes=${input.bytes.byteLength} mime=${input.mediaType} elapsed=${this.elapsed(startedAt)}`);
     return result;
   }
+
+  private async uploadApi(input: HypiHubUploadInput, auth: UploadAuth, policy: Record<string, unknown>): Promise<string> {
+    const endpoint = new URL(requiredString(policy.endpoint, "HypiHub file upload endpoint"), this.baseUrl);
+    assert(endpoint.href === `${this.baseUrl}/files`, "HypiHub file upload endpoint must belong to the selected service");
+    if (policy.max_bytes !== undefined) {
+      assert(input.bytes.byteLength <= requiredInteger(policy.max_bytes, "HypiHub file upload byte limit"),
+        "HypiHub reference exceeds the negotiated file upload byte limit");
+    }
+    const form = new FormData();
+    form.set("file", new Blob([new Uint8Array(input.bytes)], { type: input.mediaType }),
+      input.filename ?? `reference.${extension(input.mediaType)}`);
+    form.set("purpose", input.purpose ?? "reference");
+    if (input.isPersonReference !== undefined) form.set("is_person_reference", String(input.isPersonReference));
+    const response = await this.json("/files", auth, { method: "POST", body: form });
+    const url = requiredString(response.url, "HypiHub file upload URL");
+    assertHTTPS(url, "HypiHub file upload URL");
+    return url;
+  }
 }