@deverjak/tenantkit-plugin-sms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chytré Digital
+
+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/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/** Per-tenant SMS settings (doc 09 §6.5). Provider CREDENTIALS live in the vault, NEVER here (doc 09 §1, §6.5). */
+export declare const SmsSettings: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<{
+        twilio: "twilio";
+        smsbrana: "smsbrana";
+    }>>;
+    senderId: z.ZodString;
+    reminderHours: z.ZodDefault<z.ZodNumber>;
+    events: z.ZodObject<{
+        reminder: z.ZodDefault<z.ZodBoolean>;
+        creditIssued: z.ZodDefault<z.ZodBoolean>;
+        applicationApproved: z.ZodDefault<z.ZodBoolean>;
+        sessionCancelled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    quietHours: z.ZodOptional<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+        tz: z.ZodString;
+    }, z.core.$strip>>;
+    monthlyCapMinor: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SmsSettingsValues = z.infer<typeof SmsSettings>;
+declare const _default: import("@deverjak/tenantkit-kernel").Plugin;
+export default _default;
+export { type SmsProvider } from './src/port';

package/dist/index.js

@@ -0,0 +1,94 @@
+/**
+ * Realizes docs/09-plugins-and-subscriptions.md §6 + docs/02-reservation-core.md §12 — the SMS plugin.
+ *
+ * `plugin:sms` is `pro`-tier. It sends transactional SMS for the same events the email layer handles but over a
+ * different channel, behind a PROVIDER PORT so the concrete gateway (Twilio, SMSbrana) is swappable. It touches
+ * the system only through the five seams (doc 09 §1): its own `sms.*` schema, namespaced routes, the event
+ * subscriptions below, UI slots (none here), and a Zod settings schema. It NEVER alters core/public tables.
+ *
+ * Build order: ships AFTER `payments` (doc 09 §9) since it depends on the scheduler + `notification_preferences`.
+ */
+import { definePlugin } from '@deverjak/tenantkit-kernel';
+import { z } from 'zod';
+import { StubSmsProvider } from './src/port';
+/** Per-tenant SMS settings (doc 09 §6.5). Provider CREDENTIALS live in the vault, NEVER here (doc 09 §1, §6.5). */
+export const SmsSettings = z.object({
+    provider: z.enum(['twilio', 'smsbrana']).default('smsbrana'),
+    senderId: z.string().max(11), // alphanumeric sender, where the provider allows
+    reminderHours: z.number().int().default(24),
+    events: z.object({
+        reminder: z.boolean().default(true),
+        creditIssued: z.boolean().default(false),
+        applicationApproved: z.boolean().default(true),
+        sessionCancelled: z.boolean().default(true),
+    }),
+    quietHours: z.object({ start: z.string(), end: z.string(), tz: z.string() }).optional(),
+    monthlyCapMinor: z.number().int().optional(),
+});
+/** The bundled template pack seeded on enable (doc 09 §2.3, §6.4): one row per (key, locale). */
+const TEMPLATE_PACK = [
+    { key: 'session_reminder', locale: 'cs', body: 'Připomínka: lekce {{course}} zítra v {{time}}.' },
+    { key: 'session_reminder', locale: 'en', body: 'Reminder: {{course}} lesson tomorrow at {{time}}.' },
+    { key: 'credit_issued', locale: 'cs', body: 'Máte novou omluvenku, platí do {{expiresAt}}.' },
+    { key: 'credit_issued', locale: 'en', body: 'You have a new makeup credit, valid until {{expiresAt}}.' },
+];
+/** Resolve the configured provider adapter from settings (doc 09 §6.1). Real adapters read creds from the vault. */
+function selectProvider(settings) {
+    switch (settings.provider) {
+        // case 'twilio':   return new TwilioProvider(...)
+        // case 'smsbrana': return new SmsbranaProvider(...)
+        default:
+            return new StubSmsProvider(); // mockup default — logs instead of dialing a gateway
+    }
+}
+export default definePlugin({
+    id: 'sms',
+    name: { cs: 'SMS notifikace', en: 'SMS notifications' },
+    requiresTier: 'pro', // entitlement gate (doc 09 §3.2) — `plugin:sms` is pro-only
+    dbSchema: 'sms', // owns the sms.* schema; migrations ship with this package (doc 09 §1)
+    settingsSchema: SmsSettings,
+    /**
+     * Idempotent provisioning (doc 09 §2.3): seed default `sms.templates` so a freshly enabled tenant already has
+     * Czech + English reminder copy. PORTS REFACTOR (docs/14): the lifecycle ctx is vendor-neutral — `ctx.db` is a
+     * `ScopedDb` fenced to the plugin's OWN `sms.*` schema (doc 09 §7), not a Supabase client. Portable code calls
+     * a SECURITY DEFINER RPC; the on-conflict upsert lives inside `sms.seed_templates`, so enabling twice is a no-op.
+     */
+    async onEnable(ctx) {
+        await ctx.db.rpc('seed_templates', { tenant_id: ctx.tenantId, templates: TEMPLATE_PACK });
+    },
+    /**
+     * Event subscriptions (doc 09 §6.2). Each handler reads core data read-only and writes only `sms.*` (a queued
+     * `sms.messages` row the dispatcher later hands to the provider). Consent / quiet-hours / cost accounting
+     * (doc 09 §6.3) are applied by the sender before the actual `provider.send`.
+     */
+    events: {
+        /** N hours before a lesson — "Připomínka: lekce zítra v 17:00…" (doc 09 §6.2). */
+        'session.reminder_due': async (event) => {
+            await queueFromEvent(event, 'session_reminder');
+        },
+        /** On excuse → credit — "Máte novou omluvenku, platí do …" (doc 09 §5.1, §6.2; opt-in default off). */
+        'credit.issued': async (event) => {
+            await queueFromEvent(event, 'credit_issued');
+        },
+    },
+    // routes: mounted under /api/plugins/sms/* (e.g. a test-send + a costs report). Each is auto-wrapped with
+    // assertPluginEnabled (doc 09 §4) so an un-entitled tenant never reaches plugin code.
+    routes: {
+        'test-send': {
+            POST: async () => Response.json({ ok: true, note: 'mockup: would enqueue a test SMS via the configured provider' }),
+        },
+    },
+});
+/**
+ * Shared queue step: turn a core event into a queued `sms.messages` row (status='queued'). This is where a real
+ * impl resolves recipients + locale (guardian profile → tenant default, doc 09 §6.4), checks opt-in + quiet
+ * hours, renders the `{{var}}` template, and lets the dispatcher call `selectProvider(settings).send(...)`.
+ * Sketched as a structural stub so the subscription shape is concrete without wiring the dispatcher here.
+ */
+async function queueFromEvent(_event, _templateKey) {
+    // await admin.from('messages').insert({ tenant_id, to_phone, template, locale, body, status: 'queued' })
+    // void selectProvider(settings)  // chosen at send time from per-tenant settings
+    void selectProvider;
+    return;
+}
+export {} from './src/port';

