SDK Reference

// Definition helpers (all define* functions)
import {
  defineVendor, defineProduct, defineTool, defineBlock, defineTriggerBlock,
  defineCapabilityLLM, defineCapabilitySTT, defineCapabilityTTS,
  defineCapabilityEmbedding, defineCapabilityVideo, defineCapabilityOCR,
  defineCapabilityWebhook, defineCapabilityDiscovery,
} from "@scrydon/sdk-authoring/integrations/define";

// Runtime types (used in execute() signatures)
import type {
  PureContext, PureContextAuth, ToolResponse, ExecutorResult,
  RealtimeSession, RealtimeMessage,
} from "@scrydon/sdk-authoring/integrations/context";

// Credential narrowing helpers (throw CredentialKindError on kind mismatch)
import {
  requireOAuthToken, requireOAuth,
  requireApiKey, requireBasicAuth, requireBotToken,
} from "@scrydon/sdk-authoring/integrations/context";

// Manifest types (for advanced use cases)
import type { ManifestSchema } from "@scrydon/sdk-authoring/integrations/manifest";

interface VendorInput {
  /** Unique vendor ID — lowercase alphanumeric + hyphens, starts with letter */
  id: string;
  /** Display name */
  name: string;
  /** Semantic version (e.g. "1.0.0") */
  version: string;
  /** Short description */
  description?: string;
  /** Hex brand color (e.g. "#FF6B35") */
  color?: string;
  /** SVG icon as a string */
  icon: string;
  /** Vendor website URL */
  website?: string;
  /** Documentation URL */
  docsUrl?: string;
  /** Categories (e.g. ["tools"], ["llm"], ["database"]) */
  categories?: string[];
  /** Whether this vendor is enabled by default for new orgs */
  defaultEnabled?: boolean;
  /** Whether this vendor supports system-mode (client_credentials) */
  supportsSystemMode?: boolean;
  /** Whether this vendor requires external network connectivity */
  connectivity?: "cloud" | "local" | "hybrid";
  /** Authentication configuration */
  auth: AuthConfig;
  /** Admin-configurable fields (e.g. base URL for self-hosted services) */
  configFields?: ConfigFieldInput[];
  /** Vendor-level secrets (resolved per-invocation via Dapr Secret Store) */
  secrets?: SecretInput[];
  /** One or more products */
  products: ProductDefinition[];
  /** Optional protocol definitions */
  protocols?: ProtocolDefinition[];
  /** LLM provider configuration (for AI model vendors) */
  llm?: VendorLLMDef;
}

auth: {
  credentials: {
    oauth: { type: "oauth", /* ... */ },
    apiKey: { type: "apiKey", /* ... */ },
  },
  default: "oauth", // Which one to show first
}

configFields: [
  {
    key: "baseUrl",
    label: "Base URL",
    placeholder: "https://your-instance.example.com",
    description: "The base URL of your self-hosted instance",
    required: true,
    type: "url",
  },
],

secrets: [
  {
    key: "WEBHOOK_SIGNING_SECRET",
    label: "Webhook Signing Secret",
    description: "Used to verify incoming webhook payloads",
    required: true,
  },
],

interface ProductInput {
  /** Unique product ID within the vendor */
  id: string;
  /** Display name */
  name: string;
  /** Short description */
  description?: string;
  /** SVG icon as string (falls back to vendor icon if omitted) */
  icon?: string;
  /** Which credential from auth.credentials this product uses */
  credentialRef?: string;
  /** OAuth scopes required by this product */
  credentialScopes?: string[];
  /** Runtime capabilities */
  capabilities: {
    tools?: ToolDefinition[];
    triggers?: TriggerDefinition[];
    runtimes?: {
      llm?: LLMCapability;
      stt?: STTCapability;
      tts?: TTSCapability;
      embedding?: EmbeddingCapability;
      video?: VideoCapability;
      ocr?: OCRCapability;
    };
    webhooks?: WebhookCapability;
    discovery?: DiscoveryCapability;
  };
  /** The block definition for the workflow editor */
  block: BlockDefinition;
  /** NPM package dependencies (for risk assessment at upload time) */
  dependencies?: Array<{
    type: "npm";
    package: string;
    version: string;
    reason?: string;
  }>;

  /** System-mode (client_credentials) configuration */
  systemMode?: {
    supported: boolean;
    permissions?: string[];
    resources?: Array<{
      resourceType: string;
      displayName: string;
      description?: string;
      required: boolean;
      allowMultiple?: boolean;
    }>;
  };
}

