Setup orchestration
setupFabric — end-to-end first-run provisioning with credential checks + optional backfill.
Subpath: @fabricorg/integrations/setup.
setupFabric is the one-call provisioning helper for a fabric instance: it validates that every plugin has its required credentials in the KeyStore, optionally runs each plugin's backfill(ctx) hook, and returns a structured report so CLI tools / dashboards / Studio can show progress.
Quick example
import { setupFabric } from '@fabricorg/integrations/setup';
import { InMemoryKeyStore } from '@fabricorg/integrations';
import { slack, stripe, hubspot } from '@fabricorg/integrations/plugins';
const keyStore = new InMemoryKeyStore();
await keyStore.setAccountField('slack', 'org:acme', 'bot_token', 'xoxb-...');
await keyStore.setAccountField('stripe', 'org:acme', 'api_key', 'sk_test_...');
// (hubspot intentionally missing to demo the report)
const report = await setupFabric({
plugins: [slack({ botToken: '' }), stripe({ apiKey: '' }), hubspot({ key: '' })],
keyStore,
tenantId: 'org:acme',
backfill: true,
caller: 'cli',
});
if (!report.allReady) {
for (const p of report.plugins) {
if (!p.authStatus.ready) {
console.error(`${p.pluginId}: missing`, p.authStatus.missing);
}
}
process.exit(2);
}API
function setupFabric(options: {
plugins: readonly FabricPlugin[];
keyStore: KeyStore;
tenantId: string;
pluginIds?: readonly string[]; // filter to a subset
backfill?: boolean; // default false
caller?: 'cli' | 'script' | 'studio' | 'hosted';
contextBuilder?: (input) => FabricContext;
}): Promise<SetupReport>Returns:
type SetupReport = {
tenantId: string;
caller: SetupCaller;
plugins: PluginSetupResult[];
allReady: boolean;
startedAt: string;
completedAt: string;
durationMs: number;
};
type PluginSetupResult = {
pluginId: string;
authType: 'api_key' | 'oauth_2' | 'bot_token';
authStatus:
| { ready: true }
| { ready: false; missing: { integration: string[]; account: string[] } };
backfillRan: boolean;
backfillError?: string;
};Required-field rules
| Auth type | Required integration fields | Required account fields |
|---|---|---|
api_key | — | api_key |
bot_token | — | bot_token |
oauth_2 | client_id, client_secret, redirect_url | access_token |
Optional fields like webhook_signature don't block readiness — they're auto-populated when relevant.
Backfill hook
When backfill: true and a plugin defines a backfill(ctx) function, setupFabric invokes it after authStatus resolves to ready. Errors are captured in backfillError per plugin — one bad backfill doesn't abort the rest, and the overall allReady flag reflects auth status (not backfill success).
Use contextBuilder to inject your event sink, entity store, or other context fields when the default minimal context isn't enough.
Callers
The caller field surfaces in the report so downstream telemetry can distinguish:
'cli'— manual run fromfabric integrations setup'script'— programmatic boot in a service'studio'— initiated from the Studio setup wizard'hosted'— managed-platform first-run