@dharta/cli 0.6.77 → 0.6.78

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

@@ -0,0 +1,101 @@
+// Every Dharta mutation takes an `Idempotency-Key`. The header itself is set by
+// `HttpClient`, which is the one place that can see a caller's key, a
+// client-wide key and the need to mint at the same time; a resource method
+// passes what the caller chose and nothing else.
+
+// The last argument of every mutating method. Supply a key you keep and a retry
+// of an ambiguous failure replays the first response instead of doing the work
+// again; supply nothing and one is minted per call, which still protects the
+// request from arriving twice inside the platform.
+//
+// The SDK never retries on its own. A retry is a decision about your workload
+// (how long to wait, how many times, whether the operation still makes sense),
+// and a library that guesses gets it wrong on exactly the operations that
+// matter. Keep the key, retry yourself.
+//
+// 5xx and 429 responses are not stored server-side, so reusing the key after
+// one re-drives the work rather than replaying the failure.
+//
+// See MAX_IDEMPOTENCY_KEY_LENGTH below for the shape a key has to have. This is
+// the one place that rule is written down; the CLI and the docs point here.
+export interface MutationOptions {
+  idempotencyKey?: string;
+}
+
+// THE rule for an Idempotency-Key, in one place. Every caller-supplied key goes
+// through `assertIdempotencyKey`, wherever it came from: `MutationOptions`, a
+// header a caller wrote by hand, or the client-wide `idempotencyKey` option.
+//
+// 255 is the server's cap (`Idempotent::MAX_KEY_LENGTH`), which it measures with
+// Ruby's `String#length`, counting code points. Printable ASCII is narrower than
+// the server insists on, and deliberately so: the value has to survive an HTTP
+// header, and `fetch` throws a TypeError while BUILDING the request for anything
+// outside ASCII, which surfaces as a message about headers long after the
+// mistake. Excluding the space and the control characters also means a key
+// cannot split a header. Inside 0x21 to 0x7E one character is one byte is one
+// code point, so this cap and the server's measure the same thing.
+//
+// An empty key is rejected rather than passed on. A blank `Idempotency-Key` is
+// how the platform spells "not idempotent", so accepting one would quietly turn
+// the protection OFF for a caller who thought they were turning it on.
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7e]+$/;
+
+export const INVALID_IDEMPOTENCY_KEY_CODE = "invalid_idempotency_key";
+
+// Carries a stable `code` so a consumer can map it without matching on English.
+// The CLI maps it to exit 2, the same code every other rejected value gets.
+export class InvalidIdempotencyKeyError extends Error {
+  readonly code = INVALID_IDEMPOTENCY_KEY_CODE;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidIdempotencyKeyError";
+  }
+}
+
+// `source` names where the key came from, so a caller with three ways to supply
+// one is told which is wrong. Returns the key, so it reads as a checkpoint.
+export function assertIdempotencyKey(key: string, source: string): string {
+  if (key.length === 0) {
+    throw new InvalidIdempotencyKeyError(
+      `${source} cannot be empty. An empty Idempotency-Key turns idempotency off ` +
+        "rather than on; omit it to have one minted, or pass a value you keep.",
+    );
+  }
+  if (key.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+    throw new InvalidIdempotencyKeyError(
+      `${source} must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} characters, got ${key.length}.`,
+    );
+  }
+  if (!IDEMPOTENCY_KEY_PATTERN.test(key)) {
+    throw new InvalidIdempotencyKeyError(
+      `${source} must be printable ASCII with no spaces (0x21 to 0x7E). ` +
+        "The value travels as an HTTP header, which cannot carry anything else.",
+    );
+  }
+  return key;
+}
+
+export function randomIdempotencyKey(): string {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0"));
+  return [
+    hex.slice(0, 4).join(""),
+    hex.slice(4, 6).join(""),
+    hex.slice(6, 8).join(""),
+    hex.slice(8, 10).join(""),
+    hex.slice(10, 16).join(""),
+  ].join("-");
+}

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

@@ -1,36 +1,75 @@
-import { HttpClient, type KartaOptions } from "./http.js";
+import { FleetResource } from "./fleet.js";
+import { HttpClient, type DhartaOptions } from "./http.js";
 import {
+  AgentsResource,
   ApiKeysResource,
   BillingResource,
-  ModelKeysResource,
+  GithubRepositoriesResource,
+  KartasResource,
+  MembersResource,
+  ModelConnectionsResource,
+  OrganizationResource,
+  ReleasesResource,
+  SourceReposResource,
   UsageResource,
   WebhookEndpointsResource,
 } from "./resources.js";
 
 export class Dharta {
+  readonly agents: AgentsResource;
+  readonly releases: ReleasesResource;
+  readonly githubRepositories: GithubRepositoriesResource;
   readonly apiKeys: ApiKeysResource;
-  readonly modelKeys: ModelKeysResource;
+  readonly kartas: KartasResource;
+  readonly members: MembersResource;
+  readonly modelConnections: ModelConnectionsResource;
+  readonly organization: OrganizationResource;
+  readonly sourceRepos: SourceReposResource;
   readonly webhookEndpoints: WebhookEndpointsResource;
   readonly usage: UsageResource;
   readonly billing: BillingResource;
+  readonly fleet: FleetResource;
 
-  constructor(opts: KartaOptions) {
+  constructor(opts: DhartaOptions) {
     const http = new HttpClient(opts);
+    this.agents = new AgentsResource(http);
+    this.releases = new ReleasesResource(http);
+    this.githubRepositories = new GithubRepositoriesResource(http);
     this.apiKeys = new ApiKeysResource(http);
-    this.modelKeys = new ModelKeysResource(http);
+    this.kartas = new KartasResource(http);
+    this.members = new MembersResource(http);
+    this.modelConnections = new ModelConnectionsResource(http);
+    this.organization = new OrganizationResource(http);
+    this.sourceRepos = new SourceReposResource(http);
     this.webhookEndpoints = new WebhookEndpointsResource(http);
     this.usage = new UsageResource(http);
     this.billing = new BillingResource(http);
+    this.fleet = new FleetResource(http);
   }
 }
 
-export type { KartaOptions, RequestOptions } from "./http.js";
+export type { DhartaOptions, RequestOptions } from "./http.js";
+// Every mutating method takes this as its last argument. A caller retrying an
+// ambiguous failure needs to name the type to hold the key it reused.
+export type { MutationOptions } from "./idempotency.js";
+export {
+  assertIdempotencyKey,
+  InvalidIdempotencyKeyError,
+  INVALID_IDEMPOTENCY_KEY_CODE,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+} from "./idempotency.js";
 export { HttpClient } from "./http.js";
+export type { ModelConnectionApiFormat } from "./types.js";
+export * from "./fleet.js";
 export * from "./types.js";
+// The resource classes and their parameter and result shapes. Consumers reach
+// them through `new Dharta(...)`, but the types have to be nameable: the CLI
+// annotates its command functions with them.
+export * from "./resources.js";
 export {
-  KartaError,
-  KartaAuthError,
-  KartaForbiddenError,
-  KartaNotFoundError,
-  KartaValidationError,
+  DhartaError,
+  DhartaAuthError,
+  DhartaForbiddenError,
+  DhartaNotFoundError,
+  DhartaValidationError,
 } from "./errors.js";