Skip to main content
Introducing packages.sweber.dev
Documentation menuAnnounce

Announce

E-mail digest and chat posts for new releases.

@weber-development/derivative-announce turns new releases into an e-mail and chat messages, in English, German, French or Italian.

E-mail digest

npx derivative-announce digest --feed public/changelog.json --product "Acme" \
  --url https://acme.example/changelog --lang de \
  --logo https://acme.example/logo.png --color "#0f766e" \
  --unsubscribe https://acme.example/unsubscribe --footer "Acme AG, Bahnhofstrasse 1, 8001 Zürich" \
  --state .announce-mail.json --out digest.html

This writes digest.html and digest.txt and prints the subject line. The layout uses tables and inline styles, so it renders in Outlook and Gmail. A release with an image (feed format 2) shows its first image, and its links appear as call-to-action links; with --lang the digest uses the translations in the feed. Sending is up to you: hand the files to Postmark, Resend, SES or your newsletter tool.

Chat

DERIVATIVE_WEBHOOK_URL=https://hooks.slack.com/... \
  npx derivative-announce post --to slack --feed public/changelog.json --product "Acme" \
  --state .announce-slack.json

--to accepts slack, teams, discord, mattermost and google-chat. Use --dry-run to print the payload instead. Keep webhook URLs in your CI secrets.

Mastodon

DERIVATIVE_MASTODON_TOKEN=... npx derivative-announce post --to mastodon \
  --instance https://mastodon.social --feed public/changelog.json --product "Acme" \
  --hashtag changelog --state .announce-mastodon.json

Each release becomes one public status of at most 500 characters: title, the first summary paragraph and as many entries as fit, then the changelog link and hashtags. Create the token under Preferences → Development with only the write:statuses scope. The instance can also come from DERIVATIVE_MASTODON_URL.

Bluesky

DERIVATIVE_BLUESKY_APP_PASSWORD=... npx derivative-announce post --to bluesky \
  --handle acme.bsky.social --feed public/changelog.json --product "Acme" \
  --hashtag changelog --state .announce-bluesky.json

Each release becomes one post of at most 300 characters with the changelog as a link card and the hashtags as real tags. Create an app password under Settings → Privacy and security → App passwords; never use the account password. The handle can also come from DERIVATIVE_BLUESKY_HANDLE.

LinkedIn

DERIVATIVE_LINKEDIN_TOKEN=... npx derivative-announce post --to linkedin \
  --author urn:li:organization:123456 --feed public/changelog.json --product "Acme" \
  --hashtag changelog --state .announce-linkedin.json

