@pymthouse/builder-sdk 0.1.0 → 0.3.0

package/dist/gateway/client/index.d.cts

@@ -0,0 +1,63 @@
+import { StartGatewaySessionRequest, StartGatewaySessionResponse, GatewaySegmentPublishResult, GatewayLiveSubscribeSegment } from '../index.cjs';
+
+type SignerCredentials = {
+    type: "bearer";
+    accessToken: string;
+} | {
+    type: "apiKey";
+    apiKey: string;
+    facadeUrl: string;
+    scope?: string;
+    clientId?: string;
+};
+declare function resolveSignerToken(credentials: SignerCredentials, fetchImpl?: typeof fetch): Promise<string>;
+
+type BrowserGatewayClientOptions = {
+    /** Dashboard (or gateway relay) origin, e.g. https://dashboard.example.com */
+    baseUrl: string;
+    fetch?: typeof fetch;
+};
+declare class BrowserGatewayClient {
+    private readonly options;
+    private signerToken;
+    private sessionId;
+    private publishSeq;
+    /** Next trickle GET index for orchestrator output (see TrickleSubscriber). */
+    private subscribeSeq;
+    private subscribeEmptyPolls;
+    private readonly fetchImpl;
+    constructor(options: BrowserGatewayClientOptions);
+    get baseUrl(): string;
+    get signerAccessToken(): string | null;
+    get activeSessionId(): string | null;
+    get nextSubscribeSeq(): number;
+    connect(credentials: SignerCredentials): Promise<void>;
+    startSession(request: StartGatewaySessionRequest): Promise<StartGatewaySessionResponse>;
+    setSignerToken(accessToken: string): void;
+    publishSegment(bytes: ArrayBuffer | Uint8Array, options?: {
+        seq?: number;
+        contentType?: string;
+    }): Promise<GatewaySegmentPublishResult>;
+    /**
+     * Fetch the next orchestrator output segment (sequential walk from subscribeSeq).
+     * Matches livepeer-python-gateway TrickleSubscriber / MediaOutput segment iteration.
+     */
+    subscribeOutputSegment(): Promise<GatewayLiveSubscribeSegment | null>;
+    /**
+     * Stream the next orchestrator output segment incrementally.
+     * Mirrors Python SegmentReader behavior (consume bytes before segment closes).
+     */
+    subscribeOutputSegmentStream(onChunk: (chunk: Uint8Array) => void): Promise<Omit<GatewayLiveSubscribeSegment, "data" | "byteCount"> & {
+        byteCount: number;
+    } | null>;
+    private readSubscribeBody;
+    /** @deprecated Use subscribeOutputSegment() — live-edge-only polling does not advance output seq. */
+    subscribeLiveSegment(): Promise<GatewayLiveSubscribeSegment | null>;
+    private advanceSubscribeSeq;
+    private handleSubscribeEmpty;
+    private applyLatestSeqOnEmptyPoll;
+    subscribeSegment(seq?: number): Promise<ArrayBuffer | null>;
+    stop(): Promise<void>;
+}
+
+export { BrowserGatewayClient, type BrowserGatewayClientOptions, type SignerCredentials, resolveSignerToken };

package/dist/gateway/client/index.d.ts

