@fias/arche-sdk

Build plugin arches for the FIAS platform. This SDK provides React hooks, a bridge communication layer, and a CLI scaffolder so you can develop, test, and submit plugins that run inside the FIAS platform.

Quick Start

# Scaffold a new plugin
npx create-fias-plugin my-plugin
cd my-plugin
npm install

# Terminal 1: Start the plugin dev server
npm run dev

# Terminal 2: Start the dev harness (mock mode — free, offline)
npm run dev:mock

# Open http://localhost:3200 in your browser

For real AI testing with live entity invocations (costs credits), click the MOCK badge in the toolbar to switch to live mode. If you haven't saved an API key yet, the harness will prompt you to enter one.

Alternatively, use the CLI:

npx fias-dev login           # Save your API key (one-time)
npm run dev:harness           # Start harness in live mode

When you're ready to submit:

npm run submit               # Builds, validates, packages, and submits for review

Manifest Reference (fias-plugin.json)

Every plugin must include a fias-plugin.json at its root:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A short description of what the plugin does",
  "main": "src/index.tsx",
  "archeType": "tool",
  "tags": ["utility"],
  "pricing": { "model": "free", "currency": "usd" },
  "permissions": ["theme:read", "storage:sandbox"],
  "sdk": "^1.0.0"
}

| Field | Type | Description | | ------------- | ------------------------------------------------------- | ----------------------------------------------------- | | name | string | Unique plugin identifier (lowercase, hyphens allowed) | | version | string | Semver version of your plugin | | description | string | Short description shown in the marketplace | | main | string | Entry point source file | | archeType | "tool" \| "site" | Category of your plugin | | tags | string[] | Discovery tags for the marketplace | | pricing | { model: "free" \| "fixed" \| "per_use" \| "tiered" } | Pricing model | | permissions | PluginPermission[] | Scopes your plugin requires (see Permissions) | | sdk | string | Required SDK version range |

API Reference

Wrap your app in <FiasProvider> to enable all hooks:

import { FiasProvider } from '@fias/arche-sdk';

function main() {
  return (
    <FiasProvider>
      <App />
    </FiasProvider>
  );
}

useFiasTheme()

Access platform theme tokens for consistent styling. Automatically updates when the user toggles light/dark mode.

• Requires: theme:read
• Returns: FiasTheme | null

import { useFiasTheme } from '@fias/arche-sdk';

function MyComponent() {
  const theme = useFiasTheme();
  if (!theme) return null;

  return (
    <div
      style={{
        color: theme.colors.text,
        backgroundColor: theme.colors.background,
        fontFamily: theme.fonts.body,
        padding: theme.spacing.md,
      }}
    >
      Current mode: {theme.mode}
    </div>
  );
}

FiasTheme shape:

interface FiasTheme {
  colors: {
    primary: string;
    secondary: string;
    background: string;
    surface: string;
    text: string;
    textSecondary: string;
    border: string;
    error: string;
    warning: string;
    success: string;
  };
  spacing: { xs: string; sm: string; md: string; lg: string; xl: string };
  fonts: { body: string; heading: string; mono: string };
  mode: 'light' | 'dark';
}

useFiasUser()

Access the authenticated user's profile.

• Requires: user:profile:read
• Returns: FiasUser | null

import { useFiasUser } from '@fias/arche-sdk';

function Greeting() {
  const user = useFiasUser();
  if (!user) return <span>Loading...</span>;

  return <span>Hello, {user.displayName}!</span>;
}

FiasUser shape:

interface FiasUser {
  userId: string;
  displayName: string;
  avatar: string | null;
}

useFiasStorage()

Read and write files in your plugin's sandboxed storage. Each plugin gets its own isolated namespace.

• Requires: storage:sandbox
• Returns: FiasStorageApi

import { useFiasStorage } from '@fias/arche-sdk';

function NotesEditor() {
  const { readFile, writeFile, listFiles, deleteFile } = useFiasStorage();

  async function saveNote(content: string) {
    await writeFile('notes/draft.txt', content);
  }

  async function loadNotes() {
    const files = await listFiles('notes/');
    // files: ['notes/draft.txt', 'notes/archive.txt']
  }
}

FiasStorageApi shape:

interface FiasStorageApi {
  readFile: (path: string) => Promise<string | null>;
  writeFile: (path: string, content: string) => Promise<void>;
  listFiles: (prefix?: string) => Promise<string[]>;
  deleteFile: (path: string) => Promise<void>;
}

useEntityInvocation()

Invoke platform entities (AI models, tools, etc.) through the bridge.

• Requires: entities:invoke
• Returns: EntityInvocationApi

import { useEntityInvocation } from '@fias/arche-sdk';