Each release becomes one post on your company page, with the summary and entries as text and the changelog as a link card. Texts are escaped so characters like (, # or _ show up as typed. The access token needs the w_organization_social scope (or w_member_social for a personal profile with urn:li:person:…); LinkedIn issues it after you add the "Share on LinkedIn" product to your app. The author can also come from DERIVATIVE_LINKEDIN_AUTHOR. The API version header is set to last month's YYYYMM; pin another one with DERIVATIVE_LINKEDIN_VERSION. Tokens expire (60 days by default), so renew the secret in your CI before then. Use --dry-run to see the post first.

Subscribers

The digest above leaves the sending to you. For a real subscriber list, Derivative Pro runs the whole cycle with double opt-in: sign-up form, confirmation e-mail, one-click unsubscribe and the sending itself, through Resend, Postmark, Amazon SES or any SMTP server. There is no third-party list to maintain and no tracking: a subscriber is an e-mail address, a language and the timestamps of the request and the confirmation.

1. The handler

One Fetch API handler (Next.js route handler, Hono, Remix, Deno, Bun, Cloudflare Workers) answers POST /subscribe, /confirm and /unsubscribe below the URL where you mount it:

// app/api/news/[action]/route.ts (Next.js)
import { createSubscribeHandler, resendSender } from "@weber-development/derivative-announce";
import { fileSubscribers } from "@weber-development/derivative-announce/node";

const handler = createSubscribeHandler({
  store: fileSubscribers(".data/subscribers.json"),
  secret: process.env.DERIVATIVE_SUBSCRIBE_SECRET!, // 32+ random characters, keep it secret
  send: resendSender(process.env.DERIVATIVE_RESEND_KEY!),
  from: "Acme <news@acme.ch>", // the domain must be verified at your provider
  product: "Acme",
  baseUrl: "https://acme.ch/api/news",
  lang: "de",
});
export { handler as GET, handler as POST };

Your form posts email (and optionally lang) to /api/news/subscribe, as a form or as JSON with Accept: application/json. The answer is the same for known and unknown addresses.

What the handler takes care of, so you do not have to:

  • Double opt-in. An address is only mailed after its owner clicked the link. The link carries a signed token that expires after seven days and works for confirming only.
  • Mail scanners. Corporate scanners open every link in a mail. The confirm and unsubscribe links therefore show a button, and only the click on it (a POST) changes anything.
  • One-click unsubscribe. The same POST answers the request that Gmail and Yahoo send for the List-Unsubscribe-Post header (RFC 8058), which both require from bulk senders.
  • No mail bombing. An unconfirmed address is not mailed again within ten minutes, and a confirmed one is never mailed by the form.
  • Header injection. Addresses with line breaks or other special characters are rejected.

Without a disk (Vercel, Workers), keep the list in Postgres or SQLite with sqlSubscribers(query, { dialect }); store.setup() creates the table. It takes the same driver-free query function as sqlStore in derivative-insights.

2. Sending

DERIVATIVE_SUBSCRIBE_SECRET=... DERIVATIVE_RESEND_KEY=... npx derivative-announce send \
  --feed public/changelog.json --subscribers .data/subscribers.json \
  --from "Acme <news@acme.ch>" --provider resend --base-url https://acme.ch/api/news \
  --product "Acme" --lang de --state .announce-mail.json

Each confirmed subscriber gets one e-mail with a personal unsubscribe link and the List-Unsubscribe headers. --provider postmark uses DERIVATIVE_POSTMARK_TOKEN and the broadcast message stream. --provider ses uses Amazon SES with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN) and AWS_REGION; the AWS user needs only ses:SendEmail, and requests are signed in the package, without the AWS SDK. --provider smtp uses any SMTP server through DERIVATIVE_SMTP_URL, for example smtps://user:password@smtp.example.com:465 (TLS from the start) or smtp://user:password@smtp.example.com:587 (STARTTLS); percent-encode special characters in the password. TLS is required: the password is never sent over a connection without it. In code: sesSender(credentials, { region }) and, from /node, smtpSender({ host, port, user, pass }). --dry-run counts the recipients. With --state, each release goes out once. Addresses that fail are listed and the exit code is 1; the others have their mail. In code, call sendDigest({ releases, brand, store, send, secret, baseUrl, from }).

3. Managing the list

npx derivative-announce subscribers list   --file .data/subscribers.json
npx derivative-announce subscribers export --file .data/subscribers.json --status confirmed > consent.csv
npx derivative-announce subscribers remove --file .data/subscribers.json --email max@example.ch

export writes the evidence of consent: when each address was requested and confirmed. remove deletes an address completely, for erasure requests.

This is a technical aid, not legal advice. In Germany, Austria and Switzerland the double opt-in with a stored confirmation time is the usual proof that the owner of the address agreed. Mention the newsletter in your privacy policy (purpose, provider, how to unsubscribe) and your e-mail provider as a processor, and sign a data processing agreement with them. The confirmation e-mail and the digest contain no tracking pixels and no click tracking.

Each release once

--state <file> stores the newest announced release. The next run only picks up releases after it, so a CI job can run on every deploy. Use one state file per channel. Without a state file, --since <date> and --limit <n> select the releases.

In code

import {
  chatPayload,
  postWebhook,
  renderDigest,
  selectReleases,
} from "@weber-development/derivative-announce";

const releases = selectReleases(feed, { after: lastAnnounced });
const { subject, html, text } = renderDigest(releases, { name: "Acme", url }, { lang: "de" });
await postWebhook(webhookUrl, chatPayload("teams", releases[0], { product: "Acme", url }));