api/spec/packages/aip/src/apps/catalog.tsp

import "../shared/index.tsp";
import "./capability.tsp";
import "./app.tsp";

namespace Apps;

/**
 * Supported installation methods for an app.
 */
@friendlyName("BillingAppInstallMethods")
enum AppInstallMethods {
  /**
   * Install by completing an OAuth 2.0 authorization flow.
   */
  WithOAuth2: "with_oauth2",

  /**
   * Install by providing an API key.
   */
  WithAPIKey: "with_api_key",

  /**
   * Install without providing any credentials.
   */
  NoCredentialsRequired: "no_credentials_required",
}

/**
 * Available apps for billing integrations to connect with third-party services.
 * Apps can have various capabilities like syncing data from or to external
 * systems, integrating with third-party services for tax calculation, delivery of
 * invoices, collection of payments, etc.
 */
@friendlyName("BillingAppCatalogItem")
@example(#{
  type: AppType.Stripe,
  name: "Stripe",
  description: "Stripe integration allows you to collect payments with Stripe.",
  capabilities: #[
    #{
      type: AppCapabilityType.CalculateTax,
      key: "stripe_calculate_tax",
      name: "Calculate Tax",
      description: "Stripe Tax calculates tax portion of the invoices.",
    },
    #{
      type: AppCapabilityType.InvoiceCustomers,
      key: "stripe_invoice_customers",
      name: "Invoice Customers",
      description: "Stripe invoices customers with due amount.",
    },
    #{
      type: AppCapabilityType.CollectPayments,
      key: "stripe_collect_payments",
      name: "Collect Payments",
      description: "Stripe payments collects outstanding revenue with Stripe customer's default payment method.",
    }
  ],
  install_methods: #[
    AppInstallMethods.WithOAuth2,
    AppInstallMethods.WithAPIKey
  ],
})
model AppCatalogItem {
  /**
   * Type of the app.
   */
  @visibility(Lifecycle.Read)
  type: AppType;

  /**
   * Name of the app.
   */
  @visibility(Lifecycle.Read)
  name: string;

  /**
   * Description of the app.
   */
  @visibility(Lifecycle.Read)
  description: string;

  /**
   * Capabilities of the app.
   */
  @visibility(Lifecycle.Read)
  capabilities: AppCapability[];

  /**
   * Available install methods of the app.
   */
  @visibility(Lifecycle.Read)
  install_methods: AppInstallMethods[];
}

/**
 * Request to install an app from the catalog.
 */
@friendlyName("BillingInstallAppRequest")
@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
union InstallAppRequest {
  @summary("Stripe")
  stripe: InstallAppWithApiKey<AppType.Stripe>,

  @summary("Sandbox")
  sandbox: InstallAppBase<AppType.Sandbox>,

  @summary("External Invoicing")
  external_invoicing: InstallAppBase<AppType.ExternalInvoicing>,
}

/**
 * Base model for installing an app from the catalog.
 */
@friendlyName("BillingInstallApp{name}", T)
model InstallAppBase<T extends AppType> {
  /**
   * Type of the app.
   */
  type: T;

  /**
   * Name of the app.
   */
  name: string;

  /**
   * If true, a billing profile will be created for the app. The Stripe app will be
   * also set as the default billing profile if the current default is a Sandbox app.
   */
  create_billing_profile: boolean;
}

/**
 * Model for installing an app from the catalog with an API key.
 */
@friendlyName("BillingInstallApp{name}WithApiKey", T)
model InstallAppWithApiKey<T extends AppType> {
  ...InstallAppBase<T>;

  /**
   * API key for the app.
   */
  api_key: string;
}

/**
 * Response of the app install.
 */
@friendlyName("BillingInstallAppResponse")
model InstallAppResponse {
  @visibility(Lifecycle.Read)
  app: App;

  @visibility(Lifecycle.Read)
  default_for_capability_types: AppCapabilityType[];
}