Référence SDK

// Helpers de définition (toutes les fonctions define*)
import {
  defineExtension, defineToolkit, defineTool, defineBlock, defineTriggerBlock,
  defineCapabilityLLM, defineCapabilitySTT, defineCapabilityTTS,
  defineCapabilityEmbedding, defineCapabilityVideo, defineCapabilityOCR,
  defineCapabilityWebhook, defineCapabilityDiscovery,
} from "@scrydon/sdk-authoring/extensions/authoring/define";

// Types de runtime (utilisés dans les signatures execute())
import type {
  PureContext, PureContextAuth, ToolResponse, ExecutorResult,
  RealtimeSession, RealtimeMessage,
} from "@scrydon/sdk-authoring/extensions/authoring/context";

// Helpers de filtrage des credentials (lèvent une CredentialKindError en cas de type incompatible)
import {
  requireOAuthToken, requireOAuth,
  requireApiKey, requireBasicAuth, requireBotToken,
} from "@scrydon/sdk-authoring/extensions/authoring/context";

// Types du manifeste (pour les cas d'usage avancés)
import type { ManifestSchema } from "@scrydon/sdk-authoring/extensions/authoring/manifest";

interface VendorInput {
  /** Identifiant unique du fournisseur — alphanumérique minuscule + tirets, commence par une lettre */
  id: string;
  /** Nom d'affichage */
  name: string;
  /** Version sémantique (ex. "1.0.0") */
  version: string;
  /** Description courte */
  description?: string;
  /** Couleur de marque en hexadécimal (ex. "#FF6B35") */
  color?: string;
  /** Icône SVG sous forme de chaîne */
  icon: string;
  /** URL du site web du fournisseur */
  website?: string;
  /** URL de la documentation */
  docsUrl?: string;
  /** Catégories (ex. ["tools"], ["llm"], ["database"]) */
  categories?: string[];
  /** Indique si ce fournisseur est activé par défaut pour les nouvelles organisations */
  defaultEnabled?: boolean;
  /** Indique si ce fournisseur prend en charge le mode système (client_credentials) */
  supportsSystemMode?: boolean;
  /** Indique si ce fournisseur nécessite une connectivité réseau externe */
  connectivity?: "cloud" | "local" | "hybrid";
  /** Isolation minimale demandée. Les minimums plateforme et organisation ne peuvent que la renforcer. */
  isolation?: "memory" | "microvm";
  /** Hôtes HTTPS publics que le code d'outil peut contacter — exacts ou wildcards `*.`. */
  toolEgress?: {
    httpsHosts: string[];
  };
  /** Configuration de l'authentification */
  auth: AuthConfig;
  /** Champs configurables par l'administrateur (ex. URL de base pour les services auto-hébergés) */
  configFields?: ConfigFieldInput[];
  /** Secrets au niveau de l'extension (résolus par invocation via le Dapr Secret Store) */
  secrets?: SecretInput[];
  /** Ce que fournit l'extension — au moins un toolkit, une famille de modèles ou un type de contenu */
  provides: {
    toolkits?: ToolkitDefinition[];
    models?: ModelFamilyDefinition[];
  };
  /** Définitions de protocoles optionnelles */
  protocols?: ProtocolDefinition[];
}

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

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

