Type Safety - SuprSend, Notification infrastructure for Product teams

Overview

Type generation automatically creates strongly typed programming language interfaces from your SuprSend JSON schemas. Instead of manually writing type definitions, you define your workflow payload structure once as a JSON schema in SuprSend, and the CLI generates type-safe interfaces for TypeScript, Python, Go, Java, Kotlin, Swift, or Dart. This ensures payloads sent to workflows always match the expected schema, catching errors at compile time instead of at runtime.

Generated type files are auto-generated and should not be manually edited. Regenerate types when you update schemas in SuprSend.

Why Use Type Generation?

Without type generation, you work with plain objects that can lead to runtime errors. Type generation catches these errors during development with compile-time type safety and IDE autocomplete.

// ❌ Without types - bug may show up only at runtime
const data1 = { invoice_amount: "5000" };
const total1 = data1.invoice_amount + 500; // "5000500" (string concat)


// ✅ With generated types - error caught during development
type OrderCreatedEventData = {
  invoice_amount: number;
};
const data2: OrderCreatedEventData = { invoice_amount: "5000" };
//                         ^^^^^^^^^ TypeScript error:
// Type 'string' is not assignable to type 'number'.

You get early error detection, IDE autocomplete, immediate feedback when schemas change, and self-documenting code.

Generate Types

Prerequisites

Before generating types, ensure you have:

✅ SuprSend CLI installed
✅ Authenticated with your workspace
✅ Created and enabled schemas for your workflows (see guide)

Command Syntax

Once you’ve completed all the prerequisites, you can generate types using the following command in CLI. It will create type definitions for all the live schemas in your workspace:

suprsend generate-types <language> --output-file <output-file> [flags]

Here’s an example of how to generate types in all languages:

suprsend generate-types typescript
suprsend generate-types typescript --output-file types.ts

suprsend generate-types python
suprsend generate-types python --output-file types.py

suprsend generate-types go
suprsend generate-types go --output-file types.go

suprsend generate-types java
suprsend generate-types java --output-file types.java

suprsend generate-types kotlin
suprsend generate-types kotlin --output-file types.kt

suprsend generate-types swift
suprsend generate-types swift --output-file types.swift

suprsend generate-types dart
suprsend generate-types dart --output-file types.dart

Supported Languages

Language	File Extension	Default Output File
TypeScript	`.ts`	suprsend-types.ts
Python	`.py`	suprsend-types.py
Go	`.go`	suprsend-types.go
Java	`.java`	suprsend-types.java
Kotlin	`.kt`	suprsend-types.kt
Swift	`.swift`	suprsend-types.swift
Dart	`.dart`	suprsend-types.dart

For complete details on command arguments and flags, see the CLI Generate Types Reference.

Output File Structure

The output of the syntax generates a file with interfaces or definitions corresponding to all events and workflows that are linked to the schemas. So, there can’t be a mismatch between the schema mapped to the event or workflow while writing the code. All events are suffixed with Event keyword and workflows are suffixed with Workflow keyword.

from typing import Optional, List
from pydantic import BaseModel

class OrderCreatedEvent(BaseModel):
    order_id: str
    user_id: str
    order_amount: float
    currency: str
    payment_status: str
    discount_code: Optional[str] = None
    items_count: int

class SendInvoiceWorkflow(BaseModel):
    invoice_id: str
    invoice_amount: float
    invoice_date: str
    invoice_status: str
    invoice_due_date: str
    invoice_currency: str
    invoice_items: List[InvoiceItem]

export interface OrderCreatedEvent {
    order_id: string;
    user_id: string;
    order_amount: number;
    currency: string;
    payment_status: string;
    discount_code: string | null;
    items_count: number;
}

export interface SendInvoiceWorkflow {
    invoice_id: string;
    invoice_amount: number;
    invoice_date: string;
    invoice_status: string;
    invoice_due_date: string;
    invoice_currency: string;
    invoice_items: InvoiceItem[];
}

package main

type OrderCreatedEvent struct {
    OrderID string `json:"order_id"`
    UserID string `json:"user_id"`
    OrderAmount float64 `json:"order_amount"`
    Currency string `json:"currency"`
    PaymentStatus string `json:"payment_status"`
    DiscountCode string `json:"discount_code"`
    ItemsCount int `json:"items_count"`
}

type SendInvoiceWorkflow struct {
    InvoiceID string `json:"invoice_id"`
    InvoiceAmount float64 `json:"invoice_amount"`
    InvoiceDate string `json:"invoice_date"`
    InvoiceStatus string `json:"invoice_status"`
    InvoiceDueDate string `json:"invoice_due_date"`
    InvoiceCurrency string `json:"invoice_currency"`
    InvoiceItems []InvoiceItem `json:"invoice_items"`
}

