feat(felixible aggregation): Expose expression in API (#293)

* feat(felixible aggregation): Expose expression in API

* feat(felixible aggregation): Add documentation for expression evaluation endpoint

src/resources/billable_metric_evaluate_expression.yaml

@@ -0,0 +1,26 @@
+post:
+  tags:
+    - billable_metrics
+  summary: Evaluate an expression for a billable metric
+  description: Evaluate an expression for a billable metric creation by providing the expression and test data
+  operationId: evaluateBillableMetricExpression
+  requestBody:
+    description: Billable metric expression evaluation payload
+    content:
+      application/json:
+        schema:
+          $ref: "../schemas/BillableMetricEvaluateExpressionInput.yaml"
+    required: true
+  responses:
+    "200":
+      description: Billable metric expression evaluation result
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/BillableMetricEvaluateExpressionResult.yaml"
+    "400":
+      $ref: "../responses/BadRequest.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/schemas/BillableMetricBaseInput.yaml

@@ -22,6 +22,14 @@ properties:
       - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.
       - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period.
       - If not defined in the request, default value is `false`.
+  expression:
+    type: string
+    example: "round((ended_at - started_at) * units)"
+    description: |
+      Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
+      Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations.
+      Round is accepting an optional second parameter to specify the number of decimal.
+    nullable: true
   field_name:
     type: string
     example: "gb"

src/schemas/BillableMetricEvaluateExpressionInput.yaml

@@ -0,0 +1,40 @@
+type: object
+required:
+  - expression
+  - event
+properties:
+  expression:
+    type: string
+    example: "round((ended_at - started_at) * units)"
+    description: |
+      Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
+      Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations.
+      Round is accepting an optional second parameter to specify the number of decimal.
+  event:
+    type: object
+    required:
+      - code
+      - properties
+    properties:
+      code:
+        type: string
+        example: "storage"
+        description: The code that identifies a targeted billable metric.
+      timestamp:
+        anyOf:
+          - type: integer
+          - type: string
+        example: "1651240791"
+        description: |
+          This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC).
+          If this timestamp is not provided, the API will automatically set it to the time of event reception.
+      properties:
+        type: object
+        description: This field represents additional properties associated with the event. They can be used when evaluating the expression.
+        additionalProperties:
+          oneOf:
+            - type: string
+            - type: integer
+            - type: number
+        example:
+          gb: 10

src/schemas/BillableMetricEvaluateExpressionResult.yaml

@@ -0,0 +1,15 @@
+type: object
+required:
+  - expression_result
+properties:
+  expression_result:
+    type: object
+    required:
+      - value
+    properties:
+      value:
+        anyOf:
+          - type: string
+          - type: number
+        example: 1.0
+        description: "Result of evaluating the expression"

src/schemas/BillableMetricObject.yaml

@@ -42,6 +42,10 @@ properties:
     format: "date-time"
     example: "2022-09-14T16:35:31Z"
     description: "Creation date of the billable metric."
+  expression:
+    type: string
+    example: "round((ended_at - started_at) * units)"
+    description: "Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units."
   field_name:
     type: string
     example: "gb"

src/schemas/_index.yaml

@@ -44,6 +44,10 @@ BillableMetricBaseInput:
   $ref: "./BillableMetricBaseInput.yaml"
 BillableMetricCreateInput:
   $ref: "./BillableMetricCreateInput.yaml"
+BillableMetricEvaluateExpressionInput:
+  $ref: "./BillableMetricEvaluateExpressionInput.yaml"
+BillableMetricEvaluateExpressionResult:
+  $ref: "./BillableMetricEvaluateExpressionResult.yaml"
 BillableMetricFilterInput:
   $ref: "./BillableMetricFilterInput.yaml"
 BillableMetricFilterObject: