Connect a widget to its Droplet backend

{
  "operation": "commissions.summary",
  "params": { "period": "2026-09" },
  "widget_type": "fluid://extensions/42/sections/commission_summary",
  "company": { "id": 1842, "fluid_shop": "northwind.fluid.app" },
  "member": {
    "id": "01990000-0000-7000-8000-000000000001",
    "public_id": "01990000-0000-7000-8000-000000000001",
    "external_id": "exigo-4821"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret, now = Date.now()) {
  const timestamp = headers["x-fluid-timestamp"];
  const signature = headers["x-fluid-signature"];
  if (!secret || typeof timestamp !== "string" || !/^\d{10}$/.test(timestamp)) return false;
  if (typeof signature !== "string" || !/^[a-f0-9]{64}$/.test(signature)) return false;
  if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp).update(".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

async function dispatchVerifiedQuery(query, backend) {
  const { company, member, operation, params } = query;
  if (!Number.isSafeInteger(company?.id) || typeof member?.public_id !== "string") {
    throw new Error("Invalid signed identity");
  }
  if (!params || typeof params !== "object" || Array.isArray(params) ||
      Object.keys(params).some((key) => key !== "period")) {
    throw new Error("Invalid parameters");
  }
  const period = params.period;
  if (period !== undefined &&
      (typeof period !== "string" || !/^\d{4}-(0[1-9]|1[0-2])$/.test(period))) {
    throw new Error("Invalid period");
  }
  if (!["commissions.summary", "commissions.history"].includes(operation)) {
    throw new Error("Unknown operation");
  }
  const identity = await backend.resolveMember({
    companyId: company.id,
    memberPublicId: member.public_id,
  });
  if (!identity || identity.canReadCommissions !== true) {
    throw new Error("Member cannot read commissions");
  }
  if (operation === "commissions.summary") {
    return backend.summary(identity, period);
  }
  return { entries: await backend.history(identity, period) };
}

<section data-commission-example {% droplet_data_attributes %}>
  <h2>Your commissions</h2>
  <p role="status" aria-live="polite">Loading…</p>
  <pre data-output></pre>
  <button type="button">Refresh</button>
</section>

async function mountCommissions(root) {
  const status = root.querySelector('[role="status"]');
  const output = root.querySelector("[data-output]");
  let revision = 0;
  let client;
  try {
    client = await window.Fluid.droplets.createQueryClient(root, {
      extension: root.dataset.extension,
      onInvalidate() {
        revision += 1;
        output.textContent = "";
        status.textContent = "Refresh to load member data.";
      }
    });
  } catch {
    if (root.isConnected) status.textContent = "Unable to start. Reload the page to try again.";
    return;
  }
  async function load() {
    const pending = client.query("commissions.summary", {});
    const currentRevision = revision;
    status.textContent = "Loading…";
    try {
      const data = await pending;
      if (revision !== currentRevision || !root.isConnected) return;
      status.textContent = Object.keys(data).length ? "Loaded" : "No commissions yet.";
      output.textContent = Object.keys(data).length ? JSON.stringify(data, null, 2) : "";
    } catch {
      if (revision !== currentRevision || !root.isConnected) return;
      status.textContent = "Unable to load. Sign in or try again.";
      output.textContent = "";
    }
  }
  root.querySelector("button").addEventListener("click", () => void load());
  void load();
}

for (const root of document.querySelectorAll("[data-commission-example]")) {
  void mountCommissions(root);
}

{% section 'fluid://extensions/42/sections/commission_summary', id: 'commissions' %}

{% schema %}
{
  "sections": {
    "commissions": {
      "id": "commissions",
      "type": "fluid://extensions/42/sections/commission_summary",
      "settings": {}
    }
  }
}
{% endschema %}

{
  "droplet": {
    "name": "Northwind Commissions",
    "embed_url": "https://commissions.northwind.example/admin",
    "widget_data_url": "https://commissions.northwind.example/member-data"
  }
}

Create or update a Fluid Droplet and a member-page section using
/themes/member-storefront/droplet-data#instructions-for-mist-and-other-ai-agents.

Use the supplied environment, owner company, member-site company, theme,
page, backend and operation contract. Obtain missing inputs before making
assumptions about identities or permissions. Keep secret values out of output.

Build the signed read-only backend receiver and the Liquid theme extension.
Use droplet_data_attributes and await window.Fluid.droplets.createQueryClient
for each placement. Implement private-output cleanup and preview sample states.
Install the published extension, discover its real URI, and preserve the
existing template when adding its section tag and schema entry.

Verify with real member sessions and backend permission tests. Return the
artifact identifiers, operation contracts, deployment states, test evidence
and remaining blockers. Do not mark preview-only work as live-tested.