@marlinjai/mail-contract 0.11.0 → 0.13.0

package/dist/index.js

@@ -396,6 +396,13 @@ __export(index_exports, {
   TEMPLATE_SORTS: () => TEMPLATE_SORTS,
   TEMPLATE_SORT_DEFAULT_ORDER: () => TEMPLATE_SORT_DEFAULT_ORDER,
   TERMINAL_MAILING_STATUSES: () => TERMINAL_MAILING_STATUSES,
+  TRANSACTIONAL_BLOCKING_REASONS: () => TRANSACTIONAL_BLOCKING_REASONS,
+  TRANSACTIONAL_NEEDS_LETTER_REFUSAL: () => TRANSACTIONAL_NEEDS_LETTER_REFUSAL,
+  TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL: () => TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL,
+  TRANSACTIONAL_NOT_ALLOWED_REFUSAL: () => TRANSACTIONAL_NOT_ALLOWED_REFUSAL,
+  TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL: () => TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL,
+  TRUSTED_APPS: () => TRUSTED_APPS,
+  TRUSTED_APP_OPERATIONS: () => TRUSTED_APP_OPERATIONS,
   Tag: () => Tag,
   TagAssignment: () => TagAssignment,
   TagCreate: () => TagCreate,
@@ -441,6 +448,7 @@ __export(index_exports, {
   TrackingSettings: () => TrackingSettings,
   TranslationInsertion: () => TranslationInsertion,
   TranslationInsertions: () => TranslationInsertions,
+  TrustedApp: () => TrustedApp,
   UNSUBSCRIBE_PATH_PREFIX: () => UNSUBSCRIBE_PATH_PREFIX,
   UNSUBSCRIBE_SOURCES: () => UNSUBSCRIBE_SOURCES,
   USAGE_METRICS: () => USAGE_METRICS,
@@ -611,6 +619,7 @@ __export(index_exports, {
   translationInsertionProblems: () => translationInsertionProblems,
   translationTextFromInput: () => translationTextFromInput,
   triggerKey: () => triggerKey,
+  trustedAppMayCall: () => trustedAppMayCall,
   unknownRefusedInsertions: () => unknownRefusedInsertions,
   unplacedInsertions: () => unplacedInsertions,
   validateAutomation: () => validateAutomation,
@@ -1790,6 +1799,17 @@ var Mailing = import_zod8.z.object({
    * the workspace's defaults, below the recipient's own. Empty by default.
    */
   merge: MailingMerge.default({}),
+  /**
+   * Where a reader's reply goes for this mailing, or null for the sending
+   * provider's own reply address (see `MailingContent.reply_to`).
+   */
+  reply_to: Email.nullable().default(null),
+  /**
+   * Whether this is a transactional letter (see `MailingCreate.transactional`
+   * and "Transactional letters" in the contract's documentation). False for
+   * every mailing made without the flag.
+   */
+  transactional: import_zod8.z.boolean().default(false),
   scheduled_at: Timestamp.nullable(),
   /** The A/B test on subject or content (S4), null when there is none. */
   ab_test: AbTestState.nullable(),
@@ -1814,22 +1834,46 @@ var MailingContent = {
   send_locale: LocaleTag.nullable().optional(),
   /**
    * Omitted or null makes the mailing a letter: one recipient at most, sent to
-   * anybody not blocked on every topic, with an unsubscribe link that offers
-   * every topic and no List-Unsubscribe headers. See "Letters" in the
+   * anybody not blocked on every topic, with an unsubscribe link and
+   * List-Unsubscribe headers that offer every topic. See "Letters" in the
    * contract's documentation.
    */
   topic: Slug.nullable().optional(),
   provider_id: Id,
   metadata: MailingMetadata.optional(),
   /** See `Mailing.merge`. `first_name` and `last_name` only on a letter (no topic). */
-  merge: MailingMerge.optional()
+  merge: MailingMerge.optional(),
+  /**
+   * The Reply-To of this mailing's messages: one address, in place of the
+   * sending provider's `reply_to`. Omitted or null keeps the provider's. The
+   * sender (From) is always the provider's, and so is the mailto alternative
+   * of the List-Unsubscribe header, since a request to leave belongs to the
+   * workspace and not to whoever a reply reaches.
+   */
+  reply_to: Email.nullable().optional()
 };
 var MailingCreate = import_zod8.z.object({
   ...MailingContent,
   subject: MailingContent.subject.optional(),
   document: TemplateDocument.optional(),
   template_id: Id.optional(),
-  template_locale: LocaleTag.optional()
+  template_locale: LocaleTag.optional(),
+  /**
+   * True makes the mailing a transactional letter: mail that answers
+   * something its one reader did and that they need whatever they chose
+   * about marketing (a booking's confirmation, its reminder, its
+   * cancellation). It needs no `{{unsubscribe_url}}`, carries no
+   * List-Unsubscribe headers and is not stopped by an unsubscribe; a hard
+   * bounce, a spam complaint and a block set by hand still stop it.
+   *
+   * Only a key that a trusted application created may set it (`forbidden`,
+   * `details.reason: "transactional_not_allowed"`), only on a letter
+   * (`validation_failed`, `"transactional_needs_letter"`), from a template
+   * only with `template_locale` (`"transactional_needs_template_locale"`),
+   * and it is fixed when the mailing is created. See "Transactional letters" in the
+   * contract's documentation.
+   */
+  transactional: import_zod8.z.boolean().optional()
 }).refine((v) => v.document === void 0 !== (v.template_id === void 0), {
   message: "exactly one of document or template_id",
   path: ["document"]
@@ -1856,6 +1900,8 @@ var MailingUpdate = import_zod8.z.object({
    * them.
    */
   merge: MailingMerge.optional(),
+  /** See `MailingContent.reply_to`. Null goes back to the provider's reply address. */
+  reply_to: Email.nullable().optional(),
   document: TemplateDocument.optional()
 }).refine((v) => Object.keys(v).length > 0, "at least one field");
 var MailingListQuery = PageQuery.extend({
@@ -1904,6 +1950,11 @@ var Recipient = import_zod8.z.object({
 var MAX_RECIPIENTS_PER_BATCH = 1e3;
 var MAX_LETTER_RECIPIENTS = 1;
 var LETTER_RECIPIENT_REFUSAL = "letter_has_one_recipient";
+var TRANSACTIONAL_NOT_ALLOWED_REFUSAL = "transactional_not_allowed";
+var TRANSACTIONAL_NEEDS_LETTER_REFUSAL = "transactional_needs_letter";
+var TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL = "transactional_needs_template_locale";
+var TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL = "transactional_has_unsubscribe_url";
+var TRANSACTIONAL_BLOCKING_REASONS = ["bounced", "complained", "manual"];
 var RecipientInput = import_zod8.z.object({
   contact_id: Id.optional(),
   external_id: import_zod8.z.string().min(1).max(255).optional(),
@@ -3562,8 +3613,20 @@ var AUDIT_ACTIONS = [
   "event.recorded"
 ];
 var AuditAction = import_zod11.z.enum(AUDIT_ACTIONS);
+var TRUSTED_APPS = ["booking"];
+var TrustedApp = import_zod11.z.enum(TRUSTED_APPS);
 var AuditActor = import_zod11.z.discriminatedUnion("type", [
-  import_zod11.z.object({ type: import_zod11.z.literal("member"), member_id: Id, subject: import_zod11.z.string().min(1) }),
+  import_zod11.z.object({
+    type: import_zod11.z.literal("member"),
+    member_id: Id,
+    subject: import_zod11.z.string().min(1),
+    /**
+     * The application the person acted through, when it was not the dashboard:
+     * the service set it from the service token the call carried, so it is
+     * verified, unlike a key's `on_behalf_of`. Absent for the dashboard.
+     */
+    app: TrustedApp.optional()
+  }),
   import_zod11.z.object({
     type: import_zod11.z.literal("api_key"),
     api_key_id: Id,
@@ -6337,6 +6400,12 @@ var routes = {
   ...billingRoutes,
   ...automationRoutes
 };
+var TRUSTED_APP_OPERATIONS = {
+  booking: ["workspaces.list", "workspace.update", "providers.list", "apiKeys.create", "apiKeys.revoke"]
+};
+function trustedAppMayCall(app, id) {
+  return TRUSTED_APP_OPERATIONS[app].includes(id);
+}
 function acceptsIdempotencyKey(route) {
   return route.method !== "GET";
 }
@@ -6748,6 +6817,13 @@ function matchRoute(method, pathname) {
   TEMPLATE_SORTS,
   TEMPLATE_SORT_DEFAULT_ORDER,
   TERMINAL_MAILING_STATUSES,
+  TRANSACTIONAL_BLOCKING_REASONS,
+  TRANSACTIONAL_NEEDS_LETTER_REFUSAL,
+  TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL,
+  TRANSACTIONAL_NOT_ALLOWED_REFUSAL,
+  TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL,
+  TRUSTED_APPS,
+  TRUSTED_APP_OPERATIONS,
   Tag,
   TagAssignment,
   TagCreate,
@@ -6793,6 +6869,7 @@ function matchRoute(method, pathname) {
   TrackingSettings,
   TranslationInsertion,
   TranslationInsertions,
+  TrustedApp,
   UNSUBSCRIBE_PATH_PREFIX,
   UNSUBSCRIBE_SOURCES,
   USAGE_METRICS,
@@ -6963,6 +7040,7 @@ function matchRoute(method, pathname) {
   translationInsertionProblems,
   translationTextFromInput,
   triggerKey,
+  trustedAppMayCall,
   unknownRefusedInsertions,
   unplacedInsertions,
   validateAutomation,

package/dist/index.mjs

@@ -1168,6 +1168,17 @@ var Mailing = z8.object({
    * the workspace's defaults, below the recipient's own. Empty by default.
    */
   merge: MailingMerge.default({}),
+  /**
+   * Where a reader's reply goes for this mailing, or null for the sending
+   * provider's own reply address (see `MailingContent.reply_to`).
+   */
+  reply_to: Email.nullable().default(null),
+  /**
+   * Whether this is a transactional letter (see `MailingCreate.transactional`
+   * and "Transactional letters" in the contract's documentation). False for
+   * every mailing made without the flag.
+   */
+  transactional: z8.boolean().default(false),
   scheduled_at: Timestamp.nullable(),
   /** The A/B test on subject or content (S4), null when there is none. */
   ab_test: AbTestState.nullable(),
@@ -1192,22 +1203,46 @@ var MailingContent = {
   send_locale: LocaleTag.nullable().optional(),
   /**
    * Omitted or null makes the mailing a letter: one recipient at most, sent to
-   * anybody not blocked on every topic, with an unsubscribe link that offers
-   * every topic and no List-Unsubscribe headers. See "Letters" in the
+   * anybody not blocked on every topic, with an unsubscribe link and
+   * List-Unsubscribe headers that offer every topic. See "Letters" in the
    * contract's documentation.
    */
   topic: Slug.nullable().optional(),
   provider_id: Id,
   metadata: MailingMetadata.optional(),
   /** See `Mailing.merge`. `first_name` and `last_name` only on a letter (no topic). */
-  merge: MailingMerge.optional()
+  merge: MailingMerge.optional(),
+  /**
+   * The Reply-To of this mailing's messages: one address, in place of the
+   * sending provider's `reply_to`. Omitted or null keeps the provider's. The
+   * sender (From) is always the provider's, and so is the mailto alternative
+   * of the List-Unsubscribe header, since a request to leave belongs to the
+   * workspace and not to whoever a reply reaches.
+   */
+  reply_to: Email.nullable().optional()
 };
 var MailingCreate = z8.object({
   ...MailingContent,
   subject: MailingContent.subject.optional(),
   document: TemplateDocument.optional(),
   template_id: Id.optional(),
-  template_locale: LocaleTag.optional()
+  template_locale: LocaleTag.optional(),
+  /**
+   * True makes the mailing a transactional letter: mail that answers
+   * something its one reader did and that they need whatever they chose
+   * about marketing (a booking's confirmation, its reminder, its
+   * cancellation). It needs no `{{unsubscribe_url}}`, carries no
+   * List-Unsubscribe headers and is not stopped by an unsubscribe; a hard
+   * bounce, a spam complaint and a block set by hand still stop it.
+   *
+   * Only a key that a trusted application created may set it (`forbidden`,
+   * `details.reason: "transactional_not_allowed"`), only on a letter
+   * (`validation_failed`, `"transactional_needs_letter"`), from a template
+   * only with `template_locale` (`"transactional_needs_template_locale"`),
+   * and it is fixed when the mailing is created. See "Transactional letters" in the
+   * contract's documentation.
+   */
+  transactional: z8.boolean().optional()
 }).refine((v) => v.document === void 0 !== (v.template_id === void 0), {
   message: "exactly one of document or template_id",
   path: ["document"]
@@ -1234,6 +1269,8 @@ var MailingUpdate = z8.object({
    * them.
    */
   merge: MailingMerge.optional(),
+  /** See `MailingContent.reply_to`. Null goes back to the provider's reply address. */
+  reply_to: Email.nullable().optional(),
   document: TemplateDocument.optional()
 }).refine((v) => Object.keys(v).length > 0, "at least one field");
 var MailingListQuery = PageQuery.extend({
@@ -1282,6 +1319,11 @@ var Recipient = z8.object({
 var MAX_RECIPIENTS_PER_BATCH = 1e3;
 var MAX_LETTER_RECIPIENTS = 1;
 var LETTER_RECIPIENT_REFUSAL = "letter_has_one_recipient";
+var TRANSACTIONAL_NOT_ALLOWED_REFUSAL = "transactional_not_allowed";
+var TRANSACTIONAL_NEEDS_LETTER_REFUSAL = "transactional_needs_letter";
+var TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL = "transactional_needs_template_locale";
+var TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL = "transactional_has_unsubscribe_url";
+var TRANSACTIONAL_BLOCKING_REASONS = ["bounced", "complained", "manual"];
 var RecipientInput = z8.object({
   contact_id: Id.optional(),
   external_id: z8.string().min(1).max(255).optional(),
@@ -2940,8 +2982,20 @@ var AUDIT_ACTIONS = [
   "event.recorded"
 ];
 var AuditAction = z11.enum(AUDIT_ACTIONS);
+var TRUSTED_APPS = ["booking"];
+var TrustedApp = z11.enum(TRUSTED_APPS);
 var AuditActor = z11.discriminatedUnion("type", [
-  z11.object({ type: z11.literal("member"), member_id: Id, subject: z11.string().min(1) }),
+  z11.object({
+    type: z11.literal("member"),
+    member_id: Id,
+    subject: z11.string().min(1),
+    /**
+     * The application the person acted through, when it was not the dashboard:
+     * the service set it from the service token the call carried, so it is
+     * verified, unlike a key's `on_behalf_of`. Absent for the dashboard.
+     */
+    app: TrustedApp.optional()
+  }),
   z11.object({
     type: z11.literal("api_key"),
     api_key_id: Id,
@@ -5715,6 +5769,12 @@ var routes = {
   ...billingRoutes,
   ...automationRoutes
 };
+var TRUSTED_APP_OPERATIONS = {
+  booking: ["workspaces.list", "workspace.update", "providers.list", "apiKeys.create", "apiKeys.revoke"]
+};
+function trustedAppMayCall(app, id) {
+  return TRUSTED_APP_OPERATIONS[app].includes(id);
+}
 function acceptsIdempotencyKey(route) {
   return route.method !== "GET";
 }
@@ -6125,6 +6185,13 @@ export {
   TEMPLATE_SORTS,
   TEMPLATE_SORT_DEFAULT_ORDER,
   TERMINAL_MAILING_STATUSES,
+  TRANSACTIONAL_BLOCKING_REASONS,
+  TRANSACTIONAL_NEEDS_LETTER_REFUSAL,
+  TRANSACTIONAL_NEEDS_TEMPLATE_LOCALE_REFUSAL,
+  TRANSACTIONAL_NOT_ALLOWED_REFUSAL,
+  TRANSACTIONAL_UNSUBSCRIBE_URL_REFUSAL,
+  TRUSTED_APPS,
+  TRUSTED_APP_OPERATIONS,
   Tag,
   TagAssignment,
   TagCreate,
@@ -6170,6 +6237,7 @@ export {
   TrackingSettings,
   TranslationInsertion,
   TranslationInsertions,
+  TrustedApp,
   UNSUBSCRIBE_PATH_PREFIX,
   UNSUBSCRIBE_SOURCES,
   USAGE_METRICS,
@@ -6340,6 +6408,7 @@ export {
   translationInsertionProblems,
   translationTextFromInput,
   triggerKey,
+  trustedAppMayCall,
   unknownRefusedInsertions,
   unplacedInsertions,
   validateAutomation,

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The v1 API contract of the mail service: zod schemas and types for every request, response, error and webhook, the route table, and webhook signing helpers",
   "license": "MIT",
   "repository": {