bul-email 0.1.1 → 0.1.2

package/README.md

@@ -41,6 +41,8 @@ const { id } = await bul.emails.send(
   (`maxRetries`, ברירת מחדל 3). לכל שליחה `Idempotency-Key` אחד, שחוזר בכל ניסיון — ניסיון חוזר אף פעם לא שולח פעמיים.
 - **שגיאות ברורות:** כל שגיאה מה-API היא `BulError` (או תת-מחלקה) עם `code` ו-`status`. ‏409 `route_paused` → ‏`RoutePausedError`
   (`reasonCode`, ‏`returns[]`) — שום דבר לא התקבל; שולחים בדרך אחרת ומדווחים עם `recipients.proof`.
+- **חסימות:** ‏`suppressions.add` / ‏`import` יוצרות רק חסימה ידנית (`reason: "manual"`, או בלי). החזרות, תלונות והסרות — בול מוסיפה
+  לבד, ואי אפשר למחוק אותן (`remove` מחזיר 409 `suppression_not_removable`).
 - **Webhooks:** ‏`verifyWebhookSignature` / ‏`constructWebhookEvent` — ‏HMAC-SHA256, סבילות של 5 דקות, השוואה בזמן קבוע.
   ‏`BulEvent` מוקלד לפי `event`.
 
@@ -89,6 +91,8 @@ const { id } = await bul.emails.send(
   backoff (`maxRetries`, default 3). Each send gets one `Idempotency-Key`, reused on every retry — a retry never sends twice.
 - **Clear errors**: every API error is a `BulError` (or a subclass) with `code` and `status`. 409 `route_paused` → `RoutePausedError` (`reasonCode`,
   `returns[]`) — nothing was accepted; send another way and report it with `recipients.proof`.
+- **Suppressions**: `suppressions.add` / `import` create manual suppressions only (`reason: "manual"`, or omit it). Bounces, complaints and
+  unsubscribes are added by Bul itself and cannot be removed (`remove` → 409 `suppression_not_removable`).
 - **Webhooks**: `verifyWebhookSignature` / `constructWebhookEvent` — HMAC-SHA256, 5-minute tolerance, constant-time comparison.
   `BulEvent` is typed by `event`.
 
@@ -98,6 +102,8 @@ Almost the same code: change the import and the key. Full guide: [Migrating from
 
 ### Changelog
 
+- **0.1.2** — `suppressions.add` / `suppressions.import`: `reason` accepts only `"manual"` (new type `CreatableSuppressionReason`), matching the
+  API — creating any other reason now fails with 422 `reason_not_allowed`. `SuppressionReason` (all four) is unchanged for reading.
 - **0.1.1** — documentation (this changelog) and the version string. No behavior changes. The first release published straight from the build pipeline, with a verified publisher.
 - **0.1.0** — first release.
 

package/dist/index.d.ts

@@ -36,7 +36,7 @@ interface RequestSpec {
     /** POST that is safe to repeat even without an Idempotency-Key (the API deduplicates). */
     idempotent?: boolean;
 }
-export declare const SDK_VERSION = "0.1.1";
+export declare const SDK_VERSION = "0.1.2";
 export declare class Bul {
     private readonly apiKey;
     private readonly baseUrl;
@@ -124,22 +124,24 @@ export declare class Bul {
             limit: number;
             offset: number;
         }>;
+        /** POST /v1/suppressions — always a manual suppression (`reason` may be omitted or "manual"). */
         add: (input: {
             recipient: string;
-            reason?: T.SuppressionReason;
+            reason?: T.CreatableSuppressionReason;
         }) => Promise<T.Suppression | {
             recipient: string;
             already_suppressed: true;
         }>;
+        /** POST /v1/suppressions/import — always manual, like `add`. */
         import: (input: {
             recipients: string[];
-            reason?: T.SuppressionReason;
+            reason?: T.CreatableSuppressionReason;
         }) => Promise<{
             added: number;
             already_suppressed: number;
             invalid: string[];
         }>;
-        /** DELETE /v1/suppressions/{id or email} (full key). */
+        /** DELETE /v1/suppressions/{id or email} (full key). Only manual suppressions can be removed — others → 409 `suppression_not_removable`. */
         remove: (idOrEmail: string) => Promise<void>;
     };
     readonly recipients: {

package/dist/index.js

@@ -3,7 +3,7 @@ export * from "./errors";
 export * from "./types";
 export { constructWebhookEvent, verifyWebhookSignature } from "./webhooks";
 const RETRY_STATUS = new Set([500, 502, 503, 504]);
-export const SDK_VERSION = "0.1.1";
+export const SDK_VERSION = "0.1.2";
 function newKey() {
     return typeof crypto !== "undefined" && "randomUUID" in crypto
         ? crypto.randomUUID()
@@ -158,9 +158,11 @@ export class Bul {
     };
     suppressions = {
         list: (params = {}) => this.request({ method: "GET", path: "/v1/suppressions", query: params }),
+        /** POST /v1/suppressions — always a manual suppression (`reason` may be omitted or "manual"). */
         add: (input) => this.request({ method: "POST", path: "/v1/suppressions", body: input, idempotent: true }),
+        /** POST /v1/suppressions/import — always manual, like `add`. */
         import: (input) => this.request({ method: "POST", path: "/v1/suppressions/import", body: input, idempotent: true }),
-        /** DELETE /v1/suppressions/{id or email} (full key). */
+        /** DELETE /v1/suppressions/{id or email} (full key). Only manual suppressions can be removed — others → 409 `suppression_not_removable`. */
         remove: (idOrEmail) => this.request({ method: "DELETE", path: `/v1/suppressions/${encodeURIComponent(idOrEmail)}` }),
     };
     recipients = {

package/dist/types.d.ts

@@ -158,6 +158,11 @@ export interface WebhookTestResult {
     error: string | null;
 }
 export type SuppressionReason = "hard_bounce" | "complaint" | "manual" | "unsubscribe";
+/**
+ * The only reason a customer can create (0.1.2). Bounces, complaints and unsubscribes are added by Bul itself, from the provider or the
+ * recipient, and cannot be removed; the API rejects any other reason with 422 `reason_not_allowed`.
+ */
+export type CreatableSuppressionReason = "manual";
 export interface Suppression {
     id: string;
     recipient: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bul-email",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Official JavaScript/TypeScript client for the Bul email API (bul.friman.app)",
   "keywords": [
     "email",