@kirimdev/sdk 3.9.0 → 3.10.0

package/dist/generated/schema.d.ts

@@ -260,7 +260,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -320,7 +320,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -340,7 +349,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -363,7 +381,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -386,7 +413,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -409,7 +445,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -433,7 +478,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -468,7 +522,16 @@ export interface paths {
                         messaging_product: "whatsapp";
                         /** @enum {string} */
                         recipient_type?: "individual";
-                        to: string;
+                        /**
+                         * @description Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).
+                         * @example 628123456789
+                         */
+                        to?: string;
+                        /**
+                         * @description Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.
+                         * @example US.13491208655302741918
+                         */
+                        recipient?: string;
                         /** Reply context */
                         context?: {
                             /**
@@ -669,7 +732,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -784,7 +847,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -885,7 +948,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -1026,7 +1089,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -1129,7 +1192,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -1227,7 +1290,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -1824,7 +1887,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2301,7 +2364,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2395,7 +2458,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2490,7 +2553,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2536,6 +2599,8 @@ export interface paths {
             parameters: {
                 query?: {
                     phone?: string;
+                    bsuid?: string;
+                    username?: string;
                     search?: string;
                     limit?: string;
                     cursor?: string;
@@ -2585,7 +2650,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2632,7 +2697,9 @@ export interface paths {
             requestBody?: {
                 content: {
                     "application/json": {
-                        phone_number: string;
+                        phone_number?: string;
+                        bsuid?: string;
+                        username?: string;
                         name?: string;
                         /** Format: email */
                         email?: string | null;
@@ -2679,7 +2746,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2771,7 +2838,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2855,7 +2922,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -2905,6 +2972,7 @@ export interface paths {
                 content: {
                     "application/json": {
                         name?: string | null;
+                        username?: string | null;
                         email?: string | "" | null;
                         metadata?: {
                             [key: string]: unknown;
@@ -2949,7 +3017,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3040,7 +3108,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3145,7 +3213,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3241,7 +3309,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3345,7 +3413,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3445,7 +3513,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -3541,7 +3609,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Semantic failure (e.g. idempotency key reuse) */
+                /** @description Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found) */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -4004,7 +4072,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4086,7 +4154,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4167,7 +4235,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4249,7 +4317,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4341,7 +4409,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4432,7 +4500,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4523,7 +4591,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4620,7 +4688,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4719,7 +4787,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorEnvelope"];
                     };
                 };
-                /** @description Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive) */
+                /** @description Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue. */
                 402: {
                     headers: {
                         [name: string]: unknown;
@@ -4774,8 +4842,11 @@ export interface components {
     schemas: {
         ApiErrorEnvelope: {
             error: {
-                /** @example invalid_request_error */
-                type: string;
+                /**
+                 * @example invalid_request_error
+                 * @enum {string}
+                 */
+                type: "invalid_request_error" | "authentication_error" | "permission_error" | "not_found" | "conflict" | "rate_limit_error" | "api_error";
                 /** @example invalid_phone_number */
                 code: string;
                 message: string;
@@ -4803,7 +4874,26 @@ export interface components {
             id: string;
             /** @enum {string} */
             object: "message";
-            to?: string;
+            /**
+             * @description Recipient's phone number in E.164 (with leading `+`). NULL when the message targeted a Business-Scoped User ID (BSUID) recipient and the contact has no known phone number. See docs/meta-docs/bsuid.md.
+             * @example +628123456789
+             */
+            to?: string | null;
+            /**
+             * @description Recipient contact's Business-Scoped User ID. Present when the contact has been enriched with a BSUID from a Meta webhook (or from a BSUID-first send). NULL for phone-only contacts.
+             * @example US.13491208655302741918
+             */
+            bsuid?: string | null;
+            /**
+             * @description Parent BSUID for managed businesses with linked business portfolios. NULL for regular accounts.
+             * @example US.ENT.11815799212886844830
+             */
+            parent_bsuid?: string | null;
+            /**
+             * @description Recipient contact's WhatsApp username (case-insensitive comparison; case-preserving in storage). NULL when the contact has not adopted the WhatsApp username feature.
+             * @example pablomorales
+             */
+            username?: string | null;
             type?: string;
             /** @enum {string} */
             status: "queued" | "pending" | "sent" | "delivered" | "read" | "failed";
@@ -4948,7 +5038,26 @@ export interface components {
             id: string;
             /** @enum {string} */
             object: "contact";
+            /**
+             * @description Phone number in E.164. NULL when the contact was created via BSUID (username-adopted user with no shared phone number). See docs/meta-docs/bsuid.md.
+             * @example +628123456789
+             */
             phone_number: string | null;
+            /**
+             * @description Business-Scoped User ID. Populated by inbound webhooks or when the contact was created via BSUID. Format: `{ISO alpha-2 country}.{alphanumeric ≤128}`.
+             * @example US.13491208655302741918
+             */
+            bsuid: string | null;
+            /**
+             * @description Parent BSUID (managed businesses only). Format: `{ISO alpha-2 country}.ENT.{alphanumeric ≤128}`.
+             * @example US.ENT.11815799212886844830
+             */
+            parent_bsuid: string | null;
+            /**
+             * @description WhatsApp username of the contact, if the user has adopted the username feature. Case-insensitive when comparing per Meta rules; `.` and `_` are significant.
+             * @example pablomorales
+             */
+            username: string | null;
             name: string | null;
             email: string | null;
             metadata: {

package/dist/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION: "3.9.0";
+export declare const SDK_VERSION: "3.10.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,EAAG,OAAgB,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,EAAG,QAAiB,CAAA"}

package/dist/generated/version.js

@@ -2,5 +2,5 @@
 // Regenerated on every prebuild / pretypecheck / pretest from
 // package.json so the User-Agent header stays in sync with the
 // published version.
-export const SDK_VERSION = "3.9.0";
+export const SDK_VERSION = "3.10.0";
 //# sourceMappingURL=version.js.map

package/dist/generated/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,8DAA8D;AAC9D,+DAA+D;AAC/D,qBAAqB;AAErB,MAAM,CAAC,MAAM,WAAW,GAAG,OAAgB,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,8DAA8D;AAC9D,+DAA+D;AAC/D,qBAAqB;AAErB,MAAM,CAAC,MAAM,WAAW,GAAG,QAAiB,CAAA"}

package/dist/generated/version.ts

@@ -3,4 +3,4 @@
 // package.json so the User-Agent header stays in sync with the
 // published version.
 
-export const SDK_VERSION = "3.9.0" as const
+export const SDK_VERSION = "3.10.0" as const

package/openapi.json

@@ -75,6 +75,15 @@
             "properties": {
               "type": {
                 "type": "string",
+                "enum": [
+                  "invalid_request_error",
+                  "authentication_error",
+                  "permission_error",
+                  "not_found",
+                  "conflict",
+                  "rate_limit_error",
+                  "api_error"
+                ],
                 "example": "invalid_request_error"
               },
               "code": {
@@ -162,7 +171,36 @@
             ]
           },
           "to": {
-            "type": "string"
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "+628123456789",
+            "description": "Recipient's phone number in E.164 (with leading `+`). NULL when the message targeted a Business-Scoped User ID (BSUID) recipient and the contact has no known phone number. See docs/meta-docs/bsuid.md."
+          },
+          "bsuid": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "US.13491208655302741918",
+            "description": "Recipient contact's Business-Scoped User ID. Present when the contact has been enriched with a BSUID from a Meta webhook (or from a BSUID-first send). NULL for phone-only contacts."
+          },
+          "parent_bsuid": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "US.ENT.11815799212886844830",
+            "description": "Parent BSUID for managed businesses with linked business portfolios. NULL for regular accounts."
+          },
+          "username": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "pablomorales",
+            "description": "Recipient contact's WhatsApp username (case-insensitive comparison; case-preserving in storage). NULL when the contact has not adopted the WhatsApp username feature."
           },
           "type": {
             "type": "string"
@@ -678,7 +716,33 @@
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "example": "+628123456789",
+            "description": "Phone number in E.164. NULL when the contact was created via BSUID (username-adopted user with no shared phone number). See docs/meta-docs/bsuid.md."
+          },
+          "bsuid": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "US.13491208655302741918",
+            "description": "Business-Scoped User ID. Populated by inbound webhooks or when the contact was created via BSUID. Format: `{ISO alpha-2 country}.{alphanumeric ≤128}`."
+          },
+          "parent_bsuid": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "US.ENT.11815799212886844830",
+            "description": "Parent BSUID (managed businesses only). Format: `{ISO alpha-2 country}.ENT.{alphanumeric ≤128}`."
+          },
+          "username": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "example": "pablomorales",
+            "description": "WhatsApp username of the contact, if the user has adopted the username feature. Case-insensitive when comparing per Meta rules; `.` and `_` are significant."
           },
           "name": {
             "type": [
@@ -715,6 +779,9 @@
           "id",
           "object",
           "phone_number",
+          "bsuid",
+          "parent_bsuid",
+          "username",
           "name",
           "email",
           "metadata",
@@ -2615,7 +2682,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -2657,7 +2732,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "text"
                     ],
@@ -2679,7 +2753,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -2727,7 +2809,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "image"
                     ],
@@ -2749,7 +2830,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -2797,7 +2886,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "document"
                     ],
@@ -2819,7 +2907,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -2867,7 +2963,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "video"
                     ],
@@ -2889,7 +2984,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -2940,7 +3043,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "audio"
                     ],
@@ -2962,7 +3064,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -3068,7 +3178,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "template"
                     ],
@@ -3090,7 +3199,15 @@
                         ]
                       },
                       "to": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Recipient's WhatsApp phone number in E.164 (e.g. `628123456789`). Either `to` or `recipient` is required; if both are supplied, Meta uses `to` (documented precedence).",