auth: {
  credentials: {
    oauth: { type: "oauth", /* ... */ },
    apiKey: { type: "apiKey", /* ... */ },
  },
  default: "oauth", // Lequel afficher en premier
}

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 ToolkitInput {
  /** Identifiant unique de l'élément fourni au sein de l'extension */
  id: string;
  /** Nom d'affichage */
  name: string;
  /** Description courte */
  description?: string;
  /** SVG en ligne (utilise le logo de l'extension si absent) */
  logo?: string;
  /** Référence au credential d'auth.credentials utilisé par ce toolkit */
  credentialRef?: string;
  /** Scopes OAuth requis par ce toolkit */
  credentialScopes?: string[];
  /** Outils exécutables */
  tools?: ToolDefinition[];
  /** Déclencheurs — affichés dans la section « Déclencheurs » de l'éditeur */
  triggers?: TriggerDefinition[];
  /** Bloc principal du toolkit sur le canevas (absent pour un toolkit sans bloc) */
  block?: BlockDefinition;
  webhooks?: WebhookCapability;
  discovery?: DiscoveryCapability;
  webSearch?: WebSearchCapability;
  /** Catalogue de ressources ; chaque action déclare séparément ses cibles */
  resources?: Array<{
    resourceType: string;
    displayName: string;
    description?: string;
    allowMultiple?: boolean;
  }>;
  /** Dépendances NPM (pour l'évaluation des risques au moment de l'upload) */
  dependencies?: Array<{
    type: "npm";
    package: string;
    version: string;
    reason?: string;
  }>;

  /** Configuration du mode système (client_credentials) */
  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> {
  /** Identifiant unique de l'outil — convention : {vendor}:{product}:{action} */
  id: string;
  /** Nom d'affichage */
  name: string;
  /** Version sémantique */
  version: string;
  /** Description affichée aux utilisateurs et aux agents LLM */
  description?: string;
  /** Schéma Zod pour la validation de l'entrée */
  input: z.ZodType<TInput>;
  /** Schéma Zod pour la validation de la sortie */
  output: z.ZodType<TOutput>;
  /** Métadonnées des paramètres — contrôle la visibilité dans l'interface et auprès des LLM */
  params?: Record<string, ParamDef>;
  /** Ressources exactes du produit autorisées avant l'exécution de l'action */
  resourceAuthorization?: Array<{
    required?: boolean;
    oneOf: Array<{
      resourceType: string;
      source: { kind: "input"; key: string } | { kind: "binding" };
    }>;
  }>;
  /** La fonction exécutée lors de l'invocation de cet outil */
  execute: (input: TInput, ctx: PureContext) => Promise<ToolResponse<TOutput>>;
}

interface ParamDef {
  type: string;
  required?: boolean;
  description?: string;
  default?: unknown;
  /** Contrôle l'endroit où ce paramètre apparaît */
  visibility?: "user-only" | "user-or-llm" | "hidden";
}

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

async execute(input, ctx) {
  // Utiliser le logger (visible dans les journaux d'exécution du workflow)
  ctx.logger.info(`Processing request for org ${ctx.execution.orgId}`);

  // Filtrer sur ctx.auth.kind avant de lire les champs de credential.
  // Cet exemple suppose que le fournisseur déclare un credential OAuth —
  // requireOAuthToken lève une CredentialKindError si le type ne correspond pas.
  const accessToken = requireOAuthToken(ctx.auth);

  // Effectuer des appels API authentifiés
  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") },
  };
},

/**
 * Union discriminée de toutes les formes de credentials que la plateforme peut injecter.
 * Filtrez toujours sur `kind` avant de lire les champs de credential.
 * Importez les helpers de filtrage depuis @scrydon/sdk-authoring/extensions/authoring/context :
 *   requireOAuthToken(auth) → string (accessToken, lève une erreur en cas d'incompatibilité)
 *   requireOAuth(auth)      → { accessToken, refreshToken?, tokenType?, expiresAt? }
 *   requireApiKey(auth)     → string (apiKey)
 *   requireBasicAuth(auth)  → { username, password }
 *   requireBotToken(auth)   → string (botToken)
 * Chaque helper lève une CredentialKindError avec un message actionnable en cas d'incompatibilité.
 */
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 résolu par la plateforme avant l'invocation */
  auth: PureContextAuth;
  /** Métadonnées d'exécution pour la journalisation et la corrélation */
  execution: {
    executionId: string;      // Identifiant unique de l'exécution
    workflowId?: string;      // Identifiant du workflow (si exécuté dans un workflow)
    nodeId?: string;          // Identifiant du nœud de bloc dans le workflow
    orgId: string;            // Identifiant de l'organisation
    workspaceId?: string;     // Identifiant de l'espace de travail
    userId?: string;          // Utilisateur qui a déclenché l'exécution
  };
  /** Logger structuré — les appels console sont interceptés dans le 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;
  };
  /** Secrets du fournisseur configurés par l'administrateur de l'organisation (résolus par invocation via le Dapr Secret Store) */
  secrets: Record<string, string>;
  /** Présent lors de l'exécution via un Profil d'intégration — contient les remplacements spécifiques au profil */
  profileConfig?: Record<string, unknown>;
}

interface ToolResponse<T = unknown> {
  /** Indique si l'exécution de l'outil a réussi */
  success: boolean;
  /** Les données de sortie typées */
  output: T;
  /** Message d'erreur (affiché à l'utilisateur si success est false) */
  error?: string;
  /** Métadonnées optionnelles (journalisées mais non transmises aux blocs en aval) */
  metadata?: Record<string, unknown>;
}

