feat(api): add event subject list endpoint

Author: tothandras

api/spec/packages/aip-client-javascript/README.md

@@ -113,10 +113,11 @@ The full call path, HTTP route, and a short description are listed below.
 
 ### Events
 
-| Method                 | HTTP                     | Description                                                                  |
-| ---------------------- | ------------------------ | ---------------------------------------------------------------------------- |
-| `client.events.list`   | `GET /openmeter/events`  | List ingested events.                                                        |
-| `client.events.ingest` | `POST /openmeter/events` | Ingests an event or batch of events following the CloudEvents specification. |
+| Method                       | HTTP                             | Description                                                                           |
+| ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
+| `client.events.list`         | `GET /openmeter/events`          | List ingested events.                                                                 |
+| `client.events.ingest`       | `POST /openmeter/events`         | Ingests an event or batch of events following the CloudEvents specification.          |
+| `client.events.listSubjects` | `GET /openmeter/events/subjects` | List the subjects of the ingested events. Subjects are ordered by key alphabetically. |
 
 ### Meters
 

api/spec/packages/aip-client-javascript/src/funcs/events.ts

@@ -7,6 +7,8 @@ import type {
   ListMeteringEventsResponse,
   IngestMeteringEventsRequest,
   IngestMeteringEventsResponse,
+  ListEventSubjectsRequest,
+  ListEventSubjectsResponse,
 } from '../models/operations/events.js'
 
 export function listMeteringEvents(
@@ -35,3 +37,19 @@ export function ingestMeteringEvents(
     await http(client).post('openmeter/events', { ...options, json: req })
   })
 }
+
+export function listEventSubjects(
+  client: Client,
+  req: ListEventSubjectsRequest = {},
+  options?: RequestOptions,
+): Promise<Result<ListEventSubjectsResponse>> {
+  const searchParams = toURLSearchParams({
+    page: req.page,
+    filter: req.filter,
+  })
+  return request(() =>
+    http(client)
+      .get('openmeter/events/subjects', { ...options, searchParams })
+      .json<ListEventSubjectsResponse>(),
+  )
+}

api/spec/packages/aip-client-javascript/src/index.ts

