@mjczone/realtime-contract 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MJCZone, Inc.
+
+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/channel.d.ts

@@ -0,0 +1,25 @@
+export type Tier = 'live' | 'replay' | 'presence';
+export interface ParsedChannel {
+    tier: Tier;
+    /** The tenant ID, or `global` for global channels. */
+    tenant: string;
+    topic: string;
+    id?: string;
+    userId?: string;
+}
+export declare const MAX_CHANNEL_LENGTH = 255;
+export declare const RESERVED_TOPICS: readonly ['all', 'grp', 'user', 'run'];
+export declare function isValidTenant(tenant: string): boolean;
+export declare function isValidUserId(userId: string): boolean;
+export declare function tryParseChannel(name: string): ParsedChannel | null;
+export declare function parseChannel(name: string): ParsedChannel;
+export declare function isValidChannel(name: string): boolean;
+export declare const Channels: {
+    global: (topic: string, id?: string, tier?: Tier) => string;
+    tenantAll: (tenant: string, tier?: Tier) => string;
+    record: (tenant: string, topic: string, id?: string, tier?: Tier) => string;
+    group: (tenant: string, group: string, tier?: Tier) => string;
+    user: (tenant: string, userId: string, tier?: Tier) => string;
+    run: (tenant: string, runId: string) => string;
+    presence: (tenant: string, topic: string, id?: string) => string;
+};

package/dist/channel.js

@@ -0,0 +1,99 @@
+export const MAX_CHANNEL_LENGTH = 255;
+export const RESERVED_TOPICS = ['all', 'grp', 'user', 'run'];
+const SEGMENT = /^[A-Za-z0-9_-]+$/;
+const TENANT = /^[A-Za-z0-9_-]{1,64}$/;
+const USER_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const TIERS = ['live', 'replay', 'presence'];
+export function isValidTenant(tenant) {
+    return TENANT.test(tenant) && tenant !== 'global';
+}
+export function isValidUserId(userId) {
+    return USER_ID.test(userId);
+}
+export function tryParseChannel(name) {
+    if (typeof name !== 'string' || name.length > MAX_CHANNEL_LENGTH)
+        return null;
+    const colon = name.indexOf(':');
+    const tier = name.slice(0, colon);
+    if (colon < 0 || !TIERS.includes(tier))
+        return null;
+    const rest = name.slice(colon + 1);
+    if (rest.startsWith('global.')) {
+        if (tier === 'presence')
+            return null;
+        const parts = rest.slice('global.'.length).split('.');
+        if (parts.length > 2 || !parts.every((p) => SEGMENT.test(p)))
+            return null;
+        const [topic, id] = parts;
+        if (RESERVED_TOPICS.includes(topic))
+            return null;
+        return withId({ tier: tier, tenant: 'global', topic }, id);
+    }
+    if (!rest.startsWith('t-'))
+        return null;
+    const dot = rest.indexOf('.');
+    if (dot < 0)
+        return null;
+    const tenant = rest.slice(2, dot);
+    if (!isValidTenant(tenant))
+        return null;
+    const tail = rest.slice(dot + 1);
+    if (tail.startsWith('user#')) {
+        const userId = tail.slice('user#'.length);
+        if (tier === 'presence' || !isValidUserId(userId))
+            return null;
+        return { tier: tier, tenant, topic: 'user', userId };
+    }
+    const parts = tail.split('.');
+    if (parts.length > 2 || !parts.every((p) => SEGMENT.test(p)))
+        return null;
+    const [topic, id] = parts;
+    switch (topic) {
+        case 'all':
+            if (id !== undefined || tier === 'presence')
+                return null;
+            break;
+        case 'grp':
+        case 'run':
+            if (id === undefined)
+                return null;
+            break;
+        case 'user':
+            return null;
+    }
+    return withId({ tier: tier, tenant, topic }, id);
+}
+function withId(c, id) {
+    if (id !== undefined)
+        c.id = id;
+    return c;
+}
+export function parseChannel(name) {
+    const c = tryParseChannel(name);
+    if (!c)
+        throw new Error(`Invalid channel name: ${JSON.stringify(name)}`);
+    return c;
+}
+export function isValidChannel(name) {
+    return tryParseChannel(name) !== null;
+}
+function build(name, want) {
+    const c = parseChannel(name);
+    if (c.tenant !== want.tenant || c.topic !== want.topic || c.id !== want.id || c.userId !== want.userId) {
+        throw new Error(`Invalid channel parts: ${JSON.stringify(want)}`);
+    }
+    return name;
+}
+function suffix(id) {
+    return id === undefined ? '' : `.${id}`;
+}
+export const Channels = {
+    global: (topic, id, tier = 'live') => build(`${tier}:global.${topic}${suffix(id)}`, { tenant: 'global', topic, id }),
+    tenantAll: (tenant, tier = 'live') => build(`${tier}:t-${tenant}.all`, { tenant, topic: 'all' }),
+    record: (tenant, topic, id, tier = 'live') => build(`${tier}:t-${tenant}.${topic}${suffix(id)}`, { tenant, topic, id }),
+    group: (tenant, group, tier = 'live') => build(`${tier}:t-${tenant}.grp.${group}`, { tenant, topic: 'grp', id: group }),
+    user: (tenant, userId, tier = 'live') => build(`${tier}:t-${tenant}.user#${userId}`, { tenant, topic: 'user', userId }),
+    run: (tenant, runId) => build(`replay:t-${tenant}.run.${runId}`, { tenant, topic: 'run', id: runId }),
+    presence: (tenant, topic, id) => build(`presence:t-${tenant}.${topic}${suffix(id)}`, { tenant, topic, id }),
+};
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/envelope.d.ts

