@automate.ax/catalog 0.55.0

package/src/types.ts

@@ -0,0 +1,219 @@
+export interface IntegrationFormFieldBase {
+  description?: string
+  label: string
+  name: string
+  required: boolean
+}
+
+export type IntegrationFormField =
+  | (IntegrationFormFieldBase & {
+      default?: string
+      input: "email" | "text" | "url"
+      placeholder?: string
+    })
+  | (IntegrationFormFieldBase & {
+      input: "password"
+      placeholder?: string
+    })
+  | (IntegrationFormFieldBase & {
+      default?: number
+      input: "number"
+      placeholder?: string
+    })
+  | (IntegrationFormFieldBase & {
+      default?: boolean
+      input: "boolean"
+    })
+
+interface IntegrationConnectionDefinitionBase {
+  description?: string
+  id: string
+  name: string
+}
+
+export type IntegrationConnectionDefinition =
+  | (IntegrationConnectionDefinitionBase & {
+      type: "redirect"
+    })
+  | (IntegrationConnectionDefinitionBase & {
+      fields: readonly IntegrationFormField[]
+      type: "form"
+    })
+
+export interface IntegrationServiceDefinition {
+  connectionMethods: readonly IntegrationConnectionDefinition[]
+  description?: string
+  id: string
+
+  /**
+   * Overrides the icon asset key inferred from `id`.
+   *
+   * Omit this unless the service intentionally reuses another icon asset.
+   */
+  icon?: string
+  name: string
+  preferredConnectionMethodId?: string
+}
+
+export type IntegrationScopeRequirement = ScopeRequirementGroup | string
+
+/** A recursive group of integration authorization scope requirements. */
+export interface ScopeRequirementGroup {
+  requirements: readonly IntegrationScopeRequirement[]
+  type: "and" | "or"
+}
+
+/** Combinators for declaring recursive integration scope requirements. */
+export const scope = {
+  /**
+   * Requires every scope or nested group.
+   *
+   * @param requirements - Required scopes and nested groups.
+   */
+  and(...requirements: IntegrationScopeRequirement[]): ScopeRequirementGroup {
+    return { requirements: [...new Set(requirements)], type: "and" }
+  },
+
+  /**
+   * Requires any scope or nested group.
+   *
+   * Alternatives must be ordered from most permissive to least permissive.
+   *
+   * @param requirements - Alternative scopes and nested groups.
+   */
+  any(...requirements: IntegrationScopeRequirement[]): ScopeRequirementGroup {
+    return { requirements: [...new Set(requirements)], type: "or" }
+  },
+}
+
+/** One connection method accepted by an integration account requirement. */
+export interface IntegrationAccountConnectionOption {
+  connectionId?: string
+  requiredScopes: readonly IntegrationScopeRequirement[]
+}
+
+/** One normalized integration account requirement. */
+export interface IntegrationAccountRequirement<
+  TServiceId extends string = string,
+> {
+  connectionOptions: readonly IntegrationAccountConnectionOption[]
+  serviceId: TServiceId
+}
+
+/** Runtime-neutral metadata for one public trigger type. */
+export interface TriggerDefinition<
+  TType extends string = string,
+  TServiceId extends string = string,
+> {
+  account?: IntegrationAccountRequirement<TServiceId>
+  description?: string
+
+  /** Adds configuration-specific details to this trigger's presentation. */
+  getDetails?(context: TriggerPresentationContext): TriggerPresentationDetail[]
+
+  /**
+   * Overrides the connected service icon.
+   *
+   * Omit this from account-backed triggers to inherit their service icon.
+   */
+  icon?: string
+
+  /**
+   * Overrides the display name inferred from `type`.
+   *
+   * Omit this unless custom copy adds value beyond the inferred name.
+   * `triggerCatalog` and `getTriggerDefinition` always expose a resolved name.
+   */
+  name?: string
+  type: TType
+}
+
+/** Runtime-neutral context used to describe one configured trigger. */
+export interface TriggerPresentationContext {
+  appOrigin: string
+  automationId: string
+  config: unknown
+  hookSlot: number
+  projectId: string
+}
+
+/** One user-facing property of a configured trigger. */
+export interface TriggerPresentationDetail {
+  copyable?: boolean
+  label: string
+  value: string
+}
+
+/** Client-safe presentation of one configured trigger. */
+export interface TriggerPresentation {
+  details: TriggerPresentationDetail[]
+  name: string
+  type: string
+}
+
+/**
+ * Preserves the literal IDs and connection shapes in one shared definition.
+ *
+ * @param service - Complete runtime-neutral service definition.
+ * @throws When the service or a form connection is empty or IDs repeat.
+ */
+export function defineIntegrationService<
+  const TService extends IntegrationServiceDefinition,
+>(service: TService) {
+  if (service.connectionMethods.length === 0) {
+    throw new Error(
+      `Integration service has no connection methods: ${service.id}`,
+    )
+  }
+  const emptyFormConnection = service.connectionMethods.find(
+    (connection) =>
+      connection.type === "form" && connection.fields.length === 0,
+  )
+  if (emptyFormConnection) {
+    throw new Error(
+      `Integration service ${service.id} has no fields for form connection: ${emptyFormConnection.id}`,
+    )
+  }
+  const duplicateConnectionId = service.connectionMethods.find(
+    (connection, index) =>
+      service.connectionMethods.findIndex(({ id }) => id === connection.id) !==
+      index,
+  )?.id
+  if (duplicateConnectionId) {
+    throw new Error(
+      `Integration service ${service.id} has duplicate connection ID: ${duplicateConnectionId}`,
+    )
+  }
+  if (
+    service.preferredConnectionMethodId &&
+    !service.connectionMethods.some(
+      ({ id }) => id === service.preferredConnectionMethodId,
+    )
+  ) {
+    throw new Error(
+      `Integration service ${service.id} has an unknown preferred connection method: ${service.preferredConnectionMethodId}`,
+    )
+  }
+
+  return service
+}
+
+/**
+ * Validates and preserves one complete compile-time service catalog.
+ *
+ * @param services - Shared integration service definitions.
+ * @throws When multiple services use the same ID.
+ */
+export function defineIntegrationCatalog<
+  const TCatalog extends readonly IntegrationServiceDefinition[],
+>(services: TCatalog) {
+  const duplicateServiceId = services.find(
+    (service, index) =>
+      services.findIndex(({ id }) => id === service.id) !== index,
+  )?.id
+  if (duplicateServiceId) {
+    throw new Error(`Duplicate integration service ID: ${duplicateServiceId}`)
+  }
+
+  return services
+}