@gcoredev/fastedge-wizard-sdk

Guest-side SDK for building FastEdge wizard forms that embed inside the Gcore FastEdge portal UI.

A wizard is a small web app (any framework, or plain HTML/JS) that the portal loads in a hardened iframe. The wizard never holds a Gcore API credential — instead it talks to the portal over a capability-mediated postMessage bridge, and the portal performs Gcore API calls on its behalf.

Install

Published on npm (public):

npm install @gcoredev/fastedge-wizard-sdk

Or in package.json:

"dependencies": {
  "@gcoredev/fastedge-wizard-sdk": "latest"
}

Quickstart

import { connect } from '@gcoredev/fastedge-wizard-sdk';

const session = await connect({
  // Must exactly match the origin of the Gcore portal that hosts your wizard.
  expectedHostOrigin: 'https://portal.gcore.com',
});

const ctx = await session.context.get();
console.log(ctx.theme, ctx.locale);

const templates = await session.fastedge.templates.list();

See docs/quickstart.md for a full end-to-end example and local dev setup.

API

connect(options): Promise<WizardSession>

Performs the handshake with the portal host and returns a live session.

| Option | Type | Required | Description | |---|---|---|---| | expectedHostOrigin | string | Yes | Exact origin of the portal (https://…). The SDK rejects INIT from any other origin. | | handshakeTimeoutMs | number | No | Override the default 10 s handshake timeout. |

Throws WizardError with code timeout if the portal doesn't complete the handshake in time, or protocol_error on a version mismatch.

WizardSession

The full, always-current surface is the WizardSession interface in src/sdk.ts (the method tree) and the param/result types in src/types.ts. Both are re-exported from the package, so your editor shows every signature and its doc comment the moment you import. Those files are the canonical contract — the map below is orientation, not an exhaustive signature list.

| Namespace | Purpose | |---|---| | session.context | Locale, theme, the wizard's own app ID, managed app IDs, feature flags | | session.fastedge.templates | List / read FastEdge templates | | session.fastedge.apps | List / get / create / update / link apps | | session.fastedge.secrets | Pick-or-create secrets, generate ES256 keypairs | | session.fastedge.stores | Pick-or-create Edge Storage (KV) instances | | session.cdn.resources | List / pick CDN resources | | session.cdn.origins | List / create CDN origin groups | | session.cdn.rules | List / create CDN rules | | session.deployment | Plan-then-apply — prefer deploy() |

Behaviours the types don't spell out:

• Consent-gated writes — apps.create / apps.update / apps.link, cdn.origins.create, and cdn.rules.create open a portal consent dialog; a user cancel throws WizardError with code user_cancelled. Pickers (secrets.pickOrCreate, stores.pickOrCreate, cdn.resources.pick) are consent points too.
• Refs only, never plaintext — secrets and Edge Storage instances cross the bridge as { id, name } refs, both with an optional origin of 'picked' | 'created'; the guest never sees a secret value or enumerates the account.
• Deployment scope — plan / deploy create apps, CDN origins, and CDN rules, not secrets or stores. Create those eagerly with secrets.pickOrCreate / secrets.generateKeypair / stores.pickOrCreate and reference them by id. deploy plans, applies, streams deployment.progress, and tears the listener down afterwards (even if apply rejects) — prefer it over plan + apply.

session.on(event, handler)

Subscribe to host-pushed events. Returns an unsubscribe function.

const off = session.on('deployment.progress', ({ step, total, describe }) => {
  console.log(`[${step}/${total}] ${describe}`);
});
// later:
off();

session.dispose()

Closes the MessageChannel port and rejects all pending intents. Call this when the wizard unmounts.

WizardError

All bridge errors are thrown as WizardError, which extends Error and adds a typed .code field.

| Code | Meaning | |---|---| | denied | Intent not in the catalog or host refused it | | out_of_scope | Resource is outside the wizard's managed scope | | invalid_params | Request params failed host-side validation | | user_cancelled | User dismissed a consent or picker dialog | | unauthorized | Session token expired | | not_found | Requested resource doesn't exist | | conflict | Duplicate name or conflicting state | | upstream_error | Gcore API returned an error | | rate_limited | Exceeded 20 intents per 10 s | | timeout | Intent or handshake took longer than allowed | | protocol_error | Message version mismatch or session disposed |

import { WizardError } from '@gcoredev/fastedge-wizard-sdk';

try {
  await session.fastedge.apps.create(params);
} catch (err) {
  if (err instanceof WizardError && err.code === 'user_cancelled') {
    // user clicked cancel in the portal consent dialog — not a real error
  }
}

Rate limits & safety

• Max 20 intents per 10 s sliding window (host-enforced; rate_limited on breach).
• Max 8 in-flight intents at a time.
• Messages larger than 64 KB are silently dropped by the host (the client-side timeout fires after ~90 s).
• The bridge rejects INIT from any origin other than expectedHostOrigin.

Examples

Worked examples live in the sibling fastedge-wizard-apps repo under wizards/:

| Wizard | What it shows | |---|---| | _example/ | Minimal framework-agnostic wizard: handshake, context.get, templates.list | | _example-intents/ | Step-by-step exercise of the full intent surface (apps.*, secrets.*, stores.*, cdn.*, deployment.*) | | edge-totp/ | Canonical real wizard — two apps + CDN wiring, eager secrets/stores, deployment.deploy |

For local dev (mock host, fixtures) see docs/quickstart.md.