@mxraven/mail 0.1.0

package/dist/feedback/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["Buffer"],"sources":["../../src/feedback/errors.ts","../../src/feedback/client.ts"],"sourcesContent":["/**\n * A non-success response from the feedback service.\n *\n * @public\n */\nexport class FeedbackError extends Error {\n  /** The HTTP response status. */\n  readonly statusCode: number;\n\n  /**\n   * The service's error message when one was returned, otherwise the HTTP\n   * status text.\n   */\n  readonly detail: string;\n\n  /**\n   * @param options - The response status and service error message.\n   */\n  constructor(options: { statusCode: number; detail: string }) {\n    super(\n      options.detail === \"\"\n        ? `feedback: request failed with status ${options.statusCode}`\n        : `feedback: request failed with status ${options.statusCode}: ${options.detail}`,\n    );\n    this.name = \"FeedbackError\";\n    this.statusCode = options.statusCode;\n    this.detail = options.detail;\n  }\n\n  /**\n   * Reports whether the request may succeed if retried later.\n   *\n   * Rate limits (429) and server-side failures (5xx) are retryable.\n   */\n  get retryable(): boolean {\n    return this.statusCode === 429 || this.statusCode >= 500;\n  }\n}\n","/**\n * The mxRaven feedback and one-click unsubscribe client.\n */\n\nimport { Buffer } from \"node:buffer\";\n\nimport { FeedbackError } from \"./errors.js\";\n\n/** A minimal `fetch`-compatible function. @public */\nexport type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** The training label for a message. */\nexport const disposition = {\n  /** Marks the message as spam. */\n  spam: \"spam\",\n  /** Marks the message as not spam. */\n  ham: \"ham\",\n} as const;\n\n/** The training label for a message. */\nexport type Disposition = (typeof disposition)[keyof typeof disposition];\n\n/** The outcome of a successful learning request. */\nexport interface LearningResult {\n  /** The service status, normally `learned`. */\n  readonly status: string;\n  /** The training label that was applied. */\n  readonly disposition: Disposition;\n  /** The tenant that owns the matched message. */\n  readonly tenantId: string;\n  /** The listener that processed the matched message. */\n  readonly listenerId: string;\n  /** Which stored hash matched the submitted bytes. */\n  readonly matchedHashKind: string;\n}\n\n/** Options for a {@link Client}. */\nexport interface ClientOptions {\n  /** The feedback service base URL, for example `https://feedback.mxraven.com`. */\n  readonly baseUrl: string;\n  /** The submission API key username. Required for learning. */\n  readonly username?: string;\n  /** The submission API key secret. Required for learning. */\n  readonly secret?: string;\n  /** The `fetch` implementation to use. Defaults to the global `fetch`. */\n  readonly fetch?: FetchLike;\n  /** The request timeout in milliseconds. Defaults to 30000. */\n  readonly timeout?: number;\n}\n\n/** Per-call options for feedback requests. */\nexport interface RequestOptions {\n  /** Cancels the request. */\n  readonly signal?: AbortSignal;\n}\n\ninterface Credentials {\n  readonly username: string;\n  readonly secret: string;\n}\n\nconst DEFAULT_TIMEOUT = 30_000;\nconst MAX_ERROR_BODY = 4096;\nconst MAX_RESULT_BODY = 64 * 1024;\n\n/**\n * Calls the mxRaven feedback service.\n *\n * Learning requests authenticate with the same submission API key used for SMTP\n * submission, over HTTP Basic auth. A client is safe for concurrent use.\n *\n * @example\n * ```ts\n * const secret = process.env.MXRAVEN_SECRET;\n * if (secret === undefined || secret === \"\") {\n *   throw new Error(\"MXRAVEN_SECRET is required\");\n * }\n *\n * const client = new Client({\n *   baseUrl: \"https://feedback.mxraven.com\",\n *   username: \"mxr_tx_ab12cd34ef56\",\n *   secret,\n * });\n * const result = await client.learnSpam(rawMessageBytes);\n * ```\n *\n * @public\n */\nexport class Client {\n  private readonly baseUrl: string;\n  private readonly credentials: Credentials | undefined;\n  private readonly fetchImpl: FetchLike;\n  private readonly timeout: number;\n\n  /**\n   * @param options - The base URL, credentials, and transport options.\n   * @throws `Error` When the base URL is missing or an option is invalid.\n   */\n  constructor(options: ClientOptions) {\n    const baseUrl = options.baseUrl.trim();\n    if (baseUrl === \"\") {\n      throw new Error(\"feedback: base URL is required\");\n    }\n\n    const username = (options.username ?? \"\").trim();\n    const secret = options.secret ?? \"\";\n    if ((username === \"\") !== (secret === \"\")) {\n      throw new Error(\"feedback: username and secret must both be provided\");\n    }\n\n    const timeout = options.timeout ?? DEFAULT_TIMEOUT;\n    if (!Number.isFinite(timeout) || timeout <= 0) {\n      throw new Error(`feedback: invalid timeout ${timeout}`);\n    }\n\n    this.baseUrl = baseUrl.replace(/\\/+$/, \"\");\n    this.credentials = username === \"\" ? undefined : { username, secret };\n    this.fetchImpl = options.fetch ?? globalThis.fetch;\n    this.timeout = timeout;\n  }\n\n  /**\n   * Submits one training example.\n   *\n   * `rawMime` must be the exact raw RFC 822 bytes that mxRaven processed; the\n   * service matches them against stored evidence by SHA-256. A message with no\n   * matching evidence fails with a {@link FeedbackError} whose `statusCode` is\n   * 404.\n   *\n   * @param label - The training label to apply.\n   * @param rawMime - The exact raw message bytes.\n   * @param options - An optional cancellation signal.\n   * @returns The service's learning result.\n   * @throws {@link FeedbackError} When the service returns a non-success status.\n   *\n   * @public\n   */\n  async learn(\n    label: Disposition,\n    rawMime: Uint8Array,\n    options: RequestOptions = {},\n  ): Promise<LearningResult> {\n    if (label !== disposition.spam && label !== disposition.ham) {\n      throw new Error(`feedback: invalid disposition ${JSON.stringify(label)}`);\n    }\n    const credentials = this.credentials;\n    if (credentials === undefined) {\n      throw new Error(\"feedback: credentials are required for learning\");\n    }\n\n    const endpoint = `${this.baseUrl}/v1/feedback/learn/${label}`;\n    const response = await this.perform(\n      endpoint,\n      {\n        \"Content-Type\": \"message/rfc822\",\n        Authorization: `Basic ${encodeBasicAuth(credentials)}`,\n      },\n      rawMime,\n      \"submit learning request\",\n      options,\n    );\n    if (!response.ok) {\n      throw await this.toError(response);\n    }\n\n    const body = await readBounded(response, MAX_RESULT_BODY, \"learning response\");\n    return parseLearningResult(body);\n  }\n\n  /** Teaches the spam filter that `rawMime` is spam. */\n  learnSpam(rawMime: Uint8Array, options: RequestOptions = {}): Promise<LearningResult> {\n    return this.learn(disposition.spam, rawMime, options);\n  }\n\n  /** Teaches the spam filter that `rawMime` is not spam. */\n  learnHam(rawMime: Uint8Array, options: RequestOptions = {}): Promise<LearningResult> {\n    return this.learn(disposition.ham, rawMime, options);\n  }\n\n  /**\n   * Performs an RFC 8058 one-click unsubscribe for a token.\n   *\n   * This is the operation a recipient mail client performs against the\n   * `List-Unsubscribe` URL; applications rarely call it directly. It is\n   * unauthenticated.\n   *\n   * @param token - The signed unsubscribe token.\n   * @param options - An optional cancellation signal.\n   * @throws {@link FeedbackError} When the service returns a non-success status.\n   *\n   * @public\n   */\n  async unsubscribe(token: string, options: RequestOptions = {}): Promise<void> {\n    const value = token.trim();\n    if (value === \"\") {\n      throw new Error(\"feedback: unsubscribe token is empty\");\n    }\n\n    const endpoint = `${this.baseUrl}/v1/feedback/unsubscribe/${encodeURIComponent(value)}`;\n    const response = await this.perform(\n      endpoint,\n      { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n      \"List-Unsubscribe=One-Click\",\n      \"submit unsubscribe request\",\n      options,\n    );\n    if (!response.ok) {\n      throw await this.toError(response);\n    }\n  }\n\n  private async perform(\n    endpoint: string,\n    headers: Record<string, string>,\n    body: Uint8Array | string,\n    label: string,\n    options: RequestOptions,\n  ): Promise<Response> {\n    const controller = new AbortController();\n    const timer = setTimeout(\n      () => controller.abort(new Error(\"feedback: request timed out\")),\n      this.timeout,\n    );\n    timer.unref();\n\n    const signal = options.signal;\n    const onAbort = (): void => controller.abort(signal?.reason);\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n    try {\n      return await this.fetchImpl(endpoint, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (error) {\n      throw new Error(`feedback: ${label}`, { cause: error });\n    } finally {\n      clearTimeout(timer);\n      signal?.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  private async toError(response: Response): Promise<FeedbackError> {\n    let detail = `${response.status} ${response.statusText}`.trim();\n    try {\n      const body = await readBounded(response, MAX_ERROR_BODY, \"error response\");\n      const parsed = JSON.parse(new TextDecoder().decode(body)) as { error?: unknown };\n      if (typeof parsed.error === \"string\" && parsed.error.trim() !== \"\") {\n        detail = parsed.error.trim();\n      }\n    } catch {\n      // Keep the status text when the error body is unusable.\n    }\n    return new FeedbackError({ statusCode: response.status, detail });\n  }\n}\n\n/** Encodes HTTP Basic credentials. */\nfunction encodeBasicAuth(credentials: Credentials): string {\n  return Buffer.from(`${credentials.username}:${credentials.secret}`, \"utf8\").toString(\"base64\");\n}\n\n/** Parses a learning response into its public shape. */\nfunction parseLearningResult(body: Uint8Array): LearningResult {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(new TextDecoder().decode(body));\n  } catch (error) {\n    throw new Error(\"feedback: decode learning response\", { cause: error });\n  }\n  if (parsed === null || typeof parsed !== \"object\") {\n    throw new Error(\"feedback: decode learning response\");\n  }\n\n  const wire = parsed as Record<string, unknown>;\n  return {\n    status: typeof wire.status === \"string\" ? wire.status : \"\",\n    disposition: wire.disposition === disposition.ham ? disposition.ham : disposition.spam,\n    tenantId: typeof wire.tenant_id === \"string\" ? wire.tenant_id : \"\",\n    listenerId: typeof wire.listener_id === \"string\" ? wire.listener_id : \"\",\n    matchedHashKind: typeof wire.matched_hash_kind === \"string\" ? wire.matched_hash_kind : \"\",\n  };\n}\n\n/** Reads a response body, rejecting when it exceeds a byte limit. */\nasync function readBounded(response: Response, limit: number, label: string): Promise<Uint8Array> {\n  const stream = response.body;\n  if (stream === null) {\n    return new Uint8Array();\n  }\n\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n      if (done) {\n        break;\n      }\n      if (value !== undefined) {\n        total += value.byteLength;\n        if (total > limit) {\n          void reader.cancel().catch(() => undefined);\n          throw new Error(`feedback: ${label} exceeds ${limit} bytes`);\n        }\n        chunks.push(value);\n      }\n    }\n  } finally {\n    reader.releaseLock();\n  }\n\n  const result = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    result.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return result;\n}\n"],"mappings":"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"}

