Custom Providers

Providers are the bridge between Norq compiled payloads and your delivery service. Each provider implements a send method that receives a recipient and compiled payload, then makes the appropriate API call.

See each SDK's documentation for provider implementation examples.

How it works

When you call notif.send(), the SDK:

  1. Compiles the template via the norq binary
  2. Looks up the provider for each channel (from norq.config.yaml routing)
  3. Calls the provider's send() method with the recipient and payload
  4. Returns aggregated results

Providers run in your application's language, using your language's HTTP libraries.

Provider interface

Every provider must implement three things:

Property/Method Type Description
name string Unique identifier (e.g., "resend", "twilio")
channels string[] Channels this provider supports
send() function Accepts recipient + channel + payload, returns result

Quick example (Node.js)

import type { Provider, Recipient, SendResult } from "norq";
 
export class MyProvider implements Provider {
  name = "my-provider";
  channels = ["email"];
 
  async send({ to, channel, payload }: {
    to: Recipient;
    channel: string;
    payload: any;
  }): Promise<SendResult> {
    const response = await fetch("https://api.my-service.com/send", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        to: to.email,
        subject: payload.subject,
        html: payload.html,
      }),
    });
 
    return {
      success: response.ok,
      provider: this.name,
      channel,
      message_id: (await response.json()).id,
    };
  }
}

Payload shapes

Each channel produces a specific payload:

Channel Fields
email subject (string), html (string), text (string)
sms body (string), segments (number), encoding (string)
slack blocks (array), text (string)
push title (string), body (string), image (string/null), action_url (string/null)
whatsapp type (string), payload (object)
msteams card (object)

Configuration

Register providers in norq.config.yaml:

providers:
  resend:
    package: "@norq/provider-resend"
    config:
      api_key: ${RESEND_API_KEY}
      from: "notifications@myapp.com"
 
routing:
  email: resend
  sms: twilio
  slack: slack

Multi-channel providers

A single provider can handle multiple channels:

export class SuprSendProvider implements Provider {
  name = "suprsend";
  channels = ["email", "sms", "push", "whatsapp"];
  // ...
}

Built-in providers

The CLI includes a console provider that prints payloads to stdout. This is used by norq send when no external providers are configured -- useful for testing and development.

Publishing

Follow the naming convention:

  • npm: @norq/provider-{name}
  • PyPI: norq-provider-{name}
  • Other registries: norq-provider-{name}