@@ -0,0 +1,26 @@
+export interface Envelope<T extends object = Record<string, unknown>> {
+    v: 1;
+    id: string;
+    type: string;
+    tenant: string;
+    source: string;
+    ts: string;
+    corr?: string;
+    data: T;
+}
+export interface EnvelopeInput<T extends object = Record<string, unknown>> {
+    type: string;
+    tenant: string;
+    source: string;
+    corr?: string;
+    data: T;
+}
+export declare const MAX_ENVELOPE_BYTES = 65536;
+export declare const RESERVED_FAMILIES: readonly ['agui', 'job', 'entity', 'notice', 'system'];
+export declare function newId(): string;
+export declare function createEnvelope<T extends object>(input: EnvelopeInput<T>): Envelope<T>;
+/** Returns why the value is not a valid envelope, or null when it is. Unknown fields are ignored. */
+export declare function validateEnvelope(x: unknown): string | null;
+export declare function isEnvelope(x: unknown): x is Envelope;
+/** Size of the serialized envelope in UTF-8 bytes. */
+export declare function envelopeBytes(env: Envelope<object>): number;

package/dist/envelope.js

@@ -0,0 +1,66 @@
+import { monotonicFactory } from 'ulid';
+export const MAX_ENVELOPE_BYTES = 65536;
+export const RESERVED_FAMILIES = ['agui', 'job', 'entity', 'notice', 'system'];
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const TYPE = /^[a-z][a-z0-9]*\.[A-Za-z0-9_.]+$/;
+const TENANT = /^[A-Za-z0-9_-]{1,64}$/;
+const SOURCE = /^[A-Za-z0-9_.-]{1,128}$/;
+const TS = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z$/;
+const nextUlid = monotonicFactory();
+export function newId() {
+    return nextUlid();
+}
+export function createEnvelope(input) {
+    const env = {
+        v: 1,
+        id: newId(),
+        type: input.type,
+        tenant: input.tenant,
+        source: input.source,
+        ts: new Date().toISOString(),
+        data: input.data,
+    };
+    if (input.corr !== undefined)
+        env.corr = input.corr;
+    const problem = validateEnvelope(env);
+    if (problem)
+        throw new Error(`Invalid envelope: ${problem}`);
+    return env;
+}
+function isPlainObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function matches(x, re) {
+    return typeof x === 'string' && re.test(x);
+}
+/** Returns why the value is not a valid envelope, or null when it is. Unknown fields are ignored. */
+export function validateEnvelope(x) {
+    if (!isPlainObject(x))
+        return 'not an object';
+    if (x.v !== 1)
+        return 'v must be 1';
+    if (!matches(x.id, ULID))
+        return 'id must be a ULID';
+    if (!matches(x.type, TYPE) || x.type.length > 128)
+        return 'type must be <family>.<name>';
+    if (!matches(x.tenant, TENANT))
+        return 'tenant is invalid';
+    if (!matches(x.source, SOURCE))
+        return 'source is invalid';
+    if (!matches(x.ts, TS))
+        return 'ts must be RFC 3339 UTC';
+    if (x.corr !== undefined && (typeof x.corr !== 'string' || x.corr.length < 1 || x.corr.length > 256)) {
+        return 'corr must be a string of 1 to 256 characters';
+    }
+    if (!isPlainObject(x.data))
+        return 'data must be an object';
+    return null;
+}
+export function isEnvelope(x) {
+    return validateEnvelope(x) === null;
+}
+/** Size of the serialized envelope in UTF-8 bytes. */
+export function envelopeBytes(env) {
+    return new TextEncoder().encode(JSON.stringify(env)).length;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"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"}

package/dist/guard.d.ts

@@ -0,0 +1,22 @@
+export interface TenantContext {
+    tenant?: string;
+    allowGlobal?: boolean;
+}
+export type GuardReason = 'invalid_channel' | 'global_not_allowed' | 'no_tenant_context' | 'tenant_mismatch' | 'envelope_tenant_mismatch';
+export type GuardResult = {
+    allow: true;
+} | {
+    allow: false;
+    reason: GuardReason;
+};
+export declare class TenantGuardError extends Error {
+    readonly reason: GuardReason;
+    readonly channel: string;
+    constructor(reason: GuardReason, channel: string);
+}
+export declare function checkTenant(context: TenantContext, channel: string, envelope: {
+    tenant: string;
+}): GuardResult;
+export declare function assertTenant(context: TenantContext, channel: string, envelope: {
+    tenant: string;
+}): void;

package/dist/guard.js

