@valuya/whatsapp-channel-access 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valuya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @valuya/whatsapp-channel-access
+
+Reusable entitlement check for paid WhatsApp channel access backed by Valuya Guard.
+
+## What it does
+
+- Resolves whether a WhatsApp user is linked to a Guard subject
+- Calls `GET /api/v2/entitlements` with the canonical `X-Valuya-Subject-Id` header
+- Returns a small access decision object for bot handlers
+- Optionally includes a WhatsApp channel invite URL when access is active
+
+## Install
+
+```bash
+pnpm add @valuya/whatsapp-channel-access
+```
+
+## Usage
+
+```ts
+import { WhatsAppChannelAccessService } from "@valuya/whatsapp-channel-access"
+
+const access = new WhatsAppChannelAccessService({
+  baseUrl: process.env.VALUYA_BASE_URL!,
+  tenantToken: process.env.VALUYA_TENANT_TOKEN!,
+  channelResource: "whatsapp:channel:meta:premium_alpha:49123456789",
+  channelPlan: "standard",
+  channelVisitUrl: "https://chat.whatsapp.com/InviteCode",
+  linking: {
+    async ensureLinkedForPaymentAction({ whatsappUserId }) {
+      const protocolSubjectHeader = await lookupLinkedSubjectHeader(whatsappUserId)
+      if (!protocolSubjectHeader) {
+        return {
+          allowed: false,
+          code: "not_linked",
+          reply: "Account link required before channel access can be checked.",
+        }
+      }
+
+      return {
+        allowed: true,
+        link: {
+          valuya_protocol_subject_header: protocolSubjectHeader,
+        },
+      }
+    },
+  },
+})
+
+const result = await access.resolveAccess({
+  whatsappUserId: "49123456789",
+  whatsappProfileName: "Ada",
+})
+```
+
+## Result shape
+
+Allowed:
+
+```ts
+{
+  allowed: true,
+  reason: "entitled",
+  protocolSubjectHeader: "user:17",
+  resource: "whatsapp:channel:meta:premium_alpha:49123456789",
+  plan: "standard",
+  channelUrl: "https://chat.whatsapp.com/InviteCode"
+}
+```
+
+Denied:
+
+```ts
+{
+  allowed: false,
+  reason: "not_linked" | "inactive" | "guard_unavailable",
+  protocolSubjectHeader: string | null,
+  resource: string,
+  plan: string,
+  reply: string
+}
+```
+
+## Notes
+
+- Requires Node.js with built-in `fetch` support
+- Publish target in this repo is the public npm registry under the `next` dist-tag

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+export type WhatsAppChannelAccessConfig = {
+    baseUrl: string;
+    tenantToken: string;
+    channelResource?: string;
+    channelProvider?: string;
+    channelIdentifier?: string;
+    channelPhoneNumber?: string;
+    channelPlan?: string;
+    channelVisitUrl?: string;
+    linking: WhatsAppLinkResolver;
+    logger?: (event: string, fields: Record<string, unknown>) => void;
+};
+export type WhatsAppLinkResolver = {
+    ensureLinkedForPaymentAction(args: {
+        whatsappUserId: string;
+        whatsappProfileName?: string;
+    }): Promise<{
+        allowed: true;
+        link: {
+            valuya_protocol_subject_header?: string;
+        };
+    } | {
+        allowed: false;
+        code: string;
+        reply: string;
+    }>;
+};
+export type WhatsAppChannelAccessResult = {
+    allowed: true;
+    reason: "entitled";
+    protocolSubjectHeader: string;
+    resource: string;
+    plan: string;
+    channelUrl: string | null;
+} | {
+    allowed: false;
+    reason: "not_linked" | "inactive" | "guard_unavailable";
+    protocolSubjectHeader: string | null;
+    resource: string;
+    plan: string;
+    reply: string;
+};
+export declare class WhatsAppChannelAccessService {
+    private readonly baseUrl;
+    private readonly tenantToken;
+    private readonly resource;
+    private readonly plan;
+    private readonly visitUrl;
+    private readonly linking;
+    private readonly log;
+    constructor(config: WhatsAppChannelAccessConfig);
+    resolveAccess(args: {
+        whatsappUserId: string;
+        whatsappProfileName?: string;
+    }): Promise<WhatsAppChannelAccessResult>;
+    private fetchEntitlement;
+}
+export declare function buildWhatsAppChannelResource(args: {
+    resource?: string;
+    provider?: string;
+    channelIdentifier?: string;
+    phoneNumber?: string;
+}): string;

package/dist/index.js

