Skip to main content

Integrations

Documentation Map​

Integrations

Internal Helpifyr Integrations​

jhf-spindle-wire-bundle-boundary​

  • Direction: bidirectional logical integration
  • Type: product-adapter
  • Surface: jhf-spindle dispatch webhooks into jhf-wire, signed callbacks back to callback.url, ${CLAWLEDGER_MCP_URL}/mcp
  • Auth: ingress uses INGRESS_AUTH_MODE (network-trust default, optional shared-secret via x-ingress-secret); callbacks use X-Signature and X-Idempotency-Key; MCP uses canonical X-JHF-Spindle-Key (legacy X-ClawLedger-Key still sent for transition)
  • Stability: stable
  • Versioning: bundle concept jhf-spindle-wire is stable; webhook path changes are breaking; callback fields evolve additive-only
  • Owner: shared boundary between jhf-spindle and jhf-wire

Implemented:

  • jhf-spindle remains dispatch origin and callback receiver.
  • jhf-wire remains provider bridge and workflow runtime.
  • Bundle contract is limited to webhook ingress, signed callbacks, and MCP import.

Planned:

  • no additional bundle-internal runtime path is approved.

jhf-spindle-dispatch-ingress​

  • Direction: incoming
  • Type: webhook
  • Surface: /webhook/clawledger/sepa/submit, /webhook/clawledger/bank/sync, /webhook/clawledger/invoice/dispatch, /webhook/clawledger/tax/submit
  • Auth: INGRESS_AUTH_MODE=network-trust by default; optional INGRESS_AUTH_MODE=shared-secret enforces x-ingress-secret header
  • Stability: stable
  • Versioning: path-stable and breaking on path change; auth mode switch is backward-compatible because network-trust remains default
  • Owner: jhf-wire

Implemented:

  • all ingress workflows include stable webhookId values.
  • all ingress workflows include Authorize Ingress guard node with shared-secret validation path.

Planned:

  • migration to shared-secret can be enabled per environment without path changes.

jhf-spindle-signed-callback​

  • Direction: outgoing
  • Type: callback
  • Surface: callback.url from dispatch payload
  • Auth: X-Signature, X-Idempotency-Key
  • Stability: stable
  • Versioning: callback payload is additive-only; target path ownership stays with jhf-spindle
  • Owner: jhf-wire sender and jhf-spindle receiver boundary

Implemented:

  • callback-emitting workflows enforce signed callback headers and contract vocabulary in fast tests.

Planned:

  • no alternate callback channel is approved.

External Integrations​

finapi-access-provider​

  • Direction: outgoing
  • Type: provider-contract
  • Surface: ${FINAPI_BASE_URL}/api/v2/oauth/token, ${FINAPI_BASE_URL}/api/v2/bankConnections, ${FINAPI_BASE_URL}/api/v2/accounts, ${FINAPI_BASE_URL}/api/v2/transactions, ${FINAPI_BASE_URL}/api/v2/pendingTransactions, ${FINAPI_BASE_URL}/api/v2/payments
  • Auth: OAuth2 bearer token
  • Stability: partial
  • Versioning: provider-managed API versioning under /api/v2
  • Owner: finAPI

Implemented:

  • OAuth and user-context banking paths are verified in repository tooling.

Planned:

  • provider business-data edge behavior remains external follow-up.

finapi-iban-name-check​

  • Direction: outgoing
  • Type: provider-contract
  • Surface: ${FINAPI_IBAN_NAME_CHECK_BASE_URL}/api/v1/ibanNameCheck
  • Auth: user-context bearer token
  • Stability: partial
  • Versioning: provider-managed API versioning under /api/v1
  • Owner: finAPI

Implemented:

  • request shape and auth path are verified.

Planned:

  • sandbox business edge handling remains provider follow-up.

jhf-selvage-compliance-provider (moved scope)​

  • Direction: outgoing from compliance tool
  • Type: provider-contract
  • Surface: maintained in jhf-selvage
  • Auth: maintained in jhf-selvage
  • Stability: work in progress
  • Versioning: moved out of jhf-wire
  • Owner: jhf-selvage

Implemented:

  • jhf-wire no longer owns the compliance/entity-screening runtime path.

Planned:

  • compliance connectors are delivered in jhf-selvage, not in jhf-wire.

storecove-delivery-provider​

  • Direction: outgoing
  • Type: provider-contract
  • Surface: ${STORECOVE_BASE_URL} plus workflow endpoint path
  • Auth: API key
  • Stability: planned
  • Versioning: provider-managed
  • Owner: Storecove

Implemented:

  • mock path and callback contract are Git-managed.

Planned:

  • productive credential onboarding and live activation are external/operator follow-up.

