app_bridge 3.0.0-aarch64-linux → 4.1.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 045a7796fa110808d6c6529172c91514ab963bc2d7793f4bdda294ddbbbe60a7
-  data.tar.gz: 5fc04fb84855d00f6f0778262ef7e900d469622e4203b062cee3d96b32f1320c
+  metadata.gz: cd334ce501f49a41f2a323dcea31540dbdce65ff0a4d750b1ca3871ec491121f
+  data.tar.gz: f21ba99a8807c7894e1871321d4ff830daf37dde2fde7768d3af908618061ec5
 SHA512:
-  metadata.gz: 92a182f5c98b37c1f3f54da8012ee515804f0e6c98a559427c0d8c2164858ada027b5508001c4399fa50cb7e4bda30066b78b97a0cce87322cac33f4c0f3ec7e
-  data.tar.gz: e1ae9d4d23553b1be63b90b4ab7ad0e4ccfde7ed78df5de8df57e640886f7601057c245e976c0fa371d51aa2c389b64d99972b914fd193c3f0ecfe644ac944a5
+  metadata.gz: 8296e3014067a1a29917fd4139664cb331c77cfe419a234b4cc8f14f7f5491b80868f8272a278edcf41b5d25b7cd0459134b0eae2632b844072e00852bcd273d
+  data.tar.gz: 52eed814e20ef18341f7f6127d9a7aa1038be4f53cbc1d949107ebc91cac01d4883b8100729697ee44478d6a72f9dcb9e87692b472828b649039179dadcfec98

data/.rubocop.yml

@@ -13,3 +13,4 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*_spec.rb'
     - '*.gemspec'
+    - 'tasks/*.rake'

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.2
+ruby 3.4.8

data/README.md

@@ -18,7 +18,7 @@ bundle install
 
 ## Usage
 
-To use this gem, you need a WebAssembly component that adheres to the specification defined in `ext/app_bridge/wit/world.wit`.
+To use this gem, you need a WebAssembly component that adheres to the specification defined in `ext/app_bridge/wit/v4/world.wit` (or an older supported version like `v3`).
 
 You can check out the example components in `spec/fixtures/components` to see how such a component should be structured.
 
