Skip to main content

Crate portaki_sdk

Crate portaki_sdk 

Source
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::capabilities are 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::connectors for 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::kv or entity storage.
  • Synchronous side effects: host calls may fail (PortakiError); surface renderers should degrade gracefully when optional capabilities are missing.

§Typical authoring path

  1. Declare the module with portaki_module! and register surfaces/queries/commands via proc-macros (surface!, query!, command!, …).
  2. Declare the host settings on a struct with #[portaki_sdk::config] and read them with its generated load(&ctx) — the platform stores, validates and gates publication on them (see config).
  3. Import prelude in handler modules.
  4. Return Surface trees from render functions; call host::* for storage, connectors, and logging.
  5. Gate premium behaviour with ctx.has_capability(...) or capability constants.
  6. Prefer ids newtypes and contracts for cross-boundary names (surfaces, commands, events, peer ops) instead of free string literals.
  7. Keep Wasm crate folders strict: guest/ / host/ / connectors / ids (see repo docs/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::NavigateTarget;
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.
email
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.json may list under permissions.
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 EventType catalog for host::events::emit.
define_operation_namesDeprecated
Declares a module-local OperationName catalog (commands / queries).
define_surface_idsDeprecated
Declares a module-local SurfaceId catalog.
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 codes portaki_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 key rule.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. Generates load / save, the updateConfig command (host form), importRows (with import), the host query readRows (with read: the rows as declared, for the platform’s guest assistant — only on rows the guest sees, never on a record), publishReadiness (unless readiness = false), the PortakiResource entity and the manifest’s resources[] 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.
email
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 with meta its 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 a String). Adds id, the derives, #[serde(default)], and portaki_sdk::resource::Item (or Meta). 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. Generates list / for_stay / get, the commands submit (guest), add, setStatus, note, the query listForStay, the timeline contract when due_hours is set, and the entity. With hooks, the module implements portaki_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).