Merge pull request #1366 from openmeterio/feat/om738

Implement entitlement overrides OM738

api/client/node/clients/subject.ts

@@ -118,6 +118,39 @@ export class SubjectClient extends BaseClient {
     })
   }
 
+  /**
+   * Override Entitlement
+   * Enables zero downtime upgrades and downgrades of entitlements.
+   * @remarks
+   * Input should be either `EntitlementMeteredCreateInputs`, `EntitlementStaticCreateInputs`, or `EntitlementBooleanCreateInputs`
+   * @example
+   * // Issue 10,000,000 tokens every month
+   * const entitlement = await openmeter.subjects.overrideEntitlement('customer-1', 'ai_tokens', {
+   *    type: 'metered',
+   *    featureKey: 'ai_tokens',
+   *    usagePeriod: {
+   *      interval: 'MONTH',
+   *    },
+   *    issueAfterReset: 10000000,
+   * })
+   */
+  public async overrideEntitlement(
+    subjectIdOrKey: string,
+    entitlementIdOrFeatureKey: string,
+    input: EntitlementCreateInputs,
+    options?: RequestOptions
+  ): Promise<Entitlement> {
+    return await this.request({
+      path: `/api/v1/subjects/${subjectIdOrKey}/entitlements/${entitlementIdOrFeatureKey}/override`,
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(input),
+      options,
+    })
+  }
+
   /**
    * List entitlements of a subject
    * @example

api/client/node/schemas/openapi.ts

@@ -227,6 +227,15 @@ export interface paths {
      */
     delete: operations['deleteEntitlement']
   }
+  '/api/v1/subjects/{subjectIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/override': {
+    /**
+     * Override an entitlement
+     * @description Overriding an entitlement creates a new entitlement from the provided inputs and soft deletes the previous entitlement for the provided subject-feature pair. If the previous entitlement is already deleted or otherwise doesnt exist, the override will fail.
+     *
+     * This endpoint is useful for upgrades, downgrades, or other changes to entitlements that require a new entitlement to be created with zero downtime.
+     */
+    put: operations['overrideEntitlement']
+  }
   '/api/v1/subjects/{subjectIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants': {
     /**
      * List grants for an entitlement
@@ -350,6 +359,11 @@ export interface paths {
      * @description List all notification events.
      */
     get: operations['listNotificationEvents']
+    /**
+     * Create a notification event
+     * @description Create a new notification event.
+     */
+    post: operations['createNotificationEvent']
   }
   '/api/v1/notification/events/{eventId}': {
     /**
@@ -358,6 +372,13 @@ export interface paths {
      */
     get: operations['getNotificationEvent']
   }
+  '/api/v1/notification/webhook/svix': {
+    /**
+     * Receive Svix operational events
+     * @description Callback endpoint used by Svix to notify about operational events
+     */
+    post: operations['receiveSvixOperationalEvent']
+  }
 }
 
 export type webhooks = Record<string, never>
@@ -1689,6 +1710,13 @@ export interface components {
        */
       disabled: boolean
     }
+    /** @description Request for creating new notification event with specific type and payload. */
+    NotificationEventCreateRequest: {
+      type: components['schemas']['NotificationEventType']
+      payload: components['schemas']['NotificationEventPayload']
+      /** @example 01J2KNP1YTXQRXHTDJ4KPR7PZ0 */
+      ruleId: string
+    }
     /**
      * @description Notification event generated by the system based on the criteria defined in the corresponding
      * a notification rule.
@@ -1701,6 +1729,7 @@ export interface components {
        * @example 01J2KNP1YTXQRXHTDJ4KPR7PZ0
        */
       id: string
+      type: components['schemas']['NotificationEventType']
       /**
        * Format: date-time
        * @description Timestamp when the notification event was created.
@@ -1738,14 +1767,16 @@ export interface components {
         entitlement: components['schemas']['EntitlementMetered']
         feature: components['schemas']['Feature']
         subject: components['schemas']['Subject']
-        balance: components['schemas']['EntitlementValue']
+        value: components['schemas']['EntitlementValue']
         threshold: components['schemas']['NotificationRuleBalanceThresholdValue']
       }
     }
     NotificationEventDeliveryStatus: {
       channel: components['schemas']['NotificationChannelMeta']
       /** @enum {string} */