eric-submit-provider​

  • Direction: outgoing
  • Type: sidecar
  • Surface: ${ERIC_SERVICE_URL}
  • Auth: stack-internal
  • Stability: partial
  • Versioning: repo-managed wrapper compatibility
  • Owner: jhf-wire stack

Implemented:

  • ERiC service wrapper path is health-checked in stack smoke path.

Planned:

  • productive ELSTER credential onboarding remains operator follow-up.

Event Contracts​

dispatch-job-webhook-contract​

  • Direction: incoming
  • Type: execution-contract
  • Surface: jhf-spindle webhook payloads carrying dispatch_job, callback.url, document payloads, workflow metadata
  • Auth: follows ingress webhook auth posture (network-trust or optional shared-secret)
  • Stability: stable
  • Versioning: additive payload evolution only; path changes are breaking
  • Owner: shared contract between jhf-spindle and jhf-wire

signed-callback-result-contract​

  • Direction: outgoing
  • Type: execution-contract
  • Surface: signed callback body delivered to callback.url
  • Auth: X-Signature, X-Idempotency-Key
  • Stability: stable
  • Versioning: additive-only callback field posture
  • Owner: shared contract between jhf-wire and jhf-spindle

support-case-delivery-evidence-contract​

  • Direction: outgoing read-only projection
  • Type: file-contract
  • Surface: python scripts/validate_support_case_delivery.py --pretty -> artifacts/support-case-delivery-validation.json
  • Auth: no runtime auth; generated from repo-owned validation and callback contract
  • Stability: stable
  • Versioning: additive-only evidence fields under contract jhf-wire-support-case-delivery-v1
  • Owner: jhf-wire

Implemented:

  • support delivery evidence projection exists as a deterministic JSON artifact for Fabric case intake.
  • corner-case outcomes are explicit: delayed callback, duplicate callback, ack-lost recovery, evidence mismatch, degraded mode, operator-visible failure.

Planned:

  • jhf-fabric consumes this artifact as read-first intake; no jhf-wire write-back control path is approved.

MCP Integration​

jhf-spindle-mcp-bank-import​

  • Direction: outgoing
  • Type: mcp
  • Surface: ${CLAWLEDGER_MCP_URL}/mcp
  • Auth: canonical X-JHF-Spindle-Key (JHF_SPINDLE_MCP_API_KEY), with legacy fallback CLAWLEDGER_MCP_API_KEY
  • Stability: stable
  • Versioning: JSON-RPC tool contract is append-only by expectation
  • Owner: jhf-spindle MCP peer with jhf-wire as caller

Implemented:

  • normalized bank statement items are imported through this MCP path.

Planned:

  • no second MCP endpoint or write-back path is approved.

Planned Connections​

reed-module-adapter-manifest-v2​

  • Direction: outgoing read-only contract publication
  • Type: adapter-contract
  • Surface: contracts/reed/module-adapter-manifest.v2.json, schemas/reed_module_adapter_manifest_v2.schema.json, python scripts/validate_reed_adapter_manifest_v2.py --strict
  • Auth: no runtime auth; repository contract/evidence path only
  • Stability: stable (contract wave ACP-W1)
  • Versioning: schema version 2.0, adapter version family v2
  • Owner: jhf-wire for adapter contract truth, with external ownership boundaries to jhf-reed, helpifyr-fabric, jhf-warp, and jhf-heddle

Implemented:

  • jhf-wire publishes a sandbox-first adapter manifest v2 with explicit owner boundaries.
  • production send is documented as explicit-enable only (production_send_default_enabled=false).
  • strict verify path is wired into CI and release gate.

Planned:

  • no runtime adapter execution side effects are introduced in ACP-W1.

reed-sandbox-write-lanes-v1​

  • Direction: internal sandbox write simulation
  • Type: adapter-contract
  • Surface: contracts/reed/sandbox-write-lanes.v1.json, schemas/reed_sandbox_write_lanes_v1.schema.json, python scripts/validate_reed_sandbox_write_lanes.py --strict --emit-evidence artifacts/reed-sandbox-write-evidence.json
  • Auth: no productive credentials; sandbox-only simulated adapter lanes
  • Stability: active (ACP-W3 scope)
  • Versioning: contract version 1.0.0
  • Owner: jhf-wire

Implemented:

  • sandbox-only submission, receipt, rejection, and retry lanes are implemented as repo-owned contract and strict scenario validator.
  • duplicate idempotency, wrong recipient, timeout/retry, and production-send drift are fail-closed checks.
  • production send remains disabled in this wave (production_send_enabled=false).

Planned:

  • no productive dispatch/send activation in W3.

