SDK Reference

// Definition helpers (all define* functions)
import {
  defineExtension, defineToolkit, defineTool, defineBlock, defineTrigger,
  defineModels, defineWebSearch, defineWebhooks, defineDiscovery,
} from "@scrydon/sdk-authoring/extensions/define";

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

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

// Manifest types (for advanced use cases)
import { CodeManifestSchema, type CodeManifest } from "@scrydon/sdk-authoring/extensions/manifest";

interface ExtensionInput {
  /** 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 logo as a string */
  logo: string;
  /** Links shown on the extension's page */
  links?: {
    website?: string;
    docs?: string;
    releaseNotes?: string;
    support?: 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";
  /** Minimum requested isolation. Platform and organization floors may only strengthen it. */
  isolation?: "memory" | "microvm";
  /** Public HTTPS hosts that tool code may contact — exact, or `*.` wildcards. */
  egress?: {
    httpsHosts: string[];
  };
  /** Platform operations your tools need beyond their own code (see "Platform permissions") */
  platformPermissions?: readonly ExtensionPlatformPermission[];
  /** Authentication configuration */
  auth?: AuthConfig;
  /** Admin-configurable fields (e.g. base URL for self-hosted services) */
  configFields?: ConfigFieldInput[];
  /** Extension-level secrets (resolved per-invocation via Dapr Secret Store) */
  secrets?: SecretInput[];
  /** What this extension provides — at least one toolkit, model family or content kind */
  provides: {
    toolkits?: ToolkitDefinition[];
    models?: ModelFamilyDefinition[];
  };
  /** Wire protocol IDs this extension makes available to orgs that enable it */
  wireProtocols?: string[];
}

export default defineExtension({
  // ...
  egress: {
    httpsHosts: ["api.acme.example", "uploads.acme.example"],
  },
});

export default defineExtension({
  // ...
  egress: {
    // Covers acme.my.acme-crm.example and acme--dev.sandbox.my.acme-crm.example
    httpsHosts: ["*.my.acme-crm.example"],
  },
});

import { EXTENSION_PLATFORM_PERMISSIONS } from "@scrydon/sdk-authoring/extensions/types";

export default defineExtension({
  id: "acme",
  // …
  platformPermissions: [EXTENSION_PLATFORM_PERMISSIONS.CORTEX_MESSAGES_SEND],
});

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,
  },
],

export default defineExtension({
  id: "home-assistant",
  name: "Home Assistant",
  version: "1.0.0",
  logo: "./assets/icon.svg",
  configFields: [
    { key: "baseUrl", label: "Home Assistant URL", type: "url", purpose: "endpoint", required: true },
  ],
  auth: {
    credentials: {
      token: { type: "apiKey", label: "Long-lived access token", identityScope: "application" },
    },
    default: "token",
  },
  provides: { dataSources: [homeAssistantStates] }, // reads endpointRef "baseUrl", authRef "token"
});

export default defineExtension({
  // ...
  configFields: [
    { key: "baseUrl", label: "Server URL", type: "url", purpose: "endpoint", required: true },
  ],
  auth: { credentials: { none: { type: "none" } }, default: "none" },
  provides: { dataSources: [publicFeed] }, // reads endpointRef "baseUrl", no authRef
});

interface ToolkitInput {
  /** Unique provided-item ID within the extension */
  id: string;
  /** Display name */
  name: string;
  /** Short description */
  description?: string;
  /** Inline SVG string (falls back to the extension's logo if omitted) */
  logo?: string;
  /** Which credential from auth.credentials this toolkit uses */
  credentialRef?: string;
  /** OAuth scopes required by this toolkit */
  credentialScopes?: string[];
  /** Executable tools */
  tools?: ToolDefinition[];
  /** Triggers — rendered in the editor's "Triggers" section */
  triggers?: TriggerDefinition[];
  /** Main toolkit block on the canvas (omit for trigger-only toolkits) */
  block?: BlockDefinition;
  webhooks?: WebhookCapability;
  discovery?: DiscoveryCapability;
  webSearch?: WebSearchCapability;
  /** Resource catalog; actions opt into exact resources separately */
  resources?: Array<{
    resourceType: string;
    displayName: string;
    description?: string;
    allowMultiple?: boolean;
  }>;
  /** 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[];
  };
}

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 defineExtension({
  id: "acme",
  // ...
  provides: {
    toolkits: [
      defineToolkit({
        id: "acme-crm",
        name: "Acme CRM",
        tools: [listContacts, createContact],
        block: crmBlock,
        triggers: [],
      }),
      defineToolkit({
        id: "acme-email",
        name: "Acme Email",
        tools: [sendEmail, listInbox],
        block: emailBlock,
        triggers: [],
      }),
    ],
  },
});

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>;
  /** Exact product resources authorized before this action dispatches */
  resourceAuthorization?: Array<{
    required?: boolean;
    oneOf: Array<{
      resourceType: string;
      source: { kind: "input"; key: string } | { kind: "binding" };
    }>;
  }>;
  /** Platform SDK operations this tool calls, e.g. "action.sms.send" */
  platformOperations?: PlatformDescriptorKey[];
  /** 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";
}

export const sendSms = defineTool({
  id: "send",
  name: "Send SMS",
  version: "1.0.0",
  platformOperations: ["action.sms.send"],
  // …
});

import { defineTool, TOOL_EFFECTS } from "@scrydon/sdk-authoring/extensions/define";

export const listMessages = defineTool({
  id: "list-messages",
  name: "List messages",
  version: "1.0.0",
  effect: TOOL_EFFECTS.READ,
  // …
});

import { requireOAuthToken } from "@scrydon/sdk-authoring/extensions/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/extensions/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 Extension 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;
  /** Stable machine-readable error code */
  error?: string;
  /** Human-readable failure explanation; preferred over error for display */
  message?: 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;
  /** Sidebar section: "integration" for an extension's toolkit block ("trigger" is set by defineTrigger, "core" is built-in) */
  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[] };
}

