Production Pulse · 6 / 8

Package a schema client

Attach a pinned API contract for a fictional monitoring service. No requests are sent.

YOUR TASK

Make this happen

3 steps

In client.cococo, name integration_api_client.monitor as monitor. The document includes it through apiClients.
Use file("contracts/monitor.openapi.json") for schema and file("contracts/monitor.api.xml") for definition.
Keep the monitor_service device requirement and scoped policy.

THE IDEA BEHIND IT

Build on the working integration

Start with the previous solution. Add the next capability in main.cococo, client.cococo. Connect the new components through their parent lists; supplied scripts and contracts remain read-only fixtures.

Contract and connection are separate

The supplied OpenAPI contract declares POST /signals with a reason string and an accepted boolean response. The client selects sendSignal. A schema does not create an outbound route: runtime initialization still needs the bound device.

A generated fixture, not an XML exercise

The platform client definition is a generated artifact pinned to the exact OpenAPI bytes. Both are supplied immutable files for this course. You compose them through the virtual document. The academy checks the fixture identity; full API compilation and runtime response validation happen on the platform.

How this will be called

The shared script in the next lesson will use ctx.api.get("monitor"):init(ctx.device.get("monitor_service")), then sendSignal with a typed body. Credentials, if needed, come from installation/runtime inputs rather than this source.

Checks cover structure and lesson requirements. Scripts and platform behaviour are not executed.

Actor and Action reference ↗Schema client reference ↗

This lesson starts with the previous working solution. Build and connect the next capability. Your earlier drafts are kept separately.

Read the starter files

main.cococo

integration_document "monitor" {
  integrationId = "com.academy.monitor"
  sdkVersion = "2.0"
  version = "1.0.0"
  description = "A small heartbeat integration"
  resources = [integration_resource_requirement.monitor_service]
  policy = integration_policy.monitor
  actor = integration_actor.monitor
}

actor.cococo

integration_actor "monitor" {
  subscriptions = [integration_actor_subscription.job_updates]
  actions = [integration_actor_action.status]
  timers = [integration_actor_timer.heartbeat, integration_actor_timer.daily_review]
}

timer.cococo

integration_actor_timer "heartbeat" {
  name = "heartbeat"
  schedule = { every = "5m" }
  jitter = "15s"
  source = "return { alive = true }"
}

events.cococo

integration_actor_subscription "job_updates" {
  topic = "job.updated"
  source = file("scripts/job-updated.lua")
}

actions.cococo

integration_actor_action "status" {
  name = "status"
  label = "Check production pulse"
  inputSchema = { type = "object", properties = {} }
  outputSchema = {
    type = "object"
    properties = { alive = { type = "boolean" } }
    required = ["alive"]
  }
  source = file("scripts/status.lua")
}

resources.cococo

integration_resource_requirement "monitor_service" {
  id = "monitor_service"
  type = "protocol/http"
  optional = false
  description = "HTTP device for the monitoring service"
}

policy.cococo

integration_policy_statement "devices" {
  effect = "ALLOW"
  actions = ["device:*"]
  resources = [integration_resource_requirement.monitor_service.id]
}

integration_policy "monitor" {
  statements = [integration_policy_statement.devices]
}

daily.cococo

integration_actor_timer "daily_review" {
  name = "daily_review"
  schedule = { cron = "0 6 * * *" }
  source = "return { review = true }"
}

client.cococo

integration_api_client "monitor" {
  name = "monitor"
  # TODO: add schema — see the task above.
  # TODO: add definition — see the task above.
}

Supplied scripts and pinned contracts (read-only)

These fixtures explain the runtime behaviour being composed. They are included in validation but are not executed. The generated API definition is supplied, not an XML authoring task.

scripts/heartbeat.lua

return { alive = true }

scripts/job-updated.lua

local event, config = ...
return { reason = "job.updated" }

scripts/status.lua

local input, actionConfig = ...
return { alive = true }

contracts/monitor.openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Production Pulse",
    "version": "1.0.0"
  },
  "paths": {
    "/signals": {
      "post": {
        "operationId": "sendSignal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signal accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accepted"
                  ],
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

contracts/monitor.api.xml

<api-client name="monitor" schema-sha256="ff335ef17f27b04682e45ed20fc932d10c89dc2b37572defa7addf51129fa220"><operation id="sendSignal"/></api-client>