@cowliss/sdk 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 What changed in each version of `@cowliss/sdk` after 0.16.0, newest first. Earlier versions are listed on [npm](https://www.npmjs.com/package/@cowliss/sdk?activeTab=versions).
 
+## 0.21.0 (2026-10-02)
+
+### Features
+
+- Plan constants, plan_limit, meta warnings and root-domain helper
+- **Emails:** Test sends with `test: true` and reserved test addresses
+
 ## 0.20.0 (2026-10-02)
 
 ### Features

package/dist/index.d.ts

@@ -106,6 +106,12 @@ export declare class Cow {
      *
      * Addressed to `{ email }` that no profile in the app holds yet, the send
      * creates that profile first, as `identify` would.
+     *
+     * `test: true` asks "would this exact send work?": every check runs and
+     * refuses as it would, and the answer carries `status` (`would_send` or
+     * the skip) and `rendered`, but nothing is sent or created. An address at
+     * `test.cowliss.com` is the other half: a real send whose outcome the
+     * address picks (`delivered@`, `bounced@`, `complained@`, `suppressed@`).
      */
     emails: {
         send: ({ idempotencyKey, ...input }: WithDefaultSource<SendEmailInput> & {

package/dist/index.js

@@ -128,6 +128,12 @@ export class Cow {
      *
      * Addressed to `{ email }` that no profile in the app holds yet, the send
      * creates that profile first, as `identify` would.
+     *
+     * `test: true` asks "would this exact send work?": every check runs and
+     * refuses as it would, and the answer carries `status` (`would_send` or
+     * the skip) and `rendered`, but nothing is sent or created. An address at
+     * `test.cowliss.com` is the other half: a real send whose outcome the
+     * address picks (`delivered@`, `bounced@`, `complained@`, `suppressed@`).
      */
     emails = {
         send: ({ idempotencyKey, ...input }) => this.#watch(async () => this.#post("/v1/emails", { data: { ...input, sourceId: this.#sourceFor(input) } }, idempotencyKey ?? crypto.randomUUID())),

package/dist/types.d.ts

@@ -13,8 +13,13 @@
  * typecheck here rather than at a customer's call site.
  */
 /** The API's error-code enum, as the SDK surfaces it on `CowError.code`. */
-export type ErrorCode = "malformed_request" | "invalid_key" | "forbidden" | "not_found" | "conflict" | "payload_too_large" | "validation_failed" | "trait_validation_failed" | "event_denied" | "trait_denied" | "over_quota" | "rate_limited" | "dependency_unavailable" | "internal" | "journey_fuel_exceeded" | "journey_timeout" | "journey_memory_exceeded" | "journey_error" | "journey_output_invalid" | "journey_nondeterministic" | "push_invalid" | "version_not_ready" | "version_outdated" | "source_inactive" | "artifact_too_large";
+export type ErrorCode = "malformed_request" | "invalid_key" | "forbidden" | "not_found" | "conflict" | "payload_too_large" | "validation_failed" | "trait_validation_failed" | "event_denied" | "trait_denied" | "over_quota" | "rate_limited" | "dependency_unavailable" | "internal" | "journey_fuel_exceeded" | "journey_timeout" | "journey_memory_exceeded" | "journey_error" | "journey_output_invalid" | "journey_nondeterministic" | "push_invalid" | "version_not_ready" | "version_outdated" | "source_inactive" | "artifact_too_large" | "plan_limit";
 export type IdentifierKind = "anonymousId" | "userId" | "clerkId" | "email";
+/**
+ * What became of a send: handed over and how it settled, a check that
+ * skipped it, or (for a test send) the dry-run twin of either.
+ */
+export type DeliveryStatus = "sent" | "delivered" | "bounced" | "complained" | "failed" | "skipped_disabled" | "skipped_paused" | "skipped_suppressed" | "skipped_quota" | "skipped_unknown_purpose" | "skipped_frequency_cap" | "skipped_consent" | "skipped_domain" | "skipped_ssrf" | "would_send" | "would_skip_disabled" | "would_skip_paused" | "would_skip_suppressed" | "would_skip_quota" | "would_skip_unknown_purpose" | "would_skip_frequency_cap" | "would_skip_consent" | "would_skip_domain" | "would_skip_ssrf";
 /**
  * The named identifiers a call carries, at least one. Cowliss generates the
  * profile id and resolves the map to it; a call carrying two identifiers is
@@ -156,10 +161,26 @@ export type SendEmailInput = {
         key: string;
         props?: Record<string, unknown>;
     };
+    /**
+     * A dry run: every check the real send makes and the same refusals, one
+     * delivery row with the outcome, and nothing sent, no profile created, no
+     * idempotency key spent and no credit used.
+     */
+    test?: boolean;
 };
 export type SendEmailResult = {
     /** The delivery this send left behind: the row in Deliveries. */
     deliveryId: string;
+    /** `sent`, or the skip a check recorded; on a test, `would_send` or `would_skip_*`. */
+    status: DeliveryStatus;
+    /** A test send only: `to` named an `email` nobody holds, which the send would create. */
+    wouldCreateProfile?: boolean;
+    /** A test send only: the message the real send would carry. */
+    rendered?: {
+        subject: string;
+        html: string;
+        text: string;
+    };
 };
 /** A template key and the props a send would pass it. */
 export type PreviewEmailInput = {

package/dist/version.autogenerated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.20.0";
+export declare const SDK_VERSION = "0.21.0";

package/dist/version.autogenerated.js

@@ -1,2 +1,2 @@
 // Generated by scripts/version.ts from package.json. Do not edit.
-export const SDK_VERSION = "0.20.0";
+export const SDK_VERSION = "0.21.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowliss/sdk",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "exports": {
     ".": {