Golden Path

End-to-end external agent flow for purchase and install.

Node fetch (minimal integration)

const API = process.env.CLAWMARKETPLACE_API_BASE_URL;
const KEY = process.env.CLAWMARKETPLACE_API_KEY;

// 1) Search (limit <= 50)
const search = await fetch(`${API}/v1/plugins?limit=50&q=shopify`);
const { items } = await search.json();
const plugin = items[0];

// 2) Create checkout (user-session route: typically from web app)
const createCheckout = await fetch(`${API}/v1/checkout/create`, {
  method: "POST",
  credentials: "include", // requires user session cookie
  headers: { "content-type": "application/json", "Idempotency-Key": "checkout-create-123" },
  body: JSON.stringify({ pluginId: plugin.id, provider: "stripe" })
});
const checkout = await createCheckout.json();
// redirect user to checkout.checkoutUrl and return with session_id/paypalOrderId

// 3) Confirm payment after provider approval
const confirmCheckout = await fetch(`${API}/v1/checkout/confirm`, {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json", "Idempotency-Key": "checkout-confirm-123" },
  body: JSON.stringify({ provider: "stripe", stripeSessionId: "cs_test_..." })
});
await confirmCheckout.json();

// 4) Agent requests delivery payload
const deliveryRes = await fetch(`${API}/v1/agent/deliveries/request`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${KEY}`
  },
  body: JSON.stringify({ entitlementId: "entitlement_id_here" })
});
const delivery = await deliveryRes.json();
if (delivery.agentMessage) {
  console.log(delivery.agentMessage.title);
  console.log(delivery.agentMessage.nextAction);
}

// 5) Download + verify + unzip + install
// download delivery.signedDownloadUrl
// verify sha256 against delivery.sha256
// unzip safely to plugin dir, read claw.plugin.json

// 6) Report install result
const installReportRes = await fetch(`${API}/v1/agent/install-report`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${KEY}`
  },
  body: JSON.stringify({
    entitlementId: delivery.entitlementId,
    status: "SUCCESS",
    logsText: "Installed successfully"
  })
});
const installReport = await installReportRes.json();
if (installReport.agentMessage) {
  console.log(installReport.agentMessage.nextAction);
}

SDK-first example

import {
  createMarketplaceClient,
  downloadToFile,
  verifySha256,
  safeUnzip,
  installPlugin,
  reportInstall
} from "@clawmagic/agent-sdk";

const client = createMarketplaceClient({
  baseUrl: process.env.CLAWMARKETPLACE_API_BASE_URL!,
  apiKey: process.env.CLAWMARKETPLACE_API_KEY!
});

const { items } = await client.listEntitlements();
const delivery = await client.requestDelivery({ entitlementId: items[0].id });
if (delivery.agentMessage) {
  console.log(delivery.agentMessage.nextAction);
}
await downloadToFile({ signedUrl: delivery.signedDownloadUrl, outPath: "./tmp/plugin.zip" });
const checksum = await verifySha256({ filePath: "./tmp/plugin.zip", expected: delivery.sha256! });
if (!checksum.valid) throw new Error("checksum mismatch");
await safeUnzip({ zipPath: "./tmp/plugin.zip", destDir: "./tmp/unpacked" });
await installPlugin({ pluginDir: "./tmp/unpacked", targetDir: "./clawmagic/plugins" });
const report = await reportInstall({ client, entitlementId: delivery.entitlementId, status: "SUCCESS" });
if (report.agentMessage) {
  console.log(report.agentMessage.nextAction);
}