feat: Model template as an instance state instead of a separate registry

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 52
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/hypeman-0aececd4fa79c47cb7222167d6746064c53b69eb70ee14252be71ccc31e6d2a2.yml
-openapi_spec_hash: c514624af74c74835e3187b857184ff2
-config_hash: ed668fae8826ff533f38df16c9664f44
+configured_endpoints: 54
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/hypeman-48b300e51c488f55e3f36024515bdb78a8fa5fe44c6fbde99d3f8a34c16df1cb.yml
+openapi_spec_hash: 1b53b5b26006f74ccbbb8facc57a9d44
+config_hash: dfacce742631adb22616891760f57888

api.md

@@ -54,9 +54,11 @@ Methods:
 - <code title="patch /instances/{id}">client.instances.<a href="./src/resources/instances/instances.ts">update</a>(id, { ...params }) -> Instance</code>
 - <code title="get /instances">client.instances.<a href="./src/resources/instances/instances.ts">list</a>({ ...params }) -> InstanceListResponse</code>
 - <code title="delete /instances/{id}">client.instances.<a href="./src/resources/instances/instances.ts">delete</a>(id) -> void</code>
+- <code title="post /instances/{id}/demote-template">client.instances.<a href="./src/resources/instances/instances.ts">demoteTemplate</a>(id) -> Instance</code>
 - <code title="post /instances/{id}/fork">client.instances.<a href="./src/resources/instances/instances.ts">fork</a>(id, { ...params }) -> Instance</code>
 - <code title="get /instances/{id}">client.instances.<a href="./src/resources/instances/instances.ts">get</a>(id) -> Instance</code>
 - <code title="get /instances/{id}/logs">client.instances.<a href="./src/resources/instances/instances.ts">logs</a>(id, { ...params }) -> string</code>
+- <code title="post /instances/{id}/promote-template">client.instances.<a href="./src/resources/instances/instances.ts">promoteTemplate</a>(id) -> Instance</code>
 - <code title="post /instances/{id}/restore">client.instances.<a href="./src/resources/instances/instances.ts">restore</a>(id) -> Instance</code>
 - <code title="post /instances/{id}/standby">client.instances.<a href="./src/resources/instances/instances.ts">standby</a>(id, { ...params }) -> Instance</code>
 - <code title="post /instances/{id}/start">client.instances.<a href="./src/resources/instances/instances.ts">start</a>(id, { ...params }) -> Instance</code>

src/resources/instances/instances.ts

@@ -83,6 +83,20 @@ export class Instances extends APIResource {
     });
   }
 
+  /**
+   * Demote a template back to standby so it can be restored or deleted
+   *
+   * @example
+   * ```ts
+   * const instance = await client.instances.demoteTemplate(
+   *   'id',
+   * );
+   * ```
+   */
+  demoteTemplate(id: string, options?: RequestOptions): APIPromise<Instance> {
+    return this._client.post(path`/instances/${id}/demote-template`, options);
+  }
+
   /**
    * Fork an instance from stopped, standby, or running (with from_running=true)
    *
@@ -138,6 +152,20 @@ export class Instances extends APIResource {
     }) as APIPromise<Stream<InstanceLogsResponse>>;
   }
 
+  /**
+   * Promote a standby instance into a fork-only template
+   *
+   * @example
+   * ```ts
+   * const instance = await client.instances.promoteTemplate(
+   *   'id',
+   * );
+   * ```
+   */
+  promoteTemplate(id: string, options?: RequestOptions): APIPromise<Instance> {
+    return this._client.post(path`/instances/${id}/promote-template`, options);
+  }
+
   /**
    * Restore instance from standby
    *
@@ -377,9 +405,20 @@ export interface Instance {
    * - Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
    * - Stopped: No VMM running, no snapshot exists
    * - Standby: No VMM running, snapshot exists (can be restored)
+   * - Template: Standby snapshot promoted to a fork-only parent; cannot wake while
+   *   forks exist
    * - Unknown: Failed to determine state (see state_error for details)
    */
-  state: 'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown';
+  state:
+    | 'Created'
+    | 'Initializing'
+    | 'Running'
+    | 'Paused'
+    | 'Shutdown'
+    | 'Stopped'
+    | 'Standby'
+    | 'Template'
+    | 'Unknown';
 
   /**
    * Linux-only automatic standby policy based on active inbound TCP connections
@@ -812,7 +851,16 @@ export interface WaitForStateResponse {
   /**
    * Current instance state when the wait completed
    */
-  state: 'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown';
+  state:
+    | 'Created'
+    | 'Initializing'
+    | 'Running'
+    | 'Paused'
+    | 'Shutdown'
+    | 'Stopped'
+    | 'Standby'
+    | 'Template'
+    | 'Unknown';
 
   /**
    * Whether the timeout expired before the target state was reached
@@ -1095,7 +1143,16 @@ export interface InstanceListParams {
   /**
    * Filter instances by state (e.g., Running, Stopped)
    */
-  state?: 'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown';
+  state?:
+    | 'Created'
+    | 'Initializing'
+    | 'Running'
+    | 'Paused'
+    | 'Shutdown'
+    | 'Stopped'
+    | 'Standby'
+    | 'Template'
+    | 'Unknown';
 
   /**
    * Filter instances by tag key-value pairs. Uses deepObject style:
@@ -1189,7 +1246,16 @@ export interface InstanceWaitParams {
   /**
    * Target state to wait for
    */
-  state: 'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown';
+  state:
+    | 'Created'
+    | 'Initializing'
+    | 'Running'
+    | 'Paused'
+    | 'Shutdown'
+    | 'Stopped'
+    | 'Standby'
+    | 'Template'
+    | 'Unknown';
 
   /**
    * Maximum duration to wait (Go duration format, e.g. "30s", "2m"). Capped at 5

tests/api-resources/instances/instances.test.ts

@@ -138,6 +138,18 @@ describe('resource instances', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Mock server tests are disabled
+  test.skip('demoteTemplate', async () => {
+    const responsePromise = client.instances.demoteTemplate('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
   // Mock server tests are disabled
   test.skip('fork: only required params', async () => {
     const responsePromise = client.instances.fork('id', { name: 'my-workload-1-fork' });
@@ -199,6 +211,18 @@ describe('resource instances', () => {
     ).rejects.toThrow(Hypeman.NotFoundError);
   });
 
+  // Mock server tests are disabled
+  test.skip('promoteTemplate', async () => {
+    const responsePromise = client.instances.promoteTemplate('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
   // Mock server tests are disabled
   test.skip('restore', async () => {
     const responsePromise = client.instances.restore('id');