contree-client 0.2.1-dev0 → 0.2.2

package/lib/client.d.ts

@@ -34,13 +34,13 @@ export interface ContreeClientOptions {
 }
 
 export declare class ContreeClient {
-  token: string;
+  token: string | null;
   baseUrl: string;
   project: string | null;
   timeout: number | null;
   retry: RetryPolicy | null;
   identity: string | null;
-  constructor(token: string, options?: ContreeClientOptions);
+  constructor(token: string | null, options?: ContreeClientOptions);
   static fromProfile(
     profile?: string | Profile | null,
     options?: ContreeClientOptions & { configPath?: string | null },
@@ -215,10 +215,10 @@ export declare class ContreeClient {
   inspectImageList(imageUuid: string, path: string): Promise<DirectoryList>;
   inspectImageGrep(
     imageUuid: string,
-    pattern: string,
+    pattern: string | readonly string[],
     options?: {
-      path?: string | null;
-      glob?: string | null;
+      path?: string | readonly string[] | null;
+      glob?: string | readonly string[] | null;
       max_count?: number | null;
       max_total?: number | null;
       case?: "sensitive" | "insensitive" | "smart" | null;

package/lib/client.js

@@ -8,6 +8,7 @@ import {
 } from "./errors.js";
 import { AUTH_TYPE_IAM, ProfileError, resolveProfile } from "./profiles.js";
 import {
+  EVENTS_UNAVAILABLE_STATUSES,
   IS_NODE,
   SSEParser,
   TIGHT_LOOP_FLOOR,
@@ -25,7 +26,11 @@ import {
   sleep,
 } from "./runtime.js";
 import { DEFAULT_BASE_URL } from "./specInfo.js";
-import { OperationEvent, isTerminalStatus } from "./models.js";
+import {
+  EventDataCompletion,
+  OperationEvent,
+  isTerminalStatus,
+} from "./models.js";
 import * as operations from "./operations.js";
 
 /** Contree API client on top of the platform fetch.
@@ -34,6 +39,10 @@ import * as operations from "./operations.js";
  * unlike the Python adapters there is exactly one transport. Pass a
  * custom `fetch` implementation (undici dispatcher wrappers, MSW,
  * ...) via the constructor options to customize it.
+ *
+ * `token` may be null, like `project`: the client then sends no
+ * `Authorization` header, which is all the endpoints that need no
+ * authentication want.
  */
 export class ContreeClient {
   constructor(
@@ -54,7 +63,7 @@ export class ContreeClient {
         `unsupported baseUrl scheme ${parsed.protocol} in ${baseUrl}: use http:// or https://`,
       );
     }
-    this.token = token;
+    this.token = token ?? null;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.project = project;
     this.timeout = timeout;
@@ -107,8 +116,11 @@ export class ContreeClient {
   }
 
   buildHeaders(spec) {
-    const headers = { Authorization: `Bearer ${this.token}` };
-    if (this.project !== null) {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (this.project) {
       headers["Project"] = this.project;
     }
     if (spec.contentType) {
@@ -409,8 +421,13 @@ export class ContreeClient {
 
   /** Stream operation events with transparent reconnection: network
    * drops, in-band SSE error frames and retryable API statuses
-   * (410/425/5xx) reconnect from the last received event id; other
-   * API errors propagate. Ends after the `completion` event. */
+   * (410/425/5xx) reconnect from the last received event id. A status
+   * meaning the events endpoint itself doesn't exist for this
+   * operation/server (400/404/405/406) stops reconnecting and instead
+   * polls getOperationStatus() until the operation is terminal, then
+   * yields a synthesized `completion` event built from that status
+   * (there is no real event log to relay). Other API errors
+   * propagate. Ends after the `completion` event. */
   async *followOperationEvents(
     operationId,
     { last_event_id = null, spid = null, since = null, timeout = null } = {},
@@ -450,6 +467,64 @@ export class ContreeClient {
             lastId = error.lastEventId;
           }
         } else if (error instanceof ContreeAPIError) {
+          if (EVENTS_UNAVAILABLE_STATUSES.has(error.status)) {
+            // the endpoint is gone, not just failing: reconnecting the
+            // same request will never work, but the operation may
+            // still finish - stop touching /events and poll status
+            // instead for the rest of this wait
+            for (;;) {
+              checkDeadline();
+              let response;
+              try {
+                response = await this.getOperationStatus(operationId);
+              } catch (pollError) {
+                if (
+                  !(pollError instanceof ContreeError) &&
+                  !this._transportRetryable(pollError)
+                ) {
+                  throw pollError;
+                }
+                response = null;
+              }
+              if (
+                response !== null &&
+                response.status !== undefined &&
+                isTerminalStatus(response.status)
+              ) {
+                // no event log to relay, but a caller of
+                // followOperationEvents must still observe a terminal
+                // completion rather than nothing at all
+                lastId = lastId === null ? 0 : lastId + 1;
+                yield new OperationEvent({
+                  id: lastId,
+                  ts: new Date(),
+                  type: "completion",
+                  data: new EventDataCompletion({
+                    status: response.status,
+                    duration_ms:
+                      typeof response.duration === "number"
+                        ? Math.round(response.duration * 1000)
+                        : 0,
+                    result_image_uuid: response.result_image_uuid,
+                    error: response.error,
+                    image_size_bytes:
+                      typeof response.image_size === "number"
+                        ? response.image_size
+                        : undefined,
+                  }),
+                });
+                return;
+              }
+              let pollDelay = delays.next().value;
+              if (deadline !== null) {
+                pollDelay = Math.min(
+                  pollDelay,
+                  Math.max(0, deadline - monotonic()),
+                );
+              }
+              await sleep(pollDelay);
+            }
+          }
           const retryable =
             error.status === 410 ||
             error.status === 425 ||

package/lib/models.js

@@ -585,7 +585,7 @@ export class StreamRepr {
   }
 }
 
-/** Stdin payload.  Unlike output streams it is never truncated; */
+/** Stdin payload.  Delivery to the child is always complete — */
 export class ClosableStreamRepr {
   constructor(fields = {}) {
     this.value = fields.value;

package/lib/operations.d.ts

@@ -246,10 +246,10 @@ export declare function parseInspectImageList(
 
 export declare function buildInspectImageGrep(
   imageUuid: string,
-  pattern: string,
+  pattern: string | readonly string[],
   options?: {
-    path?: string | null;
-    glob?: string | null;
+    path?: string | readonly string[] | null;
+    glob?: string | readonly string[] | null;
     max_count?: number | null;
     max_total?: number | null;
     case?: "sensitive" | "insensitive" | "smart" | null;

package/lib/runtime.d.ts

@@ -21,7 +21,7 @@ export type RequestBody =
 export interface RequestSpec {
   method: string;
   path: string;
-  query?: Record<string, string>;
+  query?: Record<string, string | readonly string[]>;
   headers?: Record<string, string>;
   body?: RequestBody;
   contentType?: string | null;
@@ -58,7 +58,9 @@ export declare function sleep(seconds: number): Promise<void>;
 export declare function monotonic(): number;
 export declare function isUuid(ref: string): boolean;
 export declare function quotePath(value: unknown): string;
-export declare function encodeQuery(query: Record<string, string>): string;
+export declare function encodeQuery(
+  query: Record<string, string | readonly string[]>,
+): string;
 export declare function formatTimeParam(value: string | number | Date): string;
 export declare function parseDatetime(value: string): Date;
 export declare function bytesToText(bytes: Uint8Array): string;

package/lib/runtime.js

@@ -14,7 +14,7 @@ import {
 
 export const CHUNK_SIZE = 65536;
 
-export const PACKAGE_VERSION = "0.2.1-dev0";
+export const PACKAGE_VERSION = "0.2.2";
 export const UA_PRODUCT = `contree-client-js/${PACKAGE_VERSION}`;
 
 const NODE_VERSION =
@@ -38,6 +38,17 @@ export const RETRY_DELAYS = Object.freeze([0.1, 0.2, 0.5, 1.0, 2.0, 5.0]);
 // returning immediate empty streams does not spin the client
 export const TIGHT_LOOP_FLOOR = 0.5;
 
+// the events route itself doesn't exist for this operation/server
+// (malformed request an older backend rejects, or a reverse proxy
+// that never forwards it) rather than merely being down: reconnecting
+// will never succeed, but the operation itself may still complete -
+// degrade to polling instead of failing the whole wait. 401/403 are
+// deliberately excluded: an auth/permission failure here likely means
+// the whole client is broken, not just this route, so it still throws
+export const EVENTS_UNAVAILABLE_STATUSES = Object.freeze(
+  new Set([400, 404, 405, 406]),
+);
+
 /** An endless ladder of backoff delays: the ladder is walked once and
  * then the tail delay repeats forever. */
 export function* retryDelays(delays = RETRY_DELAYS) {
@@ -140,9 +151,11 @@ export function quotePath(value) {
 
 export function encodeQuery(query) {
   return Object.entries(query)
-    .map(
-      ([key, value]) =>
-        `${encodeURIComponent(key)}=${encodeURIComponent(value).replaceAll("%2F", "/")}`,
+    .flatMap(([key, value]) =>
+      (Array.isArray(value) ? value : [value]).map(
+        (item) =>
+          `${encodeURIComponent(key)}=${encodeURIComponent(item).replaceAll("%2F", "/")}`,
+      ),
     )
     .join("&");
 }

package/lib/specInfo.js

@@ -5,4 +5,4 @@ export const DEFAULT_BASE_URL = "https://api.tokenfactory.nebius.com/sandboxes";
 // sha256 of the exact OpenAPI document this package was built
 // from - the build input provenance
 export const SPEC_SHA256 =
-  "2bfd239341e6f61ccba1aafb39cef7b476d56f424156860a204f089d7d79b7bf";
+  "23d748a2918b1124b3072d54d17d8eb43aa00d0b969bc1fa718f34ac884ee887";

package/lib/testing.d.ts

@@ -17,7 +17,7 @@ export declare class ContreeClient extends GeneratedClient {
   mocks: Map<string, Outcome[]>;
   calls: Call[];
   constructedWith: {
-    token: string;
+    token: string | null;
     baseUrl: string;
     project: string | null;
     timeout: number | null;
@@ -25,7 +25,7 @@ export declare class ContreeClient extends GeneratedClient {
     identity: string | null;
   };
   constructor(
-    token?: string,
+    token?: string | null,
     options?: ConstructorParameters<typeof GeneratedClient>[1],
   );
   mock(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contree-client",
-  "version": "0.2.1-dev0",
+  "version": "0.2.2",
   "description": "JavaScript client for the Contree API, generated from the OpenAPI spec",
   "homepage": "https://contree.dev/",
   "repository": {