@gtrabanco/newsletter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Trabanco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @gtrabanco/newsletter
+
+Typed, zero-dependency newsletter client for external sites — published to the public npm registry.
+Workers-safe: uses native `fetch` only, no Node.js SDK.
+
+Wraps the central newsletter service (subscribe + double opt-in + unsubscribe) behind a simple,
+stable API so external repos need only a `NEWSLETTER_API_KEY` and know nothing about the internal
+endpoint shape.
+
+## Installation
+
+```bash
+npm install @gtrabanco/newsletter@0.1.0
+# or: bun add @gtrabanco/newsletter@0.1.0
+```
+
+Always pin the **exact** version (no `^` or `~`) — matches this package's convention.
+
+No `.npmrc` or PAT required — this package is on the public npm registry.
+
+## Usage
+
+```typescript
+import { createNewsletterClient } from '@gtrabanco/newsletter';
+
+const newsletter = createNewsletterClient({
+  apiKey: env.NEWSLETTER_API_KEY,
+  baseUrl: 'https://gtrabanco.com',
+});
+
+// Subscribe a user (double opt-in email is sent automatically)
+await newsletter.subscribe('user@example.com', {
+  language: 'es',
+  campaign: 'summer-2026',
+  referrer_domain: 'bingo.gruxon.com',
+  // Optional: where to land the user after they click the confirm link
+  confirmRedirectUrl: 'https://bingo.gruxon.com/subscribed',
+  // Optional: where to redirect after the unsubscribe confirm button is clicked
+  unsubscribeRedirectUrl: 'https://bingo.gruxon.com/unsubscribed',
+});
+
+// Unsubscribe via token from the List-Unsubscribe email header
+await newsletter.unsubscribeByToken(token);
+```
+
+## API
+
+### `createNewsletterClient(config)`
+
+```typescript
+createNewsletterClient({
+  apiKey: string,   // bearer token issued for your site
+  baseUrl: string,  // e.g. 'https://gtrabanco.com'
+}): NewsletterClient
+```
+
+### `client.subscribe(email, opts)`
+
+Calls `POST /api/v1/newsletter/subscribe`. On success returns `{ ok: true }`.
+
+| Option | Type | Required | Notes |
+|---|---|---|---|
+| `language` | `'es' \| 'en' \| 'ast'` | yes | Confirmation email language |
+| `campaign` | `string` | no | Acquisition campaign tag |
+| `referrer_domain` | `string` | no | Referring domain |
+| `confirmRedirectUrl` | `string` | no | Absolute HTTPS URL — where to send the user after DOI confirmation. Falls back to the source's configured base. |
+| `unsubscribeRedirectUrl` | `string` | no | Absolute HTTPS URL — where to redirect after unsubscribe confirm. Falls back to source base. |
+| `sender` | `{ name, email }` | no | **Forward-compat only — ignored by the server today.** Per-API-key sender config is a future dashboard feature. |
+
+### `client.unsubscribeByToken(token)`
+
+Calls `POST /api/v1/newsletter/unsubscribe?token=<encoded>`. On success returns `{ ok: true }`.
+The token comes from the `List-Unsubscribe` header of outgoing emails.
+
+## Errors
+
+```typescript
+import {
+  isNewsletterHTTPError,
+  isNewsletterNetworkError,
+} from '@gtrabanco/newsletter';
+
+try {
+  await newsletter.subscribe(email, opts);
+} catch (err) {
+  if (isNewsletterHTTPError(err)) {
+    // err.status, err.statusText, err.errorCode (e.g. 'RATE_LIMITED', 'ALREADY_SUBSCRIBED')
+  } else if (isNewsletterNetworkError(err)) {
+    // fetch() threw — no response received
+  }
+}
+```
+
+## Auth
+
+`apiKey` is a bearer token issued per site. Store it in `.dev.vars` locally and via
+`wrangler secret put NEWSLETTER_API_KEY` for Cloudflare Workers deploys. Never commit it.
+
+## Gotchas
+
+- `sender` is accepted in the request schema and forwarded to the server, but the server ignores it
+  and always uses the environment-default Brevo sender. This is intentional forward-compatibility —
+  per-API-key sender config is planned for a future dashboard feature.
+- `confirmRedirectUrl` / `unsubscribeRedirectUrl` must be absolute `https://` URLs. The server
+  rejects non-HTTPS values and falls back to the configured default.
+- `unsubscribeByToken()` is the only unsubscribe method — email-address-based unsubscribe is an
+  admin action, not exposed via this client.

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+export type NewsletterLanguage = 'es' | 'en' | 'ast';
+export type NewsletterSender = {
+    name: string;
+    email: string;
+};
+export type SubscribeOptions = {
+    language: NewsletterLanguage;
+    campaign?: string;
+    referrer_domain?: string;
+    /** Where to redirect the user after clicking the DOI confirm link in the email. Must be absolute HTTPS. */
+    confirmRedirectUrl?: string;
+    /** Where to redirect the user after completing the unsubscribe confirm flow. Must be absolute HTTPS. */
+    unsubscribeRedirectUrl?: string;
+    /** Forward-compat — accepted by the server schema but ignored until dashboard feature ships. */
+    sender?: NewsletterSender;
+};
+export type NewsletterClient = {
+    subscribe(email: string, opts: SubscribeOptions): Promise<{
+        ok: true;
+    }>;
+    unsubscribeByToken(token: string): Promise<{
+        ok: true;
+    }>;
+};
+export declare function createNewsletterClient(config: {
+    apiKey: string;
+    baseUrl: string;
+}): NewsletterClient;

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class NewsletterError {
+    readonly message: string;
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+    toString(): string;
+    get name(): string;
+}
+export declare class NewsletterHTTPError extends NewsletterError {
+    readonly status: number;
+    readonly statusText: string;
+    readonly errorCode?: string;
+    constructor(status: number, statusText: string, errorCode?: string);
+    get name(): string;
+}
+export declare class NewsletterNetworkError extends NewsletterError {
+    constructor(cause: unknown);
+    get name(): string;
+}
+export declare function isNewsletterHTTPError(error: unknown): error is NewsletterHTTPError;
+export declare function isNewsletterNetworkError(error: unknown): error is NewsletterNetworkError;

