@hypit/hypit 0.1.6 → 0.1.7

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.7",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

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;
+  }
 }