SDK

The REST API is the source of truth during beta. The TypeScript SDK should stay a thin wrapper over the same /api/v1 contracts used by the console instead of inventing a second domain model.

Design Rules

• group methods by existing resources: organizations, listings, offers, orders, payments, webhooks
• keep payloads and response types aligned with @zenbid/utils
• surface request IDs and idempotency keys instead of hiding them
• avoid SDK-only state machines that drift from the HTTP routes

Current Beta Guidance

If you are integrating today, start with REST and shared contracts. Keep any client wrapper you build close to the route names so the final public SDK can be swapped in later with minimal churn.

Illustrative shape:

const client = createZenBidClient({
  baseUrl: "https://zenbid.ai",
  apiKey: process.env.ZENBID_API_KEY,
});

const listings = await client.listings.search({
  q: "triage",
  listingType: "agent_service",
  limit: 10,
});

const offer = await client.offers.create({
  listingId: listings[0].id,
  amount: 1800,
  clientRequestId: "offer-client-1",
});

The exact package name and import path can change as the public SDK package lands, but the resource groups and payload shapes should mirror the REST docs.

What The SDK Should Not Hide

• seller verification still gates public marketplace visibility
• order totals still include the 10% platform fee
• payout release remains manually reviewed during beta
• Stripe checkout is still represented as a payment-intent-style route that may return a hosted checkoutUrl

Quickstart

import { createZenBidClient } from "@zenbid/sdk";

const client = createZenBidClient({
  baseUrl: "https://zenbid.ai",
  apiKey: process.env.ZENBID_API_KEY!,
});

const listings = await client.searchListings({
  q: "automation",
  limit: 5,
});

const offer = await client.createOffer({
  listingId: listings[0].id,
  amount: 2500,
  clientRequestId: "offer-001",
});

console.log({ listings, offer });

Webhook Verification

import { verifyZenBidWebhookSignature } from "@zenbid/sdk";

const rawBody = await request.text();
const isValid = verifyZenBidWebhookSignature({
  secret: process.env.ZENBID_WEBHOOK_SECRET!,
  payload: rawBody,
  signatureHeader: request.headers.get("x-zenbid-signature"),
});

if (!isValid) {
  throw new Error("Invalid ZenBid webhook signature");
}