@valuya/channel-access-core 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,8 @@
+# @valuya/channel-access-core
+
+Shared contracts and runtime helpers for channel-access packages such as:
+
+- `@valuya/whatsapp-channel-access`
+- `@valuya/telegram-channel-access`
+
+This package is intentionally channel-agnostic. Channel-specific resource building, linking, and access resolution stay in the transport packages.

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+export type LogFn = (event: string, fields: Record<string, unknown>) => void;
+export type ChannelAccessState = "paid_active" | "trial_active" | "expired_payment_required" | "inactive";
+export type ChannelMode = {
+    kind: "human";
+} | {
+    kind: "agent";
+    soulId: string;
+};
+export type SoulConfig = {
+    id: number | string;
+    slug: string;
+    name: string;
+    version: number | string;
+    capabilities?: Record<string, unknown> | null;
+    tool_policy?: Record<string, unknown> | null;
+    memory_policy?: Record<string, unknown> | null;
+    compiled_prompt_artifacts?: Record<string, unknown> | null;
+};
+export type ChannelRuntimeConfig = {
+    mode: "human" | "agent";
+    channel: string;
+    channel_kind: string;
+    provider: string | null;
+    channel_app_id?: string | null;
+    visit_url: string | null;
+    human_routing?: Record<string, unknown> | null;
+    agent_routing?: Record<string, unknown> | null;
+    fallback?: {
+        allowed: boolean;
+        mode: "human";
+    } | null;
+    soul: SoulConfig | null;
+};
+export type ChannelAccessResolveRequest = {
+    resource: string;
+    plan: string;
+    channel?: {
+        kind?: string | null;
+        provider?: string | null;
+        channel_identifier?: string | null;
+        phone_number?: string | null;
+        bot_name?: string | null;
+        chat_id?: string | null;
+    } | null;
+};
+export type ChannelAccessResolveResponse = {
+    ok: boolean;
+    state: ChannelAccessState;
+    resource: string;
+    anchor_resource: string;
+    plan: string;
+    expires_at: string | null;
+    payment_url: string | null;
+    reason: string | null;
+    runtime_config: ChannelRuntimeConfig | null;
+    capabilities: {
+        channel_access_version: string;
+        [key: string]: unknown;
+    };
+};
+export type LegacyEntitlementResponse = {
+    active?: boolean;
+    reason?: string;
+    evaluated_plan?: string;
+    expires_at?: string | null;
+    payment_url?: string | null;
+    state?: string;
+    required?: Record<string, unknown> | null;
+};
+export type SoulDefinition = {
+    id: string;
+    name: string;
+    systemPrompt: string;
+    locale?: string;
+    memoryPolicy?: {
+        keepRecentTurns: number;
+        summarizeAfterTurns: number;
+    };
+    tools?: string[];
+};
+export type SoulMemoryTurn = {
+    role: "user" | "assistant";
+    content: string;
+    createdAt: string;
+};
+export type SoulMemory = {
+    recentTurns: SoulMemoryTurn[];
+    summaries: string[];
+    userProfile?: Record<string, unknown>;
+    updatedAt: string;
+};
+export type SoulResponse = {
+    reply: string;
+    memory?: SoulMemory;
+    metadata?: Record<string, unknown>;
+};
+export interface MemoryStore {
+    load(args: {
+        userId: string;
+        soulId: string;
+    }): Promise<SoulMemory>;
+    save(args: {
+        userId: string;
+        soulId: string;
+        memory: SoulMemory;
+    }): Promise<void>;
+}
+export interface SoulRuntime {
+    run(args: {
+        soul: SoulDefinition;
+        message: string;
+        memory: SoulMemory;
+        protocolSubjectHeader: string;
+        locale?: string;
+    }): Promise<SoulResponse>;
+}
+export interface GuardToolClient {
+    getChannelAccessState(args: {
+        protocolSubjectHeader: string;
+        resource: string;
+        plan: string;
+    }): Promise<Record<string, unknown>>;
+    getEntitlements(args: {
+        protocolSubjectHeader: string;
+        resource: string;
+        plan: string;
+    }): Promise<Record<string, unknown>>;
+    getRecentOrders?(args: {
+        protocolSubjectHeader: string;
+    }): Promise<Record<string, unknown>>;
+    getRecentPayments?(args: {
+        protocolSubjectHeader: string;
+    }): Promise<Record<string, unknown>>;
+}
+export declare class InMemoryMemoryStore implements MemoryStore {
+    private readonly store;
+    load(args: {
+        userId: string;
+        soulId: string;
+    }): Promise<SoulMemory>;
+    save(args: {
+        userId: string;
+        soulId: string;
+        memory: SoulMemory;
+    }): Promise<void>;
+}
+export declare class OpenAISoulRuntimeAdapter implements SoulRuntime {
+    private readonly args;
+    constructor(args: {
+        runCompletion: (args: {
+            system: string;
+            user: string;
+            locale?: string;
+            soul: SoulDefinition;
+        }) => Promise<SoulResponse>;
+    });
+    run(args: {
+        soul: SoulDefinition;
+        message: string;
+        memory: SoulMemory;
+        protocolSubjectHeader: string;
+        locale?: string;
+    }): Promise<SoulResponse>;
+}
+export declare class StaticSoulRuntime implements SoulRuntime {
+    private readonly reply;
+    constructor(reply: string);
+    run(): Promise<SoulResponse>;
+}
+export declare function createGuardReadTools(client: GuardToolClient): {
+    getChannelAccessState(args: {
+        protocolSubjectHeader: string;
+        resource: string;
+        plan: string;
+    }): Promise<Record<string, unknown>>;
+    getEntitlements(args: {
+        protocolSubjectHeader: string;
+        resource: string;
+        plan: string;
+    }): Promise<Record<string, unknown>>;
+    getRecentOrders(args: {
+        protocolSubjectHeader: string;
+    }): Promise<{}>;
+    getRecentPayments(args: {
+        protocolSubjectHeader: string;
+    }): Promise<{}>;
+};
+export declare function appendMemory(memory: SoulMemory, userMessage: string, assistantReply: string): SoulMemory;
+export declare function buildAllowedAccessReply(args: {
+    visitUrl?: string | null;
+    state: "paid_active" | "trial_active";
+    expiresAt?: string;
+    language?: "de" | "en";
+}): string;
+export declare function buildRuntimeErrorReply(error: "runtime_missing" | "agent_misconfigured", language?: "de" | "en"): string;

