@alrim-me/sdk

Official JavaScript SDK for alrim publish and subscribe flows.

The package has two runtime sides:

• @alrim-me/sdk/server — server-only publisher helpers. Never import this in browser code.
• @alrim-me/sdk/browser — public subscribe widget helpers for browser pages.

Server code derives private publishKey values from your private secret + channel name, publishes through alrim.io, and returns public subscribe config for browser UI. Browser code only receives public values such as channelCode and never receives secret or publishKey.

Install

npm install @alrim-me/sdk

Server publishing

Create a publisher once, then select a private channel with channel(name).

import { createAlrimPublisher } from "@alrim-me/sdk/server";

const alrim = createAlrimPublisher({
  secret: process.env.ALRIM_SECRET!,
});

await alrim.channel("deploys").publish({
  title: "Server deploy",
  body: "v1.2.3 shipped",
  data: { service: "api" },
});

"deploys" is not a public channel id. It is your private server-side channel name. The SDK derives:

publishKey = hmacSha256(secret, channelName)
channelCode = sha256(publishKey).slice(0, 32)

This means the same channel name with a different secret creates a different public channel.

Create public subscribe config

Use this on the server, then pass only the returned public config to browser/UI code.

const deploys = alrim.channel("deploys");

const subscribe = deploys.subscribeConfig({
  title: "Deploys",
  icon: "bolt",
  color: "emerald",
});

// Safe to expose:
// {
//   channelCode: '...',
//   title: 'Deploys',
//   icon: 'bolt',
//   color: 'emerald',
//   origin: 'https://alrim.me',
//   subscribeUrl: 'https://alrim.me/<channelCode>?title=Deploys&...'
// }

You can also create just the URL:

const subscribeUrl = alrim.channel("deploys").subscribeUrl({
  title: "Deploys",
});

Controls

The first argument to publish() is always the publisher-owned notification payload and is sent unchanged. Alrim-specific behavior goes in the second argument under controls, which the SDK sends as X-Alrim-* headers.

await alrim.channel("deploys").publish(
  {
    title: "High error rate",
    body: "api workers are above threshold",
  },
  {
    controls: {
      severity: "warning",
      show: "1",
      ring: "force",
      level: 2,
    },
  }
);

Supported controls:

• severity: 'info' | 'warning' | 'critical'
• show: '1' | 'hide'
• ring: 'silent' | 'force'
• level: non-negative integer

Fan-out publishing

Pass a channel-name array to channel() to publish the same payload to multiple channels in one request. There is no separate channels() API.

await alrim.channel(["deploys", "incidents"]).publish({
  title: "Server deploy",
  body: "v1.2.3 shipped",
});

For fan-out, the SDK derives one publish key per channel name and sends them through the X-Alrim-Key header while keeping the request body payload-only. Fan-out channel objects are publish-only; create subscribe config from a single alrim.channel("name") value.

Attachments

Pass attachments in the second argument to send multipart form data. The SDK puts the JSON payload in the data field and appends files as repeated files fields. Do not set Content-Type manually; the fetch runtime supplies the multipart boundary.

await alrim.channel("incidents").publish(
  {
    title: "Incident report",
    body: "Screenshots and runbook attached",
    data: { incidentId: "inc_123" },
  },
  {
    attachments: [
      chartFile,
      {
        name: "runbook.txt",
        content: "restart api workers",
        type: "text/plain",
      },
      {
        name: "payload.json",
        content: JSON.stringify({ incidentId: "inc_123" }),
        type: "application/json",
      },
    ],
  }
);

Each attachment can be:

• a File
• a Blob
• { name: string, content: string | ArrayBuffer | Uint8Array | Blob, type?: string }

Direct publish keys

If you already have publish keys, create a direct channel instead of using secret + channel name.

import { createAlrimChannel } from "@alrim-me/sdk/server";

const alerts = createAlrimChannel({
  publishKey: process.env.ALRIM_PUBLISH_KEY!,
});

await alerts.publish({
  title: "Direct publish",
  body: "Using an existing publish key",
});

Direct publish-key fan-out is also supported:

const alerts = createAlrimChannel({
  publishKey: [process.env.ALERTS_KEY!, process.env.INCIDENTS_KEY!],
});

await alerts.publish({ title: "Fan-out", body: "Sent to two publish keys" });

Low-level helpers

import {
  deriveChannelCode,
  deriveChannelFromSecret,
  derivePublishKey,
} from "@alrim-me/sdk/server";

const publishKey = derivePublishKey({
  secret: process.env.ALRIM_SECRET!,
  channel: "deploys",
});
const channelCode = deriveChannelCode(publishKey);
const channel = deriveChannelFromSecret({
  secret: process.env.ALRIM_SECRET!,
  channel: "deploys",
});

