@auvexis/fabric-sdk

TypeScript SDK for building external Fabric plugins. By Auvexis.

Install

npm install @auvexis/fabric-sdk

Minimal plugin

import { defineManifest, definePlugin } from "@auvexis/fabric-sdk";

const manifest = defineManifest({
  metadata: {
    id: "my-plugin",
    name: "My Plugin",
    description: "Small external plugin",
    icon: "plug",
    categories: ["Apps"],
    author: "Acme",
    version: "1.0.0",
    repository: "https://github.com/acme/my-plugin",
  },
  methods: {
    ping: {
      metadata: {
        label: "Ping",
        description: "Returns pong",
      },
      parameters: {
        type: "object",
        properties: {},
      },
      responseSchema: {
        type: "object",
      },
    },
  },
});

export default definePlugin({
  id: "my-plugin",
  manifest,
  auth: { type: "none" },
  methods: {
    async ping() {
      return { pong: true };
    },
  },
});

Validate a manifest

import { validateManifest } from "@auvexis/fabric-sdk";

const result = validateManifest(manifest);

if (!result.valid) {
  console.error(result.errors);
}

File contracts

Fabric file values use one canonical envelope. Plugins may accept only Node.js Buffer content or Base64 content:

import {
  defineManifest,
  fileOutput,
  filesInput,
  type FabricBase64File,
  type FabricBufferFile,
} from "@auvexis/fabric-sdk";

const downloaded: FabricBufferFile = {
  name: "report.pdf",
  mimeType: "application/pdf",
  content: Buffer.from("..."),
};

const attachment: FabricBase64File = {
  name: downloaded.name,
  mimeType: downloaded.mimeType,
  content: downloaded.content.toString("base64"),
};

const manifest = defineManifest({
  metadata: {
    id: "file-transfer",
    name: "File Transfer",
    description: "Transfers files to another service.",
    categories: ["Files"],
    author: "Acme",
    version: "1.0.0",
  },
  methods: {
    transfer: {
      metadata: { label: "Transfer", description: "Transfers files." },
      parameters: {
        type: "object",
        properties: {
          attachments: filesInput({ encoding: "base64", label: "Attachments" }),
        },
        required: ["attachments"],
      },
      responseSchema: fileOutput({ encoding: "buffer" }),
      agentTool: {
        enabled: true,
        name: "file_transfer",
        description: "Transfers files to the configured external destination.",
        sideEffect: "write",
        requiresApproval: true,
        timeoutMs: 30000,
      },
    },
  },
});

The canonical fields are name, mimeType, optional size, and content. Streams and custom content field names are not valid plugin-boundary file contracts.

Available helpers:

• fileInput
• filesInput
• fileOutput
• filesOutput

Exports

• defineManifest
• definePlugin
• validateManifest
• manifestSchema
• Fabric plugin, auth, method, trigger and JSON schema types
• Canonical Buffer and Base64 file contracts
• Agent tool manifest metadata

Migration from 1.x to 2.0

Version 2.0 removes the legacy singular metadata.category field.

Before:

{
  "metadata": {
    "category": "Utilities"
  }
}

After:

{
  "metadata": {
    "categories": ["Core"]
  }
}

Valid categories are:

• AI
• Core
• Flow
• Data transformation
• Apps
• Files
• Developer