Migrating from Knock, Courier, OneSignal or Novu.

// notify/types.ts: reviewed in pull requests like any other code.
import { Notify } from "@productcraft/notify";

const notify = new Notify();

type TypeBody = Parameters<typeof notify.notificationTypes.replaceByKey>[1];

const categories = [
  { key: "security", name: "Security", transactional: true, defaults: { inbox: "mandatory", email: "mandatory" } },
  { key: "billing", name: "Billing", transactional: true },
  { key: "product", name: "Product updates", defaults: { email: "off" } },
] as const;

const types: Record<string, TypeBody> = {
  "security.new_sign_in": {
    name: "New sign-in",
    category_key: "security",
    critical: true, // ignores opt-outs and quiet hours (never bounces or complaints)
    ttl_seconds: 3600,
    routing: { always: ["inbox"], fallback: [{ channel: "push" }, { channel: "email" }] },
    templates: [
      { channel: "inbox", locale: "en", body: { title: "New sign-in from {{city}}", body: "{{device}} at {{time}}. Not you? Secure your account." } },
      { channel: "inbox", locale: "pt", body: { title: "Novo início de sessão em {{city}}", body: "{{device}} às {{time}}. Não foi você? Proteja a sua conta." } },
      { channel: "push", locale: "en", body: { title: "New sign-in", body: "{{device}} in {{city}}", url: "https://app.example.com/security" } },
      { channel: "email", locale: "en", body: { mail_template_name: "security-new-sign-in" } },
    ],
  },
};

// Apply on deploy. Both calls are upserts: running them twice changes nothing.
const existing = new Set((await notify.categories.list().toArray({ maxItems: 200 })).map((c) => c.key));
for (const c of categories) {
  if (!existing.has(c.key)) await notify.categories.create({ ...c });
}
for (const [key, body] of Object.entries(types)) {
  await notify.notificationTypes.replaceByKey(key, body);
}

import { Notify } from "@productcraft/notify";

const notify = new Notify();

type Row = Parameters<typeof notify.recipients.bulkIdentify>[0]["recipients"][number];

// Your export from the old provider, mapped to Notify rows.
declare const oldUsers: Array<{ id: string; email?: string; locale?: string; apnsTokens: string[]; mutedCategories: string[] }>;

const rows: Row[] = oldUsers.map((u) => ({
  external_id: u.id,
  email: u.email,
  locale: u.locale,
  devices: u.apnsTokens.map((token) => ({ channel: "apns" as const, token, app_id: "com.example.app", environment: "production" as const })),
  preferences: u.mutedCategories.map((key) => ({ scope: "category" as const, key, channel: "*" as const, enabled: false })),
}));

// 1,000 rows per call, 20 calls a minute. A bad row is reported, never fails the batch.
for (let i = 0; i < rows.length; i += 1000) {
  const batch = rows.slice(i, i + 1000);
  const result = await notify.recipients.bulkIdentify(
    { recipients: batch },
    { idempotencyKey: `import:2026-11:${i}` }, // a re-run replays, it does not re-import
  );
  for (const r of result.data) if (r.status === "error") console.warn(r.external_id, r.error);
  await new Promise((resolve) => setTimeout(resolve, 3_000));
}

// Your current provider's VAPID key pair (base64url, P-256). Existing
// browser subscriptions were made with this public key, so they keep working.
await notify.channels.webpush.importVapidKeys({
  public_key: process.env.OLD_VAPID_PUBLIC_KEY!,
  private_key: process.env.OLD_VAPID_PRIVATE_KEY!,
});

import { Notify } from "@productcraft/notify";

const notify = new Notify();
declare const oldProvider: { trigger(workflow: string, opts: { recipients: string[]; data: object; idempotencyKey: string }): Promise<void> };

// Phase 1: send to both, Notify restricted to the inbox (users see one bell).
// Phase 2: move channels over one by one with `channels`, then stop the old call.
export async function commentCreated(commentId: string, recipients: string[], data: Record<string, string>) {
  const key = `comment-created:${commentId}`; // the same deterministic key on both sides
  await oldProvider.trigger("comment-created", { recipients, data, idempotencyKey: key });
  await notify.notifications.send({ type: "comment.created", recipients, data, channels: ["inbox"] }, { idempotencyKey: key });
}