# Invitations

> Generate partner invitations for client WhatsApp Business onboarding via the Zavu TypeScript SDK. Track status and manage expiration.

Partner invitations allow you to generate links for clients to connect their WhatsApp Business accounts to your project.

## Create Invitation

```typescript
const invitation = await zavu.invitations.create({
  clientName: "Acme Corp",
  clientEmail: "contact@acme.com",
  expiresInDays: 14,
});

console.log(invitation.id);  // jh7am5bng9p3v2x1k4r8
console.log(invitation.url); // https://dashboard.zavu.dev/invite/abc123xyz
console.log(invitation.status); // pending
```

### With Phone Number Restrictions

Restrict which countries the client can register phone numbers from:

```typescript
const invitation = await zavu.invitations.create({
  clientName: "Acme Corp",
  clientEmail: "contact@acme.com",
  expiresInDays: 7,
  allowedPhoneCountries: ["US", "MX"],
});
```

## Get Invitation

```typescript
const { invitation } = await zavu.invitations.retrieve({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

console.log(invitation.status);      // pending | in_progress | completed | expired | cancelled
console.log(invitation.clientName);  // Acme Corp
console.log(invitation.senderId);    // null (until completed)
console.log(invitation.expiresAt);   // 2025-01-15T00:00:00.000Z
```

## List Invitations

```typescript
const { items, nextCursor } = await zavu.invitations.list({});

for (const invitation of items) {
  console.log(invitation.id, invitation.clientName, invitation.status);
}
```

### Filter by Status

```typescript
const { items } = await zavu.invitations.list({
  status: "pending",
  limit: 50,
});
```

### Pagination

```typescript
let cursor: string | undefined;

do {
  const result = await zavu.invitations.list({
    limit: 50,
    cursor,
  });

  for (const invitation of result.items) {
    console.log(invitation.id);
  }

  cursor = result.nextCursor ?? undefined;
} while (cursor);
```

## Cancel Invitation

Cancel an active invitation to prevent the client from using it:

```typescript
const { invitation } = await zavu.invitations.cancel({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

console.log(invitation.status); // cancelled
```

> **Note:**
> You cannot cancel a completed invitation. Once a sender is created, manage it through the senders API.

## After Completion

When a client completes the signup flow, a sender is created in your project:

```typescript
const { invitation } = await zavu.invitations.retrieve({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

if (invitation.status === "completed" && invitation.senderId) {
  // Use the sender to send messages
  await zavu.messages.send({
    to: "+14155551234",
    channel: "whatsapp",
    messageType: "template",
    content: {
      templateId: "tmpl_xyz789",
      templateVariables: {
        "1": "John",
      },
    },
  }, {
    headers: {
      "Zavu-Sender": invitation.senderId,
    },
  });
}
```

## Full Example

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

async function onboardClient(clientName: string, clientEmail: string) {
  // Create invitation
  const invitation = await zavu.invitations.create({
    clientName,
    clientEmail,
    expiresInDays: 7,
  });

  console.log(`Send this link to ${clientName}: ${invitation.url}`);

  return invitation;
}

async function checkInvitationStatus(invitationId: string) {
  const { invitation } = await zavu.invitations.retrieve({ invitationId });

  switch (invitation.status) {
    case "pending":
      console.log("Waiting for client to start signup");
      break;
    case "in_progress":
      console.log("Client is completing the signup flow");
      break;
    case "completed":
      console.log(`Success! Sender ID: ${invitation.senderId}`);
      break;
    case "expired":
      console.log("Invitation expired, create a new one");
      break;
    case "cancelled":
      console.log("Invitation was cancelled");
      break;
  }

  return invitation;
}

// Usage
const invitation = await onboardClient("Acme Corp", "contact@acme.com");
// Later...
await checkInvitationStatus(invitation.id);
```