@@ -55,6 +55,7 @@ export type {
   IngestedEventValidationError,
   CursorMetaPage,
   BaseError,
+  EventSubject,
   PageMeta,
   QueryFilterString,
   AppStripeCheckoutSessionCustomTextParams,
@@ -140,6 +141,7 @@ export type {
   Internal,
   NotImplemented,
   NotAvailable,
+  ListSubjectsParamsFilter,
   CreateCreditGrantFilters,
   CreditGrantFilters,
   UpsertPlanAddonRequest,
@@ -212,6 +214,7 @@ export type {
   IngestedEvent,
   MeterQueryResult,
   FeatureCostQueryResult,
+  SubjectPaginatedResponse,
   MeterPagePaginatedResponse,
   CostBasisPagePaginatedResponse,
   MeterQueryFilters,

api/spec/packages/aip-client-javascript/src/models/operations/events.ts

@@ -5,7 +5,9 @@ import type {
   EventInput,
   IngestedEventPaginatedResponse,
   ListEventsParamsFilter,
+  ListSubjectsParamsFilter,
   SortQueryInput,
+  SubjectPaginatedResponse,
 } from '../types.js'
 
 export interface ListMeteringEventsQuery {
@@ -21,3 +23,12 @@ export type ListMeteringEventsResponse = IngestedEventPaginatedResponse
 
 export type IngestMeteringEventsRequest = EventInput | EventInput[]
 export type IngestMeteringEventsResponse = void
+
+export interface ListEventSubjectsQuery {
+  page?: CursorPaginationQueryPage
+  /** Filter subjects returned in the response. To filter subjects by key add the following query param: filter[key][contains]=customer */
+  filter?: ListSubjectsParamsFilter
+}
+
+export type ListEventSubjectsRequest = ListEventSubjectsQuery
+export type ListEventSubjectsResponse = SubjectPaginatedResponse

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -253,6 +253,23 @@ export const baseError = z
   )
   .describe('Standard error response.')
 
+export const booleanFieldFilter = z
+  .union([
+    z.boolean(),
+    z.object({
+      eq: z
+        .boolean()
+        .describe('Value strictly equals the given boolean value.'),
+    }),
+  ])
+  .describe('Filter by a boolean value (true/false).')
+
+export const eventSubject = z
+  .object({
+    key: z.string().min(1).describe('The key of the subject.'),
+  })
+  .describe('Subject of an event.')
+
 export const resourceKey = z
   .string()
   .min(1)
@@ -1045,17 +1062,6 @@ export const publicLabels = z
     'Public labels store information about an entity that can be used for filtering a list of objects.',
   )
 
-export const booleanFieldFilter = z
-  .union([
-    z.boolean(),
-    z.object({
-      eq: z
-        .boolean()
-        .describe('Value strictly equals the given boolean value.'),
-    }),
-  ])
-  .describe('Filter by a boolean value (true/false).')
-
 export const numericFieldFilter = z
   .union([
     z.number(),
@@ -1927,6 +1933,13 @@ export const notImplemented = baseError.describe('Not Implemented.')
 
 export const notAvailable = baseError.describe('Not Available.')
 
+export const listSubjectsParamsFilter = z
+  .object({
+    key: stringFieldFilter.optional(),
+    attributed: booleanFieldFilter.optional(),
+  })
+  .describe('Filter options for listing subjects.')
+
 export const createCreditGrantFilters = z
   .object({
     features: z
@@ -3152,6 +3165,13 @@ export const featureCostQueryResult = z
   })
   .describe('Result of a feature cost query.')
 
+export const subjectPaginatedResponse = z
+  .object({
+    data: z.array(eventSubject),
+    meta: cursorMeta,
+  })
+  .describe('Cursor paginated response.')
+
 export const invalidParameter = z
   .union([
     invalidParameterStandard,
@@ -4624,6 +4644,16 @@ export const listMeteringEventsResponse = z.object({
 
 export const ingestMeteringEventsBody = event
 
+export const listEventSubjectsQueryParams = z.object({
+  page: cursorPaginationQueryPage.optional(),
+  filter: listSubjectsParamsFilter.optional(),
+})
+
+export const listEventSubjectsResponse = z.object({
+  data: z.array(eventSubject),
+  meta: cursorMeta,
+})
+
 export const createMeterBody = createMeterRequest
 
 export const createMeterResponse = meter

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -58,6 +58,12 @@ export interface BaseError {
   [key: string]: unknown
 }
 
+/** Subject of an event. */
+export interface EventSubject {
+  /** The key of the subject. */
+  key: string
+}
+
 /** Pagination information. */
 export interface PageMeta {
   /** Page number. */
@@ -938,6 +944,27 @@ export interface NotImplemented extends BaseError {}
 /** Not Available. */
 export interface NotAvailable extends BaseError {}
 
+/** Filter options for listing subjects. */
+export interface ListSubjectsParamsFilter {
+  /** Filter subjects by key. */
+  key?:
+    | string
+    | {
+        eq?: string
+        neq?: string
+        contains?: string
+        ocontains?: string[]
+        oeq?: string[]
+        gt?: string
+        gte?: string
+        lt?: string
+        lte?: string
+        exists?: boolean
+      }
+  /** Filter subjects by whether they are attributed to a customer. */
+  attributed?: boolean | { eq: boolean }
+}
+
 /** Filters for the credit grant. */
 export interface CreateCreditGrantFilters {
   /** Limit the credit grant to specific features. If no features are specified, the credit grant can be used for any feature. */
@@ -2089,6 +2116,12 @@ export interface FeatureCostQueryResult {
   data: FeatureCostQueryRow[]
 }
 
+/** Cursor paginated response. */
+export interface SubjectPaginatedResponse {
+  data: EventSubject[]
+  meta: CursorMeta
+}
+
 /** Page paginated response. */
 export interface MeterPagePaginatedResponse {
   data: Meter[]

api/spec/packages/aip-client-javascript/src/sdk/events.ts

@@ -1,11 +1,17 @@
 import { type Client } from '../core.js'
 import { unwrap, type RequestOptions } from '../lib/types.js'
-import { listMeteringEvents, ingestMeteringEvents } from '../funcs/events.js'
+import {
+  listMeteringEvents,
+  ingestMeteringEvents,
+  listEventSubjects,
+} from '../funcs/events.js'
 import type {
   ListMeteringEventsRequest,
   ListMeteringEventsResponse,
   IngestMeteringEventsRequest,
   IngestMeteringEventsResponse,
+  ListEventSubjectsRequest,
+  ListEventSubjectsResponse,
 } from '../models/operations/events.js'
 
 export class Events {
@@ -24,4 +30,11 @@ export class Events {
   ): Promise<IngestMeteringEventsResponse> {
     return unwrap(await ingestMeteringEvents(this._client, request, options))
   }
+
+  async listSubjects(
+    request?: ListEventSubjectsRequest,
+    options?: RequestOptions,
+  ): Promise<ListEventSubjectsResponse> {
+    return unwrap(await listEventSubjects(this._client, request, options))
+  }
 }

api/spec/packages/aip/src/events/index.tsp

@@ -1,2 +1,3 @@
 import "./event.tsp";
+import "./subject.tsp";
 import "./operations.tsp";

api/spec/packages/aip/src/events/operations.tsp

@@ -7,6 +7,7 @@ import "../common/pagination.tsp";
 import "../common/parameters.tsp";
 import "../shared/index.tsp";
 import "./event.tsp";
+import "./subject.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
@@ -132,3 +133,43 @@ interface EventsOperations {
     @body body: MeteringEvent | MeteringEvent[],
   ): IngestEventsResponse | Common.ErrorResponses;
 }
+
+/**
+ * Filter options for listing subjects.
+ */
+@friendlyName("ListSubjectsParamsFilter")
+model ListSubjectsParamsFilter {
+  /**
+   * Filter subjects by key.
+   */
+  key?: Common.StringFieldFilter;
+
+  /**
+   * Filter subjects by whether they are attributed to a customer.
+   */
+  attributed?: Common.BooleanFieldFilter;
+}
+
+interface EventsSubjectsOperations {
+  /**
+   * List the subjects of the ingested events. Subjects are ordered by key
+   * alphabetically.
+   */
+  @extension(Shared.UnstableExtension, true)
+  @extension(Shared.InternalExtension, true)
+  @get
+  @operationId("list-event-subjects")
+  @summary("List event subjects")
+  list(
+    ...Common.CursorPaginationQuery,
+
+    /**
+     * Filter subjects returned in the response.
+     *
+     * To filter subjects by key add the following query param:
+     * filter[key][contains]=customer
+     */
+    @query(#{ style: "deepObject", explode: true })
+    filter?: ListSubjectsParamsFilter,
+  ): Shared.CursorPaginatedResponse<Subject> | Common.ErrorResponses;
+}

api/spec/packages/aip/src/events/subject.tsp

@@ -0,0 +1,21 @@
+import "@typespec/openapi";
+import "@typespec/openapi3";
+import "../shared/index.tsp";
+import "../customers/index.tsp";
+
+namespace Events;
+
+/**
+ * Subject of an event.
+ */
+@friendlyName("MeteringEventSubject")
+model Subject {
+  /**
+   * The key of the subject.
+   */
+  @minLength(1)
+  @visibility(Lifecycle.Read)
+  @summary("Key")
+  @example("customer-id")
+  key: string;
+}