feat: Add customer-facing OTLP destination CRUD API

Stainless-Generated-From: f3471e525bb7006b1991b78ccc41e1805f0048c9

Author: kernel-internal[bot]

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 134
+configured_endpoints: 139

api.md

@@ -303,6 +303,22 @@ Methods:
 - <code title="post /auth/connections/{id}/submit">client.auth.connections.<a href="./src/resources/auth/connections.ts">submit</a>(id, { ...params }) -> SubmitFieldsResponse</code>
 - <code title="get /auth/connections/{id}/timeline">client.auth.connections.<a href="./src/resources/auth/connections.ts">timeline</a>(id, { ...params }) -> ManagedAuthTimelineEventsOffsetPagination</code>
 
+# Telemetry
+
+## Destinations
+
+Types:
+
+- <code><a href="./src/resources/telemetry/destinations.ts">OtlpDestination</a></code>
+
+Methods:
+
+- <code title="post /telemetry/destinations">client.telemetry.destinations.<a href="./src/resources/telemetry/destinations.ts">create</a>({ ...params }) -> OtlpDestination</code>
+- <code title="get /telemetry/destinations/{id_or_name}">client.telemetry.destinations.<a href="./src/resources/telemetry/destinations.ts">retrieve</a>(idOrName) -> OtlpDestination</code>
+- <code title="patch /telemetry/destinations/{id_or_name}">client.telemetry.destinations.<a href="./src/resources/telemetry/destinations.ts">update</a>(idOrName, { ...params }) -> OtlpDestination</code>
+- <code title="get /telemetry/destinations">client.telemetry.destinations.<a href="./src/resources/telemetry/destinations.ts">list</a>({ ...params }) -> OtlpDestinationsOffsetPagination</code>
+- <code title="delete /telemetry/destinations/{id_or_name}">client.telemetry.destinations.<a href="./src/resources/telemetry/destinations.ts">delete</a>(idOrName) -> void</code>
+
 # Proxies
 
 Types:

src/client.ts

@@ -180,6 +180,7 @@ import {
   ProjectsOffsetPagination,
   UpdateProjectRequest,
 } from './resources/projects/projects';
