@atribu/node

npm install @atribu/node

# Optional peer deps:
npm install jose      # only if you use @atribu/node/oauth
npm install msw       # only if you use @atribu/node/test

import { AtribuClient } from "@atribu/node";

const atribu = new AtribuClient({ apiKey: process.env.ATRIBU_API_KEY });

const result = await atribu.messages.send({
  connection_id: "11111111-1111-1111-1111-111111111111",
  channel: "whatsapp",
  to: "+15551234567",
  content: { type: "text", text: "Hello from @atribu/node!" },
});

console.log("Sent:", result.provider_message_id);

new AtribuClient({
  apiKey: "atb_live_...",                  // required
  baseUrl: "https://www.atribu.app",       // default
  fetch: customFetch,                       // optional — bring your own (tracing, edge)
  timeoutMs: 30_000,                        // default 30s
  userAgent: "MyApp/1.0",                   // appended after the SDK User-Agent
});

// browser, on/just before checkout
const { anonymous_id, session_id } = window.atribuTracker.getAttribution();
await fetch("/api/confirm-order", {
  method: "POST",
  body: JSON.stringify({ anonymousId: anonymous_id, sessionId: session_id, cart }),
});

// app/api/confirm-order/route.ts   (server-only — the API key lives here)
import { AtribuClient } from "@atribu/node";

const atribu = new AtribuClient({ apiKey: process.env.ATRIBU_API_KEY! });

export async function POST(req: Request) {
  const { anonymousId, sessionId, cart } = await req.json();
  const order = await chargeAndCreateOrder(cart); // your payment of record

  await atribu.events.purchase({
    anonymousId,               // ← the deterministic ad link
    sessionId,
    value: order.total,
    currency: order.currency,  // e.g. "USD", "CLP"
    orderId: order.id,         // ← idempotency key: retries never double-count
    userTraits: { email: order.email },
  });

  return Response.json({ ok: true });
}

import { AtribuClient } from "@atribu/node";
const atribu = new AtribuClient({ apiKey: process.env.ATRIBU_API_KEY! });

app.post("/confirm-order", async (req, res) => {
  const order = await chargeAndCreateOrder(req.body.cart);
  await atribu.events.purchase({
    anonymousId: req.body.anonymousId,
    value: order.total,
    currency: order.currency,
    orderId: order.id,
    userTraits: { email: order.email },
  });
  res.json({ ok: true });
});

// Public reply on the comment thread:
await atribu.comments.reply({
  comment_id: "ig_comment_id",
  connection_id: connectionId,
  text: "Thanks! DMing you now.",
});

// Private DM to the commenter (comment-to-DM flow):
await atribu.comments.privateReply({
  comment_id: "ig_comment_id",
  connection_id: connectionId,
  text: "Here are the details ...",
});

const connections = await atribu.connections.list();
for (const conn of connections) {
  console.log(`${conn.channel} — ${conn.display_name} (${conn.id})`);
}

// Filter by channel:
const igOnly = await atribu.connections.list({ channel: "instagram" });

// Revoke this OAuth app's authorization for a connection.
// Other consumers + the Atribu app UI keep using it; only this app loses access.
await atribu.connections.revoke(connectionId);

// 1. List existing templates (all statuses).
const templates = await atribu.whatsapp.templates.list({ connectionId });

// 2. Create a new one. Body text supports `{{param_name}}` placeholders;
// the named-params example block is auto-generated.
const { id, status } = await atribu.whatsapp.templates.create({
  connection_id: connectionId,
  name: "appointment_reminder",
  category: "UTILITY", // or "AUTHENTICATION" | "MARKETING"
  language: "en_US",
  body_text: "Hi {{customer_name}}, your appointment is at {{appointment_time}}.",
  header_text: "Atribu Health",        // optional
  footer_text: "Reply STOP to opt out", // optional
});

// 3. Delete by name once obsolete.
await atribu.whatsapp.templates.delete("appointment_reminder", { connectionId });

// 1. Create a draft. Max 1,000 recipients per broadcast.
const broadcast = await atribu.whatsapp.broadcasts.create({
  connection_id: connectionId,
  template_name: "appointment_reminder",
  template_language: "en_US",
  recipients: customers.map((c) => ({
    phone_number: c.phone,
    template_params: { customer_name: c.name, appointment_time: c.timeIso },
  })),
  name: "Q2 appointment reminders",
});

// 2. Dispatch. Long-running — paces 100ms between recipient sends and
// returns when every recipient has been attempted. The server caps the
// route at 5 minutes; for larger sends extend `timeoutMs` on AtribuClient.
const completed = await atribu.whatsapp.broadcasts.send(broadcast.id);
console.log(`sent: ${completed.sent_count}, failed: ${completed.failed_count}`);

// Get broadcast + first 200 recipient rows with delivery state:
const detail = await atribu.whatsapp.broadcasts.get(broadcast.id);
for (const r of detail.recipients) {
  console.log(`${r.phone_number} → ${r.status}`);
}

// Cancel an in-flight broadcast. Recipients not yet sent stay `pending`
// permanently; already-sent messages are NOT recalled.
await atribu.whatsapp.broadcasts.cancel(broadcast.id);

await atribu.messages.send({
  connection_id: connectionId,
  channel: "whatsapp",
  to: "+15551234567",
  content: {
    type: "interactive_buttons",
    body: "Pick a plan:",
    header: "Pricing",               // optional, 60 char max
    buttons: [
      { id: "plan_basic", title: "Basic" },
      { id: "plan_pro", title: "Pro" },
      { id: "plan_enterprise", title: "Enterprise" },
    ],
  },
});