auth: {
  credentials: {
    oauth: {
      type: "oauth",
      label: "Microsoft Account",
      authorizationUrl: "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize",
      tokenUrl: "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
      requiredConfig: ["tenantId"],
      supportsClientCredentials: true,
      clientCredentialScopes: ["https://graph.microsoft.com/.default"],
      extensions: {
        systemConsent: {
          kind: "redirect-template",
          urlTemplate: "https://login.microsoftonline.com/{tenantId}/adminconsent",
          params: {
            client_id: "{clientId}",
            redirect_uri: "{redirectUri}",
            scope: "{scope}",
            state: "{state}",
          },
          requiredConfig: ["tenantId"],
          callback: {
            successParam: "admin_consent",
            tenantParam: "tenant",
          },
        },
      },
    },
  },
}

extensions: {
  systemConsent: {
    kind: "handler",
    handlerRef: "microsoft.systemConsent.buildUrl",
    callback: {
      handlerRef: "microsoft.systemConsent.callback",
    },
  },
}

type SystemConsentBuildUrlInput = {
  clientId: string;
  redirectUri: string;
  state?: string;
  scopes: string[];
  providerConfig: Record<string, string | undefined>;
};

export async function buildUrl(input: SystemConsentBuildUrlInput): Promise<string> {
  const tenantId = input.providerConfig.tenantId;
  if (!tenantId) {
    throw new Error("Microsoft admin consent requires tenantId");
  }

  const url = new URL(`https://login.microsoftonline.com/${tenantId}/adminconsent`);
  url.searchParams.set("client_id", input.clientId);
  url.searchParams.set("redirect_uri", input.redirectUri);
  url.searchParams.set("scope", input.scopes.join(" "));

  if (input.state) {
    url.searchParams.set("state", input.state);
  }

  return url.toString();
}

type SystemConsentCallbackInput = {
  query: Record<string, string | undefined>;
  providerConfig: Record<string, string | undefined>;
};

export async function callback(input: SystemConsentCallbackInput) {
  return {
    approved: input.query.admin_consent === "True",
    tenantId: input.query.tenant,
  };
}

export default defineVendor({
  id: "acme",
  // ...
  products: [
    defineProduct({
      id: "acme-crm",
      name: "Acme CRM",
      block: crmBlock,
      capabilities: { tools: [listContacts, createContact] },
    }),
    defineProduct({
      id: "acme-email",
      name: "Acme Email",
      block: emailBlock,
      capabilities: { tools: [sendEmail, listInbox] },
    }),
  ],
});

interface ToolInput<TInput, TOutput> {
  /** Unique tool ID — convention: {vendor}:{product}:{action} */
  id: string;
  /** Display name */
  name: string;
  /** Semantic version */
  version: string;
  /** Description shown to users and LLM agents */
  description?: string;
  /** Zod schema for input validation */
  input: z.ZodType<TInput>;
  /** Zod schema for output validation */
  output: z.ZodType<TOutput>;
  /** Parameter metadata — controls visibility in the UI and to LLMs */
  params?: Record<string, ParamDef>;
  /** The function that runs when this tool is invoked */
  execute: (input: TInput, ctx: PureContext) => Promise<ToolResponse<TOutput>>;
}

interface ParamDef {
  type: string;
  required?: boolean;
  description?: string;
  default?: unknown;
  /** Controls where this parameter appears */
  visibility?: "user-only" | "user-or-llm" | "hidden";
}

import { requireOAuthToken } from "@scrydon/sdk-authoring/integrations/context";

async execute(input, ctx) {
  // Use the logger (visible in workflow execution logs)
  ctx.logger.info(`Processing request for org ${ctx.execution.orgId}`);

  // Narrow on ctx.auth.kind before reading credential fields.
  // This example assumes the vendor declares an OAuth credential —
  // requireOAuthToken throws a CredentialKindError if the kind doesn't match.
  const accessToken = requireOAuthToken(ctx.auth);

  // Make authenticated API calls
  const response = await fetch("https://api.example.com/data", {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input),
  });

  if (!response.ok) {
    return {
      success: false,
      output: { error: `API returned ${response.status}` },
      error: `HTTP ${response.status}: ${response.statusText}`,
    };
  }

  const data = await response.json();
  return {
    success: true,
    output: data,
    metadata: { requestId: response.headers.get("x-request-id") },
  };
},

/**
 * Discriminated union of all credential shapes the platform can inject.
 * Always narrow on `kind` before reading credential fields.
 * Import narrowing helpers from @scrydon/sdk-authoring/integrations/context:
 *   requireOAuthToken(auth) → string (accessToken, throws on mismatch)
 *   requireOAuth(auth)      → { accessToken, refreshToken?, tokenType?, expiresAt? }
 *   requireApiKey(auth)     → string (apiKey)
 *   requireBasicAuth(auth)  → { username, password }
 *   requireBotToken(auth)   → string (botToken)
 * Each helper throws a CredentialKindError with an actionable message on mismatch.
 */
