@portalshq/channel-registry 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @portalshq/channel-registry
+
+Loads, validates, PX-refreshes, and atomically persists a deployment-local channel registry.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+declare const channel: z.ZodObject<{
+    controlEndpoint: z.ZodString;
+    queueTokenEnv: z.ZodString;
+    requiredEntities: z.ZodArray<z.ZodString>;
+    youtube: z.ZodOptional<z.ZodObject<{
+        liveChatId: z.ZodString;
+        clientIdEnv: z.ZodString;
+        clientSecretEnv: z.ZodString;
+        refreshTokenEnv: z.ZodString;
+    }, z.core.$strip>>;
+    twitch: z.ZodOptional<z.ZodObject<{
+        broadcasterUserId: z.ZodString;
+        userId: z.ZodString;
+        clientIdEnv: z.ZodString;
+        clientSecretEnv: z.ZodString;
+        refreshTokenEnv: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const registrySchema: z.ZodObject<{
+    channels: z.ZodRecord<z.ZodString, z.ZodObject<{
+        controlEndpoint: z.ZodString;
+        queueTokenEnv: z.ZodString;
+        requiredEntities: z.ZodArray<z.ZodString>;
+        youtube: z.ZodOptional<z.ZodObject<{
+            liveChatId: z.ZodString;
+            clientIdEnv: z.ZodString;
+            clientSecretEnv: z.ZodString;
+            refreshTokenEnv: z.ZodString;
+        }, z.core.$strip>>;
+        twitch: z.ZodOptional<z.ZodObject<{
+            broadcasterUserId: z.ZodString;
+            userId: z.ZodString;
+            clientIdEnv: z.ZodString;
+            clientSecretEnv: z.ZodString;
+            refreshTokenEnv: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    entities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>>>;
+    entitiesFetchedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Channel = z.infer<typeof channel>;
+export type EntityManifest = {
+    id: string;
+} & Record<string, unknown>;
+export type RegistryData = z.infer<typeof registrySchema>;
+export type ChannelRegistry = {
+    get(channelId: string): Channel;
+    manifests(channelId: string): readonly EntityManifest[];
+    refresh(): Promise<void>;
+};
+export declare function openChannelRegistry(options: {
+    filePath: string;
+    resolveManifests(uris: readonly string[]): Promise<readonly EntityManifest[]>;
+}): ChannelRegistry;
+export {};

package/dist/index.js

@@ -0,0 +1,51 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+const secretRef = z.string().regex(/^[A-Z][A-Z0-9_]*$/);
+const entityUri = z.string().regex(/^px:\/\/[\w.-]+\/[\w.-]+\/[\w.-]+$/);
+const channel = z.object({
+    controlEndpoint: z.string().url(),
+    queueTokenEnv: secretRef,
+    requiredEntities: z.array(entityUri).min(1),
+    youtube: z.object({ liveChatId: z.string().min(1), clientIdEnv: secretRef, clientSecretEnv: secretRef, refreshTokenEnv: secretRef }).optional(),
+    twitch: z.object({ broadcasterUserId: z.string().min(1), userId: z.string().min(1), clientIdEnv: secretRef, clientSecretEnv: secretRef, refreshTokenEnv: secretRef }).optional(),
+});
+const registrySchema = z.object({
+    channels: z.record(z.string().regex(/^[\w.-]+$/), channel),
+    entities: z.record(entityUri, z.object({ id: entityUri }).passthrough()).default({}),
+    entitiesFetchedAt: z.string().datetime().optional(),
+});
+export function openChannelRegistry(options) {
+    let current;
+    function requireCurrent() {
+        if (!current)
+            throw new Error("Channel registry has not been refreshed.");
+        return current;
+    }
+    return {
+        get(channelId) {
+            const value = requireCurrent().channels[channelId];
+            if (!value)
+                throw new Error(`Unknown channel: ${channelId}`);
+            return value;
+        },
+        manifests(channelId) {
+            const registry = requireCurrent();
+            return this.get(channelId).requiredEntities.map((uri) => registry.entities[uri]).filter((entity) => Boolean(entity));
+        },
+        async refresh() {
+            const filePath = path.resolve(options.filePath);
+            const parsed = registrySchema.parse(JSON.parse(await readFile(filePath, "utf8")));
+            const uris = [...new Set(Object.values(parsed.channels).flatMap((value) => value.requiredEntities))];
+            const manifests = await options.resolveManifests(uris);
+            if (manifests.length !== uris.length)
+                throw new Error("Every required PX entity must resolve before the registry can refresh.");
+            const entities = Object.fromEntries(manifests.map((manifest) => [manifest.id, manifest]));
+            const refreshed = { ...parsed, entities, entitiesFetchedAt: new Date().toISOString() };
+            const temporary = `${filePath}.${process.pid}.tmp`;
+            await writeFile(temporary, `${JSON.stringify(refreshed, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+            await rename(temporary, filePath);
+            current = refreshed;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@portalshq/channel-registry",
+  "version": "0.1.0",
+  "repository": { "type": "git", "url": "git+https://github.com/portalshq/portals-cloud.git", "directory": "packages/channel-registry" },
+  "description": "Validated, PX-refreshed deployment-local channel registries.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "rm -rf dist && tsc -p tsconfig.json", "typecheck": "tsc -p tsconfig.json --noEmit", "test": "vitest run", "prepack": "npm run build" },
+  "dependencies": { "zod": "^4.3.6" },
+  "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.6.3", "vitest": "^3.2.7" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}