package/dist/feedback/index.d.cts

@@ -0,0 +1,149 @@
+//#region src/feedback/client.d.ts
+/**
+ * The mxRaven feedback and one-click unsubscribe client.
+ */
+/** A minimal `fetch`-compatible function. @public */
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** The training label for a message. */
+export declare const disposition: {
+  /** Marks the message as spam. */
+  readonly spam: "spam";
+  /** Marks the message as not spam. */
+  readonly ham: "ham";
+};
+/** The training label for a message. */
+type Disposition = (typeof disposition)[keyof typeof disposition];
+/** The outcome of a successful learning request. */
+interface LearningResult {
+  /** The service status, normally `learned`. */
+  readonly status: string;
+  /** The training label that was applied. */
+  readonly disposition: Disposition;
+  /** The tenant that owns the matched message. */
+  readonly tenantId: string;
+  /** The listener that processed the matched message. */
+  readonly listenerId: string;
+  /** Which stored hash matched the submitted bytes. */
+  readonly matchedHashKind: string;
+}
+/** Options for a {@link Client}. */
+interface ClientOptions {
+  /** The feedback service base URL, for example `https://feedback.mxraven.com`. */
+  readonly baseUrl: string;
+  /** The submission API key username. Required for learning. */
+  readonly username?: string;
+  /** The submission API key secret. Required for learning. */
+  readonly secret?: string;
+  /** The `fetch` implementation to use. Defaults to the global `fetch`. */
+  readonly fetch?: FetchLike;
+  /** The request timeout in milliseconds. Defaults to 30000. */
+  readonly timeout?: number;
+}
+/** Per-call options for feedback requests. */
+interface RequestOptions {
+  /** Cancels the request. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Calls the mxRaven feedback service.
+ *
+ * Learning requests authenticate with the same submission API key used for SMTP
+ * submission, over HTTP Basic auth. A client is safe for concurrent use.
+ *
+ * @example
+ * ```ts
+ * const secret = process.env.MXRAVEN_SECRET;
+ * if (secret === undefined || secret === "") {
+ *   throw new Error("MXRAVEN_SECRET is required");
+ * }
+ *
+ * const client = new Client({
+ *   baseUrl: "https://feedback.mxraven.com",
+ *   username: "mxr_tx_ab12cd34ef56",
+ *   secret,
+ * });
+ * const result = await client.learnSpam(rawMessageBytes);
+ * ```
+ *
+ * @public
+ */
+export declare class Client {
+  private readonly baseUrl;
+  private readonly credentials;
+  private readonly fetchImpl;
+  private readonly timeout;
+  /**
+   * @param options - The base URL, credentials, and transport options.
+   * @throws `Error` When the base URL is missing or an option is invalid.
+   */
+  constructor(options: ClientOptions);
+  /**
+   * Submits one training example.
+   *
+   * `rawMime` must be the exact raw RFC 822 bytes that mxRaven processed; the
+   * service matches them against stored evidence by SHA-256. A message with no
+   * matching evidence fails with a {@link FeedbackError} whose `statusCode` is
+   * 404.
+   *
+   * @param label - The training label to apply.
+   * @param rawMime - The exact raw message bytes.
+   * @param options - An optional cancellation signal.
+   * @returns The service's learning result.
+   * @throws {@link FeedbackError} When the service returns a non-success status.
+   *
+   * @public
+   */
+  learn(label: Disposition, rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /** Teaches the spam filter that `rawMime` is spam. */
+  learnSpam(rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /** Teaches the spam filter that `rawMime` is not spam. */
+  learnHam(rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /**
+   * Performs an RFC 8058 one-click unsubscribe for a token.
+   *
+   * This is the operation a recipient mail client performs against the
+   * `List-Unsubscribe` URL; applications rarely call it directly. It is
+   * unauthenticated.
+   *
+   * @param token - The signed unsubscribe token.
+   * @param options - An optional cancellation signal.
+   * @throws {@link FeedbackError} When the service returns a non-success status.
+   *
+   * @public
+   */
+  unsubscribe(token: string, options?: RequestOptions): Promise<void>;
+  private perform;
+  private toError;
+}
+//#endregion
+//#region src/feedback/errors.d.ts
+/**
+ * A non-success response from the feedback service.
+ *
+ * @public
+ */
+export declare class FeedbackError extends Error {
+  /** The HTTP response status. */
+  readonly statusCode: number;
+  /**
+   * The service's error message when one was returned, otherwise the HTTP
+   * status text.
+   */
+  readonly detail: string;
+  /**
+   * @param options - The response status and service error message.
+   */
+  constructor(options: {
+    statusCode: number;
+    detail: string;
+  });
+  /**
+   * Reports whether the request may succeed if retried later.
+   *
+   * Rate limits (429) and server-side failures (5xx) are retryable.
+   */
+  get retryable(): boolean;
+}
+//#endregion
+export type { ClientOptions, Disposition, FetchLike, LearningResult, RequestOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/feedback/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/feedback/client.ts","../../src/feedback/errors.ts"],"mappings":";;;;;KASY,aAAa,aAAa,OAAO,gBAAgB,QAAQ;;qBAGxD;;WAAA;;WAAA;;;KAQD,sBAAsB,0BAA0B;;UAG3C;;WAEN;;WAEA,aAAa;;WAEb;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER;;;UAIM;;WAEN,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;qBAmCP;mBACM;mBACA;mBACA;mBACA;;;;;EAML,YAAA,SAAS;;;;;;;;;;;;;;;;;EAuCf,MACJ,OAAO,aACP,SAAS,YACT,UAAS,iBACR,QAAQ;;EA6BX,UAAU,SAAS,YAAY,UAAS,iBAAsB,QAAQ;;EAKtE,SAAS,SAAS,YAAY,UAAS,iBAAsB,QAAQ;;;;;;;;;;;;;;EAiB/D,YAAY,eAAe,UAAS,iBAAsB;UAmBlD;UAiCA;;;;;;;;;qBC/OH,sBAAsB;;WAExB;;;;;WAMA;;;;EAKG,YAAA;IAAW;IAAoB;;;;;;;MAgBvC"}

package/dist/feedback/index.d.ts

@@ -0,0 +1,149 @@
+//#region src/feedback/client.d.ts
+/**
+ * The mxRaven feedback and one-click unsubscribe client.
+ */
+/** A minimal `fetch`-compatible function. @public */
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** The training label for a message. */
+export declare const disposition: {
+  /** Marks the message as spam. */
+  readonly spam: "spam";
+  /** Marks the message as not spam. */
+  readonly ham: "ham";
+};
+/** The training label for a message. */
+type Disposition = (typeof disposition)[keyof typeof disposition];
+/** The outcome of a successful learning request. */
+interface LearningResult {
+  /** The service status, normally `learned`. */
+  readonly status: string;
+  /** The training label that was applied. */
+  readonly disposition: Disposition;
+  /** The tenant that owns the matched message. */
+  readonly tenantId: string;
+  /** The listener that processed the matched message. */
+  readonly listenerId: string;
+  /** Which stored hash matched the submitted bytes. */
+  readonly matchedHashKind: string;
+}
+/** Options for a {@link Client}. */
+interface ClientOptions {
+  /** The feedback service base URL, for example `https://feedback.mxraven.com`. */
+  readonly baseUrl: string;
+  /** The submission API key username. Required for learning. */
+  readonly username?: string;
+  /** The submission API key secret. Required for learning. */
+  readonly secret?: string;
+  /** The `fetch` implementation to use. Defaults to the global `fetch`. */
+  readonly fetch?: FetchLike;
+  /** The request timeout in milliseconds. Defaults to 30000. */
+  readonly timeout?: number;
+}
+/** Per-call options for feedback requests. */
+interface RequestOptions {
+  /** Cancels the request. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Calls the mxRaven feedback service.
+ *
+ * Learning requests authenticate with the same submission API key used for SMTP
+ * submission, over HTTP Basic auth. A client is safe for concurrent use.
+ *
+ * @example
+ * ```ts
+ * const secret = process.env.MXRAVEN_SECRET;
+ * if (secret === undefined || secret === "") {
+ *   throw new Error("MXRAVEN_SECRET is required");
+ * }
+ *
+ * const client = new Client({
+ *   baseUrl: "https://feedback.mxraven.com",
+ *   username: "mxr_tx_ab12cd34ef56",
+ *   secret,
+ * });
+ * const result = await client.learnSpam(rawMessageBytes);
+ * ```
+ *
+ * @public
+ */
+export declare class Client {
+  private readonly baseUrl;
+  private readonly credentials;
+  private readonly fetchImpl;
+  private readonly timeout;
+  /**
+   * @param options - The base URL, credentials, and transport options.
+   * @throws `Error` When the base URL is missing or an option is invalid.
+   */
+  constructor(options: ClientOptions);
+  /**
+   * Submits one training example.
+   *
+   * `rawMime` must be the exact raw RFC 822 bytes that mxRaven processed; the
+   * service matches them against stored evidence by SHA-256. A message with no
+   * matching evidence fails with a {@link FeedbackError} whose `statusCode` is
+   * 404.
+   *
+   * @param label - The training label to apply.
+   * @param rawMime - The exact raw message bytes.
+   * @param options - An optional cancellation signal.
+   * @returns The service's learning result.
+   * @throws {@link FeedbackError} When the service returns a non-success status.
+   *
+   * @public
+   */
+  learn(label: Disposition, rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /** Teaches the spam filter that `rawMime` is spam. */
+  learnSpam(rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /** Teaches the spam filter that `rawMime` is not spam. */
+  learnHam(rawMime: Uint8Array, options?: RequestOptions): Promise<LearningResult>;
+  /**
+   * Performs an RFC 8058 one-click unsubscribe for a token.
+   *
+   * This is the operation a recipient mail client performs against the
+   * `List-Unsubscribe` URL; applications rarely call it directly. It is
+   * unauthenticated.
+   *
+   * @param token - The signed unsubscribe token.
+   * @param options - An optional cancellation signal.
+   * @throws {@link FeedbackError} When the service returns a non-success status.
+   *
+   * @public
+   */
+  unsubscribe(token: string, options?: RequestOptions): Promise<void>;
+  private perform;
+  private toError;
+}
+//#endregion
+//#region src/feedback/errors.d.ts
+/**
+ * A non-success response from the feedback service.
+ *
+ * @public
+ */
+export declare class FeedbackError extends Error {
+  /** The HTTP response status. */
+  readonly statusCode: number;
+  /**
+   * The service's error message when one was returned, otherwise the HTTP
+   * status text.
+   */
+  readonly detail: string;
+  /**
+   * @param options - The response status and service error message.
+   */
+  constructor(options: {
+    statusCode: number;
+    detail: string;
+  });
+  /**
+   * Reports whether the request may succeed if retried later.
+   *
+   * Rate limits (429) and server-side failures (5xx) are retryable.
+   */
+  get retryable(): boolean;
+}
+//#endregion
+export type { ClientOptions, Disposition, FetchLike, LearningResult, RequestOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/feedback/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/feedback/client.ts","../../src/feedback/errors.ts"],"mappings":";;;;;KASY,aAAa,aAAa,OAAO,gBAAgB,QAAQ;;qBAGxD;;WAAA;;WAAA;;;KAQD,sBAAsB,0BAA0B;;UAG3C;;WAEN;;WAEA,aAAa;;WAEb;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER;;;UAIM;;WAEN,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;qBAmCP;mBACM;mBACA;mBACA;mBACA;;;;;EAML,YAAA,SAAS;;;;;;;;;;;;;;;;;EAuCf,MACJ,OAAO,aACP,SAAS,YACT,UAAS,iBACR,QAAQ;;EA6BX,UAAU,SAAS,YAAY,UAAS,iBAAsB,QAAQ;;EAKtE,SAAS,SAAS,YAAY,UAAS,iBAAsB,QAAQ;;;;;;;;;;;;;;EAiB/D,YAAY,eAAe,UAAS,iBAAsB;UAmBlD;UAiCA;;;;;;;;;qBC/OH,sBAAsB;;WAExB;;;;;WAMA;;;;EAKG,YAAA;IAAW;IAAoB;;;;;;;MAgBvC"}

package/dist/feedback/index.js

@@ -0,0 +1,243 @@
+import { Buffer } from "node:buffer";
+//#region src/feedback/errors.ts
+/**
+* A non-success response from the feedback service.
+*
+* @public
+*/
+var FeedbackError = class extends Error {
+	/** The HTTP response status. */
+	statusCode;
+	/**
+	* The service's error message when one was returned, otherwise the HTTP
+	* status text.
+	*/
+	detail;
+	/**
+	* @param options - The response status and service error message.
+	*/
+	constructor(options) {
+		super(options.detail === "" ? `feedback: request failed with status ${options.statusCode}` : `feedback: request failed with status ${options.statusCode}: ${options.detail}`);
+		this.name = "FeedbackError";
+		this.statusCode = options.statusCode;
+		this.detail = options.detail;
+	}
+	/**
+	* Reports whether the request may succeed if retried later.
+	*
+	* Rate limits (429) and server-side failures (5xx) are retryable.
+	*/
+	get retryable() {
+		return this.statusCode === 429 || this.statusCode >= 500;
+	}
+};
+//#endregion
+//#region src/feedback/client.ts
+/**
+* The mxRaven feedback and one-click unsubscribe client.
+*/
+/** The training label for a message. */
+const disposition = {
+	/** Marks the message as spam. */
+	spam: "spam",
+	/** Marks the message as not spam. */
+	ham: "ham"
+};
+const DEFAULT_TIMEOUT = 3e4;
+const MAX_ERROR_BODY = 4096;
+const MAX_RESULT_BODY = 65536;
+/**
+* Calls the mxRaven feedback service.
+*
+* Learning requests authenticate with the same submission API key used for SMTP
+* submission, over HTTP Basic auth. A client is safe for concurrent use.
+*
+* @example
+* ```ts
+* const secret = process.env.MXRAVEN_SECRET;
+* if (secret === undefined || secret === "") {
+*   throw new Error("MXRAVEN_SECRET is required");
+* }
+*
+* const client = new Client({
+*   baseUrl: "https://feedback.mxraven.com",
+*   username: "mxr_tx_ab12cd34ef56",
+*   secret,
+* });
+* const result = await client.learnSpam(rawMessageBytes);
+* ```
+*
+* @public
+*/
+var Client = class {
+	baseUrl;
+	credentials;
+	fetchImpl;
+	timeout;
+	/**
+	* @param options - The base URL, credentials, and transport options.
+	* @throws `Error` When the base URL is missing or an option is invalid.
+	*/
+	constructor(options) {
+		const baseUrl = options.baseUrl.trim();
+		if (baseUrl === "") throw new Error("feedback: base URL is required");
+		const username = (options.username ?? "").trim();
+		const secret = options.secret ?? "";
+		if (username === "" !== (secret === "")) throw new Error("feedback: username and secret must both be provided");
+		const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+		if (!Number.isFinite(timeout) || timeout <= 0) throw new Error(`feedback: invalid timeout ${timeout}`);
+		this.baseUrl = baseUrl.replace(/\/+$/, "");
+		this.credentials = username === "" ? void 0 : {
+			username,
+			secret
+		};
+		this.fetchImpl = options.fetch ?? globalThis.fetch;
+		this.timeout = timeout;
+	}
+	/**
+	* Submits one training example.
+	*
+	* `rawMime` must be the exact raw RFC 822 bytes that mxRaven processed; the
+	* service matches them against stored evidence by SHA-256. A message with no
+	* matching evidence fails with a {@link FeedbackError} whose `statusCode` is
+	* 404.
+	*
+	* @param label - The training label to apply.
+	* @param rawMime - The exact raw message bytes.
+	* @param options - An optional cancellation signal.
+	* @returns The service's learning result.
+	* @throws {@link FeedbackError} When the service returns a non-success status.
+	*
+	* @public
+	*/
+	async learn(label, rawMime, options = {}) {
+		if (label !== disposition.spam && label !== disposition.ham) throw new Error(`feedback: invalid disposition ${JSON.stringify(label)}`);
+		const credentials = this.credentials;
+		if (credentials === void 0) throw new Error("feedback: credentials are required for learning");
+		const endpoint = `${this.baseUrl}/v1/feedback/learn/${label}`;
+		const response = await this.perform(endpoint, {
+			"Content-Type": "message/rfc822",
+			Authorization: `Basic ${encodeBasicAuth(credentials)}`
+		}, rawMime, "submit learning request", options);
+		if (!response.ok) throw await this.toError(response);
+		return parseLearningResult(await readBounded(response, MAX_RESULT_BODY, "learning response"));
+	}
+	/** Teaches the spam filter that `rawMime` is spam. */
+	learnSpam(rawMime, options = {}) {
+		return this.learn(disposition.spam, rawMime, options);
+	}
+	/** Teaches the spam filter that `rawMime` is not spam. */
+	learnHam(rawMime, options = {}) {
+		return this.learn(disposition.ham, rawMime, options);
+	}
+	/**
+	* Performs an RFC 8058 one-click unsubscribe for a token.
+	*
+	* This is the operation a recipient mail client performs against the
+	* `List-Unsubscribe` URL; applications rarely call it directly. It is
+	* unauthenticated.
+	*
+	* @param token - The signed unsubscribe token.
+	* @param options - An optional cancellation signal.
+	* @throws {@link FeedbackError} When the service returns a non-success status.
+	*
+	* @public
+	*/
+	async unsubscribe(token, options = {}) {
+		const value = token.trim();
+		if (value === "") throw new Error("feedback: unsubscribe token is empty");
+		const endpoint = `${this.baseUrl}/v1/feedback/unsubscribe/${encodeURIComponent(value)}`;
+		const response = await this.perform(endpoint, { "Content-Type": "application/x-www-form-urlencoded" }, "List-Unsubscribe=One-Click", "submit unsubscribe request", options);
+		if (!response.ok) throw await this.toError(response);
+	}
+	async perform(endpoint, headers, body, label, options) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("feedback: request timed out")), this.timeout);
+		timer.unref();
+		const signal = options.signal;
+		const onAbort = () => controller.abort(signal?.reason);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await this.fetchImpl(endpoint, {
+				method: "POST",
+				headers,
+				body,
+				signal: controller.signal
+			});
+		} catch (error) {
+			throw new Error(`feedback: ${label}`, { cause: error });
+		} finally {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		}
+	}
+	async toError(response) {
+		let detail = `${response.status} ${response.statusText}`.trim();
+		try {
+			const body = await readBounded(response, MAX_ERROR_BODY, "error response");
+			const parsed = JSON.parse(new TextDecoder().decode(body));
+			if (typeof parsed.error === "string" && parsed.error.trim() !== "") detail = parsed.error.trim();
+		} catch {}
+		return new FeedbackError({
+			statusCode: response.status,
+			detail
+		});
+	}
+};
+/** Encodes HTTP Basic credentials. */
+function encodeBasicAuth(credentials) {
+	return Buffer.from(`${credentials.username}:${credentials.secret}`, "utf8").toString("base64");
+}
+/** Parses a learning response into its public shape. */
+function parseLearningResult(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(body));
+	} catch (error) {
+		throw new Error("feedback: decode learning response", { cause: error });
+	}
+	if (parsed === null || typeof parsed !== "object") throw new Error("feedback: decode learning response");
+	const wire = parsed;
+	return {
+		status: typeof wire.status === "string" ? wire.status : "",
+		disposition: wire.disposition === disposition.ham ? disposition.ham : disposition.spam,
+		tenantId: typeof wire.tenant_id === "string" ? wire.tenant_id : "",
+		listenerId: typeof wire.listener_id === "string" ? wire.listener_id : "",
+		matchedHashKind: typeof wire.matched_hash_kind === "string" ? wire.matched_hash_kind : ""
+	};
+}
+/** Reads a response body, rejecting when it exceeds a byte limit. */
+async function readBounded(response, limit, label) {
+	const stream = response.body;
+	if (stream === null) return /* @__PURE__ */ new Uint8Array();
+	const reader = stream.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value !== void 0) {
+				total += value.byteLength;
+				if (total > limit) {
+					reader.cancel().catch(() => void 0);
+					throw new Error(`feedback: ${label} exceeds ${limit} bytes`);
+				}
+				chunks.push(value);
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const result = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return result;
+}
+//#endregion
+export { Client, FeedbackError, disposition };
+
+//# sourceMappingURL=index.js.map

package/dist/feedback/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/feedback/errors.ts","../../src/feedback/client.ts"],"sourcesContent":["/**\n * A non-success response from the feedback service.\n *\n * @public\n */\nexport class FeedbackError extends Error {\n  /** The HTTP response status. */\n  readonly statusCode: number;\n\n  /**\n   * The service's error message when one was returned, otherwise the HTTP\n   * status text.\n   */\n  readonly detail: string;\n\n  /**\n   * @param options - The response status and service error message.\n   */\n  constructor(options: { statusCode: number; detail: string }) {\n    super(\n      options.detail === \"\"\n        ? `feedback: request failed with status ${options.statusCode}`\n        : `feedback: request failed with status ${options.statusCode}: ${options.detail}`,\n    );\n    this.name = \"FeedbackError\";\n    this.statusCode = options.statusCode;\n    this.detail = options.detail;\n  }\n\n  /**\n   * Reports whether the request may succeed if retried later.\n   *\n   * Rate limits (429) and server-side failures (5xx) are retryable.\n   */\n  get retryable(): boolean {\n    return this.statusCode === 429 || this.statusCode >= 500;\n  }\n}\n","/**\n * The mxRaven feedback and one-click unsubscribe client.\n */\n\nimport { Buffer } from \"node:buffer\";\n\nimport { FeedbackError } from \"./errors.js\";\n\n/** A minimal `fetch`-compatible function. @public */\nexport type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** The training label for a message. */\nexport const disposition = {\n  /** Marks the message as spam. */\n  spam: \"spam\",\n  /** Marks the message as not spam. */\n  ham: \"ham\",\n} as const;\n\n/** The training label for a message. */\nexport type Disposition = (typeof disposition)[keyof typeof disposition];\n\n/** The outcome of a successful learning request. */\nexport interface LearningResult {\n  /** The service status, normally `learned`. */\n  readonly status: string;\n  /** The training label that was applied. */\n  readonly disposition: Disposition;\n  /** The tenant that owns the matched message. */\n  readonly tenantId: string;\n  /** The listener that processed the matched message. */\n  readonly listenerId: string;\n  /** Which stored hash matched the submitted bytes. */\n  readonly matchedHashKind: string;\n}\n\n/** Options for a {@link Client}. */\nexport interface ClientOptions {\n  /** The feedback service base URL, for example `https://feedback.mxraven.com`. */\n  readonly baseUrl: string;\n  /** The submission API key username. Required for learning. */\n  readonly username?: string;\n  /** The submission API key secret. Required for learning. */\n  readonly secret?: string;\n  /** The `fetch` implementation to use. Defaults to the global `fetch`. */\n  readonly fetch?: FetchLike;\n  /** The request timeout in milliseconds. Defaults to 30000. */\n  readonly timeout?: number;\n}\n\n/** Per-call options for feedback requests. */\nexport interface RequestOptions {\n  /** Cancels the request. */\n  readonly signal?: AbortSignal;\n}\n\ninterface Credentials {\n  readonly username: string;\n  readonly secret: string;\n}\n\nconst DEFAULT_TIMEOUT = 30_000;\nconst MAX_ERROR_BODY = 4096;\nconst MAX_RESULT_BODY = 64 * 1024;\n\n/**\n * Calls the mxRaven feedback service.\n *\n * Learning requests authenticate with the same submission API key used for SMTP\n * submission, over HTTP Basic auth. A client is safe for concurrent use.\n *\n * @example\n * ```ts\n * const secret = process.env.MXRAVEN_SECRET;\n * if (secret === undefined || secret === \"\") {\n *   throw new Error(\"MXRAVEN_SECRET is required\");\n * }\n *\n * const client = new Client({\n *   baseUrl: \"https://feedback.mxraven.com\",\n *   username: \"mxr_tx_ab12cd34ef56\",\n *   secret,\n * });\n * const result = await client.learnSpam(rawMessageBytes);\n * ```\n *\n * @public\n */\nexport class Client {\n  private readonly baseUrl: string;\n  private readonly credentials: Credentials | undefined;\n  private readonly fetchImpl: FetchLike;\n  private readonly timeout: number;\n\n  /**\n   * @param options - The base URL, credentials, and transport options.\n   * @throws `Error` When the base URL is missing or an option is invalid.\n   */\n  constructor(options: ClientOptions) {\n    const baseUrl = options.baseUrl.trim();\n    if (baseUrl === \"\") {\n      throw new Error(\"feedback: base URL is required\");\n    }\n\n    const username = (options.username ?? \"\").trim();\n    const secret = options.secret ?? \"\";\n    if ((username === \"\") !== (secret === \"\")) {\n      throw new Error(\"feedback: username and secret must both be provided\");\n    }\n\n    const timeout = options.timeout ?? DEFAULT_TIMEOUT;\n    if (!Number.isFinite(timeout) || timeout <= 0) {\n      throw new Error(`feedback: invalid timeout ${timeout}`);\n    }\n\n    this.baseUrl = baseUrl.replace(/\\/+$/, \"\");\n    this.credentials = username === \"\" ? undefined : { username, secret };\n    this.fetchImpl = options.fetch ?? globalThis.fetch;\n    this.timeout = timeout;\n  }\n\n  /**\n   * Submits one training example.\n   *\n   * `rawMime` must be the exact raw RFC 822 bytes that mxRaven processed; the\n   * service matches them against stored evidence by SHA-256. A message with no\n   * matching evidence fails with a {@link FeedbackError} whose `statusCode` is\n   * 404.\n   *\n   * @param label - The training label to apply.\n   * @param rawMime - The exact raw message bytes.\n   * @param options - An optional cancellation signal.\n   * @returns The service's learning result.\n   * @throws {@link FeedbackError} When the service returns a non-success status.\n   *\n   * @public\n   */\n  async learn(\n    label: Disposition,\n    rawMime: Uint8Array,\n    options: RequestOptions = {},\n  ): Promise<LearningResult> {\n    if (label !== disposition.spam && label !== disposition.ham) {\n      throw new Error(`feedback: invalid disposition ${JSON.stringify(label)}`);\n    }\n    const credentials = this.credentials;\n    if (credentials === undefined) {\n      throw new Error(\"feedback: credentials are required for learning\");\n    }\n\n    const endpoint = `${this.baseUrl}/v1/feedback/learn/${label}`;\n    const response = await this.perform(\n      endpoint,\n      {\n        \"Content-Type\": \"message/rfc822\",\n        Authorization: `Basic ${encodeBasicAuth(credentials)}`,\n      },\n      rawMime,\n      \"submit learning request\",\n      options,\n    );\n    if (!response.ok) {\n      throw await this.toError(response);\n    }\n\n    const body = await readBounded(response, MAX_RESULT_BODY, \"learning response\");\n    return parseLearningResult(body);\n  }\n\n  /** Teaches the spam filter that `rawMime` is spam. */\n  learnSpam(rawMime: Uint8Array, options: RequestOptions = {}): Promise<LearningResult> {\n    return this.learn(disposition.spam, rawMime, options);\n  }\n\n  /** Teaches the spam filter that `rawMime` is not spam. */\n  learnHam(rawMime: Uint8Array, options: RequestOptions = {}): Promise<LearningResult> {\n    return this.learn(disposition.ham, rawMime, options);\n  }\n\n  /**\n   * Performs an RFC 8058 one-click unsubscribe for a token.\n   *\n   * This is the operation a recipient mail client performs against the\n   * `List-Unsubscribe` URL; applications rarely call it directly. It is\n   * unauthenticated.\n   *\n   * @param token - The signed unsubscribe token.\n   * @param options - An optional cancellation signal.\n   * @throws {@link FeedbackError} When the service returns a non-success status.\n   *\n   * @public\n   */\n  async unsubscribe(token: string, options: RequestOptions = {}): Promise<void> {\n    const value = token.trim();\n    if (value === \"\") {\n      throw new Error(\"feedback: unsubscribe token is empty\");\n    }\n\n    const endpoint = `${this.baseUrl}/v1/feedback/unsubscribe/${encodeURIComponent(value)}`;\n    const response = await this.perform(\n      endpoint,\n      { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n      \"List-Unsubscribe=One-Click\",\n      \"submit unsubscribe request\",\n      options,\n    );\n    if (!response.ok) {\n      throw await this.toError(response);\n    }\n  }\n\n  private async perform(\n    endpoint: string,\n    headers: Record<string, string>,\n    body: Uint8Array | string,\n    label: string,\n    options: RequestOptions,\n  ): Promise<Response> {\n    const controller = new AbortController();\n    const timer = setTimeout(\n      () => controller.abort(new Error(\"feedback: request timed out\")),\n      this.timeout,\n    );\n    timer.unref();\n\n    const signal = options.signal;\n    const onAbort = (): void => controller.abort(signal?.reason);\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n    try {\n      return await this.fetchImpl(endpoint, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (error) {\n      throw new Error(`feedback: ${label}`, { cause: error });\n    } finally {\n      clearTimeout(timer);\n      signal?.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  private async toError(response: Response): Promise<FeedbackError> {\n    let detail = `${response.status} ${response.statusText}`.trim();\n    try {\n      const body = await readBounded(response, MAX_ERROR_BODY, \"error response\");\n      const parsed = JSON.parse(new TextDecoder().decode(body)) as { error?: unknown };\n      if (typeof parsed.error === \"string\" && parsed.error.trim() !== \"\") {\n        detail = parsed.error.trim();\n      }\n    } catch {\n      // Keep the status text when the error body is unusable.\n    }\n    return new FeedbackError({ statusCode: response.status, detail });\n  }\n}\n\n/** Encodes HTTP Basic credentials. */\nfunction encodeBasicAuth(credentials: Credentials): string {\n  return Buffer.from(`${credentials.username}:${credentials.secret}`, \"utf8\").toString(\"base64\");\n}\n\n/** Parses a learning response into its public shape. */\nfunction parseLearningResult(body: Uint8Array): LearningResult {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(new TextDecoder().decode(body));\n  } catch (error) {\n    throw new Error(\"feedback: decode learning response\", { cause: error });\n  }\n  if (parsed === null || typeof parsed !== \"object\") {\n    throw new Error(\"feedback: decode learning response\");\n  }\n\n  const wire = parsed as Record<string, unknown>;\n  return {\n    status: typeof wire.status === \"string\" ? wire.status : \"\",\n    disposition: wire.disposition === disposition.ham ? disposition.ham : disposition.spam,\n    tenantId: typeof wire.tenant_id === \"string\" ? wire.tenant_id : \"\",\n    listenerId: typeof wire.listener_id === \"string\" ? wire.listener_id : \"\",\n    matchedHashKind: typeof wire.matched_hash_kind === \"string\" ? wire.matched_hash_kind : \"\",\n  };\n}\n\n/** Reads a response body, rejecting when it exceeds a byte limit. */\nasync function readBounded(response: Response, limit: number, label: string): Promise<Uint8Array> {\n  const stream = response.body;\n  if (stream === null) {\n    return new Uint8Array();\n  }\n\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n      if (done) {\n        break;\n      }\n      if (value !== undefined) {\n        total += value.byteLength;\n        if (total > limit) {\n          void reader.cancel().catch(() => undefined);\n          throw new Error(`feedback: ${label} exceeds ${limit} bytes`);\n        }\n        chunks.push(value);\n      }\n    }\n  } finally {\n    reader.releaseLock();\n  }\n\n  const result = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    result.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return result;\n}\n"],"mappings":"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"}