@cowliss/sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 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.19.0 (2026-10-02)
+
+### Features
+
+- emails.send takes an idempotencyKey and creates the person it emails
+- cow.preferences.get and set, the hosted preferences page as data
+
+## 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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { BatchBody, BatchResultDto, ErrorCode, EventDto, IdentifyInput, PreferencesLink, PreferencesLinkInput, ProfileDto, SendEmailInput, SendEmailResult, TrackInput } from "./types.js";
+import type { BatchBody, BatchResultDto, ErrorCode, EventDto, GetPreferencesInput, IdentifyInput, Preferences, PreferencesLink, PreferencesLinkInput, ProfileDto, SendEmailInput, SendEmailResult, SetPreferencesInput, TrackInput } from "./types.js";
 export type * from "./types.js";
 /**
  * The Cowliss TS client SDK. Small typed surface over the ingestion API:
@@ -98,18 +98,32 @@ 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 an Idempotency-Key on every
+     * attempt, so a retry after a lost reply answers with the first send's
+     * `deliveryId` instead of sending again. Pass your own `idempotencyKey`
+     * (an order id, a job id) and a second run of your own code dedupes too;
+     * without one, each call is a send of its own.
+     *
+     * Addressed to `{ email }` that no profile in the app holds yet, the send
+     * creates that profile first, as `identify` would.
      */
     emails: {
-        send: (input: WithDefaultSource<SendEmailInput>) => Promise<SendEmailResult>;
+        send: ({ idempotencyKey, ...input }: WithDefaultSource<SendEmailInput> & {
+            idempotencyKey?: string;
+        }) => 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.
+     * One person's email preferences, `to` naming them as in `emails.send`.
+     *
+     * `link` is the hosted page, for a "Manage email preferences" button: it
+     * lists every purpose their app declares as a switch, and the link works
+     * for an hour, so ask for it when they click. `get` and `set` are the same
+     * page as data, for an app that draws its own: `set` saves what the person
+     * chose, where `identify({ consent })` records what the app decided.
      */
     preferences: {
+        get: (input: WithDefaultSource<GetPreferencesInput>) => Promise<Preferences>;
+        set: (input: WithDefaultSource<SetPreferencesInput>) => Promise<Preferences>;
         link: (input: WithDefaultSource<PreferencesLinkInput>) => Promise<PreferencesLink>;
     };
     /**

package/dist/index.js

@@ -120,20 +120,34 @@ 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 an Idempotency-Key on every
+     * attempt, so a retry after a lost reply answers with the first send's
+     * `deliveryId` instead of sending again. Pass your own `idempotencyKey`
+     * (an order id, a job id) and a second run of your own code dedupes too;
+     * without one, each call is a send of its own.
+     *
+     * Addressed to `{ email }` that no profile in the app holds yet, the send
+     * creates that profile first, as `identify` would.
      */
     emails = {
-        send: (input) => this.#watch(async () => this.#post("/v1/emails", {
-            data: { ...input, sourceId: this.#sourceFor(input) },
-        })),
+        send: ({ idempotencyKey, ...input }) => this.#watch(async () => this.#post("/v1/emails", { data: { ...input, sourceId: this.#sourceFor(input) } }, idempotencyKey ?? 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.
+     * One person's email preferences, `to` naming them as in `emails.send`.
+     *
+     * `link` is the hosted page, for a "Manage email preferences" button: it
+     * lists every purpose their app declares as a switch, and the link works
+     * for an hour, so ask for it when they click. `get` and `set` are the same
+     * page as data, for an app that draws its own: `set` saves what the person
+     * chose, where `identify({ consent })` records what the app decided.
      */
     preferences = {
+        get: (input) => this.#watch(async () => this.#post("/v1/profile-preferences/find", {
+            data: { ...input, sourceId: this.#sourceFor(input) },
+        })),
+        set: (input) => this.#watch(async () => this.#post("/v1/profile-preferences", {
+            data: { ...input, sourceId: this.#sourceFor(input) },
+        })),
         link: (input) => this.#watch(async () => this.#post("/v1/preferences-links", {
             data: { ...input, sourceId: this.#sourceFor(input) },
         })),
@@ -164,8 +178,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

@@ -167,6 +167,29 @@ export type PreferencesLinkInput = {
     /** Exactly one identifier naming a profile in the source's app. */
     to: Identifiers;
 };
+/** One profile's switches, read or saved from your app's own page. */
+export type GetPreferencesInput = PreferencesLinkInput;
+export type SetPreferencesInput = PreferencesLinkInput & {
+    /**
+     * The switches to change: `marketing` or a purpose your app declares.
+     * Keys left out keep their answer.
+     */
+    consent: ConsentPatch;
+};
+/** One switch: `marketing`, or a purpose your app declares. */
+export type Preference = {
+    key: string;
+    label: string;
+    description: string | null;
+    /** Whether a send under this purpose would reach them now. */
+    enabled: boolean;
+    /** Whether they hold their own answer, rather than the default. */
+    answered: boolean;
+};
+export type Preferences = {
+    /** `marketing` first, then your app's purposes by key. */
+    purposes: Preference[];
+};
 export type PreferencesLink = {
     /** The hosted preferences page for that profile. */
     url: string;

package/dist/version.autogenerated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.18.0";
+export declare const SDK_VERSION = "0.19.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.18.0";
+export const SDK_VERSION = "0.19.0";

package/package.json

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