interface BlockInput {
  /** Type de bloc unique — minuscule avec underscores (ex. "acme_crm") */
  type: string;
  /** Nom d'affichage dans la palette de blocs */
  name: string;
  /** Description courte */
  description?: string;
  /** Catégorie du bloc — utiliser "extension" pour les blocs de archive */
  category: string;
  /** Couleur de fond en hexadécimal */
  bgColor?: string;
  /** Mode d'auth : "none", "apiKey", "oauth", "botToken" */
  authMode?: string;
  /** Champs de formulaire affichés dans le panneau du bloc */
  subBlocks?: SubBlockInput[];
  /** Les outils que ce bloc peut invoquer */
  tools?: {
    access: string[];
    config?: {
      /** Sélection dynamique d'outil en fonction de la saisie de l'utilisateur */
      tool: (params: Record<string, any>) => string;
      /** Transformation des paramètres avant transmission à l'outil */
      params?: (params: Record<string, any>) => any;
    };
  };
  /** Connexions d'entrée depuis les blocs en amont */
  inputs?: Record<string, { type: string; description?: string }>;
  /** Connexions de sortie vers les blocs en aval */
  outputs?: Record<string, { type: string; description?: string }>;
  /** Configuration du déclencheur (pour les blocs déclencheurs) */
  triggers?: { enabled: boolean; available: string[] };
}

interface SubBlockInput {
  /** Identifiant unique du champ dans le bloc */
  id: string;
  /** Libellé du champ */
  title?: string;
  /** Type de SubBlock */
  type: string;
  /** Disposition : "full" (par défaut) ou "half" */
  layout?: "full" | "half";
  /** Indique si ce champ est obligatoire */
  required?: boolean;
  /** Texte d'espace réservé */
  placeholder?: string;
  /** Masquer la saisie en points de mot de passe */
  password?: boolean;
  /** Valeur par défaut */
  defaultValue?: unknown;
  /** Générer une nouvelle valeur une fois lors de la création de chaque bloc */
  generatedDefault?: "uuid";
  /** Options pour liste déroulante/combobox */
  options?: Array<{ label: string; id: string }>;
  /** Texte d'aide affiché sous le champ */
  description?: string;
  /** Visibilité conditionnelle basée sur la valeur d'un autre champ */
  condition?: { field: string; value: string };
  /** Indique si le champ est en lecture seule */
  readOnly?: boolean;
  /** Afficher un bouton de copie dans le presse-papiers */
  showCopyButton?: boolean;
  /** Masquer ce champ dans l'interface */
  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" },
      ],
    },
    // ... autres champs
  ],
  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 {
  /** Type de bloc unique */
  type: string;
  /** Nom d'affichage */
  name: string;
  /** Description */
  description?: string;
  /** Couleur de fond en hexadécimal */
  bgColor?: string;
  /** Mode d'auth : "none", "apiKey", "oauth", "botToken" */
  authMode?: string;
  /** Champs de formulaire pour la configuration du déclencheur */
  subBlocks?: SubBlockInput[];
  /** Les outils que ce bloc déclencheur peut invoquer */
  tools?: {
    access: string[];
    config?: {
      tool?: (params: Record<string, any>) => string;
      params?: (params: Record<string, any>) => any;
    };
  };
  /** Connexions d'entrée */
  inputs?: Record<string, { type: string; description?: string }>;
  /** Schéma de sortie — données émises par le déclencheur */
  outputs?: Record<string, { type: string; description?: string }>;
  /** Identifiant du fournisseur */
  provider?: string;
  /** Version sémantique */
  version?: string;
  /** Configuration de runtime — comment les événements atteignent le moteur de workflow */
  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 {
  /** Clé unique au sein du fournisseur — doit correspondre à ^[a-zA-Z0-9_-]+$ */
  key: string;
  /** Libellé lisible affiché dans l'interface d'administration */
  label: string;
  /** Texte d'aide décrivant l'utilisation de ce secret */
  description?: string;
  /** Indique si l'intégration nécessite ce secret pour fonctionner */
  required: boolean;
}

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

extension:org_abc123:acme:WEBHOOK_SIGNING_SECRET

import { defineTool } from "@scrydon/sdk-authoring/extensions/authoring/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 ctx.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 } };
  },
});

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

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

my-vendor-1.0.0.archive.tar.gz
├── manifest.json           # Métadonnées auto-générées (JSON Schemas, définitions UI)
├── dist/
│   └── index.js            # ESM compilé et minifié (toutes les dépendances intégrées via esbuild)
├── meta/
│   ├── sbom.cdx.json       # SBOM CycloneDX 1.6 (auto-généré)
│   └── metafile.json       # Graphe de dépendances esbuild
└── assets/                 # Icônes optionnelles
    └── icon.svg

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

{
  "$schema": "...",              // URL optionnelle du JSON Schema
  "manifestVersion": 1,         // Toujours 1
  "version": "1.0.0",           // Version du fournisseur (issue de defineExtension)
  "vendor": { ... },            // Métadonnées du fournisseur
  "auth": { ... },              // Configuration de l'authentification
  "products": [ ... ],          // Définitions des produits
  "protocols": [ ... ],         // Définitions de protocoles (optionnel)
  "llm": { ... }                // Configuration du fournisseur LLM (optionnel)
}