Add queryUsage method to billing services

A new method, queryUsage, has been added to the billing strategy classes and the gateway service to offer usage querying capabilities for Stripe and Lemon Squeezy. QueryBillingUsageSchema has also been introduced in the schema-related changes. Changes also include updates to the functions' comment descriptions. A minor tweak was made to the Button and Link components in the `faq/page.tsx' file.

packages/billing/core/src/schema/index.ts

@@ -4,3 +4,4 @@ export * from './retrieve-checkout-session.schema';
 export * from './cancel-subscription-params.schema';
 export * from './report-billing-usage.schema';
 export * from './update-subscription-params.schema';
+export * from './query-billing-usage.schema';

packages/billing/core/src/schema/query-billing-usage.schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+const TimeFilter = z.object(
+  {
+    startTime: z.number(),
+    endTime: z.number(),
+  },
+  {
+    description: `The time range to filter the usage records. Used for Stripe`,
+  },
+);
+
+const PageFilter = z.object(
+  {
+    page: z.number(),
+    size: z.number(),
+  },
+  {
+    description: `The page and size to filter the usage records. Used for LS`,
+  },
+);
+
+export const QueryBillingUsageSchema = z.object({
+  id: z.string({
+    description:
+      'The id of the usage record. For Stripe a meter ID, for LS a subscription item ID.',
+  }),
+  customerId: z.string({
+    description: 'The id of the customer in the billing system',
+  }),
+  filter: z.union([TimeFilter, PageFilter]),
+});

packages/billing/core/src/schema/report-billing-usage.schema.ts

@@ -1,9 +1,17 @@
 import { z } from 'zod';
 
 export const ReportBillingUsageSchema = z.object({
-  subscriptionItemId: z.string(),
+  id: z.string({
+    description:
+      'The id of the usage record. For Stripe a customer ID, for LS a subscription item ID.',
+  }),
+  eventName: z
+    .string({
+      description: 'The name of the event that triggered the usage',
+    })
+    .optional(),
   usage: z.object({
     quantity: z.number(),
-    action: z.enum(['increment', 'set']),
+    action: z.enum(['increment', 'set']).optional(),
   }),
 });

packages/billing/core/src/services/billing-strategy-provider.service.ts

@@ -8,6 +8,7 @@ import {
   RetrieveCheckoutSessionSchema,
   UpdateSubscriptionParamsSchema,
 } from '../schema';
+import { QueryBillingUsageSchema } from '../schema/query-billing-usage.schema';
 
 export abstract class BillingStrategyProviderService {
   abstract createBillingPortalSession(
@@ -46,6 +47,12 @@ export abstract class BillingStrategyProviderService {
     success: boolean;
   }>;
 
+  abstract queryUsage(
+    params: z.infer<typeof QueryBillingUsageSchema>,
+  ): Promise<{
+    value: number;
+  }>;
+
   abstract updateSubscription(
     params: z.infer<typeof UpdateSubscriptionParamsSchema>,
   ): Promise<{