wire-outbound-delivery-event-model-w4​

  • Direction: outgoing read-only event-contract alignment
  • Type: adapter-contract
  • Surface: contracts/reed/outbound-delivery-event-model.w4.json, schemas/wire_outbound_delivery_event_model_w4.schema.json, python scripts/validate_outbound_delivery_event_model.py --strict
  • Auth: no productive credentials; read-only event model truth
  • Stability: active (ACP-W4)
  • Versioning: contract version 1.0.0, event wire.outbound_delivery.v1
  • Owner: jhf-wire (Fabric event truth owner remains helpifyr-fabric)

Implemented:

  • Wave-4 outbound-delivery event model contract is linked to jhf-wire#87.
  • strict fail-closed validator enforces manifest/event alignment and sandbox-only posture.
  • dependency on JaddaHelpifyr/jhf-loom#97 is explicit and blocks activation drift.

Planned:

  • productive event activation is deferred until Loom dependency closure.

wire-outbound-delivery-event-model-readback​

  • Direction: outgoing read-only
  • Type: event-contract
  • Surface: contracts/reed/outbound-delivery-event-model.w4.json
  • Auth: read-only artifact
  • Stability: active
  • Versioning: event key wire.outbound_delivery.v1 with schema 1.0.0
  • Owner: jhf-wire (event family truth consumption remains Fabric-governed)

oss-version-truth-governance​

  • Direction: internal read-only governance
  • Type: dependency-governance-contract
  • Surface: maintenance/oss-inventory.json, maintenance/oss-version-truth.json, maintenance/oss-upgrade-policy.json, maintenance/oss-drift-contract.json, maintenance/upgrade-paths.json, python scripts/check_oss_inventory_versions.py --strict, python scripts/check_oss_maintenance_contracts.py --strict
  • Auth: none (repo-local verifier contract)
  • Stability: stable
  • Versioning: inventory/truth/policy schema versioned in-file
  • Owner: jhf-wire

Implemented:

  • repo-owned OSS/runtime/CI package surfaces are inventorized and version-truth pinned.
  • repo-owned :latest image tags were removed from compose/runtime surfaces.
  • external ownership surfaces are explicitly classified (no shadow owner truth).

Planned:

  • cross-repo upgrade wave closure remains dependent on upstream owner issues listed in blocked_by.

fabric-read-context-intake​

  • Direction: outgoing read-only
  • Type: repo-read
  • Surface: fabric-manifest.json, docs/FABRIC_TOOL_PROFILE.md, python scripts/export-fabric-metadata.py
  • Auth: read-only artifact intake; no runtime write credentials
  • Stability: planned
  • Versioning: additive over manifest and status-export contracts
  • Owner: future jhf-fabric reader, current artifacts owned by jhf-wire

Implemented:

  • Fabric-relevant artifact inputs already exist in this repository.

Planned:

  • current verify path is read-first only, and no write-back is implemented.

fabric-governance-contract-consumer​

  • Direction: outgoing read-only
  • Type: other (fabric-contract-consumer)
  • Surface: GET /api/v1/contracts/matrix, GET /api/v1/contracts/docs-standard
  • Auth: none in current internal host topology (network-scoped read)
  • Stability: stable
  • Versioning: Fabric-owned family versions; jhf-wire accepts 1.0.0 for helpifyr-schema-governance-docs-standard and helpifyr-schema-governance-wiki-governance
  • Owner: jhf-fabric publishes governance truth, jhf-wire consumes and verifies read-only

Implemented:

  • canonical family declarations are tracked in fabric-manifest.json under fabric_contract_consumption.
  • runtime readback and readiness evidence are generated via python scripts/check_fabric_governance_surfaces.py --emit-evidence artifacts/fabric-governance-readiness.json.
  • no local producer-consumer matrix or local docs-standard version truth is authored in jhf-wire.

Planned:

  • no local fallback truth for Fabric governance families is approved.

fabric-combination-profiles-consumer​

  • Direction: incoming read-only context
  • Type: other (fabric-control-plane-read)
  • Surface: GET /api/v1/combinations/profiles from Fabric (FABRIC_COMBINATION_PROFILES_URL)
  • Auth: none in current internal host topology (network-scoped read)
  • Stability: stable
  • Versioning: Fabric-owned response schema under contract family fabric-combination-profiles
  • Owner: jhf-fabric publishes truth, jhf-wire consumes read-only

Implemented:

  • python scripts/check_fabric_combination_profiles.py --pretty consumes Fabric profile truth.
  • jhf-wire derives membership from Fabric payload only and does not create local bundle/detection truth.
  • bridge evidence drift is exposed as stale_or_mismatch without rewriting profile semantics.

Planned:

  • no local profile authoring or local detection-family fallback is approved.

Ingress Security Decision​

  • Ingress remains non-public and stack-internal.
  • Default auth mode remains network-trust for backward compatibility.
  • Optional hardened mode is shared-secret with required x-ingress-secret header.
  • If trusted network assumptions no longer hold, shared-secret mode becomes mandatory.

License: AGPLv3 Project website: https://helpifyr.com