app_bridge 4.0.0-x86_64-linux → 5.0.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2ef17c1b654b1c1b81501984696d28346c42c3650759cad8e28f1ce10fdb427
-  data.tar.gz: 366015ee7c93a0dab3a90573994d83913083b7661f5cc5617d44137db019333c
+  metadata.gz: 42a6e98398ec928fdd633a6062f47600331ddee76382366fafbc87b5fcecc2f4
+  data.tar.gz: de9cb9e4c3169a3f9e70d57eff0a585dc7bc0620fb29e1cc7aa5aab412093728
 SHA512:
-  metadata.gz: bf5c9d65f7f7bc6849455f23e1502c4ef917de7df323ae407c6195d34c0697b15502351c301f831da8c736a21a63afaf4d9613fe3510bbbc256e52e047290dbf
-  data.tar.gz: 5a4e1c0a5c04fd3ac2c30696bd6c59c6f5d953918add386094e622e63e989f796dc9a84410c0483345cec6fee8de10d0772a5db6163d9cdd325ccb7764feab1f
+  metadata.gz: 2dd0825cdcba66bd2862ba78937e8f5ccb58856f95c503a9fb25577c5c4f49540c3a6ff15e91c8c2a0e21a0d94062b6f60506070695d04a5cba75d8c5a55e675
+  data.tar.gz: 0aff9c1d8fe5ac5c0f85303e50dc13df59848d11e5559b9cf86a197af01a93d74ddd813fa640d32a9959e65ab27efa01ce792827bbae23dfe8d47d4fceba25f9

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.8
+ruby 3.4.9

data/README.md

