@cowliss/sdk 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+<!-- GENERATED by `pnpm release` from the commit log (apps/docs/scripts/changelog.ts). Do not edit. -->
+
+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.0 (2026-10-01)
+
+### Features
+
+- cow.preferences.link asks for one profile's email preferences page
+
+## 0.17.0 (2026-10-01)
+
+### Features
+
+- **Emails:** cow.emails.send can address a profile instead of an address
+- Identify takes consent by purpose path, such as "marketing.newsletter"
+- A changelog in each package and on the docs site

package/README.md

@@ -36,19 +36,37 @@ await cow.track({
 });
 ```
 
-Send a transactional message from your own code, with a template you pushed
-or a body written inline:
+Send a message from your own code, with a template you pushed or a body
+written inline. Address an email address for mail nobody can turn off, such
+as a receipt, or a profile for mail its recipient can, such as a weekly
+report:
 
 ```ts
 await cow.emails.send({
   to: "ada@example.com",
+  from: "Acme <hello@acme.com>",
   template: { key: "receipt", props: { orderId: "A-2291" } },
 });
+
+await cow.emails.send({
+  to: { userId: "shop_1" },
+  from: "Acme <hello@acme.com>",
+  template: { key: "weekly-report", props: { visits: 120 } },
+});
 ```
 
 It resolves once the message has been handed over, and answers with the
-delivery id. Mail that follows a rule or a wait belongs in a journey, which
-is where consent and frequency live.
+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

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:
@@ -90,9 +90,11 @@ export declare class Cow {
      */
     track(input: WithDefaultSource<TrackInput>): Promise<EventDto>;
     /**
-     * The transactional send a developer's own code makes: a receipt, a
-     * password reset, an export that is ready. Mail that follows a rule or a
-     * wait belongs in a journey, which is where consent and frequency live.
+     * The send a developer's own code makes: a receipt, a password reset, an
+     * export that is ready, a weekly report. Address an address for mail
+     * nobody can turn off, or a profile (`to: { userId }`) for mail its
+     * recipient can, which then asks their consent and carries an unsubscribe
+     * link. Mail that follows a rule or a wait belongs in a journey.
      *
      * Synchronous like the rest of the client: the promise resolves once the
      * message has been handed over, and `deliveryId` is the row that records
@@ -101,6 +103,15 @@ export declare class Cow {
     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

@@ -112,9 +112,11 @@ export class Cow {
         });
     }
     /**
-     * The transactional send a developer's own code makes: a receipt, a
-     * password reset, an export that is ready. Mail that follows a rule or a
-     * wait belongs in a journey, which is where consent and frequency live.
+     * The send a developer's own code makes: a receipt, a password reset, an
+     * export that is ready, a weekly report. Address an address for mail
+     * nobody can turn off, or a profile (`to: { userId }`) for mail its
+     * recipient can, which then asks their consent and carries an unsubscribe
+     * link. Mail that follows a rule or a wait belongs in a journey.
      *
      * Synchronous like the rest of the client: the promise resolves once the
      * message has been handed over, and `deliveryId` is the row that records
@@ -125,6 +127,17 @@ export class Cow {
             data: { ...input, sourceId: this.#sourceFor(input) },
         })),
     };
+    /**
+     * 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) },
+        })),
+    };
     /**
      * 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/types.d.ts

@@ -57,10 +57,13 @@ export type EventDto = {
     receivedAt: string;
     messageId: string | null;
 };
-/** The consent purpose every org holds, as a caller patches it. */
-export type ConsentPatch = {
-    marketing?: boolean;
-};
+/**
+ * A purpose path: one of the two roots, or a name your app's `cow.json`
+ * declares under one, such as `"marketing.newsletter"`.
+ */
+export type PurposePath = "marketing" | "transactional" | `marketing.${string}` | `transactional.${string}`;
+/** What a person agreed to, per purpose path, as a caller patches it. */
+export type ConsentPatch = Partial<Record<PurposePath, boolean>>;
 export type IdentifyInput = {
     sourceId: string;
     identifiers: Identifiers;
@@ -69,8 +72,9 @@ export type IdentifyInput = {
      * What this person agreed to, as a merge patch: a purpose the call omits
      * keeps the value it had, so a later identify is never an accidental
      * revocation. Omitting it entirely leaves consent untouched, which on a
-     * first write means marketing denied and data processing granted. At least
-     * one purpose when present.
+     * first write means every marketing purpose off and every transactional
+     * one on. A name your app does not declare is refused. At least one
+     * purpose when present.
      */
     consent?: ConsentPatch;
     /** ISO 8601 UTC. A past timestamp backdates a first-write profile. */
@@ -125,10 +129,18 @@ export type BatchItemResult = {
 export type BatchResultDto = {
     results: BatchItemResult[];
 };
-/** One transactional email: a pushed template, or a body written inline. */
+/** One email: a pushed template, or a body written inline. */
 export type SendEmailInput = {
     sourceId: string;
-    to: string | string[];
+    /**
+     * An address or a list of them, or exactly one identifier naming a profile
+     * in the source's app, such as `{ userId: "shop_1" }`. A profile is mailed at
+     * its `email` trait and is the only recipient a template with a purpose
+     * they can turn off may go to; a bare address takes bare `transactional`
+     * templates and inline bodies alone. `cc` and `bcc` are refused beside a
+     * profile.
+     */
+    to: string | string[] | Identifiers;
     cc?: string | string[];
     bcc?: string | string[];
     replyTo?: string | string[];
@@ -149,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.16.0";
+export declare const SDK_VERSION = "0.18.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.16.0";
+export const SDK_VERSION = "0.18.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowliss/sdk",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "exports": {
     ".": {
@@ -30,7 +30,8 @@
   "files": [
     "dist",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsx scripts/version.ts && tsc -b tsconfig.json --force",