@runblackcat/sdk 0.1.0-alpha.89 → 0.1.0-alpha.91

package/README.md

@@ -193,7 +193,7 @@ sandbox.
 Backpressure is fleet capacity and the durable queue; there are no per-tenant
 quotas. A queued acquisition that waits past the queue deadline is torn down by
 the ordinary expiry reconciler. Request-rate limits are operator-set fleet state
-(`blackcat admin rate-limits get|set`): token mint and OIDC limits are on by
+(`blackcat admin rate-limits get|set`): session token-mint and OIDC limits are on by
 default, every workload limit is unlimited until set.
 
 The placer sizes the fleet from that backlog through the `CapacityProvider`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runblackcat/sdk",
-  "version": "0.1.0-alpha.89",
+  "version": "0.1.0-alpha.91",
   "description": "TypeScript SDK for the Blackcat sandbox gateway",
   "license": "Apache-2.0",
   "repository": "https://github.com/TreebeardHQ/blackcat",

package/sdk/dist/index.d.ts

@@ -33,7 +33,14 @@ export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit & {
 }) => Promise<Response>;
 export interface BlackcatClientOptions {
     baseUrl: string;
+    /**
+     * A tenant API key. The gateway accepts it directly on every resource route
+     * for the tenant's own resources (limited to the key's operation set), so a
+     * trusted server-side caller needs no `tokens.mint` per call. Keep it
+     * server-side; hand less-trusted holders a minted `token` instead.
+     */
     apiKey?: string;
+    /** A capability token; preferred over `apiKey` when both are set. */
     token?: string;
     /** Capability identity and expiry, using idiomatic TypeScript names. */
     tokenId?: string;

package/sdk/dist/index.js

@@ -354,17 +354,17 @@ class TemplatesResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/templates", input, "token");
+    return this.client.json("POST", "/v1/templates", input, "either");
   }
   list() {
-    return this.client.json("GET", "/v1/templates", undefined, "token");
+    return this.client.json("GET", "/v1/templates", undefined, "either");
   }
   async uploadImage(archive, options) {
     const response = await this.client.raw("POST", "/v1/template-images", archive, "either", "application/octet-stream", false, options?.signal);
     return await response.json();
   }
   activate(id) {
-    return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "token");
+    return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "either");
   }
 }
 
@@ -374,13 +374,13 @@ class TemplateResourcesResource {
     this.client = client;
   }
   get(name) {
-    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "token");
+    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
   }
   configure(name, input) {
-    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "token");
+    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "either");
   }
   delete(name) {
-    return this.client.json("DELETE", `/v1/template-resources/${pathSegment(name)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
   }
 }
 
@@ -390,13 +390,13 @@ class TemplateBuildsResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/template-builds", input, "token");
+    return this.client.json("POST", "/v1/template-builds", input, "either");
   }
   get(id) {
-    return this.client.json("GET", `/v1/template-builds/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/template-builds/${pathSegment(id)}`, undefined, "either");
   }
   retry(id) {
-    return this.client.json("POST", `/v1/template-builds/${pathSegment(id)}/retry`, undefined, "token");
+    return this.client.json("POST", `/v1/template-builds/${pathSegment(id)}/retry`, undefined, "either");
   }
 }
 
@@ -427,7 +427,7 @@ class FleetResource {
     this.client = client;
   }
   list() {
-    return this.client.json("GET", "/v1/fleet", undefined, "token");
+    return this.client.json("GET", "/v1/fleet", undefined, "either");
   }
 }
 
@@ -437,16 +437,16 @@ class ReservationsResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/capacity-reservations", input, "token");
+    return this.client.json("POST", "/v1/capacity-reservations", input, "either");
   }
   get(id) {
-    return this.client.json("GET", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
   }
   release(id) {
-    return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
   }
   renew(id, input) {
-    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "token");
+    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "either");
   }
 }
 
@@ -456,34 +456,34 @@ class SandboxesResource {
     this.client = client;
   }
   list() {
-    return this.client.json("GET", "/v1/sandboxes", undefined, "token");
+    return this.client.json("GET", "/v1/sandboxes", undefined, "either");
   }
   async create(input, options = {}) {
-    return parseCreateSandboxResponse(await this.client.json("POST", `/v1/sandboxes${waitQuery(options)}`, withTemplate(input), "token", false), input.request_id);
+    return parseCreateSandboxResponse(await this.client.json("POST", `/v1/sandboxes${waitQuery(options)}`, withTemplate(input), "either", false), input.request_id);
   }
   async createBatch(input) {
-    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
+    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "either", false), input.request_id);
   }
   async batch(requestId) {
-    return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "token"), requestId);
+    return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "either"), requestId);
   }
   async acquisition(requestId, options = {}) {
-    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}${waitQuery(options)}`, undefined, "token", options.wait_secs === undefined ? undefined : false), requestId);
+    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}${waitQuery(options)}`, undefined, "either", options.wait_secs === undefined ? undefined : false), requestId);
   }
   async cancelAcquisition(requestId) {
-    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);
+    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "either"), requestId);
   }
   get(id) {
-    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
   }
   renew(id, ttl_secs) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/renew`, { ttl_secs }, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/renew`, { ttl_secs }, "either");
   }
   grantSshKey(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "either");
   }
   async exec(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "token", false, execDeadline(input)).then(execResult);
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "either", false, execDeadline(input)).then(execResult);
   }
   async* execStream(id, input) {
     if (input.stdin !== undefined && input.stdin.length > MAX_EXEC_STDIN) {
@@ -499,7 +499,7 @@ class SandboxesResource {
       return chunk;
     };
     const decoder = new TextDecoder;
-    for await (const chunk of this.client.stream("POST", `/v1/sandboxes/${pathSegment(id)}/exec/stream`, JSON.stringify(input), "token", "application/json", true, execDeadline(input))) {
+    for await (const chunk of this.client.stream("POST", `/v1/sandboxes/${pathSegment(id)}/exec/stream`, JSON.stringify(input), "either", "application/json", true, execDeadline(input))) {
       lineBuffer += decoder.decode(chunk, { stream: true });
       const lines = lineBuffer.split(`
 `);
@@ -522,10 +522,10 @@ class SandboxesResource {
     return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/processes`, {
       ...input,
       ...input.stdin === undefined ? {} : { stdin: Array.from(input.stdin) }
-    }, "token", false, undefined, { "idempotency-key": requestId });
+    }, "either", false, undefined, { "idempotency-key": requestId });
   }
   getProcess(id, processId) {
-    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "token");
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
   }
   async processLogs(id, processId, input = {}) {
     const options = typeof input === "number" ? { stdout_offset: 0, stderr_offset: 0, max_bytes: input } : input;
@@ -537,7 +537,7 @@ class SandboxesResource {
     if (options.max_bytes !== undefined)
       query.set("max_bytes", String(options.max_bytes));
     const suffix = query.size === 0 ? "" : `?${query.toString()}`;
-    const response = await this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}/logs${suffix}`, undefined, "token");
+    const response = await this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}/logs${suffix}`, undefined, "either");
     return {
       ...response,
       logs: {
@@ -548,13 +548,13 @@ class SandboxesResource {
     };
   }
   cancelProcess(id, processId) {
-    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
   }
   prepare(id, input, idempotencyKey) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/prepare`, input, "token", undefined, undefined, { "idempotency-key": idempotencyKey });
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/prepare`, input, "either", undefined, undefined, { "idempotency-key": idempotencyKey });
   }
   logs(id) {
-    return this.client.stream("GET", `/v1/sandboxes/${pathSegment(id)}/logs`, undefined, "token", undefined, true);
+    return this.client.stream("GET", `/v1/sandboxes/${pathSegment(id)}/logs`, undefined, "either", undefined, true);
   }
   async readFileChunk(id, input) {
     if (input.offset < 0 || input.length <= 0 || input.length > MAX_FILE_READ_CHUNK) {
@@ -565,7 +565,7 @@ class SandboxesResource {
       offset: String(input.offset),
       length: String(input.length)
     });
-    const response = await this.client.raw("GET", `/v1/sandboxes/${pathSegment(id)}/files/read?${query.toString()}`, undefined, "token");
+    const response = await this.client.raw("GET", `/v1/sandboxes/${pathSegment(id)}/files/read?${query.toString()}`, undefined, "either");
     const data = new Uint8Array(await response.arrayBuffer());
     const offset = Number(response.headers.get("x-blackcat-offset") ?? input.offset);
     const eof = response.headers.get("x-blackcat-eof") === "true";
@@ -616,7 +616,7 @@ class SandboxesResource {
       offset: String(input.offset),
       truncate: String(input.truncate)
     });
-    await this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/files/write?${query.toString()}`, requestBody(input.data), "token", "application/octet-stream");
+    await this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/files/write?${query.toString()}`, requestBody(input.data), "either", "application/octet-stream");
   }
   async writeFileStream(id, input) {
     const start = input.offset ?? 0;
@@ -661,28 +661,28 @@ class SandboxesResource {
     });
   }
   snapshot(id) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/snapshot`, undefined, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/snapshot`, undefined, "either");
   }
   pause(id) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/pause`, undefined, "token").then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/pause`, undefined, "either").then(() => {
       return;
     });
   }
   hibernate(id, input) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/hibernate`, input === undefined ? undefined : JSON.stringify(input), "token", input === undefined ? undefined : "application/json", false).then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/hibernate`, input === undefined ? undefined : JSON.stringify(input), "either", input === undefined ? undefined : "application/json", false).then(() => {
       return;
     });
   }
   resize(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/resize`, { ...input, request_id: input.request_id ?? `resize-${crypto.randomUUID()}` }, "token", false);
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/resize`, { ...input, request_id: input.request_id ?? `resize-${crypto.randomUUID()}` }, "either", false);
   }
   resume(id) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/resume`, undefined, "token").then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/resume`, undefined, "either").then(() => {
       return;
     });
   }
   destroy(id) {
-    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
   }
 }