// Create a trigger.
const trigger = await atribu.instagram.triggers.create({
  connection_id: connectionId,
  keyword: "PRICE",
  keyword_match_mode: "contains",          // "contains" | "exact" | "regex"
  case_sensitive: false,
  opening_message: "Here's our pricing — happy to chat!",
  public_comment_reply: "Sent you a DM!",  // optional
  agent_context_hint: null,                // optional — gets passed to the AI agent
  enabled: true,
});

// Test the opening_message against a real IGSID (must have DMed your IG account
// in the past 7 days for Meta to accept the HUMAN_AGENT send).
await atribu.instagram.triggers.testDm(trigger.id, {
  recipient_igsid: "1234567890",
});

// Pause / update / delete:
await atribu.instagram.triggers.update(trigger.id, { enabled: false });
await atribu.instagram.triggers.delete(trigger.id);

await atribu.instagram.triggers.resumeCircuit({ connectionId });

// The catalogue, as a CHANGE FEED. Keep the newest `updated_at` you have seen
// and pass it back — the page order is ascending, so a cursor stays valid no
// matter how many products change while you walk.
let updatedSince = lastSeen;            // from your own store
let cursor: string | undefined;
do {
  const page = await atribu.commerce.products.list({
    updated_since: updatedSince,
    limit: "100",
    ...(cursor ? { cursor } : {}),
  });
  for (const product of page.data) {
    // `product.variants[]` carries sku, price, currency, inventory_quantity
    // and `inventory_state` (in_stock | low_stock | out_of_stock | discontinued).
    // `active: false` means the store deactivated or DELETED it — mirror that.
    upsertLocally(product);
  }
  cursor = page.pagination.cursor;
} while (cursor);

// "Where is my order" — by number, email or phone. At LEAST ONE is required.
const orders = await atribu.commerce.orders.list({ phone: senderPhone });
const latest = orders.data[0];          // newest first
// latest.status: placed | paid | fulfilled | delivered | cancelled

await atribu.webhooks.subscriptions.create({
  url: "https://your.app/api/atribu-webhook",
  events: ["product.stock.changed", "order.status.changed"],
  providers: ["shopify"],
});

await atribu.webhooks.subscriptions.create({
  url: "https://your.app/api/atribu-webhook",
  events: [
    "connection.connected",
    "connection.reconnect_required",
    "recompute.completed",
    "conversion.attributed",
  ],
  providers: ["atribu"],
});

// Create — secret is shown ONCE in the response
const sub = await atribu.webhooks.subscriptions.create({
  url: "https://your.app/api/atribu-webhook",
  events: ["message.received", "message.delivery"],
  providers: ["whatsapp", "instagram"],
});
console.log("Save this secret somewhere safe:", sub.secret);

// Rotate the HMAC secret — deploy dual-verify on your side BEFORE calling
const rotated = await atribu.webhooks.subscriptions.rotateSecret(sub.id, {
  grace_days: 14,
});

// Fire a synthetic event to test your handler end-to-end
await atribu.webhooks.subscriptions.test(sub.id);

// Re-deliver a webhook that failed
await atribu.webhooks.deliveries.replay(deadDeliveryId);

import { AtribuApiError } from "@atribu/node";

try {
  await atribu.messages.send({ /* ... */ });
} catch (err) {
  if (err instanceof AtribuApiError) {
    switch (err.retry.action) {
      case "retry":           return queue.retry(job, { delay: 5_000 });
      case "retry_after":     return queue.retry(job, { delay: err.retry.retryAfterMs });
      case "refresh_token":   return refreshOAuthAndRetry();
      case "fix_and_retry":   logger.error("bad payload", { requestId: err.requestId }); break;
      case "do_not_retry":    logger.error("permanent failure", { requestId: err.requestId }); break;
    }
  }
}

const atribu = new AtribuClient({ apiKey: "..." }).withRetry({
  maxAttempts: 3,             // initial + 2 retries
  backoff: "exponential",     // or "fixed" or "none"
  baseDelayMs: 500,
  maxDelayMs: 30_000,
  jitter: 0.3,
});

import { setupServer } from "msw/node";
import { atribuMockHandlers, eventFixtures } from "@atribu/node/test";

const server = setupServer(...atribuMockHandlers({
  // Every endpoint has a realistic default; override only what you care about.
  messages: {
    send: { status: 422, body: { error: { code: "validation_error", message: "...", status: 422 } } },
  },
}));

// Drive your webhook handler tests with realistic event shapes:
const event = eventFixtures.whatsappMessageReceived({
  data: { text: "Custom test message" },
});

import { trace, context, propagation } from "@opentelemetry/api";
import { AtribuClient } from "@atribu/node";

const tracer = trace.getTracer("my-app");

const tracedFetch: typeof fetch = (input, init) =>
  tracer.startActiveSpan(`atribu.${(init?.method ?? "GET").toLowerCase()}`, async (span) => {
    const headers = new Headers(init?.headers);
    propagation.inject(context.active(), headers, { set: (h, k, v) => h.set(k, v) });
    try {
      const res = await fetch(input, { ...init, headers });
      span.setAttribute("http.status_code", res.status);
      const requestId = res.headers.get("x-request-id");
      if (requestId) span.setAttribute("atribu.request_id", requestId);
      return res;
    } finally { span.end(); }
  });

const atribu = new AtribuClient({ apiKey: "...", fetch: tracedFetch });

npm audit signatures