docs: improve API docs for entitlements (#1139)

fix: typo

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

style: rephrase docs

Co-authored-by: Peter Turi <peter.turi@openmeter.io>
Signed-off-by: Alex Goth <64845621+GAlexIHU@users.noreply.github.com>

chore: regen api

api/client/node/clients/entitlement.ts

@@ -35,7 +35,9 @@ export class EntitlementClient extends BaseClient {
   }
 
   /**
-   * List entitlements
+   * List all entitlements regardless of subject.
+   * @description
+   * Most useful for administrative purposes.
    * @example
    * const entitlement = await openmeter.entitlements.list()
    */

api/client/node/clients/feature.ts

@@ -12,8 +12,11 @@ export class FeatureClient extends BaseClient {
   }
 
   /**
-   * Create Feature
    * Features are the building blocks of your entitlements, part of your product offering.
+   * @description
+   * Features are either metered or static. A feature is metered if meterSlug is provided at creation. For metered features you can pass additional filters that will be applied when calculating feature usage, based on the meter's groupBy fields. Only meters with SUM and COUNT aggregation are supported for features.
+   *
+   * Features cannot be updated later, only archived.
    *
    * @example
    * const feature = await openmeter.features.create({
@@ -76,7 +79,9 @@ export class FeatureClient extends BaseClient {
   }
 
   /**
-   * Delete feature by ID or Key
+   * Archive a feature by ID or Key.
+   * @description
+   * Once a feature is archived it cannot be unarchived. If a feature is archived, new entitlements cannot be created for it, but archiving the feature does not affect existing entitlements.
    * @example
    * await openmeter.delete('ai_tokens')
    */

api/client/node/clients/grant.ts

@@ -33,4 +33,22 @@ export class GrantClient extends BaseClient {
       options,
     })
   }
+
+  /**
+   * Void a grant
+   * @description
+   * Voiding a grant means it is no longer valid, it doesn't take part in further balance calculations. Voiding a grant does not retroactively take effect, meaning any usage that has already been attributed to the grant will remain, but future usage cannot be burnt down from the grant.
+   * @example
+   * const grant = await openmeter.grants.list()
+   */
+  public async delete(
+    id: string,
+    options?: RequestOptions
+  ): Promise<EntitlementGrant[]> {
+    return await this.request({
+      method: 'DELETE',
+      path: `/api/v1/grants/${id}`,
+      options,
+    })
+  }
 }

api/client/node/clients/subject.ts

@@ -89,7 +89,8 @@ export class SubjectClient extends BaseClient {
   /**
    * Create Entitlement
    * Entitlements allows you to manage subject feature access, balances, and usage limits.
-   *
+   * @remarks
+   * Input should be either `EntitlementMeteredCreateInputs`, `EntitlementStaticCreateInputs`, or `EntitlementBooleanCreateInputs`
    * @example
    * // Issue 10,000,000 tokens every month
    * const entitlement = await openmeter.subjects.createEntitlement('customer-1', {
@@ -118,7 +119,7 @@ export class SubjectClient extends BaseClient {
   }
 
   /**
-   * List entitlements
+   * List entitlements of a subject
    * @example
    * const entitlement = await openmeter.subjects.listEntitlements('customer-1')
    */
@@ -174,20 +175,41 @@ export class SubjectClient extends BaseClient {
   }
 
   /**
-   * Get entitlement value by ID by Feature ID or by Feature Key
+   * Get entitlement value by ID by Feature Key
    *
    * @example
    * const value = await openmeter.subjects.getEntitlementValue('customer-1', 'ai_tokens')
    */
   public async getEntitlementValue(
     subjectIdOrKey: string,
-    entitlementIdOrFeatureIdOrFeatureKey: string,
+    entitlementIdOrFeatureKey: string,
+    options?: RequestOptions
+  ): Promise<EntitlementValue> {
+    return await this.request({
+      path: `/api/v1/subjects/${subjectIdOrKey}/entitlements/${entitlementIdOrFeatureKey}/value`,
+      method: 'GET',
+      options,
+    })
+  }
+
+  /**
+   * Get entitlement value at a specific time.
+   *
+   * @example
+   * const value = await openmeter.subjects.getEntitlementValueAt('customer-1', 'ai_tokens')
+   */
+  public async getEntitlementValueAt(
+    subjectIdOrKey: string,
+    entitlementIdOrFeatureKey: string,
+    at: Date,
     options?: RequestOptions
   ): Promise<EntitlementValue> {
+    const searchParams = BaseClient.toURLSearchParams({ time: at })
     return await this.request({
-      path: `/api/v1/subjects/${subjectIdOrKey}/entitlements/${entitlementIdOrFeatureIdOrFeatureKey}/value`,
+      path: `/api/v1/subjects/${subjectIdOrKey}/entitlements/${entitlementIdOrFeatureKey}/value`,
       method: 'GET',
       options,
+      searchParams,
     })
   }