@cowliss/sdk 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 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.18.1 (2026-10-01)
+
+### Fixes
+
+- A retried emails.send carries one Idempotency-Key, so it never sends twice
+
+## 0.18.0 (2026-10-01)
+
+### Features
+
+- cow.preferences.link asks for one profile's email preferences page
+
 ## 0.17.0 (2026-10-01)
 
 ### Features

package/README.md

@@ -60,6 +60,14 @@ delivery id. A message to a profile goes to its `email` trait, skips anyone
 who turned that purpose off, and carries an unsubscribe link. Mail that
 follows a rule or a wait belongs in a journey.
 
+Send someone to their hosted email preferences page from your own "Manage
+email preferences" button. The link works for an hour, so ask for it on the
+click:
+
+```ts
+const { url, expiresAt } = await cow.preferences.link({ to: { userId: "shop_1" } });
+```
+
 Every call carries `identifiers`, a map from kind to value. Cowliss generates
 the profile id and resolves the map to it, so a call that carries two
 identifiers is what links two profiles. There is no alias call.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { BatchBody, BatchResultDto, ErrorCode, EventDto, IdentifyInput, ProfileDto, SendEmailInput, SendEmailResult, TrackInput } from "./types.js";
+import type { BatchBody, BatchResultDto, ErrorCode, EventDto, IdentifyInput, PreferencesLink, PreferencesLinkInput, ProfileDto, SendEmailInput, SendEmailResult, TrackInput } from "./types.js";
 export type * from "./types.js";
 /**
  * The Cowliss TS client SDK. Small typed surface over the ingestion API:
@@ -98,11 +98,22 @@ export declare class Cow {
      *
      * Synchronous like the rest of the client: the promise resolves once the
      * message has been handed over, and `deliveryId` is the row that records
-     * what happened to it.
+     * what happened to it. Each call carries its own Idempotency-Key on every
+     * attempt, so a retry after a lost reply answers with the first send's
+     * `deliveryId` instead of sending again.
      */
     emails: {
         send: (input: WithDefaultSource<SendEmailInput>) => Promise<SendEmailResult>;
     };
+    /**
+     * A link to one person's hosted email preferences page, for your app's own
+     * "Manage email preferences" button: `to` is one identifier naming them,
+     * as in `emails.send`. The page lists every purpose their app declares as
+     * a switch, and the link works for an hour, so ask for it when they click.
+     */
+    preferences: {
+        link: (input: WithDefaultSource<PreferencesLinkInput>) => Promise<PreferencesLink>;
+    };
     /**
      * Batch import: one source's identify and track calls in one request.
      * Track items must carry an explicit messageId: the API requires it and

package/dist/index.js

@@ -120,10 +120,21 @@ export class Cow {
      *
      * Synchronous like the rest of the client: the promise resolves once the
      * message has been handed over, and `deliveryId` is the row that records
-     * what happened to it.
+     * what happened to it. Each call carries its own Idempotency-Key on every
+     * attempt, so a retry after a lost reply answers with the first send's
+     * `deliveryId` instead of sending again.
      */
     emails = {
-        send: (input) => this.#watch(async () => this.#post("/v1/emails", {
+        send: (input) => this.#watch(async () => this.#post("/v1/emails", { data: { ...input, sourceId: this.#sourceFor(input) } }, crypto.randomUUID())),
+    };
+    /**
+     * A link to one person's hosted email preferences page, for your app's own
+     * "Manage email preferences" button: `to` is one identifier naming them,
+     * as in `emails.send`. The page lists every purpose their app declares as
+     * a switch, and the link works for an hour, so ask for it when they click.
+     */
+    preferences = {
+        link: (input) => this.#watch(async () => this.#post("/v1/preferences-links", {
             data: { ...input, sourceId: this.#sourceFor(input) },
         })),
     };
@@ -153,8 +164,8 @@ export class Cow {
                 });
                 // Reading the body is part of the attempt: an abort or a truncated
                 // response mid-read is a transport failure like any other, and
-                // retrying it is safe (track carries its Idempotency-Key, identify
-                // upserts on identifiers).
+                // retrying it is safe (track and emails.send carry an
+                // Idempotency-Key, identify upserts on identifiers).
                 if (res.ok) {
                     return (await res.json()).data;
                 }

package/dist/types.d.ts

@@ -161,6 +161,18 @@ export type SendEmailResult = {
     /** The delivery this send left behind: the row in Deliveries. */
     deliveryId: string;
 };
+/** One profile, named the way a send to a profile names it. */
+export type PreferencesLinkInput = {
+    sourceId: string;
+    /** Exactly one identifier naming a profile in the source's app. */
+    to: Identifiers;
+};
+export type PreferencesLink = {
+    /** The hosted preferences page for that profile. */
+    url: string;
+    /** ISO 8601: when the link stops working, an hour after it was minted. */
+    expiresAt: string;
+};
 /**
  * The two runtime constants in this file, and the reason they live beside
  * the types rather than in `@cowliss/shared`: this module is the SDK's one

package/dist/version.autogenerated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.17.0";
+export declare const SDK_VERSION = "0.18.1";

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.17.0";
+export const SDK_VERSION = "0.18.1";

package/package.json

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