@@ -0,0 +1,35 @@
+import { tryParseChannel } from './channel.js';
+export class TenantGuardError extends Error {
+    reason;
+    channel;
+    constructor(reason, channel) {
+        super(`Tenant guard denied publish to ${channel}: ${reason}`);
+        this.reason = reason;
+        this.channel = channel;
+        this.name = 'TenantGuardError';
+    }
+}
+export function checkTenant(context, channel, envelope) {
+    const c = tryParseChannel(channel);
+    if (!c)
+        return { allow: false, reason: 'invalid_channel' };
+    if (c.tenant === 'global') {
+        if (context.allowGlobal !== true)
+            return { allow: false, reason: 'global_not_allowed' };
+    }
+    else {
+        if (!context.tenant)
+            return { allow: false, reason: 'no_tenant_context' };
+        if (context.tenant !== c.tenant)
+            return { allow: false, reason: 'tenant_mismatch' };
+    }
+    if (envelope.tenant !== c.tenant)
+        return { allow: false, reason: 'envelope_tenant_mismatch' };
+    return { allow: true };
+}
+export function assertTenant(context, channel, envelope) {
+    const r = checkTenant(context, channel, envelope);
+    if (!r.allow)
+        throw new TenantGuardError(r.reason, channel);
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAgB/C,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAE9B,MAAM;IACN,OAAO;IAFlB,YACW,MAAmB,EACnB,OAAe;QAExB,KAAK,CAAC,kCAAkC,OAAO,KAAK,MAAM,EAAE,CAAC,CAAC;sBAHrD,MAAM;uBACN,OAAO;QAGhB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,OAAsB,EAAE,OAAe,EAAE,QAA4B;IAC/F,MAAM,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC3D,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QAC1E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAC9F,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB,EAAE,OAAe,EAAE,QAA4B;IAChG,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,CAAC,KAAK;QAAE,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC"}

package/dist/id.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_ENCODED_ID_LENGTH = 128;
+/** Encodes any key as a channel ID: A-Z, a-z, 0-9 and - pass through; every other UTF-8 byte becomes _XX. */
+export declare function encodeId(key: string): string;
+/** The reverse of encodeId. Throws on anything encodeId would not produce. */
+export declare function decodeId(id: string): string;

package/dist/id.js

@@ -0,0 +1,58 @@
+export const MAX_ENCODED_ID_LENGTH = 128;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+function isPlain(byte) {
+    return ((byte >= 0x30 && byte <= 0x39) || // 0-9
+        (byte >= 0x41 && byte <= 0x5a) || // A-Z
+        (byte >= 0x61 && byte <= 0x7a) || // a-z
+        byte === 0x2d // -
+    );
+}
+/** Encodes any key as a channel ID: A-Z, a-z, 0-9 and - pass through; every other UTF-8 byte becomes _XX. */
+export function encodeId(key) {
+    if (typeof key !== 'string' || key === '')
+        throw new Error('encodeId: key must be a non-empty string');
+    if (!key.isWellFormed())
+        throw new Error('encodeId: key is not valid Unicode text');
+    let out = '';
+    for (const b of encoder.encode(key)) {
+        out += isPlain(b) ? String.fromCharCode(b) : `_${b.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    if (out.length > MAX_ENCODED_ID_LENGTH) {
+        throw new Error(`encodeId: encoded ID is ${out.length} characters, over ${MAX_ENCODED_ID_LENGTH}`);
+    }
+    return out;
+}
+/** The reverse of encodeId. Throws on anything encodeId would not produce. */
+export function decodeId(id) {
+    if (typeof id !== 'string' || id === '' || id.length > MAX_ENCODED_ID_LENGTH) {
+        throw new Error('decodeId: not an encoded ID');
+    }
+    const bytes = [];
+    for (let i = 0; i < id.length; i++) {
+        const c = id.charCodeAt(i);
+        if (c === 0x5f) {
+            const hex = id.slice(i + 1, i + 3);
+            if (!/^[0-9A-F]{2}$/.test(hex))
+                throw new Error(`decodeId: bad escape at ${i}`);
+            const b = parseInt(hex, 16);
+            if (isPlain(b))
+                throw new Error(`decodeId: escaped plain character at ${i}`);
+            bytes.push(b);
+            i += 2;
+        }
+        else if (isPlain(c)) {
+            bytes.push(c);
+        }
+        else {
+            throw new Error(`decodeId: unexpected character at ${i}`);
+        }
+    }
+    try {
+        return decoder.decode(new Uint8Array(bytes));
+    }
+    catch {
+        throw new Error('decodeId: not valid UTF-8');
+    }
+}
+//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './channel.js';
+export * from './envelope.js';
+export * from './guard.js';
+export * from './id.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './channel.js';
+export * from './envelope.js';
+export * from './guard.js';
+export * from './id.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@mjczone/realtime-contract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Channel grammar, envelope and tenant guard for the realtime backbone",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjczone/realtime-backbone.git",
+    "directory": "ts/contract"
+  },
+  "homepage": "https://github.com/mjczone/realtime-backbone#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ulid": "3.0.2"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.