@itm-studio/partner-sdk 0.2.3 → 0.2.4

package/README.md

@@ -369,7 +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).
+- `postSubscriptionMessage`: optional welcome message delivered automatically after the subscription becomes active. The SDK exposes this as `PostSubscriptionMessageInput` and accepts it on `CreatePartnerBrandSubscriptionInput`. See [Post-Subscription Welcome Message](#post-subscription-welcome-message).
 
 ### OTP Flow Step By Step
 
@@ -388,6 +388,37 @@ If the verification token is invalid or expired, verification fails and the subs
 
 **Channels are independent.** Provide any combination of `sms`, `email`, and `push`. Channels you omit are skipped.
 
+The field is part of the generated SDK input types:
+
+```typescript
+import type {
+  CreatePartnerBrandSubscriptionInput,
+  PostSubscriptionMessageInput,
+} from '@itm-studio/partner-sdk';
+
+const welcomeMessage: PostSubscriptionMessageInput = {
+  sms: {
+    body: 'Welcome to Acme. Reply STOP to opt out.',
+    mediaUrls: ['https://cdn.example.com/welcome-banner.png'],
+  },
+  email: {
+    subject: 'Welcome to Acme',
+    body: 'Thanks for subscribing. Your first update is on the way.',
+  },
+  push: {
+    title: 'Welcome to Acme',
+    body: 'Tap to see what is dropping this week.',
+  },
+};
+
+const input: CreatePartnerBrandSubscriptionInput = {
+  phoneNumber: '+14155550111',
+  fullName: 'Jane Doe',
+  email: 'jane@example.com',
+  postSubscriptionMessage: welcomeMessage,
+};
+```
+
 ```typescript
 await itm.mutation({
   createPartnerBrandSubscription: {
@@ -418,6 +449,15 @@ await itm.mutation({
 });
 ```
 
+**Direct vs OTP timing:**
+
+| Mode | Where to pass `postSubscriptionMessage` | When delivery starts |
+|---|---|---|
+| Direct subscribe | Initial `createPartnerBrandSubscription` call | After the subscription is created or reactivated |
+| OTP subscribe | Initial `createPartnerBrandSubscription` call with `requireOtpVerification: true` | After `verifyPartnerBrandSubscription` succeeds |
+
+Do not pass `postSubscriptionMessage` to `verifyPartnerBrandSubscription`; that mutation only accepts `verificationToken` and `code`.
+
 **Channel inputs:**
 
 | Channel | Required | Optional | Notes |
@@ -432,12 +472,76 @@ await itm.mutation({
 - 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.
+- Delivery is asynchronous. A successful mutation means the subscription request was accepted; it does not mean each SMS, email, or push provider has already completed delivery.
 
 **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.
+- Keep message content deterministic for a signup attempt. Because delivery is idempotent per active subscription period, retrying the same create call is safe; changing the message between retries should not be used as an update mechanism.
+
+**Minimal SMS-only example:**
+
+```typescript
+await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: '+14155550111',
+        postSubscriptionMessage: {
+          sms: {
+            body: 'You are subscribed to Acme updates. Reply STOP to opt out.',
+          },
+        },
+      },
+    },
+    verificationRequired: true,
+    subscription: { uid: true },
+  },
+});
+```
+
+**OTP example with buffered welcome message:**
+
+```typescript
+const { createPartnerBrandSubscription } = await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: '+14155550112',
+        requireOtpVerification: true,
+        email: 'jane@example.com',
+        postSubscriptionMessage: {
+          sms: {
+            body: 'Thanks for joining Acme. Reply STOP to opt out.',
+          },
+          email: {
+            subject: 'You are subscribed',
+            body: 'Your subscription is confirmed. We will send updates here.',
+          },
+        },
+      },
+    },
+    verificationRequired: true,
+    verificationToken: true,
+  },
+});
+
+// Later, after collecting the SMS code from the user:
+await itm.mutation({
+  verifyPartnerBrandSubscription: {
+    __args: {
+      input: {
+        verificationToken: createPartnerBrandSubscription.verificationToken!,
+        code: '123456',
+      },
+    },
+    uid: true,
+    isActive: true,
+  },
+});
+```
 
 ### `createPartnerBrandSubscription`
 
@@ -446,6 +550,7 @@ Subscribe a phone number to the authenticated partner brand.
 - Omit `requireOtpVerification` or set it to `false` to create the subscription immediately.
 - Set `requireOtpVerification: true` to start the OTP flow. The backend sends the code to the provided phone number and returns a `verificationToken`.
 - If you pass `fullName`, include both first and last name.
+- Pass `postSubscriptionMessage` here if you want SMS, email, or push sent after activation. This field is accepted only on the create mutation, including OTP starts.
 
 ```typescript
 const { createPartnerBrandSubscription } = await itm.mutation({
@@ -460,6 +565,11 @@ const { createPartnerBrandSubscription } = await itm.mutation({
           pageUrl: 'https://example.com/signup',
           submissionMethod: 'partner_sdk',
         },
+        postSubscriptionMessage: {
+          sms: {
+            body: 'Welcome to Acme updates. Reply STOP to opt out.',
+          },
+        },
       },
     },
     verificationRequired: true,
@@ -580,6 +690,15 @@ export async function startOtpSubscription(request: Request) {
             submittedAt: new Date().toISOString(),
             timezone: 'America/New_York',
           },
+          postSubscriptionMessage: {
+            sms: {
+              body: 'You are subscribed. Reply STOP to opt out.',
+            },
+            email: {
+              subject: 'Welcome',
+              body: 'Your subscription is confirmed.',
+            },
+          },
         },
       },
       verificationRequired: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itm-studio/partner-sdk",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "TypeScript SDK for the ITM Partner API — typed GraphQL client with zero introspection required",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,7 +21,7 @@
     "build": "npm run generate && tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "prepublishOnly": "npm run build",
     "schema:check": "hive schema:check ./schema/partner.graphql",
     "schema:publish": "hive schema:publish ./schema/partner.graphql --author \"CI\" --commit \"$GITHUB_SHA\""