+import { Telemetry } from './resources/telemetry/telemetry';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -1020,6 +1021,7 @@ export class Kernel {
    */
   profiles: API.Profiles = new API.Profiles(this);
   auth: API.Auth = new API.Auth(this);
+  telemetry: API.Telemetry = new API.Telemetry(this);
   /**
    * Create and manage proxy configurations for routing browser traffic.
    */
@@ -1064,6 +1066,7 @@ Kernel.Invocations = Invocations;
 Kernel.Browsers = Browsers;
 Kernel.Profiles = Profiles;
 Kernel.Auth = Auth;
+Kernel.Telemetry = Telemetry;
 Kernel.Proxies = Proxies;
 Kernel.Extensions = Extensions;
 Kernel.BrowserPools = BrowserPools;
@@ -1161,6 +1164,8 @@ export declare namespace Kernel {
 
   export { Auth as Auth };
 
+  export { Telemetry as Telemetry };
+
   export {
     Proxies as Proxies,
     type ProxyCreateResponse as ProxyCreateResponse,

src/resources/browsers/telemetry.ts

@@ -10,7 +10,7 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * Stream live telemetry events from a browser session.
+ * Stream live telemetry events from a browser session, and manage the destinations sessions export them to.
  */
 export class Telemetry extends APIResource {
   /**

src/resources/index.ts

@@ -156,3 +156,4 @@ export {
   type ProxyCheckParams,
   type ProxyListResponsesOffsetPagination,
 } from './proxies';
+export { Telemetry } from './telemetry/telemetry';

src/resources/telemetry.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './telemetry/index';

src/resources/telemetry/destinations.ts

@@ -0,0 +1,188 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Stream live telemetry events from a browser session, and manage the destinations sessions export them to.
+ */
+export class Destinations extends APIResource {
+  /**
+   * Create an OTLP export destination in the resolved project. Names must be unique
+   * within the project.
+   */
+  create(body: DestinationCreateParams, options?: RequestOptions): APIPromise<OtlpDestination> {
+    return this._client.post('/telemetry/destinations', { body, ...options });
+  }
+
+  /**
+   * Retrieve a single OTLP destination in the resolved project by its ID or name.
+   */
+  retrieve(idOrName: string, options?: RequestOptions): APIPromise<OtlpDestination> {
+    return this._client.get(path`/telemetry/destinations/${idOrName}`, options);
+  }
+
+  /**
+   * Update an OTLP destination. Sessions already exporting to it pick up the new
+   * values without restarting, which makes this the way to rotate credentials
+   * without interrupting export.
+   *
+   * Names must be unique within the project. Renaming is refused with a 409 while a
+   * managed auth connection selects this destination by name, since that connection
+   * resolves the name on every login. Every other field, including `headers`, stays
+   * editable.
+   */
+  update(
+    idOrName: string,
+    body: DestinationUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<OtlpDestination> {
+    return this._client.patch(path`/telemetry/destinations/${idOrName}`, { body, ...options });
+  }
+
+  /**
+   * List OTLP export destinations in the resolved project.
+   */
+  list(
+    query: DestinationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<OtlpDestinationsOffsetPagination, OtlpDestination> {
+    return this._client.getAPIList('/telemetry/destinations', OffsetPagination<OtlpDestination>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Delete an OTLP destination. Sessions bound to it are still exporting, so the
+   * delete is refused with a 409 while any exist; either wait for those sessions to
+   * end or delete them first. It is refused the same way while a managed auth
+   * connection still selects it, because that connection re-resolves the destination
+   * on every login, and while a managed auth login using it is still in progress.
+   */
+  delete(idOrName: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/telemetry/destinations/${idOrName}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type OtlpDestinationsOffsetPagination = OffsetPagination<OtlpDestination>;
+
+/**
+ * An OTLP endpoint to export browser session telemetry to. Reference one from
+ * `telemetry.export.otlp.destination` when creating a browser to export that
+ * session's captured telemetry to it.
+ */
+export interface OtlpDestination {
+  id: string;
+
+  created_at: string;
+
+  /**
+   * OTLP/HTTP endpoint telemetry is sent to.
+   */
+  endpoint: string;
+
+  /**
+   * Headers sent with each export request. Names are returned in canonical form
+   * (`Authorization`, not `authorization`). Values are returned redacted as empty
+   * strings, so the keys are visible but the credentials are not.
+   */
+  headers: { [key: string]: string };
+
+  /**
+   * Unique within the project. Usable in place of the ID when selecting a
+   * destination, so it cannot be shaped like an ID.
+   */
+  name: string;
+
+  updated_at: string;
+
+  description?: string;
+}
+
+export interface DestinationCreateParams {
+  /**
+   * Base endpoint of the OTLP/HTTP collector, without a signal path. Kernel appends
+   * the signal path itself, so pass `https://api.honeycomb.io` rather than
+   * `https://api.honeycomb.io/v1/logs`. If your provider's docs give you a
+   * signal-specific URL, drop the trailing `/v1/logs`, `/v1/traces`, or
+   * `/v1/metrics` — an endpoint that already carries one is rejected.
+   *
+   * Must be http or https, must resolve to a public address, and must carry no query
+   * string or fragment. Examples: `https://api.honeycomb.io`,
+   * `https://otlp-gateway-prod-us-east-0.grafana.net/otlp`,
+   * `https://otlp.datadoghq.com` (Datadog's OTLP intake for US1, not its logs
+   * intake).
+   */
+  endpoint: string;
+
+  /**
+   * Unique within the project.
+   */
+  name: string;
+
+  description?: string;
+
+  /**
+   * Headers sent with each export request, typically an ingestion key. Encrypted at
+   * rest and returned redacted. Names and values must be valid HTTP header tokens,
+   * and the names and values together cannot exceed 8192 bytes. Names are matched
+   * case-insensitively and stored canonicalized, so supplying two spellings of one
+   * header is rejected.
+   */
+  headers?: { [key: string]: string };
+}
+
+export interface DestinationUpdateParams {
+  description?: string;
+
+  /**
+   * Base endpoint of the OTLP/HTTP collector, without a signal path. Same rules as
+   * on create.
+   */
+  endpoint?: string;
+
+  /**
+   * Edits stored headers key by key rather than replacing the map. A string value
+   * adds or replaces that header, `null` deletes it, and any key you omit is left as
+   * it is. Names are matched case-insensitively, so `authorization` replaces a
+   * stored `Authorization` rather than adding a second entry. This is the credential
+   * rotation path; sessions already exporting pick up the new values without
+   * restarting. Names and values must be valid HTTP header tokens, and the names and
+   * values together cannot exceed 8192 bytes.
+   */
+  headers?: { [key: string]: string | null };
+
+  name?: string;
+}
+
+export interface DestinationListParams extends OffsetPaginationParams {
+  /**
+   * Exact-match filter on destination name using the database collation. In
+   * production, matching is case- and accent-insensitive.
+   */
+  name?: string;
+
+  /**
+   * Case-insensitive substring match against destination name or endpoint. IDs match
+   * by exact value.
+   */
+  query?: string;
+}
+
+export declare namespace Destinations {
+  export {
+    type OtlpDestination as OtlpDestination,
+    type OtlpDestinationsOffsetPagination as OtlpDestinationsOffsetPagination,
+    type DestinationCreateParams as DestinationCreateParams,
+    type DestinationUpdateParams as DestinationUpdateParams,
+    type DestinationListParams as DestinationListParams,
+  };
+}

src/resources/telemetry/index.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Destinations,
+  type OtlpDestination,
+  type DestinationCreateParams,
+  type DestinationUpdateParams,
+  type DestinationListParams,
+  type OtlpDestinationsOffsetPagination,
+} from './destinations';
+export { Telemetry } from './telemetry';

src/resources/telemetry/telemetry.ts

@@ -0,0 +1,29 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as DestinationsAPI from './destinations';
+import {
+  DestinationCreateParams,
+  DestinationListParams,
+  DestinationUpdateParams,
+  Destinations,
+  OtlpDestination,
+  OtlpDestinationsOffsetPagination,
+} from './destinations';
+
+export class Telemetry extends APIResource {
+  destinations: DestinationsAPI.Destinations = new DestinationsAPI.Destinations(this._client);
+}
+
+Telemetry.Destinations = Destinations;
+
+export declare namespace Telemetry {
+  export {
+    Destinations as Destinations,
+    type OtlpDestination as OtlpDestination,
+    type OtlpDestinationsOffsetPagination as OtlpDestinationsOffsetPagination,
+    type DestinationCreateParams as DestinationCreateParams,
+    type DestinationUpdateParams as DestinationUpdateParams,
+    type DestinationListParams as DestinationListParams,
+  };
+}