feat(api): v3 meter (#3692)

Co-authored-by: Gergely Tamas Kurucz <[email protected]>

Author: tothandras

api/spec/src/v3/konnect.tsp

@@ -4,6 +4,7 @@ import "@typespec/openapi";
 import "@typespec/openapi3";
 import "./shared/index.tsp";
 import "./events/index.tsp";
+import "./meters/index.tsp";
 import "./customers/index.tsp";
 
 using TypeSpec.Http;
@@ -25,6 +26,7 @@ using TypeSpec.OpenAPI;
 // TODO: Uncomment this when the Singapore production region is available
 // @server("https://sg.api.konghq.com/v3", "Singapore Production region")
 @server("https://global.api.konghq.com/v3", "Global Production region")
+@tagMetadata(Shared.MetersTag, #{ description: Shared.MetersDescription })
 @tagMetadata(Shared.EventsTag, #{ description: Shared.EventsDescription })
 @tagMetadata(Shared.CustomersTag, #{ description: Shared.CustomersDescription })
 @useAuth(systemAccountAccessToken | personalAccessToken | konnectAccessToken)
@@ -35,6 +37,11 @@ namespace MeteringAndBilling;
 @friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.EventsTag}")
 interface EventsEndpoints extends Events.EventsOperations {}
 
+@route("/openmeter/meters")
+@tag(Shared.MetersTag)
+@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.MetersTag}")
+interface MetersEndpoints extends Meters.MetersOperations {}
+
 @route("/openmeter/customers")
 @tag(Shared.CustomersTag)
 @friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.CustomersTag}")

api/spec/src/v3/meters/index.tsp

@@ -0,0 +1,2 @@
+import "./meter.tsp";
+import "./operations.tsp";

api/spec/src/v3/meters/meter.tsp

@@ -0,0 +1,82 @@
+import "../shared/index.tsp";
+
+namespace Meters;
+
+/**
+ * A meter is a configuration that defines how to match and aggregate events.
+ */
+@friendlyName("Meter")
+@example(#{
+  id: "01G65Z755AFWAKHE12NY0CQ9FH",
+  key: "tokens_total",
+  name: "Tokens Total",
+  description: "AI Token Usage",
+  aggregation: "sum",
+  event_type: "prompt",
+  value_property: "$.tokens",
+  dimensions: #{ `model`: "$.model", type: "$.type" },
+  created_at: Shared.DateTime.fromISO("2024-01-01T01:01:01.001Z"),
+  updated_at: Shared.DateTime.fromISO("2024-01-01T01:01:01.001Z"),
+})
+model Meter {
+  ...Shared.ResourceWithKey;
+
+  /**
+   * The aggregation type to use for the meter.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  aggregation: MeterAggregation;
+
+  /**
+   * The event type to include in the aggregation.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  @minLength(1)
+  @example("prompt")
+  event_type: string;
+
+  /**
+   * The date since the meter should include events.
+   * Useful to skip old events.
+   * If not specified, all historical events are included.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  event_from?: Shared.DateTime;
+
+  /**
+   * JSONPath expression to extract the value from the ingested event's data property.
+   *
+   * The ingested value for sum, avg, min, and max aggregations is a number or a string that can be parsed to a number.
+   *
+   * For unique_count aggregation, the ingested value must be a string. For count aggregation the value_property is ignored.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  @minLength(1)
+  @example("$.tokens")
+  value_property?: string;
+
+  /**
+   * Named JSONPath expressions to extract the group by values from the event data.
+   *
+   * Keys must be unique and consist only alphanumeric and underscore characters.
+   *
+   */
+  // TODO: add key format enforcement
+  @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
+  @example(#{ type: "$.type" })
+  dimensions?: Record<string>;
+}
+
+/**
+ * The aggregation type to use for the meter.
+ */
+@friendlyName("MeterAggregation")
+union MeterAggregation {
+  sum: "sum",
+  count: "count",
+  unique_count: "unique_count",
+  avg: "avg",
+  min: "min",
+  max: "max",
+  latest: "latest",
+}

api/spec/src/v3/meters/operations.tsp

@@ -0,0 +1,56 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi";
+import "@typespec/openapi3";
+import "../common/error.tsp";
+import "../common/pagination.tsp";
+import "../common/parameters.tsp";
+import "../shared/index.tsp";
+import "./meter.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+
+namespace Meters;
+
+interface MetersOperations {
+  /**
+   * Create a meter.
+   */
+  @post
+  @operationId("create-meter")
+  @summary("Create meter")
+  create(
+    @body meter: Shared.CreateRequest<Meter>,
+  ): Shared.CreateResponse<Meter> | Common.ErrorResponses;
+
+  /**
+   * Get a meter by ID.
+   */
+  @get
+  @operationId("get-meter")
+  @summary("Get meter")
+  get(
+    @path meterId: Shared.ULID,
+  ): Shared.GetResponse<Meter> | Common.NotFound | Common.ErrorResponses;
+
+  /**
+   * List meters.
+   */
+  @get
+  @operationId("list-meters")
+  @summary("List meters")
+  list(
+    ...Common.PagePaginationQuery,
+  ): Shared.PagePaginatedResponse<Meter> | Common.ErrorResponses;
+
+  /**
+   * Delete a meter.
+   */
+  @delete
+  @operationId("delete-meter")
+  @summary("Delete meter")
+  delete(
+    @path meterId: Shared.ULID,
+  ): Shared.DeleteResponse | Common.NotFound | Common.ErrorResponses;
+}

api/spec/src/v3/openmeter.tsp

@@ -2,8 +2,9 @@ import "@typespec/http";
 import "@typespec/rest";
 import "@typespec/openapi";
 import "@typespec/openapi3";
-import "./events/index.tsp";
 import "./shared/index.tsp";
+import "./events/index.tsp";
+import "./meters/index.tsp";
 import "./customers/index.tsp";
 
 using TypeSpec.Http;
@@ -23,6 +24,7 @@ using TypeSpec.OpenAPI;
   termsOfService: "https://openmeter.cloud/terms-of-service",
 })
 @server("https://openmeter.cloud/api/v3", "Cloud")
+@tagMetadata(Shared.MetersTag, #{ description: Shared.MetersDescription })
 @tagMetadata(Shared.EventsTag, #{ description: Shared.EventsDescription })
 @tagMetadata(Shared.CustomersTag, #{ description: Shared.CustomersDescription })
 namespace OpenMeter;
@@ -32,6 +34,11 @@ namespace OpenMeter;
 @friendlyName("${Shared.OpenMeterTitle}: ${Shared.EventsTag}")
 interface EventsEndpoints extends Events.EventsOperations {}
 
+@route("/openmeter/meters")
+@tag(Shared.MetersTag)
+@friendlyName("${Shared.OpenMeterTitle}: ${Shared.MetersTag}")
+interface MetersEndpoints extends Meters.MetersOperations {}
+
 @route("/openmeter/customers")
 @tag(Shared.CustomersTag)
 @friendlyName("${Shared.OpenMeterTitle}: ${Shared.CustomersTag}")