package suprsend.types;

public class OrderCreatedEvent {
    private String orderID;
    private String userID;
    private double orderAmount;
    private String currency;
    private String paymentStatus;
    private String discountCode;
    private int itemsCount;
}

public class SendInvoiceWorkflow {
    private String invoiceID;
    private double invoiceAmount;
    private String invoiceDate;
    private String invoiceStatus;
    private String invoiceDueDate;
    private String invoiceCurrency;
    private List<InvoiceItem> invoiceItems;
}

Use Generated Types

Once generated, you can import the type definitions in your workflow or event triggers to ensure type safety throughout your codebase.

import { Suprsend, WorkflowTriggerRequest } from "@suprsend/node-sdk";
//Import the generated types
import { SendInvoiceWorkflow, OrderCreatedEvent } from "./suprsend-types";

const client = new Suprsend("workspace_key", "workspace_secret");

// ✅ Type-safe data creation
const triggerData: SendInvoiceWorkflow = {
   order_id: "Order-1234",
   user_id: "User-1234",
   order_amount: 5000,
   currency: "USD"
};

const body = {
   workflow: "send-invoice",
   recipients: [
       {
           distinct_id: "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
           $email: ["abc@example.com"],
           name: "recipient_1",
       },
   ],
   data: triggerData, // ✅ Type-safe
};

const wf = new WorkflowTriggerRequest(body, {
   tenant_id: "tenant_id",
   idempotency_key: "_unique_request_identifier",
});

const response = await client.workflows.trigger(wf);
console.log("response", response);

from suprsend import Suprsend, WorkflowTriggerRequest
# Import the generated types
from suprsend-types import SendInvoiceWorkflow, OrderCreatedEvent

supr_client = Suprsend("workspace_key", "workspace_secret")

# ✅ Type-safe data creation - Pydantic validates at runtime
trigger_data = SendInvoiceWorkflow(
   order_id="Order-1234",
   user_id="User-1234",
   order_amount=5000,
   currency="USD"
)

w1 = WorkflowTriggerRequest(
   body={
       "workflow": "send-invoice",
       "recipients": [
           {
               "distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
               "$email": ["abc@example.com"],
               "name": "recipient_1"
           }
       ],
       "data": trigger_data.model_dump(), # ✅ Convert Pydantic model to dict in Pydantic v2. For Pydantic v1, use .dict() instead.
   },
   tenant_id="tenant_id",
   idempotency_key="_unique_identifier_of_the_request_",
)

response = supr_client.workflows.trigger(w1)
print(response)

package main

import (
   "encoding/json"
   "log"
   suprsend "github.com/suprsend/suprsend-go"
)

func triggerWorkflowAPI(suprClient *suprsend.Client) {
   // ✅ Type-safe struct creation
   triggerData := SendInvoiceWorkflow{
       invoice_id: "Invoice-1234",
       invoice_amount: 5000,
       invoice_date: "2025-01-01",
       invoice_status: "paid",
       invoice_items: []InvoiceItem{
           {
               item_id: "Item-1234",
           }
       }
   }

   // Convert struct to map for workflow payload
   data := make(map[string]interface{})
   jsonData, _ := json.Marshal(triggerData)
   _ = json.Unmarshal(jsonData, &data)

   wfReqBody := map[string]interface{}{
       "workflow": "send-invoice",
       "recipients": []map[string]interface{}{
           {
               "distinct_id":         "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
               "$email":              []string{"abc@example.com"},
               "name":                "recipient_1",
           },
       },
       "data": data, // ✅ Type-safe struct converted to map
   }

   w1 := &suprsend.WorkflowTriggerRequest{
       Body:           wfReqBody,
       TenantId:       "tenant_id",
       IdempotencyKey: "_unique_identifier_of_the_request_",
   }

   resp, err := suprClient.Workflows.Trigger(w1)
   if err != nil {
       log.Fatalln(err)
   }
   log.Println(resp)
}

import org.json.JSONObject;
import org.json.JSONArray;
import suprsend.Suprsend;
import suprsend.WorkflowTriggerRequest;
import suprsend.types.SendInvoiceWorkflow; //Import the generated type
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.lang.reflect.Field;

public class Workflow {
   
   public static Map<String, Object> toMap(Object obj) {
       Map<String, Object> map = new HashMap<>();
       try {
           for (Field field : obj.getClass().getDeclaredFields()) {
               field.setAccessible(true);
               map.put(field.getName(), field.get(obj));
           }
       } catch (IllegalAccessException e) {
           throw new RuntimeException("Failed to convert object to map", e);
       }
       return map;
   }