function AISummarizer() {
  const { invoke, isLoading, result, error } = useEntityInvocation();

  async function summarize(text: string) {
    const res = await invoke({
      entityId: 'entity_summarizer',
      input: text,
      parameters: { maxLength: 200 },
    });
    console.log(res.output);
  }

  return (
    <div>
      <button onClick={() => summarize('...')} disabled={isLoading}>
        {isLoading ? 'Summarizing...' : 'Summarize'}
      </button>
      {result && <p>{result.output}</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

useFiasNavigation()

Navigate within your plugin's route space and react to navigation changes.

• Requires: No special permission
• Returns: FiasNavigationApi

import { useFiasNavigation } from '@fias/arche-sdk';

function NavBar() {
  const { navigateTo, currentPath } = useFiasNavigation();

  return (
    <nav>
      <button onClick={() => navigateTo('/settings')}>Settings</button>
      <span>Current: {currentPath}</span>
    </nav>
  );
}

fias (imperative utilities)

For operations outside React components:

import { fias } from '@fias/arche-sdk';

// Resize the plugin iframe
fias.resize(800);

// Show a platform toast notification
fias.showToast('Saved successfully!', 'success');
// Variants: 'info' | 'success' | 'warning' | 'error'

Permissions

Declare required permissions in your fias-plugin.json. Users see these before installing.

| Scope | Grants | Used by | | ------------------- | ------------------------------------------------------------- | ----------------------- | | theme:read | Read platform theme tokens (colors, fonts, spacing, mode) | useFiasTheme() | | user:profile:read | Read the current user's profile (userId, displayName, avatar) | useFiasUser() | | storage:sandbox | Read/write files in the plugin's sandboxed storage namespace | useFiasStorage() | | entities:invoke | Invoke platform entities (AI models, tools) | useEntityInvocation() |

Requesting only the permissions you need improves user trust and review speed.

Constraints

• Bundle size: Maximum 5 MB compressed
• No external scripts/stylesheets: All assets must be included in the bundle
• Rate limits: API calls through the bridge are rate-limited per type:
  • entity_invoke: 60/minute
  • storage_write: 120/minute
  • storage_read: 300/minute
  • storage_list: 60/minute
  • storage_delete: 60/minute
• Sandboxing: Plugins run in an iframe with sandbox="allow-scripts allow-forms". No access to the parent page DOM, cookies, or local storage.

Local Development

The recommended way to develop and test plugins is with the @fias/plugin-dev-harness — a standalone local server that provides a production-accurate iframe environment without requiring the full FIAS platform.

Mock Mode (free, offline)

Best for UI development, layout, and styling work:

npm run dev:mock
# Opens http://localhost:3200 with canned AI responses and in-memory storage

Live Mode (real AI, costs credits)

Best for integration testing with real AI models:

npx fias-dev login           # One-time: save your API key
npm run dev:harness           # Connects to FIAS production API

The harness provides:

• An iframe embedding your plugin (same sandbox attributes as production)
• A toolbar with:
  • Clickable MOCK/LIVE badge to toggle between modes
  • DARK/LIGHT theme badge
  • Credit balance (visible in live mode)
  • Theme toggle and reload buttons
• A dev console showing all bridge messages with timestamps

Dev Preview (alternative)

If you have the full FIAS platform running locally, you can also use the built-in dev preview:

http://localhost:3000/a/arche_plugins/dev-preview?url=http://localhost:3100&permissions=theme:read,storage:sandbox

This loads your plugin with a real PluginBridgeHost, auth tokens, and live platform data. The URL must be localhost or https://.

Submission Flow

The easiest way to submit is with the dev harness CLI:

npm run submit
# or: npx fias-dev submit

This automates the full pipeline: build, validate manifest, package, upload to S3, create submission, and poll review status.

Manual submission

If you prefer to submit manually via the API:

1. Build: npm run build to create the production bundle in dist/
2. Validate: npx fias-dev validate to check your manifest
3. Get upload URL: POST /v1/plugins/submissions/upload-url
4. Upload: PUT your .tar.gz to the returned presigned URL
5. Create submission: POST /v1/plugins/submissions with { submissionId, manifest }
6. Track status: GET /v1/plugins/submissions/:submissionId

See docs/api-plugins.md for full API details.

CLI Tools

The @fias/plugin-dev-harness package provides CLI commands for the full development lifecycle:

npx fias-dev                  # Start harness (mock mode)
npx fias-dev --live           # Start harness (live mode, costs credits)
npx fias-dev login            # Save API key to ~/.fias/credentials
npx fias-dev entities         # Browse available entities
npx fias-dev entities --search "summarize"
npx fias-dev validate         # Validate fias-plugin.json
npx fias-dev submit           # Build, package, and submit for review

TypeScript Types

All types are exported for advanced usage:

import type {
  FiasUser,
  FiasTheme,
  FiasStorageApi,
  EntityInvocationApi,
  EntityInvocationParams,
  EntityInvocationResult,
  FiasNavigationApi,
  PluginPermission,
  BridgeMessage,
  BridgeResponse,
  BridgeInitMessage,
} from '@fias/arche-sdk';

Further Reading

• Plugin Creation Guide — Step-by-step tutorial for beginners
• Developer API Reference — Bridge, entities, credits, and validation endpoints
• Plugin API Reference — Submission, review pipeline, and production bridge

License

MIT