-      state: 'SUCCESS' | 'FAILED' | 'SENDING'
+      state: 'SUCCESS' | 'FAILED' | 'SENDING' | 'PENDING'
+      /** @example Failed to dispatch event */
+      reason?: string
       /**
        * Format: date-time
        * @example 2023-01-01T00:00:00Z
@@ -1772,6 +1803,20 @@ export interface components {
       pageSize: number
       items: components['schemas']['NotificationEvents']
     }
+    SvixOperationalWebhookRequest: {
+      /** @enum {string} */
+      type:
+        | 'endpoint.created'
+        | 'endpoint.deleted'
+        | 'endpoint.disabled'
+        | 'endpoint.updated'
+        | 'message.attempt.exhausted'
+        | 'message.attempt.failing'
+        | 'message.attempt.recovered'
+      data: {
+        [key: string]: unknown
+      }
+    }
   }
   responses: {
     /** @description Conflict */
@@ -2651,6 +2696,40 @@ export interface operations {
       default: components['responses']['UnexpectedProblemResponse']
     }
   }
+  /**
+   * Override an entitlement
+   * @description Overriding an entitlement creates a new entitlement from the provided inputs and soft deletes the previous entitlement for the provided subject-feature pair. If the previous entitlement is already deleted or otherwise doesnt exist, the override will fail.
+   *
+   * This endpoint is useful for upgrades, downgrades, or other changes to entitlements that require a new entitlement to be created with zero downtime.
+   */
+  overrideEntitlement: {
+    parameters: {
+      path: {
+        subjectIdOrKey: components['parameters']['subjectIdOrKey']
+        entitlementIdOrFeatureKey: components['parameters']['entitlementIdOrFeatureKey']
+      }
+    }
+    /** @description The entitlement to create. */
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['EntitlementCreateInputs']
+      }
+    }
+    responses: {
+      /** @description Entitlement created. */
+      201: {
+        content: {
+          'application/json': components['schemas']['Entitlement']
+        }
+      }
+      400: components['responses']['BadRequestProblemResponse']
+      401: components['responses']['UnauthorizedProblemResponse']
+      404: components['responses']['NotFoundProblemResponse']
+      409: components['responses']['ConflictProblemResponse']
+      501: components['responses']['NotImplementedProblemResponse']
+      default: components['responses']['UnexpectedProblemResponse']
+    }
+  }
   /**
    * List grants for an entitlement
    * @description List all grants issued for an entitlement. The entitlement can be defined either by its id or featureKey.
@@ -3134,6 +3213,31 @@ export interface operations {
       default: components['responses']['UnexpectedProblemResponse']
     }
   }
+  /**
+   * Create a notification event
+   * @description Create a new notification event.
+   */
+  createNotificationEvent: {
+    /** @description The notification event to create. */
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['NotificationEventCreateRequest']
+      }
+    }
+    responses: {
+      /** @description Notification event created. */
+      201: {
+        content: {
+          'application/json': components['schemas']['NotificationEvent']
+        }
+      }
+      400: components['responses']['BadRequestProblemResponse']
+      401: components['responses']['UnauthorizedProblemResponse']
+      409: components['responses']['ConflictProblemResponse']
+      501: components['responses']['NotImplementedProblemResponse']
+      default: components['responses']['UnexpectedProblemResponse']
+    }
+  }
   /**
    * Get notification event
    * @description Get a notification event by id.
@@ -3156,4 +3260,26 @@ export interface operations {
       default: components['responses']['UnexpectedProblemResponse']
     }
   }
+  /**
+   * Receive Svix operational events
+   * @description Callback endpoint used by Svix to notify about operational events
+   */
+  receiveSvixOperationalEvent: {
+    /** @description The operational event. */
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['SvixOperationalWebhookRequest']
+      }
+    }
+    responses: {
+      /** @description Operational webhook request accepted */
+      204: {
+        content: never
+      }
+      400: components['responses']['BadRequestProblemResponse']
+      401: components['responses']['UnauthorizedProblemResponse']
+      501: components['responses']['NotImplementedProblemResponse']
+      default: components['responses']['UnexpectedProblemResponse']
+    }
+  }
 }