@uninspired/newsletter-client

Typed client for the newsletter API.

Development

bun run build   # ESM + CJS in dist/, with .d.ts
bun run check
bun run lint

hono is a peer dependency. In the monorepo, workspace resolution uses src/index.ts directly; published tarballs use dist/ entry points (applied from publishConfig during prepack).

Publishing (npm)

cd packages/newsletter-client
npm publish

prepack builds and swaps entry points to dist/; postpack restores the dev manifest.

Usage

import {
  NewsletterClient,
  defaultSubscribeCallbackUrl,
  defaultUnsubscribeCallbackUrl,
  unsubscribePageUrl,
} from "@uninspired/newsletter-client";

const accountsFrontendUrl = "https://uninspired.app";

const client = new NewsletterClient(
  "https://api.newsletter.uninspired.app",
  "your-public-key",
);

await client.subscribe({
  email: "[email protected]",
  userGroup: "momentum",
  callbackUrl: defaultSubscribeCallbackUrl(accountsFrontendUrl),
});

await client.unsubscribe("[email protected]");

callbackUrl is where the user is sent after they confirm opt-in. The helpers above point at the accounts frontend:

| Helper | Path | |---|---| | defaultSubscribeCallbackUrl | /newsletter/subscribe/success | | defaultUnsubscribeCallbackUrl | /newsletter/unsubscribe/success (for GET /api/newsletter/unsubscribe?redirect=) | | unsubscribePageUrl | /newsletter/unsubscribe (link this from emails; pass email to skip the form) |

Develop: use https://dev.uninspired.app as accountsFrontendUrl. You can still pass a product-app URL as callbackUrl if you host your own confirmation page.

Pass the newsletter API origin (not the /api/newsletter path). The client sends X-Public-Key on every request. Subscribe requires a matching browser Origin for that key.

Only subscribe and unsubscribe are exposed — opt-in and one-click unsubscribe links are email/browser flows, not client methods.