@jterrazz/broadcast

Multi-channel broadcast system for distributing announcements across platforms. Define an announcement once, send it everywhere — App Store In-App Events, Google Play, push notifications, email, and more.

Install

npm install @jterrazz/broadcast

Quick Start

import { AppleAppStoreAdapter, sendBroadcast } from '@jterrazz/broadcast';

const apple = new AppleAppStoreAdapter({
    issuerId: 'your-issuer-id',
    keyId: 'YOUR_KEY_ID',
    privateKey: '-----BEGIN PRIVATE KEY-----\n...',
    appId: '6444444444',
});

await sendBroadcast(
    {
        title: 'Season 2 is live!',
        shortDescription: 'New features and challenges await',
        longDescription: 'Explore new game modes, leaderboards, and exclusive rewards.',
        badge: 'new-season',
        audience: 'all',
        priority: 'high',
        startDate: new Date('2026-04-01'),
        endDate: new Date('2026-04-30'),
        deepLink: 'myapp://seasons/2',
    },
    [apple],
);

sendBroadcast fans out to all providers concurrently. If one fails, the others still succeed — each result includes a status field.

Broadcast Model

Field	Type	Description
title	string	Display title (max ~30 chars for App Store compat)
shortDescription	string	Teaser for cards/previews (max ~50 chars)
longDescription	string	Detail view description (max ~120 chars)
startDate	Date	When the event starts
endDate	Date	When the event ends
badge	BroadcastBadge	Event category
audience	BroadcastAudience	Target audience
priority	"normal" | "high"	Visibility level
deepLink	string?	Deep link URL into the app
requiresPurchase	boolean?	Whether participation requires a purchase
territories	string[]?	ISO 3166-1 alpha-2 country codes (default: all)

Badge Types

challenge · competition · live-event · major-update · new-season · premiere · special-event

Audience Types

all · new-users · active-users · lapsed-users

Providers

Apple App Store (In-App Events)

Creates In-App Events on the App Store via the App Store Connect API.

Setup

1. Go to App Store Connect → Users and Access → Integrations → App Store Connect API
2. Click Generate API Key
   • Name: e.g. signews-broadcast
   • Access: Admin (required for In-App Events)
3. Download the .p8 file — you can only download it once
4. Note the Key ID shown in the table (e.g. 2X9R4HXF34)
5. Copy the Issuer ID shown at the top of the page
6. Find your App ID: go to Apps → your app → App Information → Apple ID

Usage

import { readFileSync } from 'node:fs';
import { AppleAppStoreAdapter } from '@jterrazz/broadcast';

const apple = new AppleAppStoreAdapter({
    issuerId: '57246542-96fe-1a63-e053-0824d011072a',
    keyId: '2X9R4HXF34',
    privateKey: readFileSync('./AuthKey_2X9R4HXF34.p8', 'utf-8'),
    appId: '6444444444',
});

// Create an event
const result = await apple.create({
    title: 'Election Live Coverage',
    shortDescription: 'Real-time results & analysis',
    longDescription: 'Follow live election coverage with AI-powered fact-checking and analysis.',
    badge: 'live-event',
    audience: 'all',
    priority: 'high',
    startDate: new Date('2026-11-03'),
    endDate: new Date('2026-11-04'),
    deepLink: 'signews://live/election-2026',
    territories: ['USA', 'FRA'],
});

// List existing events
const events = await apple.list();

// Update an event
await apple.update('event-id', { priority: 'normal' });

// Delete an event
await apple.delete('event-id');

Field Mapping

Broadcast	Apple In-App Event
title	referenceName + localized name
shortDescription	Localized shortDescription
longDescription	Localized longDescription
badge	badge (CHALLENGE, COMPETITION, etc.)
audience	purpose (APPROPRIATE_FOR_ALL_USERS, ATTRACT_NEW_USERS, ATTRACT_LAPSED_USERS)
priority	priority (NORMAL, HIGH)
requiresPurchase	purchaseRequirement (NO_COST_ASSOCIATED, IN_APP_PURCHASE)
territories	territorySchedules
deepLink	deepLink

Limits

• Max 15 approved events at a time in App Store Connect
• Max 10 events published simultaneously on the App Store
• Events can last up to 31 days
• Events can be promoted up to 14 days before start

More Providers (Planned)

• Google Play Events — Google Play Store promotional events
• Push Notifications — APNs and FCM
• Email Digests — Transactional email providers
• In-App Banners — JSON/REST endpoint for web and desktop apps

Multi-Provider Example

import { sendBroadcast } from '@jterrazz/broadcast';

const results = await sendBroadcast(broadcast, [apple, google, push]);

for (const result of results) {
    if (result.status === 'failed') {
        console.error(`${result.provider} failed:`, result.raw);
    } else {
        console.log(`${result.provider}: ${result.status} (${result.id})`);
    }
}

Custom Provider

Implement BroadcastProviderPort to add your own channel:

import type { BroadcastProviderPort } from '@jterrazz/broadcast';

class SlackProvider implements BroadcastProviderPort {
    readonly name = 'slack';

    async create(broadcast) {
        // Post to Slack webhook
    }

    async update(id, broadcast) {
        /* ... */
    }
    async delete(id) {
        /* ... */
    }
    async list() {
        /* ... */
    }
}

Development

npm install
npm test        # Run tests (vitest)
npm run build   # Build ESM + CJS (rolldown)
npm run lint    # Type check + oxlint + oxfmt