@@ -0,0 +1,63 @@
+import { StartGatewaySessionRequest, StartGatewaySessionResponse, GatewaySegmentPublishResult, GatewayLiveSubscribeSegment } from '../index.js';
+
+type SignerCredentials = {
+    type: "bearer";
+    accessToken: string;
+} | {
+    type: "apiKey";
+    apiKey: string;
+    facadeUrl: string;
+    scope?: string;
+    clientId?: string;
+};
+declare function resolveSignerToken(credentials: SignerCredentials, fetchImpl?: typeof fetch): Promise<string>;
+
+type BrowserGatewayClientOptions = {
+    /** Dashboard (or gateway relay) origin, e.g. https://dashboard.example.com */
+    baseUrl: string;
+    fetch?: typeof fetch;
+};
+declare class BrowserGatewayClient {
+    private readonly options;
+    private signerToken;
+    private sessionId;
+    private publishSeq;
+    /** Next trickle GET index for orchestrator output (see TrickleSubscriber). */
+    private subscribeSeq;
+    private subscribeEmptyPolls;
+    private readonly fetchImpl;
+    constructor(options: BrowserGatewayClientOptions);
+    get baseUrl(): string;
+    get signerAccessToken(): string | null;
+    get activeSessionId(): string | null;
+    get nextSubscribeSeq(): number;
+    connect(credentials: SignerCredentials): Promise<void>;
+    startSession(request: StartGatewaySessionRequest): Promise<StartGatewaySessionResponse>;
+    setSignerToken(accessToken: string): void;
+    publishSegment(bytes: ArrayBuffer | Uint8Array, options?: {
+        seq?: number;
+        contentType?: string;
+    }): Promise<GatewaySegmentPublishResult>;
+    /**
+     * Fetch the next orchestrator output segment (sequential walk from subscribeSeq).
+     * Matches livepeer-python-gateway TrickleSubscriber / MediaOutput segment iteration.
+     */
+    subscribeOutputSegment(): Promise<GatewayLiveSubscribeSegment | null>;
+    /**
+     * Stream the next orchestrator output segment incrementally.
+     * Mirrors Python SegmentReader behavior (consume bytes before segment closes).
+     */
+    subscribeOutputSegmentStream(onChunk: (chunk: Uint8Array) => void): Promise<Omit<GatewayLiveSubscribeSegment, "data" | "byteCount"> & {
+        byteCount: number;
+    } | null>;
+    private readSubscribeBody;
+    /** @deprecated Use subscribeOutputSegment() — live-edge-only polling does not advance output seq. */
+    subscribeLiveSegment(): Promise<GatewayLiveSubscribeSegment | null>;
+    private advanceSubscribeSeq;
+    private handleSubscribeEmpty;
+    private applyLatestSeqOnEmptyPoll;
+    subscribeSegment(seq?: number): Promise<ArrayBuffer | null>;
+    stop(): Promise<void>;
+}
+
+export { BrowserGatewayClient, type BrowserGatewayClientOptions, type SignerCredentials, resolveSignerToken };

package/dist/gateway/client/index.js