package/dist/index.js

@@ -0,0 +1,108 @@
+export class InMemoryMemoryStore {
+    store = new Map();
+    async load(args) {
+        return this.store.get(memoryKey(args.userId, args.soulId)) || emptyMemory();
+    }
+    async save(args) {
+        this.store.set(memoryKey(args.userId, args.soulId), args.memory);
+    }
+}
+export class OpenAISoulRuntimeAdapter {
+    args;
+    constructor(args) {
+        this.args = args;
+    }
+    async run(args) {
+        const memorySummary = args.memory.summaries.join("\n") || "(no summary)";
+        const recentTurns = args.memory.recentTurns.map((turn) => `${turn.role}: ${turn.content}`).join("\n") || "(no history)";
+        return this.args.runCompletion({
+            system: args.soul.systemPrompt,
+            user: [
+                `Protocol subject: ${args.protocolSubjectHeader}`,
+                `Memory summary:\n${memorySummary}`,
+                `Recent turns:\n${recentTurns}`,
+                `Current message:\n${args.message}`,
+            ].join("\n\n"),
+            locale: args.locale,
+            soul: args.soul,
+        });
+    }
+}
+export class StaticSoulRuntime {
+    reply;
+    constructor(reply) {
+        this.reply = reply;
+    }
+    async run() {
+        return { reply: this.reply };
+    }
+}
+export function createGuardReadTools(client) {
+    return {
+        async getChannelAccessState(args) {
+            return client.getChannelAccessState(args);
+        },
+        async getEntitlements(args) {
+            return client.getEntitlements(args);
+        },
+        async getRecentOrders(args) {
+            return client.getRecentOrders?.(args) || {};
+        },
+        async getRecentPayments(args) {
+            return client.getRecentPayments?.(args) || {};
+        },
+    };
+}
+export function appendMemory(memory, userMessage, assistantReply) {
+    const nextTurns = [
+        ...memory.recentTurns,
+        { role: "user", content: userMessage, createdAt: new Date().toISOString() },
+        { role: "assistant", content: assistantReply, createdAt: new Date().toISOString() },
+    ].slice(-12);
+    return {
+        ...memory,
+        recentTurns: nextTurns,
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function buildAllowedAccessReply(args) {
+    const language = args.language || "en";
+    if (language === "de") {
+        return [
+            args.state === "trial_active"
+                ? "Dein Zugang ist aktiv. Dein kostenloser Zugang laeuft aktuell."
+                : "Dein Zugang ist aktiv.",
+            args.expiresAt ? `Gueltig bis: ${args.expiresAt}.` : null,
+            args.visitUrl ? `Direktlink: ${args.visitUrl}` : null,
+        ].filter(Boolean).join("\n");
+    }
+    return [
+        args.state === "trial_active"
+            ? "Your access is active. Your free access is currently running."
+            : "Your access is active.",
+        args.expiresAt ? `Valid until: ${args.expiresAt}.` : null,
+        args.visitUrl ? `Direct link: ${args.visitUrl}` : null,
+    ].filter(Boolean).join("\n");
+}
+export function buildRuntimeErrorReply(error, language = "en") {
+    if (language === "de") {
+        if (error === "agent_misconfigured") {
+            return "Dein Zugang ist aktiv, aber der Agent ist gerade nicht korrekt konfiguriert. Bitte spaeter erneut versuchen.";
+        }
+        return "Dein Zugang ist aktiv, aber fuer diesen Kanal ist noch keine Laufzeit konfiguriert.";
+    }
+    if (error === "agent_misconfigured") {
+        return "Your access is active, but the agent is currently misconfigured. Please try again later.";
+    }
+    return "Your access is active, but no runtime is configured for this channel yet.";
+}
+function memoryKey(userId, soulId) {
+    return `${userId}::${soulId}`;
+}
+function emptyMemory() {
+    return {
+        recentTurns: [],
+        summaries: [],
+        updatedAt: new Date(0).toISOString(),
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@valuya/channel-access-core",
+  "version": "0.2.0-beta.1",
+  "description": "Shared channel-access contracts and runtime helpers for Valuya Guard channel packages",
+  "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"
+  }
+}