package/dist/index.cjs

@@ -0,0 +1,167 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  isNewsletterNetworkError: () => isNewsletterNetworkError,
+  isNewsletterHTTPError: () => isNewsletterHTTPError,
+  createNewsletterClient: () => createNewsletterClient,
+  NewsletterNetworkError: () => NewsletterNetworkError,
+  NewsletterHTTPError: () => NewsletterHTTPError,
+  NewsletterError: () => NewsletterError
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/errors.ts
+class NewsletterError {
+  message;
+  cause;
+  constructor(message, cause) {
+    this.message = message;
+    if (cause !== undefined)
+      this.cause = cause;
+  }
+  toString() {
+    return `${this.name}: ${this.message}`;
+  }
+  get name() {
+    return "NewsletterError";
+  }
+}
+
+class NewsletterHTTPError extends NewsletterError {
+  status;
+  statusText;
+  errorCode;
+  constructor(status, statusText, errorCode) {
+    super(`HTTP ${status}: ${statusText}`);
+    this.status = status;
+    this.statusText = statusText;
+    if (errorCode !== undefined)
+      this.errorCode = errorCode;
+  }
+  get name() {
+    return "NewsletterHTTPError";
+  }
+}
+
+class NewsletterNetworkError extends NewsletterError {
+  constructor(cause) {
+    super("Network error", cause);
+  }
+  get name() {
+    return "NewsletterNetworkError";
+  }
+}
+function isNewsletterHTTPError(error) {
+  return error instanceof NewsletterHTTPError;
+}
+function isNewsletterNetworkError(error) {
+  return error instanceof NewsletterNetworkError;
+}
+
+// src/client.ts
+async function parseErrorCode(response) {
+  try {
+    const body = await response.clone().json();
+    const code = body["error"];
+    return typeof code === "string" ? code : undefined;
+  } catch {
+    return;
+  }
+}
+function createNewsletterClient(config) {
+  const { apiKey, baseUrl } = config;
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  return {
+    async subscribe(email, opts) {
+      const body = {
+        email,
+        language: opts.language
+      };
+      if (opts.campaign !== undefined)
+        body["campaign"] = opts.campaign;
+      if (opts.referrer_domain !== undefined)
+        body["referrer_domain"] = opts.referrer_domain;
+      if (opts.confirmRedirectUrl !== undefined)
+        body["confirm_redirect_url"] = opts.confirmRedirectUrl;
+      if (opts.unsubscribeRedirectUrl !== undefined)
+        body["unsubscribe_redirect_url"] = opts.unsubscribeRedirectUrl;
+      if (opts.sender !== undefined)
+        body["sender"] = opts.sender;
+      let response;
+      try {
+        response = await fetch(`${base}/api/v1/newsletter/subscribe`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json"
+          },
+          body: JSON.stringify(body)
+        });
+      } catch (cause) {
+        throw new NewsletterNetworkError(cause);
+      }
+      if (!response.ok) {
+        const errorCode = await parseErrorCode(response);
+        throw new NewsletterHTTPError(response.status, response.statusText, errorCode);
+      }
+      return { ok: true };
+    },
+    async unsubscribeByToken(token) {
+      let response;
+      try {
+        response = await fetch(`${base}/api/v1/newsletter/unsubscribe?token=${encodeURIComponent(token)}`, {
+          method: "POST",
+          headers: {
+            Accept: "application/json"
+          }
+        });
+      } catch (cause) {
+        throw new NewsletterNetworkError(cause);
+      }
+      if (!response.ok) {
+        const errorCode = await parseErrorCode(response);
+        throw new NewsletterHTTPError(response.status, response.statusText, errorCode);
+      }
+      return { ok: true };
+    }
+  };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { NewsletterClient, NewsletterLanguage, NewsletterSender, SubscribeOptions, } from './client';
+export { createNewsletterClient } from './client';
+export { NewsletterError, NewsletterHTTPError, NewsletterNetworkError, isNewsletterHTTPError, isNewsletterNetworkError, } from './errors';

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/errors.ts
+class NewsletterError {
+  message;
+  cause;
+  constructor(message, cause) {
+    this.message = message;
+    if (cause !== undefined)
+      this.cause = cause;
+  }
+  toString() {
+    return `${this.name}: ${this.message}`;
+  }
+  get name() {
+    return "NewsletterError";
+  }
+}
+
+class NewsletterHTTPError extends NewsletterError {
+  status;
+  statusText;
+  errorCode;
+  constructor(status, statusText, errorCode) {
+    super(`HTTP ${status}: ${statusText}`);
+    this.status = status;
+    this.statusText = statusText;
+    if (errorCode !== undefined)
+      this.errorCode = errorCode;
+  }
+  get name() {
+    return "NewsletterHTTPError";
+  }
+}
+
+class NewsletterNetworkError extends NewsletterError {
+  constructor(cause) {
+    super("Network error", cause);
+  }
+  get name() {
+    return "NewsletterNetworkError";
+  }
+}
+function isNewsletterHTTPError(error) {
+  return error instanceof NewsletterHTTPError;
+}
+function isNewsletterNetworkError(error) {
+  return error instanceof NewsletterNetworkError;
+}
+
+// src/client.ts
+async function parseErrorCode(response) {
+  try {
+    const body = await response.clone().json();
+    const code = body["error"];
+    return typeof code === "string" ? code : undefined;
+  } catch {
+    return;
+  }
+}
+function createNewsletterClient(config) {
+  const { apiKey, baseUrl } = config;
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  return {
+    async subscribe(email, opts) {
+      const body = {
+        email,
+        language: opts.language
+      };
+      if (opts.campaign !== undefined)
+        body["campaign"] = opts.campaign;
+      if (opts.referrer_domain !== undefined)
+        body["referrer_domain"] = opts.referrer_domain;
+      if (opts.confirmRedirectUrl !== undefined)
+        body["confirm_redirect_url"] = opts.confirmRedirectUrl;
+      if (opts.unsubscribeRedirectUrl !== undefined)
+        body["unsubscribe_redirect_url"] = opts.unsubscribeRedirectUrl;
+      if (opts.sender !== undefined)
+        body["sender"] = opts.sender;
+      let response;
+      try {
+        response = await fetch(`${base}/api/v1/newsletter/subscribe`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json"
+          },
+          body: JSON.stringify(body)
+        });
+      } catch (cause) {
+        throw new NewsletterNetworkError(cause);
+      }
+      if (!response.ok) {
+        const errorCode = await parseErrorCode(response);
+        throw new NewsletterHTTPError(response.status, response.statusText, errorCode);
+      }
+      return { ok: true };
+    },
+    async unsubscribeByToken(token) {
+      let response;
+      try {
+        response = await fetch(`${base}/api/v1/newsletter/unsubscribe?token=${encodeURIComponent(token)}`, {
+          method: "POST",
+          headers: {
+            Accept: "application/json"
+          }
+        });
+      } catch (cause) {
+        throw new NewsletterNetworkError(cause);
+      }
+      if (!response.ok) {
+        const errorCode = await parseErrorCode(response);
+        throw new NewsletterHTTPError(response.status, response.statusText, errorCode);
+      }
+      return { ok: true };
+    }
+  };
+}
+export {
+  isNewsletterNetworkError,
+  isNewsletterHTTPError,
+  createNewsletterClient,
+  NewsletterNetworkError,
+  NewsletterHTTPError,
+  NewsletterError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gtrabanco/newsletter",
+  "version": "0.1.0",
+  "type": "module",
+  "author": {
+    "name": "Gabriel Trabanco",
+    "url": "https://github.com/gtrabanco"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun run build:esm && bun run build:cjs",
+    "postbuild": "bun run build:types",
+    "build:types": "tsc -p tsconfig.dts.json",
+    "build:esm": "bun build --target=node --format=esm --outfile=dist/index.js ./src/index.ts",
+    "build:cjs": "bun build --target=node --format=cjs --outfile=dist/index.cjs ./src/index.ts"
+  },
+  "peerDependencies": {
+    "typescript": "6.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      }
+    }
+  }
+}