@fonoster/sipnet 0.39.0 → 0.42.0

package/dist/numbers/buildService.d.ts

@@ -19,13 +19,16 @@
 import { NumberPreconditionsCheck } from "@fonoster/common";
 import { ClientOptions } from "../types";
 import { NumberRouting } from "./engineRouting";
+import { SipEndpoint } from "./linkWhatsApp";
 /**
- * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `twilioLink`
- * is the install's PSTN root and public signaling addresses, for LinkTwilio.
+ * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `carrierLinks`
+ * is what the carrier links read from the install: its PSTN root, its public signaling addresses
+ * (LinkTwilio) and its public SIP endpoints (LinkWhatsApp takes the TLS one).
  */
-declare function buildService(clientOptions: ClientOptions, checkNumberPreconditions: NumberPreconditionsCheck, routing?: NumberRouting, twilioLink?: {
+declare function buildService(clientOptions: ClientOptions, checkNumberPreconditions: NumberPreconditionsCheck, routing?: NumberRouting, carrierLinks?: {
     pstnRoot: string;
     signalingAddresses: string[];
+    sipEndpoints?: SipEndpoint[];
 }): {
     definition: {
         serviceName: string;
@@ -52,6 +55,9 @@ declare function buildService(clientOptions: ClientOptions, checkNumberPrecondit
         linkTwilio: (call: {
             request: unknown;
         }, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
+        linkWhatsApp: (call: {
+            request: unknown;
+        }, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
     };
 };
 export { buildService };

package/dist/numbers/buildService.js

@@ -1,4 +1,15 @@
 "use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,17 +20,21 @@ const checkRefs_1 = require("../resources/checkRefs");
 const createNumber_1 = require("./createNumber");
 const getNumber_1 = require("./getNumber");
 const linkTwilio_1 = require("./linkTwilio");
+const linkWhatsApp_1 = require("./linkWhatsApp");
 const listNumbers_1 = require("./listNumbers");
 const operations_1 = require("./operations");
 const updateNumber_1 = require("./updateNumber");
 /**
- * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `twilioLink`
- * is the install's PSTN root and public signaling addresses, for LinkTwilio.
+ * `routing` picks the peer app-linked numbers point at (default: the roomr peer). `carrierLinks`
+ * is what the carrier links read from the install: its PSTN root, its public signaling addresses
+ * (LinkTwilio) and its public SIP endpoints (LinkWhatsApp takes the TLS one).
  */
-function buildService(clientOptions, checkNumberPreconditions, routing, twilioLink = {
+function buildService(clientOptions, checkNumberPreconditions, routing, carrierLinks = {
     pstnRoot: "",
-    signalingAddresses: []
+    signalingAddresses: [],
+    sipEndpoints: []
 }) {
+    const { sipEndpoints = [] } = carrierLinks, twilioLink = __rest(carrierLinks, ["sipEndpoints"]);
     const client = new sdk_1.default.Numbers(clientOptions);
     const checkRefs = (0, checkRefs_1.createCheckRefs)((0, checkRefs_1.createRefLookups)(clientOptions));
     return {
@@ -37,7 +52,17 @@ function buildService(clientOptions, checkNumberPreconditions, routing, twilioLi
             deleteNumber: (0, operations_1.deleteNumber)(client),
             linkTwilio: (0, linkTwilio_1.linkTwilio)(Object.assign({ numbers: client, trunks: new sdk_1.default.Trunks(clientOptions), credentials: new sdk_1.default.Credentials(clientOptions), checkNumberPreconditions,
                 routing,
-                checkRefs }, twilioLink))
+                checkRefs }, twilioLink)),
+            linkWhatsApp: (0, linkWhatsApp_1.linkWhatsApp)({
+                numbers: client,
+                trunks: new sdk_1.default.Trunks(clientOptions),
+                credentials: new sdk_1.default.Credentials(clientOptions),
+                checkNumberPreconditions,
+                routing,
+                checkRefs,
+                pstnRoot: twilioLink.pstnRoot,
+                sipEndpoints
+            })
         }
     };
 }

package/dist/numbers/linkShared.d.ts

@@ -0,0 +1,12 @@
+import { ListRequest, ListResponse } from "@fonoster/types";
+/** A 24-character SIP password with at least one upper, one lower and one digit. */
+declare function generatePassword(): string;
+type Listed = {
+    extended?: Record<string, unknown>;
+};
+type Lister<T> = (request: ListRequest) => Promise<ListResponse<T>>;
+/** The caller's first resource that matches. */
+declare function findOwned<T extends Listed>(list: Lister<T>, accessKeyId: string, match: (item: T) => boolean): Promise<T | undefined>;
+/** The first resource of any workspace that matches (Routr lists every workspace's items). */
+declare function findAny<T extends Listed>(list: Lister<T>, match: (item: T) => boolean): Promise<T | undefined>;
+export { findAny, findOwned, generatePassword };

package/dist/numbers/linkShared.js

@@ -0,0 +1,75 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAny = findAny;
+exports.findOwned = findOwned;
+exports.generatePassword = generatePassword;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const node_crypto_1 = require("node:crypto");
+const paginationUtils_1 = require("../resources/paginationUtils");
+const PAGE_SIZE = 100;
+const PASSWORD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** A 24-character SIP password with at least one upper, one lower and one digit. */
+function generatePassword() {
+    for (;;) {
+        const password = Array.from({ length: 24 }, () => PASSWORD_ALPHABET[(0, node_crypto_1.randomInt)(PASSWORD_ALPHABET.length)]).join("");
+        if (/[A-Z]/.test(password) &&
+            /[a-z]/.test(password) &&
+            /\d/.test(password)) {
+            return password;
+        }
+    }
+}
+/** The first item that matches, through every page Routr has, with or without a workspace filter. */
+function findWhere(list, match, accessKeyId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let pageToken;
+        for (;;) {
+            const { items = [], nextPageToken } = yield list({
+                pageSize: PAGE_SIZE,
+                pageToken
+            });
+            const candidates = accessKeyId
+                ? (0, paginationUtils_1.filterByAccessKeyId)(items, accessKeyId)
+                : items;
+            const found = candidates.find(match);
+            if (found || !nextPageToken || items.length < PAGE_SIZE) {
+                return found;
+            }
+            pageToken = nextPageToken;
+        }
+    });
+}
+/** The caller's first resource that matches. */
+function findOwned(list, accessKeyId, match) {
+    return findWhere(list, match, accessKeyId);
+}
+/** The first resource of any workspace that matches (Routr lists every workspace's items). */
+function findAny(list, match) {
+    return findWhere(list, match);
+}

package/dist/numbers/linkTwilio.js

@@ -39,47 +39,18 @@ const types_1 = require("@fonoster/types");
 const grpc_js_1 = require("@grpc/grpc-js");
 const phone_1 = require("phone");
 const checkRefs_1 = require("../resources/checkRefs");
-const paginationUtils_1 = require("../resources/paginationUtils");
 const operations_1 = require("../trunks/operations");
 const convertToRoutrNumber_1 = require("./convertToRoutrNumber");
+const linkShared_1 = require("./linkShared");
 const twilioLinkErrorToGrpc_1 = require("./twilioLinkErrorToGrpc");
 const logger = (0, logger_1.getLogger)({ service: "sipnet", filePath: __filename });
 const TWILIO_PSTN_URI_BASE = "pstn.twilio.com";
-const PAGE_SIZE = 100;
-const PASSWORD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 const isIpv4Entry = (address) => {
     const [ip, prefix, ...rest] = address.split("/");
     return (rest.length === 0 &&
         node_net_1.default.isIPv4(ip) &&
         (prefix === undefined || (/^\d{1,2}$/.test(prefix) && +prefix <= 32)));
 };
-function generatePassword() {
-    for (;;) {
-        const password = Array.from({ length: 24 }, () => PASSWORD_ALPHABET[(0, node_crypto_1.randomInt)(PASSWORD_ALPHABET.length)]).join("");
-        if (/[A-Z]/.test(password) &&
-            /[a-z]/.test(password) &&
-            /\d/.test(password)) {
-            return password;
-        }
-    }
-}
-// The caller's first resource that matches, through every page Routr has.
-function findOwned(list, accessKeyId, match) {
-    return __awaiter(this, void 0, void 0, function* () {
-        let pageToken;
-        for (;;) {
-            const { items = [], nextPageToken } = yield list({
-                pageSize: PAGE_SIZE,
-                pageToken
-            });
-            const found = (0, paginationUtils_1.filterByAccessKeyId)(items, accessKeyId).find(match);
-            if (found || !nextPageToken || items.length < PAGE_SIZE) {
-                return found;
-            }
-            pageToken = nextPageToken;
-        }
-    });
-}
 function linkTwilio(deps) {
     const { numbers, trunks, credentials, checkNumberPreconditions, routing, checkRefs, pstnRoot, twilio = {
         provisionTwilioTrunk: common_1.provisionTwilioTrunk,
@@ -129,7 +100,7 @@ function linkTwilio(deps) {
         }
         const sipCredential = {
             username: `fonoster-${(0, node_crypto_1.randomBytes)(4).toString("hex")}`,
-            password: generatePassword()
+            password: (0, linkShared_1.generatePassword)()
         };
         let twilioTrunkSid;
         try {
@@ -146,7 +117,7 @@ function linkTwilio(deps) {
             return;
         }
         const { ref: credentialsRef } = yield credentials.createCredentials(Object.assign(Object.assign({ name: `Twilio ${label}` }, sipCredential), { extended: { accessKeyId } }));
-        const trunk = yield findOwned((r) => trunks.listTrunks(r), accessKeyId, (t) => t.inboundUri === inboundUri);
+        const trunk = yield (0, linkShared_1.findOwned)((r) => trunks.listTrunks(r), accessKeyId, (t) => t.inboundUri === inboundUri);
         let trunkRef;
         if (trunk) {
             yield trunks.updateTrunk((0, operations_1.mergeTrunkUpdate)({ ref: trunk.ref, outboundCredentialsRef: credentialsRef }, trunk));
@@ -171,7 +142,7 @@ function linkTwilio(deps) {
                 extended: { accessKeyId }
             }));
         }
-        const number = yield findOwned((r) => numbers.listNumbers(r), accessKeyId, (n) => n.telUrl === telUrl);
+        const number = yield (0, linkShared_1.findOwned)((r) => numbers.listNumbers(r), accessKeyId, (n) => n.telUrl === telUrl);
         const appPeerAor = routing && appRef ? yield routing.aorFor({ appRef, telUrl }) : undefined;
         let ref;
         if (number) {

package/dist/numbers/linkWhatsApp.d.ts

@@ -0,0 +1,40 @@
+import { enableWhatsAppSipCalling, GrpcErrorMessage, inspectWhatsAppNumber, NumberPreconditionsCheck } from "@fonoster/common";
+import { CredentialsApi, NumbersApi, TrunkApi } from "@fonoster/types";
+import { CheckRefs } from "../resources/checkRefs";
+import { NumberRouting } from "./engineRouting";
+/** A public SIP endpoint of the install, as `regions.public[].endpoints.sip` declares it. */
+type SipEndpoint = {
+    host: string;
+    port: number;
+    transport: string;
+};
+type WhatsAppLink = {
+    inspectWhatsAppNumber: typeof inspectWhatsAppNumber;
+    enableWhatsAppSipCalling: typeof enableWhatsAppSipCalling;
+};
+type LinkWhatsAppDeps = {
+    numbers: NumbersApi;
+    trunks: TrunkApi;
+    credentials: CredentialsApi;
+    checkNumberPreconditions: NumberPreconditionsCheck;
+    routing?: NumberRouting;
+    checkRefs?: CheckRefs;
+    /** Where carriers reach this install's trunks (`pstn.<domain>`). */
+    pstnRoot: string;
+    /** The install's public SIP endpoints; the TLS one is what the org registers in Meta. */
+    sipEndpoints: SipEndpoint[];
+    whatsapp?: WhatsAppLink;
+};
+/**
+ * Links a WhatsApp Business number: one credential, one TLS trunk to Meta and the Number, all per
+ * number, since Meta issues one SIP password per number and a Routr trunk holds one outbound
+ * credential. With an access token, Fonoster reads the number from Meta, turns on SIP calling
+ * pointed at this install with SDES and keeps the password Meta issues; the token is used for
+ * those calls only. Without one, Fonoster calls no Meta API: the response carries the hostname
+ * the org registers in WhatsApp Manager, and the Meta-issued password arrives as `sipPassword`,
+ * now or on a later call.
+ */
+declare function linkWhatsApp(deps: LinkWhatsAppDeps): (call: {
+    request: unknown;
+}, callback: (error?: import("@fonoster/common").GrpcErrorMessage, response?: unknown) => void) => Promise<void>;
+export { linkWhatsApp, LinkWhatsAppDeps, SipEndpoint, WhatsAppLink };

package/dist/numbers/linkWhatsApp.js

@@ -0,0 +1,257 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkWhatsApp = linkWhatsApp;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const node_net_1 = __importDefault(require("node:net"));
+const common_1 = require("@fonoster/common");
+const logger_1 = require("@fonoster/logger");
+const types_1 = require("@fonoster/types");
+const grpc_js_1 = require("@grpc/grpc-js");
+const phone_1 = require("phone");
+const checkRefs_1 = require("../resources/checkRefs");
+const operations_1 = require("../trunks/operations");
+const convertToRoutrNumber_1 = require("./convertToRoutrNumber");
+const linkShared_1 = require("./linkShared");
+const whatsAppLinkErrorToGrpc_1 = require("./whatsAppLinkErrorToGrpc");
+const logger = (0, logger_1.getLogger)({ service: "sipnet", filePath: __filename });
+/** Meta's SIP edge for WhatsApp Business Calling. */
+const META_SIP_HOST = "wa.meta.vc";
+const META_SIP_PORT = 5061;
+/** Routr's media relay negotiates SRTP with SDES toward trunks over TLS (routr-rtprelay.yaml). */
+const SRTP_KEY_EXCHANGE = "SDES";
+const isTlsHostname = (endpoint) => { var _a; return ((_a = endpoint.transport) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === "tls" && node_net_1.default.isIP(endpoint.host) === 0; };
+/**
+ * Links a WhatsApp Business number: one credential, one TLS trunk to Meta and the Number, all per
+ * number, since Meta issues one SIP password per number and a Routr trunk holds one outbound
+ * credential. With an access token, Fonoster reads the number from Meta, turns on SIP calling
+ * pointed at this install with SDES and keeps the password Meta issues; the token is used for
+ * those calls only. Without one, Fonoster calls no Meta API: the response carries the hostname
+ * the org registers in WhatsApp Manager, and the Meta-issued password arrives as `sipPassword`,
+ * now or on a later call.
+ */
+function linkWhatsApp(deps) {
+    const { numbers, trunks, credentials, checkNumberPreconditions, routing, checkRefs, pstnRoot, sipEndpoints, whatsapp = { inspectWhatsAppNumber: common_1.inspectWhatsAppNumber, enableWhatsAppSipCalling: common_1.enableWhatsAppSipCalling } } = deps;
+    const fn = (call, callback) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const { request } = call;
+        const { appRef, agentAor } = request;
+        const meta = request.accessToken && request.phoneNumberId
+            ? {
+                credentials: { accessToken: request.accessToken },
+                phoneNumberId: request.phoneNumberId.trim()
+            }
+            : undefined;
+        const accessKeyId = (0, common_1.getAccessKeyIdFromCall)(call);
+        const label = accessKeyId.toLowerCase();
+        // Never the request itself: it may carry the SIP password or the access token.
+        logger.verbose("call to linkWhatsApp", {
+            phoneNumber: request.phoneNumber,
+            phoneNumberId: meta === null || meta === void 0 ? void 0 : meta.phoneNumberId,
+            label
+        });
+        try {
+            // Validates that the appRef exists in the caller's workspace (RV-B4)
+            yield checkNumberPreconditions({ appRef, accessKeyId });
+        }
+        catch (e) {
+            // The contract reports an app outside the workspace as NOT_FOUND, with the usual message.
+            if (e instanceof common_1.GrpcError && e.code === grpc_js_1.status.INVALID_ARGUMENT) {
+                callback({ code: grpc_js_1.status.NOT_FOUND, message: e.message });
+                return;
+            }
+            throw e;
+        }
+        yield (checkRefs === null || checkRefs === void 0 ? void 0 : checkRefs(accessKeyId, (0, checkRefs_1.numberRefs)(request)));
+        const tlsEndpoint = sipEndpoints.find(isTlsHostname);
+        if (!tlsEndpoint) {
+            callback({
+                code: grpc_js_1.status.FAILED_PRECONDITION,
+                message: "This install has no public SIP over TLS address for WhatsApp to send calls to"
+            });
+            return;
+        }
+        // With a token, Meta's record of the number is the number: it's what Meta will send.
+        let phoneNumber = request.phoneNumber;
+        let verifiedName = "";
+        if (meta) {
+            try {
+                const info = yield whatsapp.inspectWhatsAppNumber(meta.credentials, {
+                    phoneNumberId: meta.phoneNumberId
+                });
+                phoneNumber = info.phoneNumber;
+                verifiedName = (_a = info.verifiedName) !== null && _a !== void 0 ? _a : "";
+            }
+            catch (e) {
+                callback((0, whatsAppLinkErrorToGrpc_1.whatsAppLinkErrorToGrpc)(e, {
+                    phoneNumberId: meta.phoneNumberId,
+                    hostname: ""
+                }));
+                return;
+            }
+        }
+        const digits = phoneNumber.replace(/^\+/, "");
+        const inboundUri = `wa-${label}-${digits}.${pstnRoot}`;
+        const telUrl = `tel:${phoneNumber}`;
+        // Routr lists every workspace's items: a host or number another workspace owns stops the link
+        // before any write, in Meta or Routr (Routr's inbound_uri and tel_url are unique).
+        const foreignTrunk = yield (0, linkShared_1.findAny)((r) => trunks.listTrunks(r), (t) => t.inboundUri === inboundUri);
+        if (foreignTrunk && ((_b = foreignTrunk.extended) === null || _b === void 0 ? void 0 : _b.accessKeyId) !== accessKeyId) {
+            callback({
+                code: grpc_js_1.status.FAILED_PRECONDITION,
+                message: `${inboundUri} is already in use`
+            });
+            return;
+        }
+        const foreignNumber = yield (0, linkShared_1.findAny)((r) => numbers.listNumbers(r), (n) => n.telUrl === telUrl);
+        if (foreignNumber && ((_c = foreignNumber.extended) === null || _c === void 0 ? void 0 : _c.accessKeyId) !== accessKeyId) {
+            callback({
+                code: grpc_js_1.status.FAILED_PRECONDITION,
+                message: `${phoneNumber} is already linked in another workspace`
+            });
+            return;
+        }
+        // Meta first: if it refuses, nothing in Routr has changed. A trunk pointed at by Meta that
+        // Routr then fails to create is fixed by linking again.
+        let sipPassword = request.sipPassword;
+        if (meta) {
+            try {
+                ({ sipPassword } = yield whatsapp.enableWhatsAppSipCalling(meta.credentials, {
+                    phoneNumberId: meta.phoneNumberId,
+                    sipServer: { hostname: inboundUri, port: tlsEndpoint.port },
+                    srtpKeyExchange: SRTP_KEY_EXCHANGE
+                }));
+            }
+            catch (e) {
+                callback((0, whatsAppLinkErrorToGrpc_1.whatsAppLinkErrorToGrpc)(e, {
+                    phoneNumberId: meta.phoneNumberId,
+                    hostname: inboundUri
+                }));
+                return;
+            }
+        }
+        const trunk = foreignTrunk;
+        const credentialName = `WhatsApp ${phoneNumber}`;
+        // The credential: the trunk's, updated in place, or a new one
+        let credentialsRef;
+        let sipPasswordSet;
+        if (trunk === null || trunk === void 0 ? void 0 : trunk.outboundCredentialsRef) {
+            credentialsRef = trunk.outboundCredentialsRef;
+            const current = yield credentials.getCredentials(credentialsRef);
+            const update = {
+                ref: credentialsRef,
+                name: credentialName,
+                username: digits,
+                extended: Object.assign(Object.assign(Object.assign({}, ((_d = current.extended) !== null && _d !== void 0 ? _d : {})), { accessKeyId }), (sipPassword ? { sipPasswordSet: true } : {}))
+            };
+            if (sipPassword)
+                update.password = sipPassword;
+            yield credentials.updateCredentials(update);
+            sipPasswordSet =
+                Boolean(sipPassword) || ((_e = current.extended) === null || _e === void 0 ? void 0 : _e.sipPasswordSet) === true;
+        }
+        else {
+            ({ ref: credentialsRef } = yield credentials.createCredentials({
+                name: credentialName,
+                username: digits,
+                password: sipPassword !== null && sipPassword !== void 0 ? sipPassword : (0, linkShared_1.generatePassword)(),
+                extended: Object.assign({ accessKeyId }, (sipPassword ? { sipPasswordSet: true } : {}))
+            }));
+            sipPasswordSet = Boolean(sipPassword);
+        }
+        const routrTrunkFields = {
+            normalizeToE164: true,
+            rewriteFromWithNumber: true,
+            fromDomain: inboundUri
+        };
+        let trunkRef;
+        if (trunk) {
+            yield trunks.updateTrunk(Object.assign(Object.assign(Object.assign({}, (0, operations_1.mergeTrunkUpdate)({ ref: trunk.ref, outboundCredentialsRef: credentialsRef }, trunk)), { inboundCredentialsRef: credentialsRef }), routrTrunkFields));
+            trunkRef = trunk.ref;
+        }
+        else {
+            ({ ref: trunkRef } = yield trunks.createTrunk(Object.assign(Object.assign({ name: `WhatsApp Trunk ${phoneNumber}`, inboundUri, sendRegister: false, inboundCredentialsRef: credentialsRef, outboundCredentialsRef: credentialsRef, uris: [
+                    {
+                        host: META_SIP_HOST,
+                        port: META_SIP_PORT,
+                        transport: types_1.Transport.TLS,
+                        user: digits,
+                        enabled: true,
+                        weight: 10,
+                        priority: 10
+                    }
+                ] }, routrTrunkFields), { extended: { accessKeyId } })));
+        }
+        const number = yield (0, linkShared_1.findOwned)((r) => numbers.listNumbers(r), accessKeyId, (n) => n.telUrl === telUrl);
+        const appPeerAor = routing && appRef ? yield routing.aorFor({ appRef, telUrl }) : undefined;
+        let ref;
+        if (number) {
+            yield numbers.updateNumber((0, convertToRoutrNumber_1.convertToRoutrNumberUpdate)({
+                ref: number.ref,
+                name: request.name || number.name,
+                trunkRef,
+                appRef,
+                agentAor
+            }, appPeerAor));
+            ref = number.ref;
+        }
+        else {
+            const { countryIso2, countryIso3 } = (0, phone_1.phone)(phoneNumber);
+            ({ ref } = yield numbers.createNumber((0, convertToRoutrNumber_1.convertToRoutrNumber)({
+                name: request.name || verifiedName || phoneNumber,
+                telUrl,
+                city: "unknown",
+                country: countryIso3,
+                countryIsoCode: countryIso2,
+                trunkRef,
+                appRef,
+                agentAor
+            }, accessKeyId, appPeerAor)));
+        }
+        logger.verbose("linked the WhatsApp number", {
+            phoneNumber,
+            label,
+            sipPasswordSet,
+            metaConfigured: Boolean(meta)
+        });
+        callback(null, {
+            ref,
+            trunkRef,
+            sipServerHostname: inboundUri,
+            sipServerPort: tlsEndpoint.port,
+            sipPasswordSet,
+            phoneNumber,
+            verifiedName,
+            metaConfigured: Boolean(meta)
+        });
+    });
+    return (0, common_1.withErrorHandlingAndValidation)(fn, common_1.Validators.linkWhatsAppRequestSchema);
+}

package/dist/numbers/whatsAppLinkErrorToGrpc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { GrpcErrorMessage } from "@fonoster/common";
+/**
+ * The gRPC error for a failed Meta call. Clients place errors by these messages, so they are part
+ * of the contract. Meta's own text never reaches the caller except for the tier check, and
+ * anything unrecognized is reported as Meta being unavailable.
+ */
+declare function whatsAppLinkErrorToGrpc(error: unknown, context: {
+    phoneNumberId: string;
+    hostname: string;
+}): GrpcErrorMessage;
+export { whatsAppLinkErrorToGrpc };

package/dist/numbers/whatsAppLinkErrorToGrpc.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whatsAppLinkErrorToGrpc = whatsAppLinkErrorToGrpc;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const common_1 = require("@fonoster/common");
+const grpc_js_1 = require("@grpc/grpc-js");
+const UNAVAILABLE = {
+    code: grpc_js_1.status.UNAVAILABLE,
+    message: "Meta is unavailable; try again"
+};
+/**
+ * The gRPC error for a failed Meta call. Clients place errors by these messages, so they are part
+ * of the contract. Meta's own text never reaches the caller except for the tier check, and
+ * anything unrecognized is reported as Meta being unavailable.
+ */
+function whatsAppLinkErrorToGrpc(error, context) {
+    if (!(error instanceof common_1.WhatsAppLinkError)) {
+        return UNAVAILABLE;
+    }
+    const failedPrecondition = (message) => ({
+        code: grpc_js_1.status.FAILED_PRECONDITION,
+        message
+    });
+    switch (error.reason) {
+        case "INVALID_CREDENTIALS":
+            return { code: grpc_js_1.status.INVALID_ARGUMENT, message: error.message };
+        case "TOKEN_REFUSED":
+            return failedPrecondition("Meta didn't accept this access token");
+        case "PERMISSION_MISSING":
+            return failedPrecondition("This access token can't manage WhatsApp calling settings; use a System User token with whatsapp_business_management");
+        case "NUMBER_NOT_FOUND":
+            return failedPrecondition(`No WhatsApp number with id ${context.phoneNumberId} is reachable with this access token`);
+        case "TIER_TOO_LOW":
+            return failedPrecondition(error.message);
+        case "SIP_SERVER_REJECTED":
+            return failedPrecondition(`Meta didn't accept ${context.hostname} as the SIP server`);
+        default:
+            return UNAVAILABLE;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/sipnet",
-  "version": "0.39.0",
+  "version": "0.42.0",
   "description": "Routr-based SIP stack",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -19,11 +19,12 @@
     "fonoster": "./dist/index.js"
   },
   "dependencies": {
-    "@fonoster/common": "^0.39.0",
-    "@fonoster/identity": "^0.39.0",
-    "@fonoster/logger": "^0.39.0",
-    "@fonoster/types": "^0.39.0",
+    "@fonoster/common": "^0.42.0",
+    "@fonoster/identity": "^0.42.0",
+    "@fonoster/logger": "^0.42.0",
+    "@fonoster/types": "^0.42.0",
     "@grpc/grpc-js": "~1.14.6",
+    "@routr/common": "2.24.0",
     "@routr/sdk": "2.24.0",
     "phone": "^3.1.72",
     "zod": "^3.23.8"
@@ -41,5 +42,5 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "gitHead": "f5dbb1ff7c54e949ed66743d68f3faf4971a8b2a"
+  "gitHead": "672b9fbf92428854e9d4d94d0e40a3f830efd925"
 }