feat: [beta] adding axon, an event communication channel (#8268)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-64b2ded3d3cc58131c7ebf36c411f43c3d8dabae0b5b1edd65dd7dab307c54a1.yml
-openapi_spec_hash: 80fabb5e89a61299203113505a894dc2
-config_hash: de99cfce88e2d1f02246dc6c2f43bc6c
+configured_endpoints: 122
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-d3f6f5cc574b570bb31c768e755f957273a97846257c7144ff5c0dcf7c00fd75.yml
+openapi_spec_hash: 8d7f2b3ed5c1504d3d238e0e43d45383
+config_hash: 1b42d9862d8d811030df0ac4094f7a1d

api.md

@@ -76,6 +76,24 @@ Methods:
 - <code title="get /v1/agents/{id}">client.agents.<a href="./src/resources/agents.ts">retrieve</a>(id) -> AgentView</code>
 - <code title="get /v1/agents">client.agents.<a href="./src/resources/agents.ts">list</a>({ ...params }) -> AgentViewsAgentsCursorIDPage</code>
 
+# Axons
+
+Types:
+
+- <code><a href="./src/resources/axons.ts">AxonCreateParams</a></code>
+- <code><a href="./src/resources/axons.ts">AxonListView</a></code>
+- <code><a href="./src/resources/axons.ts">AxonView</a></code>
+- <code><a href="./src/resources/axons.ts">PublishParams</a></code>
+- <code><a href="./src/resources/axons.ts">PublishResultView</a></code>
+
+Methods:
+
+- <code title="post /v1/axons">client.axons.<a href="./src/resources/axons.ts">create</a>() -> AxonView</code>
+- <code title="get /v1/axons/{id}">client.axons.<a href="./src/resources/axons.ts">retrieve</a>(id) -> AxonView</code>
+- <code title="get /v1/axons">client.axons.<a href="./src/resources/axons.ts">list</a>() -> AxonListView</code>
+- <code title="post /v1/axons/{id}/publish">client.axons.<a href="./src/resources/axons.ts">publish</a>(id, { ...params }) -> PublishResultView</code>
+- <code title="get /v1/axons/{id}/subscribe/sse">client.axons.<a href="./src/resources/axons.ts">subscribeSse</a>(id) -> void</code>
+
 # Blueprints
 
 Types:

src/index.ts

@@ -45,6 +45,15 @@ import {
   AgentViewsAgentsCursorIDPage,
   Agents,
 } from './resources/agents';
+import {
+  AxonCreateParams,
+  AxonListView,
+  AxonPublishParams,
+  AxonView,
+  Axons,
+  PublishParams,
+  PublishResultView,
+} from './resources/axons';
 import {
   BenchmarkJobCreateParameters,
   BenchmarkJobCreateParams,
@@ -363,6 +372,7 @@ export class Runloop extends Core.APIClient {
   benchmarkRuns: API.BenchmarkRuns = new API.BenchmarkRuns(this);
   benchmarkJobs: API.BenchmarkJobs = new API.BenchmarkJobs(this);
   agents: API.Agents = new API.Agents(this);
+  axons: API.Axons = new API.Axons(this);
   blueprints: API.Blueprints = new API.Blueprints(this);
   devboxes: API.Devboxes = new API.Devboxes(this);
   scenarios: API.Scenarios = new API.Scenarios(this);
@@ -423,6 +433,7 @@ Runloop.BenchmarkRunViewsBenchmarkRunsCursorIDPage = BenchmarkRunViewsBenchmarkR
 Runloop.BenchmarkJobs = BenchmarkJobs;
 Runloop.Agents = Agents;
 Runloop.AgentViewsAgentsCursorIDPage = AgentViewsAgentsCursorIDPage;
+Runloop.Axons = Axons;
 Runloop.Blueprints = Blueprints;
 Runloop.BlueprintViewsBlueprintsCursorIDPage = BlueprintViewsBlueprintsCursorIDPage;
 Runloop.Devboxes = Devboxes;
@@ -575,6 +586,16 @@ export declare namespace Runloop {
     type AgentListParams as AgentListParams,
   };
 
+  export {
+    Axons as Axons,
+    type AxonCreateParams as AxonCreateParams,
+    type AxonListView as AxonListView,
+    type AxonView as AxonView,
+    type PublishParams as PublishParams,
+    type PublishResultView as PublishResultView,
+    type AxonPublishParams as AxonPublishParams,
+  };
+
   export {
     Blueprints as Blueprints,
     type BlueprintBuildFromInspectionParameters as BlueprintBuildFromInspectionParameters,

src/resources/axons.ts

@@ -0,0 +1,131 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../resource';
+import * as Core from '../core';
+
+export class Axons extends APIResource {
+  /**
+   * [Beta] Create a new axon.
+   */
+  create(
+    body?: AxonCreateParams | null | undefined,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<AxonView> {
+    return this._client.post('/v1/axons', { body, ...options });
+  }
+
+  /**
+   * [Beta] Get an axon given ID.
+   */
+  retrieve(id: string, options?: Core.RequestOptions): Core.APIPromise<AxonView> {
+    return this._client.get(`/v1/axons/${id}`, options);
+  }
+
+  /**
+   * [Beta] List all active axons.
+   */
+  list(options?: Core.RequestOptions): Core.APIPromise<AxonListView> {
+    return this._client.get('/v1/axons', options);
+  }
+
+  /**
+   * [Beta] Publish an event to a specified axon.
+   */
+  publish(
+    id: string,
+    body: AxonPublishParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PublishResultView> {
+    return this._client.post(`/v1/axons/${id}/publish`, { body, ...options });
+  }
+}
+
+export type AxonCreateParams = unknown;
+
+export interface AxonListView {
+  /**
+   * List of active axons.
+   */
+  axons: Array<AxonView>;
+}
+
+export interface AxonView {
+  /**
+   * The axon identifier.
+   */
+  id: string;
+
+  /**
+   * Creation time in milliseconds since epoch.
+   */
+  created_at_ms: number;
+}
+
+export interface PublishParams {
+  /**
+   * The event type (e.g. push, pull_request).
+   */
+  event_type: string;
+
+  /**
+   * Event origin.
+   */
+  origin: 'EXTERNAL_EVENT' | 'AGENT_EVENT' | 'USER_EVENT';
+
+  /**
+   * Event payload.
+   */
+  payload: string;
+
+  /**
+   * The source of the event (e.g. github, slack).
+   */
+  source: string;
+}
+
+export interface PublishResultView {
+  /**
+   * Assigned sequence number.
+   */
+  sequence: number;
+
+  /**
+   * Timestamp in milliseconds since epoch.
+   */
+  timestamp_ms: number;
+}
+
+export interface AxonCreateParams {}
+
+export interface AxonPublishParams {
+  /**
+   * The event type (e.g. push, pull_request).
+   */
+  event_type: string;
+
+  /**
+   * Event origin.
+   */
+  origin: 'EXTERNAL_EVENT' | 'AGENT_EVENT' | 'USER_EVENT';
+
+  /**
+   * Event payload.
+   */
+  payload: string;
+
+  /**
+   * The source of the event (e.g. github, slack).
+   */
+  source: string;
+}
+
+export declare namespace Axons {
+  export {
+    type AxonCreateParams as AxonCreateParams,
+    type AxonListView as AxonListView,
+    type AxonView as AxonView,
+    type PublishParams as PublishParams,
+    type PublishResultView as PublishResultView,
+    type AxonPublishParams as AxonPublishParams,
+  };
+}

src/resources/index.ts

@@ -10,6 +10,15 @@ export {
   type AgentCreateParams,
   type AgentListParams,
 } from './agents';
+export {
+  Axons,
+  type AxonCreateParams,
+  type AxonListView,
+  type AxonView,
+  type PublishParams,
+  type PublishResultView,
+  type AxonPublishParams,
+} from './axons';
 export {
   BenchmarkJobs,
   type BenchmarkJobCreateParameters,

tests/api-resources/axons.test.ts

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Runloop from '@runloop/api-client';
+import { Response } from 'node-fetch';
+
+const client = new Runloop({
+  bearerToken: 'My Bearer Token',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('resource axons', () => {
+  test('create', async () => {
+    const responsePromise = client.axons.create();
+    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);
+  });
+
+  test('create: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(client.axons.create({}, { path: '/_stainless_unknown_path' })).rejects.toThrow(
+      Runloop.NotFoundError,
+    );
+  });
+
+  test('retrieve', async () => {
+    const responsePromise = client.axons.retrieve('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);
+  });
+
+  test('retrieve: request options instead of params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(client.axons.retrieve('id', { path: '/_stainless_unknown_path' })).rejects.toThrow(
+      Runloop.NotFoundError,
+    );
+  });
+
+  test('list', async () => {
+    const responsePromise = client.axons.list();
+    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);
+  });
+
+  test('list: request options instead of params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(client.axons.list({ path: '/_stainless_unknown_path' })).rejects.toThrow(
+      Runloop.NotFoundError,
+    );
+  });
+
+  test('publish: only required params', async () => {
+    const responsePromise = client.axons.publish('id', {
+      event_type: 'event_type',
+      origin: 'EXTERNAL_EVENT',
+      payload: 'payload',
+      source: 'source',
+    });
+    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);
+  });
+
+  test('publish: required and optional params', async () => {
+    const response = await client.axons.publish('id', {
+      event_type: 'event_type',
+      origin: 'EXTERNAL_EVENT',
+      payload: 'payload',
+      source: 'source',
+    });
+  });
+
+  test('subscribeSse', async () => {
+    const responsePromise = client.axons.subscribeSse('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);
+  });
+});