@@ -0,0 +1,489 @@
+// src/gateway/types.ts
+var TRICKLE_SEQ_LATEST = -1;
+var TRICKLE_SEQ_CURRENT = -2;
+
+// src/string-utils.ts
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && (value.codePointAt(end - 1) ?? 0) === 47) {
+    end--;
+  }
+  return value.slice(0, end);
+}
+
+// src/errors.ts
+var PmtHouseError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(message, {
+    status = 500,
+    code = "pymthouse_error",
+    details
+  } = {}) {
+    super(message);
+    this.name = "PmtHouseError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/signer/fetch-json.ts
+function oauthFailureDescription(parsed, failureLabel, status) {
+  if (typeof parsed.error_description === "string") {
+    return parsed.error_description;
+  }
+  if (typeof parsed.error === "string") {
+    return parsed.error;
+  }
+  return `${failureLabel} (${status})`;
+}
+async function readJsonObjectFromResponse(response, options) {
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : {};
+  } catch {
+    throw new PmtHouseError(options.invalidJsonMessage, {
+      status: 502,
+      code: options.invalidJsonCode,
+      details: { status: response.status }
+    });
+  }
+  if (!response.ok) {
+    const description = oauthFailureDescription(parsed, options.failureLabel, response.status);
+    throw new PmtHouseError(description, {
+      status: response.status,
+      code: typeof parsed.error === "string" ? parsed.error : options.defaultErrorCode,
+      details: parsed
+    });
+  }
+  return parsed;
+}
+
+// src/signer/device-exchange.ts
+function extractSignerAccessTokenFromExchangeBody(body) {
+  const tokenObj = body.token;
+  if (tokenObj !== null && typeof tokenObj === "object" && !Array.isArray(tokenObj)) {
+    const nested = tokenObj;
+    for (const key of ["accessToken", "access_token"]) {
+      const value = nested[key];
+      if (typeof value === "string" && value.trim()) {
+        return value.trim();
+      }
+    }
+  }
+  for (const key of ["accessToken", "access_token"]) {
+    const value = body[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  throw new PmtHouseError("Device exchange response missing signer access token", {
+    status: 502,
+    code: "invalid_exchange_response"
+  });
+}
+function normalizeDeviceExchangeResponse(minted, options) {
+  const scope = minted.scope.trim() || "sign:job";
+  const body = {
+    access_token: minted.access_token,
+    token_type: "Bearer",
+    expires_in: minted.expires_in,
+    scope,
+    balanceUsdMicros: minted.balanceUsdMicros,
+    lifetimeGrantedUsdMicros: minted.lifetimeGrantedUsdMicros,
+    token: {
+      accessToken: minted.access_token,
+      access_token: minted.access_token,
+      expiresIn: minted.expires_in,
+      expires_in: minted.expires_in,
+      scope,
+      balanceUsdMicros: minted.balanceUsdMicros,
+      lifetimeGrantedUsdMicros: minted.lifetimeGrantedUsdMicros
+    }
+  };
+  const signerUrl = options?.signerUrl?.trim();
+  if (signerUrl) {
+    body.signerUrl = signerUrl;
+  }
+  return body;
+}
+
+// src/signer/api-key-exchange.ts
+var EXCHANGE_RESPONSE_ERROR = "invalid_exchange_response";
+async function exchangeApiKeyForSigner(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const url = `${stripTrailingSlashes(options.facadeUrl)}/api/pymthouse/keys/exchange`;
+  const body = { apiKey: options.apiKey };
+  if (options.scope?.trim()) {
+    body.scope = options.scope.trim();
+  }
+  if (options.clientId?.trim()) {
+    body.clientId = options.clientId.trim();
+  }
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(body),
+    cache: "no-store"
+  });
+  const parsed = await readJsonObjectFromResponse(response, {
+    invalidJsonMessage: "API key exchange returned invalid JSON",
+    invalidJsonCode: EXCHANGE_RESPONSE_ERROR,
+    failureLabel: "API key exchange failed",
+    defaultErrorCode: "api_key_exchange_failed"
+  });
+  const accessToken = extractSignerAccessTokenFromExchangeBody(parsed);
+  const signerUrlRaw = parsed.signerUrl ?? parsed.signer_url;
+  const signerUrl = typeof signerUrlRaw === "string" && signerUrlRaw.trim() ? signerUrlRaw.trim() : void 0;
+  return normalizeDeviceExchangeResponse(
+    {
+      access_token: accessToken,
+      expires_in: typeof parsed.expires_in === "number" && Number.isFinite(parsed.expires_in) ? parsed.expires_in : 3600,
+      scope: typeof parsed.scope === "string" && parsed.scope.trim() ? parsed.scope.trim() : "sign:job",
+      balanceUsdMicros: typeof parsed.balanceUsdMicros === "string" ? parsed.balanceUsdMicros : "0",
+      lifetimeGrantedUsdMicros: typeof parsed.lifetimeGrantedUsdMicros === "string" ? parsed.lifetimeGrantedUsdMicros : "0"
+    },
+    { signerUrl }
+  );
+}
+
+// src/gateway/client/resolve-signer.ts
+var boundFetch = (input, init) => globalThis.fetch(input, init);
+async function resolveSignerToken(credentials, fetchImpl = boundFetch) {
+  if (credentials.type === "bearer") {
+    const token2 = credentials.accessToken.trim();
+    if (!token2) {
+      throw new Error("Signer bearer token is empty");
+    }
+    return token2;
+  }
+  const exchanged = await exchangeApiKeyForSigner({
+    facadeUrl: credentials.facadeUrl,
+    apiKey: credentials.apiKey,
+    scope: credentials.scope ?? "sign:job",
+    clientId: credentials.clientId,
+    fetch: fetchImpl
+  });
+  const token = exchanged.access_token?.trim() || exchanged.token?.accessToken?.trim() || exchanged.token?.access_token?.trim();
+  if (!token) {
+    throw new Error("API key exchange did not return a signer access token");
+  }
+  return token;
+}
+
+// src/gateway/client/browser-client.ts
+function jsonErrorMessage(body, status, fallback) {
+  if (typeof body.message === "string") {
+    return body.message;
+  }
+  if (typeof body.error === "string") {
+    return body.error;
+  }
+  return `${fallback} (${status})`;
+}
+function resolveSubscribeSegmentSeq(requestedSeq, headerSeq) {
+  if (Number.isFinite(headerSeq)) {
+    return headerSeq;
+  }
+  if (requestedSeq >= 0) {
+    return requestedSeq;
+  }
+  return 0;
+}
+function isTrickleLeadingIndex(seq) {
+  return seq === TRICKLE_SEQ_LATEST || seq === TRICKLE_SEQ_CURRENT;
+}
+function parseHeaderInt(headers, name) {
+  const raw = headers.get(name);
+  if (!raw) {
+    return Number.NaN;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+var BrowserGatewayClient = class {
+  constructor(options) {
+    this.options = options;
+    this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+  options;
+  signerToken = null;
+  sessionId = null;
+  publishSeq = -1;
+  /** Next trickle GET index for orchestrator output (see TrickleSubscriber). */
+  subscribeSeq = TRICKLE_SEQ_CURRENT;
+  subscribeEmptyPolls = 0;
+  fetchImpl;
+  get baseUrl() {
+    return stripTrailingSlashes(this.options.baseUrl);
+  }
+  get signerAccessToken() {
+    return this.signerToken;
+  }
+  get activeSessionId() {
+    return this.sessionId;
+  }
+  get nextSubscribeSeq() {
+    return this.subscribeSeq;
+  }
+  async connect(credentials) {
+    this.signerToken = await resolveSignerToken(credentials, this.fetchImpl);
+  }
+  async startSession(request) {
+    if (!this.signerToken) {
+      throw new Error("Call connect() with signer credentials before startSession()");
+    }
+    const response = await this.fetchImpl(`${this.baseUrl}/api/gateway/sessions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.signerToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      },
+      body: JSON.stringify(request)
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new Error(jsonErrorMessage(body, response.status, "startSession failed"));
+    }
+    const sessionId = typeof body.sessionId === "string" ? body.sessionId : "";
+    const manifestId = typeof body.manifestId === "string" ? body.manifestId : "";
+    if (!sessionId) {
+      throw new Error("startSession response missing sessionId");
+    }
+    this.sessionId = sessionId;
+    const initialPublishSeq = typeof body.publishSeq === "number" && Number.isFinite(body.publishSeq) ? body.publishSeq : 0;
+    this.publishSeq = initialPublishSeq - 1;
+    const initialSubscribeSeq = typeof body.subscribeSeq === "number" && Number.isFinite(body.subscribeSeq) ? body.subscribeSeq : TRICKLE_SEQ_CURRENT;
+    this.subscribeSeq = initialSubscribeSeq;
+    this.subscribeEmptyPolls = 0;
+    const mimeType = typeof body.mimeType === "string" ? body.mimeType : void 0;
+    return {
+      sessionId,
+      manifestId,
+      mimeType,
+      publishSeq: initialPublishSeq,
+      subscribeSeq: initialSubscribeSeq
+    };
+  }
+  setSignerToken(accessToken) {
+    const token = accessToken.trim();
+    if (!token) {
+      throw new Error("Signer bearer token is empty");
+    }
+    this.signerToken = token;
+  }
+  async publishSegment(bytes, options) {
+    if (!this.sessionId || !this.signerToken) {
+      throw new Error("No active gateway session");
+    }
+    const seq = options?.seq ?? this.publishSeq + 1;
+    const part = bytes instanceof Uint8Array ? Uint8Array.from(bytes) : new Uint8Array(bytes);
+    const body = new Blob([part]);
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/gateway/sessions/${encodeURIComponent(this.sessionId)}/publish/${seq}`,
+      {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${this.signerToken}`,
+          "Content-Type": options?.contentType ?? "application/octet-stream"
+        },
+        body
+      }
+    );
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`publishSegment failed (${response.status}): ${text.slice(0, 300)}`);
+    }
+    this.publishSeq = seq;
+    return { seq, ok: true };
+  }
+  /**
+   * Fetch the next orchestrator output segment (sequential walk from subscribeSeq).
+   * Matches livepeer-python-gateway TrickleSubscriber / MediaOutput segment iteration.
+   */
+  async subscribeOutputSegment() {
+    const chunks = [];
+    const segment = await this.subscribeOutputSegmentStream((chunk) => {
+      chunks.push(chunk);
+    });
+    if (!segment) {
+      return null;
+    }
+    const total = chunks.reduce((sum, part) => sum + part.byteLength, 0);
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const part of chunks) {
+      joined.set(part, offset);
+      offset += part.byteLength;
+    }
+    return { ...segment, data: joined.buffer, byteCount: total };
+  }
+  /**
+   * Stream the next orchestrator output segment incrementally.
+   * Mirrors Python SegmentReader behavior (consume bytes before segment closes).
+   */
+  async subscribeOutputSegmentStream(onChunk) {
+    if (!this.sessionId || !this.signerToken) {
+      throw new Error("No active gateway session");
+    }
+    const requestedSeq = this.subscribeSeq;
+    const url = new URL(
+      `${this.baseUrl}/api/gateway/sessions/${encodeURIComponent(this.sessionId)}/subscribe`
+    );
+    url.searchParams.set("seq", String(requestedSeq));
+    const response = await this.fetchImpl(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.signerToken}`
+      }
+    });
+    if (response.status === 204) {
+      this.handleSubscribeEmpty(requestedSeq, response.headers);
+      return null;
+    }
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`subscribeOutputSegment failed (${response.status}): ${text.slice(0, 300)}`);
+    }
+    const segmentSeq = parseHeaderInt(response.headers, "X-Gateway-Segment-Seq");
+    const latestSeq = parseHeaderInt(response.headers, "X-Gateway-Latest-Seq");
+    const resolvedSegmentSeq = resolveSubscribeSegmentSeq(requestedSeq, segmentSeq);
+    const resolvedLatest = Number.isFinite(latestSeq) ? latestSeq : resolvedSegmentSeq;
+    const byteCount = await this.readSubscribeBody(response, onChunk);
+    if (byteCount === 0) {
+      this.handleSubscribeEmpty(requestedSeq, response.headers);
+      return null;
+    }
+    this.advanceSubscribeSeq(requestedSeq, response.headers, resolvedLatest);
+    return {
+      segmentSeq: resolvedSegmentSeq,
+      latestSeq: resolvedLatest,
+      nextSeq: this.subscribeSeq,
+      byteCount
+    };
+  }
+  async readSubscribeBody(response, onChunk) {
+    if (!response.body) {
+      const data = await response.arrayBuffer();
+      if (data.byteLength === 0) {
+        return 0;
+      }
+      onChunk(new Uint8Array(data));
+      return data.byteLength;
+    }
+    const reader = response.body.getReader();
+    let bytesRead = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        if (value && value.byteLength > 0) {
+          bytesRead += value.byteLength;
+          onChunk(value);
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return bytesRead;
+  }
+  /** @deprecated Use subscribeOutputSegment() — live-edge-only polling does not advance output seq. */
+  async subscribeLiveSegment() {
+    return this.subscribeOutputSegment();
+  }
+  advanceSubscribeSeq(requestedSeq, headers, latestSeq) {
+    const nextHeader = parseHeaderInt(headers, "X-Gateway-Next-Seq");
+    if (Number.isFinite(nextHeader)) {
+      this.subscribeSeq = nextHeader;
+    } else {
+      const segmentSeq = parseHeaderInt(headers, "X-Gateway-Segment-Seq");
+      if (Number.isFinite(segmentSeq) && segmentSeq >= 0) {
+        this.subscribeSeq = segmentSeq + 1;
+      } else if (requestedSeq >= 0) {
+        this.subscribeSeq = requestedSeq + 1;
+      } else if (Number.isFinite(latestSeq) && latestSeq >= 0) {
+        this.subscribeSeq = latestSeq + 1;
+      } else {
+        this.subscribeSeq = TRICKLE_SEQ_LATEST;
+      }
+    }
+    if (Number.isFinite(latestSeq) && latestSeq >= 0 && this.subscribeSeq >= 0 && latestSeq - this.subscribeSeq > 2) {
+      this.subscribeSeq = latestSeq;
+    }
+  }
+  handleSubscribeEmpty(requestedSeq, headers) {
+    this.subscribeEmptyPolls += 1;
+    const latest = parseHeaderInt(headers, "X-Gateway-Latest-Seq");
+    if (Number.isFinite(latest) && this.applyLatestSeqOnEmptyPoll(requestedSeq, latest, headers)) {
+      return;
+    }
+    if (requestedSeq >= 0) {
+      this.subscribeSeq = requestedSeq;
+      return;
+    }
+    if (this.subscribeEmptyPolls >= 12) {
+      this.subscribeSeq = TRICKLE_SEQ_LATEST;
+      this.subscribeEmptyPolls = 0;
+    }
+  }
+  applyLatestSeqOnEmptyPoll(requestedSeq, latest, headers) {
+    const wait = headers.get("X-Gateway-Wait") === "1";
+    if (wait && requestedSeq >= 0 && latest < requestedSeq) {
+      this.subscribeSeq = requestedSeq;
+      return true;
+    }
+    if (isTrickleLeadingIndex(requestedSeq)) {
+      this.subscribeSeq = latest >= 0 ? latest : TRICKLE_SEQ_LATEST;
+      this.subscribeEmptyPolls = 0;
+      return true;
+    }
+    if (requestedSeq >= 0 && latest === requestedSeq) {
+      this.subscribeSeq = requestedSeq;
+      return true;
+    }
+    if (requestedSeq >= 0 && latest > requestedSeq) {
+      this.subscribeSeq = latest;
+      this.subscribeEmptyPolls = 0;
+      return true;
+    }
+    return false;
+  }
+  async subscribeSegment(seq) {
+    if (seq !== void 0) {
+      this.subscribeSeq = seq;
+    }
+    const segment = await this.subscribeOutputSegment();
+    return segment?.data ?? null;
+  }
+  async stop() {
+    if (!this.sessionId || !this.signerToken) {
+      return;
+    }
+    await this.fetchImpl(
+      `${this.baseUrl}/api/gateway/sessions/${encodeURIComponent(this.sessionId)}`,
+      {
+        method: "DELETE",
+        headers: {
+          Authorization: `Bearer ${this.signerToken}`
+        }
+      }
+    ).catch(() => void 0);
+    this.sessionId = null;
+    this.publishSeq = -1;
+    this.subscribeSeq = TRICKLE_SEQ_CURRENT;
+    this.subscribeEmptyPolls = 0;
+  }
+};
+
+export { BrowserGatewayClient, resolveSignerToken };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map