feat: add install app endpoint

Author: borosr

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

@@ -320,13 +320,13 @@ The full call path, HTTP route, and a short description are listed below.
 
 ### Apps
 
-| Method                                       | HTTP                                                  | Description                                    |
-| -------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
-| `client.apps.list`                           | `GET /openmeter/apps`                                 | List installed apps.                           |
-| `client.apps.get`                            | `GET /openmeter/apps/{appId}`                         | Get an installed app.                          |
-| `client.apps.listCatalog`                    | `GET /openmeter/app-catalog`                          | List available apps.                           |
-| `client.apps.getCatalogItem`                 | `GET /openmeter/app-catalog/{appType}`                | Get an app catalog item by type.               |
-| `client.apps.getCatalogItemOauth2InstallUrl` | `GET /openmeter/app-catalog/{appType}/install/oauth2` | Get OAuth2 install URL for an app catalog item |
+| Method                       | HTTP                                   | Description                      |
+| ---------------------------- | -------------------------------------- | -------------------------------- |
+| `client.apps.list`           | `GET /openmeter/apps`                  | List installed apps.             |
+| `client.apps.get`            | `GET /openmeter/apps/{appId}`          | Get an installed app.            |
+| `client.apps.listCatalog`    | `GET /openmeter/app-catalog`           | List available apps.             |
+| `client.apps.getCatalogItem` | `GET /openmeter/app-catalog/{appType}` | Get an app catalog item by type. |
+| `client.apps.install`        | `POST /openmeter/app-catalog/install`  | Install app from the catalog     |
 
 ### Billing
 

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

@@ -15,8 +15,8 @@ import type {
   ListAppCatalogResponse,
   GetAppCatalogItemRequest,
   GetAppCatalogItemResponse,
-  GetAppCatalogItemOauth2InstallUrlRequest,
-  GetAppCatalogItemOauth2InstallUrlResponse,
+  InstallAppRequest,
+  InstallAppResponse,
 } from '../models/operations/apps.js'
 
 /**
@@ -152,33 +152,28 @@ export function getAppCatalogItem(
 }
 
 /**
- * Get OAuth2 install URL for an app catalog item
+ * Install app from the catalog
  *
- * GET /openmeter/app-catalog/{appType}/install/oauth2
+ * POST /openmeter/app-catalog/install
  */