@@ -0,0 +1,184 @@
+export class WhatsAppChannelAccessService {
+    baseUrl;
+    tenantToken;
+    resource;
+    plan;
+    visitUrl;
+    linking;
+    log;
+    constructor(config) {
+        this.baseUrl = String(config.baseUrl || "").trim().replace(/\/+$/, "");
+        this.tenantToken = String(config.tenantToken || "").trim();
+        this.resource = buildWhatsAppChannelResource({
+            resource: config.channelResource,
+            provider: config.channelProvider,
+            channelIdentifier: config.channelIdentifier,
+            phoneNumber: config.channelPhoneNumber,
+        });
+        this.plan = String(config.channelPlan || "standard").trim() || "standard";
+        this.visitUrl = cleanOptional(config.channelVisitUrl) || null;
+        this.linking = config.linking;
+        this.log =
+            config.logger ||
+                ((event, fields) => {
+                    console.log(JSON.stringify({ level: "info", event, ...fields }));
+                });
+        if (!this.baseUrl)
+            throw new Error("whatsapp_channel_base_url_required");
+        if (!this.tenantToken)
+            throw new Error("whatsapp_channel_tenant_token_required");
+    }
+    async resolveAccess(args) {
+        const whatsappUserId = String(args.whatsappUserId || "").trim();
+        this.log("whatsapp_channel_access_request", {
+            tenant: tokenPreview(this.tenantToken),
+            whatsapp_user_id: whatsappUserId,
+            resource: this.resource,
+            plan: this.plan,
+        });
+        const linked = await this.linking.ensureLinkedForPaymentAction({
+            whatsappUserId,
+            whatsappProfileName: args.whatsappProfileName,
+        });
+        if (!linked.allowed) {
+            const reason = linked.code === "not_linked" ? "not_linked" : "guard_unavailable";
+            this.log("whatsapp_channel_access_result", {
+                tenant: tokenPreview(this.tenantToken),
+                whatsapp_user_id: whatsappUserId,
+                protocol_subject_header: null,
+                resource: this.resource,
+                plan: this.plan,
+                allowed: false,
+                reason,
+            });
+            return {
+                allowed: false,
+                reason,
+                protocolSubjectHeader: null,
+                resource: this.resource,
+                plan: this.plan,
+                reply: linked.reply,
+            };
+        }
+        const protocolSubjectHeader = String(linked.link.valuya_protocol_subject_header || "").trim();
+        if (!protocolSubjectHeader) {
+            const reply = "Linked protocol subject is missing. Please restart onboarding.";
+            this.log("whatsapp_channel_access_result", {
+                tenant: tokenPreview(this.tenantToken),
+                whatsapp_user_id: whatsappUserId,
+                protocol_subject_header: null,
+                resource: this.resource,
+                plan: this.plan,
+                allowed: false,
+                reason: "guard_unavailable",
+            });
+            return {
+                allowed: false,
+                reason: "guard_unavailable",
+                protocolSubjectHeader: null,
+                resource: this.resource,
+                plan: this.plan,
+                reply,
+            };
+        }
+        const entitlement = await this.fetchEntitlement(protocolSubjectHeader);
+        if (entitlement.active !== true) {
+            this.log("whatsapp_channel_access_result", {
+                tenant: tokenPreview(this.tenantToken),
+                whatsapp_user_id: whatsappUserId,
+                protocol_subject_header: protocolSubjectHeader,
+                resource: this.resource,
+                plan: this.plan,
+                allowed: false,
+                reason: "inactive",
+            });
+            return {
+                allowed: false,
+                reason: "inactive",
+                protocolSubjectHeader,
+                resource: this.resource,
+                plan: this.plan,
+                reply: "Channel access is locked. Payment/plan activation is required.",
+            };
+        }
+        this.log("whatsapp_channel_access_result", {
+            tenant: tokenPreview(this.tenantToken),
+            whatsapp_user_id: whatsappUserId,
+            protocol_subject_header: protocolSubjectHeader,
+            resource: this.resource,
+            plan: this.plan,
+            allowed: true,
+            reason: "entitled",
+        });
+        if (this.visitUrl) {
+            this.log("whatsapp_channel_link_sent", {
+                tenant: tokenPreview(this.tenantToken),
+                whatsapp_user_id: whatsappUserId,
+                protocol_subject_header: protocolSubjectHeader,
+                resource: this.resource,
+                plan: this.plan,
+                channel_url: this.visitUrl,
+            });
+        }
+        return {
+            allowed: true,
+            reason: "entitled",
+            protocolSubjectHeader,
+            resource: this.resource,
+            plan: this.plan,
+            channelUrl: this.visitUrl,
+        };
+    }
+    async fetchEntitlement(protocolSubjectHeader) {
+        const url = new URL(`${this.baseUrl}/api/v2/entitlements`);
+        url.searchParams.set("resource", this.resource);
+        url.searchParams.set("plan", this.plan);
+        const response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.tenantToken}`,
+                Accept: "application/json",
+                "X-Valuya-Subject-Id": protocolSubjectHeader,
+            },
+        });
+        const body = await safeParseJson(response);
+        if (!response.ok) {
+            throw new Error(`whatsapp_channel_entitlement_failed:${response.status}:${JSON.stringify(body).slice(0, 300)}`);
+        }
+        return (body && typeof body === "object" ? body : {});
+    }
+}
+export function buildWhatsAppChannelResource(args) {
+    const explicit = cleanOptional(args.resource);
+    if (explicit)
+        return explicit;
+    const provider = cleanOptional(args.provider);
+    const channelIdentifier = cleanOptional(args.channelIdentifier);
+    const phone = cleanOptional(args.phoneNumber);
+    if (!provider || !channelIdentifier || !phone) {
+        throw new Error("whatsapp_channel_resource_config_missing");
+    }
+    return `whatsapp:channel:${provider}:${channelIdentifier}:${normalizePhone(phone)}`;
+}
+function normalizePhone(input) {
+    return String(input || "").trim().replace(/^\+/, "").replace(/\s+/g, "");
+}
+async function safeParseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function cleanOptional(value) {
+    const v = String(value || "").trim();
+    return v || undefined;
+}
+function tokenPreview(token) {
+    const t = String(token || "").trim();
+    return t ? t.slice(0, 12) : "unknown";
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@valuya/whatsapp-channel-access",
+  "version": "0.2.0-beta.1",
+  "description": "Reusable WhatsApp paid-channel entitlement checks for Valuya Guard bots",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test dist/*.test.js"
+  }
+}