createAlrimPublisher validates secret immediately. Missing or empty secrets throw Missing secret before any derived helper runs.

Response and errors

publish() returns the parsed response from alrim.io.

type AlrimPublishResponse = {
  ok?: boolean;
  channel_code?: string;
  channel_url?: string;
  notification_id?: string;
  created_at_ms?: number;
  attachments?: unknown[];
  [key: string]: unknown;
};

Failed publish responses throw AlrimPublishError.

import { AlrimPublishError } from "@alrim-me/sdk/server";

try {
  await alrim.channel("deploys").publish({ title: "Ping" });
} catch (error) {
  if (error instanceof AlrimPublishError) {
    console.error(error.status, error.body);
  }
}

Advanced options

Use these for self-hosting, dev/staging, tests, or custom runtimes.

const alrim = createAlrimPublisher({
  secret: process.env.ALRIM_SECRET!,
  ioOrigin: "https://dev.alrim.io",
  meOrigin: "https://dev.alrim.me",
  fetch: customFetch,
});

Browser subscribe widget

The browser SDK renders subscribe buttons/modals with Shadow DOM. It only needs public subscribe config.

CDN custom element

Recommended no-build usage:

<script src="https://alrim.me/sdk/v1/alrim-subscribe.js"></script>

<alrim-me
  channel-code="3ba3f5f43b92602683c19aee62a20342"
  title="Deploys"
  icon="bolt"
  color="emerald"
  button-label="Get alerts"
></alrim-me>

origin defaults to https://alrim.me. Set it only for dev/staging/self-hosted pages.

<alrim-me
  channel-code="3ba3f5f43b92602683c19aee62a20342"
  title="Deploys"
  origin="https://dev.alrim.me"
></alrim-me>

For dynamic updates, call the element's update() method or set observed attributes such as channel-code, title, origin, and button-label.

document.querySelector("alrim-me")?.update({
  channelCode: "3ba3f5f43b92602683c19aee62a20342",
  title: "New title",
});

Attach to existing links/buttons

Keep your own markup and let the SDK open the alrim subscribe modal on click.

<a
  data-alrim-subscribe
  href="https://alrim.me/3ba3f5f43b92602683c19aee62a20342?title=Deploys"
>
  Follow deploy alerts
</a>

<script src="https://alrim.me/sdk/v1/alrim-subscribe.js"></script>
<script>
  AlrimSubscribe.auto();
</script>

You can also bind manually:

<button id="custom-subscribe">Open subscribe modal</button>

<script src="https://alrim.me/sdk/v1/alrim-subscribe.js"></script>
<script>
  const widget = AlrimSubscribe.attach("#custom-subscribe", {
    channelCode: "3ba3f5f43b92602683c19aee62a20342",
    title: "Deploys",
  });
</script>

Imperative mount

import { mount } from "@alrim-me/sdk/browser";

const widget = mount("#alrim-subscribe", {
  channelCode: "3ba3f5f43b92602683c19aee62a20342",
  title: "Deploys",
  buttonLabel: "Get alerts",
});

widget.open();
widget.update({
  channelCode: "3ba3f5f43b92602683c19aee62a20342",
  title: "Incidents",
});
widget.destroy();

Browser exports:

import {
  attach,
  auto,
  defineCustomElement,
  mount,
  open,
} from "@alrim-me/sdk/browser";

Framework adapters

React

import { AlrimSubscribe } from "@alrim-me/sdk/react";

export function SubscribeButton() {
  return (
    <AlrimSubscribe
      channelCode="3ba3f5f43b92602683c19aee62a20342"
      title="Deploys"
      buttonLabel="Get alerts"
    />
  );
}

Svelte

<script lang="ts">
  import { alrimSubscribe } from '@alrim-me/sdk/svelte';

  const config = {
    channelCode: '3ba3f5f43b92602683c19aee62a20342',
    title: 'Deploys',
    buttonLabel: 'Get alerts'
  };
</script>

<div use:alrimSubscribe={config}></div>

Vue

<script setup lang="ts">
import { AlrimSubscribe } from "@alrim-me/sdk/vue";

const config = {
  channelCode: "3ba3f5f43b92602683c19aee62a20342",
  title: "Deploys",
  buttonLabel: "Get alerts",
};
</script>

<template>
  <AlrimSubscribe :config="config" />
</template>

CDN versioning

Use the versioned CDN path in production examples:

<script src="https://alrim.me/sdk/v1/alrim-subscribe.js"></script>

/sdk/latest/alrim-subscribe.js exists for quick testing, but production pages should prefer the versioned path.