-export function getAppCatalogItemOauth2InstallUrl(
+export function installApp(
   client: Client,
-  req: GetAppCatalogItemOauth2InstallUrlRequest,
+  req: InstallAppRequest,
   options?: RequestOptions,
-): Promise<Result<GetAppCatalogItemOauth2InstallUrlResponse>> {
+): Promise<Result<InstallAppResponse>> {
   return request(() => {
-    const path = `openmeter/app-catalog/${(() => {
-      if (req.appType === undefined) {
-        throw new Error('missing path parameter: appType')
-      }
-      return encodeURIComponent(String(req.appType))
-    })()}/install/oauth2`
+    const body = toWire(req, schemas.installAppBody)
+    if (client._options.validate) {
+      assertValid(schemas.installAppBodyWire, body)
+    }
     return http(client)
-      .get(path, options)
+      .post('openmeter/app-catalog/install', { ...options, json: body })
       .json()
       .then((data) => {
         if (client._options.validate) {
-          assertValid(
-            schemas.getAppCatalogItemOauth2InstallUrlResponseWire,
-            data,
-          )
+          assertValid(schemas.installAppResponseWire, data)
         }
-        return fromWire(data, schemas.getAppCatalogItemOauth2InstallUrlResponse)
+        return fromWire(data, schemas.installAppResponse)
       })
   })
 }

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

@@ -73,7 +73,9 @@ export type {
   PriceFree,
   RateCardStaticEntitlement,
   RateCardBooleanEntitlement,
-  AppOAuth2InstallResponse,
+  InstallAppStripeWithApiKey,
+  InstallAppSandbox,
+  InstallAppExternalInvoicing,
   WorkflowCollectionAlignmentSubscription,
   WorkflowPaymentChargeAutomaticallySettings,
   WorkflowPaymentSendInvoiceSettings,
@@ -312,6 +314,7 @@ export type {
   FeaturePagePaginatedResponse,
   Workflow,
   AppPagePaginatedResponse,
+  BillingInstallAppResponse,
   ProfileApps,
   ChargeUsageBased,
   SubscriptionAddonRateCard,

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

@@ -7,8 +7,9 @@ import type {
   App,
   AppCatalogItem,
   AppCatalogItemPagePaginatedResponse,
-  AppOAuth2InstallResponse,
   AppPagePaginatedResponse,
+  BillingInstallAppResponse,
+  InstallAppRequest as InstallAppRequestBody,
 } from '../types.js'
 
 export interface ListAppsQuery {
@@ -37,7 +38,5 @@ export type GetAppCatalogItemRequest = {
 }
 export type GetAppCatalogItemResponse = AppCatalogItem
 
-export type GetAppCatalogItemOauth2InstallUrlRequest = {
-  appType: string
-}
-export type GetAppCatalogItemOauth2InstallUrlResponse = AppOAuth2InstallResponse
+export type InstallAppRequest = AcceptDateStrings<InstallAppRequestBody>
+export type InstallAppResponse = BillingInstallAppResponse

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

@@ -728,16 +728,30 @@ export const appStatus = z
   .enum(['ready', 'unauthorized'])
   .describe('Connection status of an installed app.')
 
-export const appOAuth2InstallResponse = z
+export const installAppStripeWithApiKey = z
   .object({
-    url: z
-      .string()
-      .describe('The URL to start the OAuth2 authorization code grant flow.'),
+    type: z.literal('stripe').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    createBillingProfile: z.boolean().describe('Description of the app.'),
+    apiKey: z.string().describe('API key for the app.'),
   })
+  .describe('Model for installing an app from the catalog with an API key.')
 
-  .describe(
-    'Response from the billing app installation endpoint to initiate the OAuth2 authorization flow. This response contains the authorization URL where the user should be redirected to grant permissions to the application. The URL includes all necessary OAuth2 parameters such as client_id, redirect_uri, scope, and state.',
-  )
+export const installAppSandbox = z
+  .object({
+    type: z.literal('sandbox').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    createBillingProfile: z.boolean().describe('Description of the app.'),
+  })
+  .describe('Base model for installing an app from the catalog.')
+
+export const installAppExternalInvoicing = z
+  .object({
+    type: z.literal('external_invoicing').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    createBillingProfile: z.boolean().describe('Description of the app.'),
+  })
+  .describe('Base model for installing an app from the catalog.')
 
 export const taxIdentificationCode = z
   .string()
@@ -2805,6 +2819,14 @@ export const appCapability = z
   })
   .describe('App capability describes a function that an App can perform.')
 
+export const installAppRequest = z
+  .discriminatedUnion('type', [
+    installAppStripeWithApiKey,
+    installAppSandbox,
+    installAppExternalInvoicing,
+  ])
+  .describe('Request to install an app from the catalog.')
+
 export const partyTaxIdentity = z
   .object({
     code: taxIdentificationCode.optional(),
@@ -5037,6 +5059,13 @@ export const appPagePaginatedResponse = z
   })
   .describe('Page paginated response.')
 
+export const billingInstallAppResponse = z
+  .object({
+    app: app,
+    defaultForCapabilityTypes: z.array(appCapabilityType),
+  })
+  .describe('Response of the app install.')
+
 export const profileApps = z
   .object({
     tax: app,
@@ -6118,12 +6147,9 @@ export const getAppCatalogItemPathParams = z.object({
 
 export const getAppCatalogItemResponse = appCatalogItem
 
-export const getAppCatalogItemOauth2InstallUrlPathParams = z.object({
-  appType: appType,
-})
+export const installAppBody = installAppRequest
 
-export const getAppCatalogItemOauth2InstallUrlResponse =
-  appOAuth2InstallResponse
+export const installAppResponse = billingInstallAppResponse
 
 export const listBillingProfilesQueryParams = z.object({
   page: z
@@ -7273,16 +7299,30 @@ export const appStatusWire = z
   .enum(['ready', 'unauthorized'])
   .describe('Connection status of an installed app.')
 
-export const appOAuth2InstallResponseWire = z
+export const installAppStripeWithApiKeyWire = z
   .strictObject({
-    url: z
-      .string()
-      .describe('The URL to start the OAuth2 authorization code grant flow.'),
+    type: z.literal('stripe').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    create_billing_profile: z.boolean().describe('Description of the app.'),
+    api_key: z.string().describe('API key for the app.'),
   })
+  .describe('Model for installing an app from the catalog with an API key.')
 
-  .describe(
-    'Response from the billing app installation endpoint to initiate the OAuth2 authorization flow. This response contains the authorization URL where the user should be redirected to grant permissions to the application. The URL includes all necessary OAuth2 parameters such as client_id, redirect_uri, scope, and state.',
-  )
+export const installAppSandboxWire = z
+  .strictObject({
+    type: z.literal('sandbox').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    create_billing_profile: z.boolean().describe('Description of the app.'),
+  })
+  .describe('Base model for installing an app from the catalog.')
+
+export const installAppExternalInvoicingWire = z
+  .strictObject({
+    type: z.literal('external_invoicing').describe('Type of the app.'),
+    name: z.string().describe('Name of the app.'),
+    create_billing_profile: z.boolean().describe('Description of the app.'),
+  })
+  .describe('Base model for installing an app from the catalog.')
 
 export const taxIdentificationCodeWire = z
   .string()
@@ -9352,6 +9392,14 @@ export const appCapabilityWire = z
   })
   .describe('App capability describes a function that an App can perform.')
 
+export const installAppRequestWire = z
+  .discriminatedUnion('type', [
+    installAppStripeWithApiKeyWire,
+    installAppSandboxWire,
+    installAppExternalInvoicingWire,
+  ])
+  .describe('Request to install an app from the catalog.')
+
 export const partyTaxIdentityWire = z
   .strictObject({
     code: taxIdentificationCodeWire.optional(),
@@ -11602,6 +11650,13 @@ export const appPagePaginatedResponseWire = z
   })
   .describe('Page paginated response.')
 
+export const billingInstallAppResponseWire = z
+  .strictObject({
+    app: appWire,
+    default_for_capability_types: z.array(appCapabilityTypeWire),
+  })
+  .describe('Response of the app install.')
+
 export const profileAppsWire = z
   .strictObject({
     tax: appWire,
@@ -12691,12 +12746,9 @@ export const getAppCatalogItemPathParamsWire = z.object({
 
 export const getAppCatalogItemResponseWire = appCatalogItemWire
 
-export const getAppCatalogItemOauth2InstallUrlPathParamsWire = z.object({
-  appType: appTypeWire,
-})
+export const installAppBodyWire = installAppRequestWire
 
-export const getAppCatalogItemOauth2InstallUrlResponseWire =
-  appOAuth2InstallResponseWire
+export const installAppResponseWire = billingInstallAppResponseWire
 
 export const listBillingProfilesQueryParamsWire = z.object({
   page: z

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

@@ -199,17 +199,36 @@ export interface RateCardBooleanEntitlement {
   type: 'boolean'
 }
 
-/**
- * Response from the billing app installation endpoint to initiate the OAuth2
- * authorization flow.
- *
- * This response contains the authorization URL where the user should be redirected
- * to grant permissions to the application. The URL includes all necessary OAuth2
- * parameters such as client_id, redirect_uri, scope, and state.
- */
-export interface AppOAuth2InstallResponse {
-  /** The URL to start the OAuth2 authorization code grant flow. */
-  url: string
+/** Model for installing an app from the catalog with an API key. */
+export interface InstallAppStripeWithApiKey {
+  /** Type of the app. */
+  type: 'stripe'
+  /** Name of the app. */
+  name: string
+  /** Description of the app. */
+  createBillingProfile: boolean
+  /** API key for the app. */
+  apiKey: string
+}
+
+/** Base model for installing an app from the catalog. */
+export interface InstallAppSandbox {
+  /** Type of the app. */
+  type: 'sandbox'
+  /** Name of the app. */
+  name: string
+  /** Description of the app. */
+  createBillingProfile: boolean
+}
+
+/** Base model for installing an app from the catalog. */
+export interface InstallAppExternalInvoicing {
+  /** Type of the app. */
+  type: 'external_invoicing'
+  /** Name of the app. */
+  name: string
+  /** Description of the app. */
+  createBillingProfile: boolean
 }
 
 /**
@@ -4453,6 +4472,18 @@ export interface AppPagePaginatedResponse {
   meta: PaginatedMeta
 }
 
+/** Response of the app install. */
+export interface BillingInstallAppResponse {
+  app: App
+  defaultForCapabilityTypes: (
+    | 'report_usage'
+    | 'report_events'
+    | 'calculate_tax'
+    | 'invoice_customers'
+    | 'collect_payments'
+  )[]
+}
+
 /** Applications used by a billing profile. */
 export interface ProfileApps {
   /** The tax app used for this workflow. */
@@ -5306,6 +5337,12 @@ export type DateTimeFieldFilter =
  */
 export type SubscriptionEditTiming = 'immediate' | 'next_billing_cycle' | Date
 
+/** Request to install an app from the catalog. */
+export type InstallAppRequest =
+  | InstallAppStripeWithApiKey
+  | InstallAppSandbox
+  | InstallAppExternalInvoicing
+
 /** Payment settings for a billing workflow. */
 export type WorkflowPaymentSettings =
   | WorkflowPaymentChargeAutomaticallySettings