feat(api): v3 list entitlement access (#3693)

Co-authored-by: Peter Marton <peter@openmeter.io>

Author: tothandras

api/spec/src/v3/entitlements/access.tsp

@@ -0,0 +1,42 @@
+import "../../types.tsp";
+import "./entitlements.tsp";
+
+namespace Entitlements;
+
+/**
+ * Entitlement access result.
+ */
+@friendlyName("BillingEntitlementAccessResult")
+model EntitlementAccessResult {
+  /**
+   * The type of the entitlement.
+   */
+  @example(EntitlementType.static)
+  @visibility(Lifecycle.Read)
+  type: EntitlementType;
+
+  /**
+   * The feature key of the entitlement.
+   */
+  @example("available_models")
+  @visibility(Lifecycle.Read)
+  feature_key: ExternalKey;
+
+  /**
+   * Whether the customer has access to the feature.
+   * Always true for `boolean` and `static` entitlements.
+   * Depends on balance for `metered` entitlements.
+   */
+  @example(true)
+  @visibility(Lifecycle.Read)
+  has_access: boolean;
+
+  /**
+   * Only available for static entitlements.
+   * Config is the JSON parsable configuration of the entitlement.
+   * Useful to describe per customer configuration.
+   */
+  @example("{ \"availableModels\": [\"gpt-5\", \"gpt-4o\"] }")
+  @visibility(Lifecycle.Read)
+  config?: string;
+}

api/spec/src/v3/entitlements/entitlements.tsp

@@ -0,0 +1,11 @@
+namespace Entitlements;
+
+/**
+ * The type of the entitlement.
+ */
+@friendlyName("BillingEntitlementType")
+enum EntitlementType {
+  metered,
+  static,
+  boolean,
+}

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

@@ -0,0 +1,3 @@
+import "./entitlements.tsp";
+import "./access.tsp";
+import "./operations.tsp";

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

@@ -0,0 +1,44 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi";
+import "@typespec/openapi3";
+import "../common/error.tsp";
+import "../shared/index.tsp";
+import "./access.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+
+namespace Entitlements;
+
+/**
+ * List the customer's active features and their access.
+ */
+@friendlyName("ListCustomerEntitlementAccessResponse")
+model ListCustomerEntitlementAccessResponse {
+  @Http.statusCode _: 200;
+  @body body: ListCustomerEntitlementAccessResponseData;
+}
+
+/**
+ * List customer entitlement access response data.
+ */
+@friendlyName("ListCustomerEntitlementAccessResponseData")
+model ListCustomerEntitlementAccessResponseData {
+  /**
+   * The list of entitlement access results.
+   */
+  @visibility(Lifecycle.Read)
+  data: EntitlementAccessResult[];
+}
+
+interface CustomerEntitlementsOperations {
+  @get
+  @operationId("list-customer-entitlement-access")
+  @summary("List customer entitlement access")
+  @extension(Shared.UnstableExtension, true)
+  @extension(Shared.InternalExtension, true)
+  list(
+    @path customerId: Shared.ULID,
+  ): ListCustomerEntitlementAccessResponse | Common.NotFound | Common.ErrorResponses;
+}

api/spec/src/v3/konnect.tsp

@@ -6,6 +6,7 @@ import "./shared/index.tsp";
 import "./events/index.tsp";
 import "./meters/index.tsp";
 import "./customers/index.tsp";
+import "./entitlements/index.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
@@ -29,6 +30,10 @@ using TypeSpec.OpenAPI;
 @tagMetadata(Shared.MetersTag, #{ description: Shared.MetersDescription })
 @tagMetadata(Shared.EventsTag, #{ description: Shared.EventsDescription })
 @tagMetadata(Shared.CustomersTag, #{ description: Shared.CustomersDescription })
+@tagMetadata(
+  Shared.EntitlementsTag,
+  #{ description: Shared.EntitlementsDescription }
+)
 @useAuth(systemAccountAccessToken | personalAccessToken | konnectAccessToken)
 namespace MeteringAndBilling;
 
@@ -47,6 +52,13 @@ interface MetersEndpoints extends Meters.MetersOperations {}
 @friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.CustomersTag}")
 interface CustomersEndpoints extends Customers.CustomersOperations {}
 
+@route("/openmeter/customers/{customerId}/entitlement-access")
+@tag(Shared.CustomersTag)
+@tag(Shared.EntitlementsTag)
+@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.EntitlementsTag}")
+interface CustomerEntitlementsEndpoints
+  extends Entitlements.CustomerEntitlementsOperations {}
+
 /**
  * The system account access token is meant for automations and integrations that are not directly associated with a human identity.
  */

api/spec/src/v3/openmeter.tsp

@@ -27,6 +27,10 @@ using TypeSpec.OpenAPI;
 @tagMetadata(Shared.MetersTag, #{ description: Shared.MetersDescription })
 @tagMetadata(Shared.EventsTag, #{ description: Shared.EventsDescription })
 @tagMetadata(Shared.CustomersTag, #{ description: Shared.CustomersDescription })
+@tagMetadata(
+  Shared.EntitlementsTag,
+  #{ description: Shared.EntitlementsDescription }
+)
 namespace OpenMeter;
 
 @route("/openmeter/events")
@@ -43,3 +47,10 @@ interface MetersEndpoints extends Meters.MetersOperations {}
 @tag(Shared.CustomersTag)
 @friendlyName("${Shared.OpenMeterTitle}: ${Shared.CustomersTag}")
 interface CustomersEndpoints extends Customers.CustomersOperations {}
+
+@route("/openmeter/customers/{customerId}/entitlement-access")
+@tag(Shared.CustomersTag)
+@tag(Shared.EntitlementsTag)
+@friendlyName("${Shared.OpenMeterTitle}: ${Shared.EntitlementsTag}")
+interface CustomerEntitlementsEndpoints
+  extends Entitlements.CustomerEntitlementsOperations {}