type PureContextAuth =
  | { kind: "oauth"; accessToken: string; refreshToken?: string; tokenType?: string; expiresAt?: number }
  | { kind: "apiKey"; apiKey: string }
  | { kind: "basicAuth"; username: string; password: string }
  | { kind: "botToken"; botToken: string }
  | { kind: "none" };

interface PureContext {
  /** Credential resolved by the platform before invocation */
  auth: PureContextAuth;
  /** Execution metadata for logging and correlation */
  execution: {
    executionId: string;      // Unique execution run ID
    workflowId?: string;      // Workflow ID (if running in a workflow)
    nodeId?: string;          // Block node ID in the workflow
    orgId: string;            // Organization ID
    workspaceId?: string;     // Workspace ID
    userId?: string;          // User who triggered the execution
  };
  /** Structured logger — console calls are intercepted in the sandbox */
  logger: {
    info(message: string, ...args: unknown[]): void;
    warn(message: string, ...args: unknown[]): void;
    error(message: string, ...args: unknown[]): void;
    debug(message: string, ...args: unknown[]): void;
  };
  /** Vendor secrets configured by org admin (resolved per-invocation via Dapr Secret Store) */
  secrets: Record<string, string>;
  /** Present when executing via an Integration Profile — contains profile-specific overrides */
  profileConfig?: Record<string, unknown>;
}

interface ToolResponse<T = unknown> {
  /** Whether the tool execution succeeded */
  success: boolean;
  /** The typed output data */
  output: T;
  /** Error message (shown to user if success is false) */
  error?: string;
  /** Optional metadata (logged but not passed to downstream blocks) */
  metadata?: Record<string, unknown>;
}

interface BlockInput {
  /** Unique block type — lowercase with underscores (e.g. "acme_crm") */
  type: string;
  /** Display name in the block palette */
  name: string;
  /** Short description */
  description?: string;
  /** Block category — use "integration" for bundle blocks */
  category: string;
  /** Background color in hex */
  bgColor?: string;
  /** Auth mode: "none", "apiKey", "oauth", "botToken" */
  authMode?: string;
  /** Form fields displayed in the block panel */
  subBlocks?: SubBlockInput[];
  /** Which tools this block can invoke */
  tools?: {
    access: string[];
    config?: {
      /** Dynamic tool selection based on user input */
      tool: (params: Record<string, any>) => string;
      /** Parameter transformation before passing to tool */
      params?: (params: Record<string, any>) => any;
    };
  };
  /** Input connections from upstream blocks */
  inputs?: Record<string, { type: string; description?: string }>;
  /** Output connections to downstream blocks */
  outputs?: Record<string, { type: string; description?: string }>;
  /** Trigger configuration (for trigger blocks) */
  triggers?: { enabled: boolean; available: string[] };
}

interface SubBlockInput {
  /** Unique field ID within the block */
  id: string;
  /** Field label */
  title?: string;
  /** SubBlock type */
  type: string;
  /** Layout: "full" (default) or "half" */
  layout?: "full" | "half";
  /** Whether this field is required */
  required?: boolean;
  /** Placeholder text */
  placeholder?: string;
  /** Mask input as password dots */
  password?: boolean;
  /** Default value */
  defaultValue?: unknown;
  /** Options for dropdown/combobox */
  options?: Array<{ label: string; id: string }>;
  /** Help text shown below the field */
  description?: string;
  /** Conditional visibility based on another field's value */
  condition?: { field: string; value: string };
  /** Whether the field is read-only */
  readOnly?: boolean;
  /** Show a copy-to-clipboard button */
  showCopyButton?: boolean;
  /** Hide this field from the UI */
  hidden?: boolean;
}

defineBlock({
  // ...
  subBlocks: [
    {
      id: "operation",
      title: "Operation",
      type: "dropdown",
      options: [
        { label: "Create", id: "create" },
        { label: "Read", id: "read" },
        { label: "Update", id: "update" },
        { label: "Delete", id: "delete" },
      ],
    },
    // ... other fields
  ],
  tools: {
    access: ["acme_create", "acme_read", "acme_update", "acme_delete"],
    config: {
      tool: (params) => `acme_${params.operation}`,
    },
  },
});

subBlocks: [
  {
    id: "authType",
    title: "Auth Type",
    type: "dropdown",
    options: [
      { label: "API Key", id: "apiKey" },
      { label: "Username/Password", id: "basic" },
    ],
  },
  {
    id: "apiKey",
    title: "API Key",
    type: "short-input",
    password: true,
    condition: { field: "authType", value: "apiKey" },
  },
  {
    id: "username",
    title: "Username",
    type: "short-input",
    condition: { field: "authType", value: "basic" },
  },
  {
    id: "password",
    title: "Password",
    type: "short-input",
    password: true,
    condition: { field: "authType", value: "basic" },
  },
],

