Developer KB
Build-time generated documentation for if.bus + if.api. No runtime fetches. Search and section nav are client-side only.
This document is build-time generated from registry data, schema scaffolds, and the KB config file. It is static and does not fetch data at runtime.
flowchart TD
if_api["if.api"]
if_api_adapter["if.api.adapter"]
if_api_adapter_spec["if.api.adapter_spec"]
if_bus_blog_medium_import_request["if.bus.blog.medium_import_request"]
if_bus_blog_medium_import_result["if.bus.blog.medium_import_result"]
if_bus_carrier["if.bus.carrier"]
if_bus_carrier_manifest["if.bus.carrier_manifest"]
if_bus_runtime["if.bus.runtime"]
if_trace["if.trace"]
if_api_adapter -.-> if_api_adapter_spec
if_api_adapter_spec --> if_api_adapter
if_api_adapter_spec --> if_bus_carrier_manifest
if_bus_blog_medium_import_request -.-> if_api
if_bus_blog_medium_import_request -.-> if_bus_runtime
if_bus_blog_medium_import_result -.-> if_api
if_bus_blog_medium_import_result -.-> if_bus_runtime
if_bus_blog_medium_import_result -.-> if_trace
if_bus_carrier -.-> if_api_adapter_spec
if_bus_carrier -.-> if_bus_carrier_manifest
if_bus_carrier_manifest --> if_bus_carrier
if_bus_carrier_manifest -.-> if_api_adapter_specFields:
carrier_id (string): Stable carrier identifier.label (string): Human-readable carrier label.provider (string): Source vendor or platform providing the carrier.summary (string): One-sentence description of what the carrier enables.status (string): Carrier readiness status.category (string): Carrier family.capabilities (array): Key capabilities exposed by the carrier.docs_url (string): Public documentation link for the carrier.demo_share_id (string): Optional public demo shareId (if available).Example:
{
"capabilities": [
"send",
"status",
"audit_log"
],
"carrier_id": "docusign",
"category": "connector",
"demo_share_id": "HmlXcqae8heBq1siMrIRyw",
"docs_url": "https://developers.docusign.com/",
"label": "DocuSign",
"provider": "DocuSign",
"status": "preview",
"summary": "Send and track signature envelopes with receipt-backed outputs."
}Fields:
schema_version (string): Schema version for the manifest payload.generated_utc (string): UTC timestamp when the manifest was generated.carriers (array): Carrier entries included in the manifest.source (object)Example:
{
"carriers": [
{
"capabilities": [
"send",
"status",
"audit_log"
],
"carrier_id": "docusign",
"category": "connector",
"demo_share_id": "HmlXcqae8heBq1siMrIRyw",
"docs_url": "https://developers.docusign.com/",
"label": "DocuSign",
"provider": "DocuSign",
"status": "preview",
"summary": "Send and track signature envelopes with receipt-backed outputs."
}
],
"generated_utc": "2026-01-07T16:30:00Z",
"schema_version": "1.0.0",
"source": {
"inventory_path": "docs/32-if-api-integrations-inventory.md",
"notes": "Inventory-driven carrier list."
}
}Fields:
schema_id (string)schema_version (string)request_id (string): Stable request identifier (recommended: ULID/UUID).requested_utc (string): UTC timestamp when the request was created.source (object)transform (object)output_hint (object): Optional desired output metadata (informational only; no runtime requirement).Example:
{
"output_hint": {
"desired_url": "https://infrafabric.io/static/hosted/blog/medium-import/fire-the-nanny-hire-an-adult-called-grok.html",
"kind": "file"
},
"request_id": "req-01JHZZZZZZZZZZZZZZZZZZZZZZ",
"requested_utc": "2026-01-16T00:00:00Z",
"schema_id": "if.bus.blog.medium_import_request",
"schema_version": "1.0.0",
"source": {
"api_url": "https://infrafabric.io/blog/wp-json/wp/v2/posts?slug=fire-the-nanny-hire-an-adult-called-grok",
"kind": "wordpress",
"modified_gmt": "2026-01-16T00:00:00",
"post_id": 5,
"post_url": "https://infrafabric.io/blog/fire-the-nanny-hire-an-adult-called-grok/",
"slug": "fire-the-nanny-hire-an-adult-called-grok"
},
"transform": {
"max_links_per_paragraph": 3,
"notes": "Transform is deterministic; goal is to reduce Medium import drop-risk for link-heavy lists.",
"rewrite_ul_link_lists": true,
"ruleset": "medium_import.v1"
}
}Fields:
schema_id (string)schema_version (string)request_id (string)built_utc (string)source (object)output (object)transform_report (object)receipts (array): Optional receipt references (integrity receipts, not truth claims).Example:
{
"built_utc": "2026-01-16T00:00:10Z",
"output": {
"bytes": 6789,
"media_type": "text/html",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"url": "https://infrafabric.io/static/hosted/blog/medium-import/fire-the-nanny-hire-an-adult-called-grok.html"
},
"receipts": [
{
"kind": "if.trace",
"share_id": "w2YyNAaHDBDUUayAVeLGCw"
}
],
"request_id": "req-01JHZZZZZZZZZZZZZZZZZZZZZZ",
"schema_id": "if.bus.blog.medium_import_result",
"schema_version": "1.0.0",
"source": {
"api_url": "https://infrafabric.io/blog/wp-json/wp/v2/posts?slug=fire-the-nanny-hire-an-adult-called-grok",
"kind": "wordpress",
"modified_gmt": "2026-01-16T00:00:00",
"post_id": 5,
"post_url": "https://infrafabric.io/blog/fire-the-nanny-hire-an-adult-called-grok/",
"slug": "fire-the-nanny-hire-an-adult-called-grok",
"source_bytes": 12345,
"source_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"transform_report": {
"li_items_rewritten": 12,
"notes": [
"Heuristic rewrite: link-heavy UL blocks become paragraphs to reduce Medium import drop-risk."
],
"ruleset": "medium_import.v1",
"ul_blocks_rewritten": 2,
"ul_blocks_seen": 2
}
}Fields:
adapter_id (string): Stable adapter identifier.provider (string): Vendor or platform name.label (string): Human-readable adapter label.version (string): Adapter spec version string.base_url (string): Primary API base URL.auth (object)capabilities (array): High-level capabilities exposed by the adapter.webhooks (array)status (string): Adapter readiness status.Example:
{
"adapter_id": "docusign",
"auth": {
"scopes": [
"signature",
"envelope.read"
],
"type": "oauth2"
},
"base_url": "https://demo.example.invalid/api",
"capabilities": [
"send",
"status",
"audit_log"
],
"label": "DocuSign API",
"provider": "DocuSign",
"status": "preview",
"version": "2026-01",
"webhooks": [
{
"delivery": "webhook",
"event": "completed",
"name": "envelope.completed"
}
]
}Fields:
spec_id (string): Stable identifier for the adapter spec payload.adapter (ref: adapter.schema.json)carrier_manifest_ref (string): Reference to the carrier manifest used to build the adapter.endpoints (array)constraints (object)Example:
{
"adapter": {
"adapter_id": "docusign",
"auth": {
"scopes": [
"signature",
"envelope.read"
],
"type": "oauth2"
},
"base_url": "https://demo.example.invalid/api",
"capabilities": [
"send",
"status",
"audit_log"
],
"label": "DocuSign API",
"provider": "DocuSign",
"status": "preview",
"version": "2026-01",
"webhooks": [
{
"delivery": "webhook",
"event": "completed",
"name": "envelope.completed"
}
]
},
"carrier_manifest_ref": "schemas/if-bus/carrier_manifest.schema.json",
"constraints": {
"max_payload_bytes": 1048576,
"rate_limit": "60/min"
},
"endpoints": [
{
"method": "POST",
"name": "create_envelope",
"path": "/envelopes",
"summary": "Create a signature envelope."
},
{
"method": "GET",
"name": "get_status",
"path": "/envelopes/{id}",
"summary": "Fetch envelope status."
}
],
"spec_id": "if-api-docusign-2026-01"
}https://infrafabric.io/static/trace/U2USOHGE8j715whbmsBr0Q
https://infrafabric.io/static/hosted/review/if-api-adobe-sign-demo/2026-01-07/index.html
https://infrafabric.io/static/trace/HmlXcqae8heBq1siMrIRyw
https://infrafabric.io/static/hosted/review/if-api-docusign-demo/2026-01-07/index.html
https://infrafabric.io/static/trace/Z7cho6wS6grqOFVqfAQpSw
https://infrafabric.io/static/hosted/review/if-api-workato-demo/2026-01-07/index.html
Path: scripts/if_api_adobe_sign_demo.py (lines 44-61)
def build_input_payload() -> dict:
return {
"integration": "adobe.sign",
"schema_version": "demo.v1",
"requested_at": CREATED_AT,
"requested": [
{
"agreement_name": "Demo NDA",
"document_name": "demo-nda.pdf",
"signers": [
{"role": "signer", "email": "alpha@example.com"},
{"role": "counter_signer", "email": "beta@example.com"},
],
"signature_type": "electronic",
}
],
"note": "synthetic mapping; no live Adobe Sign API call in this demo",
}Path: scripts/if_api_docusign_demo.py (lines 44-61)
def build_input_payload() -> dict:
return {
"integration": "docusign",
"schema_version": "demo.v1",
"requested_at": CREATED_AT,
"requested": [
{
"envelope_name": "Demo Agreement",
"document_name": "demo-agreement.pdf",
"recipients": [
{"role": "signer", "email": "alpha@example.com"},
{"role": "cc", "email": "beta@example.com"},
],
"signature_type": "electronic",
}
],
"note": "synthetic mapping; no live DocuSign API call in this demo",
}Path: scripts/if_api_workato_demo.py (lines 67-83)
def build_output_payload(input_bytes: bytes, input_data: dict) -> dict:
mapping = {
"rcp_3101": {
"trigger": "salesforce.new_lead",
"action": "slack.post_message",
"status": "enabled",
"owner": "demo.builder@example.com",
"link": "https://www.workato.com/recipes/3101",
},
"rcp_3102": {
"trigger": "github.issue_opened",
"action": "google.sheets.append_row",
"status": "paused",
"owner": "demo.builder@example.com",
"link": "https://www.workato.com/recipes/3102",
},
}Path: scripts/build_blog_medium_import_pipeline.py (lines 86-142)
_BLOCK_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
_UL_BLOCK_RE = re.compile(r"<ul\b[^>]*>.*?</ul>", re.IGNORECASE | re.DOTALL)
_LI_RE = re.compile(r"<li\b[^>]*>(.*?)</li>", re.IGNORECASE | re.DOTALL)
_TAG_RE = re.compile(r"<[^>]+>")
def _strip_tags(fragment: str) -> str:
return html.unescape(_TAG_RE.sub("", fragment or "")).strip()
def _is_link_heavy_list(li_html: list[str]) -> bool:
if len(li_html) < 2:
return False
linkish = 0
for item in li_html:
if "<a" not in item.lower():
continue
text = _strip_tags(item)
if 0 < len(text) <= 160:
linkish += 1
# Heuristic: Medium import tends to drop UL blocks that read like "here is a list of links".
return (linkish / max(1, len(li_html))) >= 0.75
def _rewrite_ul_link_lists_to_paragraphs(html_in: str) -> tuple[str, dict]:
html_in = _BLOCK_COMMENT_RE.sub("", html_in or "")
report = {"ul_blocks_seen": 0, "ul_blocks_rewritten": 0, "li_items_rewritten": 0}
def _rewrite(match: re.Match[str]) -> str:
ul_block = match.group(0)
report["ul_blocks_seen"] += 1
li_items = _LI_RE.findall(ul_block)
if not li_items:
return ul_block
if not _is_link_heavy_list(li_items):
return ul_block
report["ul_blocks_rewritten"] += 1
report["li_items_rewritten"] += len(li_items)
out_parts: list[str] = []
for item in li_items:
item = item.strip()
if not item:
continue
out_parts.append(f"<p>{item}</p>")
return "\n".join(out_parts) + "\n"
html_out = _UL_BLOCK_RE.sub(_rewrite, html_in)
return html_out, report
Path: scripts/build_blog_medium_import_pipeline.py (lines 171-204)
*,
producer_id: str,
producer_version: str,
event_name: str,
topic: str,
partition_key: str,
subject_kind: str,
subject_id: str,
payload: dict,
causation_id: str | None = None,
correlation_id: str | None = None,
) -> dict:
payload_bytes = canonical_json_bytes(payload)
env: dict = {
"schema_id": "if.bus.envelope",
"schema_version": "1.0.0",
"event_id": new_event_id(),
"emitted_utc": now_utc_iso(),
"producer": {"kind": "if.api.adapter", "id": producer_id, "version": producer_version},
"event": {"name": event_name},
"subject": {"kind": subject_kind, "id": subject_id},
"routing": {"topic": topic, "partition_key": partition_key, "priority": 5, "ttl_seconds": 86400},
"payload_media_type": "application/json",
"payload": payload,
"payload_sha256": sha256_hex(payload_bytes),
"extensions": {},
}
if causation_id or correlation_id:
corr = {"correlation_id": correlation_id or (causation_id or env["event_id"])}
if causation_id:
corr["causation_id"] = causation_id
env["correlation"] = corr
return env