const listRecords = defineTool({
  // ...
  output: z.object({ records: z.array(z.record(z.string(), z.unknown())), nextLink: z.string().optional() }),
});

defineBlock({
  // ...
  outputs: {
    records: { type: "json", description: "Rows returned by List Records" },
    nextLink: { type: "string", description: "Link to the next page, when there is one" },
    error: { type: "string", description: "Error message when the operation failed" },
  },
});

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;
  /** Generate a fresh value once when each new block is created */
  generatedDefault?: "uuid";
  /**
   * For `type: "code"` fields only: what kind of content this field holds
   * (e.g. `"json-object"`, `"javascript-function-body"`, `"system-prompt"`).
   * Drives both the editor's default placeholder and the AI wand's prompt.
   */
  generationType?:
    | "javascript-function-body"
    | "typescript-function-body"
    | "json-schema"
    | "json-object"
    | "system-prompt"
    | "custom-tool-schema"
    | "sql-query"
    | "postgrest"
    | "mongodb-filter"
    | "mongodb-pipeline"
    | "mongodb-sort"
    | "mongodb-documents"
    | "mongodb-update"
    | "neo4j-cypher"
    | "neo4j-parameters";
  /** Merge this field's JSON object into the tool input (see below) */
  spreadIntoToolInput?: boolean;
  /** Send this field as a tool input of another name (see below) */
  canonicalParamId?: string;
  /** 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;
}

{
  id: "params",
  title: "Operation Parameters (JSON)",
  type: "code",
  generationType: "json-object",
  placeholder: '{ "key": "value" }',
}

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"],
    toolSelector: {
      param: "operation",
      map: {
        create: "acme_create",
        read: "acme_read",
        update: "acme_update",
        delete: "acme_delete",
      },
      default: "acme_read",
    },
  },
});

defineBlock({
  // ...
  subBlocks: [
    { id: "operation", title: "Operation", type: "dropdown", options: [/* ... */] },
    { id: "owner", title: "Repository Owner", type: "short-input" },
    {
      id: "params",
      title: "Operation Parameters (JSON)",
      type: "code",
      placeholder: '{ "title": "...", "body": "..." }',
      spreadIntoToolInput: true,
    },
  ],
});

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 TriggerInput {
  /** 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 defineExtension({
  id: "acme",
  name: "Acme",
  version: "1.0.0",
  logo: acmeIcon,
  auth: { credentials: { apiKey: { type: "apiKey", label: "API Key", identityScope: "application" } }, 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,
    },
  ],
  provides: { toolkits: [/* ... */] },
});

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 extension requires this secret to function */
  required: boolean;
}

extension:{orgId}:{extensionId}:{key}

extension:org_abc123:acme:WEBHOOK_SIGNING_SECRET

import { defineTool } from "@scrydon/sdk-authoring/extensions/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 response = await fetch("https://api.acme.example/webhooks/verify", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-acme-signing-secret": signingSecret,
      },
      body: JSON.stringify(input),
    });
    return { success: true, output: { valid: response.ok } };
  },
});

# Build an archive
sdk-authoring extension build [--entry src/index.ts] [--outDir dist]

# Test an archive
sdk-authoring extension test [--level static|sandbox|live] [--tool <id>]

my-vendor-1.0.0.archive.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 {
  defineModels,
  defineWebSearch,
  defineWebhooks,
  defineDiscovery,
} from "@scrydon/sdk-authoring/extensions/define";

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

import type {
  SttSession,
  SttSessionContext,
  SttStreamingSessionRequest,
} from "@scrydon/sdk-authoring/extensions/capabilities/stt-streaming";

// Signature of runtime.openStreamingSession:
type OpenSpeechSession = (
  request: SttStreamingSessionRequest,
  context: SttSessionContext,
) => Promise<SttSession>;