interface TriggerBlockInput {
  /** Unique block type */
  type: string;
  /** Display name */
  name: string;
  /** Description */
  description?: string;
  /** Background color in hex */
  bgColor?: string;
  /** Auth mode: "none", "apiKey", "oauth", "botToken" */
  authMode?: string;
  /** Form fields for trigger configuration */
  subBlocks?: SubBlockInput[];
  /** Which tools this trigger block can invoke */
  tools?: {
    access: string[];
    config?: {
      tool?: (params: Record<string, any>) => string;
      params?: (params: Record<string, any>) => any;
    };
  };
  /** Input connections */
  inputs?: Record<string, { type: string; description?: string }>;
  /** Output schema — what data the trigger emits */
  outputs?: Record<string, { type: string; description?: string }>;
  /** Provider identifier */
  provider?: string;
  /** Semantic version */
  version?: string;
  /** Runtime configuration — how events reach the workflow engine */
  runtime?: {
    webhook?: {
      method?: "POST" | "GET" | "PUT" | "DELETE";
      headers?: Record<string, string>;
    };
    polling?: PollingProvider;
  };
}

export default defineVendor({
  id: "acme",
  name: "Acme",
  version: "1.0.0",
  icon: acmeIcon,
  auth: { credentials: { apiKey: { type: "apiKey", label: "API Key" } }, default: "apiKey" },
  secrets: [
    {
      key: "WEBHOOK_SIGNING_SECRET",
      label: "Webhook Signing Secret",
      description: "Used to verify incoming webhook payloads",
      required: true,
    },
    {
      key: "ENCRYPTION_KEY",
      label: "Encryption Key",
      description: "AES key for encrypting sensitive payloads",
      required: false,
    },
  ],
  products: [/* ... */],
});

interface SecretInput {
  /** Unique key within the vendor — must match ^[a-zA-Z0-9_-]+$ */
  key: string;
  /** Human-readable label shown in the admin UI */
  label: string;
  /** Help text describing what this secret is used for */
  description?: string;
  /** Whether the integration requires this secret to function */
  required: boolean;
}

integration:{orgId}:{vendorId}:{key}

integration:org_abc123:acme:WEBHOOK_SIGNING_SECRET

import { defineTool } from "@scrydon/sdk-authoring/integrations/define";
import { z } from "zod";

export const verifyWebhook = defineTool({
  id: "acme:webhooks:verify",
  name: "Verify Webhook",
  version: "1.0.0",
  input: z.object({ payload: z.string(), signature: z.string() }),
  output: z.object({ valid: z.boolean() }),
  async execute(input, ctx) {
    const signingSecret = ctx.secrets["WEBHOOK_SIGNING_SECRET"];
    if (!signingSecret) {
      return { success: false, output: { valid: false }, error: "Webhook signing secret not configured" };
    }

    const valid = verifyHmac(input.payload, input.signature, signingSecret);
    return { success: true, output: { valid } };
  },
});

# Build a bundle
sdk-authoring integrations build [--entry src/index.ts] [--outDir dist]

# Test a bundle
sdk-authoring integrations test [--level static|sandbox|live] [--tool <id>]

my-vendor-1.0.0.bundle.tar.gz
├── manifest.json           # Auto-generated metadata (JSON Schemas, UI defs)
├── dist/
│   └── index.js            # Compiled, minified ESM (all deps inlined via esbuild)
├── meta/
│   ├── sbom.cdx.json       # CycloneDX 1.6 SBOM (auto-generated)
│   └── metafile.json       # esbuild dependency graph
└── assets/                 # Optional icons
    └── icon.svg

import {
  defineCapabilityLLM,
  defineCapabilitySTT,
  defineCapabilityTTS,
  defineCapabilityEmbedding,
  defineCapabilityVideo,
  defineCapabilityOCR,
  defineCapabilityWebhook,
  defineCapabilityDiscovery,
} from "@scrydon/sdk-authoring/integrations/define";

{
  "$schema": "...",              // Optional JSON Schema URL
  "manifestVersion": 1,         // Always 1
  "version": "1.0.0",           // Vendor version (from defineVendor)
  "vendor": { ... },            // Vendor metadata
  "auth": { ... },              // Authentication config
  "products": [ ... ],          // Product definitions
  "protocols": [ ... ],         // Protocol definitions (optional)
  "llm": { ... }                // LLM provider config (optional)
}