+                        "example": "628123456789"
+                      },
+                      "recipient": {
+                        "type": "string",
+                        "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$",
+                        "description": "Recipient's Business-Scoped User ID (e.g. `US.13491208655302741918`) or parent BSUID. Alternative to `to`. Auth OTP templates (one-tap / zero-tap / copy-code) do NOT support BSUID recipients — Meta rejects with error 131062.",
+                        "example": "US.13491208655302741918"
                       },
                       "context": {
                         "type": "object",
@@ -3721,7 +3838,6 @@
                     },
                     "required": [
                       "messaging_product",
-                      "to",
                       "type",
                       "interactive"
                     ],
@@ -3818,7 +3934,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -3997,7 +4113,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -4125,7 +4241,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -4267,7 +4383,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -4572,7 +4688,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -4701,7 +4817,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -4801,7 +4917,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -5562,7 +5678,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6172,7 +6288,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6280,7 +6396,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6414,7 +6530,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6479,6 +6595,25 @@
             "name": "phone",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$"
+            },
+            "required": false,
+            "name": "bsuid",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100
+            },
+            "required": false,
+            "name": "username",
+            "in": "query"
+          },
           {
             "schema": {
               "type": "string",
@@ -6549,7 +6684,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6614,6 +6749,15 @@
                   "phone_number": {
                     "type": "string"
                   },
+                  "bsuid": {
+                    "type": "string",
+                    "pattern": "^[A-Z]{2}\\.(ENT\\.)?[A-Za-z0-9]{1,128}$"
+                  },
+                  "username": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
                   "name": {
                     "type": "string",
                     "minLength": 1,
@@ -6631,10 +6775,7 @@
                     "type": "object",
                     "additionalProperties": {}
                   }
-                },
-                "required": [
-                  "phone_number"
-                ]
+                }
               }
             }
           }
@@ -6681,7 +6822,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6789,7 +6930,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -6868,6 +7009,14 @@
                     "minLength": 1,
                     "maxLength": 200
                   },
+                  "username": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
                   "email": {
                     "anyOf": [
                       {
@@ -6940,7 +7089,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7047,7 +7196,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7157,7 +7306,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7284,7 +7433,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7401,7 +7550,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7537,7 +7686,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7663,7 +7812,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -7780,7 +7929,7 @@
             }
           },
           "422": {
-            "description": "Semantic failure (e.g. idempotency key reuse)",
+            "description": "Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)",
             "content": {
               "application/json": {
                 "schema": {
@@ -8380,7 +8529,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8487,7 +8636,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8573,7 +8722,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8706,7 +8855,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8801,7 +8950,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8912,7 +9061,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9033,7 +9182,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9174,7 +9323,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9288,7 +9437,7 @@
             }
           },
           "402": {
-            "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
+            "description": "Billing / entitlement gate — subscription inactive, quota exceeded, or plan tier missing a feature (feature_not_entitled). Upgrade to continue.",
             "content": {
               "application/json": {
                 "schema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirimdev/sdk",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Official TypeScript SDK for the Kirimdev Public API.",
   "type": "module",
   "license": "MIT",