واجهة الوكلاء

# 1. Create an agent (it gets its version 1)
curl https://api.mindlabsa.com/v1/agents \
  -H "Authorization: Bearer $QIRNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "system_prompt": "صنّف رسالة العميل واقترح رداً قصيراً."
  }'

# 2. Start a run: answered 202 at once, with the queued run's id
curl https://api.mindlabsa.com/v1/agents/$AGENT_ID/runs \
  -H "Authorization: Bearer $QIRNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "message": "فاتورتي الأخيرة بمبلغ خاطئ." } }'

# 3. Follow it as server-sent events (or poll GET /v1/runs/$RUN_ID)
curl -N https://api.mindlabsa.com/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $QIRNAS_API_KEY"

# With a key that holds agents.approve and did not start the run
curl https://api.mindlabsa.com/v1/approvals/$APPROVAL_ID/approve \
  -H "Authorization: Bearer $APPROVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Checked the amount." }'

: keep-alive

data: {"type":"run.status","status":"running"}

data: {"type":"step.completed","step":{"seq":1,"kind":"assistant", ...}}

data: {"type":"run.completed","run":{"id":"…","status":"succeeded", ...}}

data: [DONE]

// Follow a run to its end. A stream that closes without [DONE] is reconnected;
// each connection replays every step, so the steps already seen are dropped by seq.
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function follow(runId, onEvent) {
  let lastSeq = 0;
  for (;;) {
    const res = await fetch(`https://api.mindlabsa.com/v1/runs/${runId}/events`, {
      headers: { Authorization: `Bearer ${process.env.QIRNAS_API_KEY}` },
    });
    if (res.status === 429) {
      await sleep(Number(res.headers.get("retry-after") ?? 1) * 1000);
      continue;
    }
    if (!res.ok) {
      const body = await res.json().catch(() => null); // a 503 page from in front of the API is not JSON
      throw new Error(`${res.status} ${body?.error?.code ?? body?.error?.type ?? res.statusText}`);
    }

    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
    let buffer = "";
    let replayed = false; // the last step frame was one already seen
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break; // closed without [DONE]: reconnect
      buffer += value;
      let end;
      while ((end = buffer.indexOf("\n\n")) >= 0) {
        const frame = buffer.slice(0, end);
        buffer = buffer.slice(end + 2);
        for (const line of frame.split("\n")) {
          if (!line.startsWith("data: ")) continue; // ": keep-alive" and other comments
          const data = line.slice(6);
          if (data === "[DONE]") return;
          const event = JSON.parse(data);
          if (event.type === "step.completed") {
            replayed = event.step.seq <= lastSeq;
            if (!replayed) lastSeq = event.step.seq;
          } else if (!event.type.startsWith("approval.")) {
            replayed = false; // approval frames follow their approval step
          }
          if (!replayed) onEvent(event);
        }
      }
    }
  }
}

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

// secret: the endpoint's whsec_... secret. body: the raw request body, before JSON.parse.
export function verifyWebhook(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures || !/^[0-9]+$/.test(timestamp)) return false;
  // Refuse stale timestamps (the platform allows 300 s on hooks).
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();
  // Several space-separated signatures can arrive (one per secret during a rotation).
  return signatures.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

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

// Fire a webhook trigger from your service. No API key: the request is signed with the
// trigger's whsec_... secret (shown once, when the trigger was created or rotated).
const secret = process.env.TRIGGER_SECRET;
const body = JSON.stringify({ order_id: "A-1042", status: "delayed" });
const id = randomUUID(); // send the same webhook-id again when you retry
const timestamp = String(Math.floor(Date.now() / 1000));
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const signature = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");

const res = await fetch(`https://api.mindlabsa.com/v1/hooks/${process.env.TRIGGER_ID}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "webhook-id": id,
    "webhook-timestamp": timestamp,
    "webhook-signature": `v1,${signature}`,
  },
  body,
});
// 202: { fire: { id, outcome, run_id } }; 200: this webhook-id was already received.
console.log(res.status, await res.json());