hrea-integration_skill

Overview

This skill integrates a UI layer with the hREA GraphQL DNA to map local entities to the ValueFlows ontology and manage proposals, intents, and prerequisites. It provides mapping patterns, a pending queue mechanism for missing prerequisites, and event-driven retries to ensure eventual consistency. Use it to translate requests/offers into two-intent reciprocal proposals and to maintain agent and resource spec mappings.

How this skill works

The skill maps local entities (users, organizations, service types, mediums of exchange, requests, offers) into hREA entities (Agents, ResourceSpecifications, Proposals, Intents) via dedicated mapper functions and a central hREA store. Proposal creation enforces three prerequisites (agent, service type spec, medium-of-exchange spec); if any are missing, the request/offer is queued in a pending queue and retried automatically when prerequisites are created. GraphQL calls are made through Apollo + SchemaLink and responses are normalized to handle nested GraphQL shapes and optional missing zome functions.

When to use it

• When creating proposals from local requests or offers that must map to ValueFlows
• When synchronizing local users or organizations with hREA Agents
• When registering service types or mediums of exchange as hREA ResourceSpecifications
• When you need robust handling for missing prerequisites via a pending queue
• When the UI must display or react to hREA proposals and intents

Best practices

• Ensure user approval triggers createPerson() via the store event to generate the agent prerequisite
• Create resource specs for service types and MoEs on approval so proposals do not get queued
• Rely on retryPendingProposals() for automated retries instead of manual re-invocation
• Use normalizeIntentResponse() and normalizeProposalResponse() to turn GraphQL nested responses into usable objects
• Expect E.catchAll usage: failures due to missing zome functions or prerequisites return safe defaults or nulls

Example use cases

• User submits a request for web development: map to a Proposal with a primary service intent and a reciprocal payment intent
• On admin approval of a service type: create its ResourceSpecification and trigger retries for queued requests
• Handle an offer creation where the MoE is not yet registered by queuing the offer and auto-retrying when MoE is approved
• Sync an organization record to an hREA Agent when the organization is accepted to enable proposal creation
• Run unit tests for the hREA store by mocking the GraphQL schema and SchemaLink