npm package: @fias/arche-sdk
Description: SDK for building FIAS platform plugin arches
Latest version: 1.6.0

# @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

```bash
# 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:

```bash
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:

```bash
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:

```json
{
  "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:

```tsx
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`

```tsx
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:**

```typescript
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`

```tsx
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:**

```typescript
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`

```tsx
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:**

```typescript
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`

```tsx
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`

```tsx
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:

```typescript
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

## Further Reading

- **[Plugin Creation Guide](../../docs/plugin-creation-guide.md)** — Step-by-step tutorial for beginners
- **[Developer API Reference](../../docs/api-developer.md)** — Bridge, entities, credits, and validation endpoints
- **[Plugin API Reference](../../docs/api-plugins.md)** — Submission, review pipeline, and production bridge

## License

MIT