Expand description
§Portaki module SDK
Authoring toolkit for Wasm modules executed by the Portaki gateway. This crate
is the module-side contract: typed wrappers around host imports, SDUI
primitives, capability identifiers, invocation context, and proc-macros that
emit manifest.json fragments at compile time.
§What the host guarantees
- Every query, command, and surface invocation receives a fully populated
Context(property, plan, locale, effective capabilities, correlation id). - Host functions (
host::kv,host::repo,host::connectors, …) are routed through the gateway — modules never talk to Postgres, Redis, or third-party APIs directly. - Capability grants reflected in
Context::capabilitiesare authoritative for the current invocation; optional manifest capabilities may be absent.
§What modules must not assume
- Secrets in Wasm: never embed API keys. Use
host::connectorsfor egress (the gateway injects pool/BYOK secrets at the boundary). - Raw HTTP / SQL: blocked by platform policy; use connectors and
host::repo. - Cross-invocation memory: Wasm instances are ephemeral — persist via
host::kvor entity storage. - Synchronous side effects: host calls may fail (
PortakiError); surface renderers should degrade gracefully when optional capabilities are missing.
§Typical authoring path
- Declare the module with
portaki_module!and register surfaces/queries/commands via proc-macros (surface!,query!,command!, …). - Declare the host settings on a struct with
#[portaki_sdk::config]and read them with its generatedload(&ctx)— the platform stores, validates and gates publication on them (seeconfig). - Import
preludein handler modules. - Return
Surfacetrees from render functions; callhost::*for storage, connectors, and logging. - Gate premium behaviour with
ctx.has_capability(...)orcapabilityconstants. - Prefer
idsnewtypes andcontractsfor cross-boundary names (surfaces, commands, events, peer ops) instead of free string literals. - Keep Wasm crate folders strict:
guest//host//connectors/ids(see repodocs/module-layout.md).
§Wasm target
On wasm32, see wasm for Extism entry points (portaki_query,
portaki_command) and the portaki_host_dispatch ABI.
Re-exports§
pub use capability::CapabilityId;pub use context::Context;pub use context::DisplayPreferences;pub use context::GuestContext;pub use context::GuestIdentity;pub use context::HostContext;pub use context::PlanInfo;pub use context::PropertyContext;pub use context::Quota;pub use context::StayContext;pub use email::EmailContextContribution;Deprecated pub use email::BlockRow;pub use email::BlockTone;pub use email::BlockType;pub use email::EmailBlock;pub use email::EmailBlocks;pub use email::EmailContextArgs;pub use email::EmailTemplateKey;pub use email::EmailVar;pub use email::EmailVars;pub use error::PortakiError;pub use error::Result;pub use ids::EventType;pub use ids::FragmentId;pub use ids::ModuleId;pub use ids::OperationName;pub use ids::SurfaceId;pub use sdui::action::json_value;pub use sdui::action::Action;pub use sdui::action::EmptyArgs;pub use sdui::action::OverlayArgs;pub use sdui::action::OverlayPresentation;pub use sdui::component::Component;pub use sdui::surface::Surface;pub use inventory;
Modules§
- capability
- Canonical capability identifier catalog.
- config
- Host configuration held by the platform — the runtime half of
#[portaki_sdk::config]. - context
- Invocation context types injected by the gateway into every handler.
- contracts
- SDK-owned cross-module / platform contracts.
- deprecation
- What the platform is withdrawing, since when, and what to use instead.
- Platform transactional email template catalog.
- error
- Error types surfaced by SDK host wrappers and Wasm dispatch.
- files
- Files a guest attaches from the booklet.
- guest_
shell - What a guest sees when a surface cannot show its content.
- host
- Host function wrappers — the module’s only supported API to platform services.
- ids
- Typed wire identifiers for module / shell / platform boundaries.
- limits
- Caps the platform applies to modules — a single table.
- manifest
- Manifest schema types consumed by the Portaki CLI when merging macro emissions.
- permission
- Manifest permissions — what
portaki.module.jsonmay list underpermissions. - prelude
- Commonly used imports for module handler code.
- resource
- Declared resources — the SDK stores, merges, checks and draws what a module declares.
- reveal
- When a secret (door code, Wi-Fi password, parking code) may be shown to a guest.
- sdui
- Server-Driven UI (SDUI) catalog for module-authored interfaces.
- surfaces
- Rules of the shared surfaces whose tree the platform reads under its own terms.
- vocab
- Closed vocabularies of the module manifest — typed, so a misspelt value does not compile.
- wasm
- Wasm / Extism integration — entry points, dispatch, and host import ABI.
Macros§
- bundle_
text - A text of the module’s own bundles, in every language they have — an
I18nText. - define_
event_ types - Declares a module-local
EventTypecatalog forhost::events::emit. - define_
operation_ names Deprecated - Declares a module-local
OperationNamecatalog (commands / queries). - define_
surface_ ids Deprecated - Declares a module-local
SurfaceIdcatalog. - log_
info - Emits a structured
info-level log line to platform observability. - portaki_
module - Function-like module declaration (
portaki_module!(…)). - refuse
- A declared refusal:
PortakiError::Refused, checked at compile time against the codesportaki_module!(error = "…")declares. - t
- Resolves an i18n key through the host translation service.
Constants§
- SDUI_
PRIMITIVES_ JSON - The SDUI primitive catalogue this SDK generates its components from.
- VERSION
- The version of this SDK, as compiled into the crate.
Attribute Macros§
- capability
- Declares a required or optional host capability dependency.
- choice
- A unit enum a declared field picks from (
unstable).label = "rule.status": a value’s label is the bundle keyrule.status.<value>;#[icon(IconName::X)]on a variant gives its icon. Writes the derives,portaki_sdk::resource::Choice, and the values for the manifest. - collection
- A collection the SDK stores (
unstable):#[collection(name = "rules", item = Rule, meta = Display, max = 30, import)]on a unit struct. Generatesload/save, theupdateConfigcommand (host form),importRows(withimport), the host queryreadRows(withread: the rows as declared, for the platform’s guest assistant — only on rows the guest sees, never on a record),publishReadiness(unlessreadiness = false), thePortakiResourceentity and the manifest’sresources[]entry. - command
- Declares a mutating gateway command operation.
- config
- Declares the module’s host configuration: the struct is the schema, the platform the store.
- connector
- Declares use of a built-in platform connector (manifest reference only).
- connector_
op - Declares one HTTP operation on the most recently emitted custom connector, or a validator stub.
- custom_
connector - Declares a custom HTTP connector implemented by the module.
- Declares an email the command sends, so the manifest lists it without anyone writing JSON.
- email_
blocks - Declares the blocks a module adds to Portaki stay emails, per email.
- email_
vars - Declares the variables a module gives Portaki guest emails, per template, on the function that computes them.
- entity
- Declares a persistent entity schema for Atlas and
host::repo. - entity_
indexes - Declares repository indexes for an entity (Atlas spatial/field indexes).
- event_
handler - Declares a subscription to a platform event type.
- item
- A row type of a declared collection (
unstable), or withmetaits settings. Each#[field(label = "…", required, max_chars = N, between(a, b), description = "…")]is declared: kind from the Rust type (I18nText,String,bool, numbers, a#[choice]enum;kind = "time_range"on aString). Addsid, the derives,#[serde(default)], andportaki_sdk::resource::Item(orMeta).key = "title": the natural key an import dedupes on. - nav
- Declares a host dashboard entry that no surface renders.
- params
- Describes the arguments of a query or command, so tooling can offer a form for them.
- query
- Declares a read-only gateway query operation.
- record
- A record the SDK stores (
unstable): what a guest deposits during a stay and the host follows.#[record(name = "reports", item = Report, status = ReportStatus, due_hours = 24, task_title = "…", task_done = "…", hooks)]on a unit struct. Generateslist/for_stay/get, the commandssubmit(guest),add,setStatus,note, the querylistForStay, the timeline contract whendue_hoursis set, and the entity. Withhooks, the module implementsportaki_sdk::resource::RecordHooks(guard, on_created, on_note). - surface
- Declares a host or guest SDUI surface renderer.
- wire
- Marks a struct or enum as a Portaki wire JSON DTO (gateway / SDUI / events / email).