@whatsapi.sh/sdk 0.1.0

package/src/generated/contract.ts

@@ -0,0 +1,402 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: packages/shared/src/http/index.ts, packages/shared/src/billing/catalog.ts, packages/shared/src/dto/index.ts, packages/shared/src/webhooks/index.ts
+//
+// The shapes the API speaks, lifted from the server's own contract.
+
+// ── from packages/shared/src/http/index.ts ───────────────────────────
+
+/** Canonical error codes. The web client can switch on these / map them to i18n. */
+export type ErrorCode =
+    | "VALIDATION_ERROR" // 400 — zod failures; details: issues[]
+    | "UNAUTHORIZED" // 401 — missing/invalid token
+    | "INVALID_TOKEN" // 401
+    | "FORBIDDEN" // 403 — RBAC / suspended account
+    | "NOT_FOUND" // 404
+    | "CONFLICT" // 409 — e.g. number already paired elsewhere
+    // 402 — out of message credits. Distinct from 429 on purpose: a rate/quota limit
+    // clears by waiting (or the month rolling over), this one clears by upgrading or
+    // buying a pack, and the client must not auto-retry it.
+    | "PAYMENT_REQUIRED"
+    // 429 — burst limiter (per key/user/ip). Carries a Retry-After header, as does
+    // every other error that knows when it clears.
+    | "RATE_LIMIT_EXCEEDED"
+    | "QUOTA_EXCEEDED" // 429 — monthly/daily message quota spent; details carry resetAt
+    // 409/502 — the WhatsApp number exists but its session is not connected right now
+    // (pairing pending, logged out, or banned). The gateway call never happened.
+    | "NUMBER_NOT_CONNECTED"
+    // 429 — QR/pairing-code generation is on cooldown (QR_GENERATION_COOLDOWN=180s,
+    // PairPhone ~5/30min budget). Carries Retry-After + details.retryAfterSecs.
+    // See docs/QUIRKS.md.
+    | "PAIRING_COOLDOWN"
+    | "OTP_INVALID" // 400 — otp/check code mismatch or expired
+    | "GATEWAY_ERROR" // 502 — wuzapi upstream failed; details carry the remapped cause
+    // 504 — WhatsApp did not confirm in time. Deliberately NOT a 502: the send
+    // was accepted upstream and very likely DELIVERED, we just stopped waiting.
+    // `details.messageId` is the id it went out with, so the caller watches for
+    // it on the `message.status` webhook instead of sending it a second time.
+    | "GATEWAY_TIMEOUT"
+    | "INTERNAL_ERROR" // 500
+    | "SERVICE_UNAVAILABLE"; // 503 — readiness/health check failed, quota store down
+// ── from packages/shared/src/billing/catalog.ts ──────────────────────
+
+export type PlanId = "free" | "starter" | "pro" | "scale";
+// ── from packages/shared/src/dto/index.ts ────────────────────────────
+
+/** A number's lifecycle: created (no session) → connected (session live) →
+ *  disconnected (dropped) / banned (restriction signal — see docs/QUIRKS.md). */
+export type NumberStatus = "pairing" | "connected" | "disconnected" | "banned";
+
+/** A WhatsApp number (a paired session), server-projected — never carries the
+ *  gateway instance id or token. */
+export interface NumberDto {
+    id: string;
+    name: string;
+    phone: string | null;
+    status: NumberStatus;
+    connectedAt: string | null;
+    historySync: boolean;
+    createdAt: string;
+}
+
+/** Answer to POST /numbers/:id/pair. `state` tells the client what to render:
+ *  "pairing" (show the QR/linking code, or poll again when both are absent —
+ *  wuzapi can take ~5s to mint a QR after connect), "connected" (already live). */
+export interface PairNumberDto {
+    mode: "qr" | "code";
+    state: "pairing" | "connected";
+    /** Base64 QR (mode qr, when ready). */
+    qrCode?: string;
+    /** XXXX-XXXX linking code (mode code). */
+    linkingCode?: string;
+    /** True when the QR is the cached one from an earlier generation. */
+    isCached: boolean;
+    /** Epoch ms of generation — the client resumes its countdown from this. */
+    generatedAt?: number;
+    /** Seconds until a NEW QR may be generated (0 when fresh). */
+    remainingCooldown: number;
+}
+
+/** POST /v1/numbers/{id}/unpair — the slot stays, the WhatsApp session is gone. */
+export interface UnpairedNumberDto {
+    id: string;
+    status: "disconnected";
+}
+
+/** DELETE /v1/numbers/{id} — the slot itself is gone, and the plan's seat is free. */
+export interface DeletedNumberDto {
+    id: string;
+    deleted: true;
+}
+
+/** A message WhatsApp accepted. `sent` is the only success state the send call
+ *  can report — delivered/read arrive later on the `message.status` webhook. */
+export interface MessageDto {
+    /** WhatsApp's message id — the same id the status webhooks carry. */
+    id: string;
+    /** E.164 recipient the message actually went to. */
+    to: string;
+    /** Id of the number that sent it (useful when the account has several). */
+    from: string;
+    status: "sent";
+    timestamp: string;
+    /** Messages left in this month's PLAN quota after this send — so a client can
+     *  show a meter without a second call. Hits 0 while sends keep working if the
+     *  account has credits: the two pools are reported separately on purpose. */
+    quotaRemaining: number;
+    /** Purchased messages left (packs never expire). Sends spill here once
+     *  `quotaRemaining` is 0, so a client that stops at `quotaRemaining === 0`
+     *  and ignores this one stops earlier than it had to. */
+    creditRemaining: number;
+}
+
+/** One recipient's outcome inside a batch. `skipped` is not a failure of its
+ *  own: something systemic (the session died, the meter refused) stopped the
+ *  run, and these are the recipients never attempted — send them again once the
+ *  reason on the batch is cleared. */
+export interface BatchResultDto {
+    to: string;
+    status: "sent" | "failed" | "skipped";
+    /** Present on `sent`. */
+    id?: string;
+    /** Present on `failed` and `skipped` — the same code the single-send
+     *  endpoint would have answered with. */
+    error?: { code: ErrorCode; message: string };
+}
+
+/** POST /v1/messages/batch. Always a 200 with per-recipient outcomes: a batch
+ *  where 24 of 25 landed is neither a success nor a failure, and collapsing it
+ *  into one status code would throw away the only part that matters. */
+export interface BatchMessageDto {
+    sent: number;
+    failed: number;
+    skipped: number;
+    /** Why the run stopped early, when it did. */
+    stoppedBecause?: { code: ErrorCode; message: string };
+    results: BatchResultDto[];
+    /** Messages left in this month's plan quota after the batch. */
+    quotaRemaining: number;
+    /** Purchased messages left after the batch — see `MessageDto.creditRemaining`. */
+    creditRemaining: number;
+}
+
+/** POST /v1/chats/{phone}/typing. Free, so there is no quota to report — it
+ *  echoes what it did, and `to` is the address the indicator went to. */
+export interface TypingDto {
+    to: string;
+    state: "composing" | "paused";
+}
+
+/** POST /v1/chats/{phone}/read — the ids that now carry blue ticks. */
+export interface MarkReadDto {
+    to: string;
+    messageIds: string[];
+}
+
+/** POST /v1/otp — the code is returned to the CALLER (that's the whole point of
+ *  the endpoint: send it and hand it back so the app can verify however it
+ *  likes). Only its hash is stored. */
+export interface OtpDto {
+    code: string;
+    expiresAt: string;
+    to: string;
+    /** The WhatsApp message that carried the code. */
+    messageId: string;
+}
+
+/** POST /v1/otp/check succeeds or throws OTP_INVALID — never `{ verified: false }`.
+ *  A verification primitive that answers 200 to a wrong code is one forgotten
+ *  `if` away from letting anyone in. */
+export interface OtpCheckDto {
+    verified: true;
+    to: string;
+}
+
+/** GET /v1/numbers/check/{phone} — is this phone on WhatsApp? */
+export interface NumberCheckDto {
+    /** E.164 of the variant WhatsApp actually matched: a Brazilian mobile may be
+     *  registered with or without the 9th digit, and we check both. */
+    e164: string;
+    hasWhatsApp: boolean;
+    /** The address to send to. Null when the number isn't on WhatsApp. */
+    jid: string | null;
+    avatarUrl: string | null;
+    /** False when WhatsApp couldn't be reached and `hasWhatsApp` is an optimistic
+     *  assumption — a check outage must never block sends to real recipients
+     *  (docs/QUIRKS.md — number-check fail-open). */
+    verified: boolean;
+}
+
+/** GET /v1/usage — this month's spend against the plan, plus the per-key split. */
+export interface UsageDto {
+    plan: PlanId;
+    /** "2026-08" (America/Sao_Paulo). */
+    month: string;
+    monthUsed: number;
+    monthLimit: number;
+    dayUsed: number;
+    dayLimit: number;
+    sendsPerMinute: number;
+    creditBalance: number;
+    /** When the monthly counter rolls over. */
+    resetAt: string;
+    /** Per-key breakdown, newest first. Revoked keys stay listed — their usage
+     *  still counts toward the account total, and a month's spend that vanished
+     *  when a key was rotated would look like a billing error. `revoked` is what
+     *  tells the two apart. */
+    keys: { id: string; name: string; prefix: string; used: number; revoked: boolean }[];
+}
+// ── from packages/shared/src/webhooks/index.ts ───────────────────────
+
+/** Every event an endpoint can subscribe to.
+ *
+ *  Deliberately FIVE, normalized out of wuzapi's ~50 provider events: an
+ *  inbound message, a status change on one we sent, and the three moments a
+ *  number's session changes hands. Everything else (presence, chat presence,
+ *  history sync, group metadata) is either noise to an API customer or
+ *  privacy-sensitive, and is dropped at the ingestion boundary. */
+export const WEBHOOK_EVENT_TYPES = [
+    /** Someone messaged one of your numbers. The payload carries the text (or
+     *  the media's metadata), never the media bytes. */
+    "message.created",
+    /** WhatsApp reported delivery/read/played for messages you sent. */
+    "message.status",
+    /** A number's WhatsApp session came up and can send again. */
+    "number.connected",
+    /** A number's session dropped and did not come back on its own — it needs
+     *  re-pairing. */
+    "number.disconnected",
+    /** WhatsApp logged the number out or restricted it. Sends will fail until
+     *  it is paired again; see the 24h restriction window in the docs. */
+    "number.logged_out",
+] as const;
+
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+
+/** The synthetic event `POST /v1/webhooks/test` fires. Not subscribable — it is
+ *  always delivered, because its whole job is proving the wiring works. */
+export const WEBHOOK_TEST_EVENT = "ping";
+
+export const WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed"] as const;
+
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+
+/** The body of every delivery. `id` is also the `x-whatsapi-delivery` header:
+ *  retries reuse it, so a receiver that has seen an id can safely drop the
+ *  repeat. */
+export interface WebhookEnvelope<T = unknown> {
+    id: string;
+    type: WebhookEventType | typeof WEBHOOK_TEST_EVENT;
+    /** ISO 8601, when we built the event — not when we sent it. */
+    timestamp: string;
+    data: T;
+}
+
+/** The sending/receiving number, on every event. Enough to route without a
+ *  lookup, never the gateway instance or token. */
+export interface WebhookNumberRef {
+    id: string;
+    name: string;
+    phone: string | null;
+}
+
+export type InboundMessageType =
+    | "text"
+    | "image"
+    | "video"
+    | "audio"
+    | "document"
+    | "location"
+    | "contact"
+    | "sticker"
+    | "reaction"
+    | "poll"
+    | "other";
+
+/** `message.created`. Media arrives as metadata only: the gateway runs with
+ *  `-skipmedia`, so the bytes stay on WhatsApp's servers until asked for. */
+export interface MessageCreatedEvent {
+    number: WebhookNumberRef;
+    message: {
+        id: string;
+        /** The conversation: a phone number for a 1:1 chat, a group JID for a group. */
+        chat: string;
+        /** Who wrote it — the same as `chat` outside groups. */
+        from: string;
+        /** True when the message was sent BY this number (from the linked phone,
+         *  or by an earlier API call) rather than to it. */
+        fromMe: boolean;
+        isGroup: boolean;
+        /** The sender's WhatsApp display name, when they publish one. */
+        pushName?: string;
+        timestamp: string;
+        type: InboundMessageType;
+        /** Text body, for text messages. */
+        text?: string;
+        /** Caption, for media that carries one. */
+        caption?: string;
+        media?: {
+            mimeType?: string;
+            fileName?: string;
+            /** Audio/video length in seconds. */
+            seconds?: number;
+            bytes?: number;
+            /** True for a voice note rather than an audio file. */
+            voice?: boolean;
+        };
+    };
+}
+
+/** `message.status`. WhatsApp acks in batches, so one event can settle several
+ *  message ids at once. */
+export interface MessageStatusEvent {
+    number: WebhookNumberRef;
+    /** Ids as returned by the send call. */
+    messageIds: string[];
+    /** The chat the acks came from. */
+    chat: string;
+    status: "delivered" | "read" | "played";
+    timestamp: string;
+}
+
+/** `number.connected` · `number.disconnected` · `number.logged_out`. */
+export interface NumberStatusEvent {
+    number: WebhookNumberRef;
+    /** Why the session ended, when the provider said — "server", "logged_out",
+     *  "connection_failure", "ban". Absent on connect. */
+    reason?: string;
+}
+
+/** `ping` — what the test-fire delivers. Not subscribable; see WEBHOOK_TEST_EVENT. */
+export interface PingEvent {
+    message: string;
+}
+
+/** Which payload rides with which event. The map is what makes `WebhookEvent`
+ *  below a discriminated union — narrow on `type` and `data` narrows with it —
+ *  and it is load-bearing on the producing side too: the emitter's input is
+ *  typed from it, so an event can never be published with the wrong shape. */
+export interface WebhookPayloads {
+    "message.created": MessageCreatedEvent;
+    "message.status": MessageStatusEvent;
+    "number.connected": NumberStatusEvent;
+    "number.disconnected": NumberStatusEvent;
+    "number.logged_out": NumberStatusEvent;
+    ping: PingEvent;
+}
+
+/** Every delivery, as the receiver sees it:
+ *
+ *      if (event.type === "message.created") event.data.message.text
+ */
+export type WebhookEvent = {
+    [K in keyof WebhookPayloads]: WebhookEnvelope<WebhookPayloads[K]> & { type: K };
+}[keyof WebhookPayloads];
+
+export interface WebhookEndpointDto {
+    url: string;
+    events: WebhookEventType[];
+    enabled: boolean;
+    /** Set when WE turned the endpoint off: "failures" after a long run of dead
+     *  deliveries. null while it is healthy. */
+    disabledReason: string | null;
+    /** Failed deliveries in a row. Resets on the first success. */
+    consecutiveFailures: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** The answer to `PUT /v1/webhooks`. `secret` is present ONLY when one was just
+ *  minted (first registration, or `rotateSecret: true`) — it is never
+ *  retrievable afterwards, exactly like an API key. */
+export interface SavedWebhookDto {
+    secret: string | null;
+    record: WebhookEndpointDto;
+}
+
+export interface WebhookDeliveryDto {
+    /** Also the `x-whatsapi-delivery` header of the POST. */
+    id: string;
+    event: string;
+    status: WebhookDeliveryStatus;
+    attempts: number;
+    /** The HTTP status the endpoint answered, when it answered at all. */
+    responseStatus: number | null;
+    error: string | null;
+    createdAt: string;
+    deliveredAt: string | null;
+}
+
+/** The synchronous outcome of `POST /v1/webhooks/test`. */
+export interface WebhookTestResultDto {
+    ok: boolean;
+    status: number | null;
+    error: string | null;
+    /** The delivery it was recorded as — it shows up in the delivery list too. */
+    deliveryId: string;
+}
+
+/** DELETE /v1/webhooks. `false` when there was nothing registered to delete —
+ *  the end state is the same either way, so it is not an error. */
+export interface DeletedWebhookDto {
+    deleted: boolean;
+}