@dharta/cli 0.6.77 → 0.6.78

package/node_modules/@dharta/sdk/src/errors.ts

@@ -1,58 +1,81 @@
 import type { ErrorBody } from "./types.js";
 
-// Base class so consumers can `catch (e: KartaError)` without
+// Base class so consumers can `catch (e: DhartaError)` without
 // switching on status codes manually for the common cases.
-export class KartaError extends Error {
+export class DhartaError extends Error {
   readonly status: number;
   readonly body: ErrorBody | string | null;
+  // Seconds the server asked the caller to wait, from the `Retry-After`
+  // header, when it sent one. Undefined otherwise, including when the header
+  // is an HTTP-date rather than a delay: a caller that wants to sleep needs a
+  // number, and guessing one from a clock this client cannot trust is worse
+  // than saying nothing. Only 429 sends it today.
+  readonly retryAfterSeconds?: number;
 
-  constructor(message: string, status: number, body: ErrorBody | string | null) {
+  constructor(
+    message: string,
+    status: number,
+    body: ErrorBody | string | null,
+    retryAfterSeconds?: number,
+  ) {
     super(message);
-    this.name = "KartaError";
+    this.name = "DhartaError";
     this.status = status;
     this.body = body;
+    this.retryAfterSeconds = retryAfterSeconds;
   }
 }
 
-export class KartaAuthError extends KartaError {
+export class DhartaAuthError extends DhartaError {
   constructor(body: ErrorBody | string | null) {
     super("Unauthenticated or invalid API key", 401, body);
-    this.name = "KartaAuthError";
+    this.name = "DhartaAuthError";
   }
 }
 
-export class KartaForbiddenError extends KartaError {
+export class DhartaForbiddenError extends DhartaError {
   constructor(body: ErrorBody | string | null) {
     super("Forbidden — caller lacks required scope", 403, body);
-    this.name = "KartaForbiddenError";
+    this.name = "DhartaForbiddenError";
   }
 }
 
-export class KartaNotFoundError extends KartaError {
+export class DhartaNotFoundError extends DhartaError {
   constructor(body: ErrorBody | string | null) {
     super("Resource not found", 404, body);
-    this.name = "KartaNotFoundError";
+    this.name = "DhartaNotFoundError";
   }
 }
 
-export class KartaValidationError extends KartaError {
+export class DhartaValidationError extends DhartaError {
   constructor(body: ErrorBody | string | null) {
     super("Validation failed", 422, body);
-    this.name = "KartaValidationError";
+    this.name = "DhartaValidationError";
   }
 }
 
 export function errorFor(
   status: number,
   body: ErrorBody | string | null,
-): KartaError {
-  if (status === 401) return new KartaAuthError(body);
-  if (status === 403) return new KartaForbiddenError(body);
-  if (status === 404) return new KartaNotFoundError(body);
-  if (status === 422) return new KartaValidationError(body);
+  retryAfterSeconds?: number,
+): DhartaError {
+  if (status === 401) return new DhartaAuthError(body);
+  if (status === 403) return new DhartaForbiddenError(body);
+  if (status === 404) return new DhartaNotFoundError(body);
+  if (status === 422) return new DhartaValidationError(body);
   const msg =
     body && typeof body === "object" && "message" in body && body.message
       ? body.message
       : `Dharta API error ${status}`;
-  return new KartaError(String(msg), status, body);
+  return new DhartaError(String(msg), status, body, retryAfterSeconds);
+}
+
+// `Retry-After` as a whole number of seconds, or undefined when the header is
+// absent, an HTTP-date, or otherwise not a non-negative integer count.
+export function parseRetryAfterSeconds(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const seconds = Number(trimmed);
+  return Number.isFinite(seconds) ? seconds : undefined;
 }

package/node_modules/@dharta/sdk/src/fleet.ts

@@ -0,0 +1,339 @@
+// The fleet mutations (RFC 0048 PR7). Reads stay on the catalog endpoint; this
+// file covers the writes the fleet console makes.
+//
+// Two scopes: `fleet:write` for routine work, and `fleet:operations:write`,
+// which expires within 90 days, for the eight actions that move live releases:
+// every operation verb past the preview, and every rollout verb.
+
+import type { HttpClient } from "./http.js";
+import type { MutationOptions } from "./idempotency.js";
+import type {
+  FleetAnomalyFinding,
+  FleetExportParams,
+  FleetOperation,
+  FleetOperationParams,
+  FleetRollout,
+  FleetSavedView,
+  FleetSavedViewParams,
+  FleetSnoozeDuration,
+  FleetAnalyticsSaveParams,
+} from "./types.js";
+
+interface OperationEnvelope {
+  operation: FleetOperation;
+}
+
+interface RolloutEnvelope {
+  rollout: FleetRollout;
+}
+
+interface FindingEnvelope {
+  finding: FleetAnomalyFinding;
+}
+
+interface SavedViewEnvelope {
+  saved_view: FleetSavedView;
+}
+
+export interface FleetRollbackResult {
+  rollout: FleetRollout;
+  operation: FleetOperation;
+}
+
+export class FleetOperationsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  // Freezes the selection and returns a draft. Nothing is applied until
+  // `confirm`, so this is safe to call to find out what an action would touch.
+  async create(
+    params: FleetOperationParams,
+    options: MutationOptions = {},
+  ): Promise<FleetOperation> {
+    const res = await this.http.request<OperationEnvelope>({
+      method: "POST",
+      path: "/api/fleet/operations",
+      idempotencyKey: options.idempotencyKey,
+      body: { operation: params },
+    });
+    return res.operation;
+  }
+
+  // `phrase` is the `confirmation_phrase` the draft returned. It is derived
+  // from the frozen manifest, which does not change after the preview, so the
+  // phrase proves the caller saw that preview. It says nothing about whether
+  // the fleet has moved since.
+  async confirm(
+    id: string,
+    phrase: string,
+    options: MutationOptions = {},
+  ): Promise<FleetOperation> {
+    return this.post(id, "confirm", { confirmation_phrase: phrase }, options);
+  }
+
+  async cancel(id: string, options: MutationOptions = {}): Promise<FleetOperation> {
+    return this.post(id, "cancel", undefined, options);
+  }
+
+  async retry(id: string, options: MutationOptions = {}): Promise<FleetOperation> {
+    return this.post(id, "retry", undefined, options);
+  }
+
+  private async post(
+    id: string,
+    action: string,
+    body?: unknown,
+    options: MutationOptions = {},
+  ): Promise<FleetOperation> {
+    const res = await this.http.request<OperationEnvelope>({
+      method: "POST",
+      path: `/api/fleet/operations/${encodeURIComponent(id)}/${action}`,
+      idempotencyKey: options.idempotencyKey,
+      body,
+    });
+    return res.operation;
+  }
+}
+
+export class FleetRolloutsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async advance(id: string, options: MutationOptions = {}): Promise<FleetRollout> {
+    return this.post(id, "advance", options);
+  }
+
+  async pause(id: string, options: MutationOptions = {}): Promise<FleetRollout> {
+    return this.post(id, "pause", options);
+  }
+
+  async resume(id: string, options: MutationOptions = {}): Promise<FleetRollout> {
+    return this.post(id, "resume", options);
+  }
+
+  // Runs the health check now instead of waiting for the next observation
+  // window. The rollout comes back as it was read, because the evaluation runs
+  // in the background.
+  async evaluate(id: string, options: MutationOptions = {}): Promise<FleetRollout> {
+    return this.post(id, "evaluate", options);
+  }
+
+  // Answers with the operation it queued as well as the rollout: the rollout is
+  // finished at that point, and the operation is the thing still worth watching.
+  async rollback(id: string, options: MutationOptions = {}): Promise<FleetRollbackResult> {
+    return this.http.request<FleetRollbackResult>({
+      method: "POST",
+      path: `/api/fleet/rollouts/${encodeURIComponent(id)}/rollback`,
+      idempotencyKey: options.idempotencyKey,
+    });
+  }
+
+  private async post(
+    id: string,
+    action: string,
+    options: MutationOptions = {},
+  ): Promise<FleetRollout> {
+    const res = await this.http.request<RolloutEnvelope>({
+      method: "POST",
+      path: `/api/fleet/rollouts/${encodeURIComponent(id)}/${action}`,
+      idempotencyKey: options.idempotencyKey,
+    });
+    return res.rollout;
+  }
+}
+
+export class FleetFindingsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async acknowledge(id: string, options: MutationOptions = {}): Promise<FleetAnomalyFinding> {
+    return this.post(id, "acknowledge", undefined, options);
+  }
+
+  async snooze(
+    id: string,
+    duration?: FleetSnoozeDuration,
+    options: MutationOptions = {},
+  ): Promise<FleetAnomalyFinding> {
+    return this.post(id, "snooze", duration === undefined ? undefined : { duration }, options);
+  }
+
+  async resolve(id: string, options: MutationOptions = {}): Promise<FleetAnomalyFinding> {
+    return this.post(id, "resolve", undefined, options);
+  }
+
+  async reopen(id: string, options: MutationOptions = {}): Promise<FleetAnomalyFinding> {
+    return this.post(id, "reopen", undefined, options);
+  }
+
+  async classify(
+    id: string,
+    classification: string,
+    options: MutationOptions = {},
+  ): Promise<FleetAnomalyFinding> {
+    return this.post(id, "classify", { classification }, options);
+  }
+
+  // Omit `membershipId`, or pass null, to unassign. The wire value for "no
+  // owner" is null, which is what the spec declares; the server treats any
+  // blank as unassign, but sending null keeps the client honest.
+  async assign(
+    id: string,
+    membershipId?: number | string | null,
+    options: MutationOptions = {},
+  ): Promise<FleetAnomalyFinding> {
+    return this.post(id, "assign", { membership_id: membershipId ?? null }, options);
+  }
+
+  // Raises the finding to an incident so it leaves the routine triage queue.
+  async promote(id: string, options: MutationOptions = {}): Promise<FleetAnomalyFinding> {
+    return this.post(id, "promote", undefined, options);
+  }
+
+  // Sets the runbook link. Pass null to clear it; the server also accepts an
+  // empty string, which is what the CLI flag sends.
+  async updateRunbook(
+    id: string,
+    runbookUrl: string | null,
+    options: MutationOptions = {},
+  ): Promise<FleetAnomalyFinding> {
+    const res = await this.http.request<FindingEnvelope>({
+      method: "PATCH",
+      path: `/api/fleet/findings/${encodeURIComponent(id)}`,
+      idempotencyKey: options.idempotencyKey,
+      body: { runbook_url: runbookUrl },
+    });
+    return res.finding;
+  }
+
+  private async post(
+    id: string,
+    action: string,
+    body?: unknown,
+    options: MutationOptions = {},
+  ): Promise<FleetAnomalyFinding> {
+    const res = await this.http.request<FindingEnvelope>({
+      method: "POST",
+      path: `/api/fleet/findings/${encodeURIComponent(id)}/${action}`,
+      idempotencyKey: options.idempotencyKey,
+      body,
+    });
+    return res.finding;
+  }
+}
+
+export class FleetSavedViewsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async create(
+    params: FleetSavedViewParams,
+    options: MutationOptions = {},
+  ): Promise<FleetSavedView> {
+    const res = await this.http.request<SavedViewEnvelope>({
+      method: "POST",
+      path: "/api/fleet/saved_views",
+      idempotencyKey: options.idempotencyKey,
+      body: { saved_view: params },
+    });
+    return res.saved_view;
+  }
+
+  async update(
+    id: string,
+    params: Partial<FleetSavedViewParams>,
+    options: MutationOptions = {},
+  ): Promise<FleetSavedView> {
+    const res = await this.http.request<SavedViewEnvelope>({
+      method: "PATCH",
+      path: `/api/fleet/saved_views/${encodeURIComponent(id)}`,
+      idempotencyKey: options.idempotencyKey,
+      body: { saved_view: params },
+    });
+    return res.saved_view;
+  }
+
+  async delete(id: string, options: MutationOptions = {}): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/api/fleet/saved_views/${encodeURIComponent(id)}`,
+      idempotencyKey: options.idempotencyKey,
+    });
+  }
+
+  // Favorites are per membership, so this marks the view for the person who
+  // created the API key, not for the organization.
+  async favorite(id: string, options: MutationOptions = {}): Promise<void> {
+    await this.http.request<void>({
+      method: "POST",
+      path: `/api/fleet/saved_views/${encodeURIComponent(id)}/favorite`,
+      idempotencyKey: options.idempotencyKey,
+    });
+  }
+
+  async unfavorite(id: string, options: MutationOptions = {}): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/api/fleet/saved_views/${encodeURIComponent(id)}/favorite`,
+      idempotencyKey: options.idempotencyKey,
+    });
+  }
+}
+
+export class FleetAnalyticsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  // Stores an explorer chart as a private saved view pinned to the caller. The
+  // parameters are the same ones the console's chart URL carries.
+  async save(
+    params: FleetAnalyticsSaveParams,
+    options: MutationOptions = {},
+  ): Promise<FleetSavedView> {
+    const res = await this.http.request<SavedViewEnvelope>({
+      method: "POST",
+      path: "/api/fleet/analytics/saved_views",
+      idempotencyKey: options.idempotencyKey,
+      body: params,
+    });
+    return res.saved_view;
+  }
+
+  // Removes the chart from the caller's pinned list. The view itself survives.
+  async unpin(id: string, options: MutationOptions = {}): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/api/fleet/analytics/saved_views/${encodeURIComponent(id)}/pin`,
+      idempotencyKey: options.idempotencyKey,
+    });
+  }
+}
+
+export class FleetExportsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  // Returns the CSV body as a string. `users` and `sessions` exports carry
+  // personal data, so they need a membership that may read sessions.
+  async create(params: FleetExportParams, options: MutationOptions = {}): Promise<string> {
+    return this.http.request<string>({
+      method: "POST",
+      path: "/api/fleet/exports",
+      headers: { Accept: "text/csv" },
+      idempotencyKey: options.idempotencyKey,
+      body: { export: params },
+    });
+  }
+}
+
+export class FleetResource {
+  readonly operations: FleetOperationsResource;
+  readonly rollouts: FleetRolloutsResource;
+  readonly findings: FleetFindingsResource;
+  readonly savedViews: FleetSavedViewsResource;
+  readonly analytics: FleetAnalyticsResource;
+  readonly exports: FleetExportsResource;
+
+  constructor(http: HttpClient) {
+    this.operations = new FleetOperationsResource(http);
+    this.rollouts = new FleetRolloutsResource(http);
+    this.findings = new FleetFindingsResource(http);
+    this.savedViews = new FleetSavedViewsResource(http);
+    this.analytics = new FleetAnalyticsResource(http);
+    this.exports = new FleetExportsResource(http);
+  }
+}

package/node_modules/@dharta/sdk/src/http.ts

@@ -1,7 +1,8 @@
-import { errorFor } from "./errors.js";
+import { errorFor, parseRetryAfterSeconds } from "./errors.js";
+import { assertIdempotencyKey, randomIdempotencyKey } from "./idempotency.js";
 import type { ErrorBody } from "./types.js";
 
-export interface KartaOptions {
+export interface DhartaOptions {
   // Bearer token, e.g. "dh_live_…". Required for headless / SDK use.
   apiKey: string;
   baseUrl?: string;
@@ -14,6 +15,18 @@ export interface KartaOptions {
   // Map a transport failure (DNS, refused connection, TLS, etc.) to the Error
   // to throw. Defaults to a generic SDK transport message.
   formatNetworkError?: (url: string, error: unknown) => Error;
+  // The Idempotency-Key for every request this client makes that does not name
+  // one of its own. Set it when the CALLER, not the library, owns recovery: a
+  // CI job that reruns after an ambiguous failure needs the second run to
+  // present the key the first run used, and it cannot do that if each process
+  // mints its own. This is what `dharta --idempotency-key` wires up.
+  //
+  // It fills in, it does not overrule. A request that names its own key keeps
+  // it, which is what lets one command make two writes under one caller key:
+  // it derives a key per write and each survives. Without that, the second
+  // write would present the first one's key with a different body and come
+  // back 422.
+  idempotencyKey?: string;
 }
 
 export interface RequestOptions {
@@ -23,8 +36,23 @@ export interface RequestOptions {
   body?: unknown;
   // Extra headers, merged over the Authorization/Accept/Content-Type defaults.
   headers?: Record<string, string>;
+  // The Idempotency-Key for THIS request. Set it when the value belongs to the
+  // operation rather than to the client: a command that writes twice derives
+  // one key per write and passes each here. It outranks the client-wide key.
+  //
+  // Leave it undefined and a mutation still carries a key: the client fills in
+  // its own, or mints a UUID. Minting lives here, in one place, so the
+  // client-wide key has somewhere to apply. A resource method that minted its
+  // own would leave nothing for the caller's key to fill in.
+  idempotencyKey?: string;
 }
 
+const IDEMPOTENCY_HEADER = "Idempotency-Key";
+
+// The methods the platform installs its idempotency filter on. A read carries
+// the header only when the caller put it there, and never a minted one.
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
 const PROTECTED_HEADER_NAMES = new Set([
   "authorization",
   "host",
@@ -41,8 +69,9 @@ export class HttpClient {
   private readonly fetchImpl: typeof fetch;
   private readonly formatError?: (status: number, body: unknown) => Error;
   private readonly formatNetworkError?: (url: string, error: unknown) => Error;
+  private readonly idempotencyKey?: string;
 
-  constructor(opts: KartaOptions) {
+  constructor(opts: DhartaOptions) {
     if (!opts.apiKey) {
       throw new Error("DhartaSDK: `apiKey` is required.");
     }
@@ -60,6 +89,12 @@ export class HttpClient {
     this.fetchImpl = f.bind(globalThis);
     this.formatError = opts.formatError;
     this.formatNetworkError = opts.formatNetworkError;
+    // Checked here rather than at first use, so a bad client-wide key fails
+    // where it was set instead of on whichever request happens to go first.
+    this.idempotencyKey =
+      opts.idempotencyKey === undefined
+        ? undefined
+        : assertIdempotencyKey(opts.idempotencyKey, "idempotencyKey");
   }
 
   async request<T>(opts: RequestOptions): Promise<T> {
@@ -71,11 +106,15 @@ export class HttpClient {
     }
 
     const extraHeaders = sanitizeHeaders(opts.headers);
-    const headers: Record<string, string> = {
-      Authorization: `Bearer ${this.apiKey}`,
-      Accept: "application/json",
-      ...extraHeaders,
-    };
+    const headers: Record<string, string> = this.withIdempotencyKey(
+      {
+        Authorization: `Bearer ${this.apiKey}`,
+        Accept: "application/json",
+        ...extraHeaders,
+      },
+      opts.method ?? "GET",
+      opts.idempotencyKey,
+    );
     let body: string | undefined;
     if (opts.body !== undefined) {
       headers["Content-Type"] = "application/json";
@@ -108,9 +147,21 @@ export class HttpClient {
     }
 
     if (!res.ok) {
-      throw this.formatError
+      const retryAfterSeconds = parseRetryAfterSeconds(res.headers.get("Retry-After"));
+      const error = this.formatError
         ? this.formatError(res.status, parsed)
-        : errorFor(res.status, parsed as ErrorBody | string | null);
+        : errorFor(res.status, parsed as ErrorBody | string | null, retryAfterSeconds);
+      // A caller-supplied `formatError` builds its own Error and never sees
+      // the response, so attach the delay here too. Otherwise the CLI, which
+      // supplies one, would print "you are rate limited" and drop the only
+      // part of the answer the user needs: how long to wait.
+      if (retryAfterSeconds !== undefined && !("retryAfterSeconds" in error)) {
+        Object.defineProperty(error, "retryAfterSeconds", {
+          value: retryAfterSeconds,
+          enumerable: true,
+        });
+      }
+      throw error;
     }
     return parsed as T;
   }
@@ -120,19 +171,61 @@ export class HttpClient {
   async raw(path: string, init?: RequestInit): Promise<Response> {
     const extraHeaders = sanitizeHeaders(init?.headers);
     const url = this.baseUrl + path;
+    // Built OUTSIDE the try. It rejects a malformed Idempotency-Key, and a
+    // rejected value is not a transport failure: catching it here would report
+    // "could not reach the host" for a key the caller mistyped.
+    const headers = this.withIdempotencyKey(
+      {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...extraHeaders,
+      },
+      init?.method ?? "GET",
+    );
     try {
-      return await this.fetchImpl(url, {
-        ...init,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          ...extraHeaders,
-        },
-      });
+      return await this.fetchImpl(url, { ...init, headers });
     } catch (error) {
       throw this.networkError(url, error);
     }
   }
 
+  // One place decides the Idempotency-Key, most specific first: the key this
+  // request named, then one a caller wrote as a header by hand, then the
+  // client-wide key, then a fresh UUID on a mutation. A read that named none of
+  // them carries no key, which is what it did before minting moved here.
+  //
+  // Whatever wins is written back under the canonical spelling and every other
+  // spelling is dropped. HTTP header names are case-insensitive, so leaving a
+  // lowercase `idempotency-key` beside the winner would send the value twice
+  // and let the server choose.
+  private withIdempotencyKey(
+    headers: Record<string, string>,
+    method: string,
+    requestKey?: string,
+  ): Record<string, string> {
+    const merged: Record<string, string> = {};
+    let handWritten: string | undefined;
+    for (const [key, value] of Object.entries(headers)) {
+      if (key.toLowerCase() === IDEMPOTENCY_HEADER.toLowerCase()) {
+        handWritten = value;
+        continue;
+      }
+      merged[key] = value;
+    }
+
+    // Both caller-supplied sources are checked, not only the winner: a key that
+    // is wrong is worth saying so about, and a caller who supplied two would
+    // otherwise learn about the loser's mistake only after changing the winner.
+    if (requestKey !== undefined) assertIdempotencyKey(requestKey, "idempotencyKey");
+    if (handWritten !== undefined) assertIdempotencyKey(handWritten, "the Idempotency-Key header");
+
+    const chosen = requestKey
+      ?? handWritten
+      ?? this.idempotencyKey
+      ?? (MUTATING_METHODS.has(method.toUpperCase()) ? randomIdempotencyKey() : undefined);
+    if (chosen !== undefined) merged[IDEMPOTENCY_HEADER] = chosen;
+    return merged;
+  }
+
   private networkError(url: string, error: unknown): Error {
     if (this.formatNetworkError) return this.formatNetworkError(url, error);
     return new Error(`DhartaSDK: could not reach ${new URL(url).origin} (${formatCause(error)}).`);