package/dist/src/port.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Realizes docs/09-plugins-and-subscriptions.md §6.1 — the SMS provider PORT (infrastructure boundary, doc 01 §3).
+ *
+ * The application layer depends on `SmsProvider`, never on Twilio/SMSbrana directly — so a tenant on SMSbrana
+ * and a tenant on Twilio run identical code (the same lesson the four Supabase factories teach: parameterize the
+ * vendor). Concrete adapters (TwilioProvider, SmsbranaProvider) implement this and are selected by
+ * `settings.provider`; their credentials come from the vault (doc 09 §6.5), never from `plugin_settings`.
+ */
+/** E.164 phone string, e.g. '+420777123456'. Branded loosely; validated at the edge. */
+export type E164 = string;
+export interface SmsProvider {
+    /** Send one message. Returns the provider reference + (optional) cost in minor units for cost accounting. */
+    send(msg: {
+        to: E164;
+        body: string;
+        senderId?: string;
+    }): Promise<{
+        ref: string;
+        costMinor?: number;
+    }>;
+    name: 'twilio' | 'smsbrana';
+}
+/**
+ * A stub provider for the mockup / local / tests: it never dials a gateway, it just logs and returns a fake ref.
+ * Real deployments register `TwilioProvider` / `SmsbranaProvider` instead (selected in index.ts `selectProvider`).
+ */
+export declare class StubSmsProvider implements SmsProvider {
+    readonly name = "smsbrana";
+    send(msg: {
+        to: E164;
+        body: string;
+        senderId?: string;
+    }): Promise<{
+        ref: string;
+        costMinor?: number;
+    }>;
+}

package/dist/src/port.js

@@ -0,0 +1,19 @@
+/**
+ * Realizes docs/09-plugins-and-subscriptions.md §6.1 — the SMS provider PORT (infrastructure boundary, doc 01 §3).
+ *
+ * The application layer depends on `SmsProvider`, never on Twilio/SMSbrana directly — so a tenant on SMSbrana
+ * and a tenant on Twilio run identical code (the same lesson the four Supabase factories teach: parameterize the
+ * vendor). Concrete adapters (TwilioProvider, SmsbranaProvider) implement this and are selected by
+ * `settings.provider`; their credentials come from the vault (doc 09 §6.5), never from `plugin_settings`.
+ */
+/**
+ * A stub provider for the mockup / local / tests: it never dials a gateway, it just logs and returns a fake ref.
+ * Real deployments register `TwilioProvider` / `SmsbranaProvider` instead (selected in index.ts `selectProvider`).
+ */
+export class StubSmsProvider {
+    name = 'smsbrana';
+    async send(msg) {
+        // console.debug('[sms:stub] →', msg.to, msg.body)  — wired to the app logger in a real build (doc 01 §9)
+        return { ref: `stub-${Date.now()}`, costMinor: 0 };
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@deverjak/tenantkit-plugin-sms",
+  "version": "0.1.0",
+  "description": "Reference SMS plugin for tenantkit, behind a swappable SmsProvider port (Twilio / SMSbrana). requiresTier: 'pro'. Touches the system only through the five plugin seams.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@deverjak/tenantkit-kernel": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}