@@ -103,6 +103,67 @@ AppBridge.file_uploader = ->(file_data) {
 
 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.
@@ -244,6 +305,12 @@ impl v5::standout::app::new_feature::Host for AppState {
 - **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
 
+- **Connections interface** (WIT 5.0.0+): Embeds `connection-config` JSON in WASM; platform extracts it at version upload
+
+## Connection configuration (WIT 5)
+
+Connectors embed `connection-config.json` via `include_str!` and export it through the `connections` interface. Integrationer reads it **once when the WASM version is saved**, validates against [connection-config-schema.json](ext/app_bridge/docs/connection-config-schema.json), and stores it on the version. Runtime connection flows use the stored JSON, not a live WASM call.
+
 ## Development
 
 To contribute or modify this gem, ensure you have the following dependencies installed:

data/Rakefile

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
 require "rb_sys/extensiontask"
 
 task build: :compile
@@ -17,12 +11,21 @@ RbSys::ExtensionTask.new("app_bridge", GEMSPEC) do |ext|
   ext.lib_dir = "lib/app_bridge"
 end
 
-# Load all project specific rake tasks
-Dir.glob(File.expand_path("tasks/**/*.rake", __dir__)).each { |file| load file }
+if ENV.key?("RUBY_TARGET")
+  task default: :compile
+else
+  require "rspec/core/rake_task"
+  require "rubocop/rake_task"
 
-# Set test mode environment variable for specs
-RSpec::Core::RakeTask.new(:spec) do |_t|
-  ENV["APP_BRIDGE_TEST_MODE"] = "1"
-end
+  RuboCop::RakeTask.new
 
-task default: %i[fixtures compile rust:test spec rubocop]
+  # Load all project specific rake tasks
+  Dir.glob(File.expand_path("tasks/**/*.rake", __dir__)).each { |file| load file }
+
+  # Set test mode environment variable for specs
+  RSpec::Core::RakeTask.new(:spec) do |_t|
+    ENV["APP_BRIDGE_TEST_MODE"] = "1"
+  end
+
+  task default: %i[fixtures compile rust:test spec rubocop]
+end

data/ext/app_bridge/docs/connection-config-schema.json

@@ -0,0 +1,500 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:standout:schemas:connection-config:2",
+  "title": "Connection Config",
+  "description": "Declares how a connector authenticates and what runtime data the platform passes to actions/triggers. OAuth uses RFC 8414 authorization_server metadata and RFC 9728 protected_resource at the top level, with Standout-specific oauth_client credentials and platform hooks alongside. Generated at connector build time (see base-connector-tools). The platform does not fetch well-known metadata at runtime.",
+  "type": "object",
+  "required": ["strategies", "default_strategy", "runtime"],
+  "properties": {
+    "protected_resource": {
+      "$ref": "#/$defs/protected_resource",
+      "description": "RFC 9728 protected resource metadata for the API. runtime.base_url defaults to resource when omitted."
+    },
+    "strategies": {
+      "type": "array",
+      "minItems": 0,
+      "description": "Connection strategies. An empty array disables WASM-driven connections.",
+      "items": { "$ref": "#/$defs/strategy" }
+    },
+    "default_strategy": {
+      "type": "string",
+      "description": "ID of the strategy used when connecting"
+    },
+    "connection_schema": {
+      "type": "object",
+      "description": "JSON Schema for user input before connection (shared fallback). Field values listed in strategy storage are available as {{field}} in templates."
+    },
+    "runtime": {
+      "$ref": "#/$defs/runtime",
+      "description": "Default runtime payload merged with strategy.runtime. Headers and optional base_url override."
+    },
+    "post_connect": { "$ref": "#/$defs/post_connect_hook" }
+  },
+  "$defs": {
+    "templated_value": {
+      "description": "Literal string or template resolved by the platform. Use {{field}} for connection storage keys and {{env:NAME}} for app environment variables.",
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["template"],
+          "additionalProperties": false,
+          "properties": {
+            "template": {
+              "type": "string",
+              "description": "e.g. Bearer {{access_token}}, {{username}}:{{password}}, {{env:CLIENT_ID}}"
+            },
+            "as": {
+              "enum": ["basic_authorization"],
+              "description": "Interpolate template then encode as HTTP Basic (Basic + Base64)"
+            }
+          }
+        }
+      ]
+    },
+    "templated_uri": {
+      "description": "Static URI or template that resolves to a URI at runtime",
+      "oneOf": [
+        { "type": "string", "format": "uri" },
+        {
+          "type": "object",
+          "required": ["template"],
+          "additionalProperties": false,
+          "properties": {
+            "template": {
+              "type": "string",
+              "description": "e.g. https://api.example.com/v1, https://{{subdomain}}.example.com/api, {{env:API_BASE_URL}}"
+            }
+          }
+        }
+      ]
+    },
+    "protected_resource": {
+      "type": "object",
+      "description": "RFC 9728 OAuth Protected Resource Metadata",
+      "required": ["resource", "authorization_servers"],
+      "properties": {
+        "resource": {
+          "type": "string",
+          "format": "uri",
+          "description": "API resource identifier (typically the API base URL)"
+        },
+        "authorization_servers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "format": "uri" },
+          "description": "Issuer URLs of authorization servers that can issue tokens for this resource"
+        },
+        "scopes_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Scopes supported when accessing this resource"
+        },
+        "bearer_methods_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "e.g. header"
+        }
+      }
+    },
+    "authorization_server": {
+      "type": "object",
+      "description": "RFC 8414 OAuth Authorization Server Metadata (server capabilities and endpoints)",
+      "required": ["issuer", "token_endpoint"],
+      "properties": {
+        "issuer": {
+          "type": "string",
+          "format": "uri",
+          "description": "Authorization server issuer identifier"
+        },
+        "authorization_endpoint": {
+          "type": "string",
+          "format": "uri",
+          "description": "OAuth authorization endpoint"
+        },
+        "token_endpoint": {
+          "type": "string",
+          "format": "uri",
+          "description": "OAuth token endpoint"
+        },
+        "response_types_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "e.g. code"
+        },
+        "grant_types_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "e.g. authorization_code, refresh_token, client_credentials"
+        },
+        "scopes_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Scopes the authorization server supports"
+        },
+        "code_challenge_methods_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "PKCE methods supported, e.g. S256"
+        },
+        "token_endpoint_auth_methods_supported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "e.g. client_secret_basic, client_secret_post"
+        },
+        "revocation_endpoint": {
+          "type": "string",
+          "format": "uri"
+        },
+        "introspection_endpoint": {
+          "type": "string",
+          "format": "uri"
+        },
+        "registration_endpoint": {
+          "type": "string",
+          "format": "uri"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "required": ["grant_types_supported"],
+            "properties": {
+              "grant_types_supported": {
+                "type": "array",
+                "contains": { "const": "client_credentials" },
+                "not": { "contains": { "const": "authorization_code" } }
+              }
+            }
+          },
+          "then": {},
+          "else": {
+            "required": ["authorization_endpoint"]
+          }
+        }
+      ]
+    },
+    "oauth_client": {
+      "type": "object",
+      "description": "Standout client registration and OAuth request choices (not part of RFC 8414)",
+      "required": ["client_id", "client_secret"],
+      "properties": {
+        "grant_type": {
+          "enum": ["authorization_code", "client_credentials"],
+          "default": "authorization_code",
+          "description": "OAuth grant used when connecting"
+        },
+        "response_type": {
+          "type": "string",
+          "default": "code",
+          "description": "Override response_type; defaults to code or first response_types_supported"
+        },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Fixed scope list when scopes_from_field is not used"
+        },
+        "scopes_from_field": {
+          "type": "string",
+          "description": "Connection form field containing selected scopes (array of strings)"
+        },
+        "scopes_always_include": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Scopes always appended to scopes_from_field"
+        },
+        "client_id": {
+          "$ref": "#/$defs/templated_value",
+          "description": "OAuth client_id, e.g. {{env:OAUTH_CLIENT_ID}}"
+        },
+        "client_secret": {
+          "$ref": "#/$defs/templated_value",
+          "description": "OAuth client_secret, e.g. {{env:OAUTH_CLIENT_SECRET}}"
+        },
+        "authorization_parameters": {
+          "type": "object",
+          "description": "Extra query parameters appended to the authorization request",
+          "additionalProperties": { "type": "string" }
+        },
+        "authorization_parameters_from_form": {
+          "type": "object",
+          "description": "Map connection form field values to authorization query parameters",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          }
+        },
+        "token_request_method": {
+          "enum": ["POST", "GET"],
+          "default": "POST"
+        },
+        "token_request_parameters": {
+          "type": "object",
+          "description": "Extra parameters sent to the token endpoint",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "strategy": {
+      "type": "object",
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": {
+          "type": "string",
+          "description": "Label shown when the user picks authentication type before connecting"
+        },
+        "type": {
+          "enum": ["oauth2", "basic_auth", "api_key", "session", "none", "custom"]
+        },
+        "authorization_server": {
+          "$ref": "#/$defs/authorization_server",
+          "description": "RFC 8414 metadata (required when type is oauth2)"
+        },
+        "oauth_client": {
+          "$ref": "#/$defs/oauth_client",
+          "description": "Client credentials and request options (required when type is oauth2)"
+        },
+        "session": {
+          "$ref": "#/$defs/session",
+          "description": "Session login configuration (required when type is session)"
+        },
+        "token_response": {
+          "$ref": "#/$defs/token_response",
+          "description": "Maps token response fields to storage keys. Optional for oauth2 — platform defaults to standard RFC 6749 field names."
+        },
+        "refresh": {
+          "$ref": "#/$defs/refresh",
+          "description": "Token refresh policy. Optional for oauth2 — platform defaults to enabled for authorization_code."
+        },
+        "storage": {
+          "description": "Fields persisted in connection storage. Array of keys or object with optional display titles. Available as {{field}} in runtime templates.",
+          "oneOf": [
+            {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            },
+            {
+              "type": "object",
+              "minProperties": 1,
+              "additionalProperties": { "$ref": "#/$defs/storage_field" }
+            }
+          ]
+        },
+        "connection_schema": {
+          "type": "object",
+          "description": "Strategy-specific pre-connection form schema (JSON Schema)"
+        },
+        "form_persist": {
+          "type": "object",
+          "description": "Map pre-connection form fields to account storage keys after connect",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "required": ["as"],
+                "properties": {
+                  "as": { "type": "string" },
+                  "join": {
+                    "type": "string",
+                    "description": "Join array values before persisting, e.g. a space for OAuth scopes"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "runtime": {
+          "$ref": "#/$defs/runtime",
+          "description": "Strategy-specific runtime override"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "oauth2" } },
+            "required": ["type"]
+          },
+          "then": { "required": ["authorization_server", "oauth_client"] }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "session" } },
+            "required": ["type"]
+          },
+          "then": { "required": ["session", "token_response"] }
+        }
+      ]
+    },
+    "session": {
+      "type": "object",
+      "required": ["token_endpoint"],
+      "additionalProperties": false,
+      "description": "HTTP request that creates an API session",
+      "properties": {
+        "token_endpoint": {
+          "$ref": "#/$defs/templated_uri",
+          "description": "Login URL that returns a session token"
+        },
+        "method": {
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          "default": "POST"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/templated_value" }
+        },
+        "body": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/templated_value" }
+        },
+        "body_format": {
+          "enum": ["json", "form"],
+          "default": "json"
+        },
+        "token_source": {
+          "enum": ["body", "header"],
+          "default": "body",
+          "description": "Whether token_response reads from JSON response body or a response header"
+        },
+        "token_header": {
+          "type": "string",
+          "description": "Response header name when token_source is header"
+        },
+        "success_status": {
+          "type": "array",
+          "items": { "type": "integer" },
+          "default": [200]
+        }
+      }
+    },
+    "token_response": {
+      "type": "object",
+      "description": "Maps token or session response fields to connection storage keys",
+      "properties": {
+        "access_token": { "type": "string" },
+        "refresh_token": { "type": "string" },
+        "expires_at": {
+          "type": "object",
+          "properties": {
+            "from": { "type": "string" },
+            "type": { "enum": ["relative_seconds", "absolute_timestamp", "iso8601"] }
+          }
+        }
+      }
+    },
+    "refresh": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "grant_type": { "enum": ["refresh_token", "client_credentials"] },
+        "token_endpoint": {
+          "$ref": "#/$defs/templated_uri",
+          "description": "Override authorization_server.token_endpoint for refresh"
+        },
+        "expires_latency": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Seconds to reduce token validity by before refresh (oauth2 expires_latency)"
+        }
+      }
+    },
+    "storage_field": {
+      "type": "object",
+      "description": "Storage field metadata for account display and connect forms.",
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Label shown for this field"
+        },
+        "description": {
+          "type": "string",
+          "description": "Help text shown on connect forms. Not persisted."
+        }
+      }
+    },
+    "post_connect_hook": {
+      "type": "object",
+      "description": "Platform-run validation after connect. Uses resolved runtime headers and base_url for the active strategy.",
+      "required": ["request"],
+      "properties": {
+        "request": {
+          "type": "object",
+          "properties": {
+            "method": {
+              "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+              "default": "GET"
+            },
+            "path": {
+              "type": "string",
+              "description": "Appended to runtime base_url, e.g. /v1/me"
+            },
+            "url": {
+              "$ref": "#/$defs/templated_uri",
+              "description": "Optional full URL override instead of base_url + path"
+            },
+            "body": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/templated_value" }
+            },
+            "body_format": {
+              "enum": ["json", "form"],
+              "default": "json"
+            }
+          },
+          "anyOf": [
+            { "required": ["path"] },
+            { "required": ["url"] }
+          ]
+        },
+        "success_status": {
+          "type": "array",
+          "items": { "type": "integer" },
+          "default": [200]
+        },
+        "persist": {
+          "type": "object",
+          "description": "Map response values to connection storage keys",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Dot path from response context, e.g. body.account.id"
+              },
+              {
+                "type": "object",
+                "required": ["from"],
+                "additionalProperties": false,
+                "properties": {
+                  "from": { "type": "string" },
+                  "as": { "enum": ["string"] }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "description": "Runtime payload for actions/triggers. base_url defaults to protected_resource.resource when omitted.",
+      "properties": {
+        "base_url": { "$ref": "#/$defs/templated_uri" },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/templated_value" }
+        },
+        "fields": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/templated_value" }
+        }
+      }
+    }
+  }
+}