@@ -31,7 +31,279 @@ app = AppBridge::App.new('path/to/your/component.wasm')
 app.triggers # => ['trigger1', 'trigger2']
 ```
 
-More documentation and features will be added as the gem evolves.
+### File Handling
+
+The gem provides a `file.normalize` function for handling files in connectors. It automatically detects the input format (URL, data URI, or base64) and returns normalized file data.
+
+#### In your WASM connector (JavaScript):
+
+```javascript
+import { normalize } from 'standout:app/file@4.0.0';
+
+// Normalize any file source - input type is auto-detected
+const fileData = normalize(
+  input.fileUrl,           // URL, data URI, or base64 string
+  [["Authorization", token]], // Optional headers for URL requests
+  "invoice.pdf"            // Optional filename override
+);
+
+// Returns: { base64, contentType, filename }
+
+// Include in your action output
+return {
+  serializedOutput: JSON.stringify({
+    document: fileData  // Will be replaced with blob ID by platform
+  })
+};
+```
+
+#### In your WASM connector (Rust):
+
+```rust
+use crate::standout::app::file::normalize;
+
+let file_data = normalize(
+    &input.file_url,
+    Some(&[("Authorization".to_string(), token)]),
+    Some("invoice.pdf"),
+)?;
+
+// file_data contains { base64, content_type, filename }
+```
+
+#### Output schema:
+
+Mark file fields with `format: "file-output"` so the platform knows to process them:
+
+```json
+{
+  "properties": {
+    "document": {
+      "type": "object",
+      "format": "file-output"
+    }
+  }
+}
+```
+
+#### Platform configuration:
+
+Configure the file uploader in your Rails app:
+
+```ruby
+AppBridge.file_uploader = ->(file_data) {
+  blob = ActiveStorage::Blob.create_and_upload!(
+    io: StringIO.new(Base64.decode64(file_data['base64'])),
+    filename: file_data['filename'],
+    content_type: file_data['content_type']
+  )
+  blob.signed_id
+}
+```
+
+The gem automatically replaces file data with the return value (in this example blob IDs) before returning the action response.
+
+### Multipart Form Data
+
+For `multipart/form-data`, you must build the body manually and set the `Content-Type` header with a boundary. In `standout:app@4.1.0` you can send raw bytes via `body-bytes`; earlier versions only support a string body.
+
+#### In your WASM connector (Rust):
+
+```rust
+let boundary = "----app-bridge-boundary";
+
+let mut body = Vec::new();
+body.extend_from_slice(format!(
+    "--{b}\r\n\
+Content-Disposition: form-data; name=\"metadata\"\r\n\r\n\
+{metadata}\r\n\
+--{b}\r\n\
+Content-Disposition: form-data; name=\"file\"; filename=\"invoice.pdf\"\r\n\
+Content-Type: application/pdf\r\n\r\n",
+    b = boundary,
+    metadata = metadata_json,
+).as_bytes());
+body.extend_from_slice(&file_bytes);
+body.extend_from_slice(format!("\r\n--{b}--\r\n", b = boundary).as_bytes());
+
+let response = RequestBuilder::new()
+    .method(Method::Post)
+    .url(upload_url)
+    .header("Content-Type", format!("multipart/form-data; boundary={}", boundary))
+    .body_bytes(body)
+    .send()?;
+```
+
+If you are targeting `standout:app@4.0.0` or earlier, you can only send a string body. That means multipart uploads must be base64-encoded and the receiving API must support `Content-Transfer-Encoding: base64`.
+
+## Retry With Reference
+
+`standout:app@4.1.0` introduces a structured retry error for actions. Connectors can return a retry error with a reference and status, and the platform can pass that back on subsequent retries via `action-context.reference-object`.
+
+### In your WASM connector (Rust)
+
+```rust
+return Err(AppError {
+    code: ErrorCode::RetryWithReference(ReferenceObject {
+        reference: request_id.to_string(),
+        status: status.to_string(),
+    }),
+    message: "Background request still processing".to_string(),
+});
+```
+
+### In the Ruby platform
+
+When the connector returns `retry-with-reference`, the bridge raises `AppBridge::RetryWithReferenceError`. You can access the structured fields:
+
+```ruby
+rescue AppBridge::RetryWithReferenceError => e
+  e.reference # => "ref-123"
+  e.status    # => "queued"
+  e.message   # => "Background request still processing after 1 attempts."
+end
+```
+
+## Backward Compatibility
+
+The gem supports **multi-version WIT interfaces**, allowing connectors built against older WIT versions to continue working when the gem is updated.
+
+### How it works
+
+When loading a WASM component, the gem automatically detects which WIT version it was built against:
+
+1. **V4 components** (current, `standout:app@4.0.0`): Full feature support including the `file` interface
+2. **V3 components** (`standout:app@3.0.0`): Legacy support without file interface
+
+### Adding support for new WIT versions
+
+When adding a new WIT version (e.g., v5), follow these steps:
+
+#### 1. Create the WIT file
+
+Copy the latest version and modify:
+
+```bash
+cp -r ext/app_bridge/wit/v4 ext/app_bridge/wit/v5
+```
+
+Edit `ext/app_bridge/wit/v5/world.wit`:
+- Update the package version: `package standout:app@5.0.0;`
+- Add new interfaces or modify existing ones
+
+#### 2. Add the bindgen module
+
+In `ext/app_bridge/src/component.rs`, add after the existing modules:
+
+```rust
+pub mod v5 {
+    wasmtime::component::bindgen!({
+        path: "./wit/v5",
+        world: "bridge",
+    });
+}
+```
+
+#### 3. Generate type conversions
+
+Add the conversion macro call:
+
+```rust
+impl_conversions!(v5);
+```
+
+#### 4. Add BridgeWrapper variant
+
+Update the enum:
+
+```rust
+pub enum BridgeWrapper {
+    V3(v3::Bridge),
+    V4(v4::Bridge),
+    V5(v5::Bridge),  // <-- add this
+}
+```
+
+Add an arm to each `bridge_method!` macro expansion. In the macro definitions, add:
+
+```rust
+BridgeWrapper::V5(b) => {
+    let r = b.$interface().$method(store, ...)?;
+    Ok(r.map(Into::into).map_err(Into::into))
+}
+```
+
+#### 5. Register interfaces in the linker
+
+In `build_linker()`:
+
+```rust
+// v5: http + environment + file + new_feature
+v5::standout::app::http::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::file::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::new_feature::add_to_linker(&mut linker, |s| s)?;  // if applicable
+```
+
+#### 6. Update the instantiation chain
+
+In `app()`, add v5 at the top (newest first):
+
+```rust
+// v5 (newest)
+if let Ok(instance) = v5::Bridge::instantiate(&mut *store, &component, &linker) {
+    return Ok(BridgeWrapper::V5(instance));
+}
+
+// v4
+if let Ok(instance) = v4::Bridge::instantiate(&mut *store, &component, &linker) {
+    return Ok(BridgeWrapper::V4(instance));
+}
+
+// v3 (oldest)
+// ...
+```
+
+#### 7. Register Host implementations
+
+In `app_state.rs`:
+
+```rust
+impl_host_for_version!(v5);
+```
+
+In `request_builder.rs`:
+
+```rust
+impl_host_request_builder!(v5);
+impl_http_type_conversions!(v5);
+```
+
+#### 8. If the version has the file interface
+
+In `file_ops.rs` (only if v5 includes the `file` interface):
+
+```rust
+impl_file_host!(v5);
+```
+
+#### 9. If adding new host functions
+
+If the new version introduces entirely new interfaces (not just `file`), implement the `Host` trait:
+
+```rust
+impl v5::standout::app::new_feature::Host for AppState {
+    fn some_function(&mut self, ...) -> ... {
+        // implementation
+    }
+}
+```
+
+### Benefits
+
+- **No forced rebuilds**: Existing connectors continue to work after gem updates
+- **Gradual migration**: Update connectors to new WIT versions at your own pace
+- **Type safety**: Each version's types are converted to the latest version internally
 
 ## Development
 

data/ext/app_bridge/wit/{world.wit → v3/world.wit}

@@ -275,9 +275,12 @@ interface http {
   }
 }
 
+// Note: v3 does NOT include the file interface
+
 world bridge {
   import http;
   import environment;
+  // Note: file interface is NOT available in v3
   export triggers;
   export actions;
 }

data/ext/app_bridge/wit/v4/world.wit

@@ -0,0 +1,328 @@
+package standout:app@4.0.0;
+
+interface types {
+  // The trigger-store is a string that is used to store data between trigger
+  // invocations. It is unique per trigger instance and is persisted between
+  // invocations.
+  //
+  // You can store any string here. We suggest that you use a serialized
+  // JSON object or similar since that will give you some flexibility if you
+  // need to add more data to the store.
+  type trigger-store = string;
+
+  record connection {
+    id: string,
+    name: string,
+    // The connection data is a JSON object serialized into a string. The JSON root
+    // will always be an object.
+    serialized-data: string,
+  }
+
+  record trigger-context {
+    // Trigger ID is a unique identifier for the trigger that is requested to be
+    // invoked.
+    trigger-id: string,
+
+    // The connection that the trigger is invoked for.
+    // Connection is required for all trigger operations.
+    connection: connection,
+
+    // The store will contain the data that was stored in the trigger store the
+    // last time the trigger was invoked.
+    store: trigger-store,
+
+    // The input data for the trigger, serialized as a JSON object string.
+    // This contains the input data from the trigger configuration form.
+    serialized-input: string,
+  }
+
+  record action-context {
+    // Action ID is a unique identifier for the action that is requested to be
+    // invoked.
+    action-id: string,
+
+    // The connection that the action is invoked for.
+    // Connection is required for all action operations.
+    connection: connection,
+
+    // The input data for the action, serialized as a JSON object string.
+    // This contains the data passed from the previous step in the workflow.
+    serialized-input: string,
+  }
+
+  record trigger-response {
+    // The trigger events, each event will be used to spawn a new workflow
+    // execution in Standouts integration plattform.
+    events: list<trigger-event>,
+
+    // The updated store will be stored and used the next time the trigger is
+    // invoked.
+    store: trigger-store,
+  }
+
+  record action-response {
+    // The output data from the action, serialized as a JSON object string.
+    // This contains the data that will be passed to the next step in the workflow.
+    // The data must be a valid JSON object (not an array or primitive).
+    serialized-output: string
+  }
+
+  record trigger-event {
+    // The ID of the trigger event
+    //
+    // If the connection used for the given instance of the trigger is the same,
+    // as seen before. Then the event will be ignored.
+    //
+    // A scheduler could therefore use an timestamp as the ID, to ensure that
+    // the event is only triggered once per given time.
+    //
+    // A trigger that acts on created orders in a e-commerce system could use
+    // the order ID as the ID, to ensure that the event is only triggered once
+    // per order.
+    //
+    // A trigger that acts on updated orders in a e-commerce system could use
+    // the order ID in combination with an updated at timestamp as the ID, to
+    // ensure that the event is only triggered once per order update.
+    id: string,
+
+    // Serialized data must be a JSON object serialized into a string
+    // Note that it is important that the root is a object, not an array,
+    // or another primitive type.
+    serialized-data: string,
+  }
+
+  /// A structured error that can be returned by for example a call to a trigger or action.
+  /// Contains a machine-readable code and a human-readable message.
+  record app-error {
+    /// The error code identifying the type of failure.
+    code: error-code,
+
+    /// A human-readable message describing the error in more detail.
+    message: string,
+  }
+
+  /// An enumeration of error codes that can be returned by a trigger implementation.
+  /// These codes help the platform and plugin developers distinguish between different types of failures.
+  variant error-code {
+    /// Authentication failed. Typically due to an invalid or expired API key or token.
+    unauthenticated,
+
+    /// Authorization failed. The connection is valid but does not have the necessary permissions.
+    forbidden,
+
+    /// The trigger is misconfigured. For example, a required setting is missing or invalid.
+    misconfigured,
+
+    /// The target system does not support a required feature or endpoint.
+    unsupported,
+
+    /// The target system is rate-limiting requests. Try again later.
+    rate-limit,
+
+    /// The request timed out. The target system did not respond in time.
+    timeout,
+
+    /// The target system is currently unavailable or unreachable.
+    unavailable,
+
+    /// An unexpected internal error occurred in the plugin.
+    internal-error,
+
+    /// The response from the external system could not be parsed or was in an invalid format.
+    malformed-response,
+
+    /// A catch-all for all other types of errors. Should include a descriptive message.
+    other,
+
+    /// Complete the current workflow execution.
+    complete-workflow,
+
+    /// Complete the parent step execution.
+    complete-parent,
+  }
+}
+
+
+interface triggers {
+  use types.{trigger-context, trigger-event, trigger-response, app-error};
+
+  trigger-ids: func() -> result<list<string>, app-error>;
+
+  // Get the input schema for a specific trigger
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The trigger-id is extracted from the context
+  input-schema: func(context: trigger-context) -> result<string, app-error>;
+
+  // Get the output schema for a specific trigger
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The trigger-id is extracted from the context
+  output-schema: func(context: trigger-context) -> result<string, app-error>;
+
+  // Fetch events
+  //
+  // There are some limitations to the function:
+  // - It must a `trigger-response` within 30 seconds
+  // - It must return less than or equal to 100 `trigger-response.events`
+  // - It must not return more than 64 kB of data in the `trigger-response.store`
+  //
+  // If you need to fetch more events, you can return up to 100 events and then
+  // store the data needed for you to remember where you left off in the store.
+  // The next time the trigger is invoked, you can use the store to continue
+  // where you left off.
+  //
+  // If you do not pass the limitations the return value will be ignored. We
+  // will not handle any events and we persist the store that was returned in
+  // the response.
+  //
+  // That also means that you should implement your fetch event function in a
+  // way that it can be called multiple times using the same context and return
+  // the same events. That will ensure that the user that is building an
+  // integration with your trigger will not miss any events if your system is
+  // down for a short period of time.
+  fetch-events: func(context: trigger-context) -> result<trigger-response, app-error>;
+}
+
+interface actions {
+  use types.{action-context, action-response, app-error};
+
+  action-ids: func() -> result<list<string>, app-error>;
+
+  // Get the input schema for a specific action
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The action-id is extracted from the context
+  input-schema: func(context: action-context) -> result<string, app-error>;
+
+  // Get the output schema for a specific action
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The action-id is extracted from the context
+  output-schema: func(context: action-context) -> result<string, app-error>;
+
+  // Execute an action
+  //
+  // There are some limitations to the function:
+  // - It must return an `action-response` within 30 seconds
+  // - The serialized-output must be a valid JSON object serialized as a string
+  //
+  // Actions can perform various operations such as:
+  // - Making HTTP requests to external APIs
+  // - Processing and transforming data
+  // - Storing data for future use
+  // - Triggering other systems or workflows
+  //
+  // The action receives input data from the previous step and can return
+  // serialized output data to be passed to the next step in the workflow.
+  execute: func(context: action-context) -> result<action-response, app-error>;
+}
+
+interface environment {
+  // Get all environment variables
+  env-vars: func() -> list<tuple<string, string>>;
+  // Get a specific environment variable by name
+  env-var: func(name: string) -> option<string>;
+}
+
+interface http {
+  record response {
+    status: u16,
+    headers: headers,
+    body: string,
+  }
+
+  record request {
+    method: method,
+    url: string,
+    headers: headers,
+    body: string,
+  }
+
+  variant request-error {
+    other(string)
+  }
+
+  type headers = list<tuple<string, string>>;
+
+  resource request-builder {
+    constructor();
+
+    method: func(method: method) -> request-builder;
+    url: func(url: string) -> request-builder;
+
+    // Add a header to the request
+    header: func(key: string, value: string) -> request-builder;
+    headers: func(headers: list<tuple<string, string>>) -> request-builder;
+
+    // Add a body to the request
+    body: func(body: string) -> request-builder;
+
+    object: func() -> request;
+
+    // Send the request
+    send: func() -> result<response, request-error>;
+  }
+
+  variant method {
+    get,
+    post,
+    put,
+    delete,
+    patch,
+    options,
+    head,
+  }
+}
+
+interface file {
+  // HTTP headers for file requests (same as http interface)
+  type headers = list<tuple<string, string>>;
+
+  // Normalized file data
+  record file-data {
+    // Base64-encoded file content
+    base64: string,
+    // MIME type (e.g., "application/pdf")
+    content-type: string,
+    // Filename
+    filename: string,
+  }
+
+  variant file-error {
+    // Failed to fetch file from URL
+    fetch-failed(string),
+    // Invalid input format (not a valid URL, data URI, or base64)
+    invalid-input(string),
+    // Request timed out
+    timeout(string),
+    // Any other error
+    other(string),
+  }
+
+  // Normalize any file source to FileData
+  //
+  // The source is automatically detected:
+  // - URL: "https://example.com/file.pdf" - fetched with optional headers
+  // - Data URI: "data:application/pdf;base64,JVBERi0..." - parsed and extracted
+  // - Base64: Any other string is treated as raw base64 - decoded to detect type
+  //
+  // Parameters:
+  // - source: URL, data URI, or base64-encoded content
+  // - headers: Optional HTTP headers for URL requests (e.g., Authorization)
+  // - filename: Optional filename override (auto-detected if not provided)
+  //
+  // Returns file-data which will be processed by the platform:
+  // 1. Fields with format: "file-output" in the output schema are identified
+  // 2. File data is uploaded using the configured file_uploader
+  // 3. The file-data is replaced with the blob ID in the response
+  normalize: func(source: string, headers: option<headers>, filename: option<string>) -> result<file-data, file-error>;
+}
+
+world bridge {
+  import http;
+  import environment;
+  import file;
+  export triggers;
+  export actions;
+}

data/ext/app_bridge/wit/v4_1/world.wit

@@ -0,0 +1,343 @@
+package standout:app@4.1.0;
+
+interface types {
+  // The trigger-store is a string that is used to store data between trigger
+  // invocations. It is unique per trigger instance and is persisted between
+  // invocations.
+  //
+  // You can store any string here. We suggest that you use a serialized
+  // JSON object or similar since that will give you some flexibility if you
+  // need to add more data to the store.
+  type trigger-store = string;
+
+  record connection {
+    id: string,
+    name: string,
+    // The connection data is a JSON object serialized into a string. The JSON root
+    // will always be an object.
+    serialized-data: string,
+  }
+
+  record trigger-context {
+    // Trigger ID is a unique identifier for the trigger that is requested to be
+    // invoked.
+    trigger-id: string,
+
+    // The connection that the trigger is invoked for.
+    // Connection is required for all trigger operations.
+    connection: connection,
+
+    // The store will contain the data that was stored in the trigger store the
+    // last time the trigger was invoked.
+    store: trigger-store,
+
+    // The input data for the trigger, serialized as a JSON object string.
+    // This contains the input data from the trigger configuration form.
+    serialized-input: string,
+  }
+
+  record action-context {
+    // Action ID is a unique identifier for the action that is requested to be
+    // invoked.
+    action-id: string,
+
+    // The connection that the action is invoked for.
+    // Connection is required for all action operations.
+    connection: connection,
+
+    // The input data for the action, serialized as a JSON object string.
+    // This contains the data passed from the previous step in the workflow.
+    serialized-input: string,
+
+    // Optional reference information when the platform retries an action.
+    reference-object: option<reference-object>,
+  }
+
+  record trigger-response {
+    // The trigger events, each event will be used to spawn a new workflow
+    // execution in Standouts integration platform.
+    events: list<trigger-event>,
+
+    // The updated store will be stored and used the next time the trigger is
+    // invoked.
+    store: trigger-store,
+  }
+
+  record action-response {
+    // The output data from the action, serialized as a JSON object string.
+    // This contains the data that will be passed to the next step in the workflow.
+    // The data must be a valid JSON object (not an array or primitive).
+    serialized-output: string
+  }
+
+  record trigger-event {
+    // The ID of the trigger event
+    //
+    // If the connection used for the given instance of the trigger is the same,
+    // as seen before. Then the event will be ignored.
+    //
+    // A scheduler could therefore use a timestamp as the ID, to ensure that
+    // the event is only triggered once per given time.
+    //
+    // A trigger that acts on created orders in a e-commerce system could use
+    // the order ID as the ID, to ensure that the event is only triggered once
+    // per order.
+    //
+    // A trigger that acts on updated orders in a e-commerce system could use
+    // the order ID in combination with an updated at timestamp as the ID, to
+    // ensure that the event is only triggered once per order update.
+    id: string,
+
+    // Serialized data must be a JSON object serialized into a string
+    // Note that it is important that the root is an object, not an array,
+    // or another primitive type.
+    serialized-data: string,
+  }
+
+  /// Retry reference payload returned with error-code.retry-with-reference.
+  record reference-object {
+    /// Reference ID provided for retrying this request later.
+    reference: string,
+
+    /// Status describing the retry state.
+    status: string,
+  }
+
+  record app-error {
+    /// The error code identifying the type of failure.
+    code: error-code,
+
+    /// A human-readable message describing the error in more detail.
+    message: string,
+  }
+
+  /// An enumeration of error codes that can be returned by a trigger implementation.
+  /// These codes help the platform and plugin developers distinguish between different types of failures.
+  variant error-code {
+    /// Authentication failed. Typically due to an invalid or expired API key or token.
+    unauthenticated,
+
+    /// Authorization failed. The connection is valid but does not have the necessary permissions.
+    forbidden,
+
+    /// The trigger is misconfigured. For example, a required setting is missing or invalid.
+    misconfigured,
+
+    /// The target system does not support a required feature or endpoint.
+    unsupported,
+
+    /// The target system is rate-limiting requests. Try again later.
+    rate-limit,
+
+    /// The request timed out. The target system did not respond in time.
+    timeout,
+
+    /// The target system is currently unavailable or unreachable.
+    unavailable,
+
+    /// An unexpected internal error occurred in the plugin.
+    internal-error,
+
+    /// The response from the external system could not be parsed or was in an invalid format.
+    malformed-response,
+
+    /// A catch-all for all other types of errors. Should include a descriptive message.
+    other,
+
+    /// Retry the request using a reference identifier.
+    retry-with-reference(reference-object),
+
+    /// Complete the current workflow execution.
+    complete-workflow,
+
+    /// Complete the parent step execution.
+    complete-parent,
+  }
+}
+
+
+interface triggers {
+  use types.{trigger-context, trigger-event, trigger-response, app-error};
+
+  trigger-ids: func() -> result<list<string>, app-error>;
+
+  // Get the input schema for a specific trigger
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The trigger-id is extracted from the context
+  input-schema: func(context: trigger-context) -> result<string, app-error>;
+
+  // Get the output schema for a specific trigger
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The trigger-id is extracted from the context
+  output-schema: func(context: trigger-context) -> result<string, app-error>;
+
+  // Fetch events
+  //
+  // There are some limitations to the function:
+  // - It must return a `trigger-response` within 30 seconds
+  // - It must return less than or equal to 100 `trigger-response.events`
+  // - It must not return more than 64 kB of data in the `trigger-response.store`
+  //
+  // If you need to fetch more events, you can return up to 100 events and then
+  // store the data needed for you to remember where you left off in the store.
+  // The next time the trigger is invoked, you can use the store to continue
+  // where you left off.
+  //
+  // If you do not pass the limitations the return value will be ignored. We
+  // will not handle any events and we persist the store that was returned in
+  // the response.
+  //
+  // That also means that you should implement your fetch event function in a
+  // way that it can be called multiple times using the same context and return
+  // the same events. That will ensure that the user that is building an
+  // integration with your trigger will not miss any events if your system is
+  // down for a short period of time.
+  fetch-events: func(context: trigger-context) -> result<trigger-response, app-error>;
+}
+
+interface actions {
+  use types.{action-context, action-response, app-error};
+
+  action-ids: func() -> result<list<string>, app-error>;
+
+  // Get the input schema for a specific action
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The action-id is extracted from the context
+  input-schema: func(context: action-context) -> result<string, app-error>;
+
+  // Get the output schema for a specific action
+  // Returns a JSON Schema Draft 2020-12 schema as a string
+  // The schema may vary based on the connection in the context
+  // The action-id is extracted from the context
+  output-schema: func(context: action-context) -> result<string, app-error>;
+
+  // Execute an action
+  //
+  // There are some limitations to the function:
+  // - It must return an `action-response` within 30 seconds
+  // - The serialized-output must be a valid JSON object serialized as a string
+  //
+  // Actions can perform various operations such as:
+  // - Making HTTP requests to external APIs
+  // - Processing and transforming data
+  // - Storing data for future use
+  // - Triggering other systems or workflows
+  //
+  // The action receives input data from the previous step and can return
+  // serialized output data to be passed to the next step in the workflow.
+  execute: func(context: action-context) -> result<action-response, app-error>;
+}
+
+interface environment {
+  // Get all environment variables
+  env-vars: func() -> list<tuple<string, string>>;
+  // Get a specific environment variable by name
+  env-var: func(name: string) -> option<string>;
+}
+
+interface http {
+  record response {
+    status: u16,
+    headers: headers,
+    body: string,
+  }
+
+  record request {
+    method: method,
+    url: string,
+    headers: headers,
+    body: string,
+  }
+
+  variant request-error {
+    other(string)
+  }
+
+  type headers = list<tuple<string, string>>;
+
+  resource request-builder {
+    constructor();
+
+    method: func(method: method) -> request-builder;
+    url: func(url: string) -> request-builder;
+
+    // Add a header to the request
+    header: func(key: string, value: string) -> request-builder;
+    headers: func(headers: list<tuple<string, string>>) -> request-builder;
+
+    // Add a body to the request
+    body: func(body: string) -> request-builder;
+    // Add a binary body to the request
+    body-bytes: func(body: list<u8>) -> request-builder;
+
+    object: func() -> request;
+
+    // Send the request
+    send: func() -> result<response, request-error>;
+  }
+
+  variant method {
+    get,
+    post,
+    put,
+    delete,
+    patch,
+    options,
+    head,
+  }
+}
+
+interface file {
+  // HTTP headers for file requests (same as http interface)
+  type headers = list<tuple<string, string>>;
+
+  // Normalized file data
+  record file-data {
+    // Base64-encoded file content
+    base64: string,
+    // MIME type (e.g., "application/pdf")
+    content-type: string,
+    // Filename
+    filename: string,
+  }
+
+  variant file-error {
+    // Failed to fetch file from URL
+    fetch-failed(string),
+    // Invalid input format (not a valid URL, data URI, or base64)
+    invalid-input(string),
+    // Request timed out
+    timeout(string),
+    // Any other error
+    other(string),
+  }
+
+  // Normalize any file source to FileData
+  //
+  // The source is automatically detected:
+  // - URL: "https://example.com/file.pdf" - fetched with optional headers
+  // - Data URI: "data:application/pdf;base64,JVBERi0..." - parsed and extracted
+  // - Base64: Any other string is treated as raw base64 - decoded to detect type
+  //
+  // Parameters:
+  // - source: URL, data URI, or base64-encoded content
+  // - headers: Optional HTTP headers for URL requests (e.g., Authorization)
+  // - filename: Optional filename override (auto-detected if not provided)
+  //
+  // Returns file-data which will be processed by the platform:
+  // 1. Fields with format: "file-output" in the output schema are identified
+  // 2. File data is uploaded using the configured file_uploader
+  // 3. The file-data is replaced with the blob ID in the response
+  normalize: func(source: string, headers: option<headers>, filename: option<string>) -> result<file-data, file-error>;
+}
+
+world bridge {
+  import http;
+  import environment;
+  import file;
+  export triggers;
+  export actions;
+}

data/lib/app_bridge/app.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "timeout"
 
 module AppBridge
@@ -25,9 +26,13 @@ module AppBridge
     def execute_action(context)
       response = request_action_with_timeout(context)
 
-      validate_action_response_size!(response.serialized_output)
+      # Process files: find file-output fields in schema and replace with blob IDs
+      processed_output = process_files(response.serialized_output, context)
 
-      response
+      validate_action_response_size!(processed_output)
+
+      # Return new response with processed output
+      response.with_output(processed_output)
     end
 
     def timeout_seconds
@@ -65,5 +70,19 @@ module AppBridge
         _rust_fetch_events(context)
       end
     end
+
+    # Process files in the response based on output schema
+    def process_files(serialized_output, context)
+      data = JSON.parse(serialized_output)
+      schema = parse_output_schema(context)
+      JSON.generate(FileProcessor.call(data, schema))
+    rescue JSON::ParserError
+      # Schema parsing failed, return original output
+      serialized_output
+    end
+
+    def parse_output_schema(context)
+      JSON.parse(action_output_schema(context))
+    end
   end
 end

data/lib/app_bridge/file_processor.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AppBridge
+  # Processes file data from WASM component responses.
+  #
+  # Uses the output schema to find fields with format: "file-output" and
+  # replaces the file data (base64, content_type, filename) with blob IDs
+  # via the configured file_uploader.
+  #
+  # The WASM component should use file.read to normalize any input format
+  # (URL, data URI, raw base64) into a consistent hash structure before output.
+  class FileProcessor
+    FILE_OUTPUT_FORMAT = "file-output"
+
+    # Process file data in a response hash.
+    #
+    # @param data [Hash] The response data from a WASM component
+    # @param schema [Hash] The JSON schema for the response data
+    # @return [Hash] The processed data with file IDs instead of file data
+    def self.call(data, schema)
+      new(data, schema).call
+    end
+
+    # @param data [Hash] The response data from a WASM component
+    # @param schema [Hash] The JSON schema for the response data
+    def initialize(data, schema)
+      @data = deep_dup(data)
+      @schema = schema
+    end
+
+    # Processes the data, uploading files and replacing file data with IDs.
+    #
+    # @return [Hash] The processed data with file IDs
+    def call
+      process_node(@data, @schema)
+      @data
+    end
+
+    private
+
+    def process_node(data_node, schema_node)
+      return unless data_node.is_a?(Hash) && schema_node.is_a?(Hash)
+
+      properties = schema_node["properties"]
+      return unless properties.is_a?(Hash)
+
+      properties.each do |key, sub_schema|
+        process_property(data_node, key, sub_schema)
+      end
+    end
+
+    def process_property(data_node, key, sub_schema)
+      data_value, actual_key = find_data_value(data_node, key)
+      return if data_value.nil?
+
+      if sub_schema["format"] == FILE_OUTPUT_FORMAT
+        process_file_field(data_node, actual_key, data_value)
+      elsif array_schema?(sub_schema)
+        process_array_field(data_value, sub_schema)
+      elsif data_value.is_a?(Hash)
+        process_node(data_value, sub_schema)
+      end
+    end
+
+    def find_data_value(data_node, key)
+      str_key = key.to_s
+      return [nil, nil] unless data_node.key?(str_key)
+
+      [data_node[str_key], str_key]
+    end
+
+    def process_file_field(data_node, actual_key, data_value)
+      return unless file_data?(data_value)
+
+      blob_id = upload_file(data_value)
+      data_node[actual_key] = blob_id
+    end
+
+    def array_schema?(sub_schema)
+      sub_schema["type"] == "array" && sub_schema["items"].is_a?(Hash)
+    end
+
+    def process_array_field(data_value, sub_schema)
+      return unless data_value.is_a?(Array)
+
+      items_schema = sub_schema["items"]
+      data_value.each_with_index do |item, index|
+        if items_schema["format"] == FILE_OUTPUT_FORMAT && file_data?(item)
+          data_value[index] = upload_file(item)
+        else
+          process_node(item, items_schema)
+        end
+      end
+    end
+
+    def file_data?(value)
+      return false unless value.is_a?(Hash)
+
+      present?(value["base64"]) && present?(value["filename"])
+    end
+
+    def upload_file(file_data)
+      result = AppBridge.file_uploader.call(file_data)
+      # If uploader returns nil (no uploader configured), leave data unchanged
+      result.nil? ? file_data : result
+    rescue StandardError => e
+      raise AppBridge::InternalError, "Failed to upload '#{file_data["filename"]}': #{e.message}"
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
+    # Deep duplicates the object and normalizes all hash keys to strings
+    def deep_dup(obj)
+      case obj
+      when Hash then obj.transform_keys(&:to_s).transform_values { |v| deep_dup(v) }
+      when Array then obj.map { |v| deep_dup(v) }
+      else safe_dup(obj)
+      end
+    end
+
+    def safe_dup(obj)
+      obj.dup
+    rescue TypeError
+      obj
+    end
+  end
+end

data/lib/app_bridge/version.rb

@@ -4,5 +4,5 @@
 # ext/app_bridge/Cargo.toml file to keep them in sync.
 
 module AppBridge
-  VERSION = "3.0.0"
+  VERSION = "4.1.0"
 end

data/lib/app_bridge.rb

@@ -2,13 +2,38 @@
 
 require_relative "app_bridge/version"
 require_relative "app_bridge/app"
+require_relative "app_bridge/file_processor"
 
+# Communication layer for Standout integration apps using WebAssembly components.
 module AppBridge
   class Error < StandardError; end
   class TimeoutError < Error; end
   class TooManyEventsError < Error; end
   class StoreTooLargeError < Error; end
   class ActionResponseTooLargeError < Error; end
+  class InternalError < Error; end
+
+  class << self
+    # Configurable file uploader callback.
+    # The platform should set this to handle file uploads and return an ID.
+    #
+    # @example Configure with ActiveStorage
+    #   AppBridge.file_uploader = ->(file_data) {
+    #     content = Base64.decode64(file_data['base64'])
+    #     blob = ActiveStorage::Blob.create_and_upload!(
+    #       io: StringIO.new(content),
+    #       filename: file_data['filename'],
+    #       content_type: file_data['content_type'] || 'application/octet-stream'
+    #     )
+    #     blob.signed_id  # Returns just the ID
+    #   }
+    attr_accessor :file_uploader
+  end
+
+  # Default no-op uploader (returns nil - no file storage configured)
+  # rubocop:disable Style/NilLambda
+  self.file_uploader = ->(_file_data) { nil }
+  # rubocop:enable Style/NilLambda
 
   # Represents a trigger event that is recieved from the app.
   class TriggerEvent

data/tasks/fixtures.rake

@@ -2,7 +2,7 @@
 
 require "English"
 
-namespace :fixtures do # rubocop:disable Metrics/BlockLength
+namespace :fixtures do
   namespace :apps do
     desc "Clean up build artifacts"
     task :clean do
@@ -37,8 +37,22 @@ namespace :fixtures do # rubocop:disable Metrics/BlockLength
       Process.wait(pid)
       raise "Failed to build artifacts" unless $CHILD_STATUS.success?
     end
+
+    desc "Compile the v3 fixture app (for backward compatibility testing)"
+    task :compile_rust_v3 do
+      pwd = "spec/fixtures/components/rust_app_v3"
+      next unless File.exist?(pwd)
+
+      compile_pid = Process.spawn("cargo clean && cargo build --release --target wasm32-wasip2",
+                                  chdir: pwd)
+      Process.wait(compile_pid)
+      raise "Failed to build v3 artifacts" unless $CHILD_STATUS.success?
+
+      move_pid = Process.spawn("mv #{pwd}/target/wasm32-wasip2/release/rust_app_v3.wasm #{pwd}/../rust_app_v3.wasm")
+      Process.wait(move_pid)
+    end
   end
 end
 
 desc "Build all fixtures"
-task fixtures: %i[fixtures:apps:clean fixtures:apps:compile_rust fixtures:apps:compile_js]
+task fixtures: %i[fixtures:apps:clean fixtures:apps:compile_rust fixtures:apps:compile_js fixtures:apps:compile_rust_v3]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: app_bridge
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.1.0
 platform: aarch64-linux
 authors:
 - Alexander Ross
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 2026-02-10 00:00:00.000000000 Z
 dependencies: []
 description: The app_bridge gem is designed to enable seamless interaction with WebAssembly
   components that adhere to the WIT specification `standout:app`. It is developed
@@ -26,11 +26,14 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
-- ext/app_bridge/wit/world.wit
+- ext/app_bridge/wit/v3/world.wit
+- ext/app_bridge/wit/v4/world.wit
+- ext/app_bridge/wit/v4_1/world.wit
 - lib/app_bridge.rb
 - lib/app_bridge/3.2/app_bridge.so
 - lib/app_bridge/3.4/app_bridge.so
 - lib/app_bridge/app.rb
+- lib/app_bridge/file_processor.rb
 - lib/app_bridge/version.rb
 - sig/app_bridge.rbs
 - tasks/fixtures.rake