Generate TypeScript Types for Third-Party SDK Integration

A payment object with a nested customer and amount yields named Customer/root interfaces you reference across handlers.

Input:
{ "id": "pi_123", "amount": 1999, "currency": "usd", "customer": { "id": "cus_9", "email": "a@x.com" } }

Output (rootName: StripePaymentIntent):
export interface StripePaymentIntent {
  id: string;
  amount: number;
  currency: string;
  customer: Customer;
}

export interface Customer {
  id: string;
  email: string;
}

Stripe's metadata is an arbitrary string map, but the generator emits the literal keys from your sample. Replace with an index signature.

Input:
{ "id": "pi_1", "metadata": { "order_id": "42", "plan": "pro" } }

Output (verbatim):
export interface Root {
  id: string;
  metadata: Metadata;
}

export interface Metadata {
  order_id: string;
  plan: string;
}

Hand-edit: metadata: Record<string, string>;  // arbitrary keys

An order with multiple line items produces one item interface from the first element. If line items vary, reorder so the richest is first.

Input:
{ "line_items": [ { "sku": "A", "qty": 1 }, { "sku": "B", "qty": 2, "gift": true } ] }

Output:
export interface Root {
  line_items: LineItemsItem[];
}

export interface LineItemsItem {
  sku: string;
  qty: number;
}

// 'gift' from item 2 is absent. Reorder the sample so the gift item is first.

Generate each event you handle separately, then combine into a discriminated union keyed on the literal type.

Generate from payment_intent.succeeded → PaymentSucceededEvent
Generate from payment_intent.failed    → PaymentFailedEvent

Combine by hand (narrow the type field to a literal):
type StripeWebhookEvent =
  | (PaymentSucceededEvent & { type: "payment_intent.succeeded" })
  | (PaymentFailedEvent & { type: "payment_intent.failed" });

Apply the generated type at the request boundary, then switch on the (hand-narrowed) event type.

export async function POST(req: Request) {
  const event: StripeWebhookEvent = await req.json();
  switch (event.type) {
    case "payment_intent.succeeded":
      // event is narrowed to PaymentSucceededEvent
      break;
  }
}

Provider maps like Stripe metadata are emitted with the literal keys in your sample. Replace with Record<string, string> (or the right value type) since the real keys are arbitrary. The generator can't distinguish a map from a fixed-shape object.

line_items, charges, and similar arrays infer their item interface from the first element only. Keys exclusive to later items are absent — reorder so the richest item is first, or paste a single merged superset object.

The literal event string becomes type: string and the generator never builds the discriminated union. Generate each handled event separately, then union them and narrow the type field to its literal by hand.

A field that's an object in one event and null in another is typed from the single sample you pasted — e.g. null. Capture both variants and widen by hand, e.g. payment_method: PaymentMethod | null.

Any null value yields the literal null type. Widen field: null to T | null manually, or capture a delivery where the field is populated to infer its type.

Stripe-style expandable fields are a string ID when collapsed and an object when expanded. The generated type matches whichever your sample contained. Decide which form your handler receives and capture that delivery, or hand-write string | CustomerObject.

If two parts of the payload contain a Address object of different shapes, only the first interface is emitted and both reference it. Rename one JSON key before generating, or split the payload and generate separately.

An empty refunds: [] becomes refunds: unknown[]. Replace with the real element type or capture an event where the array is populated.

Stripe sends created as a Unix-epoch number (number); other providers send ISO strings (string). The generated type matches the wire form — convert to Date in your handler as needed.

Input runs through JSON.parse after trimming; logs with surrounding text, trailing commas, or non-JSON wrappers throw. Isolate the pure JSON body (or fix with json-format-fixer) before regenerating.