@automate.ax/catalog 0.55.0

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+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 declare const scope: {
+    /**
+     * Requires every scope or nested group.
+     *
+     * @param requirements - Required scopes and nested groups.
+     */
+    and(...requirements: IntegrationScopeRequirement[]): ScopeRequirementGroup;
+    /**
+     * 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;
+};
+/** 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 declare function defineIntegrationService<const TService extends IntegrationServiceDefinition>(service: TService): TService;
+/**
+ * Validates and preserves one complete compile-time service catalog.
+ *
+ * @param services - Shared integration service definitions.
+ * @throws When multiple services use the same ID.
+ */
+export declare function defineIntegrationCatalog<const TCatalog extends readonly IntegrationServiceDefinition[]>(services: TCatalog): TCatalog;
+export {};

package/dist/types.js

@@ -0,0 +1,59 @@
+/** 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) {
+        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) {
+        return { requirements: [...new Set(requirements)], type: "or" };
+    },
+};
+/**
+ * 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(service) {
+    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(services) {
+    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;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@automate.ax/catalog",
+  "version": "0.55.0",
+  "description": "Shared integration service and trigger definitions for Automate.ax.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zachsents/automate.ax.git",
+    "directory": "packages/catalog"
+  },
+  "homepage": "https://automate.ax",
+  "bugs": {
+    "url": "https://github.com/zachsents/automate.ax/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "zshy": {
+    "exports": {
+      ".": "./src/index.ts"
+    },
+    "cjs": false,
+    "conditions": {
+      "bun": "src"
+    }
+  },
+  "devDependencies": {
+    "@internal/config": "0.0.0",
+    "@types/bun": "latest",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@zachsents/oxlint-config": "^0.4.1",
+    "concurrently": "^10.0.4",
+    "eslint": "^9.39.5",
+    "oxlint": "^1.76.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "zshy": "^0.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "concurrently --success all --kill-others-on-fail \"oxlint --type-aware\" \"bun --bun eslint .\"",
+    "lint:fix": "concurrently --success all --kill-others-on-fail \"oxlint --type-aware --fix --fix-suggestions\" \"bun --bun eslint . --fix\"",
+    "check": "bun run typecheck && bun run lint",
+    "test": "bun test",
+    "build": "zshy",
+    "prepublishOnly": "bun run check && bun run test && bun run build"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,403 @@
+import { defineIntegrationCatalog, defineIntegrationService } from "./types"
+import type { IntegrationServiceDefinition } from "./types"
+
+const API_KEY_FIELD = {
+  input: "password",
+  label: "API key",
+  name: "apiKey",
+  required: true,
+} as const
+
+export const airtableService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect an Airtable account.",
+  id: "airtable",
+  name: "Airtable",
+})
+
+export const anthropicService = defineApiKeyService({
+  description: "Connect an Anthropic API key.",
+  id: "anthropic",
+  name: "Anthropic",
+  placeholder: "sk-ant-...",
+})
+
+export const apolloService = defineIntegrationService({
+  connectionMethods: [
+    { id: "oauth", name: "OAuth", type: "redirect" },
+    {
+      fields: [{ ...API_KEY_FIELD, placeholder: "Apollo API key" }],
+      id: "api-key",
+      name: "API key",
+      type: "form",
+    },
+  ],
+  description: "Connect an Apollo account with OAuth or an API key.",
+  id: "apollo",
+  name: "Apollo",
+  preferredConnectionMethodId: "oauth",
+})
+
+export const asanaService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect an Asana account.",
+  id: "asana",
+  name: "Asana",
+})
+
+export const brevoService = defineApiKeyService({
+  description: "Connect a Brevo API key.",
+  id: "brevo",
+  name: "Brevo",
+  placeholder: "xkeysib-...",
+})
+
+export const cerebrasService = defineApiKeyService({
+  description: "Connect a Cerebras API key.",
+  id: "cerebras",
+  name: "Cerebras",
+})
+
+export const cloudflareService = defineIntegrationService({
+  connectionMethods: [
+    { id: "oauth", name: "OAuth", type: "redirect" },
+    {
+      fields: [
+        {
+          input: "password",
+          label: "API token",
+          name: "apiKey",
+          placeholder: "Cloudflare API token",
+          required: true,
+        },
+      ],
+      id: "api-token",
+      name: "API token",
+      type: "form",
+    },
+  ],
+  description: "Connect a Cloudflare account with OAuth or an API token.",
+  id: "cloudflare",
+  name: "Cloudflare",
+  preferredConnectionMethodId: "oauth",
+})
+
+export const cohereService = defineApiKeyService({
+  description: "Connect a Cohere API key.",
+  id: "cohere",
+  name: "Cohere",
+})
+
+export const deepinfraService = defineApiKeyService({
+  description: "Connect a DeepInfra API key.",
+  id: "deepinfra",
+  name: "DeepInfra",
+})
+
+export const deepseekService = defineApiKeyService({
+  description: "Connect a DeepSeek API key.",
+  id: "deepseek",
+  name: "DeepSeek",
+})
+
+export const firecrawlService = defineApiKeyService({
+  description: "Connect a Firecrawl API key.",
+  id: "firecrawl",
+  name: "Firecrawl",
+  placeholder: "fc-...",
+})
+
+export const fireworksService = defineApiKeyService({
+  description: "Connect a Fireworks AI API key.",
+  id: "fireworks",
+  name: "Fireworks AI",
+})
+
+export const githubService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "GitHub App", type: "redirect" }],
+  description: "Install Automate.ax on a GitHub account or organization.",
+  id: "github",
+  name: "GitHub",
+})
+
+export const googleService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect a Google account.",
+  id: "google",
+  name: "Google",
+})
+
+export const googleGenaiService = defineApiKeyService({
+  description: "Connect a Google AI Studio API key.",
+  id: "google-genai",
+  name: "Google Generative AI",
+  placeholder: "AIza...",
+})
+
+export const groqService = defineApiKeyService({
+  description: "Connect a Groq API key.",
+  id: "groq",
+  name: "Groq",
+})
+
+export const huggingfaceService = defineApiKeyService({
+  description: "Connect a Hugging Face access token.",
+  id: "huggingface",
+  name: "Hugging Face",
+  placeholder: "hf_...",
+})
+
+export const linearService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect a Linear workspace.",
+  id: "linear",
+  name: "Linear",
+})
+
+export const microsoftService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect a Microsoft account.",
+  id: "microsoft",
+  name: "Microsoft",
+})
+
+export const millionverifierService = defineApiKeyService({
+  description: "Connect a Million Verifier API key.",
+  id: "millionverifier",
+  name: "Million Verifier",
+  placeholder: "Million Verifier API key",
+})
+
+export const mistralService = defineApiKeyService({
+  description: "Connect a Mistral AI API key.",
+  id: "mistral",
+  name: "Mistral AI",
+})
+
+export const openaiService = defineApiKeyService({
+  description: "Connect an OpenAI API key.",
+  id: "openai",
+  name: "OpenAI",
+  placeholder: "sk-...",
+})
+
+export const openrouterService = defineApiKeyService({
+  description: "Connect an OpenRouter API key.",
+  id: "openrouter",
+  name: "OpenRouter",
+  placeholder: "sk-or-...",
+})
+
+export const perplexityService = defineApiKeyService({
+  description: "Connect a Perplexity API key.",
+  id: "perplexity",
+  name: "Perplexity",
+})
+
+export const postgresService = defineIntegrationService({
+  connectionMethods: [
+    {
+      fields: [
+        {
+          description: "A postgresql:// connection string.",
+          input: "password",
+          label: "Connection string",
+          name: "connectionString",
+          placeholder:
+            "postgresql://user:password@host:5432/database?sslmode=require",
+          required: true,
+        },
+      ],
+      id: "default",
+      name: "Credentials",
+      type: "form",
+    },
+  ],
+  description: "Connect a PostgreSQL database.",
+  id: "postgres",
+  name: "PostgreSQL",
+})
+
+export const resendService = defineIntegrationService({
+  connectionMethods: [
+    { id: "oauth", name: "OAuth", type: "redirect" },
+    {
+      fields: [{ ...API_KEY_FIELD, placeholder: "re_..." }],
+      id: "api-key",
+      name: "API key",
+      type: "form",
+    },
+  ],
+  description: "Connect a Resend account with OAuth or an API key.",
+  id: "resend",
+  name: "Resend",
+  preferredConnectionMethodId: "oauth",
+})
+
+export const scrapflyService = defineApiKeyService({
+  description: "Connect a Scrapfly API key.",
+  id: "scrapfly",
+  name: "Scrapfly",
+  placeholder: "scp-live-...",
+})
+
+export const slackService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Install the Automate.ax bot in a Slack workspace.",
+  id: "slack",
+  name: "Slack",
+})
+
+export const tidycalService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect a TidyCal account.",
+  id: "tidycal",
+  name: "TidyCal",
+})
+
+export const togetheraiService = defineApiKeyService({
+  description: "Connect a Together AI API key.",
+  id: "togetherai",
+  name: "Together AI",
+})
+
+export const trelloService = defineIntegrationService({
+  connectionMethods: [{ id: "default", name: "OAuth", type: "redirect" }],
+  description: "Connect a Trello account.",
+  id: "trello",
+  name: "Trello",
+})
+
+export const vercelAiGatewayService = defineApiKeyService({
+  description: "Connect a Vercel AI Gateway API key.",
+  icon: "vercel",
+  id: "vercel-ai-gateway",
+  name: "Vercel AI Gateway",
+})
+
+export const vercelService = defineIntegrationService({
+  connectionMethods: [
+    { id: "oauth", name: "OAuth", type: "redirect" },
+    {
+      fields: [
+        {
+          input: "password",
+          label: "Access token",
+          name: "apiKey",
+          placeholder: "Vercel access token",
+          required: true,
+        },
+      ],
+      id: "access-token",
+      name: "Access token",
+      type: "form",
+    },
+  ],
+  description: "Connect a Vercel account with OAuth or an access token.",
+  id: "vercel",
+  name: "Vercel",
+  preferredConnectionMethodId: "oauth",
+})
+
+export const whatsappService = defineIntegrationService({
+  connectionMethods: [
+    { id: "embedded-signup", name: "Embedded Signup", type: "redirect" },
+  ],
+  description: "Connect a WhatsApp Business Platform phone number.",
+  id: "whatsapp",
+  name: "WhatsApp",
+})
+
+export const xaiService = defineApiKeyService({
+  description: "Connect an xAI API key.",
+  id: "xai",
+  name: "xAI",
+  placeholder: "xai-...",
+})
+
+export const integrationCatalog = defineIntegrationCatalog([
+  airtableService,
+  anthropicService,
+  apolloService,
+  asanaService,
+  brevoService,
+  cerebrasService,
+  cloudflareService,
+  cohereService,
+  deepinfraService,
+  deepseekService,
+  firecrawlService,
+  fireworksService,
+  githubService,
+  googleService,
+  googleGenaiService,
+  groqService,
+  huggingfaceService,
+  linearService,
+  microsoftService,
+  millionverifierService,
+  mistralService,
+  openaiService,
+  openrouterService,
+  perplexityService,
+  postgresService,
+  resendService,
+  scrapflyService,
+  slackService,
+  tidycalService,
+  togetheraiService,
+  trelloService,
+  vercelAiGatewayService,
+  vercelService,
+  whatsappService,
+  xaiService,
+])
+
+export type IntegrationServiceId = (typeof integrationCatalog)[number]["id"]
+
+/**
+ * Looks up one known integration service by its stable ID.
+ *
+ * @param id - Stable integration service ID.
+ */
+export function getIntegrationService(
+  id: string,
+): IntegrationServiceDefinition | undefined {
+  return integrationCatalog.find((service) => service.id === id)
+}
+
+interface ApiKeyServiceDefinition {
+  description: string
+  icon?: string
+  name: string
+  placeholder?: string
+}
+
+/**
+ * Defines one service backed by a conventional API-key credential form.
+ *
+ * @param service - API-key service identity and credential placeholder.
+ */
+function defineApiKeyService<const TId extends string>(
+  service: ApiKeyServiceDefinition & { id: TId },
+) {
+  return defineIntegrationService({
+    connectionMethods: [
+      {
+        fields: [
+          {
+            ...API_KEY_FIELD,
+            placeholder: service.placeholder ?? "API key",
+          },
+        ],
+        id: "default",
+        name: "API key",
+        type: "form",
+      },
+    ],
+    description: service.description,
+    ...(service.icon ? { icon: service.icon } : {}),
+    id: service.id,
+    name: service.name,
+  })
+}