   private static void triggerWorkflow() {
       Suprsend suprClient = new Suprsend("workspace_key", "workspace_secret");

       // ✅ Type-safe data creation
       SendInvoiceWorkflowData triggerData = new SendInvoiceWorkflowData();
       triggerData.setInvoiceID("Invoice-1234");
       triggerData.setInvoiceAmount(5000);
       triggerData.setInvoiceDate("2025-01-01");
       triggerData.setInvoiceStatus("paid");

       JSONObject data = new JSONObject(toMap(triggerData));

       JSONObject body = new JSONObject()
           .put("workflow", "send-invoice")
           .put("recipients", new JSONArray()
               .put(new JSONObject()
                   .put("distinct_id", "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09")
                   .put("$email", Arrays.asList("abc@example.com"))
                   .put("name", "recipient_1")
               )
           )
           .put("data", data); // ✅ Type-safe

       WorkflowTriggerRequest wf = new WorkflowTriggerRequest(
           body, 
           "_unique_identifier_of_the_request_",
           "tenant_id"
       );

       JSONObject resp = suprClient.workflows.trigger(wf);
       System.out.println(resp);
   }
}

With Pydantic models (Python), you get runtime validation. Invalid data types will raise validation errors with clear messages.

Best Practices

Don’t edit generated files - treat them as build artifacts and regenerate from schema changes.
Regenerate on schema updates - keep types in sync with SuprSend schemas (ideally in the same PR as schema changes).
Automate in CI/CD - run type generation in your pipeline and fail the build if generated output is out of date.
Version your schemas - evolve payloads safely without breaking existing producers/consumers.
Use types at boundaries - type the payload right before calling workflows.trigger(...) (and validate incoming webhook/event payloads).

Frequently Asked Questions

My generated types are outdated. What should I do?

If generated types don’t match your current schemas, regenerate them using the CLI:

suprsend generate-types typescript --output-file types.ts

Always regenerate types after updating or committing schemas in SuprSend.

Why are some fields missing in my generated types?

This usually happens when:

The schema is still in draft and not committed
Types were not regenerated after schema changes

Ensure the schema is committed and regenerate the types using the CLI.

Why do I see type errors in my IDE but the code still runs?

This typically means:

Generated types are outdated
The schema was changed in SuprSend but types weren’t regenerated
You’re generating types from the wrong workspace

Regenerate types and verify the --workspace flag if used.

What happens if I don’t use type safety?

Without type safety:

Errors surface only at runtime
Invalid payloads may partially process
Workflow conditions and templates can break silently
Debugging becomes harder across environments

Should I edit the generated type files?

No. Generated files should not be edited manually. Any changes will be overwritten the next time types are regenerated. Always update schemas in SuprSend and regenerate types.

How often should I regenerate types?

You should regenerate types whenever:

A schema is added or updated
A field is added, removed, or renamed
A field’s datatype changes

Many teams automate this in CI/CD.

Can I automate type generation in CI/CD?

Yes. It’s recommended to add type generation to your CI/CD pipeline to ensure schemas and application code stay in sync across environments.

What does type safety mean in SuprSend workflows?

Type safety ensures that the data you send when triggering workflows or events strictly matches the schema defined in SuprSend. This helps catch missing fields, wrong data types, or invalid payloads during development instead of at runtime.

Why should I use type-safe workflow triggers?

Type-safe triggers help prevent production bugs caused by incorrect payloads, improve developer experience with autocomplete and validation, and ensure your workflow logic always receives valid and expected data.

How does SuprSend generate type-safe interfaces?

SuprSend generates strongly typed interfaces directly from your JSON schemas. You define the schema once in SuprSend, and the CLI generates language-specific types (TypeScript, Python, Go, Java, Kotlin, Swift, Dart) that stay in sync with your workflows.

Which languages are supported for type generation?

SuprSend supports type generation for:

TypeScript
Python
Go
Java
Kotlin
Swift
Dart

Validate Trigger Payload - Learn about JSON schemas and how to link them to workflows or events
CLI Generate Types Reference - Complete CLI command reference for generating types

​Overview

​Why Use Type Generation?

​Generate Types

​Prerequisites

​Command Syntax

​Supported Languages

​Output File Structure

​Use Generated Types

​Best Practices

​Frequently Asked Questions

​Related Documentation

Overview

Why Use Type Generation?

Generate Types

Prerequisites

Command Syntax

Supported Languages

Output File Structure

Use Generated Types

Best Practices

Frequently Asked Questions

Related Documentation