@itm-studio/partner-sdk 0.2.2 → 0.2.3

package/README.md

@@ -369,6 +369,7 @@ Use OTP subscribe when you want the user to confirm the phone number before the
 - `listNames`: optional brand list names. Missing lists are created automatically and the subscribed user is attached to them.
 - `compliance`: optional metadata about how consent was collected. This is the right place for fields like `pageUrl`, `submissionMethod`, `submittedAt`, `timezone`, and geo/browser/device details.
 - `compliance.ipAddress` and `compliance.userAgent`: optional. If you omit them and forward `x-forwarded-for` and `user-agent`, the backend backfills those values for you.
+- `postSubscriptionMessage`: optional welcome message delivered automatically after the subscription becomes active. See [Post-Subscription Welcome Message](#post-subscription-welcome-message).
 
 ### OTP Flow Step By Step
 
@@ -381,6 +382,63 @@ Use OTP subscribe when you want the user to confirm the phone number before the
 
 If the verification token is invalid or expired, verification fails and the subscription is not created.
 
+### Post-Subscription Welcome Message
+
+`postSubscriptionMessage` lets you fan out a welcome touch across SMS, email, and push the moment a subscription becomes active. The backend dispatches each channel asynchronously after the subscription is created (direct mode) or verified (OTP mode), so the mutation still returns synchronously — delivery happens in the background.
+
+**Channels are independent.** Provide any combination of `sms`, `email`, and `push`. Channels you omit are skipped.
+
+```typescript
+await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: '+14155550111',
+        fullName: 'Jane Doe',
+        email: 'jane@example.com',
+        postSubscriptionMessage: {
+          sms: {
+            body: 'Welcome to Acme — your first drop ships Friday. Reply STOP to opt out.',
+            mediaUrls: ['https://cdn.example.com/welcome-banner.png'],
+          },
+          email: {
+            subject: 'Welcome to Acme',
+            body: 'Hi Jane,\n\nThanks for subscribing — here is what to expect next...',
+          },
+          push: {
+            title: 'Welcome to Acme',
+            body: 'Tap to see what is dropping this week.',
+          },
+        },
+      },
+    },
+    verificationRequired: true,
+    subscription: { uid: true },
+  },
+});
+```
+
+**Channel inputs:**
+
+| Channel | Required | Optional | Notes |
+|---|---|---|---|
+| `sms` | `body` | `mediaUrls` (string array of image URLs for MMS) | Delivered to `phoneNumber`. |
+| `email` | `subject`, `body` | — | `body` is plain text or markdown, rendered via React Email. Skipped if the user has no primary email or the brand has no configured email alias. |
+| `push` | `title`, `body` | — | Skipped if the user has no push tokens or has opted out of brand messages. |
+
+**Delivery semantics:**
+
+- The message is sent **at most once per active subscription period**. The backend uses an atomic per-channel claim plus an idempotency key on each underlying task, so retrying the mutation (for example after a transient network failure) will not duplicate sends.
+- The message is delivered when the subscription is **newly created or reactivated** — re-subscribing an already-active user is a no-op.
+- In OTP mode, the message fires **after** `verifyPartnerBrandSubscription` succeeds, not when the OTP is requested.
+- Channel failures are isolated: if email cannot be sent because the user has no primary email, SMS and push are still attempted.
+
+**Recommended usage:**
+
+- Pass `postSubscriptionMessage` on the **first** `createPartnerBrandSubscription` call. In OTP mode, the message is buffered with the pending session and delivered after `verifyPartnerBrandSubscription`. You do **not** repeat it on the verify call.
+- For a marketing-style first SMS, prefer including a clear opt-out instruction (e.g. `Reply STOP to opt out`) alongside any branded copy.
+- For the email channel, your brand must have an email alias configured on the backend. Confirm this in backstage before relying on the email channel in production.
+
 ### `createPartnerBrandSubscription`
 
 Subscribe a phone number to the authenticated partner brand.

package/dist/index.d.mts

@@ -795,6 +795,34 @@ interface SubscriptionComplianceInput {
     timezone?: (Scalars['String'] | null);
     userAgent?: (Scalars['String'] | null);
 }
+interface PostSubscriptionSmsInput {
+    /** SMS message body delivered to the subscriber. */
+    body: Scalars['String'];
+    /** Optional MMS media URLs (image links) attached to the SMS. */
+    mediaUrls?: (Scalars['String'][] | null);
+}
+interface PostSubscriptionEmailInput {
+    /** Email subject line. */
+    subject: Scalars['String'];
+    /** Plain-text or markdown body. Rendered via React Email. */
+    body: Scalars['String'];
+}
+interface PostSubscriptionPushInput {
+    /** Push notification title. */
+    title: Scalars['String'];
+    /** Push notification body. */
+    body: Scalars['String'];
+}
+/**
+ * Welcome message delivered after a successful subscription. Each channel is independent —
+ * provide any combination of sms, email, and push. Channels with no input are skipped.
+ * The message is sent at most once per active subscription period (atomic per-channel claim).
+ */
+interface PostSubscriptionMessageInput {
+    sms?: (PostSubscriptionSmsInput | null);
+    email?: (PostSubscriptionEmailInput | null);
+    push?: (PostSubscriptionPushInput | null);
+}
 interface CreatePartnerBrandSubscriptionInput {
     compliance?: (SubscriptionComplianceInput | null);
     email?: (Scalars['String'] | null);
@@ -805,6 +833,13 @@ interface CreatePartnerBrandSubscriptionInput {
     /** E.164 phone number (for example +14155551234) */
     phoneNumber: Scalars['String'];
     requireOtpVerification?: (Scalars['Boolean'] | null);
+    /**
+     * Optional welcome message to deliver via the chosen channels. Sent at most once per active
+     * subscription period — safe to retry. Email requires the user to have a primary email and
+     * the brand to have a configured email alias. Push requires the user to have at least one
+     * push token and to not have opted out of brand messages.
+     */
+    postSubscriptionMessage?: (PostSubscriptionMessageInput | null);
 }
 interface VerifyPartnerBrandSubscriptionInput {
     code: Scalars['String'];
@@ -1009,4 +1044,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type BrandSubscription, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type PartnerMomentStats, type Payment, type PaymentStatus, type Query, type SubscriptionComplianceInput, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };
+export { type BrandSubscription, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type PartnerMomentStats, type Payment, type PaymentStatus, type PostSubscriptionEmailInput, type PostSubscriptionMessageInput, type PostSubscriptionPushInput, type PostSubscriptionSmsInput, type Query, type SubscriptionComplianceInput, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };

package/dist/index.d.ts

@@ -795,6 +795,34 @@ interface SubscriptionComplianceInput {
     timezone?: (Scalars['String'] | null);
     userAgent?: (Scalars['String'] | null);
 }
+interface PostSubscriptionSmsInput {
+    /** SMS message body delivered to the subscriber. */
+    body: Scalars['String'];
+    /** Optional MMS media URLs (image links) attached to the SMS. */
+    mediaUrls?: (Scalars['String'][] | null);
+}
+interface PostSubscriptionEmailInput {
+    /** Email subject line. */
+    subject: Scalars['String'];
+    /** Plain-text or markdown body. Rendered via React Email. */
+    body: Scalars['String'];
+}
+interface PostSubscriptionPushInput {
+    /** Push notification title. */
+    title: Scalars['String'];
+    /** Push notification body. */
+    body: Scalars['String'];
+}
+/**
+ * Welcome message delivered after a successful subscription. Each channel is independent —
+ * provide any combination of sms, email, and push. Channels with no input are skipped.
+ * The message is sent at most once per active subscription period (atomic per-channel claim).
+ */
+interface PostSubscriptionMessageInput {
+    sms?: (PostSubscriptionSmsInput | null);
+    email?: (PostSubscriptionEmailInput | null);
+    push?: (PostSubscriptionPushInput | null);
+}
 interface CreatePartnerBrandSubscriptionInput {
     compliance?: (SubscriptionComplianceInput | null);
     email?: (Scalars['String'] | null);
@@ -805,6 +833,13 @@ interface CreatePartnerBrandSubscriptionInput {
     /** E.164 phone number (for example +14155551234) */
     phoneNumber: Scalars['String'];
     requireOtpVerification?: (Scalars['Boolean'] | null);
+    /**
+     * Optional welcome message to deliver via the chosen channels. Sent at most once per active
+     * subscription period — safe to retry. Email requires the user to have a primary email and
+     * the brand to have a configured email alias. Push requires the user to have at least one
+     * push token and to not have opted out of brand messages.
+     */
+    postSubscriptionMessage?: (PostSubscriptionMessageInput | null);
 }
 interface VerifyPartnerBrandSubscriptionInput {
     code: Scalars['String'];
@@ -1009,4 +1044,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type BrandSubscription, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type PartnerMomentStats, type Payment, type PaymentStatus, type Query, type SubscriptionComplianceInput, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };
+export { type BrandSubscription, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type PartnerMomentStats, type Payment, type PaymentStatus, type PostSubscriptionEmailInput, type PostSubscriptionMessageInput, type PostSubscriptionPushInput, type PostSubscriptionSmsInput, type Query, type SubscriptionComplianceInput, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };

package/dist/index.js

@@ -1490,6 +1490,53 @@ var types_default = {
         13
       ]
     },
+    "PostSubscriptionSmsInput": {
+      "body": [
+        13
+      ],
+      "mediaUrls": [
+        13
+      ],
+      "__typename": [
+        13
+      ]
+    },
+    "PostSubscriptionEmailInput": {
+      "subject": [
+        13
+      ],
+      "body": [
+        13
+      ],
+      "__typename": [
+        13
+      ]
+    },
+    "PostSubscriptionPushInput": {
+      "title": [
+        13
+      ],
+      "body": [
+        13
+      ],
+      "__typename": [
+        13
+      ]
+    },
+    "PostSubscriptionMessageInput": {
+      "sms": [
+        45
+      ],
+      "email": [
+        46
+      ],
+      "push": [
+        47
+      ],
+      "__typename": [
+        13
+      ]
+    },
     "CreatePartnerBrandSubscriptionInput": {
       "compliance": [
         44
@@ -1509,6 +1556,9 @@ var types_default = {
       "requireOtpVerification": [
         17
       ],
+      "postSubscriptionMessage": [
+        48
+      ],
       "__typename": [
         13
       ]
@@ -1586,7 +1636,7 @@ var types_default = {
     },
     "Mutation": {
       "getPartnerUploadUrl": [
-        47,
+        51,
         {
           "filename": [
             13,
@@ -1599,7 +1649,7 @@ var types_default = {
         }
       ],
       "createPartnerMediaAsset": [
-        48,
+        52,
         {
           "mimetype": [
             13,
@@ -1616,10 +1666,10 @@ var types_default = {
         }
       ],
       "createPartnerBrandSubscription": [
-        49,
+        53,
         {
           "input": [
-            45,
+            49,
             "CreatePartnerBrandSubscriptionInput!"
           ]
         }
@@ -1637,7 +1687,7 @@ var types_default = {
         38,
         {
           "input": [
-            46,
+            50,
             "VerifyPartnerBrandSubscriptionInput!"
           ]
         }