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

package/README.md

@@ -168,6 +168,12 @@ GET  /v1/sandboxes/acquisitions/{id}       -> 202 pending … -> 200 {"state":"p
 POST /v1/sandboxes/{id}/renew {ttl_secs}   -> 200 {"expires_at":…, "renewable_until":…}
 ```
 
+Add `?wait_secs=N` (held at most 55 s) to the create or the lookup to have the gateway
+hold a still-pending claim and answer as soon as it is placed or fails; the
+placed receipt carries `ports`, so there is nothing to poll and no second call.
+A claim still pending when the hold ends is answered `pending`; ask again. It
+does not apply to a `count` batch: wait on each member by `request_id`.
+
 To start many identical sandboxes, add `"count": N` (1 to 1000) to the create.
 `request_id` then names the batch and member `i` is `request_id.i`. The whole batch
 is recorded in one durable transaction and answered `202` at once, with no

package/package.json

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

package/sdk/dist/index.d.ts

@@ -369,8 +369,8 @@ export type CreateCapacityReservationInput = ({
      * ordinary work; a sandbox create naming it waits for one of its slots. */
     placement?: "shared" | "dedicated";
     /** With `placement: "dedicated"`, the provider shape to launch: an exact
-     * shape or a family (`c7i`) of the fleet's capacity shapes. Absent: the
-     * planner chooses. */
+     * shape or a family (`c7i`) the fleet can launch (direct EC2: the config's
+     * instance_types). Absent: the planner chooses. */
     shape?: string;
     /** Stable retry key, at most 107 ASCII letters, digits, `_` or `-`. */
     idempotency_key?: string;
@@ -406,6 +406,15 @@ export interface CapacityReservation {
     /** When the capacity must be ready (epoch milliseconds), or null. */
     needed_by: number | null;
 }
+export interface WaitOptions {
+    /**
+     * Have the gateway hold a still-pending claim for up to this many seconds
+     * and answer as soon as it is placed or fails, with its ports, instead of
+     * answering `pending` at once. The gateway holds at most 55 seconds. A claim
+     * still pending after the hold is returned as `pending`; ask again.
+     */
+    wait_secs?: number;
+}
 /**
  * Response returned by POST /v1/sandboxes (the gateway has no template field).
  * The gateway sends a `failed` receipt with HTTP 409, so `create` and
@@ -872,7 +881,7 @@ declare class SandboxesResource {
      * recover a lost response. A pending receipt is not an executable sandbox;
      * no automatic retry, new ID, or replacement allocation is synthesized here.
      */
-    create(input: CreateSandboxInput): Promise<CreateSandboxResponse>;
+    create(input: CreateSandboxInput, options?: WaitOptions): Promise<CreateSandboxResponse>;
     /**
      * Create `count` identical sandboxes under one request ID. Resolves as soon
      * as the whole batch is durably recorded; nothing waits on a restore.
@@ -882,7 +891,7 @@ declare class SandboxesResource {
     createBatch(input: CreateSandboxBatchInput): Promise<SandboxBatchResponse>;
     /** Counts by state and every member of a batch created with `createBatch`. */
     batch(requestId: string): Promise<SandboxBatchResponse>;
-    acquisition(requestId: string): Promise<CreateSandboxResponse>;
+    acquisition(requestId: string, options?: WaitOptions): Promise<CreateSandboxResponse>;
     /**
      * Fence an acquisition request ID before its create is recorded, or destroy
      * the allocation when the create has already won.

package/sdk/dist/index.js

@@ -21,6 +21,9 @@ var BLACKCAT_ERROR_CODES = {
 function withTemplate(input) {
   return { ...input, template: input.template ?? "default" };
 }
+function waitQuery({ wait_secs }) {
+  return wait_secs === undefined ? "" : `?wait_secs=${wait_secs}`;
+}
 
 class BlackcatApiError extends Error {
   status;
@@ -455,8 +458,8 @@ class SandboxesResource {
   list() {
     return this.client.json("GET", "/v1/sandboxes", undefined, "token");
   }
-  async create(input) {
-    return parseCreateSandboxResponse(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
+  async create(input, options = {}) {
+    return parseCreateSandboxResponse(await this.client.json("POST", `/v1/sandboxes${waitQuery(options)}`, withTemplate(input), "token", false), input.request_id);
   }
   async createBatch(input) {
     return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
@@ -464,8 +467,8 @@ class SandboxesResource {
   async batch(requestId) {
     return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "token"), requestId);
   }
-  async acquisition(requestId) {
-    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), 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);
   }
   async cancelAcquisition(requestId) {
     return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);