PSA/sdk/alga-client-sdk/templates/component-basic/wit/extension-runner.wit

/// Alga extension runner component interfaces.
/// Inspired by wasmCloud's capability providers, each interface here
/// represents a host-provided capability that extensions can import.

package alga:extension;

/// Shared type definitions ---------------------------------------------------

record context-data {
    request-id: option<string>,
    tenant-id: string,
    extension-id: string,
    install-id: option<string>,
    version-id: option<string>,
}

enum secret-error {
    missing,
    denied,
    expired,
    internal,
}

record http-header {
    name: string,
    value: string,
}

record http-request {
    method: string,
    url: string,
    headers: list<http-header>,
    body: option<list<u8>>,
}

record http-response {
    status: u16,
    headers: list<http-header>,
    body: option<list<u8>>,
}

enum http-error {
    invalid-url,
    not-allowed,
    transport,
    internal,
}

enum storage-error {
    missing,
    conflict,
    denied,
    internal,
}

record storage-entry {
    namespace: string,
    key: string,
    value: list<u8>,
    revision: option<u64>,
}

enum proxy-error {
    route-not-found,
    denied,
    bad-request,
    internal,
}

record user-data {
    tenant-id: string,
    client-name: string,
    user-id: string,
    user-email: string,
    user-name: string,
    user-type: string,
}

record user-data-v2 {
    tenant-id: string,
    client-name: string,
    user-id: string,
    user-email: string,
    user-name: string,
    user-type: string,
    client-id: option<string>,
    additional-fields: list<tuple<string, string>>,
}

enum user-error {
    not-available,
    not-allowed,
}

enum client-read-error {
    not-allowed,
    invalid-input,
    internal,
}

record client-summary {
    client-id: string,
    client-name: string,
    client-type: option<string>,
    is-inactive: bool,
    default-currency-code: option<string>,
    account-manager-id: option<string>,
    account-manager-name: option<string>,
    billing-email: option<string>,
}

record clients-list-input {
    search: option<string>,
    include-inactive: option<bool>,
    page: option<u32>,
    page-size: option<u32>,
}

record clients-list-result {
    items: list<client-summary>,
    total-count: u32,
    page: u32,
    page-size: u32,
}

enum service-item-kind {
    service,
    product,
}

enum service-billing-method {
    fixed,
    hourly,
    usage,
}

enum service-read-error {
    not-allowed,
    invalid-input,
    internal,
}

record service-summary {
    service-id: string,
    service-name: string,
    item-kind: service-item-kind,
    billing-method: service-billing-method,
    service-type-id: option<string>,
    service-type-name: option<string>,
    default-rate: f64,
    unit-of-measure: string,
    is-active: bool,
    sku: option<string>,
}

record services-list-input {
    search: option<string>,
    item-kind: option<service-item-kind>,
    is-active: option<bool>,
    billing-method: option<service-billing-method>,
    page: option<u32>,
    page-size: option<u32>,
}

record services-list-result {
    items: list<service-summary>,
    total-count: u32,
    page: u32,
    page-size: u32,
}

/// Capability provider interfaces -------------------------------------------

/// Access execution context metadata.
/// @requires(cap:context.read)
interface context {
    get-context: func() -> context-data;
}

/// Retrieve install-scoped secrets.
/// @requires(cap:secrets.get)
interface secrets {
    get: func(key: string) -> result<string, secret-error>;
    list: func() -> list<string>;
}

/// Perform outbound HTTP requests with host enforced allowlists.
/// @requires(cap:http.fetch)
interface http {
    fetch: func(request: http-request) -> result<http-response, http-error>;
}

/// Work with host-backed key/value storage.
/// @requires(cap:storage.kv)
interface storage {
    get: func(namespace: string, key: string) -> result<storage-entry, storage-error>;
    put: func(entry: storage-entry) -> result<storage-entry, storage-error>;
    delete: func(namespace: string, key: string) -> result<(), storage-error>;
    list: func(namespace: string, cursor: option<string>) -> result<list<storage-entry>, storage-error>;
}

/// Emit structured log messages.
/// @requires(cap:log.emit)
interface logging {
    info: func(message: string);
    warn: func(message: string);
    error: func(message: string);
}

/// Invoke host-mediated proxy routes for UI flows.
/// @requires(cap:ui.proxy)
interface ui-proxy {
    call: func(route: string, payload: option<list<u8>>) -> result<list<u8>, proxy-error>;
}

/// Access current user information.
/// @requires(cap:user.read)
interface user {
    get-user: func() -> result<user-data, user-error>;
}

/// Access current user information (v2 adds client-id and additional-fields).
/// @requires(cap:user.read)
interface user-v2 {
    get-user: func() -> result<user-data-v2, user-error>;
}

/// Read tenant-scoped client summaries.
/// @requires(cap:client.read)
interface clients {
    list-clients: func(input: clients-list-input) -> result<clients-list-result, client-read-error>;
    get-client: func(client-id: string) -> result<option<client-summary>, client-read-error>;
}

/// Read tenant-scoped service catalog summaries.
/// @requires(cap:service.read)
interface services {
    list-services: func(input: services-list-input) -> result<services-list-result, service-read-error>;
    get-service: func(service-id: string) -> result<option<service-summary>, service-read-error>;
}

/// Guest exported HTTP-style handler entrypoint (initial contract).
record execute-request {
    context: context-data,
    http: http-request,
}

record execute-response {
    status: u16,
    headers: list<http-header>,
    body: option<list<u8>>,
}

/// World describing the Alga extension runtime contract.
world runner {
    import context: interface context;
    import secrets: interface secrets;
    import http: interface http;
    import storage: interface storage;
    import logging: interface logging;
    import ui-proxy: interface ui-proxy;
    import user-v2: interface user-v2;
    import clients: interface clients;
    import services: interface services;

